1*572c4311Sfengbojiang<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2*572c4311Sfengbojiang<html> 3*572c4311Sfengbojiang 4*572c4311Sfengbojiang<head> 5*572c4311Sfengbojiang<title>Lua 5.1 Reference Manual</title> 6*572c4311Sfengbojiang<link rel="stylesheet" type="text/css" href="lua.css"> 7*572c4311Sfengbojiang<link rel="stylesheet" type="text/css" href="manual.css"> 8*572c4311Sfengbojiang<META HTTP-EQUIV="content-type" CONTENT="text/html; charset=iso-8859-1"> 9*572c4311Sfengbojiang</head> 10*572c4311Sfengbojiang 11*572c4311Sfengbojiang<body> 12*572c4311Sfengbojiang 13*572c4311Sfengbojiang<hr> 14*572c4311Sfengbojiang<h1> 15*572c4311Sfengbojiang<a href="http://www.lua.org/"><img src="logo.gif" alt="" border="0"></a> 16*572c4311SfengbojiangLua 5.1 Reference Manual 17*572c4311Sfengbojiang</h1> 18*572c4311Sfengbojiang 19*572c4311Sfengbojiangby Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes 20*572c4311Sfengbojiang<p> 21*572c4311Sfengbojiang<small> 22*572c4311SfengbojiangCopyright © 2006–2012 Lua.org, PUC-Rio. 23*572c4311SfengbojiangFreely available under the terms of the 24*572c4311Sfengbojiang<a href="http://www.lua.org/license.html">Lua license</a>. 25*572c4311Sfengbojiang</small> 26*572c4311Sfengbojiang<hr> 27*572c4311Sfengbojiang<p> 28*572c4311Sfengbojiang 29*572c4311Sfengbojiang<a href="contents.html#contents">contents</A> 30*572c4311Sfengbojiang· 31*572c4311Sfengbojiang<a href="contents.html#index">index</A> 32*572c4311Sfengbojiang· 33*572c4311Sfengbojiang<A HREF="http://www.lua.org/manual/">other versions</A> 34*572c4311Sfengbojiang 35*572c4311Sfengbojiang<!-- ====================================================================== --> 36*572c4311Sfengbojiang<p> 37*572c4311Sfengbojiang 38*572c4311Sfengbojiang<!-- $Id: manual.of,v 1.49.1.2 2012/01/13 20:23:26 roberto Exp $ --> 39*572c4311Sfengbojiang 40*572c4311Sfengbojiang 41*572c4311Sfengbojiang 42*572c4311Sfengbojiang 43*572c4311Sfengbojiang<h1>1 - <a name="1">Introduction</a></h1> 44*572c4311Sfengbojiang 45*572c4311Sfengbojiang<p> 46*572c4311SfengbojiangLua is an extension programming language designed to support 47*572c4311Sfengbojianggeneral procedural programming with data description 48*572c4311Sfengbojiangfacilities. 49*572c4311SfengbojiangIt also offers good support for object-oriented programming, 50*572c4311Sfengbojiangfunctional programming, and data-driven programming. 51*572c4311SfengbojiangLua is intended to be used as a powerful, light-weight 52*572c4311Sfengbojiangscripting language for any program that needs one. 53*572c4311SfengbojiangLua is implemented as a library, written in <em>clean</em> C 54*572c4311Sfengbojiang(that is, in the common subset of ANSI C and C++). 55*572c4311Sfengbojiang 56*572c4311Sfengbojiang 57*572c4311Sfengbojiang<p> 58*572c4311SfengbojiangBeing an extension language, Lua has no notion of a "main" program: 59*572c4311Sfengbojiangit only works <em>embedded</em> in a host client, 60*572c4311Sfengbojiangcalled the <em>embedding program</em> or simply the <em>host</em>. 61*572c4311SfengbojiangThis host program can invoke functions to execute a piece of Lua code, 62*572c4311Sfengbojiangcan write and read Lua variables, 63*572c4311Sfengbojiangand can register C functions to be called by Lua code. 64*572c4311SfengbojiangThrough the use of C functions, Lua can be augmented to cope with 65*572c4311Sfengbojianga wide range of different domains, 66*572c4311Sfengbojiangthus creating customized programming languages sharing a syntactical framework. 67*572c4311SfengbojiangThe Lua distribution includes a sample host program called <code>lua</code>, 68*572c4311Sfengbojiangwhich uses the Lua library to offer a complete, stand-alone Lua interpreter. 69*572c4311Sfengbojiang 70*572c4311Sfengbojiang 71*572c4311Sfengbojiang<p> 72*572c4311SfengbojiangLua is free software, 73*572c4311Sfengbojiangand is provided as usual with no guarantees, 74*572c4311Sfengbojiangas stated in its license. 75*572c4311SfengbojiangThe implementation described in this manual is available 76*572c4311Sfengbojiangat Lua's official web site, <code>www.lua.org</code>. 77*572c4311Sfengbojiang 78*572c4311Sfengbojiang 79*572c4311Sfengbojiang<p> 80*572c4311SfengbojiangLike any other reference manual, 81*572c4311Sfengbojiangthis document is dry in places. 82*572c4311SfengbojiangFor a discussion of the decisions behind the design of Lua, 83*572c4311Sfengbojiangsee the technical papers available at Lua's web site. 84*572c4311SfengbojiangFor a detailed introduction to programming in Lua, 85*572c4311Sfengbojiangsee Roberto's book, <em>Programming in Lua (Second Edition)</em>. 86*572c4311Sfengbojiang 87*572c4311Sfengbojiang 88*572c4311Sfengbojiang 89*572c4311Sfengbojiang<h1>2 - <a name="2">The Language</a></h1> 90*572c4311Sfengbojiang 91*572c4311Sfengbojiang<p> 92*572c4311SfengbojiangThis section describes the lexis, the syntax, and the semantics of Lua. 93*572c4311SfengbojiangIn other words, 94*572c4311Sfengbojiangthis section describes 95*572c4311Sfengbojiangwhich tokens are valid, 96*572c4311Sfengbojianghow they can be combined, 97*572c4311Sfengbojiangand what their combinations mean. 98*572c4311Sfengbojiang 99*572c4311Sfengbojiang 100*572c4311Sfengbojiang<p> 101*572c4311SfengbojiangThe language constructs will be explained using the usual extended BNF notation, 102*572c4311Sfengbojiangin which 103*572c4311Sfengbojiang{<em>a</em>} means 0 or more <em>a</em>'s, and 104*572c4311Sfengbojiang[<em>a</em>] means an optional <em>a</em>. 105*572c4311SfengbojiangNon-terminals are shown like non-terminal, 106*572c4311Sfengbojiangkeywords are shown like <b>kword</b>, 107*572c4311Sfengbojiangand other terminal symbols are shown like `<b>=</b>´. 108*572c4311SfengbojiangThe complete syntax of Lua can be found in <a href="#8">§8</a> 109*572c4311Sfengbojiangat the end of this manual. 110*572c4311Sfengbojiang 111*572c4311Sfengbojiang 112*572c4311Sfengbojiang 113*572c4311Sfengbojiang<h2>2.1 - <a name="2.1">Lexical Conventions</a></h2> 114*572c4311Sfengbojiang 115*572c4311Sfengbojiang<p> 116*572c4311Sfengbojiang<em>Names</em> 117*572c4311Sfengbojiang(also called <em>identifiers</em>) 118*572c4311Sfengbojiangin Lua can be any string of letters, 119*572c4311Sfengbojiangdigits, and underscores, 120*572c4311Sfengbojiangnot beginning with a digit. 121*572c4311SfengbojiangThis coincides with the definition of names in most languages. 122*572c4311Sfengbojiang(The definition of letter depends on the current locale: 123*572c4311Sfengbojiangany character considered alphabetic by the current locale 124*572c4311Sfengbojiangcan be used in an identifier.) 125*572c4311SfengbojiangIdentifiers are used to name variables and table fields. 126*572c4311Sfengbojiang 127*572c4311Sfengbojiang 128*572c4311Sfengbojiang<p> 129*572c4311SfengbojiangThe following <em>keywords</em> are reserved 130*572c4311Sfengbojiangand cannot be used as names: 131*572c4311Sfengbojiang 132*572c4311Sfengbojiang 133*572c4311Sfengbojiang<pre> 134*572c4311Sfengbojiang and break do else elseif 135*572c4311Sfengbojiang end false for function if 136*572c4311Sfengbojiang in local nil not or 137*572c4311Sfengbojiang repeat return then true until while 138*572c4311Sfengbojiang</pre> 139*572c4311Sfengbojiang 140*572c4311Sfengbojiang<p> 141*572c4311SfengbojiangLua is a case-sensitive language: 142*572c4311Sfengbojiang<code>and</code> is a reserved word, but <code>And</code> and <code>AND</code> 143*572c4311Sfengbojiangare two different, valid names. 144*572c4311SfengbojiangAs a convention, names starting with an underscore followed by 145*572c4311Sfengbojianguppercase letters (such as <a href="#pdf-_VERSION"><code>_VERSION</code></a>) 146*572c4311Sfengbojiangare reserved for internal global variables used by Lua. 147*572c4311Sfengbojiang 148*572c4311Sfengbojiang 149*572c4311Sfengbojiang<p> 150*572c4311SfengbojiangThe following strings denote other tokens: 151*572c4311Sfengbojiang 152*572c4311Sfengbojiang<pre> 153*572c4311Sfengbojiang + - * / % ^ # 154*572c4311Sfengbojiang == ~= <= >= < > = 155*572c4311Sfengbojiang ( ) { } [ ] 156*572c4311Sfengbojiang ; : , . .. ... 157*572c4311Sfengbojiang</pre> 158*572c4311Sfengbojiang 159*572c4311Sfengbojiang<p> 160*572c4311Sfengbojiang<em>Literal strings</em> 161*572c4311Sfengbojiangcan be delimited by matching single or double quotes, 162*572c4311Sfengbojiangand can contain the following C-like escape sequences: 163*572c4311Sfengbojiang'<code>\a</code>' (bell), 164*572c4311Sfengbojiang'<code>\b</code>' (backspace), 165*572c4311Sfengbojiang'<code>\f</code>' (form feed), 166*572c4311Sfengbojiang'<code>\n</code>' (newline), 167*572c4311Sfengbojiang'<code>\r</code>' (carriage return), 168*572c4311Sfengbojiang'<code>\t</code>' (horizontal tab), 169*572c4311Sfengbojiang'<code>\v</code>' (vertical tab), 170*572c4311Sfengbojiang'<code>\\</code>' (backslash), 171*572c4311Sfengbojiang'<code>\"</code>' (quotation mark [double quote]), 172*572c4311Sfengbojiangand '<code>\'</code>' (apostrophe [single quote]). 173*572c4311SfengbojiangMoreover, a backslash followed by a real newline 174*572c4311Sfengbojiangresults in a newline in the string. 175*572c4311SfengbojiangA character in a string can also be specified by its numerical value 176*572c4311Sfengbojiangusing the escape sequence <code>\<em>ddd</em></code>, 177*572c4311Sfengbojiangwhere <em>ddd</em> is a sequence of up to three decimal digits. 178*572c4311Sfengbojiang(Note that if a numerical escape is to be followed by a digit, 179*572c4311Sfengbojiangit must be expressed using exactly three digits.) 180*572c4311SfengbojiangStrings in Lua can contain any 8-bit value, including embedded zeros, 181*572c4311Sfengbojiangwhich can be specified as '<code>\0</code>'. 182*572c4311Sfengbojiang 183*572c4311Sfengbojiang 184*572c4311Sfengbojiang<p> 185*572c4311SfengbojiangLiteral strings can also be defined using a long format 186*572c4311Sfengbojiangenclosed by <em>long brackets</em>. 187*572c4311SfengbojiangWe define an <em>opening long bracket of level <em>n</em></em> as an opening 188*572c4311Sfengbojiangsquare bracket followed by <em>n</em> equal signs followed by another 189*572c4311Sfengbojiangopening square bracket. 190*572c4311SfengbojiangSo, an opening long bracket of level 0 is written as <code>[[</code>, 191*572c4311Sfengbojiangan opening long bracket of level 1 is written as <code>[=[</code>, 192*572c4311Sfengbojiangand so on. 193*572c4311SfengbojiangA <em>closing long bracket</em> is defined similarly; 194*572c4311Sfengbojiangfor instance, a closing long bracket of level 4 is written as <code>]====]</code>. 195*572c4311SfengbojiangA long string starts with an opening long bracket of any level and 196*572c4311Sfengbojiangends at the first closing long bracket of the same level. 197*572c4311SfengbojiangLiterals in this bracketed form can run for several lines, 198*572c4311Sfengbojiangdo not interpret any escape sequences, 199*572c4311Sfengbojiangand ignore long brackets of any other level. 200*572c4311SfengbojiangThey can contain anything except a closing bracket of the proper level. 201*572c4311Sfengbojiang 202*572c4311Sfengbojiang 203*572c4311Sfengbojiang<p> 204*572c4311SfengbojiangFor convenience, 205*572c4311Sfengbojiangwhen the opening long bracket is immediately followed by a newline, 206*572c4311Sfengbojiangthe newline is not included in the string. 207*572c4311SfengbojiangAs an example, in a system using ASCII 208*572c4311Sfengbojiang(in which '<code>a</code>' is coded as 97, 209*572c4311Sfengbojiangnewline is coded as 10, and '<code>1</code>' is coded as 49), 210*572c4311Sfengbojiangthe five literal strings below denote the same string: 211*572c4311Sfengbojiang 212*572c4311Sfengbojiang<pre> 213*572c4311Sfengbojiang a = 'alo\n123"' 214*572c4311Sfengbojiang a = "alo\n123\"" 215*572c4311Sfengbojiang a = '\97lo\10\04923"' 216*572c4311Sfengbojiang a = [[alo 217*572c4311Sfengbojiang 123"]] 218*572c4311Sfengbojiang a = [==[ 219*572c4311Sfengbojiang alo 220*572c4311Sfengbojiang 123"]==] 221*572c4311Sfengbojiang</pre> 222*572c4311Sfengbojiang 223*572c4311Sfengbojiang<p> 224*572c4311SfengbojiangA <em>numerical constant</em> can be written with an optional decimal part 225*572c4311Sfengbojiangand an optional decimal exponent. 226*572c4311SfengbojiangLua also accepts integer hexadecimal constants, 227*572c4311Sfengbojiangby prefixing them with <code>0x</code>. 228*572c4311SfengbojiangExamples of valid numerical constants are 229*572c4311Sfengbojiang 230*572c4311Sfengbojiang<pre> 231*572c4311Sfengbojiang 3 3.0 3.1416 314.16e-2 0.31416E1 0xff 0x56 232*572c4311Sfengbojiang</pre> 233*572c4311Sfengbojiang 234*572c4311Sfengbojiang<p> 235*572c4311SfengbojiangA <em>comment</em> starts with a double hyphen (<code>--</code>) 236*572c4311Sfengbojianganywhere outside a string. 237*572c4311SfengbojiangIf the text immediately after <code>--</code> is not an opening long bracket, 238*572c4311Sfengbojiangthe comment is a <em>short comment</em>, 239*572c4311Sfengbojiangwhich runs until the end of the line. 240*572c4311SfengbojiangOtherwise, it is a <em>long comment</em>, 241*572c4311Sfengbojiangwhich runs until the corresponding closing long bracket. 242*572c4311SfengbojiangLong comments are frequently used to disable code temporarily. 243*572c4311Sfengbojiang 244*572c4311Sfengbojiang 245*572c4311Sfengbojiang 246*572c4311Sfengbojiang 247*572c4311Sfengbojiang 248*572c4311Sfengbojiang<h2>2.2 - <a name="2.2">Values and Types</a></h2> 249*572c4311Sfengbojiang 250*572c4311Sfengbojiang<p> 251*572c4311SfengbojiangLua is a <em>dynamically typed language</em>. 252*572c4311SfengbojiangThis means that 253*572c4311Sfengbojiangvariables do not have types; only values do. 254*572c4311SfengbojiangThere are no type definitions in the language. 255*572c4311SfengbojiangAll values carry their own type. 256*572c4311Sfengbojiang 257*572c4311Sfengbojiang 258*572c4311Sfengbojiang<p> 259*572c4311SfengbojiangAll values in Lua are <em>first-class values</em>. 260*572c4311SfengbojiangThis means that all values can be stored in variables, 261*572c4311Sfengbojiangpassed as arguments to other functions, and returned as results. 262*572c4311Sfengbojiang 263*572c4311Sfengbojiang 264*572c4311Sfengbojiang<p> 265*572c4311SfengbojiangThere are eight basic types in Lua: 266*572c4311Sfengbojiang<em>nil</em>, <em>boolean</em>, <em>number</em>, 267*572c4311Sfengbojiang<em>string</em>, <em>function</em>, <em>userdata</em>, 268*572c4311Sfengbojiang<em>thread</em>, and <em>table</em>. 269*572c4311Sfengbojiang<em>Nil</em> is the type of the value <b>nil</b>, 270*572c4311Sfengbojiangwhose main property is to be different from any other value; 271*572c4311Sfengbojiangit usually represents the absence of a useful value. 272*572c4311Sfengbojiang<em>Boolean</em> is the type of the values <b>false</b> and <b>true</b>. 273*572c4311SfengbojiangBoth <b>nil</b> and <b>false</b> make a condition false; 274*572c4311Sfengbojiangany other value makes it true. 275*572c4311Sfengbojiang<em>Number</em> represents real (double-precision floating-point) numbers. 276*572c4311Sfengbojiang(It is easy to build Lua interpreters that use other 277*572c4311Sfengbojianginternal representations for numbers, 278*572c4311Sfengbojiangsuch as single-precision float or long integers; 279*572c4311Sfengbojiangsee file <code>luaconf.h</code>.) 280*572c4311Sfengbojiang<em>String</em> represents arrays of characters. 281*572c4311Sfengbojiang 282*572c4311SfengbojiangLua is 8-bit clean: 283*572c4311Sfengbojiangstrings can contain any 8-bit character, 284*572c4311Sfengbojiangincluding embedded zeros ('<code>\0</code>') (see <a href="#2.1">§2.1</a>). 285*572c4311Sfengbojiang 286*572c4311Sfengbojiang 287*572c4311Sfengbojiang<p> 288*572c4311SfengbojiangLua can call (and manipulate) functions written in Lua and 289*572c4311Sfengbojiangfunctions written in C 290*572c4311Sfengbojiang(see <a href="#2.5.8">§2.5.8</a>). 291*572c4311Sfengbojiang 292*572c4311Sfengbojiang 293*572c4311Sfengbojiang<p> 294*572c4311SfengbojiangThe type <em>userdata</em> is provided to allow arbitrary C data to 295*572c4311Sfengbojiangbe stored in Lua variables. 296*572c4311SfengbojiangThis type corresponds to a block of raw memory 297*572c4311Sfengbojiangand has no pre-defined operations in Lua, 298*572c4311Sfengbojiangexcept assignment and identity test. 299*572c4311SfengbojiangHowever, by using <em>metatables</em>, 300*572c4311Sfengbojiangthe programmer can define operations for userdata values 301*572c4311Sfengbojiang(see <a href="#2.8">§2.8</a>). 302*572c4311SfengbojiangUserdata values cannot be created or modified in Lua, 303*572c4311Sfengbojiangonly through the C API. 304*572c4311SfengbojiangThis guarantees the integrity of data owned by the host program. 305*572c4311Sfengbojiang 306*572c4311Sfengbojiang 307*572c4311Sfengbojiang<p> 308*572c4311SfengbojiangThe type <em>thread</em> represents independent threads of execution 309*572c4311Sfengbojiangand it is used to implement coroutines (see <a href="#2.11">§2.11</a>). 310*572c4311SfengbojiangDo not confuse Lua threads with operating-system threads. 311*572c4311SfengbojiangLua supports coroutines on all systems, 312*572c4311Sfengbojiangeven those that do not support threads. 313*572c4311Sfengbojiang 314*572c4311Sfengbojiang 315*572c4311Sfengbojiang<p> 316*572c4311SfengbojiangThe type <em>table</em> implements associative arrays, 317*572c4311Sfengbojiangthat is, arrays that can be indexed not only with numbers, 318*572c4311Sfengbojiangbut with any value (except <b>nil</b>). 319*572c4311SfengbojiangTables can be <em>heterogeneous</em>; 320*572c4311Sfengbojiangthat is, they can contain values of all types (except <b>nil</b>). 321*572c4311SfengbojiangTables are the sole data structuring mechanism in Lua; 322*572c4311Sfengbojiangthey can be used to represent ordinary arrays, 323*572c4311Sfengbojiangsymbol tables, sets, records, graphs, trees, etc. 324*572c4311SfengbojiangTo represent records, Lua uses the field name as an index. 325*572c4311SfengbojiangThe language supports this representation by 326*572c4311Sfengbojiangproviding <code>a.name</code> as syntactic sugar for <code>a["name"]</code>. 327*572c4311SfengbojiangThere are several convenient ways to create tables in Lua 328*572c4311Sfengbojiang(see <a href="#2.5.7">§2.5.7</a>). 329*572c4311Sfengbojiang 330*572c4311Sfengbojiang 331*572c4311Sfengbojiang<p> 332*572c4311SfengbojiangLike indices, 333*572c4311Sfengbojiangthe value of a table field can be of any type (except <b>nil</b>). 334*572c4311SfengbojiangIn particular, 335*572c4311Sfengbojiangbecause functions are first-class values, 336*572c4311Sfengbojiangtable fields can contain functions. 337*572c4311SfengbojiangThus tables can also carry <em>methods</em> (see <a href="#2.5.9">§2.5.9</a>). 338*572c4311Sfengbojiang 339*572c4311Sfengbojiang 340*572c4311Sfengbojiang<p> 341*572c4311SfengbojiangTables, functions, threads, and (full) userdata values are <em>objects</em>: 342*572c4311Sfengbojiangvariables do not actually <em>contain</em> these values, 343*572c4311Sfengbojiangonly <em>references</em> to them. 344*572c4311SfengbojiangAssignment, parameter passing, and function returns 345*572c4311Sfengbojiangalways manipulate references to such values; 346*572c4311Sfengbojiangthese operations do not imply any kind of copy. 347*572c4311Sfengbojiang 348*572c4311Sfengbojiang 349*572c4311Sfengbojiang<p> 350*572c4311SfengbojiangThe library function <a href="#pdf-type"><code>type</code></a> returns a string describing the type 351*572c4311Sfengbojiangof a given value. 352*572c4311Sfengbojiang 353*572c4311Sfengbojiang 354*572c4311Sfengbojiang 355*572c4311Sfengbojiang<h3>2.2.1 - <a name="2.2.1">Coercion</a></h3> 356*572c4311Sfengbojiang 357*572c4311Sfengbojiang<p> 358*572c4311SfengbojiangLua provides automatic conversion between 359*572c4311Sfengbojiangstring and number values at run time. 360*572c4311SfengbojiangAny arithmetic operation applied to a string tries to convert 361*572c4311Sfengbojiangthis string to a number, following the usual conversion rules. 362*572c4311SfengbojiangConversely, whenever a number is used where a string is expected, 363*572c4311Sfengbojiangthe number is converted to a string, in a reasonable format. 364*572c4311SfengbojiangFor complete control over how numbers are converted to strings, 365*572c4311Sfengbojianguse the <code>format</code> function from the string library 366*572c4311Sfengbojiang(see <a href="#pdf-string.format"><code>string.format</code></a>). 367*572c4311Sfengbojiang 368*572c4311Sfengbojiang 369*572c4311Sfengbojiang 370*572c4311Sfengbojiang 371*572c4311Sfengbojiang 372*572c4311Sfengbojiang 373*572c4311Sfengbojiang 374*572c4311Sfengbojiang<h2>2.3 - <a name="2.3">Variables</a></h2> 375*572c4311Sfengbojiang 376*572c4311Sfengbojiang<p> 377*572c4311SfengbojiangVariables are places that store values. 378*572c4311Sfengbojiang 379*572c4311SfengbojiangThere are three kinds of variables in Lua: 380*572c4311Sfengbojiangglobal variables, local variables, and table fields. 381*572c4311Sfengbojiang 382*572c4311Sfengbojiang 383*572c4311Sfengbojiang<p> 384*572c4311SfengbojiangA single name can denote a global variable or a local variable 385*572c4311Sfengbojiang(or a function's formal parameter, 386*572c4311Sfengbojiangwhich is a particular kind of local variable): 387*572c4311Sfengbojiang 388*572c4311Sfengbojiang<pre> 389*572c4311Sfengbojiang var ::= Name 390*572c4311Sfengbojiang</pre><p> 391*572c4311SfengbojiangName denotes identifiers, as defined in <a href="#2.1">§2.1</a>. 392*572c4311Sfengbojiang 393*572c4311Sfengbojiang 394*572c4311Sfengbojiang<p> 395*572c4311SfengbojiangAny variable is assumed to be global unless explicitly declared 396*572c4311Sfengbojiangas a local (see <a href="#2.4.7">§2.4.7</a>). 397*572c4311SfengbojiangLocal variables are <em>lexically scoped</em>: 398*572c4311Sfengbojianglocal variables can be freely accessed by functions 399*572c4311Sfengbojiangdefined inside their scope (see <a href="#2.6">§2.6</a>). 400*572c4311Sfengbojiang 401*572c4311Sfengbojiang 402*572c4311Sfengbojiang<p> 403*572c4311SfengbojiangBefore the first assignment to a variable, its value is <b>nil</b>. 404*572c4311Sfengbojiang 405*572c4311Sfengbojiang 406*572c4311Sfengbojiang<p> 407*572c4311SfengbojiangSquare brackets are used to index a table: 408*572c4311Sfengbojiang 409*572c4311Sfengbojiang<pre> 410*572c4311Sfengbojiang var ::= prefixexp `<b>[</b>´ exp `<b>]</b>´ 411*572c4311Sfengbojiang</pre><p> 412*572c4311SfengbojiangThe meaning of accesses to global variables 413*572c4311Sfengbojiangand table fields can be changed via metatables. 414*572c4311SfengbojiangAn access to an indexed variable <code>t[i]</code> is equivalent to 415*572c4311Sfengbojianga call <code>gettable_event(t,i)</code>. 416*572c4311Sfengbojiang(See <a href="#2.8">§2.8</a> for a complete description of the 417*572c4311Sfengbojiang<code>gettable_event</code> function. 418*572c4311SfengbojiangThis function is not defined or callable in Lua. 419*572c4311SfengbojiangWe use it here only for explanatory purposes.) 420*572c4311Sfengbojiang 421*572c4311Sfengbojiang 422*572c4311Sfengbojiang<p> 423*572c4311SfengbojiangThe syntax <code>var.Name</code> is just syntactic sugar for 424*572c4311Sfengbojiang<code>var["Name"]</code>: 425*572c4311Sfengbojiang 426*572c4311Sfengbojiang<pre> 427*572c4311Sfengbojiang var ::= prefixexp `<b>.</b>´ Name 428*572c4311Sfengbojiang</pre> 429*572c4311Sfengbojiang 430*572c4311Sfengbojiang<p> 431*572c4311SfengbojiangAll global variables live as fields in ordinary Lua tables, 432*572c4311Sfengbojiangcalled <em>environment tables</em> or simply 433*572c4311Sfengbojiang<em>environments</em> (see <a href="#2.9">§2.9</a>). 434*572c4311SfengbojiangEach function has its own reference to an environment, 435*572c4311Sfengbojiangso that all global variables in this function 436*572c4311Sfengbojiangwill refer to this environment table. 437*572c4311SfengbojiangWhen a function is created, 438*572c4311Sfengbojiangit inherits the environment from the function that created it. 439*572c4311SfengbojiangTo get the environment table of a Lua function, 440*572c4311Sfengbojiangyou call <a href="#pdf-getfenv"><code>getfenv</code></a>. 441*572c4311SfengbojiangTo replace it, 442*572c4311Sfengbojiangyou call <a href="#pdf-setfenv"><code>setfenv</code></a>. 443*572c4311Sfengbojiang(You can only manipulate the environment of C functions 444*572c4311Sfengbojiangthrough the debug library; (see <a href="#5.9">§5.9</a>).) 445*572c4311Sfengbojiang 446*572c4311Sfengbojiang 447*572c4311Sfengbojiang<p> 448*572c4311SfengbojiangAn access to a global variable <code>x</code> 449*572c4311Sfengbojiangis equivalent to <code>_env.x</code>, 450*572c4311Sfengbojiangwhich in turn is equivalent to 451*572c4311Sfengbojiang 452*572c4311Sfengbojiang<pre> 453*572c4311Sfengbojiang gettable_event(_env, "x") 454*572c4311Sfengbojiang</pre><p> 455*572c4311Sfengbojiangwhere <code>_env</code> is the environment of the running function. 456*572c4311Sfengbojiang(See <a href="#2.8">§2.8</a> for a complete description of the 457*572c4311Sfengbojiang<code>gettable_event</code> function. 458*572c4311SfengbojiangThis function is not defined or callable in Lua. 459*572c4311SfengbojiangSimilarly, the <code>_env</code> variable is not defined in Lua. 460*572c4311SfengbojiangWe use them here only for explanatory purposes.) 461*572c4311Sfengbojiang 462*572c4311Sfengbojiang 463*572c4311Sfengbojiang 464*572c4311Sfengbojiang 465*572c4311Sfengbojiang 466*572c4311Sfengbojiang<h2>2.4 - <a name="2.4">Statements</a></h2> 467*572c4311Sfengbojiang 468*572c4311Sfengbojiang<p> 469*572c4311SfengbojiangLua supports an almost conventional set of statements, 470*572c4311Sfengbojiangsimilar to those in Pascal or C. 471*572c4311SfengbojiangThis set includes 472*572c4311Sfengbojiangassignments, control structures, function calls, 473*572c4311Sfengbojiangand variable declarations. 474*572c4311Sfengbojiang 475*572c4311Sfengbojiang 476*572c4311Sfengbojiang 477*572c4311Sfengbojiang<h3>2.4.1 - <a name="2.4.1">Chunks</a></h3> 478*572c4311Sfengbojiang 479*572c4311Sfengbojiang<p> 480*572c4311SfengbojiangThe unit of execution of Lua is called a <em>chunk</em>. 481*572c4311SfengbojiangA chunk is simply a sequence of statements, 482*572c4311Sfengbojiangwhich are executed sequentially. 483*572c4311SfengbojiangEach statement can be optionally followed by a semicolon: 484*572c4311Sfengbojiang 485*572c4311Sfengbojiang<pre> 486*572c4311Sfengbojiang chunk ::= {stat [`<b>;</b>´]} 487*572c4311Sfengbojiang</pre><p> 488*572c4311SfengbojiangThere are no empty statements and thus '<code>;;</code>' is not legal. 489*572c4311Sfengbojiang 490*572c4311Sfengbojiang 491*572c4311Sfengbojiang<p> 492*572c4311SfengbojiangLua handles a chunk as the body of an anonymous function 493*572c4311Sfengbojiangwith a variable number of arguments 494*572c4311Sfengbojiang(see <a href="#2.5.9">§2.5.9</a>). 495*572c4311SfengbojiangAs such, chunks can define local variables, 496*572c4311Sfengbojiangreceive arguments, and return values. 497*572c4311Sfengbojiang 498*572c4311Sfengbojiang 499*572c4311Sfengbojiang<p> 500*572c4311SfengbojiangA chunk can be stored in a file or in a string inside the host program. 501*572c4311SfengbojiangTo execute a chunk, 502*572c4311SfengbojiangLua first pre-compiles the chunk into instructions for a virtual machine, 503*572c4311Sfengbojiangand then it executes the compiled code 504*572c4311Sfengbojiangwith an interpreter for the virtual machine. 505*572c4311Sfengbojiang 506*572c4311Sfengbojiang 507*572c4311Sfengbojiang<p> 508*572c4311SfengbojiangChunks can also be pre-compiled into binary form; 509*572c4311Sfengbojiangsee program <code>luac</code> for details. 510*572c4311SfengbojiangPrograms in source and compiled forms are interchangeable; 511*572c4311SfengbojiangLua automatically detects the file type and acts accordingly. 512*572c4311Sfengbojiang 513*572c4311Sfengbojiang 514*572c4311Sfengbojiang 515*572c4311Sfengbojiang 516*572c4311Sfengbojiang 517*572c4311Sfengbojiang 518*572c4311Sfengbojiang<h3>2.4.2 - <a name="2.4.2">Blocks</a></h3><p> 519*572c4311SfengbojiangA block is a list of statements; 520*572c4311Sfengbojiangsyntactically, a block is the same as a chunk: 521*572c4311Sfengbojiang 522*572c4311Sfengbojiang<pre> 523*572c4311Sfengbojiang block ::= chunk 524*572c4311Sfengbojiang</pre> 525*572c4311Sfengbojiang 526*572c4311Sfengbojiang<p> 527*572c4311SfengbojiangA block can be explicitly delimited to produce a single statement: 528*572c4311Sfengbojiang 529*572c4311Sfengbojiang<pre> 530*572c4311Sfengbojiang stat ::= <b>do</b> block <b>end</b> 531*572c4311Sfengbojiang</pre><p> 532*572c4311SfengbojiangExplicit blocks are useful 533*572c4311Sfengbojiangto control the scope of variable declarations. 534*572c4311SfengbojiangExplicit blocks are also sometimes used to 535*572c4311Sfengbojiangadd a <b>return</b> or <b>break</b> statement in the middle 536*572c4311Sfengbojiangof another block (see <a href="#2.4.4">§2.4.4</a>). 537*572c4311Sfengbojiang 538*572c4311Sfengbojiang 539*572c4311Sfengbojiang 540*572c4311Sfengbojiang 541*572c4311Sfengbojiang 542*572c4311Sfengbojiang<h3>2.4.3 - <a name="2.4.3">Assignment</a></h3> 543*572c4311Sfengbojiang 544*572c4311Sfengbojiang<p> 545*572c4311SfengbojiangLua allows multiple assignments. 546*572c4311SfengbojiangTherefore, the syntax for assignment 547*572c4311Sfengbojiangdefines a list of variables on the left side 548*572c4311Sfengbojiangand a list of expressions on the right side. 549*572c4311SfengbojiangThe elements in both lists are separated by commas: 550*572c4311Sfengbojiang 551*572c4311Sfengbojiang<pre> 552*572c4311Sfengbojiang stat ::= varlist `<b>=</b>´ explist 553*572c4311Sfengbojiang varlist ::= var {`<b>,</b>´ var} 554*572c4311Sfengbojiang explist ::= exp {`<b>,</b>´ exp} 555*572c4311Sfengbojiang</pre><p> 556*572c4311SfengbojiangExpressions are discussed in <a href="#2.5">§2.5</a>. 557*572c4311Sfengbojiang 558*572c4311Sfengbojiang 559*572c4311Sfengbojiang<p> 560*572c4311SfengbojiangBefore the assignment, 561*572c4311Sfengbojiangthe list of values is <em>adjusted</em> to the length of 562*572c4311Sfengbojiangthe list of variables. 563*572c4311SfengbojiangIf there are more values than needed, 564*572c4311Sfengbojiangthe excess values are thrown away. 565*572c4311SfengbojiangIf there are fewer values than needed, 566*572c4311Sfengbojiangthe list is extended with as many <b>nil</b>'s as needed. 567*572c4311SfengbojiangIf the list of expressions ends with a function call, 568*572c4311Sfengbojiangthen all values returned by that call enter the list of values, 569*572c4311Sfengbojiangbefore the adjustment 570*572c4311Sfengbojiang(except when the call is enclosed in parentheses; see <a href="#2.5">§2.5</a>). 571*572c4311Sfengbojiang 572*572c4311Sfengbojiang 573*572c4311Sfengbojiang<p> 574*572c4311SfengbojiangThe assignment statement first evaluates all its expressions 575*572c4311Sfengbojiangand only then are the assignments performed. 576*572c4311SfengbojiangThus the code 577*572c4311Sfengbojiang 578*572c4311Sfengbojiang<pre> 579*572c4311Sfengbojiang i = 3 580*572c4311Sfengbojiang i, a[i] = i+1, 20 581*572c4311Sfengbojiang</pre><p> 582*572c4311Sfengbojiangsets <code>a[3]</code> to 20, without affecting <code>a[4]</code> 583*572c4311Sfengbojiangbecause the <code>i</code> in <code>a[i]</code> is evaluated (to 3) 584*572c4311Sfengbojiangbefore it is assigned 4. 585*572c4311SfengbojiangSimilarly, the line 586*572c4311Sfengbojiang 587*572c4311Sfengbojiang<pre> 588*572c4311Sfengbojiang x, y = y, x 589*572c4311Sfengbojiang</pre><p> 590*572c4311Sfengbojiangexchanges the values of <code>x</code> and <code>y</code>, 591*572c4311Sfengbojiangand 592*572c4311Sfengbojiang 593*572c4311Sfengbojiang<pre> 594*572c4311Sfengbojiang x, y, z = y, z, x 595*572c4311Sfengbojiang</pre><p> 596*572c4311Sfengbojiangcyclically permutes the values of <code>x</code>, <code>y</code>, and <code>z</code>. 597*572c4311Sfengbojiang 598*572c4311Sfengbojiang 599*572c4311Sfengbojiang<p> 600*572c4311SfengbojiangThe meaning of assignments to global variables 601*572c4311Sfengbojiangand table fields can be changed via metatables. 602*572c4311SfengbojiangAn assignment to an indexed variable <code>t[i] = val</code> is equivalent to 603*572c4311Sfengbojiang<code>settable_event(t,i,val)</code>. 604*572c4311Sfengbojiang(See <a href="#2.8">§2.8</a> for a complete description of the 605*572c4311Sfengbojiang<code>settable_event</code> function. 606*572c4311SfengbojiangThis function is not defined or callable in Lua. 607*572c4311SfengbojiangWe use it here only for explanatory purposes.) 608*572c4311Sfengbojiang 609*572c4311Sfengbojiang 610*572c4311Sfengbojiang<p> 611*572c4311SfengbojiangAn assignment to a global variable <code>x = val</code> 612*572c4311Sfengbojiangis equivalent to the assignment 613*572c4311Sfengbojiang<code>_env.x = val</code>, 614*572c4311Sfengbojiangwhich in turn is equivalent to 615*572c4311Sfengbojiang 616*572c4311Sfengbojiang<pre> 617*572c4311Sfengbojiang settable_event(_env, "x", val) 618*572c4311Sfengbojiang</pre><p> 619*572c4311Sfengbojiangwhere <code>_env</code> is the environment of the running function. 620*572c4311Sfengbojiang(The <code>_env</code> variable is not defined in Lua. 621*572c4311SfengbojiangWe use it here only for explanatory purposes.) 622*572c4311Sfengbojiang 623*572c4311Sfengbojiang 624*572c4311Sfengbojiang 625*572c4311Sfengbojiang 626*572c4311Sfengbojiang 627*572c4311Sfengbojiang<h3>2.4.4 - <a name="2.4.4">Control Structures</a></h3><p> 628*572c4311SfengbojiangThe control structures 629*572c4311Sfengbojiang<b>if</b>, <b>while</b>, and <b>repeat</b> have the usual meaning and 630*572c4311Sfengbojiangfamiliar syntax: 631*572c4311Sfengbojiang 632*572c4311Sfengbojiang 633*572c4311Sfengbojiang 634*572c4311Sfengbojiang 635*572c4311Sfengbojiang<pre> 636*572c4311Sfengbojiang stat ::= <b>while</b> exp <b>do</b> block <b>end</b> 637*572c4311Sfengbojiang stat ::= <b>repeat</b> block <b>until</b> exp 638*572c4311Sfengbojiang stat ::= <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> 639*572c4311Sfengbojiang</pre><p> 640*572c4311SfengbojiangLua also has a <b>for</b> statement, in two flavors (see <a href="#2.4.5">§2.4.5</a>). 641*572c4311Sfengbojiang 642*572c4311Sfengbojiang 643*572c4311Sfengbojiang<p> 644*572c4311SfengbojiangThe condition expression of a 645*572c4311Sfengbojiangcontrol structure can return any value. 646*572c4311SfengbojiangBoth <b>false</b> and <b>nil</b> are considered false. 647*572c4311SfengbojiangAll values different from <b>nil</b> and <b>false</b> are considered true 648*572c4311Sfengbojiang(in particular, the number 0 and the empty string are also true). 649*572c4311Sfengbojiang 650*572c4311Sfengbojiang 651*572c4311Sfengbojiang<p> 652*572c4311SfengbojiangIn the <b>repeat</b>–<b>until</b> loop, 653*572c4311Sfengbojiangthe inner block does not end at the <b>until</b> keyword, 654*572c4311Sfengbojiangbut only after the condition. 655*572c4311SfengbojiangSo, the condition can refer to local variables 656*572c4311Sfengbojiangdeclared inside the loop block. 657*572c4311Sfengbojiang 658*572c4311Sfengbojiang 659*572c4311Sfengbojiang<p> 660*572c4311SfengbojiangThe <b>return</b> statement is used to return values 661*572c4311Sfengbojiangfrom a function or a chunk (which is just a function). 662*572c4311Sfengbojiang 663*572c4311SfengbojiangFunctions and chunks can return more than one value, 664*572c4311Sfengbojiangand so the syntax for the <b>return</b> statement is 665*572c4311Sfengbojiang 666*572c4311Sfengbojiang<pre> 667*572c4311Sfengbojiang stat ::= <b>return</b> [explist] 668*572c4311Sfengbojiang</pre> 669*572c4311Sfengbojiang 670*572c4311Sfengbojiang<p> 671*572c4311SfengbojiangThe <b>break</b> statement is used to terminate the execution of a 672*572c4311Sfengbojiang<b>while</b>, <b>repeat</b>, or <b>for</b> loop, 673*572c4311Sfengbojiangskipping to the next statement after the loop: 674*572c4311Sfengbojiang 675*572c4311Sfengbojiang 676*572c4311Sfengbojiang<pre> 677*572c4311Sfengbojiang stat ::= <b>break</b> 678*572c4311Sfengbojiang</pre><p> 679*572c4311SfengbojiangA <b>break</b> ends the innermost enclosing loop. 680*572c4311Sfengbojiang 681*572c4311Sfengbojiang 682*572c4311Sfengbojiang<p> 683*572c4311SfengbojiangThe <b>return</b> and <b>break</b> 684*572c4311Sfengbojiangstatements can only be written as the <em>last</em> statement of a block. 685*572c4311SfengbojiangIf it is really necessary to <b>return</b> or <b>break</b> in the 686*572c4311Sfengbojiangmiddle of a block, 687*572c4311Sfengbojiangthen an explicit inner block can be used, 688*572c4311Sfengbojiangas in the idioms 689*572c4311Sfengbojiang<code>do return end</code> and <code>do break end</code>, 690*572c4311Sfengbojiangbecause now <b>return</b> and <b>break</b> are the last statements in 691*572c4311Sfengbojiangtheir (inner) blocks. 692*572c4311Sfengbojiang 693*572c4311Sfengbojiang 694*572c4311Sfengbojiang 695*572c4311Sfengbojiang 696*572c4311Sfengbojiang 697*572c4311Sfengbojiang<h3>2.4.5 - <a name="2.4.5">For Statement</a></h3> 698*572c4311Sfengbojiang 699*572c4311Sfengbojiang<p> 700*572c4311Sfengbojiang 701*572c4311SfengbojiangThe <b>for</b> statement has two forms: 702*572c4311Sfengbojiangone numeric and one generic. 703*572c4311Sfengbojiang 704*572c4311Sfengbojiang 705*572c4311Sfengbojiang<p> 706*572c4311SfengbojiangThe numeric <b>for</b> loop repeats a block of code while a 707*572c4311Sfengbojiangcontrol variable runs through an arithmetic progression. 708*572c4311SfengbojiangIt has the following syntax: 709*572c4311Sfengbojiang 710*572c4311Sfengbojiang<pre> 711*572c4311Sfengbojiang stat ::= <b>for</b> Name `<b>=</b>´ exp `<b>,</b>´ exp [`<b>,</b>´ exp] <b>do</b> block <b>end</b> 712*572c4311Sfengbojiang</pre><p> 713*572c4311SfengbojiangThe <em>block</em> is repeated for <em>name</em> starting at the value of 714*572c4311Sfengbojiangthe first <em>exp</em>, until it passes the second <em>exp</em> by steps of the 715*572c4311Sfengbojiangthird <em>exp</em>. 716*572c4311SfengbojiangMore precisely, a <b>for</b> statement like 717*572c4311Sfengbojiang 718*572c4311Sfengbojiang<pre> 719*572c4311Sfengbojiang for v = <em>e1</em>, <em>e2</em>, <em>e3</em> do <em>block</em> end 720*572c4311Sfengbojiang</pre><p> 721*572c4311Sfengbojiangis equivalent to the code: 722*572c4311Sfengbojiang 723*572c4311Sfengbojiang<pre> 724*572c4311Sfengbojiang do 725*572c4311Sfengbojiang local <em>var</em>, <em>limit</em>, <em>step</em> = tonumber(<em>e1</em>), tonumber(<em>e2</em>), tonumber(<em>e3</em>) 726*572c4311Sfengbojiang if not (<em>var</em> and <em>limit</em> and <em>step</em>) then error() end 727*572c4311Sfengbojiang 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 728*572c4311Sfengbojiang local v = <em>var</em> 729*572c4311Sfengbojiang <em>block</em> 730*572c4311Sfengbojiang <em>var</em> = <em>var</em> + <em>step</em> 731*572c4311Sfengbojiang end 732*572c4311Sfengbojiang end 733*572c4311Sfengbojiang</pre><p> 734*572c4311SfengbojiangNote the following: 735*572c4311Sfengbojiang 736*572c4311Sfengbojiang<ul> 737*572c4311Sfengbojiang 738*572c4311Sfengbojiang<li> 739*572c4311SfengbojiangAll three control expressions are evaluated only once, 740*572c4311Sfengbojiangbefore the loop starts. 741*572c4311SfengbojiangThey must all result in numbers. 742*572c4311Sfengbojiang</li> 743*572c4311Sfengbojiang 744*572c4311Sfengbojiang<li> 745*572c4311Sfengbojiang<code><em>var</em></code>, <code><em>limit</em></code>, and <code><em>step</em></code> are invisible variables. 746*572c4311SfengbojiangThe names shown here are for explanatory purposes only. 747*572c4311Sfengbojiang</li> 748*572c4311Sfengbojiang 749*572c4311Sfengbojiang<li> 750*572c4311SfengbojiangIf the third expression (the step) is absent, 751*572c4311Sfengbojiangthen a step of 1 is used. 752*572c4311Sfengbojiang</li> 753*572c4311Sfengbojiang 754*572c4311Sfengbojiang<li> 755*572c4311SfengbojiangYou can use <b>break</b> to exit a <b>for</b> loop. 756*572c4311Sfengbojiang</li> 757*572c4311Sfengbojiang 758*572c4311Sfengbojiang<li> 759*572c4311SfengbojiangThe loop variable <code>v</code> is local to the loop; 760*572c4311Sfengbojiangyou cannot use its value after the <b>for</b> ends or is broken. 761*572c4311SfengbojiangIf you need this value, 762*572c4311Sfengbojiangassign it to another variable before breaking or exiting the loop. 763*572c4311Sfengbojiang</li> 764*572c4311Sfengbojiang 765*572c4311Sfengbojiang</ul> 766*572c4311Sfengbojiang 767*572c4311Sfengbojiang<p> 768*572c4311SfengbojiangThe generic <b>for</b> statement works over functions, 769*572c4311Sfengbojiangcalled <em>iterators</em>. 770*572c4311SfengbojiangOn each iteration, the iterator function is called to produce a new value, 771*572c4311Sfengbojiangstopping when this new value is <b>nil</b>. 772*572c4311SfengbojiangThe generic <b>for</b> loop has the following syntax: 773*572c4311Sfengbojiang 774*572c4311Sfengbojiang<pre> 775*572c4311Sfengbojiang stat ::= <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> 776*572c4311Sfengbojiang namelist ::= Name {`<b>,</b>´ Name} 777*572c4311Sfengbojiang</pre><p> 778*572c4311SfengbojiangA <b>for</b> statement like 779*572c4311Sfengbojiang 780*572c4311Sfengbojiang<pre> 781*572c4311Sfengbojiang for <em>var_1</em>, ···, <em>var_n</em> in <em>explist</em> do <em>block</em> end 782*572c4311Sfengbojiang</pre><p> 783*572c4311Sfengbojiangis equivalent to the code: 784*572c4311Sfengbojiang 785*572c4311Sfengbojiang<pre> 786*572c4311Sfengbojiang do 787*572c4311Sfengbojiang local <em>f</em>, <em>s</em>, <em>var</em> = <em>explist</em> 788*572c4311Sfengbojiang while true do 789*572c4311Sfengbojiang local <em>var_1</em>, ···, <em>var_n</em> = <em>f</em>(<em>s</em>, <em>var</em>) 790*572c4311Sfengbojiang <em>var</em> = <em>var_1</em> 791*572c4311Sfengbojiang if <em>var</em> == nil then break end 792*572c4311Sfengbojiang <em>block</em> 793*572c4311Sfengbojiang end 794*572c4311Sfengbojiang end 795*572c4311Sfengbojiang</pre><p> 796*572c4311SfengbojiangNote the following: 797*572c4311Sfengbojiang 798*572c4311Sfengbojiang<ul> 799*572c4311Sfengbojiang 800*572c4311Sfengbojiang<li> 801*572c4311Sfengbojiang<code><em>explist</em></code> is evaluated only once. 802*572c4311SfengbojiangIts results are an <em>iterator</em> function, 803*572c4311Sfengbojianga <em>state</em>, 804*572c4311Sfengbojiangand an initial value for the first <em>iterator variable</em>. 805*572c4311Sfengbojiang</li> 806*572c4311Sfengbojiang 807*572c4311Sfengbojiang<li> 808*572c4311Sfengbojiang<code><em>f</em></code>, <code><em>s</em></code>, and <code><em>var</em></code> are invisible variables. 809*572c4311SfengbojiangThe names are here for explanatory purposes only. 810*572c4311Sfengbojiang</li> 811*572c4311Sfengbojiang 812*572c4311Sfengbojiang<li> 813*572c4311SfengbojiangYou can use <b>break</b> to exit a <b>for</b> loop. 814*572c4311Sfengbojiang</li> 815*572c4311Sfengbojiang 816*572c4311Sfengbojiang<li> 817*572c4311SfengbojiangThe loop variables <code><em>var_i</em></code> are local to the loop; 818*572c4311Sfengbojiangyou cannot use their values after the <b>for</b> ends. 819*572c4311SfengbojiangIf you need these values, 820*572c4311Sfengbojiangthen assign them to other variables before breaking or exiting the loop. 821*572c4311Sfengbojiang</li> 822*572c4311Sfengbojiang 823*572c4311Sfengbojiang</ul> 824*572c4311Sfengbojiang 825*572c4311Sfengbojiang 826*572c4311Sfengbojiang 827*572c4311Sfengbojiang 828*572c4311Sfengbojiang<h3>2.4.6 - <a name="2.4.6">Function Calls as Statements</a></h3><p> 829*572c4311SfengbojiangTo allow possible side-effects, 830*572c4311Sfengbojiangfunction calls can be executed as statements: 831*572c4311Sfengbojiang 832*572c4311Sfengbojiang<pre> 833*572c4311Sfengbojiang stat ::= functioncall 834*572c4311Sfengbojiang</pre><p> 835*572c4311SfengbojiangIn this case, all returned values are thrown away. 836*572c4311SfengbojiangFunction calls are explained in <a href="#2.5.8">§2.5.8</a>. 837*572c4311Sfengbojiang 838*572c4311Sfengbojiang 839*572c4311Sfengbojiang 840*572c4311Sfengbojiang 841*572c4311Sfengbojiang 842*572c4311Sfengbojiang<h3>2.4.7 - <a name="2.4.7">Local Declarations</a></h3><p> 843*572c4311SfengbojiangLocal variables can be declared anywhere inside a block. 844*572c4311SfengbojiangThe declaration can include an initial assignment: 845*572c4311Sfengbojiang 846*572c4311Sfengbojiang<pre> 847*572c4311Sfengbojiang stat ::= <b>local</b> namelist [`<b>=</b>´ explist] 848*572c4311Sfengbojiang</pre><p> 849*572c4311SfengbojiangIf present, an initial assignment has the same semantics 850*572c4311Sfengbojiangof a multiple assignment (see <a href="#2.4.3">§2.4.3</a>). 851*572c4311SfengbojiangOtherwise, all variables are initialized with <b>nil</b>. 852*572c4311Sfengbojiang 853*572c4311Sfengbojiang 854*572c4311Sfengbojiang<p> 855*572c4311SfengbojiangA chunk is also a block (see <a href="#2.4.1">§2.4.1</a>), 856*572c4311Sfengbojiangand so local variables can be declared in a chunk outside any explicit block. 857*572c4311SfengbojiangThe scope of such local variables extends until the end of the chunk. 858*572c4311Sfengbojiang 859*572c4311Sfengbojiang 860*572c4311Sfengbojiang<p> 861*572c4311SfengbojiangThe visibility rules for local variables are explained in <a href="#2.6">§2.6</a>. 862*572c4311Sfengbojiang 863*572c4311Sfengbojiang 864*572c4311Sfengbojiang 865*572c4311Sfengbojiang 866*572c4311Sfengbojiang 867*572c4311Sfengbojiang 868*572c4311Sfengbojiang 869*572c4311Sfengbojiang<h2>2.5 - <a name="2.5">Expressions</a></h2> 870*572c4311Sfengbojiang 871*572c4311Sfengbojiang<p> 872*572c4311SfengbojiangThe basic expressions in Lua are the following: 873*572c4311Sfengbojiang 874*572c4311Sfengbojiang<pre> 875*572c4311Sfengbojiang exp ::= prefixexp 876*572c4311Sfengbojiang exp ::= <b>nil</b> | <b>false</b> | <b>true</b> 877*572c4311Sfengbojiang exp ::= Number 878*572c4311Sfengbojiang exp ::= String 879*572c4311Sfengbojiang exp ::= function 880*572c4311Sfengbojiang exp ::= tableconstructor 881*572c4311Sfengbojiang exp ::= `<b>...</b>´ 882*572c4311Sfengbojiang exp ::= exp binop exp 883*572c4311Sfengbojiang exp ::= unop exp 884*572c4311Sfengbojiang prefixexp ::= var | functioncall | `<b>(</b>´ exp `<b>)</b>´ 885*572c4311Sfengbojiang</pre> 886*572c4311Sfengbojiang 887*572c4311Sfengbojiang<p> 888*572c4311SfengbojiangNumbers and literal strings are explained in <a href="#2.1">§2.1</a>; 889*572c4311Sfengbojiangvariables are explained in <a href="#2.3">§2.3</a>; 890*572c4311Sfengbojiangfunction definitions are explained in <a href="#2.5.9">§2.5.9</a>; 891*572c4311Sfengbojiangfunction calls are explained in <a href="#2.5.8">§2.5.8</a>; 892*572c4311Sfengbojiangtable constructors are explained in <a href="#2.5.7">§2.5.7</a>. 893*572c4311SfengbojiangVararg expressions, 894*572c4311Sfengbojiangdenoted by three dots ('<code>...</code>'), can only be used when 895*572c4311Sfengbojiangdirectly inside a vararg function; 896*572c4311Sfengbojiangthey are explained in <a href="#2.5.9">§2.5.9</a>. 897*572c4311Sfengbojiang 898*572c4311Sfengbojiang 899*572c4311Sfengbojiang<p> 900*572c4311SfengbojiangBinary operators comprise arithmetic operators (see <a href="#2.5.1">§2.5.1</a>), 901*572c4311Sfengbojiangrelational operators (see <a href="#2.5.2">§2.5.2</a>), logical operators (see <a href="#2.5.3">§2.5.3</a>), 902*572c4311Sfengbojiangand the concatenation operator (see <a href="#2.5.4">§2.5.4</a>). 903*572c4311SfengbojiangUnary operators comprise the unary minus (see <a href="#2.5.1">§2.5.1</a>), 904*572c4311Sfengbojiangthe unary <b>not</b> (see <a href="#2.5.3">§2.5.3</a>), 905*572c4311Sfengbojiangand the unary <em>length operator</em> (see <a href="#2.5.5">§2.5.5</a>). 906*572c4311Sfengbojiang 907*572c4311Sfengbojiang 908*572c4311Sfengbojiang<p> 909*572c4311SfengbojiangBoth function calls and vararg expressions can result in multiple values. 910*572c4311SfengbojiangIf an expression is used as a statement 911*572c4311Sfengbojiang(only possible for function calls (see <a href="#2.4.6">§2.4.6</a>)), 912*572c4311Sfengbojiangthen its return list is adjusted to zero elements, 913*572c4311Sfengbojiangthus discarding all returned values. 914*572c4311SfengbojiangIf an expression is used as the last (or the only) element 915*572c4311Sfengbojiangof a list of expressions, 916*572c4311Sfengbojiangthen no adjustment is made 917*572c4311Sfengbojiang(unless the call is enclosed in parentheses). 918*572c4311SfengbojiangIn all other contexts, 919*572c4311SfengbojiangLua adjusts the result list to one element, 920*572c4311Sfengbojiangdiscarding all values except the first one. 921*572c4311Sfengbojiang 922*572c4311Sfengbojiang 923*572c4311Sfengbojiang<p> 924*572c4311SfengbojiangHere are some examples: 925*572c4311Sfengbojiang 926*572c4311Sfengbojiang<pre> 927*572c4311Sfengbojiang f() -- adjusted to 0 results 928*572c4311Sfengbojiang g(f(), x) -- f() is adjusted to 1 result 929*572c4311Sfengbojiang g(x, f()) -- g gets x plus all results from f() 930*572c4311Sfengbojiang a,b,c = f(), x -- f() is adjusted to 1 result (c gets nil) 931*572c4311Sfengbojiang a,b = ... -- a gets the first vararg parameter, b gets 932*572c4311Sfengbojiang -- the second (both a and b can get nil if there 933*572c4311Sfengbojiang -- is no corresponding vararg parameter) 934*572c4311Sfengbojiang 935*572c4311Sfengbojiang a,b,c = x, f() -- f() is adjusted to 2 results 936*572c4311Sfengbojiang a,b,c = f() -- f() is adjusted to 3 results 937*572c4311Sfengbojiang return f() -- returns all results from f() 938*572c4311Sfengbojiang return ... -- returns all received vararg parameters 939*572c4311Sfengbojiang return x,y,f() -- returns x, y, and all results from f() 940*572c4311Sfengbojiang {f()} -- creates a list with all results from f() 941*572c4311Sfengbojiang {...} -- creates a list with all vararg parameters 942*572c4311Sfengbojiang {f(), nil} -- f() is adjusted to 1 result 943*572c4311Sfengbojiang</pre> 944*572c4311Sfengbojiang 945*572c4311Sfengbojiang<p> 946*572c4311SfengbojiangAny expression enclosed in parentheses always results in only one value. 947*572c4311SfengbojiangThus, 948*572c4311Sfengbojiang<code>(f(x,y,z))</code> is always a single value, 949*572c4311Sfengbojiangeven if <code>f</code> returns several values. 950*572c4311Sfengbojiang(The value of <code>(f(x,y,z))</code> is the first value returned by <code>f</code> 951*572c4311Sfengbojiangor <b>nil</b> if <code>f</code> does not return any values.) 952*572c4311Sfengbojiang 953*572c4311Sfengbojiang 954*572c4311Sfengbojiang 955*572c4311Sfengbojiang<h3>2.5.1 - <a name="2.5.1">Arithmetic Operators</a></h3><p> 956*572c4311SfengbojiangLua supports the usual arithmetic operators: 957*572c4311Sfengbojiangthe binary <code>+</code> (addition), 958*572c4311Sfengbojiang<code>-</code> (subtraction), <code>*</code> (multiplication), 959*572c4311Sfengbojiang<code>/</code> (division), <code>%</code> (modulo), and <code>^</code> (exponentiation); 960*572c4311Sfengbojiangand unary <code>-</code> (negation). 961*572c4311SfengbojiangIf the operands are numbers, or strings that can be converted to 962*572c4311Sfengbojiangnumbers (see <a href="#2.2.1">§2.2.1</a>), 963*572c4311Sfengbojiangthen all operations have the usual meaning. 964*572c4311SfengbojiangExponentiation works for any exponent. 965*572c4311SfengbojiangFor instance, <code>x^(-0.5)</code> computes the inverse of the square root of <code>x</code>. 966*572c4311SfengbojiangModulo is defined as 967*572c4311Sfengbojiang 968*572c4311Sfengbojiang<pre> 969*572c4311Sfengbojiang a % b == a - math.floor(a/b)*b 970*572c4311Sfengbojiang</pre><p> 971*572c4311SfengbojiangThat is, it is the remainder of a division that rounds 972*572c4311Sfengbojiangthe quotient towards minus infinity. 973*572c4311Sfengbojiang 974*572c4311Sfengbojiang 975*572c4311Sfengbojiang 976*572c4311Sfengbojiang 977*572c4311Sfengbojiang 978*572c4311Sfengbojiang<h3>2.5.2 - <a name="2.5.2">Relational Operators</a></h3><p> 979*572c4311SfengbojiangThe relational operators in Lua are 980*572c4311Sfengbojiang 981*572c4311Sfengbojiang<pre> 982*572c4311Sfengbojiang == ~= < > <= >= 983*572c4311Sfengbojiang</pre><p> 984*572c4311SfengbojiangThese operators always result in <b>false</b> or <b>true</b>. 985*572c4311Sfengbojiang 986*572c4311Sfengbojiang 987*572c4311Sfengbojiang<p> 988*572c4311SfengbojiangEquality (<code>==</code>) first compares the type of its operands. 989*572c4311SfengbojiangIf the types are different, then the result is <b>false</b>. 990*572c4311SfengbojiangOtherwise, the values of the operands are compared. 991*572c4311SfengbojiangNumbers and strings are compared in the usual way. 992*572c4311SfengbojiangObjects (tables, userdata, threads, and functions) 993*572c4311Sfengbojiangare compared by <em>reference</em>: 994*572c4311Sfengbojiangtwo objects are considered equal only if they are the <em>same</em> object. 995*572c4311SfengbojiangEvery time you create a new object 996*572c4311Sfengbojiang(a table, userdata, thread, or function), 997*572c4311Sfengbojiangthis new object is different from any previously existing object. 998*572c4311Sfengbojiang 999*572c4311Sfengbojiang 1000*572c4311Sfengbojiang<p> 1001*572c4311SfengbojiangYou can change the way that Lua compares tables and userdata 1002*572c4311Sfengbojiangby using the "eq" metamethod (see <a href="#2.8">§2.8</a>). 1003*572c4311Sfengbojiang 1004*572c4311Sfengbojiang 1005*572c4311Sfengbojiang<p> 1006*572c4311SfengbojiangThe conversion rules of <a href="#2.2.1">§2.2.1</a> 1007*572c4311Sfengbojiang<em>do not</em> apply to equality comparisons. 1008*572c4311SfengbojiangThus, <code>"0"==0</code> evaluates to <b>false</b>, 1009*572c4311Sfengbojiangand <code>t[0]</code> and <code>t["0"]</code> denote different 1010*572c4311Sfengbojiangentries in a table. 1011*572c4311Sfengbojiang 1012*572c4311Sfengbojiang 1013*572c4311Sfengbojiang<p> 1014*572c4311SfengbojiangThe operator <code>~=</code> is exactly the negation of equality (<code>==</code>). 1015*572c4311Sfengbojiang 1016*572c4311Sfengbojiang 1017*572c4311Sfengbojiang<p> 1018*572c4311SfengbojiangThe order operators work as follows. 1019*572c4311SfengbojiangIf both arguments are numbers, then they are compared as such. 1020*572c4311SfengbojiangOtherwise, if both arguments are strings, 1021*572c4311Sfengbojiangthen their values are compared according to the current locale. 1022*572c4311SfengbojiangOtherwise, Lua tries to call the "lt" or the "le" 1023*572c4311Sfengbojiangmetamethod (see <a href="#2.8">§2.8</a>). 1024*572c4311SfengbojiangA comparison <code>a > b</code> is translated to <code>b < a</code> 1025*572c4311Sfengbojiangand <code>a >= b</code> is translated to <code>b <= a</code>. 1026*572c4311Sfengbojiang 1027*572c4311Sfengbojiang 1028*572c4311Sfengbojiang 1029*572c4311Sfengbojiang 1030*572c4311Sfengbojiang 1031*572c4311Sfengbojiang<h3>2.5.3 - <a name="2.5.3">Logical Operators</a></h3><p> 1032*572c4311SfengbojiangThe logical operators in Lua are 1033*572c4311Sfengbojiang<b>and</b>, <b>or</b>, and <b>not</b>. 1034*572c4311SfengbojiangLike the control structures (see <a href="#2.4.4">§2.4.4</a>), 1035*572c4311Sfengbojiangall logical operators consider both <b>false</b> and <b>nil</b> as false 1036*572c4311Sfengbojiangand anything else as true. 1037*572c4311Sfengbojiang 1038*572c4311Sfengbojiang 1039*572c4311Sfengbojiang<p> 1040*572c4311SfengbojiangThe negation operator <b>not</b> always returns <b>false</b> or <b>true</b>. 1041*572c4311SfengbojiangThe conjunction operator <b>and</b> returns its first argument 1042*572c4311Sfengbojiangif this value is <b>false</b> or <b>nil</b>; 1043*572c4311Sfengbojiangotherwise, <b>and</b> returns its second argument. 1044*572c4311SfengbojiangThe disjunction operator <b>or</b> returns its first argument 1045*572c4311Sfengbojiangif this value is different from <b>nil</b> and <b>false</b>; 1046*572c4311Sfengbojiangotherwise, <b>or</b> returns its second argument. 1047*572c4311SfengbojiangBoth <b>and</b> and <b>or</b> use short-cut evaluation; 1048*572c4311Sfengbojiangthat is, 1049*572c4311Sfengbojiangthe second operand is evaluated only if necessary. 1050*572c4311SfengbojiangHere are some examples: 1051*572c4311Sfengbojiang 1052*572c4311Sfengbojiang<pre> 1053*572c4311Sfengbojiang 10 or 20 --> 10 1054*572c4311Sfengbojiang 10 or error() --> 10 1055*572c4311Sfengbojiang nil or "a" --> "a" 1056*572c4311Sfengbojiang nil and 10 --> nil 1057*572c4311Sfengbojiang false and error() --> false 1058*572c4311Sfengbojiang false and nil --> false 1059*572c4311Sfengbojiang false or nil --> nil 1060*572c4311Sfengbojiang 10 and 20 --> 20 1061*572c4311Sfengbojiang</pre><p> 1062*572c4311Sfengbojiang(In this manual, 1063*572c4311Sfengbojiang<code>--></code> indicates the result of the preceding expression.) 1064*572c4311Sfengbojiang 1065*572c4311Sfengbojiang 1066*572c4311Sfengbojiang 1067*572c4311Sfengbojiang 1068*572c4311Sfengbojiang 1069*572c4311Sfengbojiang<h3>2.5.4 - <a name="2.5.4">Concatenation</a></h3><p> 1070*572c4311SfengbojiangThe string concatenation operator in Lua is 1071*572c4311Sfengbojiangdenoted by two dots ('<code>..</code>'). 1072*572c4311SfengbojiangIf both operands are strings or numbers, then they are converted to 1073*572c4311Sfengbojiangstrings according to the rules mentioned in <a href="#2.2.1">§2.2.1</a>. 1074*572c4311SfengbojiangOtherwise, the "concat" metamethod is called (see <a href="#2.8">§2.8</a>). 1075*572c4311Sfengbojiang 1076*572c4311Sfengbojiang 1077*572c4311Sfengbojiang 1078*572c4311Sfengbojiang 1079*572c4311Sfengbojiang 1080*572c4311Sfengbojiang<h3>2.5.5 - <a name="2.5.5">The Length Operator</a></h3> 1081*572c4311Sfengbojiang 1082*572c4311Sfengbojiang<p> 1083*572c4311SfengbojiangThe length operator is denoted by the unary operator <code>#</code>. 1084*572c4311SfengbojiangThe length of a string is its number of bytes 1085*572c4311Sfengbojiang(that is, the usual meaning of string length when each 1086*572c4311Sfengbojiangcharacter is one byte). 1087*572c4311Sfengbojiang 1088*572c4311Sfengbojiang 1089*572c4311Sfengbojiang<p> 1090*572c4311SfengbojiangThe length of a table <code>t</code> is defined to be any 1091*572c4311Sfengbojianginteger index <code>n</code> 1092*572c4311Sfengbojiangsuch that <code>t[n]</code> is not <b>nil</b> and <code>t[n+1]</code> is <b>nil</b>; 1093*572c4311Sfengbojiangmoreover, if <code>t[1]</code> is <b>nil</b>, <code>n</code> can be zero. 1094*572c4311SfengbojiangFor a regular array, with non-nil values from 1 to a given <code>n</code>, 1095*572c4311Sfengbojiangits length is exactly that <code>n</code>, 1096*572c4311Sfengbojiangthe index of its last value. 1097*572c4311SfengbojiangIf the array has "holes" 1098*572c4311Sfengbojiang(that is, <b>nil</b> values between other non-nil values), 1099*572c4311Sfengbojiangthen <code>#t</code> can be any of the indices that 1100*572c4311Sfengbojiangdirectly precedes a <b>nil</b> value 1101*572c4311Sfengbojiang(that is, it may consider any such <b>nil</b> value as the end of 1102*572c4311Sfengbojiangthe array). 1103*572c4311Sfengbojiang 1104*572c4311Sfengbojiang 1105*572c4311Sfengbojiang 1106*572c4311Sfengbojiang 1107*572c4311Sfengbojiang 1108*572c4311Sfengbojiang<h3>2.5.6 - <a name="2.5.6">Precedence</a></h3><p> 1109*572c4311SfengbojiangOperator precedence in Lua follows the table below, 1110*572c4311Sfengbojiangfrom lower to higher priority: 1111*572c4311Sfengbojiang 1112*572c4311Sfengbojiang<pre> 1113*572c4311Sfengbojiang or 1114*572c4311Sfengbojiang and 1115*572c4311Sfengbojiang < > <= >= ~= == 1116*572c4311Sfengbojiang .. 1117*572c4311Sfengbojiang + - 1118*572c4311Sfengbojiang * / % 1119*572c4311Sfengbojiang not # - (unary) 1120*572c4311Sfengbojiang ^ 1121*572c4311Sfengbojiang</pre><p> 1122*572c4311SfengbojiangAs usual, 1123*572c4311Sfengbojiangyou can use parentheses to change the precedences of an expression. 1124*572c4311SfengbojiangThe concatenation ('<code>..</code>') and exponentiation ('<code>^</code>') 1125*572c4311Sfengbojiangoperators are right associative. 1126*572c4311SfengbojiangAll other binary operators are left associative. 1127*572c4311Sfengbojiang 1128*572c4311Sfengbojiang 1129*572c4311Sfengbojiang 1130*572c4311Sfengbojiang 1131*572c4311Sfengbojiang 1132*572c4311Sfengbojiang<h3>2.5.7 - <a name="2.5.7">Table Constructors</a></h3><p> 1133*572c4311SfengbojiangTable constructors are expressions that create tables. 1134*572c4311SfengbojiangEvery time a constructor is evaluated, a new table is created. 1135*572c4311SfengbojiangA constructor can be used to create an empty table 1136*572c4311Sfengbojiangor to create a table and initialize some of its fields. 1137*572c4311SfengbojiangThe general syntax for constructors is 1138*572c4311Sfengbojiang 1139*572c4311Sfengbojiang<pre> 1140*572c4311Sfengbojiang tableconstructor ::= `<b>{</b>´ [fieldlist] `<b>}</b>´ 1141*572c4311Sfengbojiang fieldlist ::= field {fieldsep field} [fieldsep] 1142*572c4311Sfengbojiang field ::= `<b>[</b>´ exp `<b>]</b>´ `<b>=</b>´ exp | Name `<b>=</b>´ exp | exp 1143*572c4311Sfengbojiang fieldsep ::= `<b>,</b>´ | `<b>;</b>´ 1144*572c4311Sfengbojiang</pre> 1145*572c4311Sfengbojiang 1146*572c4311Sfengbojiang<p> 1147*572c4311SfengbojiangEach field of the form <code>[exp1] = exp2</code> adds to the new table an entry 1148*572c4311Sfengbojiangwith key <code>exp1</code> and value <code>exp2</code>. 1149*572c4311SfengbojiangA field of the form <code>name = exp</code> is equivalent to 1150*572c4311Sfengbojiang<code>["name"] = exp</code>. 1151*572c4311SfengbojiangFinally, fields of the form <code>exp</code> are equivalent to 1152*572c4311Sfengbojiang<code>[i] = exp</code>, where <code>i</code> are consecutive numerical integers, 1153*572c4311Sfengbojiangstarting with 1. 1154*572c4311SfengbojiangFields in the other formats do not affect this counting. 1155*572c4311SfengbojiangFor example, 1156*572c4311Sfengbojiang 1157*572c4311Sfengbojiang<pre> 1158*572c4311Sfengbojiang a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 } 1159*572c4311Sfengbojiang</pre><p> 1160*572c4311Sfengbojiangis equivalent to 1161*572c4311Sfengbojiang 1162*572c4311Sfengbojiang<pre> 1163*572c4311Sfengbojiang do 1164*572c4311Sfengbojiang local t = {} 1165*572c4311Sfengbojiang t[f(1)] = g 1166*572c4311Sfengbojiang t[1] = "x" -- 1st exp 1167*572c4311Sfengbojiang t[2] = "y" -- 2nd exp 1168*572c4311Sfengbojiang t.x = 1 -- t["x"] = 1 1169*572c4311Sfengbojiang t[3] = f(x) -- 3rd exp 1170*572c4311Sfengbojiang t[30] = 23 1171*572c4311Sfengbojiang t[4] = 45 -- 4th exp 1172*572c4311Sfengbojiang a = t 1173*572c4311Sfengbojiang end 1174*572c4311Sfengbojiang</pre> 1175*572c4311Sfengbojiang 1176*572c4311Sfengbojiang<p> 1177*572c4311SfengbojiangIf the last field in the list has the form <code>exp</code> 1178*572c4311Sfengbojiangand the expression is a function call or a vararg expression, 1179*572c4311Sfengbojiangthen all values returned by this expression enter the list consecutively 1180*572c4311Sfengbojiang(see <a href="#2.5.8">§2.5.8</a>). 1181*572c4311SfengbojiangTo avoid this, 1182*572c4311Sfengbojiangenclose the function call or the vararg expression 1183*572c4311Sfengbojiangin parentheses (see <a href="#2.5">§2.5</a>). 1184*572c4311Sfengbojiang 1185*572c4311Sfengbojiang 1186*572c4311Sfengbojiang<p> 1187*572c4311SfengbojiangThe field list can have an optional trailing separator, 1188*572c4311Sfengbojiangas a convenience for machine-generated code. 1189*572c4311Sfengbojiang 1190*572c4311Sfengbojiang 1191*572c4311Sfengbojiang 1192*572c4311Sfengbojiang 1193*572c4311Sfengbojiang 1194*572c4311Sfengbojiang<h3>2.5.8 - <a name="2.5.8">Function Calls</a></h3><p> 1195*572c4311SfengbojiangA function call in Lua has the following syntax: 1196*572c4311Sfengbojiang 1197*572c4311Sfengbojiang<pre> 1198*572c4311Sfengbojiang functioncall ::= prefixexp args 1199*572c4311Sfengbojiang</pre><p> 1200*572c4311SfengbojiangIn a function call, 1201*572c4311Sfengbojiangfirst prefixexp and args are evaluated. 1202*572c4311SfengbojiangIf the value of prefixexp has type <em>function</em>, 1203*572c4311Sfengbojiangthen this function is called 1204*572c4311Sfengbojiangwith the given arguments. 1205*572c4311SfengbojiangOtherwise, the prefixexp "call" metamethod is called, 1206*572c4311Sfengbojianghaving as first parameter the value of prefixexp, 1207*572c4311Sfengbojiangfollowed by the original call arguments 1208*572c4311Sfengbojiang(see <a href="#2.8">§2.8</a>). 1209*572c4311Sfengbojiang 1210*572c4311Sfengbojiang 1211*572c4311Sfengbojiang<p> 1212*572c4311SfengbojiangThe form 1213*572c4311Sfengbojiang 1214*572c4311Sfengbojiang<pre> 1215*572c4311Sfengbojiang functioncall ::= prefixexp `<b>:</b>´ Name args 1216*572c4311Sfengbojiang</pre><p> 1217*572c4311Sfengbojiangcan be used to call "methods". 1218*572c4311SfengbojiangA call <code>v:name(<em>args</em>)</code> 1219*572c4311Sfengbojiangis syntactic sugar for <code>v.name(v,<em>args</em>)</code>, 1220*572c4311Sfengbojiangexcept that <code>v</code> is evaluated only once. 1221*572c4311Sfengbojiang 1222*572c4311Sfengbojiang 1223*572c4311Sfengbojiang<p> 1224*572c4311SfengbojiangArguments have the following syntax: 1225*572c4311Sfengbojiang 1226*572c4311Sfengbojiang<pre> 1227*572c4311Sfengbojiang args ::= `<b>(</b>´ [explist] `<b>)</b>´ 1228*572c4311Sfengbojiang args ::= tableconstructor 1229*572c4311Sfengbojiang args ::= String 1230*572c4311Sfengbojiang</pre><p> 1231*572c4311SfengbojiangAll argument expressions are evaluated before the call. 1232*572c4311SfengbojiangA call of the form <code>f{<em>fields</em>}</code> is 1233*572c4311Sfengbojiangsyntactic sugar for <code>f({<em>fields</em>})</code>; 1234*572c4311Sfengbojiangthat is, the argument list is a single new table. 1235*572c4311SfengbojiangA call of the form <code>f'<em>string</em>'</code> 1236*572c4311Sfengbojiang(or <code>f"<em>string</em>"</code> or <code>f[[<em>string</em>]]</code>) 1237*572c4311Sfengbojiangis syntactic sugar for <code>f('<em>string</em>')</code>; 1238*572c4311Sfengbojiangthat is, the argument list is a single literal string. 1239*572c4311Sfengbojiang 1240*572c4311Sfengbojiang 1241*572c4311Sfengbojiang<p> 1242*572c4311SfengbojiangAs an exception to the free-format syntax of Lua, 1243*572c4311Sfengbojiangyou cannot put a line break before the '<code>(</code>' in a function call. 1244*572c4311SfengbojiangThis restriction avoids some ambiguities in the language. 1245*572c4311SfengbojiangIf you write 1246*572c4311Sfengbojiang 1247*572c4311Sfengbojiang<pre> 1248*572c4311Sfengbojiang a = f 1249*572c4311Sfengbojiang (g).x(a) 1250*572c4311Sfengbojiang</pre><p> 1251*572c4311SfengbojiangLua would see that as a single statement, <code>a = f(g).x(a)</code>. 1252*572c4311SfengbojiangSo, if you want two statements, you must add a semi-colon between them. 1253*572c4311SfengbojiangIf you actually want to call <code>f</code>, 1254*572c4311Sfengbojiangyou must remove the line break before <code>(g)</code>. 1255*572c4311Sfengbojiang 1256*572c4311Sfengbojiang 1257*572c4311Sfengbojiang<p> 1258*572c4311SfengbojiangA call of the form <code>return</code> <em>functioncall</em> is called 1259*572c4311Sfengbojianga <em>tail call</em>. 1260*572c4311SfengbojiangLua implements <em>proper tail calls</em> 1261*572c4311Sfengbojiang(or <em>proper tail recursion</em>): 1262*572c4311Sfengbojiangin a tail call, 1263*572c4311Sfengbojiangthe called function reuses the stack entry of the calling function. 1264*572c4311SfengbojiangTherefore, there is no limit on the number of nested tail calls that 1265*572c4311Sfengbojianga program can execute. 1266*572c4311SfengbojiangHowever, a tail call erases any debug information about the 1267*572c4311Sfengbojiangcalling function. 1268*572c4311SfengbojiangNote that a tail call only happens with a particular syntax, 1269*572c4311Sfengbojiangwhere the <b>return</b> has one single function call as argument; 1270*572c4311Sfengbojiangthis syntax makes the calling function return exactly 1271*572c4311Sfengbojiangthe returns of the called function. 1272*572c4311SfengbojiangSo, none of the following examples are tail calls: 1273*572c4311Sfengbojiang 1274*572c4311Sfengbojiang<pre> 1275*572c4311Sfengbojiang return (f(x)) -- results adjusted to 1 1276*572c4311Sfengbojiang return 2 * f(x) 1277*572c4311Sfengbojiang return x, f(x) -- additional results 1278*572c4311Sfengbojiang f(x); return -- results discarded 1279*572c4311Sfengbojiang return x or f(x) -- results adjusted to 1 1280*572c4311Sfengbojiang</pre> 1281*572c4311Sfengbojiang 1282*572c4311Sfengbojiang 1283*572c4311Sfengbojiang 1284*572c4311Sfengbojiang 1285*572c4311Sfengbojiang<h3>2.5.9 - <a name="2.5.9">Function Definitions</a></h3> 1286*572c4311Sfengbojiang 1287*572c4311Sfengbojiang<p> 1288*572c4311SfengbojiangThe syntax for function definition is 1289*572c4311Sfengbojiang 1290*572c4311Sfengbojiang<pre> 1291*572c4311Sfengbojiang function ::= <b>function</b> funcbody 1292*572c4311Sfengbojiang funcbody ::= `<b>(</b>´ [parlist] `<b>)</b>´ block <b>end</b> 1293*572c4311Sfengbojiang</pre> 1294*572c4311Sfengbojiang 1295*572c4311Sfengbojiang<p> 1296*572c4311SfengbojiangThe following syntactic sugar simplifies function definitions: 1297*572c4311Sfengbojiang 1298*572c4311Sfengbojiang<pre> 1299*572c4311Sfengbojiang stat ::= <b>function</b> funcname funcbody 1300*572c4311Sfengbojiang stat ::= <b>local</b> <b>function</b> Name funcbody 1301*572c4311Sfengbojiang funcname ::= Name {`<b>.</b>´ Name} [`<b>:</b>´ Name] 1302*572c4311Sfengbojiang</pre><p> 1303*572c4311SfengbojiangThe statement 1304*572c4311Sfengbojiang 1305*572c4311Sfengbojiang<pre> 1306*572c4311Sfengbojiang function f () <em>body</em> end 1307*572c4311Sfengbojiang</pre><p> 1308*572c4311Sfengbojiangtranslates to 1309*572c4311Sfengbojiang 1310*572c4311Sfengbojiang<pre> 1311*572c4311Sfengbojiang f = function () <em>body</em> end 1312*572c4311Sfengbojiang</pre><p> 1313*572c4311SfengbojiangThe statement 1314*572c4311Sfengbojiang 1315*572c4311Sfengbojiang<pre> 1316*572c4311Sfengbojiang function t.a.b.c.f () <em>body</em> end 1317*572c4311Sfengbojiang</pre><p> 1318*572c4311Sfengbojiangtranslates to 1319*572c4311Sfengbojiang 1320*572c4311Sfengbojiang<pre> 1321*572c4311Sfengbojiang t.a.b.c.f = function () <em>body</em> end 1322*572c4311Sfengbojiang</pre><p> 1323*572c4311SfengbojiangThe statement 1324*572c4311Sfengbojiang 1325*572c4311Sfengbojiang<pre> 1326*572c4311Sfengbojiang local function f () <em>body</em> end 1327*572c4311Sfengbojiang</pre><p> 1328*572c4311Sfengbojiangtranslates to 1329*572c4311Sfengbojiang 1330*572c4311Sfengbojiang<pre> 1331*572c4311Sfengbojiang local f; f = function () <em>body</em> end 1332*572c4311Sfengbojiang</pre><p> 1333*572c4311Sfengbojiang<em>not</em> to 1334*572c4311Sfengbojiang 1335*572c4311Sfengbojiang<pre> 1336*572c4311Sfengbojiang local f = function () <em>body</em> end 1337*572c4311Sfengbojiang</pre><p> 1338*572c4311Sfengbojiang(This only makes a difference when the body of the function 1339*572c4311Sfengbojiangcontains references to <code>f</code>.) 1340*572c4311Sfengbojiang 1341*572c4311Sfengbojiang 1342*572c4311Sfengbojiang<p> 1343*572c4311SfengbojiangA function definition is an executable expression, 1344*572c4311Sfengbojiangwhose value has type <em>function</em>. 1345*572c4311SfengbojiangWhen Lua pre-compiles a chunk, 1346*572c4311Sfengbojiangall its function bodies are pre-compiled too. 1347*572c4311SfengbojiangThen, whenever Lua executes the function definition, 1348*572c4311Sfengbojiangthe function is <em>instantiated</em> (or <em>closed</em>). 1349*572c4311SfengbojiangThis function instance (or <em>closure</em>) 1350*572c4311Sfengbojiangis the final value of the expression. 1351*572c4311SfengbojiangDifferent instances of the same function 1352*572c4311Sfengbojiangcan refer to different external local variables 1353*572c4311Sfengbojiangand can have different environment tables. 1354*572c4311Sfengbojiang 1355*572c4311Sfengbojiang 1356*572c4311Sfengbojiang<p> 1357*572c4311SfengbojiangParameters act as local variables that are 1358*572c4311Sfengbojianginitialized with the argument values: 1359*572c4311Sfengbojiang 1360*572c4311Sfengbojiang<pre> 1361*572c4311Sfengbojiang parlist ::= namelist [`<b>,</b>´ `<b>...</b>´] | `<b>...</b>´ 1362*572c4311Sfengbojiang</pre><p> 1363*572c4311SfengbojiangWhen a function is called, 1364*572c4311Sfengbojiangthe list of arguments is adjusted to 1365*572c4311Sfengbojiangthe length of the list of parameters, 1366*572c4311Sfengbojiangunless the function is a variadic or <em>vararg function</em>, 1367*572c4311Sfengbojiangwhich is 1368*572c4311Sfengbojiangindicated by three dots ('<code>...</code>') at the end of its parameter list. 1369*572c4311SfengbojiangA vararg function does not adjust its argument list; 1370*572c4311Sfengbojianginstead, it collects all extra arguments and supplies them 1371*572c4311Sfengbojiangto the function through a <em>vararg expression</em>, 1372*572c4311Sfengbojiangwhich is also written as three dots. 1373*572c4311SfengbojiangThe value of this expression is a list of all actual extra arguments, 1374*572c4311Sfengbojiangsimilar to a function with multiple results. 1375*572c4311SfengbojiangIf a vararg expression is used inside another expression 1376*572c4311Sfengbojiangor in the middle of a list of expressions, 1377*572c4311Sfengbojiangthen its return list is adjusted to one element. 1378*572c4311SfengbojiangIf the expression is used as the last element of a list of expressions, 1379*572c4311Sfengbojiangthen no adjustment is made 1380*572c4311Sfengbojiang(unless that last expression is enclosed in parentheses). 1381*572c4311Sfengbojiang 1382*572c4311Sfengbojiang 1383*572c4311Sfengbojiang<p> 1384*572c4311SfengbojiangAs an example, consider the following definitions: 1385*572c4311Sfengbojiang 1386*572c4311Sfengbojiang<pre> 1387*572c4311Sfengbojiang function f(a, b) end 1388*572c4311Sfengbojiang function g(a, b, ...) end 1389*572c4311Sfengbojiang function r() return 1,2,3 end 1390*572c4311Sfengbojiang</pre><p> 1391*572c4311SfengbojiangThen, we have the following mapping from arguments to parameters and 1392*572c4311Sfengbojiangto the vararg expression: 1393*572c4311Sfengbojiang 1394*572c4311Sfengbojiang<pre> 1395*572c4311Sfengbojiang CALL PARAMETERS 1396*572c4311Sfengbojiang 1397*572c4311Sfengbojiang f(3) a=3, b=nil 1398*572c4311Sfengbojiang f(3, 4) a=3, b=4 1399*572c4311Sfengbojiang f(3, 4, 5) a=3, b=4 1400*572c4311Sfengbojiang f(r(), 10) a=1, b=10 1401*572c4311Sfengbojiang f(r()) a=1, b=2 1402*572c4311Sfengbojiang 1403*572c4311Sfengbojiang g(3) a=3, b=nil, ... --> (nothing) 1404*572c4311Sfengbojiang g(3, 4) a=3, b=4, ... --> (nothing) 1405*572c4311Sfengbojiang g(3, 4, 5, 8) a=3, b=4, ... --> 5 8 1406*572c4311Sfengbojiang g(5, r()) a=5, b=1, ... --> 2 3 1407*572c4311Sfengbojiang</pre> 1408*572c4311Sfengbojiang 1409*572c4311Sfengbojiang<p> 1410*572c4311SfengbojiangResults are returned using the <b>return</b> statement (see <a href="#2.4.4">§2.4.4</a>). 1411*572c4311SfengbojiangIf control reaches the end of a function 1412*572c4311Sfengbojiangwithout encountering a <b>return</b> statement, 1413*572c4311Sfengbojiangthen the function returns with no results. 1414*572c4311Sfengbojiang 1415*572c4311Sfengbojiang 1416*572c4311Sfengbojiang<p> 1417*572c4311SfengbojiangThe <em>colon</em> syntax 1418*572c4311Sfengbojiangis used for defining <em>methods</em>, 1419*572c4311Sfengbojiangthat is, functions that have an implicit extra parameter <code>self</code>. 1420*572c4311SfengbojiangThus, the statement 1421*572c4311Sfengbojiang 1422*572c4311Sfengbojiang<pre> 1423*572c4311Sfengbojiang function t.a.b.c:f (<em>params</em>) <em>body</em> end 1424*572c4311Sfengbojiang</pre><p> 1425*572c4311Sfengbojiangis syntactic sugar for 1426*572c4311Sfengbojiang 1427*572c4311Sfengbojiang<pre> 1428*572c4311Sfengbojiang t.a.b.c.f = function (self, <em>params</em>) <em>body</em> end 1429*572c4311Sfengbojiang</pre> 1430*572c4311Sfengbojiang 1431*572c4311Sfengbojiang 1432*572c4311Sfengbojiang 1433*572c4311Sfengbojiang 1434*572c4311Sfengbojiang 1435*572c4311Sfengbojiang 1436*572c4311Sfengbojiang<h2>2.6 - <a name="2.6">Visibility Rules</a></h2> 1437*572c4311Sfengbojiang 1438*572c4311Sfengbojiang<p> 1439*572c4311Sfengbojiang 1440*572c4311SfengbojiangLua is a lexically scoped language. 1441*572c4311SfengbojiangThe scope of variables begins at the first statement <em>after</em> 1442*572c4311Sfengbojiangtheir declaration and lasts until the end of the innermost block that 1443*572c4311Sfengbojiangincludes the declaration. 1444*572c4311SfengbojiangConsider the following example: 1445*572c4311Sfengbojiang 1446*572c4311Sfengbojiang<pre> 1447*572c4311Sfengbojiang x = 10 -- global variable 1448*572c4311Sfengbojiang do -- new block 1449*572c4311Sfengbojiang local x = x -- new 'x', with value 10 1450*572c4311Sfengbojiang print(x) --> 10 1451*572c4311Sfengbojiang x = x+1 1452*572c4311Sfengbojiang do -- another block 1453*572c4311Sfengbojiang local x = x+1 -- another 'x' 1454*572c4311Sfengbojiang print(x) --> 12 1455*572c4311Sfengbojiang end 1456*572c4311Sfengbojiang print(x) --> 11 1457*572c4311Sfengbojiang end 1458*572c4311Sfengbojiang print(x) --> 10 (the global one) 1459*572c4311Sfengbojiang</pre> 1460*572c4311Sfengbojiang 1461*572c4311Sfengbojiang<p> 1462*572c4311SfengbojiangNotice that, in a declaration like <code>local x = x</code>, 1463*572c4311Sfengbojiangthe new <code>x</code> being declared is not in scope yet, 1464*572c4311Sfengbojiangand so the second <code>x</code> refers to the outside variable. 1465*572c4311Sfengbojiang 1466*572c4311Sfengbojiang 1467*572c4311Sfengbojiang<p> 1468*572c4311SfengbojiangBecause of the lexical scoping rules, 1469*572c4311Sfengbojianglocal variables can be freely accessed by functions 1470*572c4311Sfengbojiangdefined inside their scope. 1471*572c4311SfengbojiangA local variable used by an inner function is called 1472*572c4311Sfengbojiangan <em>upvalue</em>, or <em>external local variable</em>, 1473*572c4311Sfengbojianginside the inner function. 1474*572c4311Sfengbojiang 1475*572c4311Sfengbojiang 1476*572c4311Sfengbojiang<p> 1477*572c4311SfengbojiangNotice that each execution of a <b>local</b> statement 1478*572c4311Sfengbojiangdefines new local variables. 1479*572c4311SfengbojiangConsider the following example: 1480*572c4311Sfengbojiang 1481*572c4311Sfengbojiang<pre> 1482*572c4311Sfengbojiang a = {} 1483*572c4311Sfengbojiang local x = 20 1484*572c4311Sfengbojiang for i=1,10 do 1485*572c4311Sfengbojiang local y = 0 1486*572c4311Sfengbojiang a[i] = function () y=y+1; return x+y end 1487*572c4311Sfengbojiang end 1488*572c4311Sfengbojiang</pre><p> 1489*572c4311SfengbojiangThe loop creates ten closures 1490*572c4311Sfengbojiang(that is, ten instances of the anonymous function). 1491*572c4311SfengbojiangEach of these closures uses a different <code>y</code> variable, 1492*572c4311Sfengbojiangwhile all of them share the same <code>x</code>. 1493*572c4311Sfengbojiang 1494*572c4311Sfengbojiang 1495*572c4311Sfengbojiang 1496*572c4311Sfengbojiang 1497*572c4311Sfengbojiang 1498*572c4311Sfengbojiang<h2>2.7 - <a name="2.7">Error Handling</a></h2> 1499*572c4311Sfengbojiang 1500*572c4311Sfengbojiang<p> 1501*572c4311SfengbojiangBecause Lua is an embedded extension language, 1502*572c4311Sfengbojiangall Lua actions start from C code in the host program 1503*572c4311Sfengbojiangcalling a function from the Lua library (see <a href="#lua_pcall"><code>lua_pcall</code></a>). 1504*572c4311SfengbojiangWhenever an error occurs during Lua compilation or execution, 1505*572c4311Sfengbojiangcontrol returns to C, 1506*572c4311Sfengbojiangwhich can take appropriate measures 1507*572c4311Sfengbojiang(such as printing an error message). 1508*572c4311Sfengbojiang 1509*572c4311Sfengbojiang 1510*572c4311Sfengbojiang<p> 1511*572c4311SfengbojiangLua code can explicitly generate an error by calling the 1512*572c4311Sfengbojiang<a href="#pdf-error"><code>error</code></a> function. 1513*572c4311SfengbojiangIf you need to catch errors in Lua, 1514*572c4311Sfengbojiangyou can use the <a href="#pdf-pcall"><code>pcall</code></a> function. 1515*572c4311Sfengbojiang 1516*572c4311Sfengbojiang 1517*572c4311Sfengbojiang 1518*572c4311Sfengbojiang 1519*572c4311Sfengbojiang 1520*572c4311Sfengbojiang<h2>2.8 - <a name="2.8">Metatables</a></h2> 1521*572c4311Sfengbojiang 1522*572c4311Sfengbojiang<p> 1523*572c4311SfengbojiangEvery value in Lua can have a <em>metatable</em>. 1524*572c4311SfengbojiangThis <em>metatable</em> is an ordinary Lua table 1525*572c4311Sfengbojiangthat defines the behavior of the original value 1526*572c4311Sfengbojiangunder certain special operations. 1527*572c4311SfengbojiangYou can change several aspects of the behavior 1528*572c4311Sfengbojiangof operations over a value by setting specific fields in its metatable. 1529*572c4311SfengbojiangFor instance, when a non-numeric value is the operand of an addition, 1530*572c4311SfengbojiangLua checks for a function in the field <code>"__add"</code> in its metatable. 1531*572c4311SfengbojiangIf it finds one, 1532*572c4311SfengbojiangLua calls this function to perform the addition. 1533*572c4311Sfengbojiang 1534*572c4311Sfengbojiang 1535*572c4311Sfengbojiang<p> 1536*572c4311SfengbojiangWe call the keys in a metatable <em>events</em> 1537*572c4311Sfengbojiangand the values <em>metamethods</em>. 1538*572c4311SfengbojiangIn the previous example, the event is <code>"add"</code> 1539*572c4311Sfengbojiangand the metamethod is the function that performs the addition. 1540*572c4311Sfengbojiang 1541*572c4311Sfengbojiang 1542*572c4311Sfengbojiang<p> 1543*572c4311SfengbojiangYou can query the metatable of any value 1544*572c4311Sfengbojiangthrough the <a href="#pdf-getmetatable"><code>getmetatable</code></a> function. 1545*572c4311Sfengbojiang 1546*572c4311Sfengbojiang 1547*572c4311Sfengbojiang<p> 1548*572c4311SfengbojiangYou can replace the metatable of tables 1549*572c4311Sfengbojiangthrough the <a href="#pdf-setmetatable"><code>setmetatable</code></a> 1550*572c4311Sfengbojiangfunction. 1551*572c4311SfengbojiangYou cannot change the metatable of other types from Lua 1552*572c4311Sfengbojiang(except by using the debug library); 1553*572c4311Sfengbojiangyou must use the C API for that. 1554*572c4311Sfengbojiang 1555*572c4311Sfengbojiang 1556*572c4311Sfengbojiang<p> 1557*572c4311SfengbojiangTables and full userdata have individual metatables 1558*572c4311Sfengbojiang(although multiple tables and userdata can share their metatables). 1559*572c4311SfengbojiangValues of all other types share one single metatable per type; 1560*572c4311Sfengbojiangthat is, there is one single metatable for all numbers, 1561*572c4311Sfengbojiangone for all strings, etc. 1562*572c4311Sfengbojiang 1563*572c4311Sfengbojiang 1564*572c4311Sfengbojiang<p> 1565*572c4311SfengbojiangA metatable controls how an object behaves in arithmetic operations, 1566*572c4311Sfengbojiangorder comparisons, concatenation, length operation, and indexing. 1567*572c4311SfengbojiangA metatable also can define a function to be called when a userdata 1568*572c4311Sfengbojiangis garbage collected. 1569*572c4311SfengbojiangFor each of these operations Lua associates a specific key 1570*572c4311Sfengbojiangcalled an <em>event</em>. 1571*572c4311SfengbojiangWhen Lua performs one of these operations over a value, 1572*572c4311Sfengbojiangit checks whether this value has a metatable with the corresponding event. 1573*572c4311SfengbojiangIf so, the value associated with that key (the metamethod) 1574*572c4311Sfengbojiangcontrols how Lua will perform the operation. 1575*572c4311Sfengbojiang 1576*572c4311Sfengbojiang 1577*572c4311Sfengbojiang<p> 1578*572c4311SfengbojiangMetatables control the operations listed next. 1579*572c4311SfengbojiangEach operation is identified by its corresponding name. 1580*572c4311SfengbojiangThe key for each operation is a string with its name prefixed by 1581*572c4311Sfengbojiangtwo underscores, '<code>__</code>'; 1582*572c4311Sfengbojiangfor instance, the key for operation "add" is the 1583*572c4311Sfengbojiangstring <code>"__add"</code>. 1584*572c4311SfengbojiangThe semantics of these operations is better explained by a Lua function 1585*572c4311Sfengbojiangdescribing how the interpreter executes the operation. 1586*572c4311Sfengbojiang 1587*572c4311Sfengbojiang 1588*572c4311Sfengbojiang<p> 1589*572c4311SfengbojiangThe code shown here in Lua is only illustrative; 1590*572c4311Sfengbojiangthe real behavior is hard coded in the interpreter 1591*572c4311Sfengbojiangand it is much more efficient than this simulation. 1592*572c4311SfengbojiangAll functions used in these descriptions 1593*572c4311Sfengbojiang(<a href="#pdf-rawget"><code>rawget</code></a>, <a href="#pdf-tonumber"><code>tonumber</code></a>, etc.) 1594*572c4311Sfengbojiangare described in <a href="#5.1">§5.1</a>. 1595*572c4311SfengbojiangIn particular, to retrieve the metamethod of a given object, 1596*572c4311Sfengbojiangwe use the expression 1597*572c4311Sfengbojiang 1598*572c4311Sfengbojiang<pre> 1599*572c4311Sfengbojiang metatable(obj)[event] 1600*572c4311Sfengbojiang</pre><p> 1601*572c4311SfengbojiangThis should be read as 1602*572c4311Sfengbojiang 1603*572c4311Sfengbojiang<pre> 1604*572c4311Sfengbojiang rawget(getmetatable(obj) or {}, event) 1605*572c4311Sfengbojiang</pre><p> 1606*572c4311Sfengbojiang 1607*572c4311SfengbojiangThat is, the access to a metamethod does not invoke other metamethods, 1608*572c4311Sfengbojiangand the access to objects with no metatables does not fail 1609*572c4311Sfengbojiang(it simply results in <b>nil</b>). 1610*572c4311Sfengbojiang 1611*572c4311Sfengbojiang 1612*572c4311Sfengbojiang 1613*572c4311Sfengbojiang<ul> 1614*572c4311Sfengbojiang 1615*572c4311Sfengbojiang<li><b>"add":</b> 1616*572c4311Sfengbojiangthe <code>+</code> operation. 1617*572c4311Sfengbojiang 1618*572c4311Sfengbojiang 1619*572c4311Sfengbojiang 1620*572c4311Sfengbojiang<p> 1621*572c4311SfengbojiangThe function <code>getbinhandler</code> below defines how Lua chooses a handler 1622*572c4311Sfengbojiangfor a binary operation. 1623*572c4311SfengbojiangFirst, Lua tries the first operand. 1624*572c4311SfengbojiangIf its type does not define a handler for the operation, 1625*572c4311Sfengbojiangthen Lua tries the second operand. 1626*572c4311Sfengbojiang 1627*572c4311Sfengbojiang<pre> 1628*572c4311Sfengbojiang function getbinhandler (op1, op2, event) 1629*572c4311Sfengbojiang return metatable(op1)[event] or metatable(op2)[event] 1630*572c4311Sfengbojiang end 1631*572c4311Sfengbojiang</pre><p> 1632*572c4311SfengbojiangBy using this function, 1633*572c4311Sfengbojiangthe behavior of the <code>op1 + op2</code> is 1634*572c4311Sfengbojiang 1635*572c4311Sfengbojiang<pre> 1636*572c4311Sfengbojiang function add_event (op1, op2) 1637*572c4311Sfengbojiang local o1, o2 = tonumber(op1), tonumber(op2) 1638*572c4311Sfengbojiang if o1 and o2 then -- both operands are numeric? 1639*572c4311Sfengbojiang return o1 + o2 -- '+' here is the primitive 'add' 1640*572c4311Sfengbojiang else -- at least one of the operands is not numeric 1641*572c4311Sfengbojiang local h = getbinhandler(op1, op2, "__add") 1642*572c4311Sfengbojiang if h then 1643*572c4311Sfengbojiang -- call the handler with both operands 1644*572c4311Sfengbojiang return (h(op1, op2)) 1645*572c4311Sfengbojiang else -- no handler available: default behavior 1646*572c4311Sfengbojiang error(···) 1647*572c4311Sfengbojiang end 1648*572c4311Sfengbojiang end 1649*572c4311Sfengbojiang end 1650*572c4311Sfengbojiang</pre><p> 1651*572c4311Sfengbojiang</li> 1652*572c4311Sfengbojiang 1653*572c4311Sfengbojiang<li><b>"sub":</b> 1654*572c4311Sfengbojiangthe <code>-</code> operation. 1655*572c4311Sfengbojiang 1656*572c4311SfengbojiangBehavior similar to the "add" operation. 1657*572c4311Sfengbojiang</li> 1658*572c4311Sfengbojiang 1659*572c4311Sfengbojiang<li><b>"mul":</b> 1660*572c4311Sfengbojiangthe <code>*</code> operation. 1661*572c4311Sfengbojiang 1662*572c4311SfengbojiangBehavior similar to the "add" operation. 1663*572c4311Sfengbojiang</li> 1664*572c4311Sfengbojiang 1665*572c4311Sfengbojiang<li><b>"div":</b> 1666*572c4311Sfengbojiangthe <code>/</code> operation. 1667*572c4311Sfengbojiang 1668*572c4311SfengbojiangBehavior similar to the "add" operation. 1669*572c4311Sfengbojiang</li> 1670*572c4311Sfengbojiang 1671*572c4311Sfengbojiang<li><b>"mod":</b> 1672*572c4311Sfengbojiangthe <code>%</code> operation. 1673*572c4311Sfengbojiang 1674*572c4311SfengbojiangBehavior similar to the "add" operation, 1675*572c4311Sfengbojiangwith the operation 1676*572c4311Sfengbojiang<code>o1 - floor(o1/o2)*o2</code> as the primitive operation. 1677*572c4311Sfengbojiang</li> 1678*572c4311Sfengbojiang 1679*572c4311Sfengbojiang<li><b>"pow":</b> 1680*572c4311Sfengbojiangthe <code>^</code> (exponentiation) operation. 1681*572c4311Sfengbojiang 1682*572c4311SfengbojiangBehavior similar to the "add" operation, 1683*572c4311Sfengbojiangwith the function <code>pow</code> (from the C math library) 1684*572c4311Sfengbojiangas the primitive operation. 1685*572c4311Sfengbojiang</li> 1686*572c4311Sfengbojiang 1687*572c4311Sfengbojiang<li><b>"unm":</b> 1688*572c4311Sfengbojiangthe unary <code>-</code> operation. 1689*572c4311Sfengbojiang 1690*572c4311Sfengbojiang 1691*572c4311Sfengbojiang<pre> 1692*572c4311Sfengbojiang function unm_event (op) 1693*572c4311Sfengbojiang local o = tonumber(op) 1694*572c4311Sfengbojiang if o then -- operand is numeric? 1695*572c4311Sfengbojiang return -o -- '-' here is the primitive 'unm' 1696*572c4311Sfengbojiang else -- the operand is not numeric. 1697*572c4311Sfengbojiang -- Try to get a handler from the operand 1698*572c4311Sfengbojiang local h = metatable(op).__unm 1699*572c4311Sfengbojiang if h then 1700*572c4311Sfengbojiang -- call the handler with the operand 1701*572c4311Sfengbojiang return (h(op)) 1702*572c4311Sfengbojiang else -- no handler available: default behavior 1703*572c4311Sfengbojiang error(···) 1704*572c4311Sfengbojiang end 1705*572c4311Sfengbojiang end 1706*572c4311Sfengbojiang end 1707*572c4311Sfengbojiang</pre><p> 1708*572c4311Sfengbojiang</li> 1709*572c4311Sfengbojiang 1710*572c4311Sfengbojiang<li><b>"concat":</b> 1711*572c4311Sfengbojiangthe <code>..</code> (concatenation) operation. 1712*572c4311Sfengbojiang 1713*572c4311Sfengbojiang 1714*572c4311Sfengbojiang<pre> 1715*572c4311Sfengbojiang function concat_event (op1, op2) 1716*572c4311Sfengbojiang if (type(op1) == "string" or type(op1) == "number") and 1717*572c4311Sfengbojiang (type(op2) == "string" or type(op2) == "number") then 1718*572c4311Sfengbojiang return op1 .. op2 -- primitive string concatenation 1719*572c4311Sfengbojiang else 1720*572c4311Sfengbojiang local h = getbinhandler(op1, op2, "__concat") 1721*572c4311Sfengbojiang if h then 1722*572c4311Sfengbojiang return (h(op1, op2)) 1723*572c4311Sfengbojiang else 1724*572c4311Sfengbojiang error(···) 1725*572c4311Sfengbojiang end 1726*572c4311Sfengbojiang end 1727*572c4311Sfengbojiang end 1728*572c4311Sfengbojiang</pre><p> 1729*572c4311Sfengbojiang</li> 1730*572c4311Sfengbojiang 1731*572c4311Sfengbojiang<li><b>"len":</b> 1732*572c4311Sfengbojiangthe <code>#</code> operation. 1733*572c4311Sfengbojiang 1734*572c4311Sfengbojiang 1735*572c4311Sfengbojiang<pre> 1736*572c4311Sfengbojiang function len_event (op) 1737*572c4311Sfengbojiang if type(op) == "string" then 1738*572c4311Sfengbojiang return strlen(op) -- primitive string length 1739*572c4311Sfengbojiang elseif type(op) == "table" then 1740*572c4311Sfengbojiang return #op -- primitive table length 1741*572c4311Sfengbojiang else 1742*572c4311Sfengbojiang local h = metatable(op).__len 1743*572c4311Sfengbojiang if h then 1744*572c4311Sfengbojiang -- call the handler with the operand 1745*572c4311Sfengbojiang return (h(op)) 1746*572c4311Sfengbojiang else -- no handler available: default behavior 1747*572c4311Sfengbojiang error(···) 1748*572c4311Sfengbojiang end 1749*572c4311Sfengbojiang end 1750*572c4311Sfengbojiang end 1751*572c4311Sfengbojiang</pre><p> 1752*572c4311SfengbojiangSee <a href="#2.5.5">§2.5.5</a> for a description of the length of a table. 1753*572c4311Sfengbojiang</li> 1754*572c4311Sfengbojiang 1755*572c4311Sfengbojiang<li><b>"eq":</b> 1756*572c4311Sfengbojiangthe <code>==</code> operation. 1757*572c4311Sfengbojiang 1758*572c4311SfengbojiangThe function <code>getcomphandler</code> defines how Lua chooses a metamethod 1759*572c4311Sfengbojiangfor comparison operators. 1760*572c4311SfengbojiangA metamethod only is selected when both objects 1761*572c4311Sfengbojiangbeing compared have the same type 1762*572c4311Sfengbojiangand the same metamethod for the selected operation. 1763*572c4311Sfengbojiang 1764*572c4311Sfengbojiang<pre> 1765*572c4311Sfengbojiang function getcomphandler (op1, op2, event) 1766*572c4311Sfengbojiang if type(op1) ~= type(op2) then return nil end 1767*572c4311Sfengbojiang local mm1 = metatable(op1)[event] 1768*572c4311Sfengbojiang local mm2 = metatable(op2)[event] 1769*572c4311Sfengbojiang if mm1 == mm2 then return mm1 else return nil end 1770*572c4311Sfengbojiang end 1771*572c4311Sfengbojiang</pre><p> 1772*572c4311SfengbojiangThe "eq" event is defined as follows: 1773*572c4311Sfengbojiang 1774*572c4311Sfengbojiang<pre> 1775*572c4311Sfengbojiang function eq_event (op1, op2) 1776*572c4311Sfengbojiang if type(op1) ~= type(op2) then -- different types? 1777*572c4311Sfengbojiang return false -- different objects 1778*572c4311Sfengbojiang end 1779*572c4311Sfengbojiang if op1 == op2 then -- primitive equal? 1780*572c4311Sfengbojiang return true -- objects are equal 1781*572c4311Sfengbojiang end 1782*572c4311Sfengbojiang -- try metamethod 1783*572c4311Sfengbojiang local h = getcomphandler(op1, op2, "__eq") 1784*572c4311Sfengbojiang if h then 1785*572c4311Sfengbojiang return (h(op1, op2)) 1786*572c4311Sfengbojiang else 1787*572c4311Sfengbojiang return false 1788*572c4311Sfengbojiang end 1789*572c4311Sfengbojiang end 1790*572c4311Sfengbojiang</pre><p> 1791*572c4311Sfengbojiang<code>a ~= b</code> is equivalent to <code>not (a == b)</code>. 1792*572c4311Sfengbojiang</li> 1793*572c4311Sfengbojiang 1794*572c4311Sfengbojiang<li><b>"lt":</b> 1795*572c4311Sfengbojiangthe <code><</code> operation. 1796*572c4311Sfengbojiang 1797*572c4311Sfengbojiang 1798*572c4311Sfengbojiang<pre> 1799*572c4311Sfengbojiang function lt_event (op1, op2) 1800*572c4311Sfengbojiang if type(op1) == "number" and type(op2) == "number" then 1801*572c4311Sfengbojiang return op1 < op2 -- numeric comparison 1802*572c4311Sfengbojiang elseif type(op1) == "string" and type(op2) == "string" then 1803*572c4311Sfengbojiang return op1 < op2 -- lexicographic comparison 1804*572c4311Sfengbojiang else 1805*572c4311Sfengbojiang local h = getcomphandler(op1, op2, "__lt") 1806*572c4311Sfengbojiang if h then 1807*572c4311Sfengbojiang return (h(op1, op2)) 1808*572c4311Sfengbojiang else 1809*572c4311Sfengbojiang error(···) 1810*572c4311Sfengbojiang end 1811*572c4311Sfengbojiang end 1812*572c4311Sfengbojiang end 1813*572c4311Sfengbojiang</pre><p> 1814*572c4311Sfengbojiang<code>a > b</code> is equivalent to <code>b < a</code>. 1815*572c4311Sfengbojiang</li> 1816*572c4311Sfengbojiang 1817*572c4311Sfengbojiang<li><b>"le":</b> 1818*572c4311Sfengbojiangthe <code><=</code> operation. 1819*572c4311Sfengbojiang 1820*572c4311Sfengbojiang 1821*572c4311Sfengbojiang<pre> 1822*572c4311Sfengbojiang function le_event (op1, op2) 1823*572c4311Sfengbojiang if type(op1) == "number" and type(op2) == "number" then 1824*572c4311Sfengbojiang return op1 <= op2 -- numeric comparison 1825*572c4311Sfengbojiang elseif type(op1) == "string" and type(op2) == "string" then 1826*572c4311Sfengbojiang return op1 <= op2 -- lexicographic comparison 1827*572c4311Sfengbojiang else 1828*572c4311Sfengbojiang local h = getcomphandler(op1, op2, "__le") 1829*572c4311Sfengbojiang if h then 1830*572c4311Sfengbojiang return (h(op1, op2)) 1831*572c4311Sfengbojiang else 1832*572c4311Sfengbojiang h = getcomphandler(op1, op2, "__lt") 1833*572c4311Sfengbojiang if h then 1834*572c4311Sfengbojiang return not h(op2, op1) 1835*572c4311Sfengbojiang else 1836*572c4311Sfengbojiang error(···) 1837*572c4311Sfengbojiang end 1838*572c4311Sfengbojiang end 1839*572c4311Sfengbojiang end 1840*572c4311Sfengbojiang end 1841*572c4311Sfengbojiang</pre><p> 1842*572c4311Sfengbojiang<code>a >= b</code> is equivalent to <code>b <= a</code>. 1843*572c4311SfengbojiangNote that, in the absence of a "le" metamethod, 1844*572c4311SfengbojiangLua tries the "lt", assuming that <code>a <= b</code> is 1845*572c4311Sfengbojiangequivalent to <code>not (b < a)</code>. 1846*572c4311Sfengbojiang</li> 1847*572c4311Sfengbojiang 1848*572c4311Sfengbojiang<li><b>"index":</b> 1849*572c4311SfengbojiangThe indexing access <code>table[key]</code>. 1850*572c4311Sfengbojiang 1851*572c4311Sfengbojiang 1852*572c4311Sfengbojiang<pre> 1853*572c4311Sfengbojiang function gettable_event (table, key) 1854*572c4311Sfengbojiang local h 1855*572c4311Sfengbojiang if type(table) == "table" then 1856*572c4311Sfengbojiang local v = rawget(table, key) 1857*572c4311Sfengbojiang if v ~= nil then return v end 1858*572c4311Sfengbojiang h = metatable(table).__index 1859*572c4311Sfengbojiang if h == nil then return nil end 1860*572c4311Sfengbojiang else 1861*572c4311Sfengbojiang h = metatable(table).__index 1862*572c4311Sfengbojiang if h == nil then 1863*572c4311Sfengbojiang error(···) 1864*572c4311Sfengbojiang end 1865*572c4311Sfengbojiang end 1866*572c4311Sfengbojiang if type(h) == "function" then 1867*572c4311Sfengbojiang return (h(table, key)) -- call the handler 1868*572c4311Sfengbojiang else return h[key] -- or repeat operation on it 1869*572c4311Sfengbojiang end 1870*572c4311Sfengbojiang end 1871*572c4311Sfengbojiang</pre><p> 1872*572c4311Sfengbojiang</li> 1873*572c4311Sfengbojiang 1874*572c4311Sfengbojiang<li><b>"newindex":</b> 1875*572c4311SfengbojiangThe indexing assignment <code>table[key] = value</code>. 1876*572c4311Sfengbojiang 1877*572c4311Sfengbojiang 1878*572c4311Sfengbojiang<pre> 1879*572c4311Sfengbojiang function settable_event (table, key, value) 1880*572c4311Sfengbojiang local h 1881*572c4311Sfengbojiang if type(table) == "table" then 1882*572c4311Sfengbojiang local v = rawget(table, key) 1883*572c4311Sfengbojiang if v ~= nil then rawset(table, key, value); return end 1884*572c4311Sfengbojiang h = metatable(table).__newindex 1885*572c4311Sfengbojiang if h == nil then rawset(table, key, value); return end 1886*572c4311Sfengbojiang else 1887*572c4311Sfengbojiang h = metatable(table).__newindex 1888*572c4311Sfengbojiang if h == nil then 1889*572c4311Sfengbojiang error(···) 1890*572c4311Sfengbojiang end 1891*572c4311Sfengbojiang end 1892*572c4311Sfengbojiang if type(h) == "function" then 1893*572c4311Sfengbojiang h(table, key,value) -- call the handler 1894*572c4311Sfengbojiang else h[key] = value -- or repeat operation on it 1895*572c4311Sfengbojiang end 1896*572c4311Sfengbojiang end 1897*572c4311Sfengbojiang</pre><p> 1898*572c4311Sfengbojiang</li> 1899*572c4311Sfengbojiang 1900*572c4311Sfengbojiang<li><b>"call":</b> 1901*572c4311Sfengbojiangcalled when Lua calls a value. 1902*572c4311Sfengbojiang 1903*572c4311Sfengbojiang 1904*572c4311Sfengbojiang<pre> 1905*572c4311Sfengbojiang function function_event (func, ...) 1906*572c4311Sfengbojiang if type(func) == "function" then 1907*572c4311Sfengbojiang return func(...) -- primitive call 1908*572c4311Sfengbojiang else 1909*572c4311Sfengbojiang local h = metatable(func).__call 1910*572c4311Sfengbojiang if h then 1911*572c4311Sfengbojiang return h(func, ...) 1912*572c4311Sfengbojiang else 1913*572c4311Sfengbojiang error(···) 1914*572c4311Sfengbojiang end 1915*572c4311Sfengbojiang end 1916*572c4311Sfengbojiang end 1917*572c4311Sfengbojiang</pre><p> 1918*572c4311Sfengbojiang</li> 1919*572c4311Sfengbojiang 1920*572c4311Sfengbojiang</ul> 1921*572c4311Sfengbojiang 1922*572c4311Sfengbojiang 1923*572c4311Sfengbojiang 1924*572c4311Sfengbojiang 1925*572c4311Sfengbojiang<h2>2.9 - <a name="2.9">Environments</a></h2> 1926*572c4311Sfengbojiang 1927*572c4311Sfengbojiang<p> 1928*572c4311SfengbojiangBesides metatables, 1929*572c4311Sfengbojiangobjects of types thread, function, and userdata 1930*572c4311Sfengbojianghave another table associated with them, 1931*572c4311Sfengbojiangcalled their <em>environment</em>. 1932*572c4311SfengbojiangLike metatables, environments are regular tables and 1933*572c4311Sfengbojiangmultiple objects can share the same environment. 1934*572c4311Sfengbojiang 1935*572c4311Sfengbojiang 1936*572c4311Sfengbojiang<p> 1937*572c4311SfengbojiangThreads are created sharing the environment of the creating thread. 1938*572c4311SfengbojiangUserdata and C functions are created sharing the environment 1939*572c4311Sfengbojiangof the creating C function. 1940*572c4311SfengbojiangNon-nested Lua functions 1941*572c4311Sfengbojiang(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>) 1942*572c4311Sfengbojiangare created sharing the environment of the creating thread. 1943*572c4311SfengbojiangNested Lua functions are created sharing the environment of 1944*572c4311Sfengbojiangthe creating Lua function. 1945*572c4311Sfengbojiang 1946*572c4311Sfengbojiang 1947*572c4311Sfengbojiang<p> 1948*572c4311SfengbojiangEnvironments associated with userdata have no meaning for Lua. 1949*572c4311SfengbojiangIt is only a convenience feature for programmers to associate a table to 1950*572c4311Sfengbojianga userdata. 1951*572c4311Sfengbojiang 1952*572c4311Sfengbojiang 1953*572c4311Sfengbojiang<p> 1954*572c4311SfengbojiangEnvironments associated with threads are called 1955*572c4311Sfengbojiang<em>global environments</em>. 1956*572c4311SfengbojiangThey are used as the default environment for threads and 1957*572c4311Sfengbojiangnon-nested Lua functions created by the thread 1958*572c4311Sfengbojiangand can be directly accessed by C code (see <a href="#3.3">§3.3</a>). 1959*572c4311Sfengbojiang 1960*572c4311Sfengbojiang 1961*572c4311Sfengbojiang<p> 1962*572c4311SfengbojiangThe environment associated with a C function can be directly 1963*572c4311Sfengbojiangaccessed by C code (see <a href="#3.3">§3.3</a>). 1964*572c4311SfengbojiangIt is used as the default environment for other C functions 1965*572c4311Sfengbojiangand userdata created by the function. 1966*572c4311Sfengbojiang 1967*572c4311Sfengbojiang 1968*572c4311Sfengbojiang<p> 1969*572c4311SfengbojiangEnvironments associated with Lua functions are used to resolve 1970*572c4311Sfengbojiangall accesses to global variables within the function (see <a href="#2.3">§2.3</a>). 1971*572c4311SfengbojiangThey are used as the default environment for nested Lua functions 1972*572c4311Sfengbojiangcreated by the function. 1973*572c4311Sfengbojiang 1974*572c4311Sfengbojiang 1975*572c4311Sfengbojiang<p> 1976*572c4311SfengbojiangYou can change the environment of a Lua function or the 1977*572c4311Sfengbojiangrunning thread by calling <a href="#pdf-setfenv"><code>setfenv</code></a>. 1978*572c4311SfengbojiangYou can get the environment of a Lua function or the running thread 1979*572c4311Sfengbojiangby calling <a href="#pdf-getfenv"><code>getfenv</code></a>. 1980*572c4311SfengbojiangTo manipulate the environment of other objects 1981*572c4311Sfengbojiang(userdata, C functions, other threads) you must 1982*572c4311Sfengbojianguse the C API. 1983*572c4311Sfengbojiang 1984*572c4311Sfengbojiang 1985*572c4311Sfengbojiang 1986*572c4311Sfengbojiang 1987*572c4311Sfengbojiang 1988*572c4311Sfengbojiang<h2>2.10 - <a name="2.10">Garbage Collection</a></h2> 1989*572c4311Sfengbojiang 1990*572c4311Sfengbojiang<p> 1991*572c4311SfengbojiangLua performs automatic memory management. 1992*572c4311SfengbojiangThis means that 1993*572c4311Sfengbojiangyou have to worry neither about allocating memory for new objects 1994*572c4311Sfengbojiangnor about freeing it when the objects are no longer needed. 1995*572c4311SfengbojiangLua manages memory automatically by running 1996*572c4311Sfengbojianga <em>garbage collector</em> from time to time 1997*572c4311Sfengbojiangto collect all <em>dead objects</em> 1998*572c4311Sfengbojiang(that is, objects that are no longer accessible from Lua). 1999*572c4311SfengbojiangAll memory used by Lua is subject to automatic management: 2000*572c4311Sfengbojiangtables, userdata, functions, threads, strings, etc. 2001*572c4311Sfengbojiang 2002*572c4311Sfengbojiang 2003*572c4311Sfengbojiang<p> 2004*572c4311SfengbojiangLua implements an incremental mark-and-sweep collector. 2005*572c4311SfengbojiangIt uses two numbers to control its garbage-collection cycles: 2006*572c4311Sfengbojiangthe <em>garbage-collector pause</em> and 2007*572c4311Sfengbojiangthe <em>garbage-collector step multiplier</em>. 2008*572c4311SfengbojiangBoth use percentage points as units 2009*572c4311Sfengbojiang(so that a value of 100 means an internal value of 1). 2010*572c4311Sfengbojiang 2011*572c4311Sfengbojiang 2012*572c4311Sfengbojiang<p> 2013*572c4311SfengbojiangThe garbage-collector pause 2014*572c4311Sfengbojiangcontrols how long the collector waits before starting a new cycle. 2015*572c4311SfengbojiangLarger values make the collector less aggressive. 2016*572c4311SfengbojiangValues smaller than 100 mean the collector will not wait to 2017*572c4311Sfengbojiangstart a new cycle. 2018*572c4311SfengbojiangA value of 200 means that the collector waits for the total memory in use 2019*572c4311Sfengbojiangto double before starting a new cycle. 2020*572c4311Sfengbojiang 2021*572c4311Sfengbojiang 2022*572c4311Sfengbojiang<p> 2023*572c4311SfengbojiangThe step multiplier 2024*572c4311Sfengbojiangcontrols the relative speed of the collector relative to 2025*572c4311Sfengbojiangmemory allocation. 2026*572c4311SfengbojiangLarger values make the collector more aggressive but also increase 2027*572c4311Sfengbojiangthe size of each incremental step. 2028*572c4311SfengbojiangValues smaller than 100 make the collector too slow and 2029*572c4311Sfengbojiangcan result in the collector never finishing a cycle. 2030*572c4311SfengbojiangThe default, 200, means that the collector runs at "twice" 2031*572c4311Sfengbojiangthe speed of memory allocation. 2032*572c4311Sfengbojiang 2033*572c4311Sfengbojiang 2034*572c4311Sfengbojiang<p> 2035*572c4311SfengbojiangYou can change these numbers by calling <a href="#lua_gc"><code>lua_gc</code></a> in C 2036*572c4311Sfengbojiangor <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> in Lua. 2037*572c4311SfengbojiangWith these functions you can also control 2038*572c4311Sfengbojiangthe collector directly (e.g., stop and restart it). 2039*572c4311Sfengbojiang 2040*572c4311Sfengbojiang 2041*572c4311Sfengbojiang 2042*572c4311Sfengbojiang<h3>2.10.1 - <a name="2.10.1">Garbage-Collection Metamethods</a></h3> 2043*572c4311Sfengbojiang 2044*572c4311Sfengbojiang<p> 2045*572c4311SfengbojiangUsing the C API, 2046*572c4311Sfengbojiangyou can set garbage-collector metamethods for userdata (see <a href="#2.8">§2.8</a>). 2047*572c4311SfengbojiangThese metamethods are also called <em>finalizers</em>. 2048*572c4311SfengbojiangFinalizers allow you to coordinate Lua's garbage collection 2049*572c4311Sfengbojiangwith external resource management 2050*572c4311Sfengbojiang(such as closing files, network or database connections, 2051*572c4311Sfengbojiangor freeing your own memory). 2052*572c4311Sfengbojiang 2053*572c4311Sfengbojiang 2054*572c4311Sfengbojiang<p> 2055*572c4311SfengbojiangGarbage userdata with a field <code>__gc</code> in their metatables are not 2056*572c4311Sfengbojiangcollected immediately by the garbage collector. 2057*572c4311SfengbojiangInstead, Lua puts them in a list. 2058*572c4311SfengbojiangAfter the collection, 2059*572c4311SfengbojiangLua does the equivalent of the following function 2060*572c4311Sfengbojiangfor each userdata in that list: 2061*572c4311Sfengbojiang 2062*572c4311Sfengbojiang<pre> 2063*572c4311Sfengbojiang function gc_event (udata) 2064*572c4311Sfengbojiang local h = metatable(udata).__gc 2065*572c4311Sfengbojiang if h then 2066*572c4311Sfengbojiang h(udata) 2067*572c4311Sfengbojiang end 2068*572c4311Sfengbojiang end 2069*572c4311Sfengbojiang</pre> 2070*572c4311Sfengbojiang 2071*572c4311Sfengbojiang<p> 2072*572c4311SfengbojiangAt the end of each garbage-collection cycle, 2073*572c4311Sfengbojiangthe finalizers for userdata are called in <em>reverse</em> 2074*572c4311Sfengbojiangorder of their creation, 2075*572c4311Sfengbojiangamong those collected in that cycle. 2076*572c4311SfengbojiangThat is, the first finalizer to be called is the one associated 2077*572c4311Sfengbojiangwith the userdata created last in the program. 2078*572c4311SfengbojiangThe userdata itself is freed only in the next garbage-collection cycle. 2079*572c4311Sfengbojiang 2080*572c4311Sfengbojiang 2081*572c4311Sfengbojiang 2082*572c4311Sfengbojiang 2083*572c4311Sfengbojiang 2084*572c4311Sfengbojiang<h3>2.10.2 - <a name="2.10.2">Weak Tables</a></h3> 2085*572c4311Sfengbojiang 2086*572c4311Sfengbojiang<p> 2087*572c4311SfengbojiangA <em>weak table</em> is a table whose elements are 2088*572c4311Sfengbojiang<em>weak references</em>. 2089*572c4311SfengbojiangA weak reference is ignored by the garbage collector. 2090*572c4311SfengbojiangIn other words, 2091*572c4311Sfengbojiangif the only references to an object are weak references, 2092*572c4311Sfengbojiangthen the garbage collector will collect this object. 2093*572c4311Sfengbojiang 2094*572c4311Sfengbojiang 2095*572c4311Sfengbojiang<p> 2096*572c4311SfengbojiangA weak table can have weak keys, weak values, or both. 2097*572c4311SfengbojiangA table with weak keys allows the collection of its keys, 2098*572c4311Sfengbojiangbut prevents the collection of its values. 2099*572c4311SfengbojiangA table with both weak keys and weak values allows the collection of 2100*572c4311Sfengbojiangboth keys and values. 2101*572c4311SfengbojiangIn any case, if either the key or the value is collected, 2102*572c4311Sfengbojiangthe whole pair is removed from the table. 2103*572c4311SfengbojiangThe weakness of a table is controlled by the 2104*572c4311Sfengbojiang<code>__mode</code> field of its metatable. 2105*572c4311SfengbojiangIf the <code>__mode</code> field is a string containing the character '<code>k</code>', 2106*572c4311Sfengbojiangthe keys in the table are weak. 2107*572c4311SfengbojiangIf <code>__mode</code> contains '<code>v</code>', 2108*572c4311Sfengbojiangthe values in the table are weak. 2109*572c4311Sfengbojiang 2110*572c4311Sfengbojiang 2111*572c4311Sfengbojiang<p> 2112*572c4311SfengbojiangAfter you use a table as a metatable, 2113*572c4311Sfengbojiangyou should not change the value of its <code>__mode</code> field. 2114*572c4311SfengbojiangOtherwise, the weak behavior of the tables controlled by this 2115*572c4311Sfengbojiangmetatable is undefined. 2116*572c4311Sfengbojiang 2117*572c4311Sfengbojiang 2118*572c4311Sfengbojiang 2119*572c4311Sfengbojiang 2120*572c4311Sfengbojiang 2121*572c4311Sfengbojiang 2122*572c4311Sfengbojiang 2123*572c4311Sfengbojiang<h2>2.11 - <a name="2.11">Coroutines</a></h2> 2124*572c4311Sfengbojiang 2125*572c4311Sfengbojiang<p> 2126*572c4311SfengbojiangLua supports coroutines, 2127*572c4311Sfengbojiangalso called <em>collaborative multithreading</em>. 2128*572c4311SfengbojiangA coroutine in Lua represents an independent thread of execution. 2129*572c4311SfengbojiangUnlike threads in multithread systems, however, 2130*572c4311Sfengbojianga coroutine only suspends its execution by explicitly calling 2131*572c4311Sfengbojianga yield function. 2132*572c4311Sfengbojiang 2133*572c4311Sfengbojiang 2134*572c4311Sfengbojiang<p> 2135*572c4311SfengbojiangYou create a coroutine with a call to <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>. 2136*572c4311SfengbojiangIts sole argument is a function 2137*572c4311Sfengbojiangthat is the main function of the coroutine. 2138*572c4311SfengbojiangThe <code>create</code> function only creates a new coroutine and 2139*572c4311Sfengbojiangreturns a handle to it (an object of type <em>thread</em>); 2140*572c4311Sfengbojiangit does not start the coroutine execution. 2141*572c4311Sfengbojiang 2142*572c4311Sfengbojiang 2143*572c4311Sfengbojiang<p> 2144*572c4311SfengbojiangWhen you first call <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>, 2145*572c4311Sfengbojiangpassing as its first argument 2146*572c4311Sfengbojianga thread returned by <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>, 2147*572c4311Sfengbojiangthe coroutine starts its execution, 2148*572c4311Sfengbojiangat the first line of its main function. 2149*572c4311SfengbojiangExtra arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> are passed on 2150*572c4311Sfengbojiangto the coroutine main function. 2151*572c4311SfengbojiangAfter the coroutine starts running, 2152*572c4311Sfengbojiangit runs until it terminates or <em>yields</em>. 2153*572c4311Sfengbojiang 2154*572c4311Sfengbojiang 2155*572c4311Sfengbojiang<p> 2156*572c4311SfengbojiangA coroutine can terminate its execution in two ways: 2157*572c4311Sfengbojiangnormally, when its main function returns 2158*572c4311Sfengbojiang(explicitly or implicitly, after the last instruction); 2159*572c4311Sfengbojiangand abnormally, if there is an unprotected error. 2160*572c4311SfengbojiangIn the first case, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>true</b>, 2161*572c4311Sfengbojiangplus any values returned by the coroutine main function. 2162*572c4311SfengbojiangIn case of errors, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>false</b> 2163*572c4311Sfengbojiangplus an error message. 2164*572c4311Sfengbojiang 2165*572c4311Sfengbojiang 2166*572c4311Sfengbojiang<p> 2167*572c4311SfengbojiangA coroutine yields by calling <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>. 2168*572c4311SfengbojiangWhen a coroutine yields, 2169*572c4311Sfengbojiangthe corresponding <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns immediately, 2170*572c4311Sfengbojiangeven if the yield happens inside nested function calls 2171*572c4311Sfengbojiang(that is, not in the main function, 2172*572c4311Sfengbojiangbut in a function directly or indirectly called by the main function). 2173*572c4311SfengbojiangIn the case of a yield, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> also returns <b>true</b>, 2174*572c4311Sfengbojiangplus any values passed to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>. 2175*572c4311SfengbojiangThe next time you resume the same coroutine, 2176*572c4311Sfengbojiangit continues its execution from the point where it yielded, 2177*572c4311Sfengbojiangwith the call to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a> returning any extra 2178*572c4311Sfengbojiangarguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. 2179*572c4311Sfengbojiang 2180*572c4311Sfengbojiang 2181*572c4311Sfengbojiang<p> 2182*572c4311SfengbojiangLike <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>, 2183*572c4311Sfengbojiangthe <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> function also creates a coroutine, 2184*572c4311Sfengbojiangbut instead of returning the coroutine itself, 2185*572c4311Sfengbojiangit returns a function that, when called, resumes the coroutine. 2186*572c4311SfengbojiangAny arguments passed to this function 2187*572c4311Sfengbojianggo as extra arguments to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. 2188*572c4311Sfengbojiang<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>, 2189*572c4311Sfengbojiangexcept the first one (the boolean error code). 2190*572c4311SfengbojiangUnlike <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>, 2191*572c4311Sfengbojiang<a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> does not catch errors; 2192*572c4311Sfengbojiangany error is propagated to the caller. 2193*572c4311Sfengbojiang 2194*572c4311Sfengbojiang 2195*572c4311Sfengbojiang<p> 2196*572c4311SfengbojiangAs an example, 2197*572c4311Sfengbojiangconsider the following code: 2198*572c4311Sfengbojiang 2199*572c4311Sfengbojiang<pre> 2200*572c4311Sfengbojiang function foo (a) 2201*572c4311Sfengbojiang print("foo", a) 2202*572c4311Sfengbojiang return coroutine.yield(2*a) 2203*572c4311Sfengbojiang end 2204*572c4311Sfengbojiang 2205*572c4311Sfengbojiang co = coroutine.create(function (a,b) 2206*572c4311Sfengbojiang print("co-body", a, b) 2207*572c4311Sfengbojiang local r = foo(a+1) 2208*572c4311Sfengbojiang print("co-body", r) 2209*572c4311Sfengbojiang local r, s = coroutine.yield(a+b, a-b) 2210*572c4311Sfengbojiang print("co-body", r, s) 2211*572c4311Sfengbojiang return b, "end" 2212*572c4311Sfengbojiang end) 2213*572c4311Sfengbojiang 2214*572c4311Sfengbojiang print("main", coroutine.resume(co, 1, 10)) 2215*572c4311Sfengbojiang print("main", coroutine.resume(co, "r")) 2216*572c4311Sfengbojiang print("main", coroutine.resume(co, "x", "y")) 2217*572c4311Sfengbojiang print("main", coroutine.resume(co, "x", "y")) 2218*572c4311Sfengbojiang</pre><p> 2219*572c4311SfengbojiangWhen you run it, it produces the following output: 2220*572c4311Sfengbojiang 2221*572c4311Sfengbojiang<pre> 2222*572c4311Sfengbojiang co-body 1 10 2223*572c4311Sfengbojiang foo 2 2224*572c4311Sfengbojiang 2225*572c4311Sfengbojiang main true 4 2226*572c4311Sfengbojiang co-body r 2227*572c4311Sfengbojiang main true 11 -9 2228*572c4311Sfengbojiang co-body x y 2229*572c4311Sfengbojiang main true 10 end 2230*572c4311Sfengbojiang main false cannot resume dead coroutine 2231*572c4311Sfengbojiang</pre> 2232*572c4311Sfengbojiang 2233*572c4311Sfengbojiang 2234*572c4311Sfengbojiang 2235*572c4311Sfengbojiang 2236*572c4311Sfengbojiang<h1>3 - <a name="3">The Application Program Interface</a></h1> 2237*572c4311Sfengbojiang 2238*572c4311Sfengbojiang<p> 2239*572c4311Sfengbojiang 2240*572c4311SfengbojiangThis section describes the C API for Lua, that is, 2241*572c4311Sfengbojiangthe set of C functions available to the host program to communicate 2242*572c4311Sfengbojiangwith Lua. 2243*572c4311SfengbojiangAll API functions and related types and constants 2244*572c4311Sfengbojiangare declared in the header file <a name="pdf-lua.h"><code>lua.h</code></a>. 2245*572c4311Sfengbojiang 2246*572c4311Sfengbojiang 2247*572c4311Sfengbojiang<p> 2248*572c4311SfengbojiangEven when we use the term "function", 2249*572c4311Sfengbojiangany facility in the API may be provided as a macro instead. 2250*572c4311SfengbojiangAll such macros use each of their arguments exactly once 2251*572c4311Sfengbojiang(except for the first argument, which is always a Lua state), 2252*572c4311Sfengbojiangand so do not generate any hidden side-effects. 2253*572c4311Sfengbojiang 2254*572c4311Sfengbojiang 2255*572c4311Sfengbojiang<p> 2256*572c4311SfengbojiangAs in most C libraries, 2257*572c4311Sfengbojiangthe Lua API functions do not check their arguments for validity or consistency. 2258*572c4311SfengbojiangHowever, you can change this behavior by compiling Lua 2259*572c4311Sfengbojiangwith a proper definition for the macro <a name="pdf-luai_apicheck"><code>luai_apicheck</code></a>, 2260*572c4311Sfengbojiangin file <code>luaconf.h</code>. 2261*572c4311Sfengbojiang 2262*572c4311Sfengbojiang 2263*572c4311Sfengbojiang 2264*572c4311Sfengbojiang<h2>3.1 - <a name="3.1">The Stack</a></h2> 2265*572c4311Sfengbojiang 2266*572c4311Sfengbojiang<p> 2267*572c4311SfengbojiangLua uses a <em>virtual stack</em> to pass values to and from C. 2268*572c4311SfengbojiangEach element in this stack represents a Lua value 2269*572c4311Sfengbojiang(<b>nil</b>, number, string, etc.). 2270*572c4311Sfengbojiang 2271*572c4311Sfengbojiang 2272*572c4311Sfengbojiang<p> 2273*572c4311SfengbojiangWhenever Lua calls C, the called function gets a new stack, 2274*572c4311Sfengbojiangwhich is independent of previous stacks and of stacks of 2275*572c4311SfengbojiangC functions that are still active. 2276*572c4311SfengbojiangThis stack initially contains any arguments to the C function 2277*572c4311Sfengbojiangand it is where the C function pushes its results 2278*572c4311Sfengbojiangto be returned to the caller (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 2279*572c4311Sfengbojiang 2280*572c4311Sfengbojiang 2281*572c4311Sfengbojiang<p> 2282*572c4311SfengbojiangFor convenience, 2283*572c4311Sfengbojiangmost query operations in the API do not follow a strict stack discipline. 2284*572c4311SfengbojiangInstead, they can refer to any element in the stack 2285*572c4311Sfengbojiangby using an <em>index</em>: 2286*572c4311SfengbojiangA positive index represents an <em>absolute</em> stack position 2287*572c4311Sfengbojiang(starting at 1); 2288*572c4311Sfengbojianga negative index represents an <em>offset</em> relative to the top of the stack. 2289*572c4311SfengbojiangMore specifically, if the stack has <em>n</em> elements, 2290*572c4311Sfengbojiangthen index 1 represents the first element 2291*572c4311Sfengbojiang(that is, the element that was pushed onto the stack first) 2292*572c4311Sfengbojiangand 2293*572c4311Sfengbojiangindex <em>n</em> represents the last element; 2294*572c4311Sfengbojiangindex -1 also represents the last element 2295*572c4311Sfengbojiang(that is, the element at the top) 2296*572c4311Sfengbojiangand index <em>-n</em> represents the first element. 2297*572c4311SfengbojiangWe say that an index is <em>valid</em> 2298*572c4311Sfengbojiangif it lies between 1 and the stack top 2299*572c4311Sfengbojiang(that is, if <code>1 ≤ abs(index) ≤ top</code>). 2300*572c4311Sfengbojiang 2301*572c4311Sfengbojiang 2302*572c4311Sfengbojiang 2303*572c4311Sfengbojiang 2304*572c4311Sfengbojiang 2305*572c4311Sfengbojiang 2306*572c4311Sfengbojiang<h2>3.2 - <a name="3.2">Stack Size</a></h2> 2307*572c4311Sfengbojiang 2308*572c4311Sfengbojiang<p> 2309*572c4311SfengbojiangWhen you interact with Lua API, 2310*572c4311Sfengbojiangyou are responsible for ensuring consistency. 2311*572c4311SfengbojiangIn particular, 2312*572c4311Sfengbojiang<em>you are responsible for controlling stack overflow</em>. 2313*572c4311SfengbojiangYou can use the function <a href="#lua_checkstack"><code>lua_checkstack</code></a> 2314*572c4311Sfengbojiangto grow the stack size. 2315*572c4311Sfengbojiang 2316*572c4311Sfengbojiang 2317*572c4311Sfengbojiang<p> 2318*572c4311SfengbojiangWhenever Lua calls C, 2319*572c4311Sfengbojiangit ensures that at least <a name="pdf-LUA_MINSTACK"><code>LUA_MINSTACK</code></a> stack positions are available. 2320*572c4311Sfengbojiang<code>LUA_MINSTACK</code> is defined as 20, 2321*572c4311Sfengbojiangso that usually you do not have to worry about stack space 2322*572c4311Sfengbojiangunless your code has loops pushing elements onto the stack. 2323*572c4311Sfengbojiang 2324*572c4311Sfengbojiang 2325*572c4311Sfengbojiang<p> 2326*572c4311SfengbojiangMost query functions accept as indices any value inside the 2327*572c4311Sfengbojiangavailable stack space, that is, indices up to the maximum stack size 2328*572c4311Sfengbojiangyou have set through <a href="#lua_checkstack"><code>lua_checkstack</code></a>. 2329*572c4311SfengbojiangSuch indices are called <em>acceptable indices</em>. 2330*572c4311SfengbojiangMore formally, we define an <em>acceptable index</em> 2331*572c4311Sfengbojiangas follows: 2332*572c4311Sfengbojiang 2333*572c4311Sfengbojiang<pre> 2334*572c4311Sfengbojiang (index < 0 && abs(index) <= top) || 2335*572c4311Sfengbojiang (index > 0 && index <= stackspace) 2336*572c4311Sfengbojiang</pre><p> 2337*572c4311SfengbojiangNote that 0 is never an acceptable index. 2338*572c4311Sfengbojiang 2339*572c4311Sfengbojiang 2340*572c4311Sfengbojiang 2341*572c4311Sfengbojiang 2342*572c4311Sfengbojiang 2343*572c4311Sfengbojiang<h2>3.3 - <a name="3.3">Pseudo-Indices</a></h2> 2344*572c4311Sfengbojiang 2345*572c4311Sfengbojiang<p> 2346*572c4311SfengbojiangUnless otherwise noted, 2347*572c4311Sfengbojiangany function that accepts valid indices can also be called with 2348*572c4311Sfengbojiang<em>pseudo-indices</em>, 2349*572c4311Sfengbojiangwhich represent some Lua values that are accessible to C code 2350*572c4311Sfengbojiangbut which are not in the stack. 2351*572c4311SfengbojiangPseudo-indices are used to access the thread environment, 2352*572c4311Sfengbojiangthe function environment, 2353*572c4311Sfengbojiangthe registry, 2354*572c4311Sfengbojiangand the upvalues of a C function (see <a href="#3.4">§3.4</a>). 2355*572c4311Sfengbojiang 2356*572c4311Sfengbojiang 2357*572c4311Sfengbojiang<p> 2358*572c4311SfengbojiangThe thread environment (where global variables live) is 2359*572c4311Sfengbojiangalways at pseudo-index <a name="pdf-LUA_GLOBALSINDEX"><code>LUA_GLOBALSINDEX</code></a>. 2360*572c4311SfengbojiangThe environment of the running C function is always 2361*572c4311Sfengbojiangat pseudo-index <a name="pdf-LUA_ENVIRONINDEX"><code>LUA_ENVIRONINDEX</code></a>. 2362*572c4311Sfengbojiang 2363*572c4311Sfengbojiang 2364*572c4311Sfengbojiang<p> 2365*572c4311SfengbojiangTo access and change the value of global variables, 2366*572c4311Sfengbojiangyou can use regular table operations over an environment table. 2367*572c4311SfengbojiangFor instance, to access the value of a global variable, do 2368*572c4311Sfengbojiang 2369*572c4311Sfengbojiang<pre> 2370*572c4311Sfengbojiang lua_getfield(L, LUA_GLOBALSINDEX, varname); 2371*572c4311Sfengbojiang</pre> 2372*572c4311Sfengbojiang 2373*572c4311Sfengbojiang 2374*572c4311Sfengbojiang 2375*572c4311Sfengbojiang 2376*572c4311Sfengbojiang<h2>3.4 - <a name="3.4">C Closures</a></h2> 2377*572c4311Sfengbojiang 2378*572c4311Sfengbojiang<p> 2379*572c4311SfengbojiangWhen a C function is created, 2380*572c4311Sfengbojiangit is possible to associate some values with it, 2381*572c4311Sfengbojiangthus creating a <em>C closure</em>; 2382*572c4311Sfengbojiangthese values are called <em>upvalues</em> and are 2383*572c4311Sfengbojiangaccessible to the function whenever it is called 2384*572c4311Sfengbojiang(see <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>). 2385*572c4311Sfengbojiang 2386*572c4311Sfengbojiang 2387*572c4311Sfengbojiang<p> 2388*572c4311SfengbojiangWhenever a C function is called, 2389*572c4311Sfengbojiangits upvalues are located at specific pseudo-indices. 2390*572c4311SfengbojiangThese pseudo-indices are produced by the macro 2391*572c4311Sfengbojiang<a name="lua_upvalueindex"><code>lua_upvalueindex</code></a>. 2392*572c4311SfengbojiangThe first value associated with a function is at position 2393*572c4311Sfengbojiang<code>lua_upvalueindex(1)</code>, and so on. 2394*572c4311SfengbojiangAny access to <code>lua_upvalueindex(<em>n</em>)</code>, 2395*572c4311Sfengbojiangwhere <em>n</em> is greater than the number of upvalues of the 2396*572c4311Sfengbojiangcurrent function (but not greater than 256), 2397*572c4311Sfengbojiangproduces an acceptable (but invalid) index. 2398*572c4311Sfengbojiang 2399*572c4311Sfengbojiang 2400*572c4311Sfengbojiang 2401*572c4311Sfengbojiang 2402*572c4311Sfengbojiang 2403*572c4311Sfengbojiang<h2>3.5 - <a name="3.5">Registry</a></h2> 2404*572c4311Sfengbojiang 2405*572c4311Sfengbojiang<p> 2406*572c4311SfengbojiangLua provides a <em>registry</em>, 2407*572c4311Sfengbojianga pre-defined table that can be used by any C code to 2408*572c4311Sfengbojiangstore whatever Lua value it needs to store. 2409*572c4311SfengbojiangThis table is always located at pseudo-index 2410*572c4311Sfengbojiang<a name="pdf-LUA_REGISTRYINDEX"><code>LUA_REGISTRYINDEX</code></a>. 2411*572c4311SfengbojiangAny C library can store data into this table, 2412*572c4311Sfengbojiangbut it should take care to choose keys different from those used 2413*572c4311Sfengbojiangby other libraries, to avoid collisions. 2414*572c4311SfengbojiangTypically, you should use as key a string containing your library name 2415*572c4311Sfengbojiangor a light userdata with the address of a C object in your code. 2416*572c4311Sfengbojiang 2417*572c4311Sfengbojiang 2418*572c4311Sfengbojiang<p> 2419*572c4311SfengbojiangThe integer keys in the registry are used by the reference mechanism, 2420*572c4311Sfengbojiangimplemented by the auxiliary library, 2421*572c4311Sfengbojiangand therefore should not be used for other purposes. 2422*572c4311Sfengbojiang 2423*572c4311Sfengbojiang 2424*572c4311Sfengbojiang 2425*572c4311Sfengbojiang 2426*572c4311Sfengbojiang 2427*572c4311Sfengbojiang<h2>3.6 - <a name="3.6">Error Handling in C</a></h2> 2428*572c4311Sfengbojiang 2429*572c4311Sfengbojiang<p> 2430*572c4311SfengbojiangInternally, Lua uses the C <code>longjmp</code> facility to handle errors. 2431*572c4311Sfengbojiang(You can also choose to use exceptions if you use C++; 2432*572c4311Sfengbojiangsee file <code>luaconf.h</code>.) 2433*572c4311SfengbojiangWhen Lua faces any error 2434*572c4311Sfengbojiang(such as memory allocation errors, type errors, syntax errors, 2435*572c4311Sfengbojiangand runtime errors) 2436*572c4311Sfengbojiangit <em>raises</em> an error; 2437*572c4311Sfengbojiangthat is, it does a long jump. 2438*572c4311SfengbojiangA <em>protected environment</em> uses <code>setjmp</code> 2439*572c4311Sfengbojiangto set a recover point; 2440*572c4311Sfengbojiangany error jumps to the most recent active recover point. 2441*572c4311Sfengbojiang 2442*572c4311Sfengbojiang 2443*572c4311Sfengbojiang<p> 2444*572c4311SfengbojiangMost functions in the API can throw an error, 2445*572c4311Sfengbojiangfor instance due to a memory allocation error. 2446*572c4311SfengbojiangThe documentation for each function indicates whether 2447*572c4311Sfengbojiangit can throw errors. 2448*572c4311Sfengbojiang 2449*572c4311Sfengbojiang 2450*572c4311Sfengbojiang<p> 2451*572c4311SfengbojiangInside a C function you can throw an error by calling <a href="#lua_error"><code>lua_error</code></a>. 2452*572c4311Sfengbojiang 2453*572c4311Sfengbojiang 2454*572c4311Sfengbojiang 2455*572c4311Sfengbojiang 2456*572c4311Sfengbojiang 2457*572c4311Sfengbojiang<h2>3.7 - <a name="3.7">Functions and Types</a></h2> 2458*572c4311Sfengbojiang 2459*572c4311Sfengbojiang<p> 2460*572c4311SfengbojiangHere we list all functions and types from the C API in 2461*572c4311Sfengbojiangalphabetical order. 2462*572c4311SfengbojiangEach function has an indicator like this: 2463*572c4311Sfengbojiang<span class="apii">[-o, +p, <em>x</em>]</span> 2464*572c4311Sfengbojiang 2465*572c4311Sfengbojiang 2466*572c4311Sfengbojiang<p> 2467*572c4311SfengbojiangThe first field, <code>o</code>, 2468*572c4311Sfengbojiangis how many elements the function pops from the stack. 2469*572c4311SfengbojiangThe second field, <code>p</code>, 2470*572c4311Sfengbojiangis how many elements the function pushes onto the stack. 2471*572c4311Sfengbojiang(Any function always pushes its results after popping its arguments.) 2472*572c4311SfengbojiangA field in the form <code>x|y</code> means the function can push (or pop) 2473*572c4311Sfengbojiang<code>x</code> or <code>y</code> elements, 2474*572c4311Sfengbojiangdepending on the situation; 2475*572c4311Sfengbojiangan interrogation mark '<code>?</code>' means that 2476*572c4311Sfengbojiangwe cannot know how many elements the function pops/pushes 2477*572c4311Sfengbojiangby looking only at its arguments 2478*572c4311Sfengbojiang(e.g., they may depend on what is on the stack). 2479*572c4311SfengbojiangThe third field, <code>x</code>, 2480*572c4311Sfengbojiangtells whether the function may throw errors: 2481*572c4311Sfengbojiang'<code>-</code>' means the function never throws any error; 2482*572c4311Sfengbojiang'<code>m</code>' means the function may throw an error 2483*572c4311Sfengbojiangonly due to not enough memory; 2484*572c4311Sfengbojiang'<code>e</code>' means the function may throw other kinds of errors; 2485*572c4311Sfengbojiang'<code>v</code>' means the function may throw an error on purpose. 2486*572c4311Sfengbojiang 2487*572c4311Sfengbojiang 2488*572c4311Sfengbojiang 2489*572c4311Sfengbojiang<hr><h3><a name="lua_Alloc"><code>lua_Alloc</code></a></h3> 2490*572c4311Sfengbojiang<pre>typedef void * (*lua_Alloc) (void *ud, 2491*572c4311Sfengbojiang void *ptr, 2492*572c4311Sfengbojiang size_t osize, 2493*572c4311Sfengbojiang size_t nsize);</pre> 2494*572c4311Sfengbojiang 2495*572c4311Sfengbojiang<p> 2496*572c4311SfengbojiangThe type of the memory-allocation function used by Lua states. 2497*572c4311SfengbojiangThe allocator function must provide a 2498*572c4311Sfengbojiangfunctionality similar to <code>realloc</code>, 2499*572c4311Sfengbojiangbut not exactly the same. 2500*572c4311SfengbojiangIts arguments are 2501*572c4311Sfengbojiang<code>ud</code>, an opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>; 2502*572c4311Sfengbojiang<code>ptr</code>, a pointer to the block being allocated/reallocated/freed; 2503*572c4311Sfengbojiang<code>osize</code>, the original size of the block; 2504*572c4311Sfengbojiang<code>nsize</code>, the new size of the block. 2505*572c4311Sfengbojiang<code>ptr</code> is <code>NULL</code> if and only if <code>osize</code> is zero. 2506*572c4311SfengbojiangWhen <code>nsize</code> is zero, the allocator must return <code>NULL</code>; 2507*572c4311Sfengbojiangif <code>osize</code> is not zero, 2508*572c4311Sfengbojiangit should free the block pointed to by <code>ptr</code>. 2509*572c4311SfengbojiangWhen <code>nsize</code> is not zero, the allocator returns <code>NULL</code> 2510*572c4311Sfengbojiangif and only if it cannot fill the request. 2511*572c4311SfengbojiangWhen <code>nsize</code> is not zero and <code>osize</code> is zero, 2512*572c4311Sfengbojiangthe allocator should behave like <code>malloc</code>. 2513*572c4311SfengbojiangWhen <code>nsize</code> and <code>osize</code> are not zero, 2514*572c4311Sfengbojiangthe allocator behaves like <code>realloc</code>. 2515*572c4311SfengbojiangLua assumes that the allocator never fails when 2516*572c4311Sfengbojiang<code>osize >= nsize</code>. 2517*572c4311Sfengbojiang 2518*572c4311Sfengbojiang 2519*572c4311Sfengbojiang<p> 2520*572c4311SfengbojiangHere is a simple implementation for the allocator function. 2521*572c4311SfengbojiangIt is used in the auxiliary library by <a href="#luaL_newstate"><code>luaL_newstate</code></a>. 2522*572c4311Sfengbojiang 2523*572c4311Sfengbojiang<pre> 2524*572c4311Sfengbojiang static void *l_alloc (void *ud, void *ptr, size_t osize, 2525*572c4311Sfengbojiang size_t nsize) { 2526*572c4311Sfengbojiang (void)ud; (void)osize; /* not used */ 2527*572c4311Sfengbojiang if (nsize == 0) { 2528*572c4311Sfengbojiang free(ptr); 2529*572c4311Sfengbojiang return NULL; 2530*572c4311Sfengbojiang } 2531*572c4311Sfengbojiang else 2532*572c4311Sfengbojiang return realloc(ptr, nsize); 2533*572c4311Sfengbojiang } 2534*572c4311Sfengbojiang</pre><p> 2535*572c4311SfengbojiangThis code assumes 2536*572c4311Sfengbojiangthat <code>free(NULL)</code> has no effect and that 2537*572c4311Sfengbojiang<code>realloc(NULL, size)</code> is equivalent to <code>malloc(size)</code>. 2538*572c4311SfengbojiangANSI C ensures both behaviors. 2539*572c4311Sfengbojiang 2540*572c4311Sfengbojiang 2541*572c4311Sfengbojiang 2542*572c4311Sfengbojiang 2543*572c4311Sfengbojiang 2544*572c4311Sfengbojiang<hr><h3><a name="lua_atpanic"><code>lua_atpanic</code></a></h3><p> 2545*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>-</em>]</span> 2546*572c4311Sfengbojiang<pre>lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);</pre> 2547*572c4311Sfengbojiang 2548*572c4311Sfengbojiang<p> 2549*572c4311SfengbojiangSets a new panic function and returns the old one. 2550*572c4311Sfengbojiang 2551*572c4311Sfengbojiang 2552*572c4311Sfengbojiang<p> 2553*572c4311SfengbojiangIf an error happens outside any protected environment, 2554*572c4311SfengbojiangLua calls a <em>panic function</em> 2555*572c4311Sfengbojiangand then calls <code>exit(EXIT_FAILURE)</code>, 2556*572c4311Sfengbojiangthus exiting the host application. 2557*572c4311SfengbojiangYour panic function can avoid this exit by 2558*572c4311Sfengbojiangnever returning (e.g., doing a long jump). 2559*572c4311Sfengbojiang 2560*572c4311Sfengbojiang 2561*572c4311Sfengbojiang<p> 2562*572c4311SfengbojiangThe panic function can access the error message at the top of the stack. 2563*572c4311Sfengbojiang 2564*572c4311Sfengbojiang 2565*572c4311Sfengbojiang 2566*572c4311Sfengbojiang 2567*572c4311Sfengbojiang 2568*572c4311Sfengbojiang<hr><h3><a name="lua_call"><code>lua_call</code></a></h3><p> 2569*572c4311Sfengbojiang<span class="apii">[-(nargs + 1), +nresults, <em>e</em>]</span> 2570*572c4311Sfengbojiang<pre>void lua_call (lua_State *L, int nargs, int nresults);</pre> 2571*572c4311Sfengbojiang 2572*572c4311Sfengbojiang<p> 2573*572c4311SfengbojiangCalls a function. 2574*572c4311Sfengbojiang 2575*572c4311Sfengbojiang 2576*572c4311Sfengbojiang<p> 2577*572c4311SfengbojiangTo call a function you must use the following protocol: 2578*572c4311Sfengbojiangfirst, the function to be called is pushed onto the stack; 2579*572c4311Sfengbojiangthen, the arguments to the function are pushed 2580*572c4311Sfengbojiangin direct order; 2581*572c4311Sfengbojiangthat is, the first argument is pushed first. 2582*572c4311SfengbojiangFinally you call <a href="#lua_call"><code>lua_call</code></a>; 2583*572c4311Sfengbojiang<code>nargs</code> is the number of arguments that you pushed onto the stack. 2584*572c4311SfengbojiangAll arguments and the function value are popped from the stack 2585*572c4311Sfengbojiangwhen the function is called. 2586*572c4311SfengbojiangThe function results are pushed onto the stack when the function returns. 2587*572c4311SfengbojiangThe number of results is adjusted to <code>nresults</code>, 2588*572c4311Sfengbojiangunless <code>nresults</code> is <a name="pdf-LUA_MULTRET"><code>LUA_MULTRET</code></a>. 2589*572c4311SfengbojiangIn this case, <em>all</em> results from the function are pushed. 2590*572c4311SfengbojiangLua takes care that the returned values fit into the stack space. 2591*572c4311SfengbojiangThe function results are pushed onto the stack in direct order 2592*572c4311Sfengbojiang(the first result is pushed first), 2593*572c4311Sfengbojiangso that after the call the last result is on the top of the stack. 2594*572c4311Sfengbojiang 2595*572c4311Sfengbojiang 2596*572c4311Sfengbojiang<p> 2597*572c4311SfengbojiangAny error inside the called function is propagated upwards 2598*572c4311Sfengbojiang(with a <code>longjmp</code>). 2599*572c4311Sfengbojiang 2600*572c4311Sfengbojiang 2601*572c4311Sfengbojiang<p> 2602*572c4311SfengbojiangThe following example shows how the host program can do the 2603*572c4311Sfengbojiangequivalent to this Lua code: 2604*572c4311Sfengbojiang 2605*572c4311Sfengbojiang<pre> 2606*572c4311Sfengbojiang a = f("how", t.x, 14) 2607*572c4311Sfengbojiang</pre><p> 2608*572c4311SfengbojiangHere it is in C: 2609*572c4311Sfengbojiang 2610*572c4311Sfengbojiang<pre> 2611*572c4311Sfengbojiang lua_getfield(L, LUA_GLOBALSINDEX, "f"); /* function to be called */ 2612*572c4311Sfengbojiang lua_pushstring(L, "how"); /* 1st argument */ 2613*572c4311Sfengbojiang lua_getfield(L, LUA_GLOBALSINDEX, "t"); /* table to be indexed */ 2614*572c4311Sfengbojiang lua_getfield(L, -1, "x"); /* push result of t.x (2nd arg) */ 2615*572c4311Sfengbojiang lua_remove(L, -2); /* remove 't' from the stack */ 2616*572c4311Sfengbojiang lua_pushinteger(L, 14); /* 3rd argument */ 2617*572c4311Sfengbojiang lua_call(L, 3, 1); /* call 'f' with 3 arguments and 1 result */ 2618*572c4311Sfengbojiang lua_setfield(L, LUA_GLOBALSINDEX, "a"); /* set global 'a' */ 2619*572c4311Sfengbojiang</pre><p> 2620*572c4311SfengbojiangNote that the code above is "balanced": 2621*572c4311Sfengbojiangat its end, the stack is back to its original configuration. 2622*572c4311SfengbojiangThis is considered good programming practice. 2623*572c4311Sfengbojiang 2624*572c4311Sfengbojiang 2625*572c4311Sfengbojiang 2626*572c4311Sfengbojiang 2627*572c4311Sfengbojiang 2628*572c4311Sfengbojiang<hr><h3><a name="lua_CFunction"><code>lua_CFunction</code></a></h3> 2629*572c4311Sfengbojiang<pre>typedef int (*lua_CFunction) (lua_State *L);</pre> 2630*572c4311Sfengbojiang 2631*572c4311Sfengbojiang<p> 2632*572c4311SfengbojiangType for C functions. 2633*572c4311Sfengbojiang 2634*572c4311Sfengbojiang 2635*572c4311Sfengbojiang<p> 2636*572c4311SfengbojiangIn order to communicate properly with Lua, 2637*572c4311Sfengbojianga C function must use the following protocol, 2638*572c4311Sfengbojiangwhich defines the way parameters and results are passed: 2639*572c4311Sfengbojianga C function receives its arguments from Lua in its stack 2640*572c4311Sfengbojiangin direct order (the first argument is pushed first). 2641*572c4311SfengbojiangSo, when the function starts, 2642*572c4311Sfengbojiang<code>lua_gettop(L)</code> returns the number of arguments received by the function. 2643*572c4311SfengbojiangThe first argument (if any) is at index 1 2644*572c4311Sfengbojiangand its last argument is at index <code>lua_gettop(L)</code>. 2645*572c4311SfengbojiangTo return values to Lua, a C function just pushes them onto the stack, 2646*572c4311Sfengbojiangin direct order (the first result is pushed first), 2647*572c4311Sfengbojiangand returns the number of results. 2648*572c4311SfengbojiangAny other value in the stack below the results will be properly 2649*572c4311Sfengbojiangdiscarded by Lua. 2650*572c4311SfengbojiangLike a Lua function, a C function called by Lua can also return 2651*572c4311Sfengbojiangmany results. 2652*572c4311Sfengbojiang 2653*572c4311Sfengbojiang 2654*572c4311Sfengbojiang<p> 2655*572c4311SfengbojiangAs an example, the following function receives a variable number 2656*572c4311Sfengbojiangof numerical arguments and returns their average and sum: 2657*572c4311Sfengbojiang 2658*572c4311Sfengbojiang<pre> 2659*572c4311Sfengbojiang static int foo (lua_State *L) { 2660*572c4311Sfengbojiang int n = lua_gettop(L); /* number of arguments */ 2661*572c4311Sfengbojiang lua_Number sum = 0; 2662*572c4311Sfengbojiang int i; 2663*572c4311Sfengbojiang for (i = 1; i <= n; i++) { 2664*572c4311Sfengbojiang if (!lua_isnumber(L, i)) { 2665*572c4311Sfengbojiang lua_pushstring(L, "incorrect argument"); 2666*572c4311Sfengbojiang lua_error(L); 2667*572c4311Sfengbojiang } 2668*572c4311Sfengbojiang sum += lua_tonumber(L, i); 2669*572c4311Sfengbojiang } 2670*572c4311Sfengbojiang lua_pushnumber(L, sum/n); /* first result */ 2671*572c4311Sfengbojiang lua_pushnumber(L, sum); /* second result */ 2672*572c4311Sfengbojiang return 2; /* number of results */ 2673*572c4311Sfengbojiang } 2674*572c4311Sfengbojiang</pre> 2675*572c4311Sfengbojiang 2676*572c4311Sfengbojiang 2677*572c4311Sfengbojiang 2678*572c4311Sfengbojiang 2679*572c4311Sfengbojiang<hr><h3><a name="lua_checkstack"><code>lua_checkstack</code></a></h3><p> 2680*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>m</em>]</span> 2681*572c4311Sfengbojiang<pre>int lua_checkstack (lua_State *L, int extra);</pre> 2682*572c4311Sfengbojiang 2683*572c4311Sfengbojiang<p> 2684*572c4311SfengbojiangEnsures that there are at least <code>extra</code> free stack slots in the stack. 2685*572c4311SfengbojiangIt returns false if it cannot grow the stack to that size. 2686*572c4311SfengbojiangThis function never shrinks the stack; 2687*572c4311Sfengbojiangif the stack is already larger than the new size, 2688*572c4311Sfengbojiangit is left unchanged. 2689*572c4311Sfengbojiang 2690*572c4311Sfengbojiang 2691*572c4311Sfengbojiang 2692*572c4311Sfengbojiang 2693*572c4311Sfengbojiang 2694*572c4311Sfengbojiang<hr><h3><a name="lua_close"><code>lua_close</code></a></h3><p> 2695*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>-</em>]</span> 2696*572c4311Sfengbojiang<pre>void lua_close (lua_State *L);</pre> 2697*572c4311Sfengbojiang 2698*572c4311Sfengbojiang<p> 2699*572c4311SfengbojiangDestroys all objects in the given Lua state 2700*572c4311Sfengbojiang(calling the corresponding garbage-collection metamethods, if any) 2701*572c4311Sfengbojiangand frees all dynamic memory used by this state. 2702*572c4311SfengbojiangOn several platforms, you may not need to call this function, 2703*572c4311Sfengbojiangbecause all resources are naturally released when the host program ends. 2704*572c4311SfengbojiangOn the other hand, long-running programs, 2705*572c4311Sfengbojiangsuch as a daemon or a web server, 2706*572c4311Sfengbojiangmight need to release states as soon as they are not needed, 2707*572c4311Sfengbojiangto avoid growing too large. 2708*572c4311Sfengbojiang 2709*572c4311Sfengbojiang 2710*572c4311Sfengbojiang 2711*572c4311Sfengbojiang 2712*572c4311Sfengbojiang 2713*572c4311Sfengbojiang<hr><h3><a name="lua_concat"><code>lua_concat</code></a></h3><p> 2714*572c4311Sfengbojiang<span class="apii">[-n, +1, <em>e</em>]</span> 2715*572c4311Sfengbojiang<pre>void lua_concat (lua_State *L, int n);</pre> 2716*572c4311Sfengbojiang 2717*572c4311Sfengbojiang<p> 2718*572c4311SfengbojiangConcatenates the <code>n</code> values at the top of the stack, 2719*572c4311Sfengbojiangpops them, and leaves the result at the top. 2720*572c4311SfengbojiangIf <code>n</code> is 1, the result is the single value on the stack 2721*572c4311Sfengbojiang(that is, the function does nothing); 2722*572c4311Sfengbojiangif <code>n</code> is 0, the result is the empty string. 2723*572c4311SfengbojiangConcatenation is performed following the usual semantics of Lua 2724*572c4311Sfengbojiang(see <a href="#2.5.4">§2.5.4</a>). 2725*572c4311Sfengbojiang 2726*572c4311Sfengbojiang 2727*572c4311Sfengbojiang 2728*572c4311Sfengbojiang 2729*572c4311Sfengbojiang 2730*572c4311Sfengbojiang<hr><h3><a name="lua_cpcall"><code>lua_cpcall</code></a></h3><p> 2731*572c4311Sfengbojiang<span class="apii">[-0, +(0|1), <em>-</em>]</span> 2732*572c4311Sfengbojiang<pre>int lua_cpcall (lua_State *L, lua_CFunction func, void *ud);</pre> 2733*572c4311Sfengbojiang 2734*572c4311Sfengbojiang<p> 2735*572c4311SfengbojiangCalls the C function <code>func</code> in protected mode. 2736*572c4311Sfengbojiang<code>func</code> starts with only one element in its stack, 2737*572c4311Sfengbojianga light userdata containing <code>ud</code>. 2738*572c4311SfengbojiangIn case of errors, 2739*572c4311Sfengbojiang<a href="#lua_cpcall"><code>lua_cpcall</code></a> returns the same error codes as <a href="#lua_pcall"><code>lua_pcall</code></a>, 2740*572c4311Sfengbojiangplus the error object on the top of the stack; 2741*572c4311Sfengbojiangotherwise, it returns zero, and does not change the stack. 2742*572c4311SfengbojiangAll values returned by <code>func</code> are discarded. 2743*572c4311Sfengbojiang 2744*572c4311Sfengbojiang 2745*572c4311Sfengbojiang 2746*572c4311Sfengbojiang 2747*572c4311Sfengbojiang 2748*572c4311Sfengbojiang<hr><h3><a name="lua_createtable"><code>lua_createtable</code></a></h3><p> 2749*572c4311Sfengbojiang<span class="apii">[-0, +1, <em>m</em>]</span> 2750*572c4311Sfengbojiang<pre>void lua_createtable (lua_State *L, int narr, int nrec);</pre> 2751*572c4311Sfengbojiang 2752*572c4311Sfengbojiang<p> 2753*572c4311SfengbojiangCreates a new empty table and pushes it onto the stack. 2754*572c4311SfengbojiangThe new table has space pre-allocated 2755*572c4311Sfengbojiangfor <code>narr</code> array elements and <code>nrec</code> non-array elements. 2756*572c4311SfengbojiangThis pre-allocation is useful when you know exactly how many elements 2757*572c4311Sfengbojiangthe table will have. 2758*572c4311SfengbojiangOtherwise you can use the function <a href="#lua_newtable"><code>lua_newtable</code></a>. 2759*572c4311Sfengbojiang 2760*572c4311Sfengbojiang 2761*572c4311Sfengbojiang 2762*572c4311Sfengbojiang 2763*572c4311Sfengbojiang 2764*572c4311Sfengbojiang<hr><h3><a name="lua_dump"><code>lua_dump</code></a></h3><p> 2765*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>m</em>]</span> 2766*572c4311Sfengbojiang<pre>int lua_dump (lua_State *L, lua_Writer writer, void *data);</pre> 2767*572c4311Sfengbojiang 2768*572c4311Sfengbojiang<p> 2769*572c4311SfengbojiangDumps a function as a binary chunk. 2770*572c4311SfengbojiangReceives a Lua function on the top of the stack 2771*572c4311Sfengbojiangand produces a binary chunk that, 2772*572c4311Sfengbojiangif loaded again, 2773*572c4311Sfengbojiangresults in a function equivalent to the one dumped. 2774*572c4311SfengbojiangAs it produces parts of the chunk, 2775*572c4311Sfengbojiang<a href="#lua_dump"><code>lua_dump</code></a> calls function <code>writer</code> (see <a href="#lua_Writer"><code>lua_Writer</code></a>) 2776*572c4311Sfengbojiangwith the given <code>data</code> 2777*572c4311Sfengbojiangto write them. 2778*572c4311Sfengbojiang 2779*572c4311Sfengbojiang 2780*572c4311Sfengbojiang<p> 2781*572c4311SfengbojiangThe value returned is the error code returned by the last 2782*572c4311Sfengbojiangcall to the writer; 2783*572c4311Sfengbojiang0 means no errors. 2784*572c4311Sfengbojiang 2785*572c4311Sfengbojiang 2786*572c4311Sfengbojiang<p> 2787*572c4311SfengbojiangThis function does not pop the Lua function from the stack. 2788*572c4311Sfengbojiang 2789*572c4311Sfengbojiang 2790*572c4311Sfengbojiang 2791*572c4311Sfengbojiang 2792*572c4311Sfengbojiang 2793*572c4311Sfengbojiang<hr><h3><a name="lua_equal"><code>lua_equal</code></a></h3><p> 2794*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>e</em>]</span> 2795*572c4311Sfengbojiang<pre>int lua_equal (lua_State *L, int index1, int index2);</pre> 2796*572c4311Sfengbojiang 2797*572c4311Sfengbojiang<p> 2798*572c4311SfengbojiangReturns 1 if the two values in acceptable indices <code>index1</code> and 2799*572c4311Sfengbojiang<code>index2</code> are equal, 2800*572c4311Sfengbojiangfollowing the semantics of the Lua <code>==</code> operator 2801*572c4311Sfengbojiang(that is, may call metamethods). 2802*572c4311SfengbojiangOtherwise returns 0. 2803*572c4311SfengbojiangAlso returns 0 if any of the indices is non valid. 2804*572c4311Sfengbojiang 2805*572c4311Sfengbojiang 2806*572c4311Sfengbojiang 2807*572c4311Sfengbojiang 2808*572c4311Sfengbojiang 2809*572c4311Sfengbojiang<hr><h3><a name="lua_error"><code>lua_error</code></a></h3><p> 2810*572c4311Sfengbojiang<span class="apii">[-1, +0, <em>v</em>]</span> 2811*572c4311Sfengbojiang<pre>int lua_error (lua_State *L);</pre> 2812*572c4311Sfengbojiang 2813*572c4311Sfengbojiang<p> 2814*572c4311SfengbojiangGenerates a Lua error. 2815*572c4311SfengbojiangThe error message (which can actually be a Lua value of any type) 2816*572c4311Sfengbojiangmust be on the stack top. 2817*572c4311SfengbojiangThis function does a long jump, 2818*572c4311Sfengbojiangand therefore never returns. 2819*572c4311Sfengbojiang(see <a href="#luaL_error"><code>luaL_error</code></a>). 2820*572c4311Sfengbojiang 2821*572c4311Sfengbojiang 2822*572c4311Sfengbojiang 2823*572c4311Sfengbojiang 2824*572c4311Sfengbojiang 2825*572c4311Sfengbojiang<hr><h3><a name="lua_gc"><code>lua_gc</code></a></h3><p> 2826*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>e</em>]</span> 2827*572c4311Sfengbojiang<pre>int lua_gc (lua_State *L, int what, int data);</pre> 2828*572c4311Sfengbojiang 2829*572c4311Sfengbojiang<p> 2830*572c4311SfengbojiangControls the garbage collector. 2831*572c4311Sfengbojiang 2832*572c4311Sfengbojiang 2833*572c4311Sfengbojiang<p> 2834*572c4311SfengbojiangThis function performs several tasks, 2835*572c4311Sfengbojiangaccording to the value of the parameter <code>what</code>: 2836*572c4311Sfengbojiang 2837*572c4311Sfengbojiang<ul> 2838*572c4311Sfengbojiang 2839*572c4311Sfengbojiang<li><b><code>LUA_GCSTOP</code>:</b> 2840*572c4311Sfengbojiangstops the garbage collector. 2841*572c4311Sfengbojiang</li> 2842*572c4311Sfengbojiang 2843*572c4311Sfengbojiang<li><b><code>LUA_GCRESTART</code>:</b> 2844*572c4311Sfengbojiangrestarts the garbage collector. 2845*572c4311Sfengbojiang</li> 2846*572c4311Sfengbojiang 2847*572c4311Sfengbojiang<li><b><code>LUA_GCCOLLECT</code>:</b> 2848*572c4311Sfengbojiangperforms a full garbage-collection cycle. 2849*572c4311Sfengbojiang</li> 2850*572c4311Sfengbojiang 2851*572c4311Sfengbojiang<li><b><code>LUA_GCCOUNT</code>:</b> 2852*572c4311Sfengbojiangreturns the current amount of memory (in Kbytes) in use by Lua. 2853*572c4311Sfengbojiang</li> 2854*572c4311Sfengbojiang 2855*572c4311Sfengbojiang<li><b><code>LUA_GCCOUNTB</code>:</b> 2856*572c4311Sfengbojiangreturns the remainder of dividing the current amount of bytes of 2857*572c4311Sfengbojiangmemory in use by Lua by 1024. 2858*572c4311Sfengbojiang</li> 2859*572c4311Sfengbojiang 2860*572c4311Sfengbojiang<li><b><code>LUA_GCSTEP</code>:</b> 2861*572c4311Sfengbojiangperforms an incremental step of garbage collection. 2862*572c4311SfengbojiangThe step "size" is controlled by <code>data</code> 2863*572c4311Sfengbojiang(larger values mean more steps) in a non-specified way. 2864*572c4311SfengbojiangIf you want to control the step size 2865*572c4311Sfengbojiangyou must experimentally tune the value of <code>data</code>. 2866*572c4311SfengbojiangThe function returns 1 if the step finished a 2867*572c4311Sfengbojianggarbage-collection cycle. 2868*572c4311Sfengbojiang</li> 2869*572c4311Sfengbojiang 2870*572c4311Sfengbojiang<li><b><code>LUA_GCSETPAUSE</code>:</b> 2871*572c4311Sfengbojiangsets <code>data</code> as the new value 2872*572c4311Sfengbojiangfor the <em>pause</em> of the collector (see <a href="#2.10">§2.10</a>). 2873*572c4311SfengbojiangThe function returns the previous value of the pause. 2874*572c4311Sfengbojiang</li> 2875*572c4311Sfengbojiang 2876*572c4311Sfengbojiang<li><b><code>LUA_GCSETSTEPMUL</code>:</b> 2877*572c4311Sfengbojiangsets <code>data</code> as the new value for the <em>step multiplier</em> of 2878*572c4311Sfengbojiangthe collector (see <a href="#2.10">§2.10</a>). 2879*572c4311SfengbojiangThe function returns the previous value of the step multiplier. 2880*572c4311Sfengbojiang</li> 2881*572c4311Sfengbojiang 2882*572c4311Sfengbojiang</ul> 2883*572c4311Sfengbojiang 2884*572c4311Sfengbojiang 2885*572c4311Sfengbojiang 2886*572c4311Sfengbojiang 2887*572c4311Sfengbojiang<hr><h3><a name="lua_getallocf"><code>lua_getallocf</code></a></h3><p> 2888*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>-</em>]</span> 2889*572c4311Sfengbojiang<pre>lua_Alloc lua_getallocf (lua_State *L, void **ud);</pre> 2890*572c4311Sfengbojiang 2891*572c4311Sfengbojiang<p> 2892*572c4311SfengbojiangReturns the memory-allocation function of a given state. 2893*572c4311SfengbojiangIf <code>ud</code> is not <code>NULL</code>, Lua stores in <code>*ud</code> the 2894*572c4311Sfengbojiangopaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>. 2895*572c4311Sfengbojiang 2896*572c4311Sfengbojiang 2897*572c4311Sfengbojiang 2898*572c4311Sfengbojiang 2899*572c4311Sfengbojiang 2900*572c4311Sfengbojiang<hr><h3><a name="lua_getfenv"><code>lua_getfenv</code></a></h3><p> 2901*572c4311Sfengbojiang<span class="apii">[-0, +1, <em>-</em>]</span> 2902*572c4311Sfengbojiang<pre>void lua_getfenv (lua_State *L, int index);</pre> 2903*572c4311Sfengbojiang 2904*572c4311Sfengbojiang<p> 2905*572c4311SfengbojiangPushes onto the stack the environment table of 2906*572c4311Sfengbojiangthe value at the given index. 2907*572c4311Sfengbojiang 2908*572c4311Sfengbojiang 2909*572c4311Sfengbojiang 2910*572c4311Sfengbojiang 2911*572c4311Sfengbojiang 2912*572c4311Sfengbojiang<hr><h3><a name="lua_getfield"><code>lua_getfield</code></a></h3><p> 2913*572c4311Sfengbojiang<span class="apii">[-0, +1, <em>e</em>]</span> 2914*572c4311Sfengbojiang<pre>void lua_getfield (lua_State *L, int index, const char *k);</pre> 2915*572c4311Sfengbojiang 2916*572c4311Sfengbojiang<p> 2917*572c4311SfengbojiangPushes onto the stack the value <code>t[k]</code>, 2918*572c4311Sfengbojiangwhere <code>t</code> is the value at the given valid index. 2919*572c4311SfengbojiangAs in Lua, this function may trigger a metamethod 2920*572c4311Sfengbojiangfor the "index" event (see <a href="#2.8">§2.8</a>). 2921*572c4311Sfengbojiang 2922*572c4311Sfengbojiang 2923*572c4311Sfengbojiang 2924*572c4311Sfengbojiang 2925*572c4311Sfengbojiang 2926*572c4311Sfengbojiang<hr><h3><a name="lua_getglobal"><code>lua_getglobal</code></a></h3><p> 2927*572c4311Sfengbojiang<span class="apii">[-0, +1, <em>e</em>]</span> 2928*572c4311Sfengbojiang<pre>void lua_getglobal (lua_State *L, const char *name);</pre> 2929*572c4311Sfengbojiang 2930*572c4311Sfengbojiang<p> 2931*572c4311SfengbojiangPushes onto the stack the value of the global <code>name</code>. 2932*572c4311SfengbojiangIt is defined as a macro: 2933*572c4311Sfengbojiang 2934*572c4311Sfengbojiang<pre> 2935*572c4311Sfengbojiang #define lua_getglobal(L,s) lua_getfield(L, LUA_GLOBALSINDEX, s) 2936*572c4311Sfengbojiang</pre> 2937*572c4311Sfengbojiang 2938*572c4311Sfengbojiang 2939*572c4311Sfengbojiang 2940*572c4311Sfengbojiang 2941*572c4311Sfengbojiang<hr><h3><a name="lua_getmetatable"><code>lua_getmetatable</code></a></h3><p> 2942*572c4311Sfengbojiang<span class="apii">[-0, +(0|1), <em>-</em>]</span> 2943*572c4311Sfengbojiang<pre>int lua_getmetatable (lua_State *L, int index);</pre> 2944*572c4311Sfengbojiang 2945*572c4311Sfengbojiang<p> 2946*572c4311SfengbojiangPushes onto the stack the metatable of the value at the given 2947*572c4311Sfengbojiangacceptable index. 2948*572c4311SfengbojiangIf the index is not valid, 2949*572c4311Sfengbojiangor if the value does not have a metatable, 2950*572c4311Sfengbojiangthe function returns 0 and pushes nothing on the stack. 2951*572c4311Sfengbojiang 2952*572c4311Sfengbojiang 2953*572c4311Sfengbojiang 2954*572c4311Sfengbojiang 2955*572c4311Sfengbojiang 2956*572c4311Sfengbojiang<hr><h3><a name="lua_gettable"><code>lua_gettable</code></a></h3><p> 2957*572c4311Sfengbojiang<span class="apii">[-1, +1, <em>e</em>]</span> 2958*572c4311Sfengbojiang<pre>void lua_gettable (lua_State *L, int index);</pre> 2959*572c4311Sfengbojiang 2960*572c4311Sfengbojiang<p> 2961*572c4311SfengbojiangPushes onto the stack the value <code>t[k]</code>, 2962*572c4311Sfengbojiangwhere <code>t</code> is the value at the given valid index 2963*572c4311Sfengbojiangand <code>k</code> is the value at the top of the stack. 2964*572c4311Sfengbojiang 2965*572c4311Sfengbojiang 2966*572c4311Sfengbojiang<p> 2967*572c4311SfengbojiangThis function pops the key from the stack 2968*572c4311Sfengbojiang(putting the resulting value in its place). 2969*572c4311SfengbojiangAs in Lua, this function may trigger a metamethod 2970*572c4311Sfengbojiangfor the "index" event (see <a href="#2.8">§2.8</a>). 2971*572c4311Sfengbojiang 2972*572c4311Sfengbojiang 2973*572c4311Sfengbojiang 2974*572c4311Sfengbojiang 2975*572c4311Sfengbojiang 2976*572c4311Sfengbojiang<hr><h3><a name="lua_gettop"><code>lua_gettop</code></a></h3><p> 2977*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>-</em>]</span> 2978*572c4311Sfengbojiang<pre>int lua_gettop (lua_State *L);</pre> 2979*572c4311Sfengbojiang 2980*572c4311Sfengbojiang<p> 2981*572c4311SfengbojiangReturns the index of the top element in the stack. 2982*572c4311SfengbojiangBecause indices start at 1, 2983*572c4311Sfengbojiangthis result is equal to the number of elements in the stack 2984*572c4311Sfengbojiang(and so 0 means an empty stack). 2985*572c4311Sfengbojiang 2986*572c4311Sfengbojiang 2987*572c4311Sfengbojiang 2988*572c4311Sfengbojiang 2989*572c4311Sfengbojiang 2990*572c4311Sfengbojiang<hr><h3><a name="lua_insert"><code>lua_insert</code></a></h3><p> 2991*572c4311Sfengbojiang<span class="apii">[-1, +1, <em>-</em>]</span> 2992*572c4311Sfengbojiang<pre>void lua_insert (lua_State *L, int index);</pre> 2993*572c4311Sfengbojiang 2994*572c4311Sfengbojiang<p> 2995*572c4311SfengbojiangMoves the top element into the given valid index, 2996*572c4311Sfengbojiangshifting up the elements above this index to open space. 2997*572c4311SfengbojiangCannot be called with a pseudo-index, 2998*572c4311Sfengbojiangbecause a pseudo-index is not an actual stack position. 2999*572c4311Sfengbojiang 3000*572c4311Sfengbojiang 3001*572c4311Sfengbojiang 3002*572c4311Sfengbojiang 3003*572c4311Sfengbojiang 3004*572c4311Sfengbojiang<hr><h3><a name="lua_Integer"><code>lua_Integer</code></a></h3> 3005*572c4311Sfengbojiang<pre>typedef ptrdiff_t lua_Integer;</pre> 3006*572c4311Sfengbojiang 3007*572c4311Sfengbojiang<p> 3008*572c4311SfengbojiangThe type used by the Lua API to represent integral values. 3009*572c4311Sfengbojiang 3010*572c4311Sfengbojiang 3011*572c4311Sfengbojiang<p> 3012*572c4311SfengbojiangBy default it is a <code>ptrdiff_t</code>, 3013*572c4311Sfengbojiangwhich is usually the largest signed integral type the machine handles 3014*572c4311Sfengbojiang"comfortably". 3015*572c4311Sfengbojiang 3016*572c4311Sfengbojiang 3017*572c4311Sfengbojiang 3018*572c4311Sfengbojiang 3019*572c4311Sfengbojiang 3020*572c4311Sfengbojiang<hr><h3><a name="lua_isboolean"><code>lua_isboolean</code></a></h3><p> 3021*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>-</em>]</span> 3022*572c4311Sfengbojiang<pre>int lua_isboolean (lua_State *L, int index);</pre> 3023*572c4311Sfengbojiang 3024*572c4311Sfengbojiang<p> 3025*572c4311SfengbojiangReturns 1 if the value at the given acceptable index has type boolean, 3026*572c4311Sfengbojiangand 0 otherwise. 3027*572c4311Sfengbojiang 3028*572c4311Sfengbojiang 3029*572c4311Sfengbojiang 3030*572c4311Sfengbojiang 3031*572c4311Sfengbojiang 3032*572c4311Sfengbojiang<hr><h3><a name="lua_iscfunction"><code>lua_iscfunction</code></a></h3><p> 3033*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>-</em>]</span> 3034*572c4311Sfengbojiang<pre>int lua_iscfunction (lua_State *L, int index);</pre> 3035*572c4311Sfengbojiang 3036*572c4311Sfengbojiang<p> 3037*572c4311SfengbojiangReturns 1 if the value at the given acceptable index is a C function, 3038*572c4311Sfengbojiangand 0 otherwise. 3039*572c4311Sfengbojiang 3040*572c4311Sfengbojiang 3041*572c4311Sfengbojiang 3042*572c4311Sfengbojiang 3043*572c4311Sfengbojiang 3044*572c4311Sfengbojiang<hr><h3><a name="lua_isfunction"><code>lua_isfunction</code></a></h3><p> 3045*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>-</em>]</span> 3046*572c4311Sfengbojiang<pre>int lua_isfunction (lua_State *L, int index);</pre> 3047*572c4311Sfengbojiang 3048*572c4311Sfengbojiang<p> 3049*572c4311SfengbojiangReturns 1 if the value at the given acceptable index is a function 3050*572c4311Sfengbojiang(either C or Lua), and 0 otherwise. 3051*572c4311Sfengbojiang 3052*572c4311Sfengbojiang 3053*572c4311Sfengbojiang 3054*572c4311Sfengbojiang 3055*572c4311Sfengbojiang 3056*572c4311Sfengbojiang<hr><h3><a name="lua_islightuserdata"><code>lua_islightuserdata</code></a></h3><p> 3057*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>-</em>]</span> 3058*572c4311Sfengbojiang<pre>int lua_islightuserdata (lua_State *L, int index);</pre> 3059*572c4311Sfengbojiang 3060*572c4311Sfengbojiang<p> 3061*572c4311SfengbojiangReturns 1 if the value at the given acceptable index is a light userdata, 3062*572c4311Sfengbojiangand 0 otherwise. 3063*572c4311Sfengbojiang 3064*572c4311Sfengbojiang 3065*572c4311Sfengbojiang 3066*572c4311Sfengbojiang 3067*572c4311Sfengbojiang 3068*572c4311Sfengbojiang<hr><h3><a name="lua_isnil"><code>lua_isnil</code></a></h3><p> 3069*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>-</em>]</span> 3070*572c4311Sfengbojiang<pre>int lua_isnil (lua_State *L, int index);</pre> 3071*572c4311Sfengbojiang 3072*572c4311Sfengbojiang<p> 3073*572c4311SfengbojiangReturns 1 if the value at the given acceptable index is <b>nil</b>, 3074*572c4311Sfengbojiangand 0 otherwise. 3075*572c4311Sfengbojiang 3076*572c4311Sfengbojiang 3077*572c4311Sfengbojiang 3078*572c4311Sfengbojiang 3079*572c4311Sfengbojiang 3080*572c4311Sfengbojiang<hr><h3><a name="lua_isnone"><code>lua_isnone</code></a></h3><p> 3081*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>-</em>]</span> 3082*572c4311Sfengbojiang<pre>int lua_isnone (lua_State *L, int index);</pre> 3083*572c4311Sfengbojiang 3084*572c4311Sfengbojiang<p> 3085*572c4311SfengbojiangReturns 1 if the given acceptable index is not valid 3086*572c4311Sfengbojiang(that is, it refers to an element outside the current stack), 3087*572c4311Sfengbojiangand 0 otherwise. 3088*572c4311Sfengbojiang 3089*572c4311Sfengbojiang 3090*572c4311Sfengbojiang 3091*572c4311Sfengbojiang 3092*572c4311Sfengbojiang 3093*572c4311Sfengbojiang<hr><h3><a name="lua_isnoneornil"><code>lua_isnoneornil</code></a></h3><p> 3094*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>-</em>]</span> 3095*572c4311Sfengbojiang<pre>int lua_isnoneornil (lua_State *L, int index);</pre> 3096*572c4311Sfengbojiang 3097*572c4311Sfengbojiang<p> 3098*572c4311SfengbojiangReturns 1 if the given acceptable index is not valid 3099*572c4311Sfengbojiang(that is, it refers to an element outside the current stack) 3100*572c4311Sfengbojiangor if the value at this index is <b>nil</b>, 3101*572c4311Sfengbojiangand 0 otherwise. 3102*572c4311Sfengbojiang 3103*572c4311Sfengbojiang 3104*572c4311Sfengbojiang 3105*572c4311Sfengbojiang 3106*572c4311Sfengbojiang 3107*572c4311Sfengbojiang<hr><h3><a name="lua_isnumber"><code>lua_isnumber</code></a></h3><p> 3108*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>-</em>]</span> 3109*572c4311Sfengbojiang<pre>int lua_isnumber (lua_State *L, int index);</pre> 3110*572c4311Sfengbojiang 3111*572c4311Sfengbojiang<p> 3112*572c4311SfengbojiangReturns 1 if the value at the given acceptable index is a number 3113*572c4311Sfengbojiangor a string convertible to a number, 3114*572c4311Sfengbojiangand 0 otherwise. 3115*572c4311Sfengbojiang 3116*572c4311Sfengbojiang 3117*572c4311Sfengbojiang 3118*572c4311Sfengbojiang 3119*572c4311Sfengbojiang 3120*572c4311Sfengbojiang<hr><h3><a name="lua_isstring"><code>lua_isstring</code></a></h3><p> 3121*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>-</em>]</span> 3122*572c4311Sfengbojiang<pre>int lua_isstring (lua_State *L, int index);</pre> 3123*572c4311Sfengbojiang 3124*572c4311Sfengbojiang<p> 3125*572c4311SfengbojiangReturns 1 if the value at the given acceptable index is a string 3126*572c4311Sfengbojiangor a number (which is always convertible to a string), 3127*572c4311Sfengbojiangand 0 otherwise. 3128*572c4311Sfengbojiang 3129*572c4311Sfengbojiang 3130*572c4311Sfengbojiang 3131*572c4311Sfengbojiang 3132*572c4311Sfengbojiang 3133*572c4311Sfengbojiang<hr><h3><a name="lua_istable"><code>lua_istable</code></a></h3><p> 3134*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>-</em>]</span> 3135*572c4311Sfengbojiang<pre>int lua_istable (lua_State *L, int index);</pre> 3136*572c4311Sfengbojiang 3137*572c4311Sfengbojiang<p> 3138*572c4311SfengbojiangReturns 1 if the value at the given acceptable index is a table, 3139*572c4311Sfengbojiangand 0 otherwise. 3140*572c4311Sfengbojiang 3141*572c4311Sfengbojiang 3142*572c4311Sfengbojiang 3143*572c4311Sfengbojiang 3144*572c4311Sfengbojiang 3145*572c4311Sfengbojiang<hr><h3><a name="lua_isthread"><code>lua_isthread</code></a></h3><p> 3146*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>-</em>]</span> 3147*572c4311Sfengbojiang<pre>int lua_isthread (lua_State *L, int index);</pre> 3148*572c4311Sfengbojiang 3149*572c4311Sfengbojiang<p> 3150*572c4311SfengbojiangReturns 1 if the value at the given acceptable index is a thread, 3151*572c4311Sfengbojiangand 0 otherwise. 3152*572c4311Sfengbojiang 3153*572c4311Sfengbojiang 3154*572c4311Sfengbojiang 3155*572c4311Sfengbojiang 3156*572c4311Sfengbojiang 3157*572c4311Sfengbojiang<hr><h3><a name="lua_isuserdata"><code>lua_isuserdata</code></a></h3><p> 3158*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>-</em>]</span> 3159*572c4311Sfengbojiang<pre>int lua_isuserdata (lua_State *L, int index);</pre> 3160*572c4311Sfengbojiang 3161*572c4311Sfengbojiang<p> 3162*572c4311SfengbojiangReturns 1 if the value at the given acceptable index is a userdata 3163*572c4311Sfengbojiang(either full or light), and 0 otherwise. 3164*572c4311Sfengbojiang 3165*572c4311Sfengbojiang 3166*572c4311Sfengbojiang 3167*572c4311Sfengbojiang 3168*572c4311Sfengbojiang 3169*572c4311Sfengbojiang<hr><h3><a name="lua_lessthan"><code>lua_lessthan</code></a></h3><p> 3170*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>e</em>]</span> 3171*572c4311Sfengbojiang<pre>int lua_lessthan (lua_State *L, int index1, int index2);</pre> 3172*572c4311Sfengbojiang 3173*572c4311Sfengbojiang<p> 3174*572c4311SfengbojiangReturns 1 if the value at acceptable index <code>index1</code> is smaller 3175*572c4311Sfengbojiangthan the value at acceptable index <code>index2</code>, 3176*572c4311Sfengbojiangfollowing the semantics of the Lua <code><</code> operator 3177*572c4311Sfengbojiang(that is, may call metamethods). 3178*572c4311SfengbojiangOtherwise returns 0. 3179*572c4311SfengbojiangAlso returns 0 if any of the indices is non valid. 3180*572c4311Sfengbojiang 3181*572c4311Sfengbojiang 3182*572c4311Sfengbojiang 3183*572c4311Sfengbojiang 3184*572c4311Sfengbojiang 3185*572c4311Sfengbojiang<hr><h3><a name="lua_load"><code>lua_load</code></a></h3><p> 3186*572c4311Sfengbojiang<span class="apii">[-0, +1, <em>-</em>]</span> 3187*572c4311Sfengbojiang<pre>int lua_load (lua_State *L, 3188*572c4311Sfengbojiang lua_Reader reader, 3189*572c4311Sfengbojiang void *data, 3190*572c4311Sfengbojiang const char *chunkname);</pre> 3191*572c4311Sfengbojiang 3192*572c4311Sfengbojiang<p> 3193*572c4311SfengbojiangLoads a Lua chunk. 3194*572c4311SfengbojiangIf there are no errors, 3195*572c4311Sfengbojiang<a href="#lua_load"><code>lua_load</code></a> pushes the compiled chunk as a Lua 3196*572c4311Sfengbojiangfunction on top of the stack. 3197*572c4311SfengbojiangOtherwise, it pushes an error message. 3198*572c4311SfengbojiangThe return values of <a href="#lua_load"><code>lua_load</code></a> are: 3199*572c4311Sfengbojiang 3200*572c4311Sfengbojiang<ul> 3201*572c4311Sfengbojiang 3202*572c4311Sfengbojiang<li><b>0:</b> no errors;</li> 3203*572c4311Sfengbojiang 3204*572c4311Sfengbojiang<li><b><a name="pdf-LUA_ERRSYNTAX"><code>LUA_ERRSYNTAX</code></a>:</b> 3205*572c4311Sfengbojiangsyntax error during pre-compilation;</li> 3206*572c4311Sfengbojiang 3207*572c4311Sfengbojiang<li><b><a href="#pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>:</b> 3208*572c4311Sfengbojiangmemory allocation error.</li> 3209*572c4311Sfengbojiang 3210*572c4311Sfengbojiang</ul> 3211*572c4311Sfengbojiang 3212*572c4311Sfengbojiang<p> 3213*572c4311SfengbojiangThis function only loads a chunk; 3214*572c4311Sfengbojiangit does not run it. 3215*572c4311Sfengbojiang 3216*572c4311Sfengbojiang 3217*572c4311Sfengbojiang<p> 3218*572c4311Sfengbojiang<a href="#lua_load"><code>lua_load</code></a> automatically detects whether the chunk is text or binary, 3219*572c4311Sfengbojiangand loads it accordingly (see program <code>luac</code>). 3220*572c4311Sfengbojiang 3221*572c4311Sfengbojiang 3222*572c4311Sfengbojiang<p> 3223*572c4311SfengbojiangThe <a href="#lua_load"><code>lua_load</code></a> function uses a user-supplied <code>reader</code> function 3224*572c4311Sfengbojiangto read the chunk (see <a href="#lua_Reader"><code>lua_Reader</code></a>). 3225*572c4311SfengbojiangThe <code>data</code> argument is an opaque value passed to the reader function. 3226*572c4311Sfengbojiang 3227*572c4311Sfengbojiang 3228*572c4311Sfengbojiang<p> 3229*572c4311SfengbojiangThe <code>chunkname</code> argument gives a name to the chunk, 3230*572c4311Sfengbojiangwhich is used for error messages and in debug information (see <a href="#3.8">§3.8</a>). 3231*572c4311Sfengbojiang 3232*572c4311Sfengbojiang 3233*572c4311Sfengbojiang 3234*572c4311Sfengbojiang 3235*572c4311Sfengbojiang 3236*572c4311Sfengbojiang<hr><h3><a name="lua_newstate"><code>lua_newstate</code></a></h3><p> 3237*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>-</em>]</span> 3238*572c4311Sfengbojiang<pre>lua_State *lua_newstate (lua_Alloc f, void *ud);</pre> 3239*572c4311Sfengbojiang 3240*572c4311Sfengbojiang<p> 3241*572c4311SfengbojiangCreates a new, independent state. 3242*572c4311SfengbojiangReturns <code>NULL</code> if cannot create the state 3243*572c4311Sfengbojiang(due to lack of memory). 3244*572c4311SfengbojiangThe argument <code>f</code> is the allocator function; 3245*572c4311SfengbojiangLua does all memory allocation for this state through this function. 3246*572c4311SfengbojiangThe second argument, <code>ud</code>, is an opaque pointer that Lua 3247*572c4311Sfengbojiangsimply passes to the allocator in every call. 3248*572c4311Sfengbojiang 3249*572c4311Sfengbojiang 3250*572c4311Sfengbojiang 3251*572c4311Sfengbojiang 3252*572c4311Sfengbojiang 3253*572c4311Sfengbojiang<hr><h3><a name="lua_newtable"><code>lua_newtable</code></a></h3><p> 3254*572c4311Sfengbojiang<span class="apii">[-0, +1, <em>m</em>]</span> 3255*572c4311Sfengbojiang<pre>void lua_newtable (lua_State *L);</pre> 3256*572c4311Sfengbojiang 3257*572c4311Sfengbojiang<p> 3258*572c4311SfengbojiangCreates a new empty table and pushes it onto the stack. 3259*572c4311SfengbojiangIt is equivalent to <code>lua_createtable(L, 0, 0)</code>. 3260*572c4311Sfengbojiang 3261*572c4311Sfengbojiang 3262*572c4311Sfengbojiang 3263*572c4311Sfengbojiang 3264*572c4311Sfengbojiang 3265*572c4311Sfengbojiang<hr><h3><a name="lua_newthread"><code>lua_newthread</code></a></h3><p> 3266*572c4311Sfengbojiang<span class="apii">[-0, +1, <em>m</em>]</span> 3267*572c4311Sfengbojiang<pre>lua_State *lua_newthread (lua_State *L);</pre> 3268*572c4311Sfengbojiang 3269*572c4311Sfengbojiang<p> 3270*572c4311SfengbojiangCreates a new thread, pushes it on the stack, 3271*572c4311Sfengbojiangand returns a pointer to a <a href="#lua_State"><code>lua_State</code></a> that represents this new thread. 3272*572c4311SfengbojiangThe new state returned by this function shares with the original state 3273*572c4311Sfengbojiangall global objects (such as tables), 3274*572c4311Sfengbojiangbut has an independent execution stack. 3275*572c4311Sfengbojiang 3276*572c4311Sfengbojiang 3277*572c4311Sfengbojiang<p> 3278*572c4311SfengbojiangThere is no explicit function to close or to destroy a thread. 3279*572c4311SfengbojiangThreads are subject to garbage collection, 3280*572c4311Sfengbojianglike any Lua object. 3281*572c4311Sfengbojiang 3282*572c4311Sfengbojiang 3283*572c4311Sfengbojiang 3284*572c4311Sfengbojiang 3285*572c4311Sfengbojiang 3286*572c4311Sfengbojiang<hr><h3><a name="lua_newuserdata"><code>lua_newuserdata</code></a></h3><p> 3287*572c4311Sfengbojiang<span class="apii">[-0, +1, <em>m</em>]</span> 3288*572c4311Sfengbojiang<pre>void *lua_newuserdata (lua_State *L, size_t size);</pre> 3289*572c4311Sfengbojiang 3290*572c4311Sfengbojiang<p> 3291*572c4311SfengbojiangThis function allocates a new block of memory with the given size, 3292*572c4311Sfengbojiangpushes onto the stack a new full userdata with the block address, 3293*572c4311Sfengbojiangand returns this address. 3294*572c4311Sfengbojiang 3295*572c4311Sfengbojiang 3296*572c4311Sfengbojiang<p> 3297*572c4311SfengbojiangUserdata represent C values in Lua. 3298*572c4311SfengbojiangA <em>full userdata</em> represents a block of memory. 3299*572c4311SfengbojiangIt is an object (like a table): 3300*572c4311Sfengbojiangyou must create it, it can have its own metatable, 3301*572c4311Sfengbojiangand you can detect when it is being collected. 3302*572c4311SfengbojiangA full userdata is only equal to itself (under raw equality). 3303*572c4311Sfengbojiang 3304*572c4311Sfengbojiang 3305*572c4311Sfengbojiang<p> 3306*572c4311SfengbojiangWhen Lua collects a full userdata with a <code>gc</code> metamethod, 3307*572c4311SfengbojiangLua calls the metamethod and marks the userdata as finalized. 3308*572c4311SfengbojiangWhen this userdata is collected again then 3309*572c4311SfengbojiangLua frees its corresponding memory. 3310*572c4311Sfengbojiang 3311*572c4311Sfengbojiang 3312*572c4311Sfengbojiang 3313*572c4311Sfengbojiang 3314*572c4311Sfengbojiang 3315*572c4311Sfengbojiang<hr><h3><a name="lua_next"><code>lua_next</code></a></h3><p> 3316*572c4311Sfengbojiang<span class="apii">[-1, +(2|0), <em>e</em>]</span> 3317*572c4311Sfengbojiang<pre>int lua_next (lua_State *L, int index);</pre> 3318*572c4311Sfengbojiang 3319*572c4311Sfengbojiang<p> 3320*572c4311SfengbojiangPops a key from the stack, 3321*572c4311Sfengbojiangand pushes a key-value pair from the table at the given index 3322*572c4311Sfengbojiang(the "next" pair after the given key). 3323*572c4311SfengbojiangIf there are no more elements in the table, 3324*572c4311Sfengbojiangthen <a href="#lua_next"><code>lua_next</code></a> returns 0 (and pushes nothing). 3325*572c4311Sfengbojiang 3326*572c4311Sfengbojiang 3327*572c4311Sfengbojiang<p> 3328*572c4311SfengbojiangA typical traversal looks like this: 3329*572c4311Sfengbojiang 3330*572c4311Sfengbojiang<pre> 3331*572c4311Sfengbojiang /* table is in the stack at index 't' */ 3332*572c4311Sfengbojiang lua_pushnil(L); /* first key */ 3333*572c4311Sfengbojiang while (lua_next(L, t) != 0) { 3334*572c4311Sfengbojiang /* uses 'key' (at index -2) and 'value' (at index -1) */ 3335*572c4311Sfengbojiang printf("%s - %s\n", 3336*572c4311Sfengbojiang lua_typename(L, lua_type(L, -2)), 3337*572c4311Sfengbojiang lua_typename(L, lua_type(L, -1))); 3338*572c4311Sfengbojiang /* removes 'value'; keeps 'key' for next iteration */ 3339*572c4311Sfengbojiang lua_pop(L, 1); 3340*572c4311Sfengbojiang } 3341*572c4311Sfengbojiang</pre> 3342*572c4311Sfengbojiang 3343*572c4311Sfengbojiang<p> 3344*572c4311SfengbojiangWhile traversing a table, 3345*572c4311Sfengbojiangdo not call <a href="#lua_tolstring"><code>lua_tolstring</code></a> directly on a key, 3346*572c4311Sfengbojiangunless you know that the key is actually a string. 3347*572c4311SfengbojiangRecall that <a href="#lua_tolstring"><code>lua_tolstring</code></a> <em>changes</em> 3348*572c4311Sfengbojiangthe value at the given index; 3349*572c4311Sfengbojiangthis confuses the next call to <a href="#lua_next"><code>lua_next</code></a>. 3350*572c4311Sfengbojiang 3351*572c4311Sfengbojiang 3352*572c4311Sfengbojiang 3353*572c4311Sfengbojiang 3354*572c4311Sfengbojiang 3355*572c4311Sfengbojiang<hr><h3><a name="lua_Number"><code>lua_Number</code></a></h3> 3356*572c4311Sfengbojiang<pre>typedef double lua_Number;</pre> 3357*572c4311Sfengbojiang 3358*572c4311Sfengbojiang<p> 3359*572c4311SfengbojiangThe type of numbers in Lua. 3360*572c4311SfengbojiangBy default, it is double, but that can be changed in <code>luaconf.h</code>. 3361*572c4311Sfengbojiang 3362*572c4311Sfengbojiang 3363*572c4311Sfengbojiang<p> 3364*572c4311SfengbojiangThrough the configuration file you can change 3365*572c4311SfengbojiangLua to operate with another type for numbers (e.g., float or long). 3366*572c4311Sfengbojiang 3367*572c4311Sfengbojiang 3368*572c4311Sfengbojiang 3369*572c4311Sfengbojiang 3370*572c4311Sfengbojiang 3371*572c4311Sfengbojiang<hr><h3><a name="lua_objlen"><code>lua_objlen</code></a></h3><p> 3372*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>-</em>]</span> 3373*572c4311Sfengbojiang<pre>size_t lua_objlen (lua_State *L, int index);</pre> 3374*572c4311Sfengbojiang 3375*572c4311Sfengbojiang<p> 3376*572c4311SfengbojiangReturns the "length" of the value at the given acceptable index: 3377*572c4311Sfengbojiangfor strings, this is the string length; 3378*572c4311Sfengbojiangfor tables, this is the result of the length operator ('<code>#</code>'); 3379*572c4311Sfengbojiangfor userdata, this is the size of the block of memory allocated 3380*572c4311Sfengbojiangfor the userdata; 3381*572c4311Sfengbojiangfor other values, it is 0. 3382*572c4311Sfengbojiang 3383*572c4311Sfengbojiang 3384*572c4311Sfengbojiang 3385*572c4311Sfengbojiang 3386*572c4311Sfengbojiang 3387*572c4311Sfengbojiang<hr><h3><a name="lua_pcall"><code>lua_pcall</code></a></h3><p> 3388*572c4311Sfengbojiang<span class="apii">[-(nargs + 1), +(nresults|1), <em>-</em>]</span> 3389*572c4311Sfengbojiang<pre>int lua_pcall (lua_State *L, int nargs, int nresults, int errfunc);</pre> 3390*572c4311Sfengbojiang 3391*572c4311Sfengbojiang<p> 3392*572c4311SfengbojiangCalls a function in protected mode. 3393*572c4311Sfengbojiang 3394*572c4311Sfengbojiang 3395*572c4311Sfengbojiang<p> 3396*572c4311SfengbojiangBoth <code>nargs</code> and <code>nresults</code> have the same meaning as 3397*572c4311Sfengbojiangin <a href="#lua_call"><code>lua_call</code></a>. 3398*572c4311SfengbojiangIf there are no errors during the call, 3399*572c4311Sfengbojiang<a href="#lua_pcall"><code>lua_pcall</code></a> behaves exactly like <a href="#lua_call"><code>lua_call</code></a>. 3400*572c4311SfengbojiangHowever, if there is any error, 3401*572c4311Sfengbojiang<a href="#lua_pcall"><code>lua_pcall</code></a> catches it, 3402*572c4311Sfengbojiangpushes a single value on the stack (the error message), 3403*572c4311Sfengbojiangand returns an error code. 3404*572c4311SfengbojiangLike <a href="#lua_call"><code>lua_call</code></a>, 3405*572c4311Sfengbojiang<a href="#lua_pcall"><code>lua_pcall</code></a> always removes the function 3406*572c4311Sfengbojiangand its arguments from the stack. 3407*572c4311Sfengbojiang 3408*572c4311Sfengbojiang 3409*572c4311Sfengbojiang<p> 3410*572c4311SfengbojiangIf <code>errfunc</code> is 0, 3411*572c4311Sfengbojiangthen the error message returned on the stack 3412*572c4311Sfengbojiangis exactly the original error message. 3413*572c4311SfengbojiangOtherwise, <code>errfunc</code> is the stack index of an 3414*572c4311Sfengbojiang<em>error handler function</em>. 3415*572c4311Sfengbojiang(In the current implementation, this index cannot be a pseudo-index.) 3416*572c4311SfengbojiangIn case of runtime errors, 3417*572c4311Sfengbojiangthis function will be called with the error message 3418*572c4311Sfengbojiangand its return value will be the message returned on the stack by <a href="#lua_pcall"><code>lua_pcall</code></a>. 3419*572c4311Sfengbojiang 3420*572c4311Sfengbojiang 3421*572c4311Sfengbojiang<p> 3422*572c4311SfengbojiangTypically, the error handler function is used to add more debug 3423*572c4311Sfengbojianginformation to the error message, such as a stack traceback. 3424*572c4311SfengbojiangSuch information cannot be gathered after the return of <a href="#lua_pcall"><code>lua_pcall</code></a>, 3425*572c4311Sfengbojiangsince by then the stack has unwound. 3426*572c4311Sfengbojiang 3427*572c4311Sfengbojiang 3428*572c4311Sfengbojiang<p> 3429*572c4311SfengbojiangThe <a href="#lua_pcall"><code>lua_pcall</code></a> function returns 0 in case of success 3430*572c4311Sfengbojiangor one of the following error codes 3431*572c4311Sfengbojiang(defined in <code>lua.h</code>): 3432*572c4311Sfengbojiang 3433*572c4311Sfengbojiang<ul> 3434*572c4311Sfengbojiang 3435*572c4311Sfengbojiang<li><b><a name="pdf-LUA_ERRRUN"><code>LUA_ERRRUN</code></a>:</b> 3436*572c4311Sfengbojianga runtime error. 3437*572c4311Sfengbojiang</li> 3438*572c4311Sfengbojiang 3439*572c4311Sfengbojiang<li><b><a name="pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>:</b> 3440*572c4311Sfengbojiangmemory allocation error. 3441*572c4311SfengbojiangFor such errors, Lua does not call the error handler function. 3442*572c4311Sfengbojiang</li> 3443*572c4311Sfengbojiang 3444*572c4311Sfengbojiang<li><b><a name="pdf-LUA_ERRERR"><code>LUA_ERRERR</code></a>:</b> 3445*572c4311Sfengbojiangerror while running the error handler function. 3446*572c4311Sfengbojiang</li> 3447*572c4311Sfengbojiang 3448*572c4311Sfengbojiang</ul> 3449*572c4311Sfengbojiang 3450*572c4311Sfengbojiang 3451*572c4311Sfengbojiang 3452*572c4311Sfengbojiang 3453*572c4311Sfengbojiang<hr><h3><a name="lua_pop"><code>lua_pop</code></a></h3><p> 3454*572c4311Sfengbojiang<span class="apii">[-n, +0, <em>-</em>]</span> 3455*572c4311Sfengbojiang<pre>void lua_pop (lua_State *L, int n);</pre> 3456*572c4311Sfengbojiang 3457*572c4311Sfengbojiang<p> 3458*572c4311SfengbojiangPops <code>n</code> elements from the stack. 3459*572c4311Sfengbojiang 3460*572c4311Sfengbojiang 3461*572c4311Sfengbojiang 3462*572c4311Sfengbojiang 3463*572c4311Sfengbojiang 3464*572c4311Sfengbojiang<hr><h3><a name="lua_pushboolean"><code>lua_pushboolean</code></a></h3><p> 3465*572c4311Sfengbojiang<span class="apii">[-0, +1, <em>-</em>]</span> 3466*572c4311Sfengbojiang<pre>void lua_pushboolean (lua_State *L, int b);</pre> 3467*572c4311Sfengbojiang 3468*572c4311Sfengbojiang<p> 3469*572c4311SfengbojiangPushes a boolean value with value <code>b</code> onto the stack. 3470*572c4311Sfengbojiang 3471*572c4311Sfengbojiang 3472*572c4311Sfengbojiang 3473*572c4311Sfengbojiang 3474*572c4311Sfengbojiang 3475*572c4311Sfengbojiang<hr><h3><a name="lua_pushcclosure"><code>lua_pushcclosure</code></a></h3><p> 3476*572c4311Sfengbojiang<span class="apii">[-n, +1, <em>m</em>]</span> 3477*572c4311Sfengbojiang<pre>void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);</pre> 3478*572c4311Sfengbojiang 3479*572c4311Sfengbojiang<p> 3480*572c4311SfengbojiangPushes a new C closure onto the stack. 3481*572c4311Sfengbojiang 3482*572c4311Sfengbojiang 3483*572c4311Sfengbojiang<p> 3484*572c4311SfengbojiangWhen a C function is created, 3485*572c4311Sfengbojiangit is possible to associate some values with it, 3486*572c4311Sfengbojiangthus creating a C closure (see <a href="#3.4">§3.4</a>); 3487*572c4311Sfengbojiangthese values are then accessible to the function whenever it is called. 3488*572c4311SfengbojiangTo associate values with a C function, 3489*572c4311Sfengbojiangfirst these values should be pushed onto the stack 3490*572c4311Sfengbojiang(when there are multiple values, the first value is pushed first). 3491*572c4311SfengbojiangThen <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> 3492*572c4311Sfengbojiangis called to create and push the C function onto the stack, 3493*572c4311Sfengbojiangwith the argument <code>n</code> telling how many values should be 3494*572c4311Sfengbojiangassociated with the function. 3495*572c4311Sfengbojiang<a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> also pops these values from the stack. 3496*572c4311Sfengbojiang 3497*572c4311Sfengbojiang 3498*572c4311Sfengbojiang<p> 3499*572c4311SfengbojiangThe maximum value for <code>n</code> is 255. 3500*572c4311Sfengbojiang 3501*572c4311Sfengbojiang 3502*572c4311Sfengbojiang 3503*572c4311Sfengbojiang 3504*572c4311Sfengbojiang 3505*572c4311Sfengbojiang<hr><h3><a name="lua_pushcfunction"><code>lua_pushcfunction</code></a></h3><p> 3506*572c4311Sfengbojiang<span class="apii">[-0, +1, <em>m</em>]</span> 3507*572c4311Sfengbojiang<pre>void lua_pushcfunction (lua_State *L, lua_CFunction f);</pre> 3508*572c4311Sfengbojiang 3509*572c4311Sfengbojiang<p> 3510*572c4311SfengbojiangPushes a C function onto the stack. 3511*572c4311SfengbojiangThis function receives a pointer to a C function 3512*572c4311Sfengbojiangand pushes onto the stack a Lua value of type <code>function</code> that, 3513*572c4311Sfengbojiangwhen called, invokes the corresponding C function. 3514*572c4311Sfengbojiang 3515*572c4311Sfengbojiang 3516*572c4311Sfengbojiang<p> 3517*572c4311SfengbojiangAny function to be registered in Lua must 3518*572c4311Sfengbojiangfollow the correct protocol to receive its parameters 3519*572c4311Sfengbojiangand return its results (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 3520*572c4311Sfengbojiang 3521*572c4311Sfengbojiang 3522*572c4311Sfengbojiang<p> 3523*572c4311Sfengbojiang<code>lua_pushcfunction</code> is defined as a macro: 3524*572c4311Sfengbojiang 3525*572c4311Sfengbojiang<pre> 3526*572c4311Sfengbojiang #define lua_pushcfunction(L,f) lua_pushcclosure(L,f,0) 3527*572c4311Sfengbojiang</pre> 3528*572c4311Sfengbojiang 3529*572c4311Sfengbojiang 3530*572c4311Sfengbojiang 3531*572c4311Sfengbojiang 3532*572c4311Sfengbojiang<hr><h3><a name="lua_pushfstring"><code>lua_pushfstring</code></a></h3><p> 3533*572c4311Sfengbojiang<span class="apii">[-0, +1, <em>m</em>]</span> 3534*572c4311Sfengbojiang<pre>const char *lua_pushfstring (lua_State *L, const char *fmt, ...);</pre> 3535*572c4311Sfengbojiang 3536*572c4311Sfengbojiang<p> 3537*572c4311SfengbojiangPushes onto the stack a formatted string 3538*572c4311Sfengbojiangand returns a pointer to this string. 3539*572c4311SfengbojiangIt is similar to the C function <code>sprintf</code>, 3540*572c4311Sfengbojiangbut has some important differences: 3541*572c4311Sfengbojiang 3542*572c4311Sfengbojiang<ul> 3543*572c4311Sfengbojiang 3544*572c4311Sfengbojiang<li> 3545*572c4311SfengbojiangYou do not have to allocate space for the result: 3546*572c4311Sfengbojiangthe result is a Lua string and Lua takes care of memory allocation 3547*572c4311Sfengbojiang(and deallocation, through garbage collection). 3548*572c4311Sfengbojiang</li> 3549*572c4311Sfengbojiang 3550*572c4311Sfengbojiang<li> 3551*572c4311SfengbojiangThe conversion specifiers are quite restricted. 3552*572c4311SfengbojiangThere are no flags, widths, or precisions. 3553*572c4311SfengbojiangThe conversion specifiers can only be 3554*572c4311Sfengbojiang'<code>%%</code>' (inserts a '<code>%</code>' in the string), 3555*572c4311Sfengbojiang'<code>%s</code>' (inserts a zero-terminated string, with no size restrictions), 3556*572c4311Sfengbojiang'<code>%f</code>' (inserts a <a href="#lua_Number"><code>lua_Number</code></a>), 3557*572c4311Sfengbojiang'<code>%p</code>' (inserts a pointer as a hexadecimal numeral), 3558*572c4311Sfengbojiang'<code>%d</code>' (inserts an <code>int</code>), and 3559*572c4311Sfengbojiang'<code>%c</code>' (inserts an <code>int</code> as a character). 3560*572c4311Sfengbojiang</li> 3561*572c4311Sfengbojiang 3562*572c4311Sfengbojiang</ul> 3563*572c4311Sfengbojiang 3564*572c4311Sfengbojiang 3565*572c4311Sfengbojiang 3566*572c4311Sfengbojiang 3567*572c4311Sfengbojiang<hr><h3><a name="lua_pushinteger"><code>lua_pushinteger</code></a></h3><p> 3568*572c4311Sfengbojiang<span class="apii">[-0, +1, <em>-</em>]</span> 3569*572c4311Sfengbojiang<pre>void lua_pushinteger (lua_State *L, lua_Integer n);</pre> 3570*572c4311Sfengbojiang 3571*572c4311Sfengbojiang<p> 3572*572c4311SfengbojiangPushes a number with value <code>n</code> onto the stack. 3573*572c4311Sfengbojiang 3574*572c4311Sfengbojiang 3575*572c4311Sfengbojiang 3576*572c4311Sfengbojiang 3577*572c4311Sfengbojiang 3578*572c4311Sfengbojiang<hr><h3><a name="lua_pushlightuserdata"><code>lua_pushlightuserdata</code></a></h3><p> 3579*572c4311Sfengbojiang<span class="apii">[-0, +1, <em>-</em>]</span> 3580*572c4311Sfengbojiang<pre>void lua_pushlightuserdata (lua_State *L, void *p);</pre> 3581*572c4311Sfengbojiang 3582*572c4311Sfengbojiang<p> 3583*572c4311SfengbojiangPushes a light userdata onto the stack. 3584*572c4311Sfengbojiang 3585*572c4311Sfengbojiang 3586*572c4311Sfengbojiang<p> 3587*572c4311SfengbojiangUserdata represent C values in Lua. 3588*572c4311SfengbojiangA <em>light userdata</em> represents a pointer. 3589*572c4311SfengbojiangIt is a value (like a number): 3590*572c4311Sfengbojiangyou do not create it, it has no individual metatable, 3591*572c4311Sfengbojiangand it is not collected (as it was never created). 3592*572c4311SfengbojiangA light userdata is equal to "any" 3593*572c4311Sfengbojianglight userdata with the same C address. 3594*572c4311Sfengbojiang 3595*572c4311Sfengbojiang 3596*572c4311Sfengbojiang 3597*572c4311Sfengbojiang 3598*572c4311Sfengbojiang 3599*572c4311Sfengbojiang<hr><h3><a name="lua_pushliteral"><code>lua_pushliteral</code></a></h3><p> 3600*572c4311Sfengbojiang<span class="apii">[-0, +1, <em>m</em>]</span> 3601*572c4311Sfengbojiang<pre>void lua_pushliteral (lua_State *L, const char *s);</pre> 3602*572c4311Sfengbojiang 3603*572c4311Sfengbojiang<p> 3604*572c4311SfengbojiangThis macro is equivalent to <a href="#lua_pushlstring"><code>lua_pushlstring</code></a>, 3605*572c4311Sfengbojiangbut can be used only when <code>s</code> is a literal string. 3606*572c4311SfengbojiangIn these cases, it automatically provides the string length. 3607*572c4311Sfengbojiang 3608*572c4311Sfengbojiang 3609*572c4311Sfengbojiang 3610*572c4311Sfengbojiang 3611*572c4311Sfengbojiang 3612*572c4311Sfengbojiang<hr><h3><a name="lua_pushlstring"><code>lua_pushlstring</code></a></h3><p> 3613*572c4311Sfengbojiang<span class="apii">[-0, +1, <em>m</em>]</span> 3614*572c4311Sfengbojiang<pre>void lua_pushlstring (lua_State *L, const char *s, size_t len);</pre> 3615*572c4311Sfengbojiang 3616*572c4311Sfengbojiang<p> 3617*572c4311SfengbojiangPushes the string pointed to by <code>s</code> with size <code>len</code> 3618*572c4311Sfengbojiangonto the stack. 3619*572c4311SfengbojiangLua makes (or reuses) an internal copy of the given string, 3620*572c4311Sfengbojiangso the memory at <code>s</code> can be freed or reused immediately after 3621*572c4311Sfengbojiangthe function returns. 3622*572c4311SfengbojiangThe string can contain embedded zeros. 3623*572c4311Sfengbojiang 3624*572c4311Sfengbojiang 3625*572c4311Sfengbojiang 3626*572c4311Sfengbojiang 3627*572c4311Sfengbojiang 3628*572c4311Sfengbojiang<hr><h3><a name="lua_pushnil"><code>lua_pushnil</code></a></h3><p> 3629*572c4311Sfengbojiang<span class="apii">[-0, +1, <em>-</em>]</span> 3630*572c4311Sfengbojiang<pre>void lua_pushnil (lua_State *L);</pre> 3631*572c4311Sfengbojiang 3632*572c4311Sfengbojiang<p> 3633*572c4311SfengbojiangPushes a nil value onto the stack. 3634*572c4311Sfengbojiang 3635*572c4311Sfengbojiang 3636*572c4311Sfengbojiang 3637*572c4311Sfengbojiang 3638*572c4311Sfengbojiang 3639*572c4311Sfengbojiang<hr><h3><a name="lua_pushnumber"><code>lua_pushnumber</code></a></h3><p> 3640*572c4311Sfengbojiang<span class="apii">[-0, +1, <em>-</em>]</span> 3641*572c4311Sfengbojiang<pre>void lua_pushnumber (lua_State *L, lua_Number n);</pre> 3642*572c4311Sfengbojiang 3643*572c4311Sfengbojiang<p> 3644*572c4311SfengbojiangPushes a number with value <code>n</code> onto the stack. 3645*572c4311Sfengbojiang 3646*572c4311Sfengbojiang 3647*572c4311Sfengbojiang 3648*572c4311Sfengbojiang 3649*572c4311Sfengbojiang 3650*572c4311Sfengbojiang<hr><h3><a name="lua_pushstring"><code>lua_pushstring</code></a></h3><p> 3651*572c4311Sfengbojiang<span class="apii">[-0, +1, <em>m</em>]</span> 3652*572c4311Sfengbojiang<pre>void lua_pushstring (lua_State *L, const char *s);</pre> 3653*572c4311Sfengbojiang 3654*572c4311Sfengbojiang<p> 3655*572c4311SfengbojiangPushes the zero-terminated string pointed to by <code>s</code> 3656*572c4311Sfengbojiangonto the stack. 3657*572c4311SfengbojiangLua makes (or reuses) an internal copy of the given string, 3658*572c4311Sfengbojiangso the memory at <code>s</code> can be freed or reused immediately after 3659*572c4311Sfengbojiangthe function returns. 3660*572c4311SfengbojiangThe string cannot contain embedded zeros; 3661*572c4311Sfengbojiangit is assumed to end at the first zero. 3662*572c4311Sfengbojiang 3663*572c4311Sfengbojiang 3664*572c4311Sfengbojiang 3665*572c4311Sfengbojiang 3666*572c4311Sfengbojiang 3667*572c4311Sfengbojiang<hr><h3><a name="lua_pushthread"><code>lua_pushthread</code></a></h3><p> 3668*572c4311Sfengbojiang<span class="apii">[-0, +1, <em>-</em>]</span> 3669*572c4311Sfengbojiang<pre>int lua_pushthread (lua_State *L);</pre> 3670*572c4311Sfengbojiang 3671*572c4311Sfengbojiang<p> 3672*572c4311SfengbojiangPushes the thread represented by <code>L</code> onto the stack. 3673*572c4311SfengbojiangReturns 1 if this thread is the main thread of its state. 3674*572c4311Sfengbojiang 3675*572c4311Sfengbojiang 3676*572c4311Sfengbojiang 3677*572c4311Sfengbojiang 3678*572c4311Sfengbojiang 3679*572c4311Sfengbojiang<hr><h3><a name="lua_pushvalue"><code>lua_pushvalue</code></a></h3><p> 3680*572c4311Sfengbojiang<span class="apii">[-0, +1, <em>-</em>]</span> 3681*572c4311Sfengbojiang<pre>void lua_pushvalue (lua_State *L, int index);</pre> 3682*572c4311Sfengbojiang 3683*572c4311Sfengbojiang<p> 3684*572c4311SfengbojiangPushes a copy of the element at the given valid index 3685*572c4311Sfengbojiangonto the stack. 3686*572c4311Sfengbojiang 3687*572c4311Sfengbojiang 3688*572c4311Sfengbojiang 3689*572c4311Sfengbojiang 3690*572c4311Sfengbojiang 3691*572c4311Sfengbojiang<hr><h3><a name="lua_pushvfstring"><code>lua_pushvfstring</code></a></h3><p> 3692*572c4311Sfengbojiang<span class="apii">[-0, +1, <em>m</em>]</span> 3693*572c4311Sfengbojiang<pre>const char *lua_pushvfstring (lua_State *L, 3694*572c4311Sfengbojiang const char *fmt, 3695*572c4311Sfengbojiang va_list argp);</pre> 3696*572c4311Sfengbojiang 3697*572c4311Sfengbojiang<p> 3698*572c4311SfengbojiangEquivalent to <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>, except that it receives a <code>va_list</code> 3699*572c4311Sfengbojianginstead of a variable number of arguments. 3700*572c4311Sfengbojiang 3701*572c4311Sfengbojiang 3702*572c4311Sfengbojiang 3703*572c4311Sfengbojiang 3704*572c4311Sfengbojiang 3705*572c4311Sfengbojiang<hr><h3><a name="lua_rawequal"><code>lua_rawequal</code></a></h3><p> 3706*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>-</em>]</span> 3707*572c4311Sfengbojiang<pre>int lua_rawequal (lua_State *L, int index1, int index2);</pre> 3708*572c4311Sfengbojiang 3709*572c4311Sfengbojiang<p> 3710*572c4311SfengbojiangReturns 1 if the two values in acceptable indices <code>index1</code> and 3711*572c4311Sfengbojiang<code>index2</code> are primitively equal 3712*572c4311Sfengbojiang(that is, without calling metamethods). 3713*572c4311SfengbojiangOtherwise returns 0. 3714*572c4311SfengbojiangAlso returns 0 if any of the indices are non valid. 3715*572c4311Sfengbojiang 3716*572c4311Sfengbojiang 3717*572c4311Sfengbojiang 3718*572c4311Sfengbojiang 3719*572c4311Sfengbojiang 3720*572c4311Sfengbojiang<hr><h3><a name="lua_rawget"><code>lua_rawget</code></a></h3><p> 3721*572c4311Sfengbojiang<span class="apii">[-1, +1, <em>-</em>]</span> 3722*572c4311Sfengbojiang<pre>void lua_rawget (lua_State *L, int index);</pre> 3723*572c4311Sfengbojiang 3724*572c4311Sfengbojiang<p> 3725*572c4311SfengbojiangSimilar to <a href="#lua_gettable"><code>lua_gettable</code></a>, but does a raw access 3726*572c4311Sfengbojiang(i.e., without metamethods). 3727*572c4311Sfengbojiang 3728*572c4311Sfengbojiang 3729*572c4311Sfengbojiang 3730*572c4311Sfengbojiang 3731*572c4311Sfengbojiang 3732*572c4311Sfengbojiang<hr><h3><a name="lua_rawgeti"><code>lua_rawgeti</code></a></h3><p> 3733*572c4311Sfengbojiang<span class="apii">[-0, +1, <em>-</em>]</span> 3734*572c4311Sfengbojiang<pre>void lua_rawgeti (lua_State *L, int index, int n);</pre> 3735*572c4311Sfengbojiang 3736*572c4311Sfengbojiang<p> 3737*572c4311SfengbojiangPushes onto the stack the value <code>t[n]</code>, 3738*572c4311Sfengbojiangwhere <code>t</code> is the value at the given valid index. 3739*572c4311SfengbojiangThe access is raw; 3740*572c4311Sfengbojiangthat is, it does not invoke metamethods. 3741*572c4311Sfengbojiang 3742*572c4311Sfengbojiang 3743*572c4311Sfengbojiang 3744*572c4311Sfengbojiang 3745*572c4311Sfengbojiang 3746*572c4311Sfengbojiang<hr><h3><a name="lua_rawset"><code>lua_rawset</code></a></h3><p> 3747*572c4311Sfengbojiang<span class="apii">[-2, +0, <em>m</em>]</span> 3748*572c4311Sfengbojiang<pre>void lua_rawset (lua_State *L, int index);</pre> 3749*572c4311Sfengbojiang 3750*572c4311Sfengbojiang<p> 3751*572c4311SfengbojiangSimilar to <a href="#lua_settable"><code>lua_settable</code></a>, but does a raw assignment 3752*572c4311Sfengbojiang(i.e., without metamethods). 3753*572c4311Sfengbojiang 3754*572c4311Sfengbojiang 3755*572c4311Sfengbojiang 3756*572c4311Sfengbojiang 3757*572c4311Sfengbojiang 3758*572c4311Sfengbojiang<hr><h3><a name="lua_rawseti"><code>lua_rawseti</code></a></h3><p> 3759*572c4311Sfengbojiang<span class="apii">[-1, +0, <em>m</em>]</span> 3760*572c4311Sfengbojiang<pre>void lua_rawseti (lua_State *L, int index, int n);</pre> 3761*572c4311Sfengbojiang 3762*572c4311Sfengbojiang<p> 3763*572c4311SfengbojiangDoes the equivalent of <code>t[n] = v</code>, 3764*572c4311Sfengbojiangwhere <code>t</code> is the value at the given valid index 3765*572c4311Sfengbojiangand <code>v</code> is the value at the top of the stack. 3766*572c4311Sfengbojiang 3767*572c4311Sfengbojiang 3768*572c4311Sfengbojiang<p> 3769*572c4311SfengbojiangThis function pops the value from the stack. 3770*572c4311SfengbojiangThe assignment is raw; 3771*572c4311Sfengbojiangthat is, it does not invoke metamethods. 3772*572c4311Sfengbojiang 3773*572c4311Sfengbojiang 3774*572c4311Sfengbojiang 3775*572c4311Sfengbojiang 3776*572c4311Sfengbojiang 3777*572c4311Sfengbojiang<hr><h3><a name="lua_Reader"><code>lua_Reader</code></a></h3> 3778*572c4311Sfengbojiang<pre>typedef const char * (*lua_Reader) (lua_State *L, 3779*572c4311Sfengbojiang void *data, 3780*572c4311Sfengbojiang size_t *size);</pre> 3781*572c4311Sfengbojiang 3782*572c4311Sfengbojiang<p> 3783*572c4311SfengbojiangThe reader function used by <a href="#lua_load"><code>lua_load</code></a>. 3784*572c4311SfengbojiangEvery time it needs another piece of the chunk, 3785*572c4311Sfengbojiang<a href="#lua_load"><code>lua_load</code></a> calls the reader, 3786*572c4311Sfengbojiangpassing along its <code>data</code> parameter. 3787*572c4311SfengbojiangThe reader must return a pointer to a block of memory 3788*572c4311Sfengbojiangwith a new piece of the chunk 3789*572c4311Sfengbojiangand set <code>size</code> to the block size. 3790*572c4311SfengbojiangThe block must exist until the reader function is called again. 3791*572c4311SfengbojiangTo signal the end of the chunk, 3792*572c4311Sfengbojiangthe reader must return <code>NULL</code> or set <code>size</code> to zero. 3793*572c4311SfengbojiangThe reader function may return pieces of any size greater than zero. 3794*572c4311Sfengbojiang 3795*572c4311Sfengbojiang 3796*572c4311Sfengbojiang 3797*572c4311Sfengbojiang 3798*572c4311Sfengbojiang 3799*572c4311Sfengbojiang<hr><h3><a name="lua_register"><code>lua_register</code></a></h3><p> 3800*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>e</em>]</span> 3801*572c4311Sfengbojiang<pre>void lua_register (lua_State *L, 3802*572c4311Sfengbojiang const char *name, 3803*572c4311Sfengbojiang lua_CFunction f);</pre> 3804*572c4311Sfengbojiang 3805*572c4311Sfengbojiang<p> 3806*572c4311SfengbojiangSets the C function <code>f</code> as the new value of global <code>name</code>. 3807*572c4311SfengbojiangIt is defined as a macro: 3808*572c4311Sfengbojiang 3809*572c4311Sfengbojiang<pre> 3810*572c4311Sfengbojiang #define lua_register(L,n,f) \ 3811*572c4311Sfengbojiang (lua_pushcfunction(L, f), lua_setglobal(L, n)) 3812*572c4311Sfengbojiang</pre> 3813*572c4311Sfengbojiang 3814*572c4311Sfengbojiang 3815*572c4311Sfengbojiang 3816*572c4311Sfengbojiang 3817*572c4311Sfengbojiang<hr><h3><a name="lua_remove"><code>lua_remove</code></a></h3><p> 3818*572c4311Sfengbojiang<span class="apii">[-1, +0, <em>-</em>]</span> 3819*572c4311Sfengbojiang<pre>void lua_remove (lua_State *L, int index);</pre> 3820*572c4311Sfengbojiang 3821*572c4311Sfengbojiang<p> 3822*572c4311SfengbojiangRemoves the element at the given valid index, 3823*572c4311Sfengbojiangshifting down the elements above this index to fill the gap. 3824*572c4311SfengbojiangCannot be called with a pseudo-index, 3825*572c4311Sfengbojiangbecause a pseudo-index is not an actual stack position. 3826*572c4311Sfengbojiang 3827*572c4311Sfengbojiang 3828*572c4311Sfengbojiang 3829*572c4311Sfengbojiang 3830*572c4311Sfengbojiang 3831*572c4311Sfengbojiang<hr><h3><a name="lua_replace"><code>lua_replace</code></a></h3><p> 3832*572c4311Sfengbojiang<span class="apii">[-1, +0, <em>-</em>]</span> 3833*572c4311Sfengbojiang<pre>void lua_replace (lua_State *L, int index);</pre> 3834*572c4311Sfengbojiang 3835*572c4311Sfengbojiang<p> 3836*572c4311SfengbojiangMoves the top element into the given position (and pops it), 3837*572c4311Sfengbojiangwithout shifting any element 3838*572c4311Sfengbojiang(therefore replacing the value at the given position). 3839*572c4311Sfengbojiang 3840*572c4311Sfengbojiang 3841*572c4311Sfengbojiang 3842*572c4311Sfengbojiang 3843*572c4311Sfengbojiang 3844*572c4311Sfengbojiang<hr><h3><a name="lua_resume"><code>lua_resume</code></a></h3><p> 3845*572c4311Sfengbojiang<span class="apii">[-?, +?, <em>-</em>]</span> 3846*572c4311Sfengbojiang<pre>int lua_resume (lua_State *L, int narg);</pre> 3847*572c4311Sfengbojiang 3848*572c4311Sfengbojiang<p> 3849*572c4311SfengbojiangStarts and resumes a coroutine in a given thread. 3850*572c4311Sfengbojiang 3851*572c4311Sfengbojiang 3852*572c4311Sfengbojiang<p> 3853*572c4311SfengbojiangTo start a coroutine, you first create a new thread 3854*572c4311Sfengbojiang(see <a href="#lua_newthread"><code>lua_newthread</code></a>); 3855*572c4311Sfengbojiangthen you push onto its stack the main function plus any arguments; 3856*572c4311Sfengbojiangthen you call <a href="#lua_resume"><code>lua_resume</code></a>, 3857*572c4311Sfengbojiangwith <code>narg</code> being the number of arguments. 3858*572c4311SfengbojiangThis call returns when the coroutine suspends or finishes its execution. 3859*572c4311SfengbojiangWhen it returns, the stack contains all values passed to <a href="#lua_yield"><code>lua_yield</code></a>, 3860*572c4311Sfengbojiangor all values returned by the body function. 3861*572c4311Sfengbojiang<a href="#lua_resume"><code>lua_resume</code></a> returns 3862*572c4311Sfengbojiang<a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the coroutine yields, 3863*572c4311Sfengbojiang0 if the coroutine finishes its execution 3864*572c4311Sfengbojiangwithout errors, 3865*572c4311Sfengbojiangor an error code in case of errors (see <a href="#lua_pcall"><code>lua_pcall</code></a>). 3866*572c4311SfengbojiangIn case of errors, 3867*572c4311Sfengbojiangthe stack is not unwound, 3868*572c4311Sfengbojiangso you can use the debug API over it. 3869*572c4311SfengbojiangThe error message is on the top of the stack. 3870*572c4311SfengbojiangTo restart a coroutine, you put on its stack only the values to 3871*572c4311Sfengbojiangbe passed as results from <code>yield</code>, 3872*572c4311Sfengbojiangand then call <a href="#lua_resume"><code>lua_resume</code></a>. 3873*572c4311Sfengbojiang 3874*572c4311Sfengbojiang 3875*572c4311Sfengbojiang 3876*572c4311Sfengbojiang 3877*572c4311Sfengbojiang 3878*572c4311Sfengbojiang<hr><h3><a name="lua_setallocf"><code>lua_setallocf</code></a></h3><p> 3879*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>-</em>]</span> 3880*572c4311Sfengbojiang<pre>void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);</pre> 3881*572c4311Sfengbojiang 3882*572c4311Sfengbojiang<p> 3883*572c4311SfengbojiangChanges the allocator function of a given state to <code>f</code> 3884*572c4311Sfengbojiangwith user data <code>ud</code>. 3885*572c4311Sfengbojiang 3886*572c4311Sfengbojiang 3887*572c4311Sfengbojiang 3888*572c4311Sfengbojiang 3889*572c4311Sfengbojiang 3890*572c4311Sfengbojiang<hr><h3><a name="lua_setfenv"><code>lua_setfenv</code></a></h3><p> 3891*572c4311Sfengbojiang<span class="apii">[-1, +0, <em>-</em>]</span> 3892*572c4311Sfengbojiang<pre>int lua_setfenv (lua_State *L, int index);</pre> 3893*572c4311Sfengbojiang 3894*572c4311Sfengbojiang<p> 3895*572c4311SfengbojiangPops a table from the stack and sets it as 3896*572c4311Sfengbojiangthe new environment for the value at the given index. 3897*572c4311SfengbojiangIf the value at the given index is 3898*572c4311Sfengbojiangneither a function nor a thread nor a userdata, 3899*572c4311Sfengbojiang<a href="#lua_setfenv"><code>lua_setfenv</code></a> returns 0. 3900*572c4311SfengbojiangOtherwise it returns 1. 3901*572c4311Sfengbojiang 3902*572c4311Sfengbojiang 3903*572c4311Sfengbojiang 3904*572c4311Sfengbojiang 3905*572c4311Sfengbojiang 3906*572c4311Sfengbojiang<hr><h3><a name="lua_setfield"><code>lua_setfield</code></a></h3><p> 3907*572c4311Sfengbojiang<span class="apii">[-1, +0, <em>e</em>]</span> 3908*572c4311Sfengbojiang<pre>void lua_setfield (lua_State *L, int index, const char *k);</pre> 3909*572c4311Sfengbojiang 3910*572c4311Sfengbojiang<p> 3911*572c4311SfengbojiangDoes the equivalent to <code>t[k] = v</code>, 3912*572c4311Sfengbojiangwhere <code>t</code> is the value at the given valid index 3913*572c4311Sfengbojiangand <code>v</code> is the value at the top of the stack. 3914*572c4311Sfengbojiang 3915*572c4311Sfengbojiang 3916*572c4311Sfengbojiang<p> 3917*572c4311SfengbojiangThis function pops the value from the stack. 3918*572c4311SfengbojiangAs in Lua, this function may trigger a metamethod 3919*572c4311Sfengbojiangfor the "newindex" event (see <a href="#2.8">§2.8</a>). 3920*572c4311Sfengbojiang 3921*572c4311Sfengbojiang 3922*572c4311Sfengbojiang 3923*572c4311Sfengbojiang 3924*572c4311Sfengbojiang 3925*572c4311Sfengbojiang<hr><h3><a name="lua_setglobal"><code>lua_setglobal</code></a></h3><p> 3926*572c4311Sfengbojiang<span class="apii">[-1, +0, <em>e</em>]</span> 3927*572c4311Sfengbojiang<pre>void lua_setglobal (lua_State *L, const char *name);</pre> 3928*572c4311Sfengbojiang 3929*572c4311Sfengbojiang<p> 3930*572c4311SfengbojiangPops a value from the stack and 3931*572c4311Sfengbojiangsets it as the new value of global <code>name</code>. 3932*572c4311SfengbojiangIt is defined as a macro: 3933*572c4311Sfengbojiang 3934*572c4311Sfengbojiang<pre> 3935*572c4311Sfengbojiang #define lua_setglobal(L,s) lua_setfield(L, LUA_GLOBALSINDEX, s) 3936*572c4311Sfengbojiang</pre> 3937*572c4311Sfengbojiang 3938*572c4311Sfengbojiang 3939*572c4311Sfengbojiang 3940*572c4311Sfengbojiang 3941*572c4311Sfengbojiang<hr><h3><a name="lua_setmetatable"><code>lua_setmetatable</code></a></h3><p> 3942*572c4311Sfengbojiang<span class="apii">[-1, +0, <em>-</em>]</span> 3943*572c4311Sfengbojiang<pre>int lua_setmetatable (lua_State *L, int index);</pre> 3944*572c4311Sfengbojiang 3945*572c4311Sfengbojiang<p> 3946*572c4311SfengbojiangPops a table from the stack and 3947*572c4311Sfengbojiangsets it as the new metatable for the value at the given 3948*572c4311Sfengbojiangacceptable index. 3949*572c4311Sfengbojiang 3950*572c4311Sfengbojiang 3951*572c4311Sfengbojiang 3952*572c4311Sfengbojiang 3953*572c4311Sfengbojiang 3954*572c4311Sfengbojiang<hr><h3><a name="lua_settable"><code>lua_settable</code></a></h3><p> 3955*572c4311Sfengbojiang<span class="apii">[-2, +0, <em>e</em>]</span> 3956*572c4311Sfengbojiang<pre>void lua_settable (lua_State *L, int index);</pre> 3957*572c4311Sfengbojiang 3958*572c4311Sfengbojiang<p> 3959*572c4311SfengbojiangDoes the equivalent to <code>t[k] = v</code>, 3960*572c4311Sfengbojiangwhere <code>t</code> is the value at the given valid index, 3961*572c4311Sfengbojiang<code>v</code> is the value at the top of the stack, 3962*572c4311Sfengbojiangand <code>k</code> is the value just below the top. 3963*572c4311Sfengbojiang 3964*572c4311Sfengbojiang 3965*572c4311Sfengbojiang<p> 3966*572c4311SfengbojiangThis function pops both the key and the value from the stack. 3967*572c4311SfengbojiangAs in Lua, this function may trigger a metamethod 3968*572c4311Sfengbojiangfor the "newindex" event (see <a href="#2.8">§2.8</a>). 3969*572c4311Sfengbojiang 3970*572c4311Sfengbojiang 3971*572c4311Sfengbojiang 3972*572c4311Sfengbojiang 3973*572c4311Sfengbojiang 3974*572c4311Sfengbojiang<hr><h3><a name="lua_settop"><code>lua_settop</code></a></h3><p> 3975*572c4311Sfengbojiang<span class="apii">[-?, +?, <em>-</em>]</span> 3976*572c4311Sfengbojiang<pre>void lua_settop (lua_State *L, int index);</pre> 3977*572c4311Sfengbojiang 3978*572c4311Sfengbojiang<p> 3979*572c4311SfengbojiangAccepts any acceptable index, or 0, 3980*572c4311Sfengbojiangand sets the stack top to this index. 3981*572c4311SfengbojiangIf the new top is larger than the old one, 3982*572c4311Sfengbojiangthen the new elements are filled with <b>nil</b>. 3983*572c4311SfengbojiangIf <code>index</code> is 0, then all stack elements are removed. 3984*572c4311Sfengbojiang 3985*572c4311Sfengbojiang 3986*572c4311Sfengbojiang 3987*572c4311Sfengbojiang 3988*572c4311Sfengbojiang 3989*572c4311Sfengbojiang<hr><h3><a name="lua_State"><code>lua_State</code></a></h3> 3990*572c4311Sfengbojiang<pre>typedef struct lua_State lua_State;</pre> 3991*572c4311Sfengbojiang 3992*572c4311Sfengbojiang<p> 3993*572c4311SfengbojiangOpaque structure that keeps the whole state of a Lua interpreter. 3994*572c4311SfengbojiangThe Lua library is fully reentrant: 3995*572c4311Sfengbojiangit has no global variables. 3996*572c4311SfengbojiangAll information about a state is kept in this structure. 3997*572c4311Sfengbojiang 3998*572c4311Sfengbojiang 3999*572c4311Sfengbojiang<p> 4000*572c4311SfengbojiangA pointer to this state must be passed as the first argument to 4001*572c4311Sfengbojiangevery function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>, 4002*572c4311Sfengbojiangwhich creates a Lua state from scratch. 4003*572c4311Sfengbojiang 4004*572c4311Sfengbojiang 4005*572c4311Sfengbojiang 4006*572c4311Sfengbojiang 4007*572c4311Sfengbojiang 4008*572c4311Sfengbojiang<hr><h3><a name="lua_status"><code>lua_status</code></a></h3><p> 4009*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>-</em>]</span> 4010*572c4311Sfengbojiang<pre>int lua_status (lua_State *L);</pre> 4011*572c4311Sfengbojiang 4012*572c4311Sfengbojiang<p> 4013*572c4311SfengbojiangReturns the status of the thread <code>L</code>. 4014*572c4311Sfengbojiang 4015*572c4311Sfengbojiang 4016*572c4311Sfengbojiang<p> 4017*572c4311SfengbojiangThe status can be 0 for a normal thread, 4018*572c4311Sfengbojiangan error code if the thread finished its execution with an error, 4019*572c4311Sfengbojiangor <a name="pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the thread is suspended. 4020*572c4311Sfengbojiang 4021*572c4311Sfengbojiang 4022*572c4311Sfengbojiang 4023*572c4311Sfengbojiang 4024*572c4311Sfengbojiang 4025*572c4311Sfengbojiang<hr><h3><a name="lua_toboolean"><code>lua_toboolean</code></a></h3><p> 4026*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>-</em>]</span> 4027*572c4311Sfengbojiang<pre>int lua_toboolean (lua_State *L, int index);</pre> 4028*572c4311Sfengbojiang 4029*572c4311Sfengbojiang<p> 4030*572c4311SfengbojiangConverts the Lua value at the given acceptable index to a C boolean 4031*572c4311Sfengbojiangvalue (0 or 1). 4032*572c4311SfengbojiangLike all tests in Lua, 4033*572c4311Sfengbojiang<a href="#lua_toboolean"><code>lua_toboolean</code></a> returns 1 for any Lua value 4034*572c4311Sfengbojiangdifferent from <b>false</b> and <b>nil</b>; 4035*572c4311Sfengbojiangotherwise it returns 0. 4036*572c4311SfengbojiangIt also returns 0 when called with a non-valid index. 4037*572c4311Sfengbojiang(If you want to accept only actual boolean values, 4038*572c4311Sfengbojianguse <a href="#lua_isboolean"><code>lua_isboolean</code></a> to test the value's type.) 4039*572c4311Sfengbojiang 4040*572c4311Sfengbojiang 4041*572c4311Sfengbojiang 4042*572c4311Sfengbojiang 4043*572c4311Sfengbojiang 4044*572c4311Sfengbojiang<hr><h3><a name="lua_tocfunction"><code>lua_tocfunction</code></a></h3><p> 4045*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>-</em>]</span> 4046*572c4311Sfengbojiang<pre>lua_CFunction lua_tocfunction (lua_State *L, int index);</pre> 4047*572c4311Sfengbojiang 4048*572c4311Sfengbojiang<p> 4049*572c4311SfengbojiangConverts a value at the given acceptable index to a C function. 4050*572c4311SfengbojiangThat value must be a C function; 4051*572c4311Sfengbojiangotherwise, returns <code>NULL</code>. 4052*572c4311Sfengbojiang 4053*572c4311Sfengbojiang 4054*572c4311Sfengbojiang 4055*572c4311Sfengbojiang 4056*572c4311Sfengbojiang 4057*572c4311Sfengbojiang<hr><h3><a name="lua_tointeger"><code>lua_tointeger</code></a></h3><p> 4058*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>-</em>]</span> 4059*572c4311Sfengbojiang<pre>lua_Integer lua_tointeger (lua_State *L, int index);</pre> 4060*572c4311Sfengbojiang 4061*572c4311Sfengbojiang<p> 4062*572c4311SfengbojiangConverts the Lua value at the given acceptable index 4063*572c4311Sfengbojiangto the signed integral type <a href="#lua_Integer"><code>lua_Integer</code></a>. 4064*572c4311SfengbojiangThe Lua value must be a number or a string convertible to a number 4065*572c4311Sfengbojiang(see <a href="#2.2.1">§2.2.1</a>); 4066*572c4311Sfengbojiangotherwise, <a href="#lua_tointeger"><code>lua_tointeger</code></a> returns 0. 4067*572c4311Sfengbojiang 4068*572c4311Sfengbojiang 4069*572c4311Sfengbojiang<p> 4070*572c4311SfengbojiangIf the number is not an integer, 4071*572c4311Sfengbojiangit is truncated in some non-specified way. 4072*572c4311Sfengbojiang 4073*572c4311Sfengbojiang 4074*572c4311Sfengbojiang 4075*572c4311Sfengbojiang 4076*572c4311Sfengbojiang 4077*572c4311Sfengbojiang<hr><h3><a name="lua_tolstring"><code>lua_tolstring</code></a></h3><p> 4078*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>m</em>]</span> 4079*572c4311Sfengbojiang<pre>const char *lua_tolstring (lua_State *L, int index, size_t *len);</pre> 4080*572c4311Sfengbojiang 4081*572c4311Sfengbojiang<p> 4082*572c4311SfengbojiangConverts the Lua value at the given acceptable index to a C string. 4083*572c4311SfengbojiangIf <code>len</code> is not <code>NULL</code>, 4084*572c4311Sfengbojiangit also sets <code>*len</code> with the string length. 4085*572c4311SfengbojiangThe Lua value must be a string or a number; 4086*572c4311Sfengbojiangotherwise, the function returns <code>NULL</code>. 4087*572c4311SfengbojiangIf the value is a number, 4088*572c4311Sfengbojiangthen <a href="#lua_tolstring"><code>lua_tolstring</code></a> also 4089*572c4311Sfengbojiang<em>changes the actual value in the stack to a string</em>. 4090*572c4311Sfengbojiang(This change confuses <a href="#lua_next"><code>lua_next</code></a> 4091*572c4311Sfengbojiangwhen <a href="#lua_tolstring"><code>lua_tolstring</code></a> is applied to keys during a table traversal.) 4092*572c4311Sfengbojiang 4093*572c4311Sfengbojiang 4094*572c4311Sfengbojiang<p> 4095*572c4311Sfengbojiang<a href="#lua_tolstring"><code>lua_tolstring</code></a> returns a fully aligned pointer 4096*572c4311Sfengbojiangto a string inside the Lua state. 4097*572c4311SfengbojiangThis string always has a zero ('<code>\0</code>') 4098*572c4311Sfengbojiangafter its last character (as in C), 4099*572c4311Sfengbojiangbut can contain other zeros in its body. 4100*572c4311SfengbojiangBecause Lua has garbage collection, 4101*572c4311Sfengbojiangthere is no guarantee that the pointer returned by <a href="#lua_tolstring"><code>lua_tolstring</code></a> 4102*572c4311Sfengbojiangwill be valid after the corresponding value is removed from the stack. 4103*572c4311Sfengbojiang 4104*572c4311Sfengbojiang 4105*572c4311Sfengbojiang 4106*572c4311Sfengbojiang 4107*572c4311Sfengbojiang 4108*572c4311Sfengbojiang<hr><h3><a name="lua_tonumber"><code>lua_tonumber</code></a></h3><p> 4109*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>-</em>]</span> 4110*572c4311Sfengbojiang<pre>lua_Number lua_tonumber (lua_State *L, int index);</pre> 4111*572c4311Sfengbojiang 4112*572c4311Sfengbojiang<p> 4113*572c4311SfengbojiangConverts the Lua value at the given acceptable index 4114*572c4311Sfengbojiangto the C type <a href="#lua_Number"><code>lua_Number</code></a> (see <a href="#lua_Number"><code>lua_Number</code></a>). 4115*572c4311SfengbojiangThe Lua value must be a number or a string convertible to a number 4116*572c4311Sfengbojiang(see <a href="#2.2.1">§2.2.1</a>); 4117*572c4311Sfengbojiangotherwise, <a href="#lua_tonumber"><code>lua_tonumber</code></a> returns 0. 4118*572c4311Sfengbojiang 4119*572c4311Sfengbojiang 4120*572c4311Sfengbojiang 4121*572c4311Sfengbojiang 4122*572c4311Sfengbojiang 4123*572c4311Sfengbojiang<hr><h3><a name="lua_topointer"><code>lua_topointer</code></a></h3><p> 4124*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>-</em>]</span> 4125*572c4311Sfengbojiang<pre>const void *lua_topointer (lua_State *L, int index);</pre> 4126*572c4311Sfengbojiang 4127*572c4311Sfengbojiang<p> 4128*572c4311SfengbojiangConverts the value at the given acceptable index to a generic 4129*572c4311SfengbojiangC pointer (<code>void*</code>). 4130*572c4311SfengbojiangThe value can be a userdata, a table, a thread, or a function; 4131*572c4311Sfengbojiangotherwise, <a href="#lua_topointer"><code>lua_topointer</code></a> returns <code>NULL</code>. 4132*572c4311SfengbojiangDifferent objects will give different pointers. 4133*572c4311SfengbojiangThere is no way to convert the pointer back to its original value. 4134*572c4311Sfengbojiang 4135*572c4311Sfengbojiang 4136*572c4311Sfengbojiang<p> 4137*572c4311SfengbojiangTypically this function is used only for debug information. 4138*572c4311Sfengbojiang 4139*572c4311Sfengbojiang 4140*572c4311Sfengbojiang 4141*572c4311Sfengbojiang 4142*572c4311Sfengbojiang 4143*572c4311Sfengbojiang<hr><h3><a name="lua_tostring"><code>lua_tostring</code></a></h3><p> 4144*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>m</em>]</span> 4145*572c4311Sfengbojiang<pre>const char *lua_tostring (lua_State *L, int index);</pre> 4146*572c4311Sfengbojiang 4147*572c4311Sfengbojiang<p> 4148*572c4311SfengbojiangEquivalent to <a href="#lua_tolstring"><code>lua_tolstring</code></a> with <code>len</code> equal to <code>NULL</code>. 4149*572c4311Sfengbojiang 4150*572c4311Sfengbojiang 4151*572c4311Sfengbojiang 4152*572c4311Sfengbojiang 4153*572c4311Sfengbojiang 4154*572c4311Sfengbojiang<hr><h3><a name="lua_tothread"><code>lua_tothread</code></a></h3><p> 4155*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>-</em>]</span> 4156*572c4311Sfengbojiang<pre>lua_State *lua_tothread (lua_State *L, int index);</pre> 4157*572c4311Sfengbojiang 4158*572c4311Sfengbojiang<p> 4159*572c4311SfengbojiangConverts the value at the given acceptable index to a Lua thread 4160*572c4311Sfengbojiang(represented as <code>lua_State*</code>). 4161*572c4311SfengbojiangThis value must be a thread; 4162*572c4311Sfengbojiangotherwise, the function returns <code>NULL</code>. 4163*572c4311Sfengbojiang 4164*572c4311Sfengbojiang 4165*572c4311Sfengbojiang 4166*572c4311Sfengbojiang 4167*572c4311Sfengbojiang 4168*572c4311Sfengbojiang<hr><h3><a name="lua_touserdata"><code>lua_touserdata</code></a></h3><p> 4169*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>-</em>]</span> 4170*572c4311Sfengbojiang<pre>void *lua_touserdata (lua_State *L, int index);</pre> 4171*572c4311Sfengbojiang 4172*572c4311Sfengbojiang<p> 4173*572c4311SfengbojiangIf the value at the given acceptable index is a full userdata, 4174*572c4311Sfengbojiangreturns its block address. 4175*572c4311SfengbojiangIf the value is a light userdata, 4176*572c4311Sfengbojiangreturns its pointer. 4177*572c4311SfengbojiangOtherwise, returns <code>NULL</code>. 4178*572c4311Sfengbojiang 4179*572c4311Sfengbojiang 4180*572c4311Sfengbojiang 4181*572c4311Sfengbojiang 4182*572c4311Sfengbojiang 4183*572c4311Sfengbojiang<hr><h3><a name="lua_type"><code>lua_type</code></a></h3><p> 4184*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>-</em>]</span> 4185*572c4311Sfengbojiang<pre>int lua_type (lua_State *L, int index);</pre> 4186*572c4311Sfengbojiang 4187*572c4311Sfengbojiang<p> 4188*572c4311SfengbojiangReturns the type of the value in the given acceptable index, 4189*572c4311Sfengbojiangor <code>LUA_TNONE</code> for a non-valid index 4190*572c4311Sfengbojiang(that is, an index to an "empty" stack position). 4191*572c4311SfengbojiangThe types returned by <a href="#lua_type"><code>lua_type</code></a> are coded by the following constants 4192*572c4311Sfengbojiangdefined in <code>lua.h</code>: 4193*572c4311Sfengbojiang<code>LUA_TNIL</code>, 4194*572c4311Sfengbojiang<code>LUA_TNUMBER</code>, 4195*572c4311Sfengbojiang<code>LUA_TBOOLEAN</code>, 4196*572c4311Sfengbojiang<code>LUA_TSTRING</code>, 4197*572c4311Sfengbojiang<code>LUA_TTABLE</code>, 4198*572c4311Sfengbojiang<code>LUA_TFUNCTION</code>, 4199*572c4311Sfengbojiang<code>LUA_TUSERDATA</code>, 4200*572c4311Sfengbojiang<code>LUA_TTHREAD</code>, 4201*572c4311Sfengbojiangand 4202*572c4311Sfengbojiang<code>LUA_TLIGHTUSERDATA</code>. 4203*572c4311Sfengbojiang 4204*572c4311Sfengbojiang 4205*572c4311Sfengbojiang 4206*572c4311Sfengbojiang 4207*572c4311Sfengbojiang 4208*572c4311Sfengbojiang<hr><h3><a name="lua_typename"><code>lua_typename</code></a></h3><p> 4209*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>-</em>]</span> 4210*572c4311Sfengbojiang<pre>const char *lua_typename (lua_State *L, int tp);</pre> 4211*572c4311Sfengbojiang 4212*572c4311Sfengbojiang<p> 4213*572c4311SfengbojiangReturns the name of the type encoded by the value <code>tp</code>, 4214*572c4311Sfengbojiangwhich must be one the values returned by <a href="#lua_type"><code>lua_type</code></a>. 4215*572c4311Sfengbojiang 4216*572c4311Sfengbojiang 4217*572c4311Sfengbojiang 4218*572c4311Sfengbojiang 4219*572c4311Sfengbojiang 4220*572c4311Sfengbojiang<hr><h3><a name="lua_Writer"><code>lua_Writer</code></a></h3> 4221*572c4311Sfengbojiang<pre>typedef int (*lua_Writer) (lua_State *L, 4222*572c4311Sfengbojiang const void* p, 4223*572c4311Sfengbojiang size_t sz, 4224*572c4311Sfengbojiang void* ud);</pre> 4225*572c4311Sfengbojiang 4226*572c4311Sfengbojiang<p> 4227*572c4311SfengbojiangThe type of the writer function used by <a href="#lua_dump"><code>lua_dump</code></a>. 4228*572c4311SfengbojiangEvery time it produces another piece of chunk, 4229*572c4311Sfengbojiang<a href="#lua_dump"><code>lua_dump</code></a> calls the writer, 4230*572c4311Sfengbojiangpassing along the buffer to be written (<code>p</code>), 4231*572c4311Sfengbojiangits size (<code>sz</code>), 4232*572c4311Sfengbojiangand the <code>data</code> parameter supplied to <a href="#lua_dump"><code>lua_dump</code></a>. 4233*572c4311Sfengbojiang 4234*572c4311Sfengbojiang 4235*572c4311Sfengbojiang<p> 4236*572c4311SfengbojiangThe writer returns an error code: 4237*572c4311Sfengbojiang0 means no errors; 4238*572c4311Sfengbojiangany other value means an error and stops <a href="#lua_dump"><code>lua_dump</code></a> from 4239*572c4311Sfengbojiangcalling the writer again. 4240*572c4311Sfengbojiang 4241*572c4311Sfengbojiang 4242*572c4311Sfengbojiang 4243*572c4311Sfengbojiang 4244*572c4311Sfengbojiang 4245*572c4311Sfengbojiang<hr><h3><a name="lua_xmove"><code>lua_xmove</code></a></h3><p> 4246*572c4311Sfengbojiang<span class="apii">[-?, +?, <em>-</em>]</span> 4247*572c4311Sfengbojiang<pre>void lua_xmove (lua_State *from, lua_State *to, int n);</pre> 4248*572c4311Sfengbojiang 4249*572c4311Sfengbojiang<p> 4250*572c4311SfengbojiangExchange values between different threads of the <em>same</em> global state. 4251*572c4311Sfengbojiang 4252*572c4311Sfengbojiang 4253*572c4311Sfengbojiang<p> 4254*572c4311SfengbojiangThis function pops <code>n</code> values from the stack <code>from</code>, 4255*572c4311Sfengbojiangand pushes them onto the stack <code>to</code>. 4256*572c4311Sfengbojiang 4257*572c4311Sfengbojiang 4258*572c4311Sfengbojiang 4259*572c4311Sfengbojiang 4260*572c4311Sfengbojiang 4261*572c4311Sfengbojiang<hr><h3><a name="lua_yield"><code>lua_yield</code></a></h3><p> 4262*572c4311Sfengbojiang<span class="apii">[-?, +?, <em>-</em>]</span> 4263*572c4311Sfengbojiang<pre>int lua_yield (lua_State *L, int nresults);</pre> 4264*572c4311Sfengbojiang 4265*572c4311Sfengbojiang<p> 4266*572c4311SfengbojiangYields a coroutine. 4267*572c4311Sfengbojiang 4268*572c4311Sfengbojiang 4269*572c4311Sfengbojiang<p> 4270*572c4311SfengbojiangThis function should only be called as the 4271*572c4311Sfengbojiangreturn expression of a C function, as follows: 4272*572c4311Sfengbojiang 4273*572c4311Sfengbojiang<pre> 4274*572c4311Sfengbojiang return lua_yield (L, nresults); 4275*572c4311Sfengbojiang</pre><p> 4276*572c4311SfengbojiangWhen a C function calls <a href="#lua_yield"><code>lua_yield</code></a> in that way, 4277*572c4311Sfengbojiangthe running coroutine suspends its execution, 4278*572c4311Sfengbojiangand the call to <a href="#lua_resume"><code>lua_resume</code></a> that started this coroutine returns. 4279*572c4311SfengbojiangThe parameter <code>nresults</code> is the number of values from the stack 4280*572c4311Sfengbojiangthat are passed as results to <a href="#lua_resume"><code>lua_resume</code></a>. 4281*572c4311Sfengbojiang 4282*572c4311Sfengbojiang 4283*572c4311Sfengbojiang 4284*572c4311Sfengbojiang 4285*572c4311Sfengbojiang 4286*572c4311Sfengbojiang 4287*572c4311Sfengbojiang 4288*572c4311Sfengbojiang<h2>3.8 - <a name="3.8">The Debug Interface</a></h2> 4289*572c4311Sfengbojiang 4290*572c4311Sfengbojiang<p> 4291*572c4311SfengbojiangLua has no built-in debugging facilities. 4292*572c4311SfengbojiangInstead, it offers a special interface 4293*572c4311Sfengbojiangby means of functions and <em>hooks</em>. 4294*572c4311SfengbojiangThis interface allows the construction of different 4295*572c4311Sfengbojiangkinds of debuggers, profilers, and other tools 4296*572c4311Sfengbojiangthat need "inside information" from the interpreter. 4297*572c4311Sfengbojiang 4298*572c4311Sfengbojiang 4299*572c4311Sfengbojiang 4300*572c4311Sfengbojiang<hr><h3><a name="lua_Debug"><code>lua_Debug</code></a></h3> 4301*572c4311Sfengbojiang<pre>typedef struct lua_Debug { 4302*572c4311Sfengbojiang int event; 4303*572c4311Sfengbojiang const char *name; /* (n) */ 4304*572c4311Sfengbojiang const char *namewhat; /* (n) */ 4305*572c4311Sfengbojiang const char *what; /* (S) */ 4306*572c4311Sfengbojiang const char *source; /* (S) */ 4307*572c4311Sfengbojiang int currentline; /* (l) */ 4308*572c4311Sfengbojiang int nups; /* (u) number of upvalues */ 4309*572c4311Sfengbojiang int linedefined; /* (S) */ 4310*572c4311Sfengbojiang int lastlinedefined; /* (S) */ 4311*572c4311Sfengbojiang char short_src[LUA_IDSIZE]; /* (S) */ 4312*572c4311Sfengbojiang /* private part */ 4313*572c4311Sfengbojiang <em>other fields</em> 4314*572c4311Sfengbojiang} lua_Debug;</pre> 4315*572c4311Sfengbojiang 4316*572c4311Sfengbojiang<p> 4317*572c4311SfengbojiangA structure used to carry different pieces of 4318*572c4311Sfengbojianginformation about an active function. 4319*572c4311Sfengbojiang<a href="#lua_getstack"><code>lua_getstack</code></a> fills only the private part 4320*572c4311Sfengbojiangof this structure, for later use. 4321*572c4311SfengbojiangTo fill the other fields of <a href="#lua_Debug"><code>lua_Debug</code></a> with useful information, 4322*572c4311Sfengbojiangcall <a href="#lua_getinfo"><code>lua_getinfo</code></a>. 4323*572c4311Sfengbojiang 4324*572c4311Sfengbojiang 4325*572c4311Sfengbojiang<p> 4326*572c4311SfengbojiangThe fields of <a href="#lua_Debug"><code>lua_Debug</code></a> have the following meaning: 4327*572c4311Sfengbojiang 4328*572c4311Sfengbojiang<ul> 4329*572c4311Sfengbojiang 4330*572c4311Sfengbojiang<li><b><code>source</code>:</b> 4331*572c4311SfengbojiangIf the function was defined in a string, 4332*572c4311Sfengbojiangthen <code>source</code> is that string. 4333*572c4311SfengbojiangIf the function was defined in a file, 4334*572c4311Sfengbojiangthen <code>source</code> starts with a '<code>@</code>' followed by the file name. 4335*572c4311Sfengbojiang</li> 4336*572c4311Sfengbojiang 4337*572c4311Sfengbojiang<li><b><code>short_src</code>:</b> 4338*572c4311Sfengbojianga "printable" version of <code>source</code>, to be used in error messages. 4339*572c4311Sfengbojiang</li> 4340*572c4311Sfengbojiang 4341*572c4311Sfengbojiang<li><b><code>linedefined</code>:</b> 4342*572c4311Sfengbojiangthe line number where the definition of the function starts. 4343*572c4311Sfengbojiang</li> 4344*572c4311Sfengbojiang 4345*572c4311Sfengbojiang<li><b><code>lastlinedefined</code>:</b> 4346*572c4311Sfengbojiangthe line number where the definition of the function ends. 4347*572c4311Sfengbojiang</li> 4348*572c4311Sfengbojiang 4349*572c4311Sfengbojiang<li><b><code>what</code>:</b> 4350*572c4311Sfengbojiangthe string <code>"Lua"</code> if the function is a Lua function, 4351*572c4311Sfengbojiang<code>"C"</code> if it is a C function, 4352*572c4311Sfengbojiang<code>"main"</code> if it is the main part of a chunk, 4353*572c4311Sfengbojiangand <code>"tail"</code> if it was a function that did a tail call. 4354*572c4311SfengbojiangIn the latter case, 4355*572c4311SfengbojiangLua has no other information about the function. 4356*572c4311Sfengbojiang</li> 4357*572c4311Sfengbojiang 4358*572c4311Sfengbojiang<li><b><code>currentline</code>:</b> 4359*572c4311Sfengbojiangthe current line where the given function is executing. 4360*572c4311SfengbojiangWhen no line information is available, 4361*572c4311Sfengbojiang<code>currentline</code> is set to -1. 4362*572c4311Sfengbojiang</li> 4363*572c4311Sfengbojiang 4364*572c4311Sfengbojiang<li><b><code>name</code>:</b> 4365*572c4311Sfengbojianga reasonable name for the given function. 4366*572c4311SfengbojiangBecause functions in Lua are first-class values, 4367*572c4311Sfengbojiangthey do not have a fixed name: 4368*572c4311Sfengbojiangsome functions can be the value of multiple global variables, 4369*572c4311Sfengbojiangwhile others can be stored only in a table field. 4370*572c4311SfengbojiangThe <code>lua_getinfo</code> function checks how the function was 4371*572c4311Sfengbojiangcalled to find a suitable name. 4372*572c4311SfengbojiangIf it cannot find a name, 4373*572c4311Sfengbojiangthen <code>name</code> is set to <code>NULL</code>. 4374*572c4311Sfengbojiang</li> 4375*572c4311Sfengbojiang 4376*572c4311Sfengbojiang<li><b><code>namewhat</code>:</b> 4377*572c4311Sfengbojiangexplains the <code>name</code> field. 4378*572c4311SfengbojiangThe value of <code>namewhat</code> can be 4379*572c4311Sfengbojiang<code>"global"</code>, <code>"local"</code>, <code>"method"</code>, 4380*572c4311Sfengbojiang<code>"field"</code>, <code>"upvalue"</code>, or <code>""</code> (the empty string), 4381*572c4311Sfengbojiangaccording to how the function was called. 4382*572c4311Sfengbojiang(Lua uses the empty string when no other option seems to apply.) 4383*572c4311Sfengbojiang</li> 4384*572c4311Sfengbojiang 4385*572c4311Sfengbojiang<li><b><code>nups</code>:</b> 4386*572c4311Sfengbojiangthe number of upvalues of the function. 4387*572c4311Sfengbojiang</li> 4388*572c4311Sfengbojiang 4389*572c4311Sfengbojiang</ul> 4390*572c4311Sfengbojiang 4391*572c4311Sfengbojiang 4392*572c4311Sfengbojiang 4393*572c4311Sfengbojiang 4394*572c4311Sfengbojiang<hr><h3><a name="lua_gethook"><code>lua_gethook</code></a></h3><p> 4395*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>-</em>]</span> 4396*572c4311Sfengbojiang<pre>lua_Hook lua_gethook (lua_State *L);</pre> 4397*572c4311Sfengbojiang 4398*572c4311Sfengbojiang<p> 4399*572c4311SfengbojiangReturns the current hook function. 4400*572c4311Sfengbojiang 4401*572c4311Sfengbojiang 4402*572c4311Sfengbojiang 4403*572c4311Sfengbojiang 4404*572c4311Sfengbojiang 4405*572c4311Sfengbojiang<hr><h3><a name="lua_gethookcount"><code>lua_gethookcount</code></a></h3><p> 4406*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>-</em>]</span> 4407*572c4311Sfengbojiang<pre>int lua_gethookcount (lua_State *L);</pre> 4408*572c4311Sfengbojiang 4409*572c4311Sfengbojiang<p> 4410*572c4311SfengbojiangReturns the current hook count. 4411*572c4311Sfengbojiang 4412*572c4311Sfengbojiang 4413*572c4311Sfengbojiang 4414*572c4311Sfengbojiang 4415*572c4311Sfengbojiang 4416*572c4311Sfengbojiang<hr><h3><a name="lua_gethookmask"><code>lua_gethookmask</code></a></h3><p> 4417*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>-</em>]</span> 4418*572c4311Sfengbojiang<pre>int lua_gethookmask (lua_State *L);</pre> 4419*572c4311Sfengbojiang 4420*572c4311Sfengbojiang<p> 4421*572c4311SfengbojiangReturns the current hook mask. 4422*572c4311Sfengbojiang 4423*572c4311Sfengbojiang 4424*572c4311Sfengbojiang 4425*572c4311Sfengbojiang 4426*572c4311Sfengbojiang 4427*572c4311Sfengbojiang<hr><h3><a name="lua_getinfo"><code>lua_getinfo</code></a></h3><p> 4428*572c4311Sfengbojiang<span class="apii">[-(0|1), +(0|1|2), <em>m</em>]</span> 4429*572c4311Sfengbojiang<pre>int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar);</pre> 4430*572c4311Sfengbojiang 4431*572c4311Sfengbojiang<p> 4432*572c4311SfengbojiangReturns information about a specific function or function invocation. 4433*572c4311Sfengbojiang 4434*572c4311Sfengbojiang 4435*572c4311Sfengbojiang<p> 4436*572c4311SfengbojiangTo get information about a function invocation, 4437*572c4311Sfengbojiangthe parameter <code>ar</code> must be a valid activation record that was 4438*572c4311Sfengbojiangfilled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or 4439*572c4311Sfengbojianggiven as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>). 4440*572c4311Sfengbojiang 4441*572c4311Sfengbojiang 4442*572c4311Sfengbojiang<p> 4443*572c4311SfengbojiangTo get information about a function you push it onto the stack 4444*572c4311Sfengbojiangand start the <code>what</code> string with the character '<code>></code>'. 4445*572c4311Sfengbojiang(In that case, 4446*572c4311Sfengbojiang<code>lua_getinfo</code> pops the function in the top of the stack.) 4447*572c4311SfengbojiangFor instance, to know in which line a function <code>f</code> was defined, 4448*572c4311Sfengbojiangyou can write the following code: 4449*572c4311Sfengbojiang 4450*572c4311Sfengbojiang<pre> 4451*572c4311Sfengbojiang lua_Debug ar; 4452*572c4311Sfengbojiang lua_getfield(L, LUA_GLOBALSINDEX, "f"); /* get global 'f' */ 4453*572c4311Sfengbojiang lua_getinfo(L, ">S", &ar); 4454*572c4311Sfengbojiang printf("%d\n", ar.linedefined); 4455*572c4311Sfengbojiang</pre> 4456*572c4311Sfengbojiang 4457*572c4311Sfengbojiang<p> 4458*572c4311SfengbojiangEach character in the string <code>what</code> 4459*572c4311Sfengbojiangselects some fields of the structure <code>ar</code> to be filled or 4460*572c4311Sfengbojianga value to be pushed on the stack: 4461*572c4311Sfengbojiang 4462*572c4311Sfengbojiang<ul> 4463*572c4311Sfengbojiang 4464*572c4311Sfengbojiang<li><b>'<code>n</code>':</b> fills in the field <code>name</code> and <code>namewhat</code>; 4465*572c4311Sfengbojiang</li> 4466*572c4311Sfengbojiang 4467*572c4311Sfengbojiang<li><b>'<code>S</code>':</b> 4468*572c4311Sfengbojiangfills in the fields <code>source</code>, <code>short_src</code>, 4469*572c4311Sfengbojiang<code>linedefined</code>, <code>lastlinedefined</code>, and <code>what</code>; 4470*572c4311Sfengbojiang</li> 4471*572c4311Sfengbojiang 4472*572c4311Sfengbojiang<li><b>'<code>l</code>':</b> fills in the field <code>currentline</code>; 4473*572c4311Sfengbojiang</li> 4474*572c4311Sfengbojiang 4475*572c4311Sfengbojiang<li><b>'<code>u</code>':</b> fills in the field <code>nups</code>; 4476*572c4311Sfengbojiang</li> 4477*572c4311Sfengbojiang 4478*572c4311Sfengbojiang<li><b>'<code>f</code>':</b> 4479*572c4311Sfengbojiangpushes onto the stack the function that is 4480*572c4311Sfengbojiangrunning at the given level; 4481*572c4311Sfengbojiang</li> 4482*572c4311Sfengbojiang 4483*572c4311Sfengbojiang<li><b>'<code>L</code>':</b> 4484*572c4311Sfengbojiangpushes onto the stack a table whose indices are the 4485*572c4311Sfengbojiangnumbers of the lines that are valid on the function. 4486*572c4311Sfengbojiang(A <em>valid line</em> is a line with some associated code, 4487*572c4311Sfengbojiangthat is, a line where you can put a break point. 4488*572c4311SfengbojiangNon-valid lines include empty lines and comments.) 4489*572c4311Sfengbojiang</li> 4490*572c4311Sfengbojiang 4491*572c4311Sfengbojiang</ul> 4492*572c4311Sfengbojiang 4493*572c4311Sfengbojiang<p> 4494*572c4311SfengbojiangThis function returns 0 on error 4495*572c4311Sfengbojiang(for instance, an invalid option in <code>what</code>). 4496*572c4311Sfengbojiang 4497*572c4311Sfengbojiang 4498*572c4311Sfengbojiang 4499*572c4311Sfengbojiang 4500*572c4311Sfengbojiang 4501*572c4311Sfengbojiang<hr><h3><a name="lua_getlocal"><code>lua_getlocal</code></a></h3><p> 4502*572c4311Sfengbojiang<span class="apii">[-0, +(0|1), <em>-</em>]</span> 4503*572c4311Sfengbojiang<pre>const char *lua_getlocal (lua_State *L, lua_Debug *ar, int n);</pre> 4504*572c4311Sfengbojiang 4505*572c4311Sfengbojiang<p> 4506*572c4311SfengbojiangGets information about a local variable of a given activation record. 4507*572c4311SfengbojiangThe parameter <code>ar</code> must be a valid activation record that was 4508*572c4311Sfengbojiangfilled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or 4509*572c4311Sfengbojianggiven as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>). 4510*572c4311SfengbojiangThe index <code>n</code> selects which local variable to inspect 4511*572c4311Sfengbojiang(1 is the first parameter or active local variable, and so on, 4512*572c4311Sfengbojianguntil the last active local variable). 4513*572c4311Sfengbojiang<a href="#lua_getlocal"><code>lua_getlocal</code></a> pushes the variable's value onto the stack 4514*572c4311Sfengbojiangand returns its name. 4515*572c4311Sfengbojiang 4516*572c4311Sfengbojiang 4517*572c4311Sfengbojiang<p> 4518*572c4311SfengbojiangVariable names starting with '<code>(</code>' (open parentheses) 4519*572c4311Sfengbojiangrepresent internal variables 4520*572c4311Sfengbojiang(loop control variables, temporaries, and C function locals). 4521*572c4311Sfengbojiang 4522*572c4311Sfengbojiang 4523*572c4311Sfengbojiang<p> 4524*572c4311SfengbojiangReturns <code>NULL</code> (and pushes nothing) 4525*572c4311Sfengbojiangwhen the index is greater than 4526*572c4311Sfengbojiangthe number of active local variables. 4527*572c4311Sfengbojiang 4528*572c4311Sfengbojiang 4529*572c4311Sfengbojiang 4530*572c4311Sfengbojiang 4531*572c4311Sfengbojiang 4532*572c4311Sfengbojiang<hr><h3><a name="lua_getstack"><code>lua_getstack</code></a></h3><p> 4533*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>-</em>]</span> 4534*572c4311Sfengbojiang<pre>int lua_getstack (lua_State *L, int level, lua_Debug *ar);</pre> 4535*572c4311Sfengbojiang 4536*572c4311Sfengbojiang<p> 4537*572c4311SfengbojiangGet information about the interpreter runtime stack. 4538*572c4311Sfengbojiang 4539*572c4311Sfengbojiang 4540*572c4311Sfengbojiang<p> 4541*572c4311SfengbojiangThis function fills parts of a <a href="#lua_Debug"><code>lua_Debug</code></a> structure with 4542*572c4311Sfengbojiangan identification of the <em>activation record</em> 4543*572c4311Sfengbojiangof the function executing at a given level. 4544*572c4311SfengbojiangLevel 0 is the current running function, 4545*572c4311Sfengbojiangwhereas level <em>n+1</em> is the function that has called level <em>n</em>. 4546*572c4311SfengbojiangWhen there are no errors, <a href="#lua_getstack"><code>lua_getstack</code></a> returns 1; 4547*572c4311Sfengbojiangwhen called with a level greater than the stack depth, 4548*572c4311Sfengbojiangit returns 0. 4549*572c4311Sfengbojiang 4550*572c4311Sfengbojiang 4551*572c4311Sfengbojiang 4552*572c4311Sfengbojiang 4553*572c4311Sfengbojiang 4554*572c4311Sfengbojiang<hr><h3><a name="lua_getupvalue"><code>lua_getupvalue</code></a></h3><p> 4555*572c4311Sfengbojiang<span class="apii">[-0, +(0|1), <em>-</em>]</span> 4556*572c4311Sfengbojiang<pre>const char *lua_getupvalue (lua_State *L, int funcindex, int n);</pre> 4557*572c4311Sfengbojiang 4558*572c4311Sfengbojiang<p> 4559*572c4311SfengbojiangGets information about a closure's upvalue. 4560*572c4311Sfengbojiang(For Lua functions, 4561*572c4311Sfengbojiangupvalues are the external local variables that the function uses, 4562*572c4311Sfengbojiangand that are consequently included in its closure.) 4563*572c4311Sfengbojiang<a href="#lua_getupvalue"><code>lua_getupvalue</code></a> gets the index <code>n</code> of an upvalue, 4564*572c4311Sfengbojiangpushes the upvalue's value onto the stack, 4565*572c4311Sfengbojiangand returns its name. 4566*572c4311Sfengbojiang<code>funcindex</code> points to the closure in the stack. 4567*572c4311Sfengbojiang(Upvalues have no particular order, 4568*572c4311Sfengbojiangas they are active through the whole function. 4569*572c4311SfengbojiangSo, they are numbered in an arbitrary order.) 4570*572c4311Sfengbojiang 4571*572c4311Sfengbojiang 4572*572c4311Sfengbojiang<p> 4573*572c4311SfengbojiangReturns <code>NULL</code> (and pushes nothing) 4574*572c4311Sfengbojiangwhen the index is greater than the number of upvalues. 4575*572c4311SfengbojiangFor C functions, this function uses the empty string <code>""</code> 4576*572c4311Sfengbojiangas a name for all upvalues. 4577*572c4311Sfengbojiang 4578*572c4311Sfengbojiang 4579*572c4311Sfengbojiang 4580*572c4311Sfengbojiang 4581*572c4311Sfengbojiang 4582*572c4311Sfengbojiang<hr><h3><a name="lua_Hook"><code>lua_Hook</code></a></h3> 4583*572c4311Sfengbojiang<pre>typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar);</pre> 4584*572c4311Sfengbojiang 4585*572c4311Sfengbojiang<p> 4586*572c4311SfengbojiangType for debugging hook functions. 4587*572c4311Sfengbojiang 4588*572c4311Sfengbojiang 4589*572c4311Sfengbojiang<p> 4590*572c4311SfengbojiangWhenever a hook is called, its <code>ar</code> argument has its field 4591*572c4311Sfengbojiang<code>event</code> set to the specific event that triggered the hook. 4592*572c4311SfengbojiangLua identifies these events with the following constants: 4593*572c4311Sfengbojiang<a name="pdf-LUA_HOOKCALL"><code>LUA_HOOKCALL</code></a>, <a name="pdf-LUA_HOOKRET"><code>LUA_HOOKRET</code></a>, 4594*572c4311Sfengbojiang<a name="pdf-LUA_HOOKTAILRET"><code>LUA_HOOKTAILRET</code></a>, <a name="pdf-LUA_HOOKLINE"><code>LUA_HOOKLINE</code></a>, 4595*572c4311Sfengbojiangand <a name="pdf-LUA_HOOKCOUNT"><code>LUA_HOOKCOUNT</code></a>. 4596*572c4311SfengbojiangMoreover, for line events, the field <code>currentline</code> is also set. 4597*572c4311SfengbojiangTo get the value of any other field in <code>ar</code>, 4598*572c4311Sfengbojiangthe hook must call <a href="#lua_getinfo"><code>lua_getinfo</code></a>. 4599*572c4311SfengbojiangFor return events, <code>event</code> can be <code>LUA_HOOKRET</code>, 4600*572c4311Sfengbojiangthe normal value, or <code>LUA_HOOKTAILRET</code>. 4601*572c4311SfengbojiangIn the latter case, Lua is simulating a return from 4602*572c4311Sfengbojianga function that did a tail call; 4603*572c4311Sfengbojiangin this case, it is useless to call <a href="#lua_getinfo"><code>lua_getinfo</code></a>. 4604*572c4311Sfengbojiang 4605*572c4311Sfengbojiang 4606*572c4311Sfengbojiang<p> 4607*572c4311SfengbojiangWhile Lua is running a hook, it disables other calls to hooks. 4608*572c4311SfengbojiangTherefore, if a hook calls back Lua to execute a function or a chunk, 4609*572c4311Sfengbojiangthis execution occurs without any calls to hooks. 4610*572c4311Sfengbojiang 4611*572c4311Sfengbojiang 4612*572c4311Sfengbojiang 4613*572c4311Sfengbojiang 4614*572c4311Sfengbojiang 4615*572c4311Sfengbojiang<hr><h3><a name="lua_sethook"><code>lua_sethook</code></a></h3><p> 4616*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>-</em>]</span> 4617*572c4311Sfengbojiang<pre>int lua_sethook (lua_State *L, lua_Hook f, int mask, int count);</pre> 4618*572c4311Sfengbojiang 4619*572c4311Sfengbojiang<p> 4620*572c4311SfengbojiangSets the debugging hook function. 4621*572c4311Sfengbojiang 4622*572c4311Sfengbojiang 4623*572c4311Sfengbojiang<p> 4624*572c4311SfengbojiangArgument <code>f</code> is the hook function. 4625*572c4311Sfengbojiang<code>mask</code> specifies on which events the hook will be called: 4626*572c4311Sfengbojiangit is formed by a bitwise or of the constants 4627*572c4311Sfengbojiang<a name="pdf-LUA_MASKCALL"><code>LUA_MASKCALL</code></a>, 4628*572c4311Sfengbojiang<a name="pdf-LUA_MASKRET"><code>LUA_MASKRET</code></a>, 4629*572c4311Sfengbojiang<a name="pdf-LUA_MASKLINE"><code>LUA_MASKLINE</code></a>, 4630*572c4311Sfengbojiangand <a name="pdf-LUA_MASKCOUNT"><code>LUA_MASKCOUNT</code></a>. 4631*572c4311SfengbojiangThe <code>count</code> argument is only meaningful when the mask 4632*572c4311Sfengbojiangincludes <code>LUA_MASKCOUNT</code>. 4633*572c4311SfengbojiangFor each event, the hook is called as explained below: 4634*572c4311Sfengbojiang 4635*572c4311Sfengbojiang<ul> 4636*572c4311Sfengbojiang 4637*572c4311Sfengbojiang<li><b>The call hook:</b> is called when the interpreter calls a function. 4638*572c4311SfengbojiangThe hook is called just after Lua enters the new function, 4639*572c4311Sfengbojiangbefore the function gets its arguments. 4640*572c4311Sfengbojiang</li> 4641*572c4311Sfengbojiang 4642*572c4311Sfengbojiang<li><b>The return hook:</b> is called when the interpreter returns from a function. 4643*572c4311SfengbojiangThe hook is called just before Lua leaves the function. 4644*572c4311SfengbojiangYou have no access to the values to be returned by the function. 4645*572c4311Sfengbojiang</li> 4646*572c4311Sfengbojiang 4647*572c4311Sfengbojiang<li><b>The line hook:</b> is called when the interpreter is about to 4648*572c4311Sfengbojiangstart the execution of a new line of code, 4649*572c4311Sfengbojiangor when it jumps back in the code (even to the same line). 4650*572c4311Sfengbojiang(This event only happens while Lua is executing a Lua function.) 4651*572c4311Sfengbojiang</li> 4652*572c4311Sfengbojiang 4653*572c4311Sfengbojiang<li><b>The count hook:</b> is called after the interpreter executes every 4654*572c4311Sfengbojiang<code>count</code> instructions. 4655*572c4311Sfengbojiang(This event only happens while Lua is executing a Lua function.) 4656*572c4311Sfengbojiang</li> 4657*572c4311Sfengbojiang 4658*572c4311Sfengbojiang</ul> 4659*572c4311Sfengbojiang 4660*572c4311Sfengbojiang<p> 4661*572c4311SfengbojiangA hook is disabled by setting <code>mask</code> to zero. 4662*572c4311Sfengbojiang 4663*572c4311Sfengbojiang 4664*572c4311Sfengbojiang 4665*572c4311Sfengbojiang 4666*572c4311Sfengbojiang 4667*572c4311Sfengbojiang<hr><h3><a name="lua_setlocal"><code>lua_setlocal</code></a></h3><p> 4668*572c4311Sfengbojiang<span class="apii">[-(0|1), +0, <em>-</em>]</span> 4669*572c4311Sfengbojiang<pre>const char *lua_setlocal (lua_State *L, lua_Debug *ar, int n);</pre> 4670*572c4311Sfengbojiang 4671*572c4311Sfengbojiang<p> 4672*572c4311SfengbojiangSets the value of a local variable of a given activation record. 4673*572c4311SfengbojiangParameters <code>ar</code> and <code>n</code> are as in <a href="#lua_getlocal"><code>lua_getlocal</code></a> 4674*572c4311Sfengbojiang(see <a href="#lua_getlocal"><code>lua_getlocal</code></a>). 4675*572c4311Sfengbojiang<a href="#lua_setlocal"><code>lua_setlocal</code></a> assigns the value at the top of the stack 4676*572c4311Sfengbojiangto the variable and returns its name. 4677*572c4311SfengbojiangIt also pops the value from the stack. 4678*572c4311Sfengbojiang 4679*572c4311Sfengbojiang 4680*572c4311Sfengbojiang<p> 4681*572c4311SfengbojiangReturns <code>NULL</code> (and pops nothing) 4682*572c4311Sfengbojiangwhen the index is greater than 4683*572c4311Sfengbojiangthe number of active local variables. 4684*572c4311Sfengbojiang 4685*572c4311Sfengbojiang 4686*572c4311Sfengbojiang 4687*572c4311Sfengbojiang 4688*572c4311Sfengbojiang 4689*572c4311Sfengbojiang<hr><h3><a name="lua_setupvalue"><code>lua_setupvalue</code></a></h3><p> 4690*572c4311Sfengbojiang<span class="apii">[-(0|1), +0, <em>-</em>]</span> 4691*572c4311Sfengbojiang<pre>const char *lua_setupvalue (lua_State *L, int funcindex, int n);</pre> 4692*572c4311Sfengbojiang 4693*572c4311Sfengbojiang<p> 4694*572c4311SfengbojiangSets the value of a closure's upvalue. 4695*572c4311SfengbojiangIt assigns the value at the top of the stack 4696*572c4311Sfengbojiangto the upvalue and returns its name. 4697*572c4311SfengbojiangIt also pops the value from the stack. 4698*572c4311SfengbojiangParameters <code>funcindex</code> and <code>n</code> are as in the <a href="#lua_getupvalue"><code>lua_getupvalue</code></a> 4699*572c4311Sfengbojiang(see <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>). 4700*572c4311Sfengbojiang 4701*572c4311Sfengbojiang 4702*572c4311Sfengbojiang<p> 4703*572c4311SfengbojiangReturns <code>NULL</code> (and pops nothing) 4704*572c4311Sfengbojiangwhen the index is greater than the number of upvalues. 4705*572c4311Sfengbojiang 4706*572c4311Sfengbojiang 4707*572c4311Sfengbojiang 4708*572c4311Sfengbojiang 4709*572c4311Sfengbojiang 4710*572c4311Sfengbojiang 4711*572c4311Sfengbojiang 4712*572c4311Sfengbojiang<h1>4 - <a name="4">The Auxiliary Library</a></h1> 4713*572c4311Sfengbojiang 4714*572c4311Sfengbojiang<p> 4715*572c4311Sfengbojiang 4716*572c4311SfengbojiangThe <em>auxiliary library</em> provides several convenient functions 4717*572c4311Sfengbojiangto interface C with Lua. 4718*572c4311SfengbojiangWhile the basic API provides the primitive functions for all 4719*572c4311Sfengbojianginteractions between C and Lua, 4720*572c4311Sfengbojiangthe auxiliary library provides higher-level functions for some 4721*572c4311Sfengbojiangcommon tasks. 4722*572c4311Sfengbojiang 4723*572c4311Sfengbojiang 4724*572c4311Sfengbojiang<p> 4725*572c4311SfengbojiangAll functions from the auxiliary library 4726*572c4311Sfengbojiangare defined in header file <code>lauxlib.h</code> and 4727*572c4311Sfengbojianghave a prefix <code>luaL_</code>. 4728*572c4311Sfengbojiang 4729*572c4311Sfengbojiang 4730*572c4311Sfengbojiang<p> 4731*572c4311SfengbojiangAll functions in the auxiliary library are built on 4732*572c4311Sfengbojiangtop of the basic API, 4733*572c4311Sfengbojiangand so they provide nothing that cannot be done with this API. 4734*572c4311Sfengbojiang 4735*572c4311Sfengbojiang 4736*572c4311Sfengbojiang<p> 4737*572c4311SfengbojiangSeveral functions in the auxiliary library are used to 4738*572c4311Sfengbojiangcheck C function arguments. 4739*572c4311SfengbojiangTheir names are always <code>luaL_check*</code> or <code>luaL_opt*</code>. 4740*572c4311SfengbojiangAll of these functions throw an error if the check is not satisfied. 4741*572c4311SfengbojiangBecause the error message is formatted for arguments 4742*572c4311Sfengbojiang(e.g., "<code>bad argument #1</code>"), 4743*572c4311Sfengbojiangyou should not use these functions for other stack values. 4744*572c4311Sfengbojiang 4745*572c4311Sfengbojiang 4746*572c4311Sfengbojiang 4747*572c4311Sfengbojiang<h2>4.1 - <a name="4.1">Functions and Types</a></h2> 4748*572c4311Sfengbojiang 4749*572c4311Sfengbojiang<p> 4750*572c4311SfengbojiangHere we list all functions and types from the auxiliary library 4751*572c4311Sfengbojiangin alphabetical order. 4752*572c4311Sfengbojiang 4753*572c4311Sfengbojiang 4754*572c4311Sfengbojiang 4755*572c4311Sfengbojiang<hr><h3><a name="luaL_addchar"><code>luaL_addchar</code></a></h3><p> 4756*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>m</em>]</span> 4757*572c4311Sfengbojiang<pre>void luaL_addchar (luaL_Buffer *B, char c);</pre> 4758*572c4311Sfengbojiang 4759*572c4311Sfengbojiang<p> 4760*572c4311SfengbojiangAdds the character <code>c</code> to the buffer <code>B</code> 4761*572c4311Sfengbojiang(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 4762*572c4311Sfengbojiang 4763*572c4311Sfengbojiang 4764*572c4311Sfengbojiang 4765*572c4311Sfengbojiang 4766*572c4311Sfengbojiang 4767*572c4311Sfengbojiang<hr><h3><a name="luaL_addlstring"><code>luaL_addlstring</code></a></h3><p> 4768*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>m</em>]</span> 4769*572c4311Sfengbojiang<pre>void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l);</pre> 4770*572c4311Sfengbojiang 4771*572c4311Sfengbojiang<p> 4772*572c4311SfengbojiangAdds the string pointed to by <code>s</code> with length <code>l</code> to 4773*572c4311Sfengbojiangthe buffer <code>B</code> 4774*572c4311Sfengbojiang(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 4775*572c4311SfengbojiangThe string may contain embedded zeros. 4776*572c4311Sfengbojiang 4777*572c4311Sfengbojiang 4778*572c4311Sfengbojiang 4779*572c4311Sfengbojiang 4780*572c4311Sfengbojiang 4781*572c4311Sfengbojiang<hr><h3><a name="luaL_addsize"><code>luaL_addsize</code></a></h3><p> 4782*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>m</em>]</span> 4783*572c4311Sfengbojiang<pre>void luaL_addsize (luaL_Buffer *B, size_t n);</pre> 4784*572c4311Sfengbojiang 4785*572c4311Sfengbojiang<p> 4786*572c4311SfengbojiangAdds to the buffer <code>B</code> (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>) 4787*572c4311Sfengbojianga string of length <code>n</code> previously copied to the 4788*572c4311Sfengbojiangbuffer area (see <a href="#luaL_prepbuffer"><code>luaL_prepbuffer</code></a>). 4789*572c4311Sfengbojiang 4790*572c4311Sfengbojiang 4791*572c4311Sfengbojiang 4792*572c4311Sfengbojiang 4793*572c4311Sfengbojiang 4794*572c4311Sfengbojiang<hr><h3><a name="luaL_addstring"><code>luaL_addstring</code></a></h3><p> 4795*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>m</em>]</span> 4796*572c4311Sfengbojiang<pre>void luaL_addstring (luaL_Buffer *B, const char *s);</pre> 4797*572c4311Sfengbojiang 4798*572c4311Sfengbojiang<p> 4799*572c4311SfengbojiangAdds the zero-terminated string pointed to by <code>s</code> 4800*572c4311Sfengbojiangto the buffer <code>B</code> 4801*572c4311Sfengbojiang(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 4802*572c4311SfengbojiangThe string may not contain embedded zeros. 4803*572c4311Sfengbojiang 4804*572c4311Sfengbojiang 4805*572c4311Sfengbojiang 4806*572c4311Sfengbojiang 4807*572c4311Sfengbojiang 4808*572c4311Sfengbojiang<hr><h3><a name="luaL_addvalue"><code>luaL_addvalue</code></a></h3><p> 4809*572c4311Sfengbojiang<span class="apii">[-1, +0, <em>m</em>]</span> 4810*572c4311Sfengbojiang<pre>void luaL_addvalue (luaL_Buffer *B);</pre> 4811*572c4311Sfengbojiang 4812*572c4311Sfengbojiang<p> 4813*572c4311SfengbojiangAdds the value at the top of the stack 4814*572c4311Sfengbojiangto the buffer <code>B</code> 4815*572c4311Sfengbojiang(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 4816*572c4311SfengbojiangPops the value. 4817*572c4311Sfengbojiang 4818*572c4311Sfengbojiang 4819*572c4311Sfengbojiang<p> 4820*572c4311SfengbojiangThis is the only function on string buffers that can (and must) 4821*572c4311Sfengbojiangbe called with an extra element on the stack, 4822*572c4311Sfengbojiangwhich is the value to be added to the buffer. 4823*572c4311Sfengbojiang 4824*572c4311Sfengbojiang 4825*572c4311Sfengbojiang 4826*572c4311Sfengbojiang 4827*572c4311Sfengbojiang 4828*572c4311Sfengbojiang<hr><h3><a name="luaL_argcheck"><code>luaL_argcheck</code></a></h3><p> 4829*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>v</em>]</span> 4830*572c4311Sfengbojiang<pre>void luaL_argcheck (lua_State *L, 4831*572c4311Sfengbojiang int cond, 4832*572c4311Sfengbojiang int narg, 4833*572c4311Sfengbojiang const char *extramsg);</pre> 4834*572c4311Sfengbojiang 4835*572c4311Sfengbojiang<p> 4836*572c4311SfengbojiangChecks whether <code>cond</code> is true. 4837*572c4311SfengbojiangIf not, raises an error with the following message, 4838*572c4311Sfengbojiangwhere <code>func</code> is retrieved from the call stack: 4839*572c4311Sfengbojiang 4840*572c4311Sfengbojiang<pre> 4841*572c4311Sfengbojiang bad argument #<narg> to <func> (<extramsg>) 4842*572c4311Sfengbojiang</pre> 4843*572c4311Sfengbojiang 4844*572c4311Sfengbojiang 4845*572c4311Sfengbojiang 4846*572c4311Sfengbojiang 4847*572c4311Sfengbojiang<hr><h3><a name="luaL_argerror"><code>luaL_argerror</code></a></h3><p> 4848*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>v</em>]</span> 4849*572c4311Sfengbojiang<pre>int luaL_argerror (lua_State *L, int narg, const char *extramsg);</pre> 4850*572c4311Sfengbojiang 4851*572c4311Sfengbojiang<p> 4852*572c4311SfengbojiangRaises an error with the following message, 4853*572c4311Sfengbojiangwhere <code>func</code> is retrieved from the call stack: 4854*572c4311Sfengbojiang 4855*572c4311Sfengbojiang<pre> 4856*572c4311Sfengbojiang bad argument #<narg> to <func> (<extramsg>) 4857*572c4311Sfengbojiang</pre> 4858*572c4311Sfengbojiang 4859*572c4311Sfengbojiang<p> 4860*572c4311SfengbojiangThis function never returns, 4861*572c4311Sfengbojiangbut it is an idiom to use it in C functions 4862*572c4311Sfengbojiangas <code>return luaL_argerror(<em>args</em>)</code>. 4863*572c4311Sfengbojiang 4864*572c4311Sfengbojiang 4865*572c4311Sfengbojiang 4866*572c4311Sfengbojiang 4867*572c4311Sfengbojiang 4868*572c4311Sfengbojiang<hr><h3><a name="luaL_Buffer"><code>luaL_Buffer</code></a></h3> 4869*572c4311Sfengbojiang<pre>typedef struct luaL_Buffer luaL_Buffer;</pre> 4870*572c4311Sfengbojiang 4871*572c4311Sfengbojiang<p> 4872*572c4311SfengbojiangType for a <em>string buffer</em>. 4873*572c4311Sfengbojiang 4874*572c4311Sfengbojiang 4875*572c4311Sfengbojiang<p> 4876*572c4311SfengbojiangA string buffer allows C code to build Lua strings piecemeal. 4877*572c4311SfengbojiangIts pattern of use is as follows: 4878*572c4311Sfengbojiang 4879*572c4311Sfengbojiang<ul> 4880*572c4311Sfengbojiang 4881*572c4311Sfengbojiang<li>First you declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li> 4882*572c4311Sfengbojiang 4883*572c4311Sfengbojiang<li>Then you initialize it with a call <code>luaL_buffinit(L, &b)</code>.</li> 4884*572c4311Sfengbojiang 4885*572c4311Sfengbojiang<li> 4886*572c4311SfengbojiangThen you add string pieces to the buffer calling any of 4887*572c4311Sfengbojiangthe <code>luaL_add*</code> functions. 4888*572c4311Sfengbojiang</li> 4889*572c4311Sfengbojiang 4890*572c4311Sfengbojiang<li> 4891*572c4311SfengbojiangYou finish by calling <code>luaL_pushresult(&b)</code>. 4892*572c4311SfengbojiangThis call leaves the final string on the top of the stack. 4893*572c4311Sfengbojiang</li> 4894*572c4311Sfengbojiang 4895*572c4311Sfengbojiang</ul> 4896*572c4311Sfengbojiang 4897*572c4311Sfengbojiang<p> 4898*572c4311SfengbojiangDuring its normal operation, 4899*572c4311Sfengbojianga string buffer uses a variable number of stack slots. 4900*572c4311SfengbojiangSo, while using a buffer, you cannot assume that you know where 4901*572c4311Sfengbojiangthe top of the stack is. 4902*572c4311SfengbojiangYou can use the stack between successive calls to buffer operations 4903*572c4311Sfengbojiangas long as that use is balanced; 4904*572c4311Sfengbojiangthat is, 4905*572c4311Sfengbojiangwhen you call a buffer operation, 4906*572c4311Sfengbojiangthe stack is at the same level 4907*572c4311Sfengbojiangit was immediately after the previous buffer operation. 4908*572c4311Sfengbojiang(The only exception to this rule is <a href="#luaL_addvalue"><code>luaL_addvalue</code></a>.) 4909*572c4311SfengbojiangAfter calling <a href="#luaL_pushresult"><code>luaL_pushresult</code></a> the stack is back to its 4910*572c4311Sfengbojianglevel when the buffer was initialized, 4911*572c4311Sfengbojiangplus the final string on its top. 4912*572c4311Sfengbojiang 4913*572c4311Sfengbojiang 4914*572c4311Sfengbojiang 4915*572c4311Sfengbojiang 4916*572c4311Sfengbojiang 4917*572c4311Sfengbojiang<hr><h3><a name="luaL_buffinit"><code>luaL_buffinit</code></a></h3><p> 4918*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>-</em>]</span> 4919*572c4311Sfengbojiang<pre>void luaL_buffinit (lua_State *L, luaL_Buffer *B);</pre> 4920*572c4311Sfengbojiang 4921*572c4311Sfengbojiang<p> 4922*572c4311SfengbojiangInitializes a buffer <code>B</code>. 4923*572c4311SfengbojiangThis function does not allocate any space; 4924*572c4311Sfengbojiangthe buffer must be declared as a variable 4925*572c4311Sfengbojiang(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 4926*572c4311Sfengbojiang 4927*572c4311Sfengbojiang 4928*572c4311Sfengbojiang 4929*572c4311Sfengbojiang 4930*572c4311Sfengbojiang 4931*572c4311Sfengbojiang<hr><h3><a name="luaL_callmeta"><code>luaL_callmeta</code></a></h3><p> 4932*572c4311Sfengbojiang<span class="apii">[-0, +(0|1), <em>e</em>]</span> 4933*572c4311Sfengbojiang<pre>int luaL_callmeta (lua_State *L, int obj, const char *e);</pre> 4934*572c4311Sfengbojiang 4935*572c4311Sfengbojiang<p> 4936*572c4311SfengbojiangCalls a metamethod. 4937*572c4311Sfengbojiang 4938*572c4311Sfengbojiang 4939*572c4311Sfengbojiang<p> 4940*572c4311SfengbojiangIf the object at index <code>obj</code> has a metatable and this 4941*572c4311Sfengbojiangmetatable has a field <code>e</code>, 4942*572c4311Sfengbojiangthis function calls this field and passes the object as its only argument. 4943*572c4311SfengbojiangIn this case this function returns 1 and pushes onto the 4944*572c4311Sfengbojiangstack the value returned by the call. 4945*572c4311SfengbojiangIf there is no metatable or no metamethod, 4946*572c4311Sfengbojiangthis function returns 0 (without pushing any value on the stack). 4947*572c4311Sfengbojiang 4948*572c4311Sfengbojiang 4949*572c4311Sfengbojiang 4950*572c4311Sfengbojiang 4951*572c4311Sfengbojiang 4952*572c4311Sfengbojiang<hr><h3><a name="luaL_checkany"><code>luaL_checkany</code></a></h3><p> 4953*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>v</em>]</span> 4954*572c4311Sfengbojiang<pre>void luaL_checkany (lua_State *L, int narg);</pre> 4955*572c4311Sfengbojiang 4956*572c4311Sfengbojiang<p> 4957*572c4311SfengbojiangChecks whether the function has an argument 4958*572c4311Sfengbojiangof any type (including <b>nil</b>) at position <code>narg</code>. 4959*572c4311Sfengbojiang 4960*572c4311Sfengbojiang 4961*572c4311Sfengbojiang 4962*572c4311Sfengbojiang 4963*572c4311Sfengbojiang 4964*572c4311Sfengbojiang<hr><h3><a name="luaL_checkint"><code>luaL_checkint</code></a></h3><p> 4965*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>v</em>]</span> 4966*572c4311Sfengbojiang<pre>int luaL_checkint (lua_State *L, int narg);</pre> 4967*572c4311Sfengbojiang 4968*572c4311Sfengbojiang<p> 4969*572c4311SfengbojiangChecks whether the function argument <code>narg</code> is a number 4970*572c4311Sfengbojiangand returns this number cast to an <code>int</code>. 4971*572c4311Sfengbojiang 4972*572c4311Sfengbojiang 4973*572c4311Sfengbojiang 4974*572c4311Sfengbojiang 4975*572c4311Sfengbojiang 4976*572c4311Sfengbojiang<hr><h3><a name="luaL_checkinteger"><code>luaL_checkinteger</code></a></h3><p> 4977*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>v</em>]</span> 4978*572c4311Sfengbojiang<pre>lua_Integer luaL_checkinteger (lua_State *L, int narg);</pre> 4979*572c4311Sfengbojiang 4980*572c4311Sfengbojiang<p> 4981*572c4311SfengbojiangChecks whether the function argument <code>narg</code> is a number 4982*572c4311Sfengbojiangand returns this number cast to a <a href="#lua_Integer"><code>lua_Integer</code></a>. 4983*572c4311Sfengbojiang 4984*572c4311Sfengbojiang 4985*572c4311Sfengbojiang 4986*572c4311Sfengbojiang 4987*572c4311Sfengbojiang 4988*572c4311Sfengbojiang<hr><h3><a name="luaL_checklong"><code>luaL_checklong</code></a></h3><p> 4989*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>v</em>]</span> 4990*572c4311Sfengbojiang<pre>long luaL_checklong (lua_State *L, int narg);</pre> 4991*572c4311Sfengbojiang 4992*572c4311Sfengbojiang<p> 4993*572c4311SfengbojiangChecks whether the function argument <code>narg</code> is a number 4994*572c4311Sfengbojiangand returns this number cast to a <code>long</code>. 4995*572c4311Sfengbojiang 4996*572c4311Sfengbojiang 4997*572c4311Sfengbojiang 4998*572c4311Sfengbojiang 4999*572c4311Sfengbojiang 5000*572c4311Sfengbojiang<hr><h3><a name="luaL_checklstring"><code>luaL_checklstring</code></a></h3><p> 5001*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>v</em>]</span> 5002*572c4311Sfengbojiang<pre>const char *luaL_checklstring (lua_State *L, int narg, size_t *l);</pre> 5003*572c4311Sfengbojiang 5004*572c4311Sfengbojiang<p> 5005*572c4311SfengbojiangChecks whether the function argument <code>narg</code> is a string 5006*572c4311Sfengbojiangand returns this string; 5007*572c4311Sfengbojiangif <code>l</code> is not <code>NULL</code> fills <code>*l</code> 5008*572c4311Sfengbojiangwith the string's length. 5009*572c4311Sfengbojiang 5010*572c4311Sfengbojiang 5011*572c4311Sfengbojiang<p> 5012*572c4311SfengbojiangThis function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, 5013*572c4311Sfengbojiangso all conversions and caveats of that function apply here. 5014*572c4311Sfengbojiang 5015*572c4311Sfengbojiang 5016*572c4311Sfengbojiang 5017*572c4311Sfengbojiang 5018*572c4311Sfengbojiang 5019*572c4311Sfengbojiang<hr><h3><a name="luaL_checknumber"><code>luaL_checknumber</code></a></h3><p> 5020*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>v</em>]</span> 5021*572c4311Sfengbojiang<pre>lua_Number luaL_checknumber (lua_State *L, int narg);</pre> 5022*572c4311Sfengbojiang 5023*572c4311Sfengbojiang<p> 5024*572c4311SfengbojiangChecks whether the function argument <code>narg</code> is a number 5025*572c4311Sfengbojiangand returns this number. 5026*572c4311Sfengbojiang 5027*572c4311Sfengbojiang 5028*572c4311Sfengbojiang 5029*572c4311Sfengbojiang 5030*572c4311Sfengbojiang 5031*572c4311Sfengbojiang<hr><h3><a name="luaL_checkoption"><code>luaL_checkoption</code></a></h3><p> 5032*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>v</em>]</span> 5033*572c4311Sfengbojiang<pre>int luaL_checkoption (lua_State *L, 5034*572c4311Sfengbojiang int narg, 5035*572c4311Sfengbojiang const char *def, 5036*572c4311Sfengbojiang const char *const lst[]);</pre> 5037*572c4311Sfengbojiang 5038*572c4311Sfengbojiang<p> 5039*572c4311SfengbojiangChecks whether the function argument <code>narg</code> is a string and 5040*572c4311Sfengbojiangsearches for this string in the array <code>lst</code> 5041*572c4311Sfengbojiang(which must be NULL-terminated). 5042*572c4311SfengbojiangReturns the index in the array where the string was found. 5043*572c4311SfengbojiangRaises an error if the argument is not a string or 5044*572c4311Sfengbojiangif the string cannot be found. 5045*572c4311Sfengbojiang 5046*572c4311Sfengbojiang 5047*572c4311Sfengbojiang<p> 5048*572c4311SfengbojiangIf <code>def</code> is not <code>NULL</code>, 5049*572c4311Sfengbojiangthe function uses <code>def</code> as a default value when 5050*572c4311Sfengbojiangthere is no argument <code>narg</code> or if this argument is <b>nil</b>. 5051*572c4311Sfengbojiang 5052*572c4311Sfengbojiang 5053*572c4311Sfengbojiang<p> 5054*572c4311SfengbojiangThis is a useful function for mapping strings to C enums. 5055*572c4311Sfengbojiang(The usual convention in Lua libraries is 5056*572c4311Sfengbojiangto use strings instead of numbers to select options.) 5057*572c4311Sfengbojiang 5058*572c4311Sfengbojiang 5059*572c4311Sfengbojiang 5060*572c4311Sfengbojiang 5061*572c4311Sfengbojiang 5062*572c4311Sfengbojiang<hr><h3><a name="luaL_checkstack"><code>luaL_checkstack</code></a></h3><p> 5063*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>v</em>]</span> 5064*572c4311Sfengbojiang<pre>void luaL_checkstack (lua_State *L, int sz, const char *msg);</pre> 5065*572c4311Sfengbojiang 5066*572c4311Sfengbojiang<p> 5067*572c4311SfengbojiangGrows the stack size to <code>top + sz</code> elements, 5068*572c4311Sfengbojiangraising an error if the stack cannot grow to that size. 5069*572c4311Sfengbojiang<code>msg</code> is an additional text to go into the error message. 5070*572c4311Sfengbojiang 5071*572c4311Sfengbojiang 5072*572c4311Sfengbojiang 5073*572c4311Sfengbojiang 5074*572c4311Sfengbojiang 5075*572c4311Sfengbojiang<hr><h3><a name="luaL_checkstring"><code>luaL_checkstring</code></a></h3><p> 5076*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>v</em>]</span> 5077*572c4311Sfengbojiang<pre>const char *luaL_checkstring (lua_State *L, int narg);</pre> 5078*572c4311Sfengbojiang 5079*572c4311Sfengbojiang<p> 5080*572c4311SfengbojiangChecks whether the function argument <code>narg</code> is a string 5081*572c4311Sfengbojiangand returns this string. 5082*572c4311Sfengbojiang 5083*572c4311Sfengbojiang 5084*572c4311Sfengbojiang<p> 5085*572c4311SfengbojiangThis function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, 5086*572c4311Sfengbojiangso all conversions and caveats of that function apply here. 5087*572c4311Sfengbojiang 5088*572c4311Sfengbojiang 5089*572c4311Sfengbojiang 5090*572c4311Sfengbojiang 5091*572c4311Sfengbojiang 5092*572c4311Sfengbojiang<hr><h3><a name="luaL_checktype"><code>luaL_checktype</code></a></h3><p> 5093*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>v</em>]</span> 5094*572c4311Sfengbojiang<pre>void luaL_checktype (lua_State *L, int narg, int t);</pre> 5095*572c4311Sfengbojiang 5096*572c4311Sfengbojiang<p> 5097*572c4311SfengbojiangChecks whether the function argument <code>narg</code> has type <code>t</code>. 5098*572c4311SfengbojiangSee <a href="#lua_type"><code>lua_type</code></a> for the encoding of types for <code>t</code>. 5099*572c4311Sfengbojiang 5100*572c4311Sfengbojiang 5101*572c4311Sfengbojiang 5102*572c4311Sfengbojiang 5103*572c4311Sfengbojiang 5104*572c4311Sfengbojiang<hr><h3><a name="luaL_checkudata"><code>luaL_checkudata</code></a></h3><p> 5105*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>v</em>]</span> 5106*572c4311Sfengbojiang<pre>void *luaL_checkudata (lua_State *L, int narg, const char *tname);</pre> 5107*572c4311Sfengbojiang 5108*572c4311Sfengbojiang<p> 5109*572c4311SfengbojiangChecks whether the function argument <code>narg</code> is a userdata 5110*572c4311Sfengbojiangof the type <code>tname</code> (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). 5111*572c4311Sfengbojiang 5112*572c4311Sfengbojiang 5113*572c4311Sfengbojiang 5114*572c4311Sfengbojiang 5115*572c4311Sfengbojiang 5116*572c4311Sfengbojiang<hr><h3><a name="luaL_dofile"><code>luaL_dofile</code></a></h3><p> 5117*572c4311Sfengbojiang<span class="apii">[-0, +?, <em>m</em>]</span> 5118*572c4311Sfengbojiang<pre>int luaL_dofile (lua_State *L, const char *filename);</pre> 5119*572c4311Sfengbojiang 5120*572c4311Sfengbojiang<p> 5121*572c4311SfengbojiangLoads and runs the given file. 5122*572c4311SfengbojiangIt is defined as the following macro: 5123*572c4311Sfengbojiang 5124*572c4311Sfengbojiang<pre> 5125*572c4311Sfengbojiang (luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0)) 5126*572c4311Sfengbojiang</pre><p> 5127*572c4311SfengbojiangIt returns 0 if there are no errors 5128*572c4311Sfengbojiangor 1 in case of errors. 5129*572c4311Sfengbojiang 5130*572c4311Sfengbojiang 5131*572c4311Sfengbojiang 5132*572c4311Sfengbojiang 5133*572c4311Sfengbojiang 5134*572c4311Sfengbojiang<hr><h3><a name="luaL_dostring"><code>luaL_dostring</code></a></h3><p> 5135*572c4311Sfengbojiang<span class="apii">[-0, +?, <em>m</em>]</span> 5136*572c4311Sfengbojiang<pre>int luaL_dostring (lua_State *L, const char *str);</pre> 5137*572c4311Sfengbojiang 5138*572c4311Sfengbojiang<p> 5139*572c4311SfengbojiangLoads and runs the given string. 5140*572c4311SfengbojiangIt is defined as the following macro: 5141*572c4311Sfengbojiang 5142*572c4311Sfengbojiang<pre> 5143*572c4311Sfengbojiang (luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0)) 5144*572c4311Sfengbojiang</pre><p> 5145*572c4311SfengbojiangIt returns 0 if there are no errors 5146*572c4311Sfengbojiangor 1 in case of errors. 5147*572c4311Sfengbojiang 5148*572c4311Sfengbojiang 5149*572c4311Sfengbojiang 5150*572c4311Sfengbojiang 5151*572c4311Sfengbojiang 5152*572c4311Sfengbojiang<hr><h3><a name="luaL_error"><code>luaL_error</code></a></h3><p> 5153*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>v</em>]</span> 5154*572c4311Sfengbojiang<pre>int luaL_error (lua_State *L, const char *fmt, ...);</pre> 5155*572c4311Sfengbojiang 5156*572c4311Sfengbojiang<p> 5157*572c4311SfengbojiangRaises an error. 5158*572c4311SfengbojiangThe error message format is given by <code>fmt</code> 5159*572c4311Sfengbojiangplus any extra arguments, 5160*572c4311Sfengbojiangfollowing the same rules of <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>. 5161*572c4311SfengbojiangIt also adds at the beginning of the message the file name and 5162*572c4311Sfengbojiangthe line number where the error occurred, 5163*572c4311Sfengbojiangif this information is available. 5164*572c4311Sfengbojiang 5165*572c4311Sfengbojiang 5166*572c4311Sfengbojiang<p> 5167*572c4311SfengbojiangThis function never returns, 5168*572c4311Sfengbojiangbut it is an idiom to use it in C functions 5169*572c4311Sfengbojiangas <code>return luaL_error(<em>args</em>)</code>. 5170*572c4311Sfengbojiang 5171*572c4311Sfengbojiang 5172*572c4311Sfengbojiang 5173*572c4311Sfengbojiang 5174*572c4311Sfengbojiang 5175*572c4311Sfengbojiang<hr><h3><a name="luaL_getmetafield"><code>luaL_getmetafield</code></a></h3><p> 5176*572c4311Sfengbojiang<span class="apii">[-0, +(0|1), <em>m</em>]</span> 5177*572c4311Sfengbojiang<pre>int luaL_getmetafield (lua_State *L, int obj, const char *e);</pre> 5178*572c4311Sfengbojiang 5179*572c4311Sfengbojiang<p> 5180*572c4311SfengbojiangPushes onto the stack the field <code>e</code> from the metatable 5181*572c4311Sfengbojiangof the object at index <code>obj</code>. 5182*572c4311SfengbojiangIf the object does not have a metatable, 5183*572c4311Sfengbojiangor if the metatable does not have this field, 5184*572c4311Sfengbojiangreturns 0 and pushes nothing. 5185*572c4311Sfengbojiang 5186*572c4311Sfengbojiang 5187*572c4311Sfengbojiang 5188*572c4311Sfengbojiang 5189*572c4311Sfengbojiang 5190*572c4311Sfengbojiang<hr><h3><a name="luaL_getmetatable"><code>luaL_getmetatable</code></a></h3><p> 5191*572c4311Sfengbojiang<span class="apii">[-0, +1, <em>-</em>]</span> 5192*572c4311Sfengbojiang<pre>void luaL_getmetatable (lua_State *L, const char *tname);</pre> 5193*572c4311Sfengbojiang 5194*572c4311Sfengbojiang<p> 5195*572c4311SfengbojiangPushes onto the stack the metatable associated with name <code>tname</code> 5196*572c4311Sfengbojiangin the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). 5197*572c4311Sfengbojiang 5198*572c4311Sfengbojiang 5199*572c4311Sfengbojiang 5200*572c4311Sfengbojiang 5201*572c4311Sfengbojiang 5202*572c4311Sfengbojiang<hr><h3><a name="luaL_gsub"><code>luaL_gsub</code></a></h3><p> 5203*572c4311Sfengbojiang<span class="apii">[-0, +1, <em>m</em>]</span> 5204*572c4311Sfengbojiang<pre>const char *luaL_gsub (lua_State *L, 5205*572c4311Sfengbojiang const char *s, 5206*572c4311Sfengbojiang const char *p, 5207*572c4311Sfengbojiang const char *r);</pre> 5208*572c4311Sfengbojiang 5209*572c4311Sfengbojiang<p> 5210*572c4311SfengbojiangCreates a copy of string <code>s</code> by replacing 5211*572c4311Sfengbojiangany occurrence of the string <code>p</code> 5212*572c4311Sfengbojiangwith the string <code>r</code>. 5213*572c4311SfengbojiangPushes the resulting string on the stack and returns it. 5214*572c4311Sfengbojiang 5215*572c4311Sfengbojiang 5216*572c4311Sfengbojiang 5217*572c4311Sfengbojiang 5218*572c4311Sfengbojiang 5219*572c4311Sfengbojiang<hr><h3><a name="luaL_loadbuffer"><code>luaL_loadbuffer</code></a></h3><p> 5220*572c4311Sfengbojiang<span class="apii">[-0, +1, <em>m</em>]</span> 5221*572c4311Sfengbojiang<pre>int luaL_loadbuffer (lua_State *L, 5222*572c4311Sfengbojiang const char *buff, 5223*572c4311Sfengbojiang size_t sz, 5224*572c4311Sfengbojiang const char *name);</pre> 5225*572c4311Sfengbojiang 5226*572c4311Sfengbojiang<p> 5227*572c4311SfengbojiangLoads a buffer as a Lua chunk. 5228*572c4311SfengbojiangThis function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the 5229*572c4311Sfengbojiangbuffer pointed to by <code>buff</code> with size <code>sz</code>. 5230*572c4311Sfengbojiang 5231*572c4311Sfengbojiang 5232*572c4311Sfengbojiang<p> 5233*572c4311SfengbojiangThis function returns the same results as <a href="#lua_load"><code>lua_load</code></a>. 5234*572c4311Sfengbojiang<code>name</code> is the chunk name, 5235*572c4311Sfengbojiangused for debug information and error messages. 5236*572c4311Sfengbojiang 5237*572c4311Sfengbojiang 5238*572c4311Sfengbojiang 5239*572c4311Sfengbojiang 5240*572c4311Sfengbojiang 5241*572c4311Sfengbojiang<hr><h3><a name="luaL_loadfile"><code>luaL_loadfile</code></a></h3><p> 5242*572c4311Sfengbojiang<span class="apii">[-0, +1, <em>m</em>]</span> 5243*572c4311Sfengbojiang<pre>int luaL_loadfile (lua_State *L, const char *filename);</pre> 5244*572c4311Sfengbojiang 5245*572c4311Sfengbojiang<p> 5246*572c4311SfengbojiangLoads a file as a Lua chunk. 5247*572c4311SfengbojiangThis function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the file 5248*572c4311Sfengbojiangnamed <code>filename</code>. 5249*572c4311SfengbojiangIf <code>filename</code> is <code>NULL</code>, 5250*572c4311Sfengbojiangthen it loads from the standard input. 5251*572c4311SfengbojiangThe first line in the file is ignored if it starts with a <code>#</code>. 5252*572c4311Sfengbojiang 5253*572c4311Sfengbojiang 5254*572c4311Sfengbojiang<p> 5255*572c4311SfengbojiangThis function returns the same results as <a href="#lua_load"><code>lua_load</code></a>, 5256*572c4311Sfengbojiangbut it has an extra error code <a name="pdf-LUA_ERRFILE"><code>LUA_ERRFILE</code></a> 5257*572c4311Sfengbojiangif it cannot open/read the file. 5258*572c4311Sfengbojiang 5259*572c4311Sfengbojiang 5260*572c4311Sfengbojiang<p> 5261*572c4311SfengbojiangAs <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk; 5262*572c4311Sfengbojiangit does not run it. 5263*572c4311Sfengbojiang 5264*572c4311Sfengbojiang 5265*572c4311Sfengbojiang 5266*572c4311Sfengbojiang 5267*572c4311Sfengbojiang 5268*572c4311Sfengbojiang<hr><h3><a name="luaL_loadstring"><code>luaL_loadstring</code></a></h3><p> 5269*572c4311Sfengbojiang<span class="apii">[-0, +1, <em>m</em>]</span> 5270*572c4311Sfengbojiang<pre>int luaL_loadstring (lua_State *L, const char *s);</pre> 5271*572c4311Sfengbojiang 5272*572c4311Sfengbojiang<p> 5273*572c4311SfengbojiangLoads a string as a Lua chunk. 5274*572c4311SfengbojiangThis function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in 5275*572c4311Sfengbojiangthe zero-terminated string <code>s</code>. 5276*572c4311Sfengbojiang 5277*572c4311Sfengbojiang 5278*572c4311Sfengbojiang<p> 5279*572c4311SfengbojiangThis function returns the same results as <a href="#lua_load"><code>lua_load</code></a>. 5280*572c4311Sfengbojiang 5281*572c4311Sfengbojiang 5282*572c4311Sfengbojiang<p> 5283*572c4311SfengbojiangAlso as <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk; 5284*572c4311Sfengbojiangit does not run it. 5285*572c4311Sfengbojiang 5286*572c4311Sfengbojiang 5287*572c4311Sfengbojiang 5288*572c4311Sfengbojiang 5289*572c4311Sfengbojiang 5290*572c4311Sfengbojiang<hr><h3><a name="luaL_newmetatable"><code>luaL_newmetatable</code></a></h3><p> 5291*572c4311Sfengbojiang<span class="apii">[-0, +1, <em>m</em>]</span> 5292*572c4311Sfengbojiang<pre>int luaL_newmetatable (lua_State *L, const char *tname);</pre> 5293*572c4311Sfengbojiang 5294*572c4311Sfengbojiang<p> 5295*572c4311SfengbojiangIf the registry already has the key <code>tname</code>, 5296*572c4311Sfengbojiangreturns 0. 5297*572c4311SfengbojiangOtherwise, 5298*572c4311Sfengbojiangcreates a new table to be used as a metatable for userdata, 5299*572c4311Sfengbojiangadds it to the registry with key <code>tname</code>, 5300*572c4311Sfengbojiangand returns 1. 5301*572c4311Sfengbojiang 5302*572c4311Sfengbojiang 5303*572c4311Sfengbojiang<p> 5304*572c4311SfengbojiangIn both cases pushes onto the stack the final value associated 5305*572c4311Sfengbojiangwith <code>tname</code> in the registry. 5306*572c4311Sfengbojiang 5307*572c4311Sfengbojiang 5308*572c4311Sfengbojiang 5309*572c4311Sfengbojiang 5310*572c4311Sfengbojiang 5311*572c4311Sfengbojiang<hr><h3><a name="luaL_newstate"><code>luaL_newstate</code></a></h3><p> 5312*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>-</em>]</span> 5313*572c4311Sfengbojiang<pre>lua_State *luaL_newstate (void);</pre> 5314*572c4311Sfengbojiang 5315*572c4311Sfengbojiang<p> 5316*572c4311SfengbojiangCreates a new Lua state. 5317*572c4311SfengbojiangIt calls <a href="#lua_newstate"><code>lua_newstate</code></a> with an 5318*572c4311Sfengbojiangallocator based on the standard C <code>realloc</code> function 5319*572c4311Sfengbojiangand then sets a panic function (see <a href="#lua_atpanic"><code>lua_atpanic</code></a>) that prints 5320*572c4311Sfengbojiangan error message to the standard error output in case of fatal 5321*572c4311Sfengbojiangerrors. 5322*572c4311Sfengbojiang 5323*572c4311Sfengbojiang 5324*572c4311Sfengbojiang<p> 5325*572c4311SfengbojiangReturns the new state, 5326*572c4311Sfengbojiangor <code>NULL</code> if there is a memory allocation error. 5327*572c4311Sfengbojiang 5328*572c4311Sfengbojiang 5329*572c4311Sfengbojiang 5330*572c4311Sfengbojiang 5331*572c4311Sfengbojiang 5332*572c4311Sfengbojiang<hr><h3><a name="luaL_openlibs"><code>luaL_openlibs</code></a></h3><p> 5333*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>m</em>]</span> 5334*572c4311Sfengbojiang<pre>void luaL_openlibs (lua_State *L);</pre> 5335*572c4311Sfengbojiang 5336*572c4311Sfengbojiang<p> 5337*572c4311SfengbojiangOpens all standard Lua libraries into the given state. 5338*572c4311Sfengbojiang 5339*572c4311Sfengbojiang 5340*572c4311Sfengbojiang 5341*572c4311Sfengbojiang 5342*572c4311Sfengbojiang 5343*572c4311Sfengbojiang<hr><h3><a name="luaL_optint"><code>luaL_optint</code></a></h3><p> 5344*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>v</em>]</span> 5345*572c4311Sfengbojiang<pre>int luaL_optint (lua_State *L, int narg, int d);</pre> 5346*572c4311Sfengbojiang 5347*572c4311Sfengbojiang<p> 5348*572c4311SfengbojiangIf the function argument <code>narg</code> is a number, 5349*572c4311Sfengbojiangreturns this number cast to an <code>int</code>. 5350*572c4311SfengbojiangIf this argument is absent or is <b>nil</b>, 5351*572c4311Sfengbojiangreturns <code>d</code>. 5352*572c4311SfengbojiangOtherwise, raises an error. 5353*572c4311Sfengbojiang 5354*572c4311Sfengbojiang 5355*572c4311Sfengbojiang 5356*572c4311Sfengbojiang 5357*572c4311Sfengbojiang 5358*572c4311Sfengbojiang<hr><h3><a name="luaL_optinteger"><code>luaL_optinteger</code></a></h3><p> 5359*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>v</em>]</span> 5360*572c4311Sfengbojiang<pre>lua_Integer luaL_optinteger (lua_State *L, 5361*572c4311Sfengbojiang int narg, 5362*572c4311Sfengbojiang lua_Integer d);</pre> 5363*572c4311Sfengbojiang 5364*572c4311Sfengbojiang<p> 5365*572c4311SfengbojiangIf the function argument <code>narg</code> is a number, 5366*572c4311Sfengbojiangreturns this number cast to a <a href="#lua_Integer"><code>lua_Integer</code></a>. 5367*572c4311SfengbojiangIf this argument is absent or is <b>nil</b>, 5368*572c4311Sfengbojiangreturns <code>d</code>. 5369*572c4311SfengbojiangOtherwise, raises an error. 5370*572c4311Sfengbojiang 5371*572c4311Sfengbojiang 5372*572c4311Sfengbojiang 5373*572c4311Sfengbojiang 5374*572c4311Sfengbojiang 5375*572c4311Sfengbojiang<hr><h3><a name="luaL_optlong"><code>luaL_optlong</code></a></h3><p> 5376*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>v</em>]</span> 5377*572c4311Sfengbojiang<pre>long luaL_optlong (lua_State *L, int narg, long d);</pre> 5378*572c4311Sfengbojiang 5379*572c4311Sfengbojiang<p> 5380*572c4311SfengbojiangIf the function argument <code>narg</code> is a number, 5381*572c4311Sfengbojiangreturns this number cast to a <code>long</code>. 5382*572c4311SfengbojiangIf this argument is absent or is <b>nil</b>, 5383*572c4311Sfengbojiangreturns <code>d</code>. 5384*572c4311SfengbojiangOtherwise, raises an error. 5385*572c4311Sfengbojiang 5386*572c4311Sfengbojiang 5387*572c4311Sfengbojiang 5388*572c4311Sfengbojiang 5389*572c4311Sfengbojiang 5390*572c4311Sfengbojiang<hr><h3><a name="luaL_optlstring"><code>luaL_optlstring</code></a></h3><p> 5391*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>v</em>]</span> 5392*572c4311Sfengbojiang<pre>const char *luaL_optlstring (lua_State *L, 5393*572c4311Sfengbojiang int narg, 5394*572c4311Sfengbojiang const char *d, 5395*572c4311Sfengbojiang size_t *l);</pre> 5396*572c4311Sfengbojiang 5397*572c4311Sfengbojiang<p> 5398*572c4311SfengbojiangIf the function argument <code>narg</code> is a string, 5399*572c4311Sfengbojiangreturns this string. 5400*572c4311SfengbojiangIf this argument is absent or is <b>nil</b>, 5401*572c4311Sfengbojiangreturns <code>d</code>. 5402*572c4311SfengbojiangOtherwise, raises an error. 5403*572c4311Sfengbojiang 5404*572c4311Sfengbojiang 5405*572c4311Sfengbojiang<p> 5406*572c4311SfengbojiangIf <code>l</code> is not <code>NULL</code>, 5407*572c4311Sfengbojiangfills the position <code>*l</code> with the results's length. 5408*572c4311Sfengbojiang 5409*572c4311Sfengbojiang 5410*572c4311Sfengbojiang 5411*572c4311Sfengbojiang 5412*572c4311Sfengbojiang 5413*572c4311Sfengbojiang<hr><h3><a name="luaL_optnumber"><code>luaL_optnumber</code></a></h3><p> 5414*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>v</em>]</span> 5415*572c4311Sfengbojiang<pre>lua_Number luaL_optnumber (lua_State *L, int narg, lua_Number d);</pre> 5416*572c4311Sfengbojiang 5417*572c4311Sfengbojiang<p> 5418*572c4311SfengbojiangIf the function argument <code>narg</code> is a number, 5419*572c4311Sfengbojiangreturns this number. 5420*572c4311SfengbojiangIf this argument is absent or is <b>nil</b>, 5421*572c4311Sfengbojiangreturns <code>d</code>. 5422*572c4311SfengbojiangOtherwise, raises an error. 5423*572c4311Sfengbojiang 5424*572c4311Sfengbojiang 5425*572c4311Sfengbojiang 5426*572c4311Sfengbojiang 5427*572c4311Sfengbojiang 5428*572c4311Sfengbojiang<hr><h3><a name="luaL_optstring"><code>luaL_optstring</code></a></h3><p> 5429*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>v</em>]</span> 5430*572c4311Sfengbojiang<pre>const char *luaL_optstring (lua_State *L, 5431*572c4311Sfengbojiang int narg, 5432*572c4311Sfengbojiang const char *d);</pre> 5433*572c4311Sfengbojiang 5434*572c4311Sfengbojiang<p> 5435*572c4311SfengbojiangIf the function argument <code>narg</code> is a string, 5436*572c4311Sfengbojiangreturns this string. 5437*572c4311SfengbojiangIf this argument is absent or is <b>nil</b>, 5438*572c4311Sfengbojiangreturns <code>d</code>. 5439*572c4311SfengbojiangOtherwise, raises an error. 5440*572c4311Sfengbojiang 5441*572c4311Sfengbojiang 5442*572c4311Sfengbojiang 5443*572c4311Sfengbojiang 5444*572c4311Sfengbojiang 5445*572c4311Sfengbojiang<hr><h3><a name="luaL_prepbuffer"><code>luaL_prepbuffer</code></a></h3><p> 5446*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>-</em>]</span> 5447*572c4311Sfengbojiang<pre>char *luaL_prepbuffer (luaL_Buffer *B);</pre> 5448*572c4311Sfengbojiang 5449*572c4311Sfengbojiang<p> 5450*572c4311SfengbojiangReturns an address to a space of size <a name="pdf-LUAL_BUFFERSIZE"><code>LUAL_BUFFERSIZE</code></a> 5451*572c4311Sfengbojiangwhere you can copy a string to be added to buffer <code>B</code> 5452*572c4311Sfengbojiang(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 5453*572c4311SfengbojiangAfter copying the string into this space you must call 5454*572c4311Sfengbojiang<a href="#luaL_addsize"><code>luaL_addsize</code></a> with the size of the string to actually add 5455*572c4311Sfengbojiangit to the buffer. 5456*572c4311Sfengbojiang 5457*572c4311Sfengbojiang 5458*572c4311Sfengbojiang 5459*572c4311Sfengbojiang 5460*572c4311Sfengbojiang 5461*572c4311Sfengbojiang<hr><h3><a name="luaL_pushresult"><code>luaL_pushresult</code></a></h3><p> 5462*572c4311Sfengbojiang<span class="apii">[-?, +1, <em>m</em>]</span> 5463*572c4311Sfengbojiang<pre>void luaL_pushresult (luaL_Buffer *B);</pre> 5464*572c4311Sfengbojiang 5465*572c4311Sfengbojiang<p> 5466*572c4311SfengbojiangFinishes the use of buffer <code>B</code> leaving the final string on 5467*572c4311Sfengbojiangthe top of the stack. 5468*572c4311Sfengbojiang 5469*572c4311Sfengbojiang 5470*572c4311Sfengbojiang 5471*572c4311Sfengbojiang 5472*572c4311Sfengbojiang 5473*572c4311Sfengbojiang<hr><h3><a name="luaL_ref"><code>luaL_ref</code></a></h3><p> 5474*572c4311Sfengbojiang<span class="apii">[-1, +0, <em>m</em>]</span> 5475*572c4311Sfengbojiang<pre>int luaL_ref (lua_State *L, int t);</pre> 5476*572c4311Sfengbojiang 5477*572c4311Sfengbojiang<p> 5478*572c4311SfengbojiangCreates and returns a <em>reference</em>, 5479*572c4311Sfengbojiangin the table at index <code>t</code>, 5480*572c4311Sfengbojiangfor the object at the top of the stack (and pops the object). 5481*572c4311Sfengbojiang 5482*572c4311Sfengbojiang 5483*572c4311Sfengbojiang<p> 5484*572c4311SfengbojiangA reference is a unique integer key. 5485*572c4311SfengbojiangAs long as you do not manually add integer keys into table <code>t</code>, 5486*572c4311Sfengbojiang<a href="#luaL_ref"><code>luaL_ref</code></a> ensures the uniqueness of the key it returns. 5487*572c4311SfengbojiangYou can retrieve an object referred by reference <code>r</code> 5488*572c4311Sfengbojiangby calling <code>lua_rawgeti(L, t, r)</code>. 5489*572c4311SfengbojiangFunction <a href="#luaL_unref"><code>luaL_unref</code></a> frees a reference and its associated object. 5490*572c4311Sfengbojiang 5491*572c4311Sfengbojiang 5492*572c4311Sfengbojiang<p> 5493*572c4311SfengbojiangIf the object at the top of the stack is <b>nil</b>, 5494*572c4311Sfengbojiang<a href="#luaL_ref"><code>luaL_ref</code></a> returns the constant <a name="pdf-LUA_REFNIL"><code>LUA_REFNIL</code></a>. 5495*572c4311SfengbojiangThe constant <a name="pdf-LUA_NOREF"><code>LUA_NOREF</code></a> is guaranteed to be different 5496*572c4311Sfengbojiangfrom any reference returned by <a href="#luaL_ref"><code>luaL_ref</code></a>. 5497*572c4311Sfengbojiang 5498*572c4311Sfengbojiang 5499*572c4311Sfengbojiang 5500*572c4311Sfengbojiang 5501*572c4311Sfengbojiang 5502*572c4311Sfengbojiang<hr><h3><a name="luaL_Reg"><code>luaL_Reg</code></a></h3> 5503*572c4311Sfengbojiang<pre>typedef struct luaL_Reg { 5504*572c4311Sfengbojiang const char *name; 5505*572c4311Sfengbojiang lua_CFunction func; 5506*572c4311Sfengbojiang} luaL_Reg;</pre> 5507*572c4311Sfengbojiang 5508*572c4311Sfengbojiang<p> 5509*572c4311SfengbojiangType for arrays of functions to be registered by 5510*572c4311Sfengbojiang<a href="#luaL_register"><code>luaL_register</code></a>. 5511*572c4311Sfengbojiang<code>name</code> is the function name and <code>func</code> is a pointer to 5512*572c4311Sfengbojiangthe function. 5513*572c4311SfengbojiangAny array of <a href="#luaL_Reg"><code>luaL_Reg</code></a> must end with an sentinel entry 5514*572c4311Sfengbojiangin which both <code>name</code> and <code>func</code> are <code>NULL</code>. 5515*572c4311Sfengbojiang 5516*572c4311Sfengbojiang 5517*572c4311Sfengbojiang 5518*572c4311Sfengbojiang 5519*572c4311Sfengbojiang 5520*572c4311Sfengbojiang<hr><h3><a name="luaL_register"><code>luaL_register</code></a></h3><p> 5521*572c4311Sfengbojiang<span class="apii">[-(0|1), +1, <em>m</em>]</span> 5522*572c4311Sfengbojiang<pre>void luaL_register (lua_State *L, 5523*572c4311Sfengbojiang const char *libname, 5524*572c4311Sfengbojiang const luaL_Reg *l);</pre> 5525*572c4311Sfengbojiang 5526*572c4311Sfengbojiang<p> 5527*572c4311SfengbojiangOpens a library. 5528*572c4311Sfengbojiang 5529*572c4311Sfengbojiang 5530*572c4311Sfengbojiang<p> 5531*572c4311SfengbojiangWhen called with <code>libname</code> equal to <code>NULL</code>, 5532*572c4311Sfengbojiangit simply registers all functions in the list <code>l</code> 5533*572c4311Sfengbojiang(see <a href="#luaL_Reg"><code>luaL_Reg</code></a>) into the table on the top of the stack. 5534*572c4311Sfengbojiang 5535*572c4311Sfengbojiang 5536*572c4311Sfengbojiang<p> 5537*572c4311SfengbojiangWhen called with a non-null <code>libname</code>, 5538*572c4311Sfengbojiang<code>luaL_register</code> creates a new table <code>t</code>, 5539*572c4311Sfengbojiangsets it as the value of the global variable <code>libname</code>, 5540*572c4311Sfengbojiangsets it as the value of <code>package.loaded[libname]</code>, 5541*572c4311Sfengbojiangand registers on it all functions in the list <code>l</code>. 5542*572c4311SfengbojiangIf there is a table in <code>package.loaded[libname]</code> or in 5543*572c4311Sfengbojiangvariable <code>libname</code>, 5544*572c4311Sfengbojiangreuses this table instead of creating a new one. 5545*572c4311Sfengbojiang 5546*572c4311Sfengbojiang 5547*572c4311Sfengbojiang<p> 5548*572c4311SfengbojiangIn any case the function leaves the table 5549*572c4311Sfengbojiangon the top of the stack. 5550*572c4311Sfengbojiang 5551*572c4311Sfengbojiang 5552*572c4311Sfengbojiang 5553*572c4311Sfengbojiang 5554*572c4311Sfengbojiang 5555*572c4311Sfengbojiang<hr><h3><a name="luaL_typename"><code>luaL_typename</code></a></h3><p> 5556*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>-</em>]</span> 5557*572c4311Sfengbojiang<pre>const char *luaL_typename (lua_State *L, int index);</pre> 5558*572c4311Sfengbojiang 5559*572c4311Sfengbojiang<p> 5560*572c4311SfengbojiangReturns the name of the type of the value at the given index. 5561*572c4311Sfengbojiang 5562*572c4311Sfengbojiang 5563*572c4311Sfengbojiang 5564*572c4311Sfengbojiang 5565*572c4311Sfengbojiang 5566*572c4311Sfengbojiang<hr><h3><a name="luaL_typerror"><code>luaL_typerror</code></a></h3><p> 5567*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>v</em>]</span> 5568*572c4311Sfengbojiang<pre>int luaL_typerror (lua_State *L, int narg, const char *tname);</pre> 5569*572c4311Sfengbojiang 5570*572c4311Sfengbojiang<p> 5571*572c4311SfengbojiangGenerates an error with a message like the following: 5572*572c4311Sfengbojiang 5573*572c4311Sfengbojiang<pre> 5574*572c4311Sfengbojiang <em>location</em>: bad argument <em>narg</em> to '<em>func</em>' (<em>tname</em> expected, got <em>rt</em>) 5575*572c4311Sfengbojiang</pre><p> 5576*572c4311Sfengbojiangwhere <code><em>location</em></code> is produced by <a href="#luaL_where"><code>luaL_where</code></a>, 5577*572c4311Sfengbojiang<code><em>func</em></code> is the name of the current function, 5578*572c4311Sfengbojiangand <code><em>rt</em></code> is the type name of the actual argument. 5579*572c4311Sfengbojiang 5580*572c4311Sfengbojiang 5581*572c4311Sfengbojiang 5582*572c4311Sfengbojiang 5583*572c4311Sfengbojiang 5584*572c4311Sfengbojiang<hr><h3><a name="luaL_unref"><code>luaL_unref</code></a></h3><p> 5585*572c4311Sfengbojiang<span class="apii">[-0, +0, <em>-</em>]</span> 5586*572c4311Sfengbojiang<pre>void luaL_unref (lua_State *L, int t, int ref);</pre> 5587*572c4311Sfengbojiang 5588*572c4311Sfengbojiang<p> 5589*572c4311SfengbojiangReleases reference <code>ref</code> from the table at index <code>t</code> 5590*572c4311Sfengbojiang(see <a href="#luaL_ref"><code>luaL_ref</code></a>). 5591*572c4311SfengbojiangThe entry is removed from the table, 5592*572c4311Sfengbojiangso that the referred object can be collected. 5593*572c4311SfengbojiangThe reference <code>ref</code> is also freed to be used again. 5594*572c4311Sfengbojiang 5595*572c4311Sfengbojiang 5596*572c4311Sfengbojiang<p> 5597*572c4311SfengbojiangIf <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>, 5598*572c4311Sfengbojiang<a href="#luaL_unref"><code>luaL_unref</code></a> does nothing. 5599*572c4311Sfengbojiang 5600*572c4311Sfengbojiang 5601*572c4311Sfengbojiang 5602*572c4311Sfengbojiang 5603*572c4311Sfengbojiang 5604*572c4311Sfengbojiang<hr><h3><a name="luaL_where"><code>luaL_where</code></a></h3><p> 5605*572c4311Sfengbojiang<span class="apii">[-0, +1, <em>m</em>]</span> 5606*572c4311Sfengbojiang<pre>void luaL_where (lua_State *L, int lvl);</pre> 5607*572c4311Sfengbojiang 5608*572c4311Sfengbojiang<p> 5609*572c4311SfengbojiangPushes onto the stack a string identifying the current position 5610*572c4311Sfengbojiangof the control at level <code>lvl</code> in the call stack. 5611*572c4311SfengbojiangTypically this string has the following format: 5612*572c4311Sfengbojiang 5613*572c4311Sfengbojiang<pre> 5614*572c4311Sfengbojiang <em>chunkname</em>:<em>currentline</em>: 5615*572c4311Sfengbojiang</pre><p> 5616*572c4311SfengbojiangLevel 0 is the running function, 5617*572c4311Sfengbojianglevel 1 is the function that called the running function, 5618*572c4311Sfengbojiangetc. 5619*572c4311Sfengbojiang 5620*572c4311Sfengbojiang 5621*572c4311Sfengbojiang<p> 5622*572c4311SfengbojiangThis function is used to build a prefix for error messages. 5623*572c4311Sfengbojiang 5624*572c4311Sfengbojiang 5625*572c4311Sfengbojiang 5626*572c4311Sfengbojiang 5627*572c4311Sfengbojiang 5628*572c4311Sfengbojiang 5629*572c4311Sfengbojiang 5630*572c4311Sfengbojiang<h1>5 - <a name="5">Standard Libraries</a></h1> 5631*572c4311Sfengbojiang 5632*572c4311Sfengbojiang<p> 5633*572c4311SfengbojiangThe standard Lua libraries provide useful functions 5634*572c4311Sfengbojiangthat are implemented directly through the C API. 5635*572c4311SfengbojiangSome of these functions provide essential services to the language 5636*572c4311Sfengbojiang(e.g., <a href="#pdf-type"><code>type</code></a> and <a href="#pdf-getmetatable"><code>getmetatable</code></a>); 5637*572c4311Sfengbojiangothers provide access to "outside" services (e.g., I/O); 5638*572c4311Sfengbojiangand others could be implemented in Lua itself, 5639*572c4311Sfengbojiangbut are quite useful or have critical performance requirements that 5640*572c4311Sfengbojiangdeserve an implementation in C (e.g., <a href="#pdf-table.sort"><code>table.sort</code></a>). 5641*572c4311Sfengbojiang 5642*572c4311Sfengbojiang 5643*572c4311Sfengbojiang<p> 5644*572c4311SfengbojiangAll libraries are implemented through the official C API 5645*572c4311Sfengbojiangand are provided as separate C modules. 5646*572c4311SfengbojiangCurrently, Lua has the following standard libraries: 5647*572c4311Sfengbojiang 5648*572c4311Sfengbojiang<ul> 5649*572c4311Sfengbojiang 5650*572c4311Sfengbojiang<li>basic library, which includes the coroutine sub-library;</li> 5651*572c4311Sfengbojiang 5652*572c4311Sfengbojiang<li>package library;</li> 5653*572c4311Sfengbojiang 5654*572c4311Sfengbojiang<li>string manipulation;</li> 5655*572c4311Sfengbojiang 5656*572c4311Sfengbojiang<li>table manipulation;</li> 5657*572c4311Sfengbojiang 5658*572c4311Sfengbojiang<li>mathematical functions (sin, log, etc.);</li> 5659*572c4311Sfengbojiang 5660*572c4311Sfengbojiang<li>input and output;</li> 5661*572c4311Sfengbojiang 5662*572c4311Sfengbojiang<li>operating system facilities;</li> 5663*572c4311Sfengbojiang 5664*572c4311Sfengbojiang<li>debug facilities.</li> 5665*572c4311Sfengbojiang 5666*572c4311Sfengbojiang</ul><p> 5667*572c4311SfengbojiangExcept for the basic and package libraries, 5668*572c4311Sfengbojiangeach library provides all its functions as fields of a global table 5669*572c4311Sfengbojiangor as methods of its objects. 5670*572c4311Sfengbojiang 5671*572c4311Sfengbojiang 5672*572c4311Sfengbojiang<p> 5673*572c4311SfengbojiangTo have access to these libraries, 5674*572c4311Sfengbojiangthe C host program should call the <a href="#luaL_openlibs"><code>luaL_openlibs</code></a> function, 5675*572c4311Sfengbojiangwhich opens all standard libraries. 5676*572c4311SfengbojiangAlternatively, 5677*572c4311Sfengbojiangit can open them individually by calling 5678*572c4311Sfengbojiang<a name="pdf-luaopen_base"><code>luaopen_base</code></a> (for the basic library), 5679*572c4311Sfengbojiang<a name="pdf-luaopen_package"><code>luaopen_package</code></a> (for the package library), 5680*572c4311Sfengbojiang<a name="pdf-luaopen_string"><code>luaopen_string</code></a> (for the string library), 5681*572c4311Sfengbojiang<a name="pdf-luaopen_table"><code>luaopen_table</code></a> (for the table library), 5682*572c4311Sfengbojiang<a name="pdf-luaopen_math"><code>luaopen_math</code></a> (for the mathematical library), 5683*572c4311Sfengbojiang<a name="pdf-luaopen_io"><code>luaopen_io</code></a> (for the I/O library), 5684*572c4311Sfengbojiang<a name="pdf-luaopen_os"><code>luaopen_os</code></a> (for the Operating System library), 5685*572c4311Sfengbojiangand <a name="pdf-luaopen_debug"><code>luaopen_debug</code></a> (for the debug library). 5686*572c4311SfengbojiangThese functions are declared in <a name="pdf-lualib.h"><code>lualib.h</code></a> 5687*572c4311Sfengbojiangand should not be called directly: 5688*572c4311Sfengbojiangyou must call them like any other Lua C function, 5689*572c4311Sfengbojiange.g., by using <a href="#lua_call"><code>lua_call</code></a>. 5690*572c4311Sfengbojiang 5691*572c4311Sfengbojiang 5692*572c4311Sfengbojiang 5693*572c4311Sfengbojiang<h2>5.1 - <a name="5.1">Basic Functions</a></h2> 5694*572c4311Sfengbojiang 5695*572c4311Sfengbojiang<p> 5696*572c4311SfengbojiangThe basic library provides some core functions to Lua. 5697*572c4311SfengbojiangIf you do not include this library in your application, 5698*572c4311Sfengbojiangyou should check carefully whether you need to provide 5699*572c4311Sfengbojiangimplementations for some of its facilities. 5700*572c4311Sfengbojiang 5701*572c4311Sfengbojiang 5702*572c4311Sfengbojiang<p> 5703*572c4311Sfengbojiang<hr><h3><a name="pdf-assert"><code>assert (v [, message])</code></a></h3> 5704*572c4311SfengbojiangIssues an error when 5705*572c4311Sfengbojiangthe value of its argument <code>v</code> is false (i.e., <b>nil</b> or <b>false</b>); 5706*572c4311Sfengbojiangotherwise, returns all its arguments. 5707*572c4311Sfengbojiang<code>message</code> is an error message; 5708*572c4311Sfengbojiangwhen absent, it defaults to "assertion failed!" 5709*572c4311Sfengbojiang 5710*572c4311Sfengbojiang 5711*572c4311Sfengbojiang 5712*572c4311Sfengbojiang 5713*572c4311Sfengbojiang<p> 5714*572c4311Sfengbojiang<hr><h3><a name="pdf-collectgarbage"><code>collectgarbage ([opt [, arg]])</code></a></h3> 5715*572c4311Sfengbojiang 5716*572c4311Sfengbojiang 5717*572c4311Sfengbojiang<p> 5718*572c4311SfengbojiangThis function is a generic interface to the garbage collector. 5719*572c4311SfengbojiangIt performs different functions according to its first argument, <code>opt</code>: 5720*572c4311Sfengbojiang 5721*572c4311Sfengbojiang<ul> 5722*572c4311Sfengbojiang 5723*572c4311Sfengbojiang<li><b>"collect":</b> 5724*572c4311Sfengbojiangperforms a full garbage-collection cycle. 5725*572c4311SfengbojiangThis is the default option. 5726*572c4311Sfengbojiang</li> 5727*572c4311Sfengbojiang 5728*572c4311Sfengbojiang<li><b>"stop":</b> 5729*572c4311Sfengbojiangstops the garbage collector. 5730*572c4311Sfengbojiang</li> 5731*572c4311Sfengbojiang 5732*572c4311Sfengbojiang<li><b>"restart":</b> 5733*572c4311Sfengbojiangrestarts the garbage collector. 5734*572c4311Sfengbojiang</li> 5735*572c4311Sfengbojiang 5736*572c4311Sfengbojiang<li><b>"count":</b> 5737*572c4311Sfengbojiangreturns the total memory in use by Lua (in Kbytes). 5738*572c4311Sfengbojiang</li> 5739*572c4311Sfengbojiang 5740*572c4311Sfengbojiang<li><b>"step":</b> 5741*572c4311Sfengbojiangperforms a garbage-collection step. 5742*572c4311SfengbojiangThe step "size" is controlled by <code>arg</code> 5743*572c4311Sfengbojiang(larger values mean more steps) in a non-specified way. 5744*572c4311SfengbojiangIf you want to control the step size 5745*572c4311Sfengbojiangyou must experimentally tune the value of <code>arg</code>. 5746*572c4311SfengbojiangReturns <b>true</b> if the step finished a collection cycle. 5747*572c4311Sfengbojiang</li> 5748*572c4311Sfengbojiang 5749*572c4311Sfengbojiang<li><b>"setpause":</b> 5750*572c4311Sfengbojiangsets <code>arg</code> as the new value for the <em>pause</em> of 5751*572c4311Sfengbojiangthe collector (see <a href="#2.10">§2.10</a>). 5752*572c4311SfengbojiangReturns the previous value for <em>pause</em>. 5753*572c4311Sfengbojiang</li> 5754*572c4311Sfengbojiang 5755*572c4311Sfengbojiang<li><b>"setstepmul":</b> 5756*572c4311Sfengbojiangsets <code>arg</code> as the new value for the <em>step multiplier</em> of 5757*572c4311Sfengbojiangthe collector (see <a href="#2.10">§2.10</a>). 5758*572c4311SfengbojiangReturns the previous value for <em>step</em>. 5759*572c4311Sfengbojiang</li> 5760*572c4311Sfengbojiang 5761*572c4311Sfengbojiang</ul> 5762*572c4311Sfengbojiang 5763*572c4311Sfengbojiang 5764*572c4311Sfengbojiang 5765*572c4311Sfengbojiang<p> 5766*572c4311Sfengbojiang<hr><h3><a name="pdf-dofile"><code>dofile ([filename])</code></a></h3> 5767*572c4311SfengbojiangOpens the named file and executes its contents as a Lua chunk. 5768*572c4311SfengbojiangWhen called without arguments, 5769*572c4311Sfengbojiang<code>dofile</code> executes the contents of the standard input (<code>stdin</code>). 5770*572c4311SfengbojiangReturns all values returned by the chunk. 5771*572c4311SfengbojiangIn case of errors, <code>dofile</code> propagates the error 5772*572c4311Sfengbojiangto its caller (that is, <code>dofile</code> does not run in protected mode). 5773*572c4311Sfengbojiang 5774*572c4311Sfengbojiang 5775*572c4311Sfengbojiang 5776*572c4311Sfengbojiang 5777*572c4311Sfengbojiang<p> 5778*572c4311Sfengbojiang<hr><h3><a name="pdf-error"><code>error (message [, level])</code></a></h3> 5779*572c4311SfengbojiangTerminates the last protected function called 5780*572c4311Sfengbojiangand returns <code>message</code> as the error message. 5781*572c4311SfengbojiangFunction <code>error</code> never returns. 5782*572c4311Sfengbojiang 5783*572c4311Sfengbojiang 5784*572c4311Sfengbojiang<p> 5785*572c4311SfengbojiangUsually, <code>error</code> adds some information about the error position 5786*572c4311Sfengbojiangat the beginning of the message. 5787*572c4311SfengbojiangThe <code>level</code> argument specifies how to get the error position. 5788*572c4311SfengbojiangWith level 1 (the default), the error position is where the 5789*572c4311Sfengbojiang<code>error</code> function was called. 5790*572c4311SfengbojiangLevel 2 points the error to where the function 5791*572c4311Sfengbojiangthat called <code>error</code> was called; and so on. 5792*572c4311SfengbojiangPassing a level 0 avoids the addition of error position information 5793*572c4311Sfengbojiangto the message. 5794*572c4311Sfengbojiang 5795*572c4311Sfengbojiang 5796*572c4311Sfengbojiang 5797*572c4311Sfengbojiang 5798*572c4311Sfengbojiang<p> 5799*572c4311Sfengbojiang<hr><h3><a name="pdf-_G"><code>_G</code></a></h3> 5800*572c4311SfengbojiangA global variable (not a function) that 5801*572c4311Sfengbojiangholds the global environment (that is, <code>_G._G = _G</code>). 5802*572c4311SfengbojiangLua itself does not use this variable; 5803*572c4311Sfengbojiangchanging its value does not affect any environment, 5804*572c4311Sfengbojiangnor vice-versa. 5805*572c4311Sfengbojiang(Use <a href="#pdf-setfenv"><code>setfenv</code></a> to change environments.) 5806*572c4311Sfengbojiang 5807*572c4311Sfengbojiang 5808*572c4311Sfengbojiang 5809*572c4311Sfengbojiang 5810*572c4311Sfengbojiang<p> 5811*572c4311Sfengbojiang<hr><h3><a name="pdf-getfenv"><code>getfenv ([f])</code></a></h3> 5812*572c4311SfengbojiangReturns the current environment in use by the function. 5813*572c4311Sfengbojiang<code>f</code> can be a Lua function or a number 5814*572c4311Sfengbojiangthat specifies the function at that stack level: 5815*572c4311SfengbojiangLevel 1 is the function calling <code>getfenv</code>. 5816*572c4311SfengbojiangIf the given function is not a Lua function, 5817*572c4311Sfengbojiangor if <code>f</code> is 0, 5818*572c4311Sfengbojiang<code>getfenv</code> returns the global environment. 5819*572c4311SfengbojiangThe default for <code>f</code> is 1. 5820*572c4311Sfengbojiang 5821*572c4311Sfengbojiang 5822*572c4311Sfengbojiang 5823*572c4311Sfengbojiang 5824*572c4311Sfengbojiang<p> 5825*572c4311Sfengbojiang<hr><h3><a name="pdf-getmetatable"><code>getmetatable (object)</code></a></h3> 5826*572c4311Sfengbojiang 5827*572c4311Sfengbojiang 5828*572c4311Sfengbojiang<p> 5829*572c4311SfengbojiangIf <code>object</code> does not have a metatable, returns <b>nil</b>. 5830*572c4311SfengbojiangOtherwise, 5831*572c4311Sfengbojiangif the object's metatable has a <code>"__metatable"</code> field, 5832*572c4311Sfengbojiangreturns the associated value. 5833*572c4311SfengbojiangOtherwise, returns the metatable of the given object. 5834*572c4311Sfengbojiang 5835*572c4311Sfengbojiang 5836*572c4311Sfengbojiang 5837*572c4311Sfengbojiang 5838*572c4311Sfengbojiang<p> 5839*572c4311Sfengbojiang<hr><h3><a name="pdf-ipairs"><code>ipairs (t)</code></a></h3> 5840*572c4311Sfengbojiang 5841*572c4311Sfengbojiang 5842*572c4311Sfengbojiang<p> 5843*572c4311SfengbojiangReturns three values: an iterator function, the table <code>t</code>, and 0, 5844*572c4311Sfengbojiangso that the construction 5845*572c4311Sfengbojiang 5846*572c4311Sfengbojiang<pre> 5847*572c4311Sfengbojiang for i,v in ipairs(t) do <em>body</em> end 5848*572c4311Sfengbojiang</pre><p> 5849*572c4311Sfengbojiangwill iterate over the pairs (<code>1,t[1]</code>), (<code>2,t[2]</code>), ···, 5850*572c4311Sfengbojiangup to the first integer key absent from the table. 5851*572c4311Sfengbojiang 5852*572c4311Sfengbojiang 5853*572c4311Sfengbojiang 5854*572c4311Sfengbojiang 5855*572c4311Sfengbojiang<p> 5856*572c4311Sfengbojiang<hr><h3><a name="pdf-load"><code>load (func [, chunkname])</code></a></h3> 5857*572c4311Sfengbojiang 5858*572c4311Sfengbojiang 5859*572c4311Sfengbojiang<p> 5860*572c4311SfengbojiangLoads a chunk using function <code>func</code> to get its pieces. 5861*572c4311SfengbojiangEach call to <code>func</code> must return a string that concatenates 5862*572c4311Sfengbojiangwith previous results. 5863*572c4311SfengbojiangA return of an empty string, <b>nil</b>, or no value signals the end of the chunk. 5864*572c4311Sfengbojiang 5865*572c4311Sfengbojiang 5866*572c4311Sfengbojiang<p> 5867*572c4311SfengbojiangIf there are no errors, 5868*572c4311Sfengbojiangreturns the compiled chunk as a function; 5869*572c4311Sfengbojiangotherwise, returns <b>nil</b> plus the error message. 5870*572c4311SfengbojiangThe environment of the returned function is the global environment. 5871*572c4311Sfengbojiang 5872*572c4311Sfengbojiang 5873*572c4311Sfengbojiang<p> 5874*572c4311Sfengbojiang<code>chunkname</code> is used as the chunk name for error messages 5875*572c4311Sfengbojiangand debug information. 5876*572c4311SfengbojiangWhen absent, 5877*572c4311Sfengbojiangit defaults to "<code>=(load)</code>". 5878*572c4311Sfengbojiang 5879*572c4311Sfengbojiang 5880*572c4311Sfengbojiang 5881*572c4311Sfengbojiang 5882*572c4311Sfengbojiang<p> 5883*572c4311Sfengbojiang<hr><h3><a name="pdf-loadfile"><code>loadfile ([filename])</code></a></h3> 5884*572c4311Sfengbojiang 5885*572c4311Sfengbojiang 5886*572c4311Sfengbojiang<p> 5887*572c4311SfengbojiangSimilar to <a href="#pdf-load"><code>load</code></a>, 5888*572c4311Sfengbojiangbut gets the chunk from file <code>filename</code> 5889*572c4311Sfengbojiangor from the standard input, 5890*572c4311Sfengbojiangif no file name is given. 5891*572c4311Sfengbojiang 5892*572c4311Sfengbojiang 5893*572c4311Sfengbojiang 5894*572c4311Sfengbojiang 5895*572c4311Sfengbojiang<p> 5896*572c4311Sfengbojiang<hr><h3><a name="pdf-loadstring"><code>loadstring (string [, chunkname])</code></a></h3> 5897*572c4311Sfengbojiang 5898*572c4311Sfengbojiang 5899*572c4311Sfengbojiang<p> 5900*572c4311SfengbojiangSimilar to <a href="#pdf-load"><code>load</code></a>, 5901*572c4311Sfengbojiangbut gets the chunk from the given string. 5902*572c4311Sfengbojiang 5903*572c4311Sfengbojiang 5904*572c4311Sfengbojiang<p> 5905*572c4311SfengbojiangTo load and run a given string, use the idiom 5906*572c4311Sfengbojiang 5907*572c4311Sfengbojiang<pre> 5908*572c4311Sfengbojiang assert(loadstring(s))() 5909*572c4311Sfengbojiang</pre> 5910*572c4311Sfengbojiang 5911*572c4311Sfengbojiang<p> 5912*572c4311SfengbojiangWhen absent, 5913*572c4311Sfengbojiang<code>chunkname</code> defaults to the given string. 5914*572c4311Sfengbojiang 5915*572c4311Sfengbojiang 5916*572c4311Sfengbojiang 5917*572c4311Sfengbojiang 5918*572c4311Sfengbojiang<p> 5919*572c4311Sfengbojiang<hr><h3><a name="pdf-next"><code>next (table [, index])</code></a></h3> 5920*572c4311Sfengbojiang 5921*572c4311Sfengbojiang 5922*572c4311Sfengbojiang<p> 5923*572c4311SfengbojiangAllows a program to traverse all fields of a table. 5924*572c4311SfengbojiangIts first argument is a table and its second argument 5925*572c4311Sfengbojiangis an index in this table. 5926*572c4311Sfengbojiang<code>next</code> returns the next index of the table 5927*572c4311Sfengbojiangand its associated value. 5928*572c4311SfengbojiangWhen called with <b>nil</b> as its second argument, 5929*572c4311Sfengbojiang<code>next</code> returns an initial index 5930*572c4311Sfengbojiangand its associated value. 5931*572c4311SfengbojiangWhen called with the last index, 5932*572c4311Sfengbojiangor with <b>nil</b> in an empty table, 5933*572c4311Sfengbojiang<code>next</code> returns <b>nil</b>. 5934*572c4311SfengbojiangIf the second argument is absent, then it is interpreted as <b>nil</b>. 5935*572c4311SfengbojiangIn particular, 5936*572c4311Sfengbojiangyou can use <code>next(t)</code> to check whether a table is empty. 5937*572c4311Sfengbojiang 5938*572c4311Sfengbojiang 5939*572c4311Sfengbojiang<p> 5940*572c4311SfengbojiangThe order in which the indices are enumerated is not specified, 5941*572c4311Sfengbojiang<em>even for numeric indices</em>. 5942*572c4311Sfengbojiang(To traverse a table in numeric order, 5943*572c4311Sfengbojianguse a numerical <b>for</b> or the <a href="#pdf-ipairs"><code>ipairs</code></a> function.) 5944*572c4311Sfengbojiang 5945*572c4311Sfengbojiang 5946*572c4311Sfengbojiang<p> 5947*572c4311SfengbojiangThe behavior of <code>next</code> is <em>undefined</em> if, 5948*572c4311Sfengbojiangduring the traversal, 5949*572c4311Sfengbojiangyou assign any value to a non-existent field in the table. 5950*572c4311SfengbojiangYou may however modify existing fields. 5951*572c4311SfengbojiangIn particular, you may clear existing fields. 5952*572c4311Sfengbojiang 5953*572c4311Sfengbojiang 5954*572c4311Sfengbojiang 5955*572c4311Sfengbojiang 5956*572c4311Sfengbojiang<p> 5957*572c4311Sfengbojiang<hr><h3><a name="pdf-pairs"><code>pairs (t)</code></a></h3> 5958*572c4311Sfengbojiang 5959*572c4311Sfengbojiang 5960*572c4311Sfengbojiang<p> 5961*572c4311SfengbojiangReturns three values: the <a href="#pdf-next"><code>next</code></a> function, the table <code>t</code>, and <b>nil</b>, 5962*572c4311Sfengbojiangso that the construction 5963*572c4311Sfengbojiang 5964*572c4311Sfengbojiang<pre> 5965*572c4311Sfengbojiang for k,v in pairs(t) do <em>body</em> end 5966*572c4311Sfengbojiang</pre><p> 5967*572c4311Sfengbojiangwill iterate over all key–value pairs of table <code>t</code>. 5968*572c4311Sfengbojiang 5969*572c4311Sfengbojiang 5970*572c4311Sfengbojiang<p> 5971*572c4311SfengbojiangSee function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying 5972*572c4311Sfengbojiangthe table during its traversal. 5973*572c4311Sfengbojiang 5974*572c4311Sfengbojiang 5975*572c4311Sfengbojiang 5976*572c4311Sfengbojiang 5977*572c4311Sfengbojiang<p> 5978*572c4311Sfengbojiang<hr><h3><a name="pdf-pcall"><code>pcall (f, arg1, ···)</code></a></h3> 5979*572c4311Sfengbojiang 5980*572c4311Sfengbojiang 5981*572c4311Sfengbojiang<p> 5982*572c4311SfengbojiangCalls function <code>f</code> with 5983*572c4311Sfengbojiangthe given arguments in <em>protected mode</em>. 5984*572c4311SfengbojiangThis means that any error inside <code>f</code> is not propagated; 5985*572c4311Sfengbojianginstead, <code>pcall</code> catches the error 5986*572c4311Sfengbojiangand returns a status code. 5987*572c4311SfengbojiangIts first result is the status code (a boolean), 5988*572c4311Sfengbojiangwhich is true if the call succeeds without errors. 5989*572c4311SfengbojiangIn such case, <code>pcall</code> also returns all results from the call, 5990*572c4311Sfengbojiangafter this first result. 5991*572c4311SfengbojiangIn case of any error, <code>pcall</code> returns <b>false</b> plus the error message. 5992*572c4311Sfengbojiang 5993*572c4311Sfengbojiang 5994*572c4311Sfengbojiang 5995*572c4311Sfengbojiang 5996*572c4311Sfengbojiang<p> 5997*572c4311Sfengbojiang<hr><h3><a name="pdf-print"><code>print (···)</code></a></h3> 5998*572c4311SfengbojiangReceives any number of arguments, 5999*572c4311Sfengbojiangand prints their values to <code>stdout</code>, 6000*572c4311Sfengbojiangusing the <a href="#pdf-tostring"><code>tostring</code></a> function to convert them to strings. 6001*572c4311Sfengbojiang<code>print</code> is not intended for formatted output, 6002*572c4311Sfengbojiangbut only as a quick way to show a value, 6003*572c4311Sfengbojiangtypically for debugging. 6004*572c4311SfengbojiangFor formatted output, use <a href="#pdf-string.format"><code>string.format</code></a>. 6005*572c4311Sfengbojiang 6006*572c4311Sfengbojiang 6007*572c4311Sfengbojiang 6008*572c4311Sfengbojiang 6009*572c4311Sfengbojiang<p> 6010*572c4311Sfengbojiang<hr><h3><a name="pdf-rawequal"><code>rawequal (v1, v2)</code></a></h3> 6011*572c4311SfengbojiangChecks whether <code>v1</code> is equal to <code>v2</code>, 6012*572c4311Sfengbojiangwithout invoking any metamethod. 6013*572c4311SfengbojiangReturns a boolean. 6014*572c4311Sfengbojiang 6015*572c4311Sfengbojiang 6016*572c4311Sfengbojiang 6017*572c4311Sfengbojiang 6018*572c4311Sfengbojiang<p> 6019*572c4311Sfengbojiang<hr><h3><a name="pdf-rawget"><code>rawget (table, index)</code></a></h3> 6020*572c4311SfengbojiangGets the real value of <code>table[index]</code>, 6021*572c4311Sfengbojiangwithout invoking any metamethod. 6022*572c4311Sfengbojiang<code>table</code> must be a table; 6023*572c4311Sfengbojiang<code>index</code> may be any value. 6024*572c4311Sfengbojiang 6025*572c4311Sfengbojiang 6026*572c4311Sfengbojiang 6027*572c4311Sfengbojiang 6028*572c4311Sfengbojiang<p> 6029*572c4311Sfengbojiang<hr><h3><a name="pdf-rawset"><code>rawset (table, index, value)</code></a></h3> 6030*572c4311SfengbojiangSets the real value of <code>table[index]</code> to <code>value</code>, 6031*572c4311Sfengbojiangwithout invoking any metamethod. 6032*572c4311Sfengbojiang<code>table</code> must be a table, 6033*572c4311Sfengbojiang<code>index</code> any value different from <b>nil</b>, 6034*572c4311Sfengbojiangand <code>value</code> any Lua value. 6035*572c4311Sfengbojiang 6036*572c4311Sfengbojiang 6037*572c4311Sfengbojiang<p> 6038*572c4311SfengbojiangThis function returns <code>table</code>. 6039*572c4311Sfengbojiang 6040*572c4311Sfengbojiang 6041*572c4311Sfengbojiang 6042*572c4311Sfengbojiang 6043*572c4311Sfengbojiang<p> 6044*572c4311Sfengbojiang<hr><h3><a name="pdf-select"><code>select (index, ···)</code></a></h3> 6045*572c4311Sfengbojiang 6046*572c4311Sfengbojiang 6047*572c4311Sfengbojiang<p> 6048*572c4311SfengbojiangIf <code>index</code> is a number, 6049*572c4311Sfengbojiangreturns all arguments after argument number <code>index</code>. 6050*572c4311SfengbojiangOtherwise, <code>index</code> must be the string <code>"#"</code>, 6051*572c4311Sfengbojiangand <code>select</code> returns the total number of extra arguments it received. 6052*572c4311Sfengbojiang 6053*572c4311Sfengbojiang 6054*572c4311Sfengbojiang 6055*572c4311Sfengbojiang 6056*572c4311Sfengbojiang<p> 6057*572c4311Sfengbojiang<hr><h3><a name="pdf-setfenv"><code>setfenv (f, table)</code></a></h3> 6058*572c4311Sfengbojiang 6059*572c4311Sfengbojiang 6060*572c4311Sfengbojiang<p> 6061*572c4311SfengbojiangSets the environment to be used by the given function. 6062*572c4311Sfengbojiang<code>f</code> can be a Lua function or a number 6063*572c4311Sfengbojiangthat specifies the function at that stack level: 6064*572c4311SfengbojiangLevel 1 is the function calling <code>setfenv</code>. 6065*572c4311Sfengbojiang<code>setfenv</code> returns the given function. 6066*572c4311Sfengbojiang 6067*572c4311Sfengbojiang 6068*572c4311Sfengbojiang<p> 6069*572c4311SfengbojiangAs a special case, when <code>f</code> is 0 <code>setfenv</code> changes 6070*572c4311Sfengbojiangthe environment of the running thread. 6071*572c4311SfengbojiangIn this case, <code>setfenv</code> returns no values. 6072*572c4311Sfengbojiang 6073*572c4311Sfengbojiang 6074*572c4311Sfengbojiang 6075*572c4311Sfengbojiang 6076*572c4311Sfengbojiang<p> 6077*572c4311Sfengbojiang<hr><h3><a name="pdf-setmetatable"><code>setmetatable (table, metatable)</code></a></h3> 6078*572c4311Sfengbojiang 6079*572c4311Sfengbojiang 6080*572c4311Sfengbojiang<p> 6081*572c4311SfengbojiangSets the metatable for the given table. 6082*572c4311Sfengbojiang(You cannot change the metatable of other types from Lua, only from C.) 6083*572c4311SfengbojiangIf <code>metatable</code> is <b>nil</b>, 6084*572c4311Sfengbojiangremoves the metatable of the given table. 6085*572c4311SfengbojiangIf the original metatable has a <code>"__metatable"</code> field, 6086*572c4311Sfengbojiangraises an error. 6087*572c4311Sfengbojiang 6088*572c4311Sfengbojiang 6089*572c4311Sfengbojiang<p> 6090*572c4311SfengbojiangThis function returns <code>table</code>. 6091*572c4311Sfengbojiang 6092*572c4311Sfengbojiang 6093*572c4311Sfengbojiang 6094*572c4311Sfengbojiang 6095*572c4311Sfengbojiang<p> 6096*572c4311Sfengbojiang<hr><h3><a name="pdf-tonumber"><code>tonumber (e [, base])</code></a></h3> 6097*572c4311SfengbojiangTries to convert its argument to a number. 6098*572c4311SfengbojiangIf the argument is already a number or a string convertible 6099*572c4311Sfengbojiangto a number, then <code>tonumber</code> returns this number; 6100*572c4311Sfengbojiangotherwise, it returns <b>nil</b>. 6101*572c4311Sfengbojiang 6102*572c4311Sfengbojiang 6103*572c4311Sfengbojiang<p> 6104*572c4311SfengbojiangAn optional argument specifies the base to interpret the numeral. 6105*572c4311SfengbojiangThe base may be any integer between 2 and 36, inclusive. 6106*572c4311SfengbojiangIn bases above 10, the letter '<code>A</code>' (in either upper or lower case) 6107*572c4311Sfengbojiangrepresents 10, '<code>B</code>' represents 11, and so forth, 6108*572c4311Sfengbojiangwith '<code>Z</code>' representing 35. 6109*572c4311SfengbojiangIn base 10 (the default), the number can have a decimal part, 6110*572c4311Sfengbojiangas well as an optional exponent part (see <a href="#2.1">§2.1</a>). 6111*572c4311SfengbojiangIn other bases, only unsigned integers are accepted. 6112*572c4311Sfengbojiang 6113*572c4311Sfengbojiang 6114*572c4311Sfengbojiang 6115*572c4311Sfengbojiang 6116*572c4311Sfengbojiang<p> 6117*572c4311Sfengbojiang<hr><h3><a name="pdf-tostring"><code>tostring (e)</code></a></h3> 6118*572c4311SfengbojiangReceives an argument of any type and 6119*572c4311Sfengbojiangconverts it to a string in a reasonable format. 6120*572c4311SfengbojiangFor complete control of how numbers are converted, 6121*572c4311Sfengbojianguse <a href="#pdf-string.format"><code>string.format</code></a>. 6122*572c4311Sfengbojiang 6123*572c4311Sfengbojiang 6124*572c4311Sfengbojiang<p> 6125*572c4311SfengbojiangIf the metatable of <code>e</code> has a <code>"__tostring"</code> field, 6126*572c4311Sfengbojiangthen <code>tostring</code> calls the corresponding value 6127*572c4311Sfengbojiangwith <code>e</code> as argument, 6128*572c4311Sfengbojiangand uses the result of the call as its result. 6129*572c4311Sfengbojiang 6130*572c4311Sfengbojiang 6131*572c4311Sfengbojiang 6132*572c4311Sfengbojiang 6133*572c4311Sfengbojiang<p> 6134*572c4311Sfengbojiang<hr><h3><a name="pdf-type"><code>type (v)</code></a></h3> 6135*572c4311SfengbojiangReturns the type of its only argument, coded as a string. 6136*572c4311SfengbojiangThe possible results of this function are 6137*572c4311Sfengbojiang"<code>nil</code>" (a string, not the value <b>nil</b>), 6138*572c4311Sfengbojiang"<code>number</code>", 6139*572c4311Sfengbojiang"<code>string</code>", 6140*572c4311Sfengbojiang"<code>boolean</code>", 6141*572c4311Sfengbojiang"<code>table</code>", 6142*572c4311Sfengbojiang"<code>function</code>", 6143*572c4311Sfengbojiang"<code>thread</code>", 6144*572c4311Sfengbojiangand "<code>userdata</code>". 6145*572c4311Sfengbojiang 6146*572c4311Sfengbojiang 6147*572c4311Sfengbojiang 6148*572c4311Sfengbojiang 6149*572c4311Sfengbojiang<p> 6150*572c4311Sfengbojiang<hr><h3><a name="pdf-unpack"><code>unpack (list [, i [, j]])</code></a></h3> 6151*572c4311SfengbojiangReturns the elements from the given table. 6152*572c4311SfengbojiangThis function is equivalent to 6153*572c4311Sfengbojiang 6154*572c4311Sfengbojiang<pre> 6155*572c4311Sfengbojiang return list[i], list[i+1], ···, list[j] 6156*572c4311Sfengbojiang</pre><p> 6157*572c4311Sfengbojiangexcept that the above code can be written only for a fixed number 6158*572c4311Sfengbojiangof elements. 6159*572c4311SfengbojiangBy default, <code>i</code> is 1 and <code>j</code> is the length of the list, 6160*572c4311Sfengbojiangas defined by the length operator (see <a href="#2.5.5">§2.5.5</a>). 6161*572c4311Sfengbojiang 6162*572c4311Sfengbojiang 6163*572c4311Sfengbojiang 6164*572c4311Sfengbojiang 6165*572c4311Sfengbojiang<p> 6166*572c4311Sfengbojiang<hr><h3><a name="pdf-_VERSION"><code>_VERSION</code></a></h3> 6167*572c4311SfengbojiangA global variable (not a function) that 6168*572c4311Sfengbojiangholds a string containing the current interpreter version. 6169*572c4311SfengbojiangThe current contents of this variable is "<code>Lua 5.1</code>". 6170*572c4311Sfengbojiang 6171*572c4311Sfengbojiang 6172*572c4311Sfengbojiang 6173*572c4311Sfengbojiang 6174*572c4311Sfengbojiang<p> 6175*572c4311Sfengbojiang<hr><h3><a name="pdf-xpcall"><code>xpcall (f, err)</code></a></h3> 6176*572c4311Sfengbojiang 6177*572c4311Sfengbojiang 6178*572c4311Sfengbojiang<p> 6179*572c4311SfengbojiangThis function is similar to <a href="#pdf-pcall"><code>pcall</code></a>, 6180*572c4311Sfengbojiangexcept that you can set a new error handler. 6181*572c4311Sfengbojiang 6182*572c4311Sfengbojiang 6183*572c4311Sfengbojiang<p> 6184*572c4311Sfengbojiang<code>xpcall</code> calls function <code>f</code> in protected mode, 6185*572c4311Sfengbojiangusing <code>err</code> as the error handler. 6186*572c4311SfengbojiangAny error inside <code>f</code> is not propagated; 6187*572c4311Sfengbojianginstead, <code>xpcall</code> catches the error, 6188*572c4311Sfengbojiangcalls the <code>err</code> function with the original error object, 6189*572c4311Sfengbojiangand returns a status code. 6190*572c4311SfengbojiangIts first result is the status code (a boolean), 6191*572c4311Sfengbojiangwhich is true if the call succeeds without errors. 6192*572c4311SfengbojiangIn this case, <code>xpcall</code> also returns all results from the call, 6193*572c4311Sfengbojiangafter this first result. 6194*572c4311SfengbojiangIn case of any error, 6195*572c4311Sfengbojiang<code>xpcall</code> returns <b>false</b> plus the result from <code>err</code>. 6196*572c4311Sfengbojiang 6197*572c4311Sfengbojiang 6198*572c4311Sfengbojiang 6199*572c4311Sfengbojiang 6200*572c4311Sfengbojiang 6201*572c4311Sfengbojiang 6202*572c4311Sfengbojiang 6203*572c4311Sfengbojiang<h2>5.2 - <a name="5.2">Coroutine Manipulation</a></h2> 6204*572c4311Sfengbojiang 6205*572c4311Sfengbojiang<p> 6206*572c4311SfengbojiangThe operations related to coroutines comprise a sub-library of 6207*572c4311Sfengbojiangthe basic library and come inside the table <a name="pdf-coroutine"><code>coroutine</code></a>. 6208*572c4311SfengbojiangSee <a href="#2.11">§2.11</a> for a general description of coroutines. 6209*572c4311Sfengbojiang 6210*572c4311Sfengbojiang 6211*572c4311Sfengbojiang<p> 6212*572c4311Sfengbojiang<hr><h3><a name="pdf-coroutine.create"><code>coroutine.create (f)</code></a></h3> 6213*572c4311Sfengbojiang 6214*572c4311Sfengbojiang 6215*572c4311Sfengbojiang<p> 6216*572c4311SfengbojiangCreates a new coroutine, with body <code>f</code>. 6217*572c4311Sfengbojiang<code>f</code> must be a Lua function. 6218*572c4311SfengbojiangReturns this new coroutine, 6219*572c4311Sfengbojiangan object with type <code>"thread"</code>. 6220*572c4311Sfengbojiang 6221*572c4311Sfengbojiang 6222*572c4311Sfengbojiang 6223*572c4311Sfengbojiang 6224*572c4311Sfengbojiang<p> 6225*572c4311Sfengbojiang<hr><h3><a name="pdf-coroutine.resume"><code>coroutine.resume (co [, val1, ···])</code></a></h3> 6226*572c4311Sfengbojiang 6227*572c4311Sfengbojiang 6228*572c4311Sfengbojiang<p> 6229*572c4311SfengbojiangStarts or continues the execution of coroutine <code>co</code>. 6230*572c4311SfengbojiangThe first time you resume a coroutine, 6231*572c4311Sfengbojiangit starts running its body. 6232*572c4311SfengbojiangThe values <code>val1</code>, ··· are passed 6233*572c4311Sfengbojiangas the arguments to the body function. 6234*572c4311SfengbojiangIf the coroutine has yielded, 6235*572c4311Sfengbojiang<code>resume</code> restarts it; 6236*572c4311Sfengbojiangthe values <code>val1</code>, ··· are passed 6237*572c4311Sfengbojiangas the results from the yield. 6238*572c4311Sfengbojiang 6239*572c4311Sfengbojiang 6240*572c4311Sfengbojiang<p> 6241*572c4311SfengbojiangIf the coroutine runs without any errors, 6242*572c4311Sfengbojiang<code>resume</code> returns <b>true</b> plus any values passed to <code>yield</code> 6243*572c4311Sfengbojiang(if the coroutine yields) or any values returned by the body function 6244*572c4311Sfengbojiang(if the coroutine terminates). 6245*572c4311SfengbojiangIf there is any error, 6246*572c4311Sfengbojiang<code>resume</code> returns <b>false</b> plus the error message. 6247*572c4311Sfengbojiang 6248*572c4311Sfengbojiang 6249*572c4311Sfengbojiang 6250*572c4311Sfengbojiang 6251*572c4311Sfengbojiang<p> 6252*572c4311Sfengbojiang<hr><h3><a name="pdf-coroutine.running"><code>coroutine.running ()</code></a></h3> 6253*572c4311Sfengbojiang 6254*572c4311Sfengbojiang 6255*572c4311Sfengbojiang<p> 6256*572c4311SfengbojiangReturns the running coroutine, 6257*572c4311Sfengbojiangor <b>nil</b> when called by the main thread. 6258*572c4311Sfengbojiang 6259*572c4311Sfengbojiang 6260*572c4311Sfengbojiang 6261*572c4311Sfengbojiang 6262*572c4311Sfengbojiang<p> 6263*572c4311Sfengbojiang<hr><h3><a name="pdf-coroutine.status"><code>coroutine.status (co)</code></a></h3> 6264*572c4311Sfengbojiang 6265*572c4311Sfengbojiang 6266*572c4311Sfengbojiang<p> 6267*572c4311SfengbojiangReturns the status of coroutine <code>co</code>, as a string: 6268*572c4311Sfengbojiang<code>"running"</code>, 6269*572c4311Sfengbojiangif the coroutine is running (that is, it called <code>status</code>); 6270*572c4311Sfengbojiang<code>"suspended"</code>, if the coroutine is suspended in a call to <code>yield</code>, 6271*572c4311Sfengbojiangor if it has not started running yet; 6272*572c4311Sfengbojiang<code>"normal"</code> if the coroutine is active but not running 6273*572c4311Sfengbojiang(that is, it has resumed another coroutine); 6274*572c4311Sfengbojiangand <code>"dead"</code> if the coroutine has finished its body function, 6275*572c4311Sfengbojiangor if it has stopped with an error. 6276*572c4311Sfengbojiang 6277*572c4311Sfengbojiang 6278*572c4311Sfengbojiang 6279*572c4311Sfengbojiang 6280*572c4311Sfengbojiang<p> 6281*572c4311Sfengbojiang<hr><h3><a name="pdf-coroutine.wrap"><code>coroutine.wrap (f)</code></a></h3> 6282*572c4311Sfengbojiang 6283*572c4311Sfengbojiang 6284*572c4311Sfengbojiang<p> 6285*572c4311SfengbojiangCreates a new coroutine, with body <code>f</code>. 6286*572c4311Sfengbojiang<code>f</code> must be a Lua function. 6287*572c4311SfengbojiangReturns a function that resumes the coroutine each time it is called. 6288*572c4311SfengbojiangAny arguments passed to the function behave as the 6289*572c4311Sfengbojiangextra arguments to <code>resume</code>. 6290*572c4311SfengbojiangReturns the same values returned by <code>resume</code>, 6291*572c4311Sfengbojiangexcept the first boolean. 6292*572c4311SfengbojiangIn case of error, propagates the error. 6293*572c4311Sfengbojiang 6294*572c4311Sfengbojiang 6295*572c4311Sfengbojiang 6296*572c4311Sfengbojiang 6297*572c4311Sfengbojiang<p> 6298*572c4311Sfengbojiang<hr><h3><a name="pdf-coroutine.yield"><code>coroutine.yield (···)</code></a></h3> 6299*572c4311Sfengbojiang 6300*572c4311Sfengbojiang 6301*572c4311Sfengbojiang<p> 6302*572c4311SfengbojiangSuspends the execution of the calling coroutine. 6303*572c4311SfengbojiangThe coroutine cannot be running a C function, 6304*572c4311Sfengbojianga metamethod, or an iterator. 6305*572c4311SfengbojiangAny arguments to <code>yield</code> are passed as extra results to <code>resume</code>. 6306*572c4311Sfengbojiang 6307*572c4311Sfengbojiang 6308*572c4311Sfengbojiang 6309*572c4311Sfengbojiang 6310*572c4311Sfengbojiang 6311*572c4311Sfengbojiang 6312*572c4311Sfengbojiang 6313*572c4311Sfengbojiang<h2>5.3 - <a name="5.3">Modules</a></h2> 6314*572c4311Sfengbojiang 6315*572c4311Sfengbojiang<p> 6316*572c4311SfengbojiangThe package library provides basic 6317*572c4311Sfengbojiangfacilities for loading and building modules in Lua. 6318*572c4311SfengbojiangIt exports two of its functions directly in the global environment: 6319*572c4311Sfengbojiang<a href="#pdf-require"><code>require</code></a> and <a href="#pdf-module"><code>module</code></a>. 6320*572c4311SfengbojiangEverything else is exported in a table <a name="pdf-package"><code>package</code></a>. 6321*572c4311Sfengbojiang 6322*572c4311Sfengbojiang 6323*572c4311Sfengbojiang<p> 6324*572c4311Sfengbojiang<hr><h3><a name="pdf-module"><code>module (name [, ···])</code></a></h3> 6325*572c4311Sfengbojiang 6326*572c4311Sfengbojiang 6327*572c4311Sfengbojiang<p> 6328*572c4311SfengbojiangCreates a module. 6329*572c4311SfengbojiangIf there is a table in <code>package.loaded[name]</code>, 6330*572c4311Sfengbojiangthis table is the module. 6331*572c4311SfengbojiangOtherwise, if there is a global table <code>t</code> with the given name, 6332*572c4311Sfengbojiangthis table is the module. 6333*572c4311SfengbojiangOtherwise creates a new table <code>t</code> and 6334*572c4311Sfengbojiangsets it as the value of the global <code>name</code> and 6335*572c4311Sfengbojiangthe value of <code>package.loaded[name]</code>. 6336*572c4311SfengbojiangThis function also initializes <code>t._NAME</code> with the given name, 6337*572c4311Sfengbojiang<code>t._M</code> with the module (<code>t</code> itself), 6338*572c4311Sfengbojiangand <code>t._PACKAGE</code> with the package name 6339*572c4311Sfengbojiang(the full module name minus last component; see below). 6340*572c4311SfengbojiangFinally, <code>module</code> sets <code>t</code> as the new environment 6341*572c4311Sfengbojiangof the current function and the new value of <code>package.loaded[name]</code>, 6342*572c4311Sfengbojiangso that <a href="#pdf-require"><code>require</code></a> returns <code>t</code>. 6343*572c4311Sfengbojiang 6344*572c4311Sfengbojiang 6345*572c4311Sfengbojiang<p> 6346*572c4311SfengbojiangIf <code>name</code> is a compound name 6347*572c4311Sfengbojiang(that is, one with components separated by dots), 6348*572c4311Sfengbojiang<code>module</code> creates (or reuses, if they already exist) 6349*572c4311Sfengbojiangtables for each component. 6350*572c4311SfengbojiangFor instance, if <code>name</code> is <code>a.b.c</code>, 6351*572c4311Sfengbojiangthen <code>module</code> stores the module table in field <code>c</code> of 6352*572c4311Sfengbojiangfield <code>b</code> of global <code>a</code>. 6353*572c4311Sfengbojiang 6354*572c4311Sfengbojiang 6355*572c4311Sfengbojiang<p> 6356*572c4311SfengbojiangThis function can receive optional <em>options</em> after 6357*572c4311Sfengbojiangthe module name, 6358*572c4311Sfengbojiangwhere each option is a function to be applied over the module. 6359*572c4311Sfengbojiang 6360*572c4311Sfengbojiang 6361*572c4311Sfengbojiang 6362*572c4311Sfengbojiang 6363*572c4311Sfengbojiang<p> 6364*572c4311Sfengbojiang<hr><h3><a name="pdf-require"><code>require (modname)</code></a></h3> 6365*572c4311Sfengbojiang 6366*572c4311Sfengbojiang 6367*572c4311Sfengbojiang<p> 6368*572c4311SfengbojiangLoads the given module. 6369*572c4311SfengbojiangThe function starts by looking into the <a href="#pdf-package.loaded"><code>package.loaded</code></a> table 6370*572c4311Sfengbojiangto determine whether <code>modname</code> is already loaded. 6371*572c4311SfengbojiangIf it is, then <code>require</code> returns the value stored 6372*572c4311Sfengbojiangat <code>package.loaded[modname]</code>. 6373*572c4311SfengbojiangOtherwise, it tries to find a <em>loader</em> for the module. 6374*572c4311Sfengbojiang 6375*572c4311Sfengbojiang 6376*572c4311Sfengbojiang<p> 6377*572c4311SfengbojiangTo find a loader, 6378*572c4311Sfengbojiang<code>require</code> is guided by the <a href="#pdf-package.loaders"><code>package.loaders</code></a> array. 6379*572c4311SfengbojiangBy changing this array, 6380*572c4311Sfengbojiangwe can change how <code>require</code> looks for a module. 6381*572c4311SfengbojiangThe following explanation is based on the default configuration 6382*572c4311Sfengbojiangfor <a href="#pdf-package.loaders"><code>package.loaders</code></a>. 6383*572c4311Sfengbojiang 6384*572c4311Sfengbojiang 6385*572c4311Sfengbojiang<p> 6386*572c4311SfengbojiangFirst <code>require</code> queries <code>package.preload[modname]</code>. 6387*572c4311SfengbojiangIf it has a value, 6388*572c4311Sfengbojiangthis value (which should be a function) is the loader. 6389*572c4311SfengbojiangOtherwise <code>require</code> searches for a Lua loader using the 6390*572c4311Sfengbojiangpath stored in <a href="#pdf-package.path"><code>package.path</code></a>. 6391*572c4311SfengbojiangIf that also fails, it searches for a C loader using the 6392*572c4311Sfengbojiangpath stored in <a href="#pdf-package.cpath"><code>package.cpath</code></a>. 6393*572c4311SfengbojiangIf that also fails, 6394*572c4311Sfengbojiangit tries an <em>all-in-one</em> loader (see <a href="#pdf-package.loaders"><code>package.loaders</code></a>). 6395*572c4311Sfengbojiang 6396*572c4311Sfengbojiang 6397*572c4311Sfengbojiang<p> 6398*572c4311SfengbojiangOnce a loader is found, 6399*572c4311Sfengbojiang<code>require</code> calls the loader with a single argument, <code>modname</code>. 6400*572c4311SfengbojiangIf the loader returns any value, 6401*572c4311Sfengbojiang<code>require</code> assigns the returned value to <code>package.loaded[modname]</code>. 6402*572c4311SfengbojiangIf the loader returns no value and 6403*572c4311Sfengbojianghas not assigned any value to <code>package.loaded[modname]</code>, 6404*572c4311Sfengbojiangthen <code>require</code> assigns <b>true</b> to this entry. 6405*572c4311SfengbojiangIn any case, <code>require</code> returns the 6406*572c4311Sfengbojiangfinal value of <code>package.loaded[modname]</code>. 6407*572c4311Sfengbojiang 6408*572c4311Sfengbojiang 6409*572c4311Sfengbojiang<p> 6410*572c4311SfengbojiangIf there is any error loading or running the module, 6411*572c4311Sfengbojiangor if it cannot find any loader for the module, 6412*572c4311Sfengbojiangthen <code>require</code> signals an error. 6413*572c4311Sfengbojiang 6414*572c4311Sfengbojiang 6415*572c4311Sfengbojiang 6416*572c4311Sfengbojiang 6417*572c4311Sfengbojiang<p> 6418*572c4311Sfengbojiang<hr><h3><a name="pdf-package.cpath"><code>package.cpath</code></a></h3> 6419*572c4311Sfengbojiang 6420*572c4311Sfengbojiang 6421*572c4311Sfengbojiang<p> 6422*572c4311SfengbojiangThe path used by <a href="#pdf-require"><code>require</code></a> to search for a C loader. 6423*572c4311Sfengbojiang 6424*572c4311Sfengbojiang 6425*572c4311Sfengbojiang<p> 6426*572c4311SfengbojiangLua initializes the C path <a href="#pdf-package.cpath"><code>package.cpath</code></a> in the same way 6427*572c4311Sfengbojiangit initializes the Lua path <a href="#pdf-package.path"><code>package.path</code></a>, 6428*572c4311Sfengbojiangusing the environment variable <a name="pdf-LUA_CPATH"><code>LUA_CPATH</code></a> 6429*572c4311Sfengbojiangor a default path defined in <code>luaconf.h</code>. 6430*572c4311Sfengbojiang 6431*572c4311Sfengbojiang 6432*572c4311Sfengbojiang 6433*572c4311Sfengbojiang 6434*572c4311Sfengbojiang<p> 6435*572c4311Sfengbojiang 6436*572c4311Sfengbojiang<hr><h3><a name="pdf-package.loaded"><code>package.loaded</code></a></h3> 6437*572c4311Sfengbojiang 6438*572c4311Sfengbojiang 6439*572c4311Sfengbojiang<p> 6440*572c4311SfengbojiangA table used by <a href="#pdf-require"><code>require</code></a> to control which 6441*572c4311Sfengbojiangmodules are already loaded. 6442*572c4311SfengbojiangWhen you require a module <code>modname</code> and 6443*572c4311Sfengbojiang<code>package.loaded[modname]</code> is not false, 6444*572c4311Sfengbojiang<a href="#pdf-require"><code>require</code></a> simply returns the value stored there. 6445*572c4311Sfengbojiang 6446*572c4311Sfengbojiang 6447*572c4311Sfengbojiang 6448*572c4311Sfengbojiang 6449*572c4311Sfengbojiang<p> 6450*572c4311Sfengbojiang<hr><h3><a name="pdf-package.loaders"><code>package.loaders</code></a></h3> 6451*572c4311Sfengbojiang 6452*572c4311Sfengbojiang 6453*572c4311Sfengbojiang<p> 6454*572c4311SfengbojiangA table used by <a href="#pdf-require"><code>require</code></a> to control how to load modules. 6455*572c4311Sfengbojiang 6456*572c4311Sfengbojiang 6457*572c4311Sfengbojiang<p> 6458*572c4311SfengbojiangEach entry in this table is a <em>searcher function</em>. 6459*572c4311SfengbojiangWhen looking for a module, 6460*572c4311Sfengbojiang<a href="#pdf-require"><code>require</code></a> calls each of these searchers in ascending order, 6461*572c4311Sfengbojiangwith the module name (the argument given to <a href="#pdf-require"><code>require</code></a>) as its 6462*572c4311Sfengbojiangsole parameter. 6463*572c4311SfengbojiangThe function can return another function (the module <em>loader</em>) 6464*572c4311Sfengbojiangor a string explaining why it did not find that module 6465*572c4311Sfengbojiang(or <b>nil</b> if it has nothing to say). 6466*572c4311SfengbojiangLua initializes this table with four functions. 6467*572c4311Sfengbojiang 6468*572c4311Sfengbojiang 6469*572c4311Sfengbojiang<p> 6470*572c4311SfengbojiangThe first searcher simply looks for a loader in the 6471*572c4311Sfengbojiang<a href="#pdf-package.preload"><code>package.preload</code></a> table. 6472*572c4311Sfengbojiang 6473*572c4311Sfengbojiang 6474*572c4311Sfengbojiang<p> 6475*572c4311SfengbojiangThe second searcher looks for a loader as a Lua library, 6476*572c4311Sfengbojiangusing the path stored at <a href="#pdf-package.path"><code>package.path</code></a>. 6477*572c4311SfengbojiangA path is a sequence of <em>templates</em> separated by semicolons. 6478*572c4311SfengbojiangFor each template, 6479*572c4311Sfengbojiangthe searcher will change each interrogation 6480*572c4311Sfengbojiangmark in the template by <code>filename</code>, 6481*572c4311Sfengbojiangwhich is the module name with each dot replaced by a 6482*572c4311Sfengbojiang"directory separator" (such as "<code>/</code>" in Unix); 6483*572c4311Sfengbojiangthen it will try to open the resulting file name. 6484*572c4311SfengbojiangSo, for instance, if the Lua path is the string 6485*572c4311Sfengbojiang 6486*572c4311Sfengbojiang<pre> 6487*572c4311Sfengbojiang "./?.lua;./?.lc;/usr/local/?/init.lua" 6488*572c4311Sfengbojiang</pre><p> 6489*572c4311Sfengbojiangthe search for a Lua file for module <code>foo</code> 6490*572c4311Sfengbojiangwill try to open the files 6491*572c4311Sfengbojiang<code>./foo.lua</code>, <code>./foo.lc</code>, and 6492*572c4311Sfengbojiang<code>/usr/local/foo/init.lua</code>, in that order. 6493*572c4311Sfengbojiang 6494*572c4311Sfengbojiang 6495*572c4311Sfengbojiang<p> 6496*572c4311SfengbojiangThe third searcher looks for a loader as a C library, 6497*572c4311Sfengbojiangusing the path given by the variable <a href="#pdf-package.cpath"><code>package.cpath</code></a>. 6498*572c4311SfengbojiangFor instance, 6499*572c4311Sfengbojiangif the C path is the string 6500*572c4311Sfengbojiang 6501*572c4311Sfengbojiang<pre> 6502*572c4311Sfengbojiang "./?.so;./?.dll;/usr/local/?/init.so" 6503*572c4311Sfengbojiang</pre><p> 6504*572c4311Sfengbojiangthe searcher for module <code>foo</code> 6505*572c4311Sfengbojiangwill try to open the files <code>./foo.so</code>, <code>./foo.dll</code>, 6506*572c4311Sfengbojiangand <code>/usr/local/foo/init.so</code>, in that order. 6507*572c4311SfengbojiangOnce it finds a C library, 6508*572c4311Sfengbojiangthis searcher first uses a dynamic link facility to link the 6509*572c4311Sfengbojiangapplication with the library. 6510*572c4311SfengbojiangThen it tries to find a C function inside the library to 6511*572c4311Sfengbojiangbe used as the loader. 6512*572c4311SfengbojiangThe name of this C function is the string "<code>luaopen_</code>" 6513*572c4311Sfengbojiangconcatenated with a copy of the module name where each dot 6514*572c4311Sfengbojiangis replaced by an underscore. 6515*572c4311SfengbojiangMoreover, if the module name has a hyphen, 6516*572c4311Sfengbojiangits prefix up to (and including) the first hyphen is removed. 6517*572c4311SfengbojiangFor instance, if the module name is <code>a.v1-b.c</code>, 6518*572c4311Sfengbojiangthe function name will be <code>luaopen_b_c</code>. 6519*572c4311Sfengbojiang 6520*572c4311Sfengbojiang 6521*572c4311Sfengbojiang<p> 6522*572c4311SfengbojiangThe fourth searcher tries an <em>all-in-one loader</em>. 6523*572c4311SfengbojiangIt searches the C path for a library for 6524*572c4311Sfengbojiangthe root name of the given module. 6525*572c4311SfengbojiangFor instance, when requiring <code>a.b.c</code>, 6526*572c4311Sfengbojiangit will search for a C library for <code>a</code>. 6527*572c4311SfengbojiangIf found, it looks into it for an open function for 6528*572c4311Sfengbojiangthe submodule; 6529*572c4311Sfengbojiangin our example, that would be <code>luaopen_a_b_c</code>. 6530*572c4311SfengbojiangWith this facility, a package can pack several C submodules 6531*572c4311Sfengbojianginto one single library, 6532*572c4311Sfengbojiangwith each submodule keeping its original open function. 6533*572c4311Sfengbojiang 6534*572c4311Sfengbojiang 6535*572c4311Sfengbojiang 6536*572c4311Sfengbojiang 6537*572c4311Sfengbojiang<p> 6538*572c4311Sfengbojiang<hr><h3><a name="pdf-package.loadlib"><code>package.loadlib (libname, funcname)</code></a></h3> 6539*572c4311Sfengbojiang 6540*572c4311Sfengbojiang 6541*572c4311Sfengbojiang<p> 6542*572c4311SfengbojiangDynamically links the host program with the C library <code>libname</code>. 6543*572c4311SfengbojiangInside this library, looks for a function <code>funcname</code> 6544*572c4311Sfengbojiangand returns this function as a C function. 6545*572c4311Sfengbojiang(So, <code>funcname</code> must follow the protocol (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>)). 6546*572c4311Sfengbojiang 6547*572c4311Sfengbojiang 6548*572c4311Sfengbojiang<p> 6549*572c4311SfengbojiangThis is a low-level function. 6550*572c4311SfengbojiangIt completely bypasses the package and module system. 6551*572c4311SfengbojiangUnlike <a href="#pdf-require"><code>require</code></a>, 6552*572c4311Sfengbojiangit does not perform any path searching and 6553*572c4311Sfengbojiangdoes not automatically adds extensions. 6554*572c4311Sfengbojiang<code>libname</code> must be the complete file name of the C library, 6555*572c4311Sfengbojiangincluding if necessary a path and extension. 6556*572c4311Sfengbojiang<code>funcname</code> must be the exact name exported by the C library 6557*572c4311Sfengbojiang(which may depend on the C compiler and linker used). 6558*572c4311Sfengbojiang 6559*572c4311Sfengbojiang 6560*572c4311Sfengbojiang<p> 6561*572c4311SfengbojiangThis function is not supported by ANSI C. 6562*572c4311SfengbojiangAs such, it is only available on some platforms 6563*572c4311Sfengbojiang(Windows, Linux, Mac OS X, Solaris, BSD, 6564*572c4311Sfengbojiangplus other Unix systems that support the <code>dlfcn</code> standard). 6565*572c4311Sfengbojiang 6566*572c4311Sfengbojiang 6567*572c4311Sfengbojiang 6568*572c4311Sfengbojiang 6569*572c4311Sfengbojiang<p> 6570*572c4311Sfengbojiang<hr><h3><a name="pdf-package.path"><code>package.path</code></a></h3> 6571*572c4311Sfengbojiang 6572*572c4311Sfengbojiang 6573*572c4311Sfengbojiang<p> 6574*572c4311SfengbojiangThe path used by <a href="#pdf-require"><code>require</code></a> to search for a Lua loader. 6575*572c4311Sfengbojiang 6576*572c4311Sfengbojiang 6577*572c4311Sfengbojiang<p> 6578*572c4311SfengbojiangAt start-up, Lua initializes this variable with 6579*572c4311Sfengbojiangthe value of the environment variable <a name="pdf-LUA_PATH"><code>LUA_PATH</code></a> or 6580*572c4311Sfengbojiangwith a default path defined in <code>luaconf.h</code>, 6581*572c4311Sfengbojiangif the environment variable is not defined. 6582*572c4311SfengbojiangAny "<code>;;</code>" in the value of the environment variable 6583*572c4311Sfengbojiangis replaced by the default path. 6584*572c4311Sfengbojiang 6585*572c4311Sfengbojiang 6586*572c4311Sfengbojiang 6587*572c4311Sfengbojiang 6588*572c4311Sfengbojiang<p> 6589*572c4311Sfengbojiang<hr><h3><a name="pdf-package.preload"><code>package.preload</code></a></h3> 6590*572c4311Sfengbojiang 6591*572c4311Sfengbojiang 6592*572c4311Sfengbojiang<p> 6593*572c4311SfengbojiangA table to store loaders for specific modules 6594*572c4311Sfengbojiang(see <a href="#pdf-require"><code>require</code></a>). 6595*572c4311Sfengbojiang 6596*572c4311Sfengbojiang 6597*572c4311Sfengbojiang 6598*572c4311Sfengbojiang 6599*572c4311Sfengbojiang<p> 6600*572c4311Sfengbojiang<hr><h3><a name="pdf-package.seeall"><code>package.seeall (module)</code></a></h3> 6601*572c4311Sfengbojiang 6602*572c4311Sfengbojiang 6603*572c4311Sfengbojiang<p> 6604*572c4311SfengbojiangSets a metatable for <code>module</code> with 6605*572c4311Sfengbojiangits <code>__index</code> field referring to the global environment, 6606*572c4311Sfengbojiangso that this module inherits values 6607*572c4311Sfengbojiangfrom the global environment. 6608*572c4311SfengbojiangTo be used as an option to function <a href="#pdf-module"><code>module</code></a>. 6609*572c4311Sfengbojiang 6610*572c4311Sfengbojiang 6611*572c4311Sfengbojiang 6612*572c4311Sfengbojiang 6613*572c4311Sfengbojiang 6614*572c4311Sfengbojiang 6615*572c4311Sfengbojiang 6616*572c4311Sfengbojiang<h2>5.4 - <a name="5.4">String Manipulation</a></h2> 6617*572c4311Sfengbojiang 6618*572c4311Sfengbojiang<p> 6619*572c4311SfengbojiangThis library provides generic functions for string manipulation, 6620*572c4311Sfengbojiangsuch as finding and extracting substrings, and pattern matching. 6621*572c4311SfengbojiangWhen indexing a string in Lua, the first character is at position 1 6622*572c4311Sfengbojiang(not at 0, as in C). 6623*572c4311SfengbojiangIndices are allowed to be negative and are interpreted as indexing backwards, 6624*572c4311Sfengbojiangfrom the end of the string. 6625*572c4311SfengbojiangThus, the last character is at position -1, and so on. 6626*572c4311Sfengbojiang 6627*572c4311Sfengbojiang 6628*572c4311Sfengbojiang<p> 6629*572c4311SfengbojiangThe string library provides all its functions inside the table 6630*572c4311Sfengbojiang<a name="pdf-string"><code>string</code></a>. 6631*572c4311SfengbojiangIt also sets a metatable for strings 6632*572c4311Sfengbojiangwhere the <code>__index</code> field points to the <code>string</code> table. 6633*572c4311SfengbojiangTherefore, you can use the string functions in object-oriented style. 6634*572c4311SfengbojiangFor instance, <code>string.byte(s, i)</code> 6635*572c4311Sfengbojiangcan be written as <code>s:byte(i)</code>. 6636*572c4311Sfengbojiang 6637*572c4311Sfengbojiang 6638*572c4311Sfengbojiang<p> 6639*572c4311SfengbojiangThe string library assumes one-byte character encodings. 6640*572c4311Sfengbojiang 6641*572c4311Sfengbojiang 6642*572c4311Sfengbojiang<p> 6643*572c4311Sfengbojiang<hr><h3><a name="pdf-string.byte"><code>string.byte (s [, i [, j]])</code></a></h3> 6644*572c4311SfengbojiangReturns the internal numerical codes of the characters <code>s[i]</code>, 6645*572c4311Sfengbojiang<code>s[i+1]</code>, ···, <code>s[j]</code>. 6646*572c4311SfengbojiangThe default value for <code>i</code> is 1; 6647*572c4311Sfengbojiangthe default value for <code>j</code> is <code>i</code>. 6648*572c4311Sfengbojiang 6649*572c4311Sfengbojiang 6650*572c4311Sfengbojiang<p> 6651*572c4311SfengbojiangNote that numerical codes are not necessarily portable across platforms. 6652*572c4311Sfengbojiang 6653*572c4311Sfengbojiang 6654*572c4311Sfengbojiang 6655*572c4311Sfengbojiang 6656*572c4311Sfengbojiang<p> 6657*572c4311Sfengbojiang<hr><h3><a name="pdf-string.char"><code>string.char (···)</code></a></h3> 6658*572c4311SfengbojiangReceives zero or more integers. 6659*572c4311SfengbojiangReturns a string with length equal to the number of arguments, 6660*572c4311Sfengbojiangin which each character has the internal numerical code equal 6661*572c4311Sfengbojiangto its corresponding argument. 6662*572c4311Sfengbojiang 6663*572c4311Sfengbojiang 6664*572c4311Sfengbojiang<p> 6665*572c4311SfengbojiangNote that numerical codes are not necessarily portable across platforms. 6666*572c4311Sfengbojiang 6667*572c4311Sfengbojiang 6668*572c4311Sfengbojiang 6669*572c4311Sfengbojiang 6670*572c4311Sfengbojiang<p> 6671*572c4311Sfengbojiang<hr><h3><a name="pdf-string.dump"><code>string.dump (function)</code></a></h3> 6672*572c4311Sfengbojiang 6673*572c4311Sfengbojiang 6674*572c4311Sfengbojiang<p> 6675*572c4311SfengbojiangReturns a string containing a binary representation of the given function, 6676*572c4311Sfengbojiangso that a later <a href="#pdf-loadstring"><code>loadstring</code></a> on this string returns 6677*572c4311Sfengbojianga copy of the function. 6678*572c4311Sfengbojiang<code>function</code> must be a Lua function without upvalues. 6679*572c4311Sfengbojiang 6680*572c4311Sfengbojiang 6681*572c4311Sfengbojiang 6682*572c4311Sfengbojiang 6683*572c4311Sfengbojiang<p> 6684*572c4311Sfengbojiang<hr><h3><a name="pdf-string.find"><code>string.find (s, pattern [, init [, plain]])</code></a></h3> 6685*572c4311SfengbojiangLooks for the first match of 6686*572c4311Sfengbojiang<code>pattern</code> in the string <code>s</code>. 6687*572c4311SfengbojiangIf it finds a match, then <code>find</code> returns the indices of <code>s</code> 6688*572c4311Sfengbojiangwhere this occurrence starts and ends; 6689*572c4311Sfengbojiangotherwise, it returns <b>nil</b>. 6690*572c4311SfengbojiangA third, optional numerical argument <code>init</code> specifies 6691*572c4311Sfengbojiangwhere to start the search; 6692*572c4311Sfengbojiangits default value is 1 and can be negative. 6693*572c4311SfengbojiangA value of <b>true</b> as a fourth, optional argument <code>plain</code> 6694*572c4311Sfengbojiangturns off the pattern matching facilities, 6695*572c4311Sfengbojiangso the function does a plain "find substring" operation, 6696*572c4311Sfengbojiangwith no characters in <code>pattern</code> being considered "magic". 6697*572c4311SfengbojiangNote that if <code>plain</code> is given, then <code>init</code> must be given as well. 6698*572c4311Sfengbojiang 6699*572c4311Sfengbojiang 6700*572c4311Sfengbojiang<p> 6701*572c4311SfengbojiangIf the pattern has captures, 6702*572c4311Sfengbojiangthen in a successful match 6703*572c4311Sfengbojiangthe captured values are also returned, 6704*572c4311Sfengbojiangafter the two indices. 6705*572c4311Sfengbojiang 6706*572c4311Sfengbojiang 6707*572c4311Sfengbojiang 6708*572c4311Sfengbojiang 6709*572c4311Sfengbojiang<p> 6710*572c4311Sfengbojiang<hr><h3><a name="pdf-string.format"><code>string.format (formatstring, ···)</code></a></h3> 6711*572c4311SfengbojiangReturns a formatted version of its variable number of arguments 6712*572c4311Sfengbojiangfollowing the description given in its first argument (which must be a string). 6713*572c4311SfengbojiangThe format string follows the same rules as the <code>printf</code> family of 6714*572c4311Sfengbojiangstandard C functions. 6715*572c4311SfengbojiangThe only differences are that the options/modifiers 6716*572c4311Sfengbojiang<code>*</code>, <code>l</code>, <code>L</code>, <code>n</code>, <code>p</code>, 6717*572c4311Sfengbojiangand <code>h</code> are not supported 6718*572c4311Sfengbojiangand that there is an extra option, <code>q</code>. 6719*572c4311SfengbojiangThe <code>q</code> option formats a string in a form suitable to be safely read 6720*572c4311Sfengbojiangback by the Lua interpreter: 6721*572c4311Sfengbojiangthe string is written between double quotes, 6722*572c4311Sfengbojiangand all double quotes, newlines, embedded zeros, 6723*572c4311Sfengbojiangand backslashes in the string 6724*572c4311Sfengbojiangare correctly escaped when written. 6725*572c4311SfengbojiangFor instance, the call 6726*572c4311Sfengbojiang 6727*572c4311Sfengbojiang<pre> 6728*572c4311Sfengbojiang string.format('%q', 'a string with "quotes" and \n new line') 6729*572c4311Sfengbojiang</pre><p> 6730*572c4311Sfengbojiangwill produce the string: 6731*572c4311Sfengbojiang 6732*572c4311Sfengbojiang<pre> 6733*572c4311Sfengbojiang "a string with \"quotes\" and \ 6734*572c4311Sfengbojiang new line" 6735*572c4311Sfengbojiang</pre> 6736*572c4311Sfengbojiang 6737*572c4311Sfengbojiang<p> 6738*572c4311SfengbojiangThe options <code>c</code>, <code>d</code>, <code>E</code>, <code>e</code>, <code>f</code>, 6739*572c4311Sfengbojiang<code>g</code>, <code>G</code>, <code>i</code>, <code>o</code>, <code>u</code>, <code>X</code>, and <code>x</code> all 6740*572c4311Sfengbojiangexpect a number as argument, 6741*572c4311Sfengbojiangwhereas <code>q</code> and <code>s</code> expect a string. 6742*572c4311Sfengbojiang 6743*572c4311Sfengbojiang 6744*572c4311Sfengbojiang<p> 6745*572c4311SfengbojiangThis function does not accept string values 6746*572c4311Sfengbojiangcontaining embedded zeros, 6747*572c4311Sfengbojiangexcept as arguments to the <code>q</code> option. 6748*572c4311Sfengbojiang 6749*572c4311Sfengbojiang 6750*572c4311Sfengbojiang 6751*572c4311Sfengbojiang 6752*572c4311Sfengbojiang<p> 6753*572c4311Sfengbojiang<hr><h3><a name="pdf-string.gmatch"><code>string.gmatch (s, pattern)</code></a></h3> 6754*572c4311SfengbojiangReturns an iterator function that, 6755*572c4311Sfengbojiangeach time it is called, 6756*572c4311Sfengbojiangreturns the next captures from <code>pattern</code> over string <code>s</code>. 6757*572c4311SfengbojiangIf <code>pattern</code> specifies no captures, 6758*572c4311Sfengbojiangthen the whole match is produced in each call. 6759*572c4311Sfengbojiang 6760*572c4311Sfengbojiang 6761*572c4311Sfengbojiang<p> 6762*572c4311SfengbojiangAs an example, the following loop 6763*572c4311Sfengbojiang 6764*572c4311Sfengbojiang<pre> 6765*572c4311Sfengbojiang s = "hello world from Lua" 6766*572c4311Sfengbojiang for w in string.gmatch(s, "%a+") do 6767*572c4311Sfengbojiang print(w) 6768*572c4311Sfengbojiang end 6769*572c4311Sfengbojiang</pre><p> 6770*572c4311Sfengbojiangwill iterate over all the words from string <code>s</code>, 6771*572c4311Sfengbojiangprinting one per line. 6772*572c4311SfengbojiangThe next example collects all pairs <code>key=value</code> from the 6773*572c4311Sfengbojianggiven string into a table: 6774*572c4311Sfengbojiang 6775*572c4311Sfengbojiang<pre> 6776*572c4311Sfengbojiang t = {} 6777*572c4311Sfengbojiang s = "from=world, to=Lua" 6778*572c4311Sfengbojiang for k, v in string.gmatch(s, "(%w+)=(%w+)") do 6779*572c4311Sfengbojiang t[k] = v 6780*572c4311Sfengbojiang end 6781*572c4311Sfengbojiang</pre> 6782*572c4311Sfengbojiang 6783*572c4311Sfengbojiang<p> 6784*572c4311SfengbojiangFor this function, a '<code>^</code>' at the start of a pattern does not 6785*572c4311Sfengbojiangwork as an anchor, as this would prevent the iteration. 6786*572c4311Sfengbojiang 6787*572c4311Sfengbojiang 6788*572c4311Sfengbojiang 6789*572c4311Sfengbojiang 6790*572c4311Sfengbojiang<p> 6791*572c4311Sfengbojiang<hr><h3><a name="pdf-string.gsub"><code>string.gsub (s, pattern, repl [, n])</code></a></h3> 6792*572c4311SfengbojiangReturns a copy of <code>s</code> 6793*572c4311Sfengbojiangin which all (or the first <code>n</code>, if given) 6794*572c4311Sfengbojiangoccurrences of the <code>pattern</code> have been 6795*572c4311Sfengbojiangreplaced by a replacement string specified by <code>repl</code>, 6796*572c4311Sfengbojiangwhich can be a string, a table, or a function. 6797*572c4311Sfengbojiang<code>gsub</code> also returns, as its second value, 6798*572c4311Sfengbojiangthe total number of matches that occurred. 6799*572c4311Sfengbojiang 6800*572c4311Sfengbojiang 6801*572c4311Sfengbojiang<p> 6802*572c4311SfengbojiangIf <code>repl</code> is a string, then its value is used for replacement. 6803*572c4311SfengbojiangThe character <code>%</code> works as an escape character: 6804*572c4311Sfengbojiangany sequence in <code>repl</code> of the form <code>%<em>n</em></code>, 6805*572c4311Sfengbojiangwith <em>n</em> between 1 and 9, 6806*572c4311Sfengbojiangstands for the value of the <em>n</em>-th captured substring (see below). 6807*572c4311SfengbojiangThe sequence <code>%0</code> stands for the whole match. 6808*572c4311SfengbojiangThe sequence <code>%%</code> stands for a single <code>%</code>. 6809*572c4311Sfengbojiang 6810*572c4311Sfengbojiang 6811*572c4311Sfengbojiang<p> 6812*572c4311SfengbojiangIf <code>repl</code> is a table, then the table is queried for every match, 6813*572c4311Sfengbojiangusing the first capture as the key; 6814*572c4311Sfengbojiangif the pattern specifies no captures, 6815*572c4311Sfengbojiangthen the whole match is used as the key. 6816*572c4311Sfengbojiang 6817*572c4311Sfengbojiang 6818*572c4311Sfengbojiang<p> 6819*572c4311SfengbojiangIf <code>repl</code> is a function, then this function is called every time a 6820*572c4311Sfengbojiangmatch occurs, with all captured substrings passed as arguments, 6821*572c4311Sfengbojiangin order; 6822*572c4311Sfengbojiangif the pattern specifies no captures, 6823*572c4311Sfengbojiangthen the whole match is passed as a sole argument. 6824*572c4311Sfengbojiang 6825*572c4311Sfengbojiang 6826*572c4311Sfengbojiang<p> 6827*572c4311SfengbojiangIf the value returned by the table query or by the function call 6828*572c4311Sfengbojiangis a string or a number, 6829*572c4311Sfengbojiangthen it is used as the replacement string; 6830*572c4311Sfengbojiangotherwise, if it is <b>false</b> or <b>nil</b>, 6831*572c4311Sfengbojiangthen there is no replacement 6832*572c4311Sfengbojiang(that is, the original match is kept in the string). 6833*572c4311Sfengbojiang 6834*572c4311Sfengbojiang 6835*572c4311Sfengbojiang<p> 6836*572c4311SfengbojiangHere are some examples: 6837*572c4311Sfengbojiang 6838*572c4311Sfengbojiang<pre> 6839*572c4311Sfengbojiang x = string.gsub("hello world", "(%w+)", "%1 %1") 6840*572c4311Sfengbojiang --> x="hello hello world world" 6841*572c4311Sfengbojiang 6842*572c4311Sfengbojiang x = string.gsub("hello world", "%w+", "%0 %0", 1) 6843*572c4311Sfengbojiang --> x="hello hello world" 6844*572c4311Sfengbojiang 6845*572c4311Sfengbojiang x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1") 6846*572c4311Sfengbojiang --> x="world hello Lua from" 6847*572c4311Sfengbojiang 6848*572c4311Sfengbojiang x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv) 6849*572c4311Sfengbojiang --> x="home = /home/roberto, user = roberto" 6850*572c4311Sfengbojiang 6851*572c4311Sfengbojiang x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s) 6852*572c4311Sfengbojiang return loadstring(s)() 6853*572c4311Sfengbojiang end) 6854*572c4311Sfengbojiang --> x="4+5 = 9" 6855*572c4311Sfengbojiang 6856*572c4311Sfengbojiang local t = {name="lua", version="5.1"} 6857*572c4311Sfengbojiang x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t) 6858*572c4311Sfengbojiang --> x="lua-5.1.tar.gz" 6859*572c4311Sfengbojiang</pre> 6860*572c4311Sfengbojiang 6861*572c4311Sfengbojiang 6862*572c4311Sfengbojiang 6863*572c4311Sfengbojiang<p> 6864*572c4311Sfengbojiang<hr><h3><a name="pdf-string.len"><code>string.len (s)</code></a></h3> 6865*572c4311SfengbojiangReceives a string and returns its length. 6866*572c4311SfengbojiangThe empty string <code>""</code> has length 0. 6867*572c4311SfengbojiangEmbedded zeros are counted, 6868*572c4311Sfengbojiangso <code>"a\000bc\000"</code> has length 5. 6869*572c4311Sfengbojiang 6870*572c4311Sfengbojiang 6871*572c4311Sfengbojiang 6872*572c4311Sfengbojiang 6873*572c4311Sfengbojiang<p> 6874*572c4311Sfengbojiang<hr><h3><a name="pdf-string.lower"><code>string.lower (s)</code></a></h3> 6875*572c4311SfengbojiangReceives a string and returns a copy of this string with all 6876*572c4311Sfengbojianguppercase letters changed to lowercase. 6877*572c4311SfengbojiangAll other characters are left unchanged. 6878*572c4311SfengbojiangThe definition of what an uppercase letter is depends on the current locale. 6879*572c4311Sfengbojiang 6880*572c4311Sfengbojiang 6881*572c4311Sfengbojiang 6882*572c4311Sfengbojiang 6883*572c4311Sfengbojiang<p> 6884*572c4311Sfengbojiang<hr><h3><a name="pdf-string.match"><code>string.match (s, pattern [, init])</code></a></h3> 6885*572c4311SfengbojiangLooks for the first <em>match</em> of 6886*572c4311Sfengbojiang<code>pattern</code> in the string <code>s</code>. 6887*572c4311SfengbojiangIf it finds one, then <code>match</code> returns 6888*572c4311Sfengbojiangthe captures from the pattern; 6889*572c4311Sfengbojiangotherwise it returns <b>nil</b>. 6890*572c4311SfengbojiangIf <code>pattern</code> specifies no captures, 6891*572c4311Sfengbojiangthen the whole match is returned. 6892*572c4311SfengbojiangA third, optional numerical argument <code>init</code> specifies 6893*572c4311Sfengbojiangwhere to start the search; 6894*572c4311Sfengbojiangits default value is 1 and can be negative. 6895*572c4311Sfengbojiang 6896*572c4311Sfengbojiang 6897*572c4311Sfengbojiang 6898*572c4311Sfengbojiang 6899*572c4311Sfengbojiang<p> 6900*572c4311Sfengbojiang<hr><h3><a name="pdf-string.rep"><code>string.rep (s, n)</code></a></h3> 6901*572c4311SfengbojiangReturns a string that is the concatenation of <code>n</code> copies of 6902*572c4311Sfengbojiangthe string <code>s</code>. 6903*572c4311Sfengbojiang 6904*572c4311Sfengbojiang 6905*572c4311Sfengbojiang 6906*572c4311Sfengbojiang 6907*572c4311Sfengbojiang<p> 6908*572c4311Sfengbojiang<hr><h3><a name="pdf-string.reverse"><code>string.reverse (s)</code></a></h3> 6909*572c4311SfengbojiangReturns a string that is the string <code>s</code> reversed. 6910*572c4311Sfengbojiang 6911*572c4311Sfengbojiang 6912*572c4311Sfengbojiang 6913*572c4311Sfengbojiang 6914*572c4311Sfengbojiang<p> 6915*572c4311Sfengbojiang<hr><h3><a name="pdf-string.sub"><code>string.sub (s, i [, j])</code></a></h3> 6916*572c4311SfengbojiangReturns the substring of <code>s</code> that 6917*572c4311Sfengbojiangstarts at <code>i</code> and continues until <code>j</code>; 6918*572c4311Sfengbojiang<code>i</code> and <code>j</code> can be negative. 6919*572c4311SfengbojiangIf <code>j</code> is absent, then it is assumed to be equal to -1 6920*572c4311Sfengbojiang(which is the same as the string length). 6921*572c4311SfengbojiangIn particular, 6922*572c4311Sfengbojiangthe call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code> 6923*572c4311Sfengbojiangwith length <code>j</code>, 6924*572c4311Sfengbojiangand <code>string.sub(s, -i)</code> returns a suffix of <code>s</code> 6925*572c4311Sfengbojiangwith length <code>i</code>. 6926*572c4311Sfengbojiang 6927*572c4311Sfengbojiang 6928*572c4311Sfengbojiang 6929*572c4311Sfengbojiang 6930*572c4311Sfengbojiang<p> 6931*572c4311Sfengbojiang<hr><h3><a name="pdf-string.upper"><code>string.upper (s)</code></a></h3> 6932*572c4311SfengbojiangReceives a string and returns a copy of this string with all 6933*572c4311Sfengbojianglowercase letters changed to uppercase. 6934*572c4311SfengbojiangAll other characters are left unchanged. 6935*572c4311SfengbojiangThe definition of what a lowercase letter is depends on the current locale. 6936*572c4311Sfengbojiang 6937*572c4311Sfengbojiang 6938*572c4311Sfengbojiang 6939*572c4311Sfengbojiang<h3>5.4.1 - <a name="5.4.1">Patterns</a></h3> 6940*572c4311Sfengbojiang 6941*572c4311Sfengbojiang 6942*572c4311Sfengbojiang<h4>Character Class:</h4><p> 6943*572c4311SfengbojiangA <em>character class</em> is used to represent a set of characters. 6944*572c4311SfengbojiangThe following combinations are allowed in describing a character class: 6945*572c4311Sfengbojiang 6946*572c4311Sfengbojiang<ul> 6947*572c4311Sfengbojiang 6948*572c4311Sfengbojiang<li><b><em>x</em>:</b> 6949*572c4311Sfengbojiang(where <em>x</em> is not one of the <em>magic characters</em> 6950*572c4311Sfengbojiang<code>^$()%.[]*+-?</code>) 6951*572c4311Sfengbojiangrepresents the character <em>x</em> itself. 6952*572c4311Sfengbojiang</li> 6953*572c4311Sfengbojiang 6954*572c4311Sfengbojiang<li><b><code>.</code>:</b> (a dot) represents all characters.</li> 6955*572c4311Sfengbojiang 6956*572c4311Sfengbojiang<li><b><code>%a</code>:</b> represents all letters.</li> 6957*572c4311Sfengbojiang 6958*572c4311Sfengbojiang<li><b><code>%c</code>:</b> represents all control characters.</li> 6959*572c4311Sfengbojiang 6960*572c4311Sfengbojiang<li><b><code>%d</code>:</b> represents all digits.</li> 6961*572c4311Sfengbojiang 6962*572c4311Sfengbojiang<li><b><code>%l</code>:</b> represents all lowercase letters.</li> 6963*572c4311Sfengbojiang 6964*572c4311Sfengbojiang<li><b><code>%p</code>:</b> represents all punctuation characters.</li> 6965*572c4311Sfengbojiang 6966*572c4311Sfengbojiang<li><b><code>%s</code>:</b> represents all space characters.</li> 6967*572c4311Sfengbojiang 6968*572c4311Sfengbojiang<li><b><code>%u</code>:</b> represents all uppercase letters.</li> 6969*572c4311Sfengbojiang 6970*572c4311Sfengbojiang<li><b><code>%w</code>:</b> represents all alphanumeric characters.</li> 6971*572c4311Sfengbojiang 6972*572c4311Sfengbojiang<li><b><code>%x</code>:</b> represents all hexadecimal digits.</li> 6973*572c4311Sfengbojiang 6974*572c4311Sfengbojiang<li><b><code>%z</code>:</b> represents the character with representation 0.</li> 6975*572c4311Sfengbojiang 6976*572c4311Sfengbojiang<li><b><code>%<em>x</em></code>:</b> (where <em>x</em> is any non-alphanumeric character) 6977*572c4311Sfengbojiangrepresents the character <em>x</em>. 6978*572c4311SfengbojiangThis is the standard way to escape the magic characters. 6979*572c4311SfengbojiangAny punctuation character (even the non magic) 6980*572c4311Sfengbojiangcan be preceded by a '<code>%</code>' 6981*572c4311Sfengbojiangwhen used to represent itself in a pattern. 6982*572c4311Sfengbojiang</li> 6983*572c4311Sfengbojiang 6984*572c4311Sfengbojiang<li><b><code>[<em>set</em>]</code>:</b> 6985*572c4311Sfengbojiangrepresents the class which is the union of all 6986*572c4311Sfengbojiangcharacters in <em>set</em>. 6987*572c4311SfengbojiangA range of characters can be specified by 6988*572c4311Sfengbojiangseparating the end characters of the range with a '<code>-</code>'. 6989*572c4311SfengbojiangAll classes <code>%</code><em>x</em> described above can also be used as 6990*572c4311Sfengbojiangcomponents in <em>set</em>. 6991*572c4311SfengbojiangAll other characters in <em>set</em> represent themselves. 6992*572c4311SfengbojiangFor example, <code>[%w_]</code> (or <code>[_%w]</code>) 6993*572c4311Sfengbojiangrepresents all alphanumeric characters plus the underscore, 6994*572c4311Sfengbojiang<code>[0-7]</code> represents the octal digits, 6995*572c4311Sfengbojiangand <code>[0-7%l%-]</code> represents the octal digits plus 6996*572c4311Sfengbojiangthe lowercase letters plus the '<code>-</code>' character. 6997*572c4311Sfengbojiang 6998*572c4311Sfengbojiang 6999*572c4311Sfengbojiang<p> 7000*572c4311SfengbojiangThe interaction between ranges and classes is not defined. 7001*572c4311SfengbojiangTherefore, patterns like <code>[%a-z]</code> or <code>[a-%%]</code> 7002*572c4311Sfengbojianghave no meaning. 7003*572c4311Sfengbojiang</li> 7004*572c4311Sfengbojiang 7005*572c4311Sfengbojiang<li><b><code>[^<em>set</em>]</code>:</b> 7006*572c4311Sfengbojiangrepresents the complement of <em>set</em>, 7007*572c4311Sfengbojiangwhere <em>set</em> is interpreted as above. 7008*572c4311Sfengbojiang</li> 7009*572c4311Sfengbojiang 7010*572c4311Sfengbojiang</ul><p> 7011*572c4311SfengbojiangFor all classes represented by single letters (<code>%a</code>, <code>%c</code>, etc.), 7012*572c4311Sfengbojiangthe corresponding uppercase letter represents the complement of the class. 7013*572c4311SfengbojiangFor instance, <code>%S</code> represents all non-space characters. 7014*572c4311Sfengbojiang 7015*572c4311Sfengbojiang 7016*572c4311Sfengbojiang<p> 7017*572c4311SfengbojiangThe definitions of letter, space, and other character groups 7018*572c4311Sfengbojiangdepend on the current locale. 7019*572c4311SfengbojiangIn particular, the class <code>[a-z]</code> may not be equivalent to <code>%l</code>. 7020*572c4311Sfengbojiang 7021*572c4311Sfengbojiang 7022*572c4311Sfengbojiang 7023*572c4311Sfengbojiang 7024*572c4311Sfengbojiang 7025*572c4311Sfengbojiang<h4>Pattern Item:</h4><p> 7026*572c4311SfengbojiangA <em>pattern item</em> can be 7027*572c4311Sfengbojiang 7028*572c4311Sfengbojiang<ul> 7029*572c4311Sfengbojiang 7030*572c4311Sfengbojiang<li> 7031*572c4311Sfengbojianga single character class, 7032*572c4311Sfengbojiangwhich matches any single character in the class; 7033*572c4311Sfengbojiang</li> 7034*572c4311Sfengbojiang 7035*572c4311Sfengbojiang<li> 7036*572c4311Sfengbojianga single character class followed by '<code>*</code>', 7037*572c4311Sfengbojiangwhich matches 0 or more repetitions of characters in the class. 7038*572c4311SfengbojiangThese repetition items will always match the longest possible sequence; 7039*572c4311Sfengbojiang</li> 7040*572c4311Sfengbojiang 7041*572c4311Sfengbojiang<li> 7042*572c4311Sfengbojianga single character class followed by '<code>+</code>', 7043*572c4311Sfengbojiangwhich matches 1 or more repetitions of characters in the class. 7044*572c4311SfengbojiangThese repetition items will always match the longest possible sequence; 7045*572c4311Sfengbojiang</li> 7046*572c4311Sfengbojiang 7047*572c4311Sfengbojiang<li> 7048*572c4311Sfengbojianga single character class followed by '<code>-</code>', 7049*572c4311Sfengbojiangwhich also matches 0 or more repetitions of characters in the class. 7050*572c4311SfengbojiangUnlike '<code>*</code>', 7051*572c4311Sfengbojiangthese repetition items will always match the <em>shortest</em> possible sequence; 7052*572c4311Sfengbojiang</li> 7053*572c4311Sfengbojiang 7054*572c4311Sfengbojiang<li> 7055*572c4311Sfengbojianga single character class followed by '<code>?</code>', 7056*572c4311Sfengbojiangwhich matches 0 or 1 occurrence of a character in the class; 7057*572c4311Sfengbojiang</li> 7058*572c4311Sfengbojiang 7059*572c4311Sfengbojiang<li> 7060*572c4311Sfengbojiang<code>%<em>n</em></code>, for <em>n</em> between 1 and 9; 7061*572c4311Sfengbojiangsuch item matches a substring equal to the <em>n</em>-th captured string 7062*572c4311Sfengbojiang(see below); 7063*572c4311Sfengbojiang</li> 7064*572c4311Sfengbojiang 7065*572c4311Sfengbojiang<li> 7066*572c4311Sfengbojiang<code>%b<em>xy</em></code>, where <em>x</em> and <em>y</em> are two distinct characters; 7067*572c4311Sfengbojiangsuch item matches strings that start with <em>x</em>, end with <em>y</em>, 7068*572c4311Sfengbojiangand where the <em>x</em> and <em>y</em> are <em>balanced</em>. 7069*572c4311SfengbojiangThis means that, if one reads the string from left to right, 7070*572c4311Sfengbojiangcounting <em>+1</em> for an <em>x</em> and <em>-1</em> for a <em>y</em>, 7071*572c4311Sfengbojiangthe ending <em>y</em> is the first <em>y</em> where the count reaches 0. 7072*572c4311SfengbojiangFor instance, the item <code>%b()</code> matches expressions with 7073*572c4311Sfengbojiangbalanced parentheses. 7074*572c4311Sfengbojiang</li> 7075*572c4311Sfengbojiang 7076*572c4311Sfengbojiang</ul> 7077*572c4311Sfengbojiang 7078*572c4311Sfengbojiang 7079*572c4311Sfengbojiang 7080*572c4311Sfengbojiang 7081*572c4311Sfengbojiang<h4>Pattern:</h4><p> 7082*572c4311SfengbojiangA <em>pattern</em> is a sequence of pattern items. 7083*572c4311SfengbojiangA '<code>^</code>' at the beginning of a pattern anchors the match at the 7084*572c4311Sfengbojiangbeginning of the subject string. 7085*572c4311SfengbojiangA '<code>$</code>' at the end of a pattern anchors the match at the 7086*572c4311Sfengbojiangend of the subject string. 7087*572c4311SfengbojiangAt other positions, 7088*572c4311Sfengbojiang'<code>^</code>' and '<code>$</code>' have no special meaning and represent themselves. 7089*572c4311Sfengbojiang 7090*572c4311Sfengbojiang 7091*572c4311Sfengbojiang 7092*572c4311Sfengbojiang 7093*572c4311Sfengbojiang 7094*572c4311Sfengbojiang<h4>Captures:</h4><p> 7095*572c4311SfengbojiangA pattern can contain sub-patterns enclosed in parentheses; 7096*572c4311Sfengbojiangthey describe <em>captures</em>. 7097*572c4311SfengbojiangWhen a match succeeds, the substrings of the subject string 7098*572c4311Sfengbojiangthat match captures are stored (<em>captured</em>) for future use. 7099*572c4311SfengbojiangCaptures are numbered according to their left parentheses. 7100*572c4311SfengbojiangFor instance, in the pattern <code>"(a*(.)%w(%s*))"</code>, 7101*572c4311Sfengbojiangthe part of the string matching <code>"a*(.)%w(%s*)"</code> is 7102*572c4311Sfengbojiangstored as the first capture (and therefore has number 1); 7103*572c4311Sfengbojiangthe character matching "<code>.</code>" is captured with number 2, 7104*572c4311Sfengbojiangand the part matching "<code>%s*</code>" has number 3. 7105*572c4311Sfengbojiang 7106*572c4311Sfengbojiang 7107*572c4311Sfengbojiang<p> 7108*572c4311SfengbojiangAs a special case, the empty capture <code>()</code> captures 7109*572c4311Sfengbojiangthe current string position (a number). 7110*572c4311SfengbojiangFor instance, if we apply the pattern <code>"()aa()"</code> on the 7111*572c4311Sfengbojiangstring <code>"flaaap"</code>, there will be two captures: 3 and 5. 7112*572c4311Sfengbojiang 7113*572c4311Sfengbojiang 7114*572c4311Sfengbojiang<p> 7115*572c4311SfengbojiangA pattern cannot contain embedded zeros. Use <code>%z</code> instead. 7116*572c4311Sfengbojiang 7117*572c4311Sfengbojiang 7118*572c4311Sfengbojiang 7119*572c4311Sfengbojiang 7120*572c4311Sfengbojiang 7121*572c4311Sfengbojiang 7122*572c4311Sfengbojiang 7123*572c4311Sfengbojiang 7124*572c4311Sfengbojiang 7125*572c4311Sfengbojiang 7126*572c4311Sfengbojiang 7127*572c4311Sfengbojiang<h2>5.5 - <a name="5.5">Table Manipulation</a></h2><p> 7128*572c4311SfengbojiangThis library provides generic functions for table manipulation. 7129*572c4311SfengbojiangIt provides all its functions inside the table <a name="pdf-table"><code>table</code></a>. 7130*572c4311Sfengbojiang 7131*572c4311Sfengbojiang 7132*572c4311Sfengbojiang<p> 7133*572c4311SfengbojiangMost functions in the table library assume that the table 7134*572c4311Sfengbojiangrepresents an array or a list. 7135*572c4311SfengbojiangFor these functions, when we talk about the "length" of a table 7136*572c4311Sfengbojiangwe mean the result of the length operator. 7137*572c4311Sfengbojiang 7138*572c4311Sfengbojiang 7139*572c4311Sfengbojiang<p> 7140*572c4311Sfengbojiang<hr><h3><a name="pdf-table.concat"><code>table.concat (table [, sep [, i [, j]]])</code></a></h3> 7141*572c4311SfengbojiangGiven an array where all elements are strings or numbers, 7142*572c4311Sfengbojiangreturns <code>table[i]..sep..table[i+1] ··· sep..table[j]</code>. 7143*572c4311SfengbojiangThe default value for <code>sep</code> is the empty string, 7144*572c4311Sfengbojiangthe default for <code>i</code> is 1, 7145*572c4311Sfengbojiangand the default for <code>j</code> is the length of the table. 7146*572c4311SfengbojiangIf <code>i</code> is greater than <code>j</code>, returns the empty string. 7147*572c4311Sfengbojiang 7148*572c4311Sfengbojiang 7149*572c4311Sfengbojiang 7150*572c4311Sfengbojiang 7151*572c4311Sfengbojiang<p> 7152*572c4311Sfengbojiang<hr><h3><a name="pdf-table.insert"><code>table.insert (table, [pos,] value)</code></a></h3> 7153*572c4311Sfengbojiang 7154*572c4311Sfengbojiang 7155*572c4311Sfengbojiang<p> 7156*572c4311SfengbojiangInserts element <code>value</code> at position <code>pos</code> in <code>table</code>, 7157*572c4311Sfengbojiangshifting up other elements to open space, if necessary. 7158*572c4311SfengbojiangThe default value for <code>pos</code> is <code>n+1</code>, 7159*572c4311Sfengbojiangwhere <code>n</code> is the length of the table (see <a href="#2.5.5">§2.5.5</a>), 7160*572c4311Sfengbojiangso that a call <code>table.insert(t,x)</code> inserts <code>x</code> at the end 7161*572c4311Sfengbojiangof table <code>t</code>. 7162*572c4311Sfengbojiang 7163*572c4311Sfengbojiang 7164*572c4311Sfengbojiang 7165*572c4311Sfengbojiang 7166*572c4311Sfengbojiang<p> 7167*572c4311Sfengbojiang<hr><h3><a name="pdf-table.maxn"><code>table.maxn (table)</code></a></h3> 7168*572c4311Sfengbojiang 7169*572c4311Sfengbojiang 7170*572c4311Sfengbojiang<p> 7171*572c4311SfengbojiangReturns the largest positive numerical index of the given table, 7172*572c4311Sfengbojiangor zero if the table has no positive numerical indices. 7173*572c4311Sfengbojiang(To do its job this function does a linear traversal of 7174*572c4311Sfengbojiangthe whole table.) 7175*572c4311Sfengbojiang 7176*572c4311Sfengbojiang 7177*572c4311Sfengbojiang 7178*572c4311Sfengbojiang 7179*572c4311Sfengbojiang<p> 7180*572c4311Sfengbojiang<hr><h3><a name="pdf-table.remove"><code>table.remove (table [, pos])</code></a></h3> 7181*572c4311Sfengbojiang 7182*572c4311Sfengbojiang 7183*572c4311Sfengbojiang<p> 7184*572c4311SfengbojiangRemoves from <code>table</code> the element at position <code>pos</code>, 7185*572c4311Sfengbojiangshifting down other elements to close the space, if necessary. 7186*572c4311SfengbojiangReturns the value of the removed element. 7187*572c4311SfengbojiangThe default value for <code>pos</code> is <code>n</code>, 7188*572c4311Sfengbojiangwhere <code>n</code> is the length of the table, 7189*572c4311Sfengbojiangso that a call <code>table.remove(t)</code> removes the last element 7190*572c4311Sfengbojiangof table <code>t</code>. 7191*572c4311Sfengbojiang 7192*572c4311Sfengbojiang 7193*572c4311Sfengbojiang 7194*572c4311Sfengbojiang 7195*572c4311Sfengbojiang<p> 7196*572c4311Sfengbojiang<hr><h3><a name="pdf-table.sort"><code>table.sort (table [, comp])</code></a></h3> 7197*572c4311SfengbojiangSorts table elements in a given order, <em>in-place</em>, 7198*572c4311Sfengbojiangfrom <code>table[1]</code> to <code>table[n]</code>, 7199*572c4311Sfengbojiangwhere <code>n</code> is the length of the table. 7200*572c4311SfengbojiangIf <code>comp</code> is given, 7201*572c4311Sfengbojiangthen it must be a function that receives two table elements, 7202*572c4311Sfengbojiangand returns true 7203*572c4311Sfengbojiangwhen the first is less than the second 7204*572c4311Sfengbojiang(so that <code>not comp(a[i+1],a[i])</code> will be true after the sort). 7205*572c4311SfengbojiangIf <code>comp</code> is not given, 7206*572c4311Sfengbojiangthen the standard Lua operator <code><</code> is used instead. 7207*572c4311Sfengbojiang 7208*572c4311Sfengbojiang 7209*572c4311Sfengbojiang<p> 7210*572c4311SfengbojiangThe sort algorithm is not stable; 7211*572c4311Sfengbojiangthat is, elements considered equal by the given order 7212*572c4311Sfengbojiangmay have their relative positions changed by the sort. 7213*572c4311Sfengbojiang 7214*572c4311Sfengbojiang 7215*572c4311Sfengbojiang 7216*572c4311Sfengbojiang 7217*572c4311Sfengbojiang 7218*572c4311Sfengbojiang 7219*572c4311Sfengbojiang 7220*572c4311Sfengbojiang<h2>5.6 - <a name="5.6">Mathematical Functions</a></h2> 7221*572c4311Sfengbojiang 7222*572c4311Sfengbojiang<p> 7223*572c4311SfengbojiangThis library is an interface to the standard C math library. 7224*572c4311SfengbojiangIt provides all its functions inside the table <a name="pdf-math"><code>math</code></a>. 7225*572c4311Sfengbojiang 7226*572c4311Sfengbojiang 7227*572c4311Sfengbojiang<p> 7228*572c4311Sfengbojiang<hr><h3><a name="pdf-math.abs"><code>math.abs (x)</code></a></h3> 7229*572c4311Sfengbojiang 7230*572c4311Sfengbojiang 7231*572c4311Sfengbojiang<p> 7232*572c4311SfengbojiangReturns the absolute value of <code>x</code>. 7233*572c4311Sfengbojiang 7234*572c4311Sfengbojiang 7235*572c4311Sfengbojiang 7236*572c4311Sfengbojiang 7237*572c4311Sfengbojiang<p> 7238*572c4311Sfengbojiang<hr><h3><a name="pdf-math.acos"><code>math.acos (x)</code></a></h3> 7239*572c4311Sfengbojiang 7240*572c4311Sfengbojiang 7241*572c4311Sfengbojiang<p> 7242*572c4311SfengbojiangReturns the arc cosine of <code>x</code> (in radians). 7243*572c4311Sfengbojiang 7244*572c4311Sfengbojiang 7245*572c4311Sfengbojiang 7246*572c4311Sfengbojiang 7247*572c4311Sfengbojiang<p> 7248*572c4311Sfengbojiang<hr><h3><a name="pdf-math.asin"><code>math.asin (x)</code></a></h3> 7249*572c4311Sfengbojiang 7250*572c4311Sfengbojiang 7251*572c4311Sfengbojiang<p> 7252*572c4311SfengbojiangReturns the arc sine of <code>x</code> (in radians). 7253*572c4311Sfengbojiang 7254*572c4311Sfengbojiang 7255*572c4311Sfengbojiang 7256*572c4311Sfengbojiang 7257*572c4311Sfengbojiang<p> 7258*572c4311Sfengbojiang<hr><h3><a name="pdf-math.atan"><code>math.atan (x)</code></a></h3> 7259*572c4311Sfengbojiang 7260*572c4311Sfengbojiang 7261*572c4311Sfengbojiang<p> 7262*572c4311SfengbojiangReturns the arc tangent of <code>x</code> (in radians). 7263*572c4311Sfengbojiang 7264*572c4311Sfengbojiang 7265*572c4311Sfengbojiang 7266*572c4311Sfengbojiang 7267*572c4311Sfengbojiang<p> 7268*572c4311Sfengbojiang<hr><h3><a name="pdf-math.atan2"><code>math.atan2 (y, x)</code></a></h3> 7269*572c4311Sfengbojiang 7270*572c4311Sfengbojiang 7271*572c4311Sfengbojiang<p> 7272*572c4311SfengbojiangReturns the arc tangent of <code>y/x</code> (in radians), 7273*572c4311Sfengbojiangbut uses the signs of both parameters to find the 7274*572c4311Sfengbojiangquadrant of the result. 7275*572c4311Sfengbojiang(It also handles correctly the case of <code>x</code> being zero.) 7276*572c4311Sfengbojiang 7277*572c4311Sfengbojiang 7278*572c4311Sfengbojiang 7279*572c4311Sfengbojiang 7280*572c4311Sfengbojiang<p> 7281*572c4311Sfengbojiang<hr><h3><a name="pdf-math.ceil"><code>math.ceil (x)</code></a></h3> 7282*572c4311Sfengbojiang 7283*572c4311Sfengbojiang 7284*572c4311Sfengbojiang<p> 7285*572c4311SfengbojiangReturns the smallest integer larger than or equal to <code>x</code>. 7286*572c4311Sfengbojiang 7287*572c4311Sfengbojiang 7288*572c4311Sfengbojiang 7289*572c4311Sfengbojiang 7290*572c4311Sfengbojiang<p> 7291*572c4311Sfengbojiang<hr><h3><a name="pdf-math.cos"><code>math.cos (x)</code></a></h3> 7292*572c4311Sfengbojiang 7293*572c4311Sfengbojiang 7294*572c4311Sfengbojiang<p> 7295*572c4311SfengbojiangReturns the cosine of <code>x</code> (assumed to be in radians). 7296*572c4311Sfengbojiang 7297*572c4311Sfengbojiang 7298*572c4311Sfengbojiang 7299*572c4311Sfengbojiang 7300*572c4311Sfengbojiang<p> 7301*572c4311Sfengbojiang<hr><h3><a name="pdf-math.cosh"><code>math.cosh (x)</code></a></h3> 7302*572c4311Sfengbojiang 7303*572c4311Sfengbojiang 7304*572c4311Sfengbojiang<p> 7305*572c4311SfengbojiangReturns the hyperbolic cosine of <code>x</code>. 7306*572c4311Sfengbojiang 7307*572c4311Sfengbojiang 7308*572c4311Sfengbojiang 7309*572c4311Sfengbojiang 7310*572c4311Sfengbojiang<p> 7311*572c4311Sfengbojiang<hr><h3><a name="pdf-math.deg"><code>math.deg (x)</code></a></h3> 7312*572c4311Sfengbojiang 7313*572c4311Sfengbojiang 7314*572c4311Sfengbojiang<p> 7315*572c4311SfengbojiangReturns the angle <code>x</code> (given in radians) in degrees. 7316*572c4311Sfengbojiang 7317*572c4311Sfengbojiang 7318*572c4311Sfengbojiang 7319*572c4311Sfengbojiang 7320*572c4311Sfengbojiang<p> 7321*572c4311Sfengbojiang<hr><h3><a name="pdf-math.exp"><code>math.exp (x)</code></a></h3> 7322*572c4311Sfengbojiang 7323*572c4311Sfengbojiang 7324*572c4311Sfengbojiang<p> 7325*572c4311SfengbojiangReturns the value <em>e<sup>x</sup></em>. 7326*572c4311Sfengbojiang 7327*572c4311Sfengbojiang 7328*572c4311Sfengbojiang 7329*572c4311Sfengbojiang 7330*572c4311Sfengbojiang<p> 7331*572c4311Sfengbojiang<hr><h3><a name="pdf-math.floor"><code>math.floor (x)</code></a></h3> 7332*572c4311Sfengbojiang 7333*572c4311Sfengbojiang 7334*572c4311Sfengbojiang<p> 7335*572c4311SfengbojiangReturns the largest integer smaller than or equal to <code>x</code>. 7336*572c4311Sfengbojiang 7337*572c4311Sfengbojiang 7338*572c4311Sfengbojiang 7339*572c4311Sfengbojiang 7340*572c4311Sfengbojiang<p> 7341*572c4311Sfengbojiang<hr><h3><a name="pdf-math.fmod"><code>math.fmod (x, y)</code></a></h3> 7342*572c4311Sfengbojiang 7343*572c4311Sfengbojiang 7344*572c4311Sfengbojiang<p> 7345*572c4311SfengbojiangReturns the remainder of the division of <code>x</code> by <code>y</code> 7346*572c4311Sfengbojiangthat rounds the quotient towards zero. 7347*572c4311Sfengbojiang 7348*572c4311Sfengbojiang 7349*572c4311Sfengbojiang 7350*572c4311Sfengbojiang 7351*572c4311Sfengbojiang<p> 7352*572c4311Sfengbojiang<hr><h3><a name="pdf-math.frexp"><code>math.frexp (x)</code></a></h3> 7353*572c4311Sfengbojiang 7354*572c4311Sfengbojiang 7355*572c4311Sfengbojiang<p> 7356*572c4311SfengbojiangReturns <code>m</code> and <code>e</code> such that <em>x = m2<sup>e</sup></em>, 7357*572c4311Sfengbojiang<code>e</code> is an integer and the absolute value of <code>m</code> is 7358*572c4311Sfengbojiangin the range <em>[0.5, 1)</em> 7359*572c4311Sfengbojiang(or zero when <code>x</code> is zero). 7360*572c4311Sfengbojiang 7361*572c4311Sfengbojiang 7362*572c4311Sfengbojiang 7363*572c4311Sfengbojiang 7364*572c4311Sfengbojiang<p> 7365*572c4311Sfengbojiang<hr><h3><a name="pdf-math.huge"><code>math.huge</code></a></h3> 7366*572c4311Sfengbojiang 7367*572c4311Sfengbojiang 7368*572c4311Sfengbojiang<p> 7369*572c4311SfengbojiangThe value <code>HUGE_VAL</code>, 7370*572c4311Sfengbojianga value larger than or equal to any other numerical value. 7371*572c4311Sfengbojiang 7372*572c4311Sfengbojiang 7373*572c4311Sfengbojiang 7374*572c4311Sfengbojiang 7375*572c4311Sfengbojiang<p> 7376*572c4311Sfengbojiang<hr><h3><a name="pdf-math.ldexp"><code>math.ldexp (m, e)</code></a></h3> 7377*572c4311Sfengbojiang 7378*572c4311Sfengbojiang 7379*572c4311Sfengbojiang<p> 7380*572c4311SfengbojiangReturns <em>m2<sup>e</sup></em> (<code>e</code> should be an integer). 7381*572c4311Sfengbojiang 7382*572c4311Sfengbojiang 7383*572c4311Sfengbojiang 7384*572c4311Sfengbojiang 7385*572c4311Sfengbojiang<p> 7386*572c4311Sfengbojiang<hr><h3><a name="pdf-math.log"><code>math.log (x)</code></a></h3> 7387*572c4311Sfengbojiang 7388*572c4311Sfengbojiang 7389*572c4311Sfengbojiang<p> 7390*572c4311SfengbojiangReturns the natural logarithm of <code>x</code>. 7391*572c4311Sfengbojiang 7392*572c4311Sfengbojiang 7393*572c4311Sfengbojiang 7394*572c4311Sfengbojiang 7395*572c4311Sfengbojiang<p> 7396*572c4311Sfengbojiang<hr><h3><a name="pdf-math.log10"><code>math.log10 (x)</code></a></h3> 7397*572c4311Sfengbojiang 7398*572c4311Sfengbojiang 7399*572c4311Sfengbojiang<p> 7400*572c4311SfengbojiangReturns the base-10 logarithm of <code>x</code>. 7401*572c4311Sfengbojiang 7402*572c4311Sfengbojiang 7403*572c4311Sfengbojiang 7404*572c4311Sfengbojiang 7405*572c4311Sfengbojiang<p> 7406*572c4311Sfengbojiang<hr><h3><a name="pdf-math.max"><code>math.max (x, ···)</code></a></h3> 7407*572c4311Sfengbojiang 7408*572c4311Sfengbojiang 7409*572c4311Sfengbojiang<p> 7410*572c4311SfengbojiangReturns the maximum value among its arguments. 7411*572c4311Sfengbojiang 7412*572c4311Sfengbojiang 7413*572c4311Sfengbojiang 7414*572c4311Sfengbojiang 7415*572c4311Sfengbojiang<p> 7416*572c4311Sfengbojiang<hr><h3><a name="pdf-math.min"><code>math.min (x, ···)</code></a></h3> 7417*572c4311Sfengbojiang 7418*572c4311Sfengbojiang 7419*572c4311Sfengbojiang<p> 7420*572c4311SfengbojiangReturns the minimum value among its arguments. 7421*572c4311Sfengbojiang 7422*572c4311Sfengbojiang 7423*572c4311Sfengbojiang 7424*572c4311Sfengbojiang 7425*572c4311Sfengbojiang<p> 7426*572c4311Sfengbojiang<hr><h3><a name="pdf-math.modf"><code>math.modf (x)</code></a></h3> 7427*572c4311Sfengbojiang 7428*572c4311Sfengbojiang 7429*572c4311Sfengbojiang<p> 7430*572c4311SfengbojiangReturns two numbers, 7431*572c4311Sfengbojiangthe integral part of <code>x</code> and the fractional part of <code>x</code>. 7432*572c4311Sfengbojiang 7433*572c4311Sfengbojiang 7434*572c4311Sfengbojiang 7435*572c4311Sfengbojiang 7436*572c4311Sfengbojiang<p> 7437*572c4311Sfengbojiang<hr><h3><a name="pdf-math.pi"><code>math.pi</code></a></h3> 7438*572c4311Sfengbojiang 7439*572c4311Sfengbojiang 7440*572c4311Sfengbojiang<p> 7441*572c4311SfengbojiangThe value of <em>pi</em>. 7442*572c4311Sfengbojiang 7443*572c4311Sfengbojiang 7444*572c4311Sfengbojiang 7445*572c4311Sfengbojiang 7446*572c4311Sfengbojiang<p> 7447*572c4311Sfengbojiang<hr><h3><a name="pdf-math.pow"><code>math.pow (x, y)</code></a></h3> 7448*572c4311Sfengbojiang 7449*572c4311Sfengbojiang 7450*572c4311Sfengbojiang<p> 7451*572c4311SfengbojiangReturns <em>x<sup>y</sup></em>. 7452*572c4311Sfengbojiang(You can also use the expression <code>x^y</code> to compute this value.) 7453*572c4311Sfengbojiang 7454*572c4311Sfengbojiang 7455*572c4311Sfengbojiang 7456*572c4311Sfengbojiang 7457*572c4311Sfengbojiang<p> 7458*572c4311Sfengbojiang<hr><h3><a name="pdf-math.rad"><code>math.rad (x)</code></a></h3> 7459*572c4311Sfengbojiang 7460*572c4311Sfengbojiang 7461*572c4311Sfengbojiang<p> 7462*572c4311SfengbojiangReturns the angle <code>x</code> (given in degrees) in radians. 7463*572c4311Sfengbojiang 7464*572c4311Sfengbojiang 7465*572c4311Sfengbojiang 7466*572c4311Sfengbojiang 7467*572c4311Sfengbojiang<p> 7468*572c4311Sfengbojiang<hr><h3><a name="pdf-math.random"><code>math.random ([m [, n]])</code></a></h3> 7469*572c4311Sfengbojiang 7470*572c4311Sfengbojiang 7471*572c4311Sfengbojiang<p> 7472*572c4311SfengbojiangThis function is an interface to the simple 7473*572c4311Sfengbojiangpseudo-random generator function <code>rand</code> provided by ANSI C. 7474*572c4311Sfengbojiang(No guarantees can be given for its statistical properties.) 7475*572c4311Sfengbojiang 7476*572c4311Sfengbojiang 7477*572c4311Sfengbojiang<p> 7478*572c4311SfengbojiangWhen called without arguments, 7479*572c4311Sfengbojiangreturns a uniform pseudo-random real number 7480*572c4311Sfengbojiangin the range <em>[0,1)</em>. 7481*572c4311SfengbojiangWhen called with an integer number <code>m</code>, 7482*572c4311Sfengbojiang<code>math.random</code> returns 7483*572c4311Sfengbojianga uniform pseudo-random integer in the range <em>[1, m]</em>. 7484*572c4311SfengbojiangWhen called with two integer numbers <code>m</code> and <code>n</code>, 7485*572c4311Sfengbojiang<code>math.random</code> returns a uniform pseudo-random 7486*572c4311Sfengbojianginteger in the range <em>[m, n]</em>. 7487*572c4311Sfengbojiang 7488*572c4311Sfengbojiang 7489*572c4311Sfengbojiang 7490*572c4311Sfengbojiang 7491*572c4311Sfengbojiang<p> 7492*572c4311Sfengbojiang<hr><h3><a name="pdf-math.randomseed"><code>math.randomseed (x)</code></a></h3> 7493*572c4311Sfengbojiang 7494*572c4311Sfengbojiang 7495*572c4311Sfengbojiang<p> 7496*572c4311SfengbojiangSets <code>x</code> as the "seed" 7497*572c4311Sfengbojiangfor the pseudo-random generator: 7498*572c4311Sfengbojiangequal seeds produce equal sequences of numbers. 7499*572c4311Sfengbojiang 7500*572c4311Sfengbojiang 7501*572c4311Sfengbojiang 7502*572c4311Sfengbojiang 7503*572c4311Sfengbojiang<p> 7504*572c4311Sfengbojiang<hr><h3><a name="pdf-math.sin"><code>math.sin (x)</code></a></h3> 7505*572c4311Sfengbojiang 7506*572c4311Sfengbojiang 7507*572c4311Sfengbojiang<p> 7508*572c4311SfengbojiangReturns the sine of <code>x</code> (assumed to be in radians). 7509*572c4311Sfengbojiang 7510*572c4311Sfengbojiang 7511*572c4311Sfengbojiang 7512*572c4311Sfengbojiang 7513*572c4311Sfengbojiang<p> 7514*572c4311Sfengbojiang<hr><h3><a name="pdf-math.sinh"><code>math.sinh (x)</code></a></h3> 7515*572c4311Sfengbojiang 7516*572c4311Sfengbojiang 7517*572c4311Sfengbojiang<p> 7518*572c4311SfengbojiangReturns the hyperbolic sine of <code>x</code>. 7519*572c4311Sfengbojiang 7520*572c4311Sfengbojiang 7521*572c4311Sfengbojiang 7522*572c4311Sfengbojiang 7523*572c4311Sfengbojiang<p> 7524*572c4311Sfengbojiang<hr><h3><a name="pdf-math.sqrt"><code>math.sqrt (x)</code></a></h3> 7525*572c4311Sfengbojiang 7526*572c4311Sfengbojiang 7527*572c4311Sfengbojiang<p> 7528*572c4311SfengbojiangReturns the square root of <code>x</code>. 7529*572c4311Sfengbojiang(You can also use the expression <code>x^0.5</code> to compute this value.) 7530*572c4311Sfengbojiang 7531*572c4311Sfengbojiang 7532*572c4311Sfengbojiang 7533*572c4311Sfengbojiang 7534*572c4311Sfengbojiang<p> 7535*572c4311Sfengbojiang<hr><h3><a name="pdf-math.tan"><code>math.tan (x)</code></a></h3> 7536*572c4311Sfengbojiang 7537*572c4311Sfengbojiang 7538*572c4311Sfengbojiang<p> 7539*572c4311SfengbojiangReturns the tangent of <code>x</code> (assumed to be in radians). 7540*572c4311Sfengbojiang 7541*572c4311Sfengbojiang 7542*572c4311Sfengbojiang 7543*572c4311Sfengbojiang 7544*572c4311Sfengbojiang<p> 7545*572c4311Sfengbojiang<hr><h3><a name="pdf-math.tanh"><code>math.tanh (x)</code></a></h3> 7546*572c4311Sfengbojiang 7547*572c4311Sfengbojiang 7548*572c4311Sfengbojiang<p> 7549*572c4311SfengbojiangReturns the hyperbolic tangent of <code>x</code>. 7550*572c4311Sfengbojiang 7551*572c4311Sfengbojiang 7552*572c4311Sfengbojiang 7553*572c4311Sfengbojiang 7554*572c4311Sfengbojiang 7555*572c4311Sfengbojiang 7556*572c4311Sfengbojiang 7557*572c4311Sfengbojiang<h2>5.7 - <a name="5.7">Input and Output Facilities</a></h2> 7558*572c4311Sfengbojiang 7559*572c4311Sfengbojiang<p> 7560*572c4311SfengbojiangThe I/O library provides two different styles for file manipulation. 7561*572c4311SfengbojiangThe first one uses implicit file descriptors; 7562*572c4311Sfengbojiangthat is, there are operations to set a default input file and a 7563*572c4311Sfengbojiangdefault output file, 7564*572c4311Sfengbojiangand all input/output operations are over these default files. 7565*572c4311SfengbojiangThe second style uses explicit file descriptors. 7566*572c4311Sfengbojiang 7567*572c4311Sfengbojiang 7568*572c4311Sfengbojiang<p> 7569*572c4311SfengbojiangWhen using implicit file descriptors, 7570*572c4311Sfengbojiangall operations are supplied by table <a name="pdf-io"><code>io</code></a>. 7571*572c4311SfengbojiangWhen using explicit file descriptors, 7572*572c4311Sfengbojiangthe operation <a href="#pdf-io.open"><code>io.open</code></a> returns a file descriptor 7573*572c4311Sfengbojiangand then all operations are supplied as methods of the file descriptor. 7574*572c4311Sfengbojiang 7575*572c4311Sfengbojiang 7576*572c4311Sfengbojiang<p> 7577*572c4311SfengbojiangThe table <code>io</code> also provides 7578*572c4311Sfengbojiangthree predefined file descriptors with their usual meanings from C: 7579*572c4311Sfengbojiang<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>. 7580*572c4311SfengbojiangThe I/O library never closes these files. 7581*572c4311Sfengbojiang 7582*572c4311Sfengbojiang 7583*572c4311Sfengbojiang<p> 7584*572c4311SfengbojiangUnless otherwise stated, 7585*572c4311Sfengbojiangall I/O functions return <b>nil</b> on failure 7586*572c4311Sfengbojiang(plus an error message as a second result and 7587*572c4311Sfengbojianga system-dependent error code as a third result) 7588*572c4311Sfengbojiangand some value different from <b>nil</b> on success. 7589*572c4311Sfengbojiang 7590*572c4311Sfengbojiang 7591*572c4311Sfengbojiang<p> 7592*572c4311Sfengbojiang<hr><h3><a name="pdf-io.close"><code>io.close ([file])</code></a></h3> 7593*572c4311Sfengbojiang 7594*572c4311Sfengbojiang 7595*572c4311Sfengbojiang<p> 7596*572c4311SfengbojiangEquivalent to <code>file:close()</code>. 7597*572c4311SfengbojiangWithout a <code>file</code>, closes the default output file. 7598*572c4311Sfengbojiang 7599*572c4311Sfengbojiang 7600*572c4311Sfengbojiang 7601*572c4311Sfengbojiang 7602*572c4311Sfengbojiang<p> 7603*572c4311Sfengbojiang<hr><h3><a name="pdf-io.flush"><code>io.flush ()</code></a></h3> 7604*572c4311Sfengbojiang 7605*572c4311Sfengbojiang 7606*572c4311Sfengbojiang<p> 7607*572c4311SfengbojiangEquivalent to <code>file:flush</code> over the default output file. 7608*572c4311Sfengbojiang 7609*572c4311Sfengbojiang 7610*572c4311Sfengbojiang 7611*572c4311Sfengbojiang 7612*572c4311Sfengbojiang<p> 7613*572c4311Sfengbojiang<hr><h3><a name="pdf-io.input"><code>io.input ([file])</code></a></h3> 7614*572c4311Sfengbojiang 7615*572c4311Sfengbojiang 7616*572c4311Sfengbojiang<p> 7617*572c4311SfengbojiangWhen called with a file name, it opens the named file (in text mode), 7618*572c4311Sfengbojiangand sets its handle as the default input file. 7619*572c4311SfengbojiangWhen called with a file handle, 7620*572c4311Sfengbojiangit simply sets this file handle as the default input file. 7621*572c4311SfengbojiangWhen called without parameters, 7622*572c4311Sfengbojiangit returns the current default input file. 7623*572c4311Sfengbojiang 7624*572c4311Sfengbojiang 7625*572c4311Sfengbojiang<p> 7626*572c4311SfengbojiangIn case of errors this function raises the error, 7627*572c4311Sfengbojianginstead of returning an error code. 7628*572c4311Sfengbojiang 7629*572c4311Sfengbojiang 7630*572c4311Sfengbojiang 7631*572c4311Sfengbojiang 7632*572c4311Sfengbojiang<p> 7633*572c4311Sfengbojiang<hr><h3><a name="pdf-io.lines"><code>io.lines ([filename])</code></a></h3> 7634*572c4311Sfengbojiang 7635*572c4311Sfengbojiang 7636*572c4311Sfengbojiang<p> 7637*572c4311SfengbojiangOpens the given file name in read mode 7638*572c4311Sfengbojiangand returns an iterator function that, 7639*572c4311Sfengbojiangeach time it is called, 7640*572c4311Sfengbojiangreturns a new line from the file. 7641*572c4311SfengbojiangTherefore, the construction 7642*572c4311Sfengbojiang 7643*572c4311Sfengbojiang<pre> 7644*572c4311Sfengbojiang for line in io.lines(filename) do <em>body</em> end 7645*572c4311Sfengbojiang</pre><p> 7646*572c4311Sfengbojiangwill iterate over all lines of the file. 7647*572c4311SfengbojiangWhen the iterator function detects the end of file, 7648*572c4311Sfengbojiangit returns <b>nil</b> (to finish the loop) and automatically closes the file. 7649*572c4311Sfengbojiang 7650*572c4311Sfengbojiang 7651*572c4311Sfengbojiang<p> 7652*572c4311SfengbojiangThe call <code>io.lines()</code> (with no file name) is equivalent 7653*572c4311Sfengbojiangto <code>io.input():lines()</code>; 7654*572c4311Sfengbojiangthat is, it iterates over the lines of the default input file. 7655*572c4311SfengbojiangIn this case it does not close the file when the loop ends. 7656*572c4311Sfengbojiang 7657*572c4311Sfengbojiang 7658*572c4311Sfengbojiang 7659*572c4311Sfengbojiang 7660*572c4311Sfengbojiang<p> 7661*572c4311Sfengbojiang<hr><h3><a name="pdf-io.open"><code>io.open (filename [, mode])</code></a></h3> 7662*572c4311Sfengbojiang 7663*572c4311Sfengbojiang 7664*572c4311Sfengbojiang<p> 7665*572c4311SfengbojiangThis function opens a file, 7666*572c4311Sfengbojiangin the mode specified in the string <code>mode</code>. 7667*572c4311SfengbojiangIt returns a new file handle, 7668*572c4311Sfengbojiangor, in case of errors, <b>nil</b> plus an error message. 7669*572c4311Sfengbojiang 7670*572c4311Sfengbojiang 7671*572c4311Sfengbojiang<p> 7672*572c4311SfengbojiangThe <code>mode</code> string can be any of the following: 7673*572c4311Sfengbojiang 7674*572c4311Sfengbojiang<ul> 7675*572c4311Sfengbojiang<li><b>"r":</b> read mode (the default);</li> 7676*572c4311Sfengbojiang<li><b>"w":</b> write mode;</li> 7677*572c4311Sfengbojiang<li><b>"a":</b> append mode;</li> 7678*572c4311Sfengbojiang<li><b>"r+":</b> update mode, all previous data is preserved;</li> 7679*572c4311Sfengbojiang<li><b>"w+":</b> update mode, all previous data is erased;</li> 7680*572c4311Sfengbojiang<li><b>"a+":</b> append update mode, previous data is preserved, 7681*572c4311Sfengbojiang writing is only allowed at the end of file.</li> 7682*572c4311Sfengbojiang</ul><p> 7683*572c4311SfengbojiangThe <code>mode</code> string can also have a '<code>b</code>' at the end, 7684*572c4311Sfengbojiangwhich is needed in some systems to open the file in binary mode. 7685*572c4311SfengbojiangThis string is exactly what is used in the 7686*572c4311Sfengbojiangstandard C function <code>fopen</code>. 7687*572c4311Sfengbojiang 7688*572c4311Sfengbojiang 7689*572c4311Sfengbojiang 7690*572c4311Sfengbojiang 7691*572c4311Sfengbojiang<p> 7692*572c4311Sfengbojiang<hr><h3><a name="pdf-io.output"><code>io.output ([file])</code></a></h3> 7693*572c4311Sfengbojiang 7694*572c4311Sfengbojiang 7695*572c4311Sfengbojiang<p> 7696*572c4311SfengbojiangSimilar to <a href="#pdf-io.input"><code>io.input</code></a>, but operates over the default output file. 7697*572c4311Sfengbojiang 7698*572c4311Sfengbojiang 7699*572c4311Sfengbojiang 7700*572c4311Sfengbojiang 7701*572c4311Sfengbojiang<p> 7702*572c4311Sfengbojiang<hr><h3><a name="pdf-io.popen"><code>io.popen (prog [, mode])</code></a></h3> 7703*572c4311Sfengbojiang 7704*572c4311Sfengbojiang 7705*572c4311Sfengbojiang<p> 7706*572c4311SfengbojiangStarts program <code>prog</code> in a separated process and returns 7707*572c4311Sfengbojianga file handle that you can use to read data from this program 7708*572c4311Sfengbojiang(if <code>mode</code> is <code>"r"</code>, the default) 7709*572c4311Sfengbojiangor to write data to this program 7710*572c4311Sfengbojiang(if <code>mode</code> is <code>"w"</code>). 7711*572c4311Sfengbojiang 7712*572c4311Sfengbojiang 7713*572c4311Sfengbojiang<p> 7714*572c4311SfengbojiangThis function is system dependent and is not available 7715*572c4311Sfengbojiangon all platforms. 7716*572c4311Sfengbojiang 7717*572c4311Sfengbojiang 7718*572c4311Sfengbojiang 7719*572c4311Sfengbojiang 7720*572c4311Sfengbojiang<p> 7721*572c4311Sfengbojiang<hr><h3><a name="pdf-io.read"><code>io.read (···)</code></a></h3> 7722*572c4311Sfengbojiang 7723*572c4311Sfengbojiang 7724*572c4311Sfengbojiang<p> 7725*572c4311SfengbojiangEquivalent to <code>io.input():read</code>. 7726*572c4311Sfengbojiang 7727*572c4311Sfengbojiang 7728*572c4311Sfengbojiang 7729*572c4311Sfengbojiang 7730*572c4311Sfengbojiang<p> 7731*572c4311Sfengbojiang<hr><h3><a name="pdf-io.tmpfile"><code>io.tmpfile ()</code></a></h3> 7732*572c4311Sfengbojiang 7733*572c4311Sfengbojiang 7734*572c4311Sfengbojiang<p> 7735*572c4311SfengbojiangReturns a handle for a temporary file. 7736*572c4311SfengbojiangThis file is opened in update mode 7737*572c4311Sfengbojiangand it is automatically removed when the program ends. 7738*572c4311Sfengbojiang 7739*572c4311Sfengbojiang 7740*572c4311Sfengbojiang 7741*572c4311Sfengbojiang 7742*572c4311Sfengbojiang<p> 7743*572c4311Sfengbojiang<hr><h3><a name="pdf-io.type"><code>io.type (obj)</code></a></h3> 7744*572c4311Sfengbojiang 7745*572c4311Sfengbojiang 7746*572c4311Sfengbojiang<p> 7747*572c4311SfengbojiangChecks whether <code>obj</code> is a valid file handle. 7748*572c4311SfengbojiangReturns the string <code>"file"</code> if <code>obj</code> is an open file handle, 7749*572c4311Sfengbojiang<code>"closed file"</code> if <code>obj</code> is a closed file handle, 7750*572c4311Sfengbojiangor <b>nil</b> if <code>obj</code> is not a file handle. 7751*572c4311Sfengbojiang 7752*572c4311Sfengbojiang 7753*572c4311Sfengbojiang 7754*572c4311Sfengbojiang 7755*572c4311Sfengbojiang<p> 7756*572c4311Sfengbojiang<hr><h3><a name="pdf-io.write"><code>io.write (···)</code></a></h3> 7757*572c4311Sfengbojiang 7758*572c4311Sfengbojiang 7759*572c4311Sfengbojiang<p> 7760*572c4311SfengbojiangEquivalent to <code>io.output():write</code>. 7761*572c4311Sfengbojiang 7762*572c4311Sfengbojiang 7763*572c4311Sfengbojiang 7764*572c4311Sfengbojiang 7765*572c4311Sfengbojiang<p> 7766*572c4311Sfengbojiang<hr><h3><a name="pdf-file:close"><code>file:close ()</code></a></h3> 7767*572c4311Sfengbojiang 7768*572c4311Sfengbojiang 7769*572c4311Sfengbojiang<p> 7770*572c4311SfengbojiangCloses <code>file</code>. 7771*572c4311SfengbojiangNote that files are automatically closed when 7772*572c4311Sfengbojiangtheir handles are garbage collected, 7773*572c4311Sfengbojiangbut that takes an unpredictable amount of time to happen. 7774*572c4311Sfengbojiang 7775*572c4311Sfengbojiang 7776*572c4311Sfengbojiang 7777*572c4311Sfengbojiang 7778*572c4311Sfengbojiang<p> 7779*572c4311Sfengbojiang<hr><h3><a name="pdf-file:flush"><code>file:flush ()</code></a></h3> 7780*572c4311Sfengbojiang 7781*572c4311Sfengbojiang 7782*572c4311Sfengbojiang<p> 7783*572c4311SfengbojiangSaves any written data to <code>file</code>. 7784*572c4311Sfengbojiang 7785*572c4311Sfengbojiang 7786*572c4311Sfengbojiang 7787*572c4311Sfengbojiang 7788*572c4311Sfengbojiang<p> 7789*572c4311Sfengbojiang<hr><h3><a name="pdf-file:lines"><code>file:lines ()</code></a></h3> 7790*572c4311Sfengbojiang 7791*572c4311Sfengbojiang 7792*572c4311Sfengbojiang<p> 7793*572c4311SfengbojiangReturns an iterator function that, 7794*572c4311Sfengbojiangeach time it is called, 7795*572c4311Sfengbojiangreturns a new line from the file. 7796*572c4311SfengbojiangTherefore, the construction 7797*572c4311Sfengbojiang 7798*572c4311Sfengbojiang<pre> 7799*572c4311Sfengbojiang for line in file:lines() do <em>body</em> end 7800*572c4311Sfengbojiang</pre><p> 7801*572c4311Sfengbojiangwill iterate over all lines of the file. 7802*572c4311Sfengbojiang(Unlike <a href="#pdf-io.lines"><code>io.lines</code></a>, this function does not close the file 7803*572c4311Sfengbojiangwhen the loop ends.) 7804*572c4311Sfengbojiang 7805*572c4311Sfengbojiang 7806*572c4311Sfengbojiang 7807*572c4311Sfengbojiang 7808*572c4311Sfengbojiang<p> 7809*572c4311Sfengbojiang<hr><h3><a name="pdf-file:read"><code>file:read (···)</code></a></h3> 7810*572c4311Sfengbojiang 7811*572c4311Sfengbojiang 7812*572c4311Sfengbojiang<p> 7813*572c4311SfengbojiangReads the file <code>file</code>, 7814*572c4311Sfengbojiangaccording to the given formats, which specify what to read. 7815*572c4311SfengbojiangFor each format, 7816*572c4311Sfengbojiangthe function returns a string (or a number) with the characters read, 7817*572c4311Sfengbojiangor <b>nil</b> if it cannot read data with the specified format. 7818*572c4311SfengbojiangWhen called without formats, 7819*572c4311Sfengbojiangit uses a default format that reads the entire next line 7820*572c4311Sfengbojiang(see below). 7821*572c4311Sfengbojiang 7822*572c4311Sfengbojiang 7823*572c4311Sfengbojiang<p> 7824*572c4311SfengbojiangThe available formats are 7825*572c4311Sfengbojiang 7826*572c4311Sfengbojiang<ul> 7827*572c4311Sfengbojiang 7828*572c4311Sfengbojiang<li><b>"*n":</b> 7829*572c4311Sfengbojiangreads a number; 7830*572c4311Sfengbojiangthis is the only format that returns a number instead of a string. 7831*572c4311Sfengbojiang</li> 7832*572c4311Sfengbojiang 7833*572c4311Sfengbojiang<li><b>"*a":</b> 7834*572c4311Sfengbojiangreads the whole file, starting at the current position. 7835*572c4311SfengbojiangOn end of file, it returns the empty string. 7836*572c4311Sfengbojiang</li> 7837*572c4311Sfengbojiang 7838*572c4311Sfengbojiang<li><b>"*l":</b> 7839*572c4311Sfengbojiangreads the next line (skipping the end of line), 7840*572c4311Sfengbojiangreturning <b>nil</b> on end of file. 7841*572c4311SfengbojiangThis is the default format. 7842*572c4311Sfengbojiang</li> 7843*572c4311Sfengbojiang 7844*572c4311Sfengbojiang<li><b><em>number</em>:</b> 7845*572c4311Sfengbojiangreads a string with up to this number of characters, 7846*572c4311Sfengbojiangreturning <b>nil</b> on end of file. 7847*572c4311SfengbojiangIf number is zero, 7848*572c4311Sfengbojiangit reads nothing and returns an empty string, 7849*572c4311Sfengbojiangor <b>nil</b> on end of file. 7850*572c4311Sfengbojiang</li> 7851*572c4311Sfengbojiang 7852*572c4311Sfengbojiang</ul> 7853*572c4311Sfengbojiang 7854*572c4311Sfengbojiang 7855*572c4311Sfengbojiang 7856*572c4311Sfengbojiang<p> 7857*572c4311Sfengbojiang<hr><h3><a name="pdf-file:seek"><code>file:seek ([whence] [, offset])</code></a></h3> 7858*572c4311Sfengbojiang 7859*572c4311Sfengbojiang 7860*572c4311Sfengbojiang<p> 7861*572c4311SfengbojiangSets and gets the file position, 7862*572c4311Sfengbojiangmeasured from the beginning of the file, 7863*572c4311Sfengbojiangto the position given by <code>offset</code> plus a base 7864*572c4311Sfengbojiangspecified by the string <code>whence</code>, as follows: 7865*572c4311Sfengbojiang 7866*572c4311Sfengbojiang<ul> 7867*572c4311Sfengbojiang<li><b>"set":</b> base is position 0 (beginning of the file);</li> 7868*572c4311Sfengbojiang<li><b>"cur":</b> base is current position;</li> 7869*572c4311Sfengbojiang<li><b>"end":</b> base is end of file;</li> 7870*572c4311Sfengbojiang</ul><p> 7871*572c4311SfengbojiangIn case of success, function <code>seek</code> returns the final file position, 7872*572c4311Sfengbojiangmeasured in bytes from the beginning of the file. 7873*572c4311SfengbojiangIf this function fails, it returns <b>nil</b>, 7874*572c4311Sfengbojiangplus a string describing the error. 7875*572c4311Sfengbojiang 7876*572c4311Sfengbojiang 7877*572c4311Sfengbojiang<p> 7878*572c4311SfengbojiangThe default value for <code>whence</code> is <code>"cur"</code>, 7879*572c4311Sfengbojiangand for <code>offset</code> is 0. 7880*572c4311SfengbojiangTherefore, the call <code>file:seek()</code> returns the current 7881*572c4311Sfengbojiangfile position, without changing it; 7882*572c4311Sfengbojiangthe call <code>file:seek("set")</code> sets the position to the 7883*572c4311Sfengbojiangbeginning of the file (and returns 0); 7884*572c4311Sfengbojiangand the call <code>file:seek("end")</code> sets the position to the 7885*572c4311Sfengbojiangend of the file, and returns its size. 7886*572c4311Sfengbojiang 7887*572c4311Sfengbojiang 7888*572c4311Sfengbojiang 7889*572c4311Sfengbojiang 7890*572c4311Sfengbojiang<p> 7891*572c4311Sfengbojiang<hr><h3><a name="pdf-file:setvbuf"><code>file:setvbuf (mode [, size])</code></a></h3> 7892*572c4311Sfengbojiang 7893*572c4311Sfengbojiang 7894*572c4311Sfengbojiang<p> 7895*572c4311SfengbojiangSets the buffering mode for an output file. 7896*572c4311SfengbojiangThere are three available modes: 7897*572c4311Sfengbojiang 7898*572c4311Sfengbojiang<ul> 7899*572c4311Sfengbojiang 7900*572c4311Sfengbojiang<li><b>"no":</b> 7901*572c4311Sfengbojiangno buffering; the result of any output operation appears immediately. 7902*572c4311Sfengbojiang</li> 7903*572c4311Sfengbojiang 7904*572c4311Sfengbojiang<li><b>"full":</b> 7905*572c4311Sfengbojiangfull buffering; output operation is performed only 7906*572c4311Sfengbojiangwhen the buffer is full (or when you explicitly <code>flush</code> the file 7907*572c4311Sfengbojiang(see <a href="#pdf-io.flush"><code>io.flush</code></a>)). 7908*572c4311Sfengbojiang</li> 7909*572c4311Sfengbojiang 7910*572c4311Sfengbojiang<li><b>"line":</b> 7911*572c4311Sfengbojiangline buffering; output is buffered until a newline is output 7912*572c4311Sfengbojiangor there is any input from some special files 7913*572c4311Sfengbojiang(such as a terminal device). 7914*572c4311Sfengbojiang</li> 7915*572c4311Sfengbojiang 7916*572c4311Sfengbojiang</ul><p> 7917*572c4311SfengbojiangFor the last two cases, <code>size</code> 7918*572c4311Sfengbojiangspecifies the size of the buffer, in bytes. 7919*572c4311SfengbojiangThe default is an appropriate size. 7920*572c4311Sfengbojiang 7921*572c4311Sfengbojiang 7922*572c4311Sfengbojiang 7923*572c4311Sfengbojiang 7924*572c4311Sfengbojiang<p> 7925*572c4311Sfengbojiang<hr><h3><a name="pdf-file:write"><code>file:write (···)</code></a></h3> 7926*572c4311Sfengbojiang 7927*572c4311Sfengbojiang 7928*572c4311Sfengbojiang<p> 7929*572c4311SfengbojiangWrites the value of each of its arguments to 7930*572c4311Sfengbojiangthe <code>file</code>. 7931*572c4311SfengbojiangThe arguments must be strings or numbers. 7932*572c4311SfengbojiangTo write other values, 7933*572c4311Sfengbojianguse <a href="#pdf-tostring"><code>tostring</code></a> or <a href="#pdf-string.format"><code>string.format</code></a> before <code>write</code>. 7934*572c4311Sfengbojiang 7935*572c4311Sfengbojiang 7936*572c4311Sfengbojiang 7937*572c4311Sfengbojiang 7938*572c4311Sfengbojiang 7939*572c4311Sfengbojiang 7940*572c4311Sfengbojiang 7941*572c4311Sfengbojiang<h2>5.8 - <a name="5.8">Operating System Facilities</a></h2> 7942*572c4311Sfengbojiang 7943*572c4311Sfengbojiang<p> 7944*572c4311SfengbojiangThis library is implemented through table <a name="pdf-os"><code>os</code></a>. 7945*572c4311Sfengbojiang 7946*572c4311Sfengbojiang 7947*572c4311Sfengbojiang<p> 7948*572c4311Sfengbojiang<hr><h3><a name="pdf-os.clock"><code>os.clock ()</code></a></h3> 7949*572c4311Sfengbojiang 7950*572c4311Sfengbojiang 7951*572c4311Sfengbojiang<p> 7952*572c4311SfengbojiangReturns an approximation of the amount in seconds of CPU time 7953*572c4311Sfengbojiangused by the program. 7954*572c4311Sfengbojiang 7955*572c4311Sfengbojiang 7956*572c4311Sfengbojiang 7957*572c4311Sfengbojiang 7958*572c4311Sfengbojiang<p> 7959*572c4311Sfengbojiang<hr><h3><a name="pdf-os.date"><code>os.date ([format [, time]])</code></a></h3> 7960*572c4311Sfengbojiang 7961*572c4311Sfengbojiang 7962*572c4311Sfengbojiang<p> 7963*572c4311SfengbojiangReturns a string or a table containing date and time, 7964*572c4311Sfengbojiangformatted according to the given string <code>format</code>. 7965*572c4311Sfengbojiang 7966*572c4311Sfengbojiang 7967*572c4311Sfengbojiang<p> 7968*572c4311SfengbojiangIf the <code>time</code> argument is present, 7969*572c4311Sfengbojiangthis is the time to be formatted 7970*572c4311Sfengbojiang(see the <a href="#pdf-os.time"><code>os.time</code></a> function for a description of this value). 7971*572c4311SfengbojiangOtherwise, <code>date</code> formats the current time. 7972*572c4311Sfengbojiang 7973*572c4311Sfengbojiang 7974*572c4311Sfengbojiang<p> 7975*572c4311SfengbojiangIf <code>format</code> starts with '<code>!</code>', 7976*572c4311Sfengbojiangthen the date is formatted in Coordinated Universal Time. 7977*572c4311SfengbojiangAfter this optional character, 7978*572c4311Sfengbojiangif <code>format</code> is the string "<code>*t</code>", 7979*572c4311Sfengbojiangthen <code>date</code> returns a table with the following fields: 7980*572c4311Sfengbojiang<code>year</code> (four digits), <code>month</code> (1--12), <code>day</code> (1--31), 7981*572c4311Sfengbojiang<code>hour</code> (0--23), <code>min</code> (0--59), <code>sec</code> (0--61), 7982*572c4311Sfengbojiang<code>wday</code> (weekday, Sunday is 1), 7983*572c4311Sfengbojiang<code>yday</code> (day of the year), 7984*572c4311Sfengbojiangand <code>isdst</code> (daylight saving flag, a boolean). 7985*572c4311Sfengbojiang 7986*572c4311Sfengbojiang 7987*572c4311Sfengbojiang<p> 7988*572c4311SfengbojiangIf <code>format</code> is not "<code>*t</code>", 7989*572c4311Sfengbojiangthen <code>date</code> returns the date as a string, 7990*572c4311Sfengbojiangformatted according to the same rules as the C function <code>strftime</code>. 7991*572c4311Sfengbojiang 7992*572c4311Sfengbojiang 7993*572c4311Sfengbojiang<p> 7994*572c4311SfengbojiangWhen called without arguments, 7995*572c4311Sfengbojiang<code>date</code> returns a reasonable date and time representation that depends on 7996*572c4311Sfengbojiangthe host system and on the current locale 7997*572c4311Sfengbojiang(that is, <code>os.date()</code> is equivalent to <code>os.date("%c")</code>). 7998*572c4311Sfengbojiang 7999*572c4311Sfengbojiang 8000*572c4311Sfengbojiang 8001*572c4311Sfengbojiang 8002*572c4311Sfengbojiang<p> 8003*572c4311Sfengbojiang<hr><h3><a name="pdf-os.difftime"><code>os.difftime (t2, t1)</code></a></h3> 8004*572c4311Sfengbojiang 8005*572c4311Sfengbojiang 8006*572c4311Sfengbojiang<p> 8007*572c4311SfengbojiangReturns the number of seconds from time <code>t1</code> to time <code>t2</code>. 8008*572c4311SfengbojiangIn POSIX, Windows, and some other systems, 8009*572c4311Sfengbojiangthis value is exactly <code>t2</code><em>-</em><code>t1</code>. 8010*572c4311Sfengbojiang 8011*572c4311Sfengbojiang 8012*572c4311Sfengbojiang 8013*572c4311Sfengbojiang 8014*572c4311Sfengbojiang<p> 8015*572c4311Sfengbojiang<hr><h3><a name="pdf-os.execute"><code>os.execute ([command])</code></a></h3> 8016*572c4311Sfengbojiang 8017*572c4311Sfengbojiang 8018*572c4311Sfengbojiang<p> 8019*572c4311SfengbojiangThis function is equivalent to the C function <code>system</code>. 8020*572c4311SfengbojiangIt passes <code>command</code> to be executed by an operating system shell. 8021*572c4311SfengbojiangIt returns a status code, which is system-dependent. 8022*572c4311SfengbojiangIf <code>command</code> is absent, then it returns nonzero if a shell is available 8023*572c4311Sfengbojiangand zero otherwise. 8024*572c4311Sfengbojiang 8025*572c4311Sfengbojiang 8026*572c4311Sfengbojiang 8027*572c4311Sfengbojiang 8028*572c4311Sfengbojiang<p> 8029*572c4311Sfengbojiang<hr><h3><a name="pdf-os.exit"><code>os.exit ([code])</code></a></h3> 8030*572c4311Sfengbojiang 8031*572c4311Sfengbojiang 8032*572c4311Sfengbojiang<p> 8033*572c4311SfengbojiangCalls the C function <code>exit</code>, 8034*572c4311Sfengbojiangwith an optional <code>code</code>, 8035*572c4311Sfengbojiangto terminate the host program. 8036*572c4311SfengbojiangThe default value for <code>code</code> is the success code. 8037*572c4311Sfengbojiang 8038*572c4311Sfengbojiang 8039*572c4311Sfengbojiang 8040*572c4311Sfengbojiang 8041*572c4311Sfengbojiang<p> 8042*572c4311Sfengbojiang<hr><h3><a name="pdf-os.getenv"><code>os.getenv (varname)</code></a></h3> 8043*572c4311Sfengbojiang 8044*572c4311Sfengbojiang 8045*572c4311Sfengbojiang<p> 8046*572c4311SfengbojiangReturns the value of the process environment variable <code>varname</code>, 8047*572c4311Sfengbojiangor <b>nil</b> if the variable is not defined. 8048*572c4311Sfengbojiang 8049*572c4311Sfengbojiang 8050*572c4311Sfengbojiang 8051*572c4311Sfengbojiang 8052*572c4311Sfengbojiang<p> 8053*572c4311Sfengbojiang<hr><h3><a name="pdf-os.remove"><code>os.remove (filename)</code></a></h3> 8054*572c4311Sfengbojiang 8055*572c4311Sfengbojiang 8056*572c4311Sfengbojiang<p> 8057*572c4311SfengbojiangDeletes the file or directory with the given name. 8058*572c4311SfengbojiangDirectories must be empty to be removed. 8059*572c4311SfengbojiangIf this function fails, it returns <b>nil</b>, 8060*572c4311Sfengbojiangplus a string describing the error. 8061*572c4311Sfengbojiang 8062*572c4311Sfengbojiang 8063*572c4311Sfengbojiang 8064*572c4311Sfengbojiang 8065*572c4311Sfengbojiang<p> 8066*572c4311Sfengbojiang<hr><h3><a name="pdf-os.rename"><code>os.rename (oldname, newname)</code></a></h3> 8067*572c4311Sfengbojiang 8068*572c4311Sfengbojiang 8069*572c4311Sfengbojiang<p> 8070*572c4311SfengbojiangRenames file or directory named <code>oldname</code> to <code>newname</code>. 8071*572c4311SfengbojiangIf this function fails, it returns <b>nil</b>, 8072*572c4311Sfengbojiangplus a string describing the error. 8073*572c4311Sfengbojiang 8074*572c4311Sfengbojiang 8075*572c4311Sfengbojiang 8076*572c4311Sfengbojiang 8077*572c4311Sfengbojiang<p> 8078*572c4311Sfengbojiang<hr><h3><a name="pdf-os.setlocale"><code>os.setlocale (locale [, category])</code></a></h3> 8079*572c4311Sfengbojiang 8080*572c4311Sfengbojiang 8081*572c4311Sfengbojiang<p> 8082*572c4311SfengbojiangSets the current locale of the program. 8083*572c4311Sfengbojiang<code>locale</code> is a string specifying a locale; 8084*572c4311Sfengbojiang<code>category</code> is an optional string describing which category to change: 8085*572c4311Sfengbojiang<code>"all"</code>, <code>"collate"</code>, <code>"ctype"</code>, 8086*572c4311Sfengbojiang<code>"monetary"</code>, <code>"numeric"</code>, or <code>"time"</code>; 8087*572c4311Sfengbojiangthe default category is <code>"all"</code>. 8088*572c4311SfengbojiangThe function returns the name of the new locale, 8089*572c4311Sfengbojiangor <b>nil</b> if the request cannot be honored. 8090*572c4311Sfengbojiang 8091*572c4311Sfengbojiang 8092*572c4311Sfengbojiang<p> 8093*572c4311SfengbojiangIf <code>locale</code> is the empty string, 8094*572c4311Sfengbojiangthe current locale is set to an implementation-defined native locale. 8095*572c4311SfengbojiangIf <code>locale</code> is the string "<code>C</code>", 8096*572c4311Sfengbojiangthe current locale is set to the standard C locale. 8097*572c4311Sfengbojiang 8098*572c4311Sfengbojiang 8099*572c4311Sfengbojiang<p> 8100*572c4311SfengbojiangWhen called with <b>nil</b> as the first argument, 8101*572c4311Sfengbojiangthis function only returns the name of the current locale 8102*572c4311Sfengbojiangfor the given category. 8103*572c4311Sfengbojiang 8104*572c4311Sfengbojiang 8105*572c4311Sfengbojiang 8106*572c4311Sfengbojiang 8107*572c4311Sfengbojiang<p> 8108*572c4311Sfengbojiang<hr><h3><a name="pdf-os.time"><code>os.time ([table])</code></a></h3> 8109*572c4311Sfengbojiang 8110*572c4311Sfengbojiang 8111*572c4311Sfengbojiang<p> 8112*572c4311SfengbojiangReturns the current time when called without arguments, 8113*572c4311Sfengbojiangor a time representing the date and time specified by the given table. 8114*572c4311SfengbojiangThis table must have fields <code>year</code>, <code>month</code>, and <code>day</code>, 8115*572c4311Sfengbojiangand may have fields <code>hour</code>, <code>min</code>, <code>sec</code>, and <code>isdst</code> 8116*572c4311Sfengbojiang(for a description of these fields, see the <a href="#pdf-os.date"><code>os.date</code></a> function). 8117*572c4311Sfengbojiang 8118*572c4311Sfengbojiang 8119*572c4311Sfengbojiang<p> 8120*572c4311SfengbojiangThe returned value is a number, whose meaning depends on your system. 8121*572c4311SfengbojiangIn POSIX, Windows, and some other systems, this number counts the number 8122*572c4311Sfengbojiangof seconds since some given start time (the "epoch"). 8123*572c4311SfengbojiangIn other systems, the meaning is not specified, 8124*572c4311Sfengbojiangand the number returned by <code>time</code> can be used only as an argument to 8125*572c4311Sfengbojiang<code>date</code> and <code>difftime</code>. 8126*572c4311Sfengbojiang 8127*572c4311Sfengbojiang 8128*572c4311Sfengbojiang 8129*572c4311Sfengbojiang 8130*572c4311Sfengbojiang<p> 8131*572c4311Sfengbojiang<hr><h3><a name="pdf-os.tmpname"><code>os.tmpname ()</code></a></h3> 8132*572c4311Sfengbojiang 8133*572c4311Sfengbojiang 8134*572c4311Sfengbojiang<p> 8135*572c4311SfengbojiangReturns a string with a file name that can 8136*572c4311Sfengbojiangbe used for a temporary file. 8137*572c4311SfengbojiangThe file must be explicitly opened before its use 8138*572c4311Sfengbojiangand explicitly removed when no longer needed. 8139*572c4311Sfengbojiang 8140*572c4311Sfengbojiang 8141*572c4311Sfengbojiang<p> 8142*572c4311SfengbojiangOn some systems (POSIX), 8143*572c4311Sfengbojiangthis function also creates a file with that name, 8144*572c4311Sfengbojiangto avoid security risks. 8145*572c4311Sfengbojiang(Someone else might create the file with wrong permissions 8146*572c4311Sfengbojiangin the time between getting the name and creating the file.) 8147*572c4311SfengbojiangYou still have to open the file to use it 8148*572c4311Sfengbojiangand to remove it (even if you do not use it). 8149*572c4311Sfengbojiang 8150*572c4311Sfengbojiang 8151*572c4311Sfengbojiang<p> 8152*572c4311SfengbojiangWhen possible, 8153*572c4311Sfengbojiangyou may prefer to use <a href="#pdf-io.tmpfile"><code>io.tmpfile</code></a>, 8154*572c4311Sfengbojiangwhich automatically removes the file when the program ends. 8155*572c4311Sfengbojiang 8156*572c4311Sfengbojiang 8157*572c4311Sfengbojiang 8158*572c4311Sfengbojiang 8159*572c4311Sfengbojiang 8160*572c4311Sfengbojiang 8161*572c4311Sfengbojiang 8162*572c4311Sfengbojiang<h2>5.9 - <a name="5.9">The Debug Library</a></h2> 8163*572c4311Sfengbojiang 8164*572c4311Sfengbojiang<p> 8165*572c4311SfengbojiangThis library provides 8166*572c4311Sfengbojiangthe functionality of the debug interface to Lua programs. 8167*572c4311SfengbojiangYou should exert care when using this library. 8168*572c4311SfengbojiangThe functions provided here should be used exclusively for debugging 8169*572c4311Sfengbojiangand similar tasks, such as profiling. 8170*572c4311SfengbojiangPlease resist the temptation to use them as a 8171*572c4311Sfengbojiangusual programming tool: 8172*572c4311Sfengbojiangthey can be very slow. 8173*572c4311SfengbojiangMoreover, several of these functions 8174*572c4311Sfengbojiangviolate some assumptions about Lua code 8175*572c4311Sfengbojiang(e.g., that variables local to a function 8176*572c4311Sfengbojiangcannot be accessed from outside or 8177*572c4311Sfengbojiangthat userdata metatables cannot be changed by Lua code) 8178*572c4311Sfengbojiangand therefore can compromise otherwise secure code. 8179*572c4311Sfengbojiang 8180*572c4311Sfengbojiang 8181*572c4311Sfengbojiang<p> 8182*572c4311SfengbojiangAll functions in this library are provided 8183*572c4311Sfengbojianginside the <a name="pdf-debug"><code>debug</code></a> table. 8184*572c4311SfengbojiangAll functions that operate over a thread 8185*572c4311Sfengbojianghave an optional first argument which is the 8186*572c4311Sfengbojiangthread to operate over. 8187*572c4311SfengbojiangThe default is always the current thread. 8188*572c4311Sfengbojiang 8189*572c4311Sfengbojiang 8190*572c4311Sfengbojiang<p> 8191*572c4311Sfengbojiang<hr><h3><a name="pdf-debug.debug"><code>debug.debug ()</code></a></h3> 8192*572c4311Sfengbojiang 8193*572c4311Sfengbojiang 8194*572c4311Sfengbojiang<p> 8195*572c4311SfengbojiangEnters an interactive mode with the user, 8196*572c4311Sfengbojiangrunning each string that the user enters. 8197*572c4311SfengbojiangUsing simple commands and other debug facilities, 8198*572c4311Sfengbojiangthe user can inspect global and local variables, 8199*572c4311Sfengbojiangchange their values, evaluate expressions, and so on. 8200*572c4311SfengbojiangA line containing only the word <code>cont</code> finishes this function, 8201*572c4311Sfengbojiangso that the caller continues its execution. 8202*572c4311Sfengbojiang 8203*572c4311Sfengbojiang 8204*572c4311Sfengbojiang<p> 8205*572c4311SfengbojiangNote that commands for <code>debug.debug</code> are not lexically nested 8206*572c4311Sfengbojiangwithin any function, and so have no direct access to local variables. 8207*572c4311Sfengbojiang 8208*572c4311Sfengbojiang 8209*572c4311Sfengbojiang 8210*572c4311Sfengbojiang 8211*572c4311Sfengbojiang<p> 8212*572c4311Sfengbojiang<hr><h3><a name="pdf-debug.getfenv"><code>debug.getfenv (o)</code></a></h3> 8213*572c4311SfengbojiangReturns the environment of object <code>o</code>. 8214*572c4311Sfengbojiang 8215*572c4311Sfengbojiang 8216*572c4311Sfengbojiang 8217*572c4311Sfengbojiang 8218*572c4311Sfengbojiang<p> 8219*572c4311Sfengbojiang<hr><h3><a name="pdf-debug.gethook"><code>debug.gethook ([thread])</code></a></h3> 8220*572c4311Sfengbojiang 8221*572c4311Sfengbojiang 8222*572c4311Sfengbojiang<p> 8223*572c4311SfengbojiangReturns the current hook settings of the thread, as three values: 8224*572c4311Sfengbojiangthe current hook function, the current hook mask, 8225*572c4311Sfengbojiangand the current hook count 8226*572c4311Sfengbojiang(as set by the <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> function). 8227*572c4311Sfengbojiang 8228*572c4311Sfengbojiang 8229*572c4311Sfengbojiang 8230*572c4311Sfengbojiang 8231*572c4311Sfengbojiang<p> 8232*572c4311Sfengbojiang<hr><h3><a name="pdf-debug.getinfo"><code>debug.getinfo ([thread,] function [, what])</code></a></h3> 8233*572c4311Sfengbojiang 8234*572c4311Sfengbojiang 8235*572c4311Sfengbojiang<p> 8236*572c4311SfengbojiangReturns a table with information about a function. 8237*572c4311SfengbojiangYou can give the function directly, 8238*572c4311Sfengbojiangor you can give a number as the value of <code>function</code>, 8239*572c4311Sfengbojiangwhich means the function running at level <code>function</code> of the call stack 8240*572c4311Sfengbojiangof the given thread: 8241*572c4311Sfengbojianglevel 0 is the current function (<code>getinfo</code> itself); 8242*572c4311Sfengbojianglevel 1 is the function that called <code>getinfo</code>; 8243*572c4311Sfengbojiangand so on. 8244*572c4311SfengbojiangIf <code>function</code> is a number larger than the number of active functions, 8245*572c4311Sfengbojiangthen <code>getinfo</code> returns <b>nil</b>. 8246*572c4311Sfengbojiang 8247*572c4311Sfengbojiang 8248*572c4311Sfengbojiang<p> 8249*572c4311SfengbojiangThe returned table can contain all the fields returned by <a href="#lua_getinfo"><code>lua_getinfo</code></a>, 8250*572c4311Sfengbojiangwith the string <code>what</code> describing which fields to fill in. 8251*572c4311SfengbojiangThe default for <code>what</code> is to get all information available, 8252*572c4311Sfengbojiangexcept the table of valid lines. 8253*572c4311SfengbojiangIf present, 8254*572c4311Sfengbojiangthe option '<code>f</code>' 8255*572c4311Sfengbojiangadds a field named <code>func</code> with the function itself. 8256*572c4311SfengbojiangIf present, 8257*572c4311Sfengbojiangthe option '<code>L</code>' 8258*572c4311Sfengbojiangadds a field named <code>activelines</code> with the table of 8259*572c4311Sfengbojiangvalid lines. 8260*572c4311Sfengbojiang 8261*572c4311Sfengbojiang 8262*572c4311Sfengbojiang<p> 8263*572c4311SfengbojiangFor instance, the expression <code>debug.getinfo(1,"n").name</code> returns 8264*572c4311Sfengbojianga table with a name for the current function, 8265*572c4311Sfengbojiangif a reasonable name can be found, 8266*572c4311Sfengbojiangand the expression <code>debug.getinfo(print)</code> 8267*572c4311Sfengbojiangreturns a table with all available information 8268*572c4311Sfengbojiangabout the <a href="#pdf-print"><code>print</code></a> function. 8269*572c4311Sfengbojiang 8270*572c4311Sfengbojiang 8271*572c4311Sfengbojiang 8272*572c4311Sfengbojiang 8273*572c4311Sfengbojiang<p> 8274*572c4311Sfengbojiang<hr><h3><a name="pdf-debug.getlocal"><code>debug.getlocal ([thread,] level, local)</code></a></h3> 8275*572c4311Sfengbojiang 8276*572c4311Sfengbojiang 8277*572c4311Sfengbojiang<p> 8278*572c4311SfengbojiangThis function returns the name and the value of the local variable 8279*572c4311Sfengbojiangwith index <code>local</code> of the function at level <code>level</code> of the stack. 8280*572c4311Sfengbojiang(The first parameter or local variable has index 1, and so on, 8281*572c4311Sfengbojianguntil the last active local variable.) 8282*572c4311SfengbojiangThe function returns <b>nil</b> if there is no local 8283*572c4311Sfengbojiangvariable with the given index, 8284*572c4311Sfengbojiangand raises an error when called with a <code>level</code> out of range. 8285*572c4311Sfengbojiang(You can call <a href="#pdf-debug.getinfo"><code>debug.getinfo</code></a> to check whether the level is valid.) 8286*572c4311Sfengbojiang 8287*572c4311Sfengbojiang 8288*572c4311Sfengbojiang<p> 8289*572c4311SfengbojiangVariable names starting with '<code>(</code>' (open parentheses) 8290*572c4311Sfengbojiangrepresent internal variables 8291*572c4311Sfengbojiang(loop control variables, temporaries, and C function locals). 8292*572c4311Sfengbojiang 8293*572c4311Sfengbojiang 8294*572c4311Sfengbojiang 8295*572c4311Sfengbojiang 8296*572c4311Sfengbojiang<p> 8297*572c4311Sfengbojiang<hr><h3><a name="pdf-debug.getmetatable"><code>debug.getmetatable (object)</code></a></h3> 8298*572c4311Sfengbojiang 8299*572c4311Sfengbojiang 8300*572c4311Sfengbojiang<p> 8301*572c4311SfengbojiangReturns the metatable of the given <code>object</code> 8302*572c4311Sfengbojiangor <b>nil</b> if it does not have a metatable. 8303*572c4311Sfengbojiang 8304*572c4311Sfengbojiang 8305*572c4311Sfengbojiang 8306*572c4311Sfengbojiang 8307*572c4311Sfengbojiang<p> 8308*572c4311Sfengbojiang<hr><h3><a name="pdf-debug.getregistry"><code>debug.getregistry ()</code></a></h3> 8309*572c4311Sfengbojiang 8310*572c4311Sfengbojiang 8311*572c4311Sfengbojiang<p> 8312*572c4311SfengbojiangReturns the registry table (see <a href="#3.5">§3.5</a>). 8313*572c4311Sfengbojiang 8314*572c4311Sfengbojiang 8315*572c4311Sfengbojiang 8316*572c4311Sfengbojiang 8317*572c4311Sfengbojiang<p> 8318*572c4311Sfengbojiang<hr><h3><a name="pdf-debug.getupvalue"><code>debug.getupvalue (func, up)</code></a></h3> 8319*572c4311Sfengbojiang 8320*572c4311Sfengbojiang 8321*572c4311Sfengbojiang<p> 8322*572c4311SfengbojiangThis function returns the name and the value of the upvalue 8323*572c4311Sfengbojiangwith index <code>up</code> of the function <code>func</code>. 8324*572c4311SfengbojiangThe function returns <b>nil</b> if there is no upvalue with the given index. 8325*572c4311Sfengbojiang 8326*572c4311Sfengbojiang 8327*572c4311Sfengbojiang 8328*572c4311Sfengbojiang 8329*572c4311Sfengbojiang<p> 8330*572c4311Sfengbojiang<hr><h3><a name="pdf-debug.setfenv"><code>debug.setfenv (object, table)</code></a></h3> 8331*572c4311Sfengbojiang 8332*572c4311Sfengbojiang 8333*572c4311Sfengbojiang<p> 8334*572c4311SfengbojiangSets the environment of the given <code>object</code> to the given <code>table</code>. 8335*572c4311SfengbojiangReturns <code>object</code>. 8336*572c4311Sfengbojiang 8337*572c4311Sfengbojiang 8338*572c4311Sfengbojiang 8339*572c4311Sfengbojiang 8340*572c4311Sfengbojiang<p> 8341*572c4311Sfengbojiang<hr><h3><a name="pdf-debug.sethook"><code>debug.sethook ([thread,] hook, mask [, count])</code></a></h3> 8342*572c4311Sfengbojiang 8343*572c4311Sfengbojiang 8344*572c4311Sfengbojiang<p> 8345*572c4311SfengbojiangSets the given function as a hook. 8346*572c4311SfengbojiangThe string <code>mask</code> and the number <code>count</code> describe 8347*572c4311Sfengbojiangwhen the hook will be called. 8348*572c4311SfengbojiangThe string mask may have the following characters, 8349*572c4311Sfengbojiangwith the given meaning: 8350*572c4311Sfengbojiang 8351*572c4311Sfengbojiang<ul> 8352*572c4311Sfengbojiang<li><b><code>"c"</code>:</b> the hook is called every time Lua calls a function;</li> 8353*572c4311Sfengbojiang<li><b><code>"r"</code>:</b> the hook is called every time Lua returns from a function;</li> 8354*572c4311Sfengbojiang<li><b><code>"l"</code>:</b> the hook is called every time Lua enters a new line of code.</li> 8355*572c4311Sfengbojiang</ul><p> 8356*572c4311SfengbojiangWith a <code>count</code> different from zero, 8357*572c4311Sfengbojiangthe hook is called after every <code>count</code> instructions. 8358*572c4311Sfengbojiang 8359*572c4311Sfengbojiang 8360*572c4311Sfengbojiang<p> 8361*572c4311SfengbojiangWhen called without arguments, 8362*572c4311Sfengbojiang<a href="#pdf-debug.sethook"><code>debug.sethook</code></a> turns off the hook. 8363*572c4311Sfengbojiang 8364*572c4311Sfengbojiang 8365*572c4311Sfengbojiang<p> 8366*572c4311SfengbojiangWhen the hook is called, its first parameter is a string 8367*572c4311Sfengbojiangdescribing the event that has triggered its call: 8368*572c4311Sfengbojiang<code>"call"</code>, <code>"return"</code> (or <code>"tail return"</code>, 8369*572c4311Sfengbojiangwhen simulating a return from a tail call), 8370*572c4311Sfengbojiang<code>"line"</code>, and <code>"count"</code>. 8371*572c4311SfengbojiangFor line events, 8372*572c4311Sfengbojiangthe hook also gets the new line number as its second parameter. 8373*572c4311SfengbojiangInside a hook, 8374*572c4311Sfengbojiangyou can call <code>getinfo</code> with level 2 to get more information about 8375*572c4311Sfengbojiangthe running function 8376*572c4311Sfengbojiang(level 0 is the <code>getinfo</code> function, 8377*572c4311Sfengbojiangand level 1 is the hook function), 8378*572c4311Sfengbojiangunless the event is <code>"tail return"</code>. 8379*572c4311SfengbojiangIn this case, Lua is only simulating the return, 8380*572c4311Sfengbojiangand a call to <code>getinfo</code> will return invalid data. 8381*572c4311Sfengbojiang 8382*572c4311Sfengbojiang 8383*572c4311Sfengbojiang 8384*572c4311Sfengbojiang 8385*572c4311Sfengbojiang<p> 8386*572c4311Sfengbojiang<hr><h3><a name="pdf-debug.setlocal"><code>debug.setlocal ([thread,] level, local, value)</code></a></h3> 8387*572c4311Sfengbojiang 8388*572c4311Sfengbojiang 8389*572c4311Sfengbojiang<p> 8390*572c4311SfengbojiangThis function assigns the value <code>value</code> to the local variable 8391*572c4311Sfengbojiangwith index <code>local</code> of the function at level <code>level</code> of the stack. 8392*572c4311SfengbojiangThe function returns <b>nil</b> if there is no local 8393*572c4311Sfengbojiangvariable with the given index, 8394*572c4311Sfengbojiangand raises an error when called with a <code>level</code> out of range. 8395*572c4311Sfengbojiang(You can call <code>getinfo</code> to check whether the level is valid.) 8396*572c4311SfengbojiangOtherwise, it returns the name of the local variable. 8397*572c4311Sfengbojiang 8398*572c4311Sfengbojiang 8399*572c4311Sfengbojiang 8400*572c4311Sfengbojiang 8401*572c4311Sfengbojiang<p> 8402*572c4311Sfengbojiang<hr><h3><a name="pdf-debug.setmetatable"><code>debug.setmetatable (object, table)</code></a></h3> 8403*572c4311Sfengbojiang 8404*572c4311Sfengbojiang 8405*572c4311Sfengbojiang<p> 8406*572c4311SfengbojiangSets the metatable for the given <code>object</code> to the given <code>table</code> 8407*572c4311Sfengbojiang(which can be <b>nil</b>). 8408*572c4311Sfengbojiang 8409*572c4311Sfengbojiang 8410*572c4311Sfengbojiang 8411*572c4311Sfengbojiang 8412*572c4311Sfengbojiang<p> 8413*572c4311Sfengbojiang<hr><h3><a name="pdf-debug.setupvalue"><code>debug.setupvalue (func, up, value)</code></a></h3> 8414*572c4311Sfengbojiang 8415*572c4311Sfengbojiang 8416*572c4311Sfengbojiang<p> 8417*572c4311SfengbojiangThis function assigns the value <code>value</code> to the upvalue 8418*572c4311Sfengbojiangwith index <code>up</code> of the function <code>func</code>. 8419*572c4311SfengbojiangThe function returns <b>nil</b> if there is no upvalue 8420*572c4311Sfengbojiangwith the given index. 8421*572c4311SfengbojiangOtherwise, it returns the name of the upvalue. 8422*572c4311Sfengbojiang 8423*572c4311Sfengbojiang 8424*572c4311Sfengbojiang 8425*572c4311Sfengbojiang 8426*572c4311Sfengbojiang<p> 8427*572c4311Sfengbojiang<hr><h3><a name="pdf-debug.traceback"><code>debug.traceback ([thread,] [message [, level]])</code></a></h3> 8428*572c4311Sfengbojiang 8429*572c4311Sfengbojiang 8430*572c4311Sfengbojiang<p> 8431*572c4311SfengbojiangReturns a string with a traceback of the call stack. 8432*572c4311SfengbojiangAn optional <code>message</code> string is appended 8433*572c4311Sfengbojiangat the beginning of the traceback. 8434*572c4311SfengbojiangAn optional <code>level</code> number tells at which level 8435*572c4311Sfengbojiangto start the traceback 8436*572c4311Sfengbojiang(default is 1, the function calling <code>traceback</code>). 8437*572c4311Sfengbojiang 8438*572c4311Sfengbojiang 8439*572c4311Sfengbojiang 8440*572c4311Sfengbojiang 8441*572c4311Sfengbojiang 8442*572c4311Sfengbojiang 8443*572c4311Sfengbojiang 8444*572c4311Sfengbojiang<h1>6 - <a name="6">Lua Stand-alone</a></h1> 8445*572c4311Sfengbojiang 8446*572c4311Sfengbojiang<p> 8447*572c4311SfengbojiangAlthough Lua has been designed as an extension language, 8448*572c4311Sfengbojiangto be embedded in a host C program, 8449*572c4311Sfengbojiangit is also frequently used as a stand-alone language. 8450*572c4311SfengbojiangAn interpreter for Lua as a stand-alone language, 8451*572c4311Sfengbojiangcalled simply <code>lua</code>, 8452*572c4311Sfengbojiangis provided with the standard distribution. 8453*572c4311SfengbojiangThe stand-alone interpreter includes 8454*572c4311Sfengbojiangall standard libraries, including the debug library. 8455*572c4311SfengbojiangIts usage is: 8456*572c4311Sfengbojiang 8457*572c4311Sfengbojiang<pre> 8458*572c4311Sfengbojiang lua [options] [script [args]] 8459*572c4311Sfengbojiang</pre><p> 8460*572c4311SfengbojiangThe options are: 8461*572c4311Sfengbojiang 8462*572c4311Sfengbojiang<ul> 8463*572c4311Sfengbojiang<li><b><code>-e <em>stat</em></code>:</b> executes string <em>stat</em>;</li> 8464*572c4311Sfengbojiang<li><b><code>-l <em>mod</em></code>:</b> "requires" <em>mod</em>;</li> 8465*572c4311Sfengbojiang<li><b><code>-i</code>:</b> enters interactive mode after running <em>script</em>;</li> 8466*572c4311Sfengbojiang<li><b><code>-v</code>:</b> prints version information;</li> 8467*572c4311Sfengbojiang<li><b><code>--</code>:</b> stops handling options;</li> 8468*572c4311Sfengbojiang<li><b><code>-</code>:</b> executes <code>stdin</code> as a file and stops handling options.</li> 8469*572c4311Sfengbojiang</ul><p> 8470*572c4311SfengbojiangAfter handling its options, <code>lua</code> runs the given <em>script</em>, 8471*572c4311Sfengbojiangpassing to it the given <em>args</em> as string arguments. 8472*572c4311SfengbojiangWhen called without arguments, 8473*572c4311Sfengbojiang<code>lua</code> behaves as <code>lua -v -i</code> 8474*572c4311Sfengbojiangwhen the standard input (<code>stdin</code>) is a terminal, 8475*572c4311Sfengbojiangand as <code>lua -</code> otherwise. 8476*572c4311Sfengbojiang 8477*572c4311Sfengbojiang 8478*572c4311Sfengbojiang<p> 8479*572c4311SfengbojiangBefore running any argument, 8480*572c4311Sfengbojiangthe interpreter checks for an environment variable <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a>. 8481*572c4311SfengbojiangIf its format is <code>@<em>filename</em></code>, 8482*572c4311Sfengbojiangthen <code>lua</code> executes the file. 8483*572c4311SfengbojiangOtherwise, <code>lua</code> executes the string itself. 8484*572c4311Sfengbojiang 8485*572c4311Sfengbojiang 8486*572c4311Sfengbojiang<p> 8487*572c4311SfengbojiangAll options are handled in order, except <code>-i</code>. 8488*572c4311SfengbojiangFor instance, an invocation like 8489*572c4311Sfengbojiang 8490*572c4311Sfengbojiang<pre> 8491*572c4311Sfengbojiang $ lua -e'a=1' -e 'print(a)' script.lua 8492*572c4311Sfengbojiang</pre><p> 8493*572c4311Sfengbojiangwill first set <code>a</code> to 1, then print the value of <code>a</code> (which is '<code>1</code>'), 8494*572c4311Sfengbojiangand finally run the file <code>script.lua</code> with no arguments. 8495*572c4311Sfengbojiang(Here <code>$</code> is the shell prompt. Your prompt may be different.) 8496*572c4311Sfengbojiang 8497*572c4311Sfengbojiang 8498*572c4311Sfengbojiang<p> 8499*572c4311SfengbojiangBefore starting to run the script, 8500*572c4311Sfengbojiang<code>lua</code> collects all arguments in the command line 8501*572c4311Sfengbojiangin a global table called <code>arg</code>. 8502*572c4311SfengbojiangThe script name is stored at index 0, 8503*572c4311Sfengbojiangthe first argument after the script name goes to index 1, 8504*572c4311Sfengbojiangand so on. 8505*572c4311SfengbojiangAny arguments before the script name 8506*572c4311Sfengbojiang(that is, the interpreter name plus the options) 8507*572c4311Sfengbojianggo to negative indices. 8508*572c4311SfengbojiangFor instance, in the call 8509*572c4311Sfengbojiang 8510*572c4311Sfengbojiang<pre> 8511*572c4311Sfengbojiang $ lua -la b.lua t1 t2 8512*572c4311Sfengbojiang</pre><p> 8513*572c4311Sfengbojiangthe interpreter first runs the file <code>a.lua</code>, 8514*572c4311Sfengbojiangthen creates a table 8515*572c4311Sfengbojiang 8516*572c4311Sfengbojiang<pre> 8517*572c4311Sfengbojiang arg = { [-2] = "lua", [-1] = "-la", 8518*572c4311Sfengbojiang [0] = "b.lua", 8519*572c4311Sfengbojiang [1] = "t1", [2] = "t2" } 8520*572c4311Sfengbojiang</pre><p> 8521*572c4311Sfengbojiangand finally runs the file <code>b.lua</code>. 8522*572c4311SfengbojiangThe script is called with <code>arg[1]</code>, <code>arg[2]</code>, ··· 8523*572c4311Sfengbojiangas arguments; 8524*572c4311Sfengbojiangit can also access these arguments with the vararg expression '<code>...</code>'. 8525*572c4311Sfengbojiang 8526*572c4311Sfengbojiang 8527*572c4311Sfengbojiang<p> 8528*572c4311SfengbojiangIn interactive mode, 8529*572c4311Sfengbojiangif you write an incomplete statement, 8530*572c4311Sfengbojiangthe interpreter waits for its completion 8531*572c4311Sfengbojiangby issuing a different prompt. 8532*572c4311Sfengbojiang 8533*572c4311Sfengbojiang 8534*572c4311Sfengbojiang<p> 8535*572c4311SfengbojiangIf the global variable <a name="pdf-_PROMPT"><code>_PROMPT</code></a> contains a string, 8536*572c4311Sfengbojiangthen its value is used as the prompt. 8537*572c4311SfengbojiangSimilarly, if the global variable <a name="pdf-_PROMPT2"><code>_PROMPT2</code></a> contains a string, 8538*572c4311Sfengbojiangits value is used as the secondary prompt 8539*572c4311Sfengbojiang(issued during incomplete statements). 8540*572c4311SfengbojiangTherefore, both prompts can be changed directly on the command line 8541*572c4311Sfengbojiangor in any Lua programs by assigning to <code>_PROMPT</code>. 8542*572c4311SfengbojiangSee the next example: 8543*572c4311Sfengbojiang 8544*572c4311Sfengbojiang<pre> 8545*572c4311Sfengbojiang $ lua -e"_PROMPT='myprompt> '" -i 8546*572c4311Sfengbojiang</pre><p> 8547*572c4311Sfengbojiang(The outer pair of quotes is for the shell, 8548*572c4311Sfengbojiangthe inner pair is for Lua.) 8549*572c4311SfengbojiangNote the use of <code>-i</code> to enter interactive mode; 8550*572c4311Sfengbojiangotherwise, 8551*572c4311Sfengbojiangthe program would just end silently 8552*572c4311Sfengbojiangright after the assignment to <code>_PROMPT</code>. 8553*572c4311Sfengbojiang 8554*572c4311Sfengbojiang 8555*572c4311Sfengbojiang<p> 8556*572c4311SfengbojiangTo allow the use of Lua as a 8557*572c4311Sfengbojiangscript interpreter in Unix systems, 8558*572c4311Sfengbojiangthe stand-alone interpreter skips 8559*572c4311Sfengbojiangthe first line of a chunk if it starts with <code>#</code>. 8560*572c4311SfengbojiangTherefore, Lua scripts can be made into executable programs 8561*572c4311Sfengbojiangby using <code>chmod +x</code> and the <code>#!</code> form, 8562*572c4311Sfengbojiangas in 8563*572c4311Sfengbojiang 8564*572c4311Sfengbojiang<pre> 8565*572c4311Sfengbojiang #!/usr/local/bin/lua 8566*572c4311Sfengbojiang</pre><p> 8567*572c4311Sfengbojiang(Of course, 8568*572c4311Sfengbojiangthe location of the Lua interpreter may be different in your machine. 8569*572c4311SfengbojiangIf <code>lua</code> is in your <code>PATH</code>, 8570*572c4311Sfengbojiangthen 8571*572c4311Sfengbojiang 8572*572c4311Sfengbojiang<pre> 8573*572c4311Sfengbojiang #!/usr/bin/env lua 8574*572c4311Sfengbojiang</pre><p> 8575*572c4311Sfengbojiangis a more portable solution.) 8576*572c4311Sfengbojiang 8577*572c4311Sfengbojiang 8578*572c4311Sfengbojiang 8579*572c4311Sfengbojiang<h1>7 - <a name="7">Incompatibilities with the Previous Version</a></h1> 8580*572c4311Sfengbojiang 8581*572c4311Sfengbojiang<p> 8582*572c4311SfengbojiangHere we list the incompatibilities that you may find when moving a program 8583*572c4311Sfengbojiangfrom Lua 5.0 to Lua 5.1. 8584*572c4311SfengbojiangYou can avoid most of the incompatibilities compiling Lua with 8585*572c4311Sfengbojiangappropriate options (see file <code>luaconf.h</code>). 8586*572c4311SfengbojiangHowever, 8587*572c4311Sfengbojiangall these compatibility options will be removed in the next version of Lua. 8588*572c4311Sfengbojiang 8589*572c4311Sfengbojiang 8590*572c4311Sfengbojiang 8591*572c4311Sfengbojiang<h2>7.1 - <a name="7.1">Changes in the Language</a></h2> 8592*572c4311Sfengbojiang<ul> 8593*572c4311Sfengbojiang 8594*572c4311Sfengbojiang<li> 8595*572c4311SfengbojiangThe vararg system changed from the pseudo-argument <code>arg</code> with a 8596*572c4311Sfengbojiangtable with the extra arguments to the vararg expression. 8597*572c4311Sfengbojiang(See compile-time option <code>LUA_COMPAT_VARARG</code> in <code>luaconf.h</code>.) 8598*572c4311Sfengbojiang</li> 8599*572c4311Sfengbojiang 8600*572c4311Sfengbojiang<li> 8601*572c4311SfengbojiangThere was a subtle change in the scope of the implicit 8602*572c4311Sfengbojiangvariables of the <b>for</b> statement and for the <b>repeat</b> statement. 8603*572c4311Sfengbojiang</li> 8604*572c4311Sfengbojiang 8605*572c4311Sfengbojiang<li> 8606*572c4311SfengbojiangThe long string/long comment syntax (<code>[[<em>string</em>]]</code>) 8607*572c4311Sfengbojiangdoes not allow nesting. 8608*572c4311SfengbojiangYou can use the new syntax (<code>[=[<em>string</em>]=]</code>) in these cases. 8609*572c4311Sfengbojiang(See compile-time option <code>LUA_COMPAT_LSTR</code> in <code>luaconf.h</code>.) 8610*572c4311Sfengbojiang</li> 8611*572c4311Sfengbojiang 8612*572c4311Sfengbojiang</ul> 8613*572c4311Sfengbojiang 8614*572c4311Sfengbojiang 8615*572c4311Sfengbojiang 8616*572c4311Sfengbojiang 8617*572c4311Sfengbojiang<h2>7.2 - <a name="7.2">Changes in the Libraries</a></h2> 8618*572c4311Sfengbojiang<ul> 8619*572c4311Sfengbojiang 8620*572c4311Sfengbojiang<li> 8621*572c4311SfengbojiangFunction <code>string.gfind</code> was renamed <a href="#pdf-string.gmatch"><code>string.gmatch</code></a>. 8622*572c4311Sfengbojiang(See compile-time option <code>LUA_COMPAT_GFIND</code> in <code>luaconf.h</code>.) 8623*572c4311Sfengbojiang</li> 8624*572c4311Sfengbojiang 8625*572c4311Sfengbojiang<li> 8626*572c4311SfengbojiangWhen <a href="#pdf-string.gsub"><code>string.gsub</code></a> is called with a function as its 8627*572c4311Sfengbojiangthird argument, 8628*572c4311Sfengbojiangwhenever this function returns <b>nil</b> or <b>false</b> the 8629*572c4311Sfengbojiangreplacement string is the whole match, 8630*572c4311Sfengbojianginstead of the empty string. 8631*572c4311Sfengbojiang</li> 8632*572c4311Sfengbojiang 8633*572c4311Sfengbojiang<li> 8634*572c4311SfengbojiangFunction <code>table.setn</code> was deprecated. 8635*572c4311SfengbojiangFunction <code>table.getn</code> corresponds 8636*572c4311Sfengbojiangto the new length operator (<code>#</code>); 8637*572c4311Sfengbojianguse the operator instead of the function. 8638*572c4311Sfengbojiang(See compile-time option <code>LUA_COMPAT_GETN</code> in <code>luaconf.h</code>.) 8639*572c4311Sfengbojiang</li> 8640*572c4311Sfengbojiang 8641*572c4311Sfengbojiang<li> 8642*572c4311SfengbojiangFunction <code>loadlib</code> was renamed <a href="#pdf-package.loadlib"><code>package.loadlib</code></a>. 8643*572c4311Sfengbojiang(See compile-time option <code>LUA_COMPAT_LOADLIB</code> in <code>luaconf.h</code>.) 8644*572c4311Sfengbojiang</li> 8645*572c4311Sfengbojiang 8646*572c4311Sfengbojiang<li> 8647*572c4311SfengbojiangFunction <code>math.mod</code> was renamed <a href="#pdf-math.fmod"><code>math.fmod</code></a>. 8648*572c4311Sfengbojiang(See compile-time option <code>LUA_COMPAT_MOD</code> in <code>luaconf.h</code>.) 8649*572c4311Sfengbojiang</li> 8650*572c4311Sfengbojiang 8651*572c4311Sfengbojiang<li> 8652*572c4311SfengbojiangFunctions <code>table.foreach</code> and <code>table.foreachi</code> are deprecated. 8653*572c4311SfengbojiangYou can use a for loop with <code>pairs</code> or <code>ipairs</code> instead. 8654*572c4311Sfengbojiang</li> 8655*572c4311Sfengbojiang 8656*572c4311Sfengbojiang<li> 8657*572c4311SfengbojiangThere were substantial changes in function <a href="#pdf-require"><code>require</code></a> due to 8658*572c4311Sfengbojiangthe new module system. 8659*572c4311SfengbojiangHowever, the new behavior is mostly compatible with the old, 8660*572c4311Sfengbojiangbut <code>require</code> gets the path from <a href="#pdf-package.path"><code>package.path</code></a> instead 8661*572c4311Sfengbojiangof from <code>LUA_PATH</code>. 8662*572c4311Sfengbojiang</li> 8663*572c4311Sfengbojiang 8664*572c4311Sfengbojiang<li> 8665*572c4311SfengbojiangFunction <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> has different arguments. 8666*572c4311SfengbojiangFunction <code>gcinfo</code> is deprecated; 8667*572c4311Sfengbojianguse <code>collectgarbage("count")</code> instead. 8668*572c4311Sfengbojiang</li> 8669*572c4311Sfengbojiang 8670*572c4311Sfengbojiang</ul> 8671*572c4311Sfengbojiang 8672*572c4311Sfengbojiang 8673*572c4311Sfengbojiang 8674*572c4311Sfengbojiang 8675*572c4311Sfengbojiang<h2>7.3 - <a name="7.3">Changes in the API</a></h2> 8676*572c4311Sfengbojiang<ul> 8677*572c4311Sfengbojiang 8678*572c4311Sfengbojiang<li> 8679*572c4311SfengbojiangThe <code>luaopen_*</code> functions (to open libraries) 8680*572c4311Sfengbojiangcannot be called directly, 8681*572c4311Sfengbojianglike a regular C function. 8682*572c4311SfengbojiangThey must be called through Lua, 8683*572c4311Sfengbojianglike a Lua function. 8684*572c4311Sfengbojiang</li> 8685*572c4311Sfengbojiang 8686*572c4311Sfengbojiang<li> 8687*572c4311SfengbojiangFunction <code>lua_open</code> was replaced by <a href="#lua_newstate"><code>lua_newstate</code></a> to 8688*572c4311Sfengbojiangallow the user to set a memory-allocation function. 8689*572c4311SfengbojiangYou can use <a href="#luaL_newstate"><code>luaL_newstate</code></a> from the standard library to 8690*572c4311Sfengbojiangcreate a state with a standard allocation function 8691*572c4311Sfengbojiang(based on <code>realloc</code>). 8692*572c4311Sfengbojiang</li> 8693*572c4311Sfengbojiang 8694*572c4311Sfengbojiang<li> 8695*572c4311SfengbojiangFunctions <code>luaL_getn</code> and <code>luaL_setn</code> 8696*572c4311Sfengbojiang(from the auxiliary library) are deprecated. 8697*572c4311SfengbojiangUse <a href="#lua_objlen"><code>lua_objlen</code></a> instead of <code>luaL_getn</code> 8698*572c4311Sfengbojiangand nothing instead of <code>luaL_setn</code>. 8699*572c4311Sfengbojiang</li> 8700*572c4311Sfengbojiang 8701*572c4311Sfengbojiang<li> 8702*572c4311SfengbojiangFunction <code>luaL_openlib</code> was replaced by <a href="#luaL_register"><code>luaL_register</code></a>. 8703*572c4311Sfengbojiang</li> 8704*572c4311Sfengbojiang 8705*572c4311Sfengbojiang<li> 8706*572c4311SfengbojiangFunction <code>luaL_checkudata</code> now throws an error when the given value 8707*572c4311Sfengbojiangis not a userdata of the expected type. 8708*572c4311Sfengbojiang(In Lua 5.0 it returned <code>NULL</code>.) 8709*572c4311Sfengbojiang</li> 8710*572c4311Sfengbojiang 8711*572c4311Sfengbojiang</ul> 8712*572c4311Sfengbojiang 8713*572c4311Sfengbojiang 8714*572c4311Sfengbojiang 8715*572c4311Sfengbojiang 8716*572c4311Sfengbojiang<h1>8 - <a name="8">The Complete Syntax of Lua</a></h1> 8717*572c4311Sfengbojiang 8718*572c4311Sfengbojiang<p> 8719*572c4311SfengbojiangHere is the complete syntax of Lua in extended BNF. 8720*572c4311Sfengbojiang(It does not describe operator precedences.) 8721*572c4311Sfengbojiang 8722*572c4311Sfengbojiang 8723*572c4311Sfengbojiang 8724*572c4311Sfengbojiang 8725*572c4311Sfengbojiang<pre> 8726*572c4311Sfengbojiang 8727*572c4311Sfengbojiang chunk ::= {stat [`<b>;</b>´]} [laststat [`<b>;</b>´]] 8728*572c4311Sfengbojiang 8729*572c4311Sfengbojiang block ::= chunk 8730*572c4311Sfengbojiang 8731*572c4311Sfengbojiang stat ::= varlist `<b>=</b>´ explist | 8732*572c4311Sfengbojiang functioncall | 8733*572c4311Sfengbojiang <b>do</b> block <b>end</b> | 8734*572c4311Sfengbojiang <b>while</b> exp <b>do</b> block <b>end</b> | 8735*572c4311Sfengbojiang <b>repeat</b> block <b>until</b> exp | 8736*572c4311Sfengbojiang <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> | 8737*572c4311Sfengbojiang <b>for</b> Name `<b>=</b>´ exp `<b>,</b>´ exp [`<b>,</b>´ exp] <b>do</b> block <b>end</b> | 8738*572c4311Sfengbojiang <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> | 8739*572c4311Sfengbojiang <b>function</b> funcname funcbody | 8740*572c4311Sfengbojiang <b>local</b> <b>function</b> Name funcbody | 8741*572c4311Sfengbojiang <b>local</b> namelist [`<b>=</b>´ explist] 8742*572c4311Sfengbojiang 8743*572c4311Sfengbojiang laststat ::= <b>return</b> [explist] | <b>break</b> 8744*572c4311Sfengbojiang 8745*572c4311Sfengbojiang funcname ::= Name {`<b>.</b>´ Name} [`<b>:</b>´ Name] 8746*572c4311Sfengbojiang 8747*572c4311Sfengbojiang varlist ::= var {`<b>,</b>´ var} 8748*572c4311Sfengbojiang 8749*572c4311Sfengbojiang var ::= Name | prefixexp `<b>[</b>´ exp `<b>]</b>´ | prefixexp `<b>.</b>´ Name 8750*572c4311Sfengbojiang 8751*572c4311Sfengbojiang namelist ::= Name {`<b>,</b>´ Name} 8752*572c4311Sfengbojiang 8753*572c4311Sfengbojiang explist ::= {exp `<b>,</b>´} exp 8754*572c4311Sfengbojiang 8755*572c4311Sfengbojiang exp ::= <b>nil</b> | <b>false</b> | <b>true</b> | Number | String | `<b>...</b>´ | function | 8756*572c4311Sfengbojiang prefixexp | tableconstructor | exp binop exp | unop exp 8757*572c4311Sfengbojiang 8758*572c4311Sfengbojiang prefixexp ::= var | functioncall | `<b>(</b>´ exp `<b>)</b>´ 8759*572c4311Sfengbojiang 8760*572c4311Sfengbojiang functioncall ::= prefixexp args | prefixexp `<b>:</b>´ Name args 8761*572c4311Sfengbojiang 8762*572c4311Sfengbojiang args ::= `<b>(</b>´ [explist] `<b>)</b>´ | tableconstructor | String 8763*572c4311Sfengbojiang 8764*572c4311Sfengbojiang function ::= <b>function</b> funcbody 8765*572c4311Sfengbojiang 8766*572c4311Sfengbojiang funcbody ::= `<b>(</b>´ [parlist] `<b>)</b>´ block <b>end</b> 8767*572c4311Sfengbojiang 8768*572c4311Sfengbojiang parlist ::= namelist [`<b>,</b>´ `<b>...</b>´] | `<b>...</b>´ 8769*572c4311Sfengbojiang 8770*572c4311Sfengbojiang tableconstructor ::= `<b>{</b>´ [fieldlist] `<b>}</b>´ 8771*572c4311Sfengbojiang 8772*572c4311Sfengbojiang fieldlist ::= field {fieldsep field} [fieldsep] 8773*572c4311Sfengbojiang 8774*572c4311Sfengbojiang field ::= `<b>[</b>´ exp `<b>]</b>´ `<b>=</b>´ exp | Name `<b>=</b>´ exp | exp 8775*572c4311Sfengbojiang 8776*572c4311Sfengbojiang fieldsep ::= `<b>,</b>´ | `<b>;</b>´ 8777*572c4311Sfengbojiang 8778*572c4311Sfengbojiang binop ::= `<b>+</b>´ | `<b>-</b>´ | `<b>*</b>´ | `<b>/</b>´ | `<b>^</b>´ | `<b>%</b>´ | `<b>..</b>´ | 8779*572c4311Sfengbojiang `<b><</b>´ | `<b><=</b>´ | `<b>></b>´ | `<b>>=</b>´ | `<b>==</b>´ | `<b>~=</b>´ | 8780*572c4311Sfengbojiang <b>and</b> | <b>or</b> 8781*572c4311Sfengbojiang 8782*572c4311Sfengbojiang unop ::= `<b>-</b>´ | <b>not</b> | `<b>#</b>´ 8783*572c4311Sfengbojiang 8784*572c4311Sfengbojiang</pre> 8785*572c4311Sfengbojiang 8786*572c4311Sfengbojiang<p> 8787*572c4311Sfengbojiang 8788*572c4311Sfengbojiang 8789*572c4311Sfengbojiang 8790*572c4311Sfengbojiang 8791*572c4311Sfengbojiang 8792*572c4311Sfengbojiang 8793*572c4311Sfengbojiang 8794*572c4311Sfengbojiang<HR> 8795*572c4311Sfengbojiang<SMALL CLASS="footer"> 8796*572c4311SfengbojiangLast update: 8797*572c4311SfengbojiangMon Feb 13 18:54:19 BRST 2012 8798*572c4311Sfengbojiang</SMALL> 8799*572c4311Sfengbojiang<!-- 8800*572c4311SfengbojiangLast change: revised for Lua 5.1.5 8801*572c4311Sfengbojiang--> 8802*572c4311Sfengbojiang 8803*572c4311Sfengbojiang</body></html> 8804*572c4311Sfengbojiang 8805
