manual.html revision 326344
1280405Srpaulo<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2326344Simp<HTML> 3326344Simp<HEAD> 4326344Simp<TITLE>Lua 5.3 Reference Manual</TITLE> 5326344Simp<LINK REL="stylesheet" TYPE="text/css" HREF="lua.css"> 6326344Simp<LINK REL="stylesheet" TYPE="text/css" HREF="manual.css"> 7280405Srpaulo<META HTTP-EQUIV="content-type" CONTENT="text/html; charset=iso-8859-1"> 8326344Simp</HEAD> 9280405Srpaulo 10326344Simp<BODY> 11280405Srpaulo 12326344Simp<H1> 13326344Simp<A HREF="http://www.lua.org/"><IMG SRC="logo.gif" ALT="Lua"></A> 14280405SrpauloLua 5.3 Reference Manual 15326344Simp</H1> 16280405Srpaulo 17326344Simp<P> 18280405Srpauloby Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes 19326344Simp 20326344Simp<P> 21326344Simp<SMALL> 22326344SimpCopyright © 2015–2017 Lua.org, PUC-Rio. 23280405SrpauloFreely available under the terms of the 24280405Srpaulo<a href="http://www.lua.org/license.html">Lua license</a>. 25326344Simp</SMALL> 26280405Srpaulo 27326344Simp<DIV CLASS="menubar"> 28326344Simp<A HREF="contents.html#contents">contents</A> 29280405Srpaulo· 30326344Simp<A HREF="contents.html#index">index</A> 31326344Simp· 32326344Simp<A HREF="http://www.lua.org/manual/">other versions</A> 33326344Simp</DIV> 34280405Srpaulo 35280405Srpaulo<!-- ====================================================================== --> 36280405Srpaulo<p> 37280405Srpaulo 38326344Simp<!-- $Id: manual.of,v 1.167 2017/01/09 15:18:11 roberto Exp $ --> 39280405Srpaulo 40280405Srpaulo 41280405Srpaulo 42280405Srpaulo 43280405Srpaulo<h1>1 – <a name="1">Introduction</a></h1> 44280405Srpaulo 45280405Srpaulo<p> 46326344SimpLua is a powerful, efficient, lightweight, embeddable scripting language. 47326344SimpIt supports procedural programming, 48326344Simpobject-oriented programming, functional programming, 49326344Simpdata-driven programming, and data description. 50326344Simp 51326344Simp 52326344Simp<p> 53326344SimpLua combines simple procedural syntax with powerful data description 54326344Simpconstructs based on associative arrays and extensible semantics. 55326344SimpLua is dynamically typed, 56326344Simpruns by interpreting bytecode with a register-based 57326344Simpvirtual machine, 58326344Simpand has automatic memory management with 59326344Simpincremental garbage collection, 60326344Simpmaking it ideal for configuration, scripting, 61326344Simpand rapid prototyping. 62326344Simp 63326344Simp 64326344Simp<p> 65280405SrpauloLua is implemented as a library, written in <em>clean C</em>, 66280405Srpaulothe common subset of Standard C and C++. 67326344SimpThe Lua distribution includes a host program called <code>lua</code>, 68326344Simpwhich uses the Lua library to offer a complete, 69326344Simpstandalone Lua interpreter, 70326344Simpfor interactive or batch use. 71326344SimpLua is intended to be used both as a powerful, lightweight, 72326344Simpembeddable scripting language for any program that needs one, 73326344Simpand as a powerful but lightweight and efficient stand-alone language. 74280405Srpaulo 75280405Srpaulo 76280405Srpaulo<p> 77280405SrpauloAs an extension language, Lua has no notion of a "main" program: 78326344Simpit works <em>embedded</em> in a host client, 79280405Srpaulocalled the <em>embedding program</em> or simply the <em>host</em>. 80326344Simp(Frequently, this host is the stand-alone <code>lua</code> program.) 81280405SrpauloThe host program can invoke functions to execute a piece of Lua code, 82280405Srpaulocan write and read Lua variables, 83280405Srpauloand can register C functions to be called by Lua code. 84280405SrpauloThrough the use of C functions, Lua can be augmented to cope with 85280405Srpauloa wide range of different domains, 86280405Srpaulothus creating customized programming languages sharing a syntactical framework. 87280405Srpaulo 88280405Srpaulo 89280405Srpaulo<p> 90280405SrpauloLua is free software, 91280405Srpauloand is provided as usual with no guarantees, 92280405Srpauloas stated in its license. 93280405SrpauloThe implementation described in this manual is available 94280405Srpauloat Lua's official web site, <code>www.lua.org</code>. 95280405Srpaulo 96280405Srpaulo 97280405Srpaulo<p> 98280405SrpauloLike any other reference manual, 99280405Srpaulothis document is dry in places. 100280405SrpauloFor a discussion of the decisions behind the design of Lua, 101280405Srpaulosee the technical papers available at Lua's web site. 102280405SrpauloFor a detailed introduction to programming in Lua, 103280405Srpaulosee Roberto's book, <em>Programming in Lua</em>. 104280405Srpaulo 105280405Srpaulo 106280405Srpaulo 107280405Srpaulo<h1>2 – <a name="2">Basic Concepts</a></h1> 108280405Srpaulo 109280405Srpaulo<p> 110280405SrpauloThis section describes the basic concepts of the language. 111280405Srpaulo 112280405Srpaulo 113280405Srpaulo 114280405Srpaulo<h2>2.1 – <a name="2.1">Values and Types</a></h2> 115280405Srpaulo 116280405Srpaulo<p> 117280405SrpauloLua is a <em>dynamically typed language</em>. 118280405SrpauloThis means that 119280405Srpaulovariables do not have types; only values do. 120280405SrpauloThere are no type definitions in the language. 121280405SrpauloAll values carry their own type. 122280405Srpaulo 123280405Srpaulo 124280405Srpaulo<p> 125280405SrpauloAll values in Lua are <em>first-class values</em>. 126280405SrpauloThis means that all values can be stored in variables, 127280405Srpaulopassed as arguments to other functions, and returned as results. 128280405Srpaulo 129280405Srpaulo 130280405Srpaulo<p> 131280405SrpauloThere are eight basic types in Lua: 132280405Srpaulo<em>nil</em>, <em>boolean</em>, <em>number</em>, 133280405Srpaulo<em>string</em>, <em>function</em>, <em>userdata</em>, 134280405Srpaulo<em>thread</em>, and <em>table</em>. 135326344SimpThe type <em>nil</em> has one single value, <b>nil</b>, 136280405Srpaulowhose main property is to be different from any other value; 137280405Srpauloit usually represents the absence of a useful value. 138326344SimpThe type <em>boolean</em> has two values, <b>false</b> and <b>true</b>. 139280405SrpauloBoth <b>nil</b> and <b>false</b> make a condition false; 140280405Srpauloany other value makes it true. 141326344SimpThe type <em>number</em> represents both 142280405Srpaulointeger numbers and real (floating-point) numbers. 143326344SimpThe type <em>string</em> represents immutable sequences of bytes. 144280405Srpaulo 145280405SrpauloLua is 8-bit clean: 146280405Srpaulostrings can contain any 8-bit value, 147280405Srpauloincluding embedded zeros ('<code>\0</code>'). 148280405SrpauloLua is also encoding-agnostic; 149280405Srpauloit makes no assumptions about the contents of a string. 150280405Srpaulo 151280405Srpaulo 152280405Srpaulo<p> 153280405SrpauloThe type <em>number</em> uses two internal representations, 154326344Simpor two subtypes, 155280405Srpauloone called <em>integer</em> and the other called <em>float</em>. 156280405SrpauloLua has explicit rules about when each representation is used, 157280405Srpaulobut it also converts between them automatically as needed (see <a href="#3.4.3">§3.4.3</a>). 158280405SrpauloTherefore, 159280405Srpaulothe programmer may choose to mostly ignore the difference 160280405Srpaulobetween integers and floats 161280405Srpauloor to assume complete control over the representation of each number. 162280405SrpauloStandard Lua uses 64-bit integers and double-precision (64-bit) floats, 163280405Srpaulobut you can also compile Lua so that it 164280405Srpaulouses 32-bit integers and/or single-precision (32-bit) floats. 165326344SimpThe option with 32 bits for both integers and floats 166280405Srpaulois particularly attractive 167280405Srpaulofor small machines and embedded systems. 168280405Srpaulo(See macro <code>LUA_32BITS</code> in file <code>luaconf.h</code>.) 169280405Srpaulo 170280405Srpaulo 171280405Srpaulo<p> 172280405SrpauloLua can call (and manipulate) functions written in Lua and 173280405Srpaulofunctions written in C (see <a href="#3.4.10">§3.4.10</a>). 174280405SrpauloBoth are represented by the type <em>function</em>. 175280405Srpaulo 176280405Srpaulo 177280405Srpaulo<p> 178280405SrpauloThe type <em>userdata</em> is provided to allow arbitrary C data to 179280405Srpaulobe stored in Lua variables. 180280405SrpauloA userdata value represents a block of raw memory. 181280405SrpauloThere are two kinds of userdata: 182280405Srpaulo<em>full userdata</em>, 183280405Srpaulowhich is an object with a block of memory managed by Lua, 184280405Srpauloand <em>light userdata</em>, 185280405Srpaulowhich is simply a C pointer value. 186280405SrpauloUserdata has no predefined operations in Lua, 187280405Srpauloexcept assignment and identity test. 188280405SrpauloBy using <em>metatables</em>, 189280405Srpaulothe programmer can define operations for full userdata values 190280405Srpaulo(see <a href="#2.4">§2.4</a>). 191280405SrpauloUserdata values cannot be created or modified in Lua, 192280405Srpauloonly through the C API. 193280405SrpauloThis guarantees the integrity of data owned by the host program. 194280405Srpaulo 195280405Srpaulo 196280405Srpaulo<p> 197280405SrpauloThe type <em>thread</em> represents independent threads of execution 198280405Srpauloand it is used to implement coroutines (see <a href="#2.6">§2.6</a>). 199280405SrpauloLua threads are not related to operating-system threads. 200280405SrpauloLua supports coroutines on all systems, 201280405Srpauloeven those that do not support threads natively. 202280405Srpaulo 203280405Srpaulo 204280405Srpaulo<p> 205280405SrpauloThe type <em>table</em> implements associative arrays, 206280405Srpaulothat is, arrays that can be indexed not only with numbers, 207280405Srpaulobut with any Lua value except <b>nil</b> and NaN. 208326344Simp(<em>Not a Number</em> is a special value used to represent 209326344Simpundefined or unrepresentable numerical results, such as <code>0/0</code>.) 210280405SrpauloTables can be <em>heterogeneous</em>; 211280405Srpaulothat is, they can contain values of all types (except <b>nil</b>). 212280405SrpauloAny key with value <b>nil</b> is not considered part of the table. 213280405SrpauloConversely, any key that is not part of a table has 214280405Srpauloan associated value <b>nil</b>. 215280405Srpaulo 216280405Srpaulo 217280405Srpaulo<p> 218280405SrpauloTables are the sole data-structuring mechanism in Lua; 219326344Simpthey can be used to represent ordinary arrays, lists, 220280405Srpaulosymbol tables, sets, records, graphs, trees, etc. 221280405SrpauloTo represent records, Lua uses the field name as an index. 222280405SrpauloThe language supports this representation by 223280405Srpauloproviding <code>a.name</code> as syntactic sugar for <code>a["name"]</code>. 224280405SrpauloThere are several convenient ways to create tables in Lua 225280405Srpaulo(see <a href="#3.4.9">§3.4.9</a>). 226280405Srpaulo 227280405Srpaulo 228280405Srpaulo<p> 229280405SrpauloLike indices, 230280405Srpaulothe values of table fields can be of any type. 231280405SrpauloIn particular, 232280405Srpaulobecause functions are first-class values, 233280405Srpaulotable fields can contain functions. 234280405SrpauloThus tables can also carry <em>methods</em> (see <a href="#3.4.11">§3.4.11</a>). 235280405Srpaulo 236280405Srpaulo 237280405Srpaulo<p> 238280405SrpauloThe indexing of tables follows 239280405Srpaulothe definition of raw equality in the language. 240280405SrpauloThe expressions <code>a[i]</code> and <code>a[j]</code> 241280405Srpaulodenote the same table element 242280405Srpauloif and only if <code>i</code> and <code>j</code> are raw equal 243280405Srpaulo(that is, equal without metamethods). 244280405SrpauloIn particular, floats with integral values 245280405Srpauloare equal to their respective integers 246280405Srpaulo(e.g., <code>1.0 == 1</code>). 247280405SrpauloTo avoid ambiguities, 248280405Srpauloany float with integral value used as a key 249280405Srpaulois converted to its respective integer. 250280405SrpauloFor instance, if you write <code>a[2.0] = true</code>, 251280405Srpaulothe actual key inserted into the table will be the 252280405Srpaulointeger <code>2</code>. 253280405Srpaulo(On the other hand, 254280405Srpaulo2 and "<code>2</code>" are different Lua values and therefore 255280405Srpaulodenote different table entries.) 256280405Srpaulo 257280405Srpaulo 258280405Srpaulo<p> 259280405SrpauloTables, functions, threads, and (full) userdata values are <em>objects</em>: 260280405Srpaulovariables do not actually <em>contain</em> these values, 261280405Srpauloonly <em>references</em> to them. 262280405SrpauloAssignment, parameter passing, and function returns 263280405Srpauloalways manipulate references to such values; 264280405Srpaulothese operations do not imply any kind of copy. 265280405Srpaulo 266280405Srpaulo 267280405Srpaulo<p> 268280405SrpauloThe library function <a href="#pdf-type"><code>type</code></a> returns a string describing the type 269280405Srpauloof a given value (see <a href="#6.1">§6.1</a>). 270280405Srpaulo 271280405Srpaulo 272280405Srpaulo 273280405Srpaulo 274280405Srpaulo 275280405Srpaulo<h2>2.2 – <a name="2.2">Environments and the Global Environment</a></h2> 276280405Srpaulo 277280405Srpaulo<p> 278280405SrpauloAs will be discussed in <a href="#3.2">§3.2</a> and <a href="#3.3.3">§3.3.3</a>, 279280405Srpauloany reference to a free name 280280405Srpaulo(that is, a name not bound to any declaration) <code>var</code> 281280405Srpaulois syntactically translated to <code>_ENV.var</code>. 282280405SrpauloMoreover, every chunk is compiled in the scope of 283280405Srpauloan external local variable named <code>_ENV</code> (see <a href="#3.3.2">§3.3.2</a>), 284280405Srpauloso <code>_ENV</code> itself is never a free name in a chunk. 285280405Srpaulo 286280405Srpaulo 287280405Srpaulo<p> 288280405SrpauloDespite the existence of this external <code>_ENV</code> variable and 289280405Srpaulothe translation of free names, 290280405Srpaulo<code>_ENV</code> is a completely regular name. 291280405SrpauloIn particular, 292280405Srpauloyou can define new variables and parameters with that name. 293280405SrpauloEach reference to a free name uses the <code>_ENV</code> that is 294280405Srpaulovisible at that point in the program, 295280405Srpaulofollowing the usual visibility rules of Lua (see <a href="#3.5">§3.5</a>). 296280405Srpaulo 297280405Srpaulo 298280405Srpaulo<p> 299280405SrpauloAny table used as the value of <code>_ENV</code> is called an <em>environment</em>. 300280405Srpaulo 301280405Srpaulo 302280405Srpaulo<p> 303280405SrpauloLua keeps a distinguished environment called the <em>global environment</em>. 304280405SrpauloThis value is kept at a special index in the C registry (see <a href="#4.5">§4.5</a>). 305280405SrpauloIn Lua, the global variable <a href="#pdf-_G"><code>_G</code></a> is initialized with this same value. 306280405Srpaulo(<a href="#pdf-_G"><code>_G</code></a> is never used internally.) 307280405Srpaulo 308280405Srpaulo 309280405Srpaulo<p> 310280405SrpauloWhen Lua loads a chunk, 311280405Srpaulothe default value for its <code>_ENV</code> upvalue 312280405Srpaulois the global environment (see <a href="#pdf-load"><code>load</code></a>). 313280405SrpauloTherefore, by default, 314280405Srpaulofree names in Lua code refer to entries in the global environment 315280405Srpaulo(and, therefore, they are also called <em>global variables</em>). 316280405SrpauloMoreover, all standard libraries are loaded in the global environment 317280405Srpauloand some functions there operate on that environment. 318280405SrpauloYou can use <a href="#pdf-load"><code>load</code></a> (or <a href="#pdf-loadfile"><code>loadfile</code></a>) 319280405Srpauloto load a chunk with a different environment. 320280405Srpaulo(In C, you have to load the chunk and then change the value 321280405Srpauloof its first upvalue.) 322280405Srpaulo 323280405Srpaulo 324280405Srpaulo 325280405Srpaulo 326280405Srpaulo 327280405Srpaulo<h2>2.3 – <a name="2.3">Error Handling</a></h2> 328280405Srpaulo 329280405Srpaulo<p> 330280405SrpauloBecause Lua is an embedded extension language, 331280405Srpauloall Lua actions start from C code in the host program 332280405Srpaulocalling a function from the Lua library. 333280405Srpaulo(When you use Lua standalone, 334280405Srpaulothe <code>lua</code> application is the host program.) 335280405SrpauloWhenever an error occurs during 336280405Srpaulothe compilation or execution of a Lua chunk, 337280405Srpaulocontrol returns to the host, 338280405Srpaulowhich can take appropriate measures 339280405Srpaulo(such as printing an error message). 340280405Srpaulo 341280405Srpaulo 342280405Srpaulo<p> 343280405SrpauloLua code can explicitly generate an error by calling the 344280405Srpaulo<a href="#pdf-error"><code>error</code></a> function. 345280405SrpauloIf you need to catch errors in Lua, 346280405Srpauloyou can use <a href="#pdf-pcall"><code>pcall</code></a> or <a href="#pdf-xpcall"><code>xpcall</code></a> 347280405Srpauloto call a given function in <em>protected mode</em>. 348280405Srpaulo 349280405Srpaulo 350280405Srpaulo<p> 351280405SrpauloWhenever there is an error, 352280405Srpauloan <em>error object</em> (also called an <em>error message</em>) 353280405Srpaulois propagated with information about the error. 354280405SrpauloLua itself only generates errors whose error object is a string, 355280405Srpaulobut programs may generate errors with 356280405Srpauloany value as the error object. 357280405SrpauloIt is up to the Lua program or its host to handle such error objects. 358280405Srpaulo 359280405Srpaulo 360280405Srpaulo<p> 361280405SrpauloWhen you use <a href="#pdf-xpcall"><code>xpcall</code></a> or <a href="#lua_pcall"><code>lua_pcall</code></a>, 362280405Srpauloyou may give a <em>message handler</em> 363280405Srpauloto be called in case of errors. 364326344SimpThis function is called with the original error object 365326344Simpand returns a new error object. 366280405SrpauloIt is called before the error unwinds the stack, 367280405Srpauloso that it can gather more information about the error, 368280405Srpaulofor instance by inspecting the stack and creating a stack traceback. 369280405SrpauloThis message handler is still protected by the protected call; 370280405Srpauloso, an error inside the message handler 371280405Srpaulowill call the message handler again. 372280405SrpauloIf this loop goes on for too long, 373280405SrpauloLua breaks it and returns an appropriate message. 374326344Simp(The message handler is called only for regular runtime errors. 375326344SimpIt is not called for memory-allocation errors 376326344Simpnor for errors while running finalizers.) 377280405Srpaulo 378280405Srpaulo 379280405Srpaulo 380280405Srpaulo 381280405Srpaulo 382280405Srpaulo<h2>2.4 – <a name="2.4">Metatables and Metamethods</a></h2> 383280405Srpaulo 384280405Srpaulo<p> 385280405SrpauloEvery value in Lua can have a <em>metatable</em>. 386280405SrpauloThis <em>metatable</em> is an ordinary Lua table 387280405Srpaulothat defines the behavior of the original value 388280405Srpaulounder certain special operations. 389280405SrpauloYou can change several aspects of the behavior 390280405Srpauloof operations over a value by setting specific fields in its metatable. 391280405SrpauloFor instance, when a non-numeric value is the operand of an addition, 392280405SrpauloLua checks for a function in the field "<code>__add</code>" of the value's metatable. 393280405SrpauloIf it finds one, 394280405SrpauloLua calls this function to perform the addition. 395280405Srpaulo 396280405Srpaulo 397280405Srpaulo<p> 398326344SimpThe key for each event in a metatable is a string 399326344Simpwith the event name prefixed by two underscores; 400280405Srpaulothe corresponding values are called <em>metamethods</em>. 401326344SimpIn the previous example, the key is "<code>__add</code>" 402280405Srpauloand the metamethod is the function that performs the addition. 403280405Srpaulo 404280405Srpaulo 405280405Srpaulo<p> 406280405SrpauloYou can query the metatable of any value 407280405Srpaulousing the <a href="#pdf-getmetatable"><code>getmetatable</code></a> function. 408326344SimpLua queries metamethods in metatables using a raw access (see <a href="#pdf-rawget"><code>rawget</code></a>). 409326344SimpSo, to retrieve the metamethod for event <code>ev</code> in object <code>o</code>, 410326344SimpLua does the equivalent to the following code: 411280405Srpaulo 412326344Simp<pre> 413326344Simp rawget(getmetatable(<em>o</em>) or {}, "__<em>ev</em>") 414326344Simp</pre> 415280405Srpaulo 416280405Srpaulo<p> 417280405SrpauloYou can replace the metatable of tables 418280405Srpaulousing the <a href="#pdf-setmetatable"><code>setmetatable</code></a> function. 419326344SimpYou cannot change the metatable of other types from Lua code 420280405Srpaulo(except by using the debug library (<a href="#6.10">§6.10</a>)); 421326344Simpyou should use the C API for that. 422280405Srpaulo 423280405Srpaulo 424280405Srpaulo<p> 425280405SrpauloTables and full userdata have individual metatables 426280405Srpaulo(although multiple tables and userdata can share their metatables). 427280405SrpauloValues of all other types share one single metatable per type; 428280405Srpaulothat is, there is one single metatable for all numbers, 429280405Srpauloone for all strings, etc. 430280405SrpauloBy default, a value has no metatable, 431280405Srpaulobut the string library sets a metatable for the string type (see <a href="#6.4">§6.4</a>). 432280405Srpaulo 433280405Srpaulo 434280405Srpaulo<p> 435280405SrpauloA metatable controls how an object behaves in 436280405Srpauloarithmetic operations, bitwise operations, 437280405Srpauloorder comparisons, concatenation, length operation, calls, and indexing. 438280405SrpauloA metatable also can define a function to be called 439280405Srpaulowhen a userdata or a table is garbage collected (<a href="#2.5">§2.5</a>). 440280405Srpaulo 441280405Srpaulo 442280405Srpaulo<p> 443326344SimpFor the unary operators (negation, length, and bitwise NOT), 444280405Srpaulothe metamethod is computed and called with a dummy second operand, 445280405Srpauloequal to the first one. 446280405SrpauloThis extra operand is only to simplify Lua's internals 447280405Srpaulo(by making these operators behave like a binary operation) 448280405Srpauloand may be removed in future versions. 449280405Srpaulo(For most uses this extra operand is irrelevant.) 450280405Srpaulo 451280405Srpaulo 452326344Simp<p> 453326344SimpA detailed list of events controlled by metatables is given next. 454326344SimpEach operation is identified by its corresponding key. 455280405Srpaulo 456326344Simp 457326344Simp 458280405Srpaulo<ul> 459280405Srpaulo 460326344Simp<li><b><code>__add</code>: </b> 461326344Simpthe addition (<code>+</code>) operation. 462280405SrpauloIf any operand for an addition is not a number 463280405Srpaulo(nor a string coercible to a number), 464280405SrpauloLua will try to call a metamethod. 465280405SrpauloFirst, Lua will check the first operand (even if it is valid). 466326344SimpIf that operand does not define a metamethod for <code>__add</code>, 467280405Srpaulothen Lua will check the second operand. 468280405SrpauloIf Lua can find a metamethod, 469280405Srpauloit calls the metamethod with the two operands as arguments, 470280405Srpauloand the result of the call 471280405Srpaulo(adjusted to one value) 472280405Srpaulois the result of the operation. 473280405SrpauloOtherwise, 474280405Srpauloit raises an error. 475280405Srpaulo</li> 476280405Srpaulo 477326344Simp<li><b><code>__sub</code>: </b> 478326344Simpthe subtraction (<code>-</code>) operation. 479326344SimpBehavior similar to the addition operation. 480280405Srpaulo</li> 481280405Srpaulo 482326344Simp<li><b><code>__mul</code>: </b> 483326344Simpthe multiplication (<code>*</code>) operation. 484326344SimpBehavior similar to the addition operation. 485280405Srpaulo</li> 486280405Srpaulo 487326344Simp<li><b><code>__div</code>: </b> 488326344Simpthe division (<code>/</code>) operation. 489326344SimpBehavior similar to the addition operation. 490280405Srpaulo</li> 491280405Srpaulo 492326344Simp<li><b><code>__mod</code>: </b> 493326344Simpthe modulo (<code>%</code>) operation. 494326344SimpBehavior similar to the addition operation. 495280405Srpaulo</li> 496280405Srpaulo 497326344Simp<li><b><code>__pow</code>: </b> 498326344Simpthe exponentiation (<code>^</code>) operation. 499326344SimpBehavior similar to the addition operation. 500280405Srpaulo</li> 501280405Srpaulo 502326344Simp<li><b><code>__unm</code>: </b> 503326344Simpthe negation (unary <code>-</code>) operation. 504326344SimpBehavior similar to the addition operation. 505280405Srpaulo</li> 506280405Srpaulo 507326344Simp<li><b><code>__idiv</code>: </b> 508326344Simpthe floor division (<code>//</code>) operation. 509326344SimpBehavior similar to the addition operation. 510280405Srpaulo</li> 511280405Srpaulo 512326344Simp<li><b><code>__band</code>: </b> 513326344Simpthe bitwise AND (<code>&</code>) operation. 514326344SimpBehavior similar to the addition operation, 515280405Srpauloexcept that Lua will try a metamethod 516326344Simpif any operand is neither an integer 517280405Srpaulonor a value coercible to an integer (see <a href="#3.4.3">§3.4.3</a>). 518280405Srpaulo</li> 519280405Srpaulo 520326344Simp<li><b><code>__bor</code>: </b> 521326344Simpthe bitwise OR (<code>|</code>) operation. 522326344SimpBehavior similar to the bitwise AND operation. 523280405Srpaulo</li> 524280405Srpaulo 525326344Simp<li><b><code>__bxor</code>: </b> 526326344Simpthe bitwise exclusive OR (binary <code>~</code>) operation. 527326344SimpBehavior similar to the bitwise AND operation. 528280405Srpaulo</li> 529280405Srpaulo 530326344Simp<li><b><code>__bnot</code>: </b> 531326344Simpthe bitwise NOT (unary <code>~</code>) operation. 532326344SimpBehavior similar to the bitwise AND operation. 533280405Srpaulo</li> 534280405Srpaulo 535326344Simp<li><b><code>__shl</code>: </b> 536326344Simpthe bitwise left shift (<code><<</code>) operation. 537326344SimpBehavior similar to the bitwise AND operation. 538280405Srpaulo</li> 539280405Srpaulo 540326344Simp<li><b><code>__shr</code>: </b> 541326344Simpthe bitwise right shift (<code>>></code>) operation. 542326344SimpBehavior similar to the bitwise AND operation. 543280405Srpaulo</li> 544280405Srpaulo 545326344Simp<li><b><code>__concat</code>: </b> 546326344Simpthe concatenation (<code>..</code>) operation. 547326344SimpBehavior similar to the addition operation, 548280405Srpauloexcept that Lua will try a metamethod 549326344Simpif any operand is neither a string nor a number 550280405Srpaulo(which is always coercible to a string). 551280405Srpaulo</li> 552280405Srpaulo 553326344Simp<li><b><code>__len</code>: </b> 554326344Simpthe length (<code>#</code>) operation. 555280405SrpauloIf the object is not a string, 556280405SrpauloLua will try its metamethod. 557280405SrpauloIf there is a metamethod, 558280405SrpauloLua calls it with the object as argument, 559280405Srpauloand the result of the call 560280405Srpaulo(always adjusted to one value) 561280405Srpaulois the result of the operation. 562280405SrpauloIf there is no metamethod but the object is a table, 563280405Srpaulothen Lua uses the table length operation (see <a href="#3.4.7">§3.4.7</a>). 564280405SrpauloOtherwise, Lua raises an error. 565280405Srpaulo</li> 566280405Srpaulo 567326344Simp<li><b><code>__eq</code>: </b> 568326344Simpthe equal (<code>==</code>) operation. 569326344SimpBehavior similar to the addition operation, 570280405Srpauloexcept that Lua will try a metamethod only when the values 571280405Srpaulobeing compared are either both tables or both full userdata 572280405Srpauloand they are not primitively equal. 573280405SrpauloThe result of the call is always converted to a boolean. 574280405Srpaulo</li> 575280405Srpaulo 576326344Simp<li><b><code>__lt</code>: </b> 577326344Simpthe less than (<code><</code>) operation. 578326344SimpBehavior similar to the addition operation, 579280405Srpauloexcept that Lua will try a metamethod only when the values 580280405Srpaulobeing compared are neither both numbers nor both strings. 581280405SrpauloThe result of the call is always converted to a boolean. 582280405Srpaulo</li> 583280405Srpaulo 584326344Simp<li><b><code>__le</code>: </b> 585326344Simpthe less equal (<code><=</code>) operation. 586280405SrpauloUnlike other operations, 587326344Simpthe less-equal operation can use two different events. 588326344SimpFirst, Lua looks for the <code>__le</code> metamethod in both operands, 589326344Simplike in the less than operation. 590280405SrpauloIf it cannot find such a metamethod, 591326344Simpthen it will try the <code>__lt</code> metamethod, 592280405Srpauloassuming that <code>a <= b</code> is equivalent to <code>not (b < a)</code>. 593280405SrpauloAs with the other comparison operators, 594280405Srpaulothe result is always a boolean. 595326344Simp(This use of the <code>__lt</code> event can be removed in future versions; 596326344Simpit is also slower than a real <code>__le</code> metamethod.) 597280405Srpaulo</li> 598280405Srpaulo 599326344Simp<li><b><code>__index</code>: </b> 600280405SrpauloThe indexing access <code>table[key]</code>. 601280405SrpauloThis event happens when <code>table</code> is not a table or 602280405Srpaulowhen <code>key</code> is not present in <code>table</code>. 603280405SrpauloThe metamethod is looked up in <code>table</code>. 604280405Srpaulo 605280405Srpaulo 606280405Srpaulo<p> 607280405SrpauloDespite the name, 608280405Srpaulothe metamethod for this event can be either a function or a table. 609280405SrpauloIf it is a function, 610326344Simpit is called with <code>table</code> and <code>key</code> as arguments, 611326344Simpand the result of the call 612326344Simp(adjusted to one value) 613326344Simpis the result of the operation. 614280405SrpauloIf it is a table, 615280405Srpaulothe final result is the result of indexing this table with <code>key</code>. 616280405Srpaulo(This indexing is regular, not raw, 617280405Srpauloand therefore can trigger another metamethod.) 618280405Srpaulo</li> 619280405Srpaulo 620326344Simp<li><b><code>__newindex</code>: </b> 621280405SrpauloThe indexing assignment <code>table[key] = value</code>. 622280405SrpauloLike the index event, 623280405Srpaulothis event happens when <code>table</code> is not a table or 624280405Srpaulowhen <code>key</code> is not present in <code>table</code>. 625280405SrpauloThe metamethod is looked up in <code>table</code>. 626280405Srpaulo 627280405Srpaulo 628280405Srpaulo<p> 629280405SrpauloLike with indexing, 630280405Srpaulothe metamethod for this event can be either a function or a table. 631280405SrpauloIf it is a function, 632280405Srpauloit is called with <code>table</code>, <code>key</code>, and <code>value</code> as arguments. 633280405SrpauloIf it is a table, 634280405SrpauloLua does an indexing assignment to this table with the same key and value. 635280405Srpaulo(This assignment is regular, not raw, 636280405Srpauloand therefore can trigger another metamethod.) 637280405Srpaulo 638280405Srpaulo 639280405Srpaulo<p> 640326344SimpWhenever there is a <code>__newindex</code> metamethod, 641280405SrpauloLua does not perform the primitive assignment. 642280405Srpaulo(If necessary, 643280405Srpaulothe metamethod itself can call <a href="#pdf-rawset"><code>rawset</code></a> 644280405Srpauloto do the assignment.) 645280405Srpaulo</li> 646280405Srpaulo 647326344Simp<li><b><code>__call</code>: </b> 648280405SrpauloThe call operation <code>func(args)</code>. 649280405SrpauloThis event happens when Lua tries to call a non-function value 650280405Srpaulo(that is, <code>func</code> is not a function). 651280405SrpauloThe metamethod is looked up in <code>func</code>. 652280405SrpauloIf present, 653280405Srpaulothe metamethod is called with <code>func</code> as its first argument, 654280405Srpaulofollowed by the arguments of the original call (<code>args</code>). 655326344SimpAll results of the call 656326344Simpare the result of the operation. 657326344Simp(This is the only metamethod that allows multiple results.) 658280405Srpaulo</li> 659280405Srpaulo 660280405Srpaulo</ul> 661280405Srpaulo 662326344Simp<p> 663326344SimpIt is a good practice to add all needed metamethods to a table 664326344Simpbefore setting it as a metatable of some object. 665326344SimpIn particular, the <code>__gc</code> metamethod works only when this order 666326344Simpis followed (see <a href="#2.5.1">§2.5.1</a>). 667280405Srpaulo 668280405Srpaulo 669326344Simp<p> 670326344SimpBecause metatables are regular tables, 671326344Simpthey can contain arbitrary fields, 672326344Simpnot only the event names defined above. 673326344SimpSome functions in the standard library 674326344Simp(e.g., <a href="#pdf-tostring"><code>tostring</code></a>) 675326344Simpuse other fields in metatables for their own purposes. 676280405Srpaulo 677326344Simp 678326344Simp 679326344Simp 680326344Simp 681280405Srpaulo<h2>2.5 – <a name="2.5">Garbage Collection</a></h2> 682280405Srpaulo 683280405Srpaulo<p> 684280405SrpauloLua performs automatic memory management. 685280405SrpauloThis means that 686280405Srpauloyou do not have to worry about allocating memory for new objects 687280405Srpauloor freeing it when the objects are no longer needed. 688280405SrpauloLua manages memory automatically by running 689280405Srpauloa <em>garbage collector</em> to collect all <em>dead objects</em> 690280405Srpaulo(that is, objects that are no longer accessible from Lua). 691280405SrpauloAll memory used by Lua is subject to automatic management: 692280405Srpaulostrings, tables, userdata, functions, threads, internal structures, etc. 693280405Srpaulo 694280405Srpaulo 695280405Srpaulo<p> 696280405SrpauloLua implements an incremental mark-and-sweep collector. 697280405SrpauloIt uses two numbers to control its garbage-collection cycles: 698280405Srpaulothe <em>garbage-collector pause</em> and 699280405Srpaulothe <em>garbage-collector step multiplier</em>. 700280405SrpauloBoth use percentage points as units 701280405Srpaulo(e.g., a value of 100 means an internal value of 1). 702280405Srpaulo 703280405Srpaulo 704280405Srpaulo<p> 705280405SrpauloThe garbage-collector pause 706280405Srpaulocontrols how long the collector waits before starting a new cycle. 707280405SrpauloLarger values make the collector less aggressive. 708280405SrpauloValues smaller than 100 mean the collector will not wait to 709280405Srpaulostart a new cycle. 710280405SrpauloA value of 200 means that the collector waits for the total memory in use 711280405Srpauloto double before starting a new cycle. 712280405Srpaulo 713280405Srpaulo 714280405Srpaulo<p> 715280405SrpauloThe garbage-collector step multiplier 716280405Srpaulocontrols the relative speed of the collector relative to 717280405Srpaulomemory allocation. 718280405SrpauloLarger values make the collector more aggressive but also increase 719280405Srpaulothe size of each incremental step. 720280405SrpauloYou should not use values smaller than 100, 721280405Srpaulobecause they make the collector too slow and 722280405Srpaulocan result in the collector never finishing a cycle. 723280405SrpauloThe default is 200, 724280405Srpaulowhich means that the collector runs at "twice" 725280405Srpaulothe speed of memory allocation. 726280405Srpaulo 727280405Srpaulo 728280405Srpaulo<p> 729280405SrpauloIf you set the step multiplier to a very large number 730280405Srpaulo(larger than 10% of the maximum number of 731280405Srpaulobytes that the program may use), 732280405Srpaulothe collector behaves like a stop-the-world collector. 733280405SrpauloIf you then set the pause to 200, 734280405Srpaulothe collector behaves as in old Lua versions, 735280405Srpaulodoing a complete collection every time Lua doubles its 736280405Srpaulomemory usage. 737280405Srpaulo 738280405Srpaulo 739280405Srpaulo<p> 740280405SrpauloYou can change these numbers by calling <a href="#lua_gc"><code>lua_gc</code></a> in C 741280405Srpauloor <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> in Lua. 742280405SrpauloYou can also use these functions to control 743280405Srpaulothe collector directly (e.g., stop and restart it). 744280405Srpaulo 745280405Srpaulo 746280405Srpaulo 747280405Srpaulo<h3>2.5.1 – <a name="2.5.1">Garbage-Collection Metamethods</a></h3> 748280405Srpaulo 749280405Srpaulo<p> 750280405SrpauloYou can set garbage-collector metamethods for tables 751280405Srpauloand, using the C API, 752280405Srpaulofor full userdata (see <a href="#2.4">§2.4</a>). 753280405SrpauloThese metamethods are also called <em>finalizers</em>. 754280405SrpauloFinalizers allow you to coordinate Lua's garbage collection 755280405Srpaulowith external resource management 756280405Srpaulo(such as closing files, network or database connections, 757280405Srpauloor freeing your own memory). 758280405Srpaulo 759280405Srpaulo 760280405Srpaulo<p> 761280405SrpauloFor an object (table or userdata) to be finalized when collected, 762280405Srpauloyou must <em>mark</em> it for finalization. 763280405Srpaulo 764280405SrpauloYou mark an object for finalization when you set its metatable 765280405Srpauloand the metatable has a field indexed by the string "<code>__gc</code>". 766280405SrpauloNote that if you set a metatable without a <code>__gc</code> field 767280405Srpauloand later create that field in the metatable, 768280405Srpaulothe object will not be marked for finalization. 769280405Srpaulo 770280405Srpaulo 771280405Srpaulo<p> 772280405SrpauloWhen a marked object becomes garbage, 773280405Srpauloit is not collected immediately by the garbage collector. 774280405SrpauloInstead, Lua puts it in a list. 775280405SrpauloAfter the collection, 776280405SrpauloLua goes through that list. 777280405SrpauloFor each object in the list, 778280405Srpauloit checks the object's <code>__gc</code> metamethod: 779280405SrpauloIf it is a function, 780280405SrpauloLua calls it with the object as its single argument; 781280405Srpauloif the metamethod is not a function, 782280405SrpauloLua simply ignores it. 783280405Srpaulo 784280405Srpaulo 785280405Srpaulo<p> 786280405SrpauloAt the end of each garbage-collection cycle, 787280405Srpaulothe finalizers for objects are called in 788280405Srpaulothe reverse order that the objects were marked for finalization, 789280405Srpauloamong those collected in that cycle; 790280405Srpaulothat is, the first finalizer to be called is the one associated 791280405Srpaulowith the object marked last in the program. 792280405SrpauloThe execution of each finalizer may occur at any point during 793280405Srpaulothe execution of the regular code. 794280405Srpaulo 795280405Srpaulo 796280405Srpaulo<p> 797280405SrpauloBecause the object being collected must still be used by the finalizer, 798280405Srpaulothat object (and other objects accessible only through it) 799280405Srpaulomust be <em>resurrected</em> by Lua. 800280405SrpauloUsually, this resurrection is transient, 801280405Srpauloand the object memory is freed in the next garbage-collection cycle. 802280405SrpauloHowever, if the finalizer stores the object in some global place 803280405Srpaulo(e.g., a global variable), 804280405Srpaulothen the resurrection is permanent. 805280405SrpauloMoreover, if the finalizer marks a finalizing object for finalization again, 806280405Srpauloits finalizer will be called again in the next cycle where the 807280405Srpauloobject is unreachable. 808280405SrpauloIn any case, 809326344Simpthe object memory is freed only in a GC cycle where 810280405Srpaulothe object is unreachable and not marked for finalization. 811280405Srpaulo 812280405Srpaulo 813280405Srpaulo<p> 814280405SrpauloWhen you close a state (see <a href="#lua_close"><code>lua_close</code></a>), 815280405SrpauloLua calls the finalizers of all objects marked for finalization, 816280405Srpaulofollowing the reverse order that they were marked. 817280405SrpauloIf any finalizer marks objects for collection during that phase, 818280405Srpaulothese marks have no effect. 819280405Srpaulo 820280405Srpaulo 821280405Srpaulo 822280405Srpaulo 823280405Srpaulo 824280405Srpaulo<h3>2.5.2 – <a name="2.5.2">Weak Tables</a></h3> 825280405Srpaulo 826280405Srpaulo<p> 827280405SrpauloA <em>weak table</em> is a table whose elements are 828280405Srpaulo<em>weak references</em>. 829280405SrpauloA weak reference is ignored by the garbage collector. 830280405SrpauloIn other words, 831280405Srpauloif the only references to an object are weak references, 832280405Srpaulothen the garbage collector will collect that object. 833280405Srpaulo 834280405Srpaulo 835280405Srpaulo<p> 836280405SrpauloA weak table can have weak keys, weak values, or both. 837326344SimpA table with weak values allows the collection of its values, 838326344Simpbut prevents the collection of its keys. 839280405SrpauloA table with both weak keys and weak values allows the collection of 840280405Srpauloboth keys and values. 841280405SrpauloIn any case, if either the key or the value is collected, 842280405Srpaulothe whole pair is removed from the table. 843280405SrpauloThe weakness of a table is controlled by the 844280405Srpaulo<code>__mode</code> field of its metatable. 845280405SrpauloIf the <code>__mode</code> field is a string containing the character '<code>k</code>', 846280405Srpaulothe keys in the table are weak. 847280405SrpauloIf <code>__mode</code> contains '<code>v</code>', 848280405Srpaulothe values in the table are weak. 849280405Srpaulo 850280405Srpaulo 851280405Srpaulo<p> 852280405SrpauloA table with weak keys and strong values 853280405Srpaulois also called an <em>ephemeron table</em>. 854280405SrpauloIn an ephemeron table, 855280405Srpauloa value is considered reachable only if its key is reachable. 856280405SrpauloIn particular, 857280405Srpauloif the only reference to a key comes through its value, 858280405Srpaulothe pair is removed. 859280405Srpaulo 860280405Srpaulo 861280405Srpaulo<p> 862280405SrpauloAny change in the weakness of a table may take effect only 863280405Srpauloat the next collect cycle. 864280405SrpauloIn particular, if you change the weakness to a stronger mode, 865280405SrpauloLua may still collect some items from that table 866280405Srpaulobefore the change takes effect. 867280405Srpaulo 868280405Srpaulo 869280405Srpaulo<p> 870280405SrpauloOnly objects that have an explicit construction 871280405Srpauloare removed from weak tables. 872326344SimpValues, such as numbers and light C functions, 873280405Srpauloare not subject to garbage collection, 874280405Srpauloand therefore are not removed from weak tables 875280405Srpaulo(unless their associated values are collected). 876280405SrpauloAlthough strings are subject to garbage collection, 877280405Srpaulothey do not have an explicit construction, 878280405Srpauloand therefore are not removed from weak tables. 879280405Srpaulo 880280405Srpaulo 881280405Srpaulo<p> 882280405SrpauloResurrected objects 883280405Srpaulo(that is, objects being finalized 884280405Srpauloand objects accessible only through objects being finalized) 885280405Srpaulohave a special behavior in weak tables. 886280405SrpauloThey are removed from weak values before running their finalizers, 887280405Srpaulobut are removed from weak keys only in the next collection 888280405Srpauloafter running their finalizers, when such objects are actually freed. 889280405SrpauloThis behavior allows the finalizer to access properties 890280405Srpauloassociated with the object through weak tables. 891280405Srpaulo 892280405Srpaulo 893280405Srpaulo<p> 894280405SrpauloIf a weak table is among the resurrected objects in a collection cycle, 895280405Srpauloit may not be properly cleared until the next cycle. 896280405Srpaulo 897280405Srpaulo 898280405Srpaulo 899280405Srpaulo 900280405Srpaulo 901280405Srpaulo 902280405Srpaulo 903280405Srpaulo<h2>2.6 – <a name="2.6">Coroutines</a></h2> 904280405Srpaulo 905280405Srpaulo<p> 906280405SrpauloLua supports coroutines, 907280405Srpauloalso called <em>collaborative multithreading</em>. 908280405SrpauloA coroutine in Lua represents an independent thread of execution. 909280405SrpauloUnlike threads in multithread systems, however, 910280405Srpauloa coroutine only suspends its execution by explicitly calling 911280405Srpauloa yield function. 912280405Srpaulo 913280405Srpaulo 914280405Srpaulo<p> 915280405SrpauloYou create a coroutine by calling <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>. 916280405SrpauloIts sole argument is a function 917280405Srpaulothat is the main function of the coroutine. 918280405SrpauloThe <code>create</code> function only creates a new coroutine and 919280405Srpauloreturns a handle to it (an object of type <em>thread</em>); 920280405Srpauloit does not start the coroutine. 921280405Srpaulo 922280405Srpaulo 923280405Srpaulo<p> 924280405SrpauloYou execute a coroutine by calling <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. 925280405SrpauloWhen you first call <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>, 926280405Srpaulopassing as its first argument 927280405Srpauloa thread returned by <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>, 928326344Simpthe coroutine starts its execution by 929326344Simpcalling its main function. 930280405SrpauloExtra arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> are passed 931326344Simpas arguments to that function. 932280405SrpauloAfter the coroutine starts running, 933280405Srpauloit runs until it terminates or <em>yields</em>. 934280405Srpaulo 935280405Srpaulo 936280405Srpaulo<p> 937280405SrpauloA coroutine can terminate its execution in two ways: 938280405Srpaulonormally, when its main function returns 939280405Srpaulo(explicitly or implicitly, after the last instruction); 940280405Srpauloand abnormally, if there is an unprotected error. 941280405SrpauloIn case of normal termination, 942280405Srpaulo<a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>true</b>, 943280405Srpauloplus any values returned by the coroutine main function. 944280405SrpauloIn case of errors, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>false</b> 945326344Simpplus an error object. 946280405Srpaulo 947280405Srpaulo 948280405Srpaulo<p> 949280405SrpauloA coroutine yields by calling <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>. 950280405SrpauloWhen a coroutine yields, 951280405Srpaulothe corresponding <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns immediately, 952280405Srpauloeven if the yield happens inside nested function calls 953280405Srpaulo(that is, not in the main function, 954280405Srpaulobut in a function directly or indirectly called by the main function). 955280405SrpauloIn the case of a yield, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> also returns <b>true</b>, 956280405Srpauloplus any values passed to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>. 957280405SrpauloThe next time you resume the same coroutine, 958280405Srpauloit continues its execution from the point where it yielded, 959280405Srpaulowith the call to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a> returning any extra 960280405Srpauloarguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. 961280405Srpaulo 962280405Srpaulo 963280405Srpaulo<p> 964280405SrpauloLike <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>, 965280405Srpaulothe <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> function also creates a coroutine, 966280405Srpaulobut instead of returning the coroutine itself, 967280405Srpauloit returns a function that, when called, resumes the coroutine. 968280405SrpauloAny arguments passed to this function 969280405Srpaulogo as extra arguments to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. 970280405Srpaulo<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>, 971280405Srpauloexcept the first one (the boolean error code). 972280405SrpauloUnlike <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>, 973280405Srpaulo<a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> does not catch errors; 974280405Srpauloany error is propagated to the caller. 975280405Srpaulo 976280405Srpaulo 977280405Srpaulo<p> 978280405SrpauloAs an example of how coroutines work, 979280405Srpauloconsider the following code: 980280405Srpaulo 981280405Srpaulo<pre> 982280405Srpaulo function foo (a) 983280405Srpaulo print("foo", a) 984280405Srpaulo return coroutine.yield(2*a) 985280405Srpaulo end 986280405Srpaulo 987280405Srpaulo co = coroutine.create(function (a,b) 988280405Srpaulo print("co-body", a, b) 989280405Srpaulo local r = foo(a+1) 990280405Srpaulo print("co-body", r) 991280405Srpaulo local r, s = coroutine.yield(a+b, a-b) 992280405Srpaulo print("co-body", r, s) 993280405Srpaulo return b, "end" 994280405Srpaulo end) 995280405Srpaulo 996280405Srpaulo print("main", coroutine.resume(co, 1, 10)) 997280405Srpaulo print("main", coroutine.resume(co, "r")) 998280405Srpaulo print("main", coroutine.resume(co, "x", "y")) 999280405Srpaulo print("main", coroutine.resume(co, "x", "y")) 1000280405Srpaulo</pre><p> 1001280405SrpauloWhen you run it, it produces the following output: 1002280405Srpaulo 1003280405Srpaulo<pre> 1004280405Srpaulo co-body 1 10 1005280405Srpaulo foo 2 1006280405Srpaulo main true 4 1007280405Srpaulo co-body r 1008280405Srpaulo main true 11 -9 1009280405Srpaulo co-body x y 1010280405Srpaulo main true 10 end 1011280405Srpaulo main false cannot resume dead coroutine 1012280405Srpaulo</pre> 1013280405Srpaulo 1014280405Srpaulo<p> 1015280405SrpauloYou can also create and manipulate coroutines through the C API: 1016280405Srpaulosee functions <a href="#lua_newthread"><code>lua_newthread</code></a>, <a href="#lua_resume"><code>lua_resume</code></a>, 1017280405Srpauloand <a href="#lua_yield"><code>lua_yield</code></a>. 1018280405Srpaulo 1019280405Srpaulo 1020280405Srpaulo 1021280405Srpaulo 1022280405Srpaulo 1023280405Srpaulo<h1>3 – <a name="3">The Language</a></h1> 1024280405Srpaulo 1025280405Srpaulo<p> 1026280405SrpauloThis section describes the lexis, the syntax, and the semantics of Lua. 1027280405SrpauloIn other words, 1028280405Srpaulothis section describes 1029280405Srpaulowhich tokens are valid, 1030280405Srpaulohow they can be combined, 1031280405Srpauloand what their combinations mean. 1032280405Srpaulo 1033280405Srpaulo 1034280405Srpaulo<p> 1035280405SrpauloLanguage constructs will be explained using the usual extended BNF notation, 1036280405Srpauloin which 1037280405Srpaulo{<em>a</em>} means 0 or more <em>a</em>'s, and 1038280405Srpaulo[<em>a</em>] means an optional <em>a</em>. 1039280405SrpauloNon-terminals are shown like non-terminal, 1040280405Srpaulokeywords are shown like <b>kword</b>, 1041280405Srpauloand other terminal symbols are shown like ‘<b>=</b>’. 1042280405SrpauloThe complete syntax of Lua can be found in <a href="#9">§9</a> 1043280405Srpauloat the end of this manual. 1044280405Srpaulo 1045280405Srpaulo 1046280405Srpaulo 1047280405Srpaulo<h2>3.1 – <a name="3.1">Lexical Conventions</a></h2> 1048280405Srpaulo 1049280405Srpaulo<p> 1050280405SrpauloLua is a free-form language. 1051280405SrpauloIt ignores spaces (including new lines) and comments 1052280405Srpaulobetween lexical elements (tokens), 1053280405Srpauloexcept as delimiters between names and keywords. 1054280405Srpaulo 1055280405Srpaulo 1056280405Srpaulo<p> 1057280405Srpaulo<em>Names</em> 1058280405Srpaulo(also called <em>identifiers</em>) 1059280405Srpauloin Lua can be any string of letters, 1060280405Srpaulodigits, and underscores, 1061326344Simpnot beginning with a digit and 1062326344Simpnot being a reserved word. 1063280405SrpauloIdentifiers are used to name variables, table fields, and labels. 1064280405Srpaulo 1065280405Srpaulo 1066280405Srpaulo<p> 1067280405SrpauloThe following <em>keywords</em> are reserved 1068280405Srpauloand cannot be used as names: 1069280405Srpaulo 1070280405Srpaulo 1071280405Srpaulo<pre> 1072280405Srpaulo and break do else elseif end 1073280405Srpaulo false for function goto if in 1074280405Srpaulo local nil not or repeat return 1075280405Srpaulo then true until while 1076280405Srpaulo</pre> 1077280405Srpaulo 1078280405Srpaulo<p> 1079280405SrpauloLua is a case-sensitive language: 1080280405Srpaulo<code>and</code> is a reserved word, but <code>And</code> and <code>AND</code> 1081280405Srpauloare two different, valid names. 1082280405SrpauloAs a convention, 1083326344Simpprograms should avoid creating 1084280405Srpaulonames that start with an underscore followed by 1085280405Srpauloone or more uppercase letters (such as <a href="#pdf-_VERSION"><code>_VERSION</code></a>). 1086280405Srpaulo 1087280405Srpaulo 1088280405Srpaulo<p> 1089280405SrpauloThe following strings denote other tokens: 1090280405Srpaulo 1091280405Srpaulo<pre> 1092280405Srpaulo + - * / % ^ # 1093280405Srpaulo & ~ | << >> // 1094280405Srpaulo == ~= <= >= < > = 1095280405Srpaulo ( ) { } [ ] :: 1096280405Srpaulo ; : , . .. ... 1097280405Srpaulo</pre> 1098280405Srpaulo 1099280405Srpaulo<p> 1100326344SimpA <em>short literal string</em> 1101280405Srpaulocan be delimited by matching single or double quotes, 1102280405Srpauloand can contain the following C-like escape sequences: 1103280405Srpaulo'<code>\a</code>' (bell), 1104280405Srpaulo'<code>\b</code>' (backspace), 1105280405Srpaulo'<code>\f</code>' (form feed), 1106280405Srpaulo'<code>\n</code>' (newline), 1107280405Srpaulo'<code>\r</code>' (carriage return), 1108280405Srpaulo'<code>\t</code>' (horizontal tab), 1109280405Srpaulo'<code>\v</code>' (vertical tab), 1110280405Srpaulo'<code>\\</code>' (backslash), 1111280405Srpaulo'<code>\"</code>' (quotation mark [double quote]), 1112280405Srpauloand '<code>\'</code>' (apostrophe [single quote]). 1113326344SimpA backslash followed by a line break 1114280405Srpauloresults in a newline in the string. 1115280405SrpauloThe escape sequence '<code>\z</code>' skips the following span 1116280405Srpauloof white-space characters, 1117280405Srpauloincluding line breaks; 1118280405Srpauloit is particularly useful to break and indent a long literal string 1119280405Srpaulointo multiple lines without adding the newlines and spaces 1120280405Srpaulointo the string contents. 1121326344SimpA short literal string cannot contain unescaped line breaks 1122326344Simpnor escapes not forming a valid escape sequence. 1123280405Srpaulo 1124280405Srpaulo 1125280405Srpaulo<p> 1126326344SimpWe can specify any byte in a short literal string by its numeric value 1127326344Simp(including embedded zeros). 1128280405SrpauloThis can be done 1129280405Srpaulowith the escape sequence <code>\x<em>XX</em></code>, 1130280405Srpaulowhere <em>XX</em> is a sequence of exactly two hexadecimal digits, 1131280405Srpauloor with the escape sequence <code>\<em>ddd</em></code>, 1132280405Srpaulowhere <em>ddd</em> is a sequence of up to three decimal digits. 1133280405Srpaulo(Note that if a decimal escape sequence is to be followed by a digit, 1134280405Srpauloit must be expressed using exactly three digits.) 1135280405Srpaulo 1136280405Srpaulo 1137280405Srpaulo<p> 1138280405SrpauloThe UTF-8 encoding of a Unicode character 1139280405Srpaulocan be inserted in a literal string with 1140280405Srpaulothe escape sequence <code>\u{<em>XXX</em>}</code> 1141280405Srpaulo(note the mandatory enclosing brackets), 1142280405Srpaulowhere <em>XXX</em> is a sequence of one or more hexadecimal digits 1143280405Srpaulorepresenting the character code point. 1144280405Srpaulo 1145280405Srpaulo 1146280405Srpaulo<p> 1147280405SrpauloLiteral strings can also be defined using a long format 1148280405Srpauloenclosed by <em>long brackets</em>. 1149280405SrpauloWe define an <em>opening long bracket of level <em>n</em></em> as an opening 1150280405Srpaulosquare bracket followed by <em>n</em> equal signs followed by another 1151280405Srpauloopening square bracket. 1152280405SrpauloSo, an opening long bracket of level 0 is written as <code>[[</code>, 1153280405Srpauloan opening long bracket of level 1 is written as <code>[=[</code>, 1154280405Srpauloand so on. 1155280405SrpauloA <em>closing long bracket</em> is defined similarly; 1156280405Srpaulofor instance, 1157280405Srpauloa closing long bracket of level 4 is written as <code>]====]</code>. 1158280405SrpauloA <em>long literal</em> starts with an opening long bracket of any level and 1159280405Srpauloends at the first closing long bracket of the same level. 1160280405SrpauloIt can contain any text except a closing bracket of the same level. 1161280405SrpauloLiterals in this bracketed form can run for several lines, 1162280405Srpaulodo not interpret any escape sequences, 1163280405Srpauloand ignore long brackets of any other level. 1164280405SrpauloAny kind of end-of-line sequence 1165280405Srpaulo(carriage return, newline, carriage return followed by newline, 1166280405Srpauloor newline followed by carriage return) 1167280405Srpaulois converted to a simple newline. 1168280405Srpaulo 1169280405Srpaulo 1170280405Srpaulo<p> 1171280405SrpauloFor convenience, 1172280405Srpaulowhen the opening long bracket is immediately followed by a newline, 1173280405Srpaulothe newline is not included in the string. 1174280405SrpauloAs an example, in a system using ASCII 1175280405Srpaulo(in which '<code>a</code>' is coded as 97, 1176280405Srpaulonewline is coded as 10, and '<code>1</code>' is coded as 49), 1177280405Srpaulothe five literal strings below denote the same string: 1178280405Srpaulo 1179280405Srpaulo<pre> 1180280405Srpaulo a = 'alo\n123"' 1181280405Srpaulo a = "alo\n123\"" 1182280405Srpaulo a = '\97lo\10\04923"' 1183280405Srpaulo a = [[alo 1184280405Srpaulo 123"]] 1185280405Srpaulo a = [==[ 1186280405Srpaulo alo 1187280405Srpaulo 123"]==] 1188280405Srpaulo</pre> 1189280405Srpaulo 1190280405Srpaulo<p> 1191326344SimpAny byte in a literal string not 1192326344Simpexplicitly affected by the previous rules represents itself. 1193326344SimpHowever, Lua opens files for parsing in text mode, 1194326344Simpand the system file functions may have problems with 1195326344Simpsome control characters. 1196326344SimpSo, it is safer to represent 1197326344Simpnon-text data as a quoted literal with 1198326344Simpexplicit escape sequences for the non-text characters. 1199326344Simp 1200326344Simp 1201326344Simp<p> 1202326344SimpA <em>numeric constant</em> (or <em>numeral</em>) 1203280405Srpaulocan be written with an optional fractional part 1204280405Srpauloand an optional decimal exponent, 1205280405Srpaulomarked by a letter '<code>e</code>' or '<code>E</code>'. 1206280405SrpauloLua also accepts hexadecimal constants, 1207280405Srpaulowhich start with <code>0x</code> or <code>0X</code>. 1208280405SrpauloHexadecimal constants also accept an optional fractional part 1209280405Srpauloplus an optional binary exponent, 1210280405Srpaulomarked by a letter '<code>p</code>' or '<code>P</code>'. 1211326344SimpA numeric constant with a radix point or an exponent 1212280405Srpaulodenotes a float; 1213326344Simpotherwise, 1214326344Simpif its value fits in an integer, 1215326344Simpit denotes an integer. 1216280405SrpauloExamples of valid integer constants are 1217280405Srpaulo 1218280405Srpaulo<pre> 1219280405Srpaulo 3 345 0xff 0xBEBADA 1220280405Srpaulo</pre><p> 1221280405SrpauloExamples of valid float constants are 1222280405Srpaulo 1223280405Srpaulo<pre> 1224280405Srpaulo 3.0 3.1416 314.16e-2 0.31416E1 34e1 1225280405Srpaulo 0x0.1E 0xA23p-4 0X1.921FB54442D18P+1 1226280405Srpaulo</pre> 1227280405Srpaulo 1228280405Srpaulo<p> 1229280405SrpauloA <em>comment</em> starts with a double hyphen (<code>--</code>) 1230280405Srpauloanywhere outside a string. 1231280405SrpauloIf the text immediately after <code>--</code> is not an opening long bracket, 1232280405Srpaulothe comment is a <em>short comment</em>, 1233280405Srpaulowhich runs until the end of the line. 1234280405SrpauloOtherwise, it is a <em>long comment</em>, 1235280405Srpaulowhich runs until the corresponding closing long bracket. 1236280405SrpauloLong comments are frequently used to disable code temporarily. 1237280405Srpaulo 1238280405Srpaulo 1239280405Srpaulo 1240280405Srpaulo 1241280405Srpaulo 1242280405Srpaulo<h2>3.2 – <a name="3.2">Variables</a></h2> 1243280405Srpaulo 1244280405Srpaulo<p> 1245280405SrpauloVariables are places that store values. 1246280405SrpauloThere are three kinds of variables in Lua: 1247280405Srpauloglobal variables, local variables, and table fields. 1248280405Srpaulo 1249280405Srpaulo 1250280405Srpaulo<p> 1251280405SrpauloA single name can denote a global variable or a local variable 1252280405Srpaulo(or a function's formal parameter, 1253280405Srpaulowhich is a particular kind of local variable): 1254280405Srpaulo 1255280405Srpaulo<pre> 1256280405Srpaulo var ::= Name 1257280405Srpaulo</pre><p> 1258280405SrpauloName denotes identifiers, as defined in <a href="#3.1">§3.1</a>. 1259280405Srpaulo 1260280405Srpaulo 1261280405Srpaulo<p> 1262280405SrpauloAny variable name is assumed to be global unless explicitly declared 1263280405Srpauloas a local (see <a href="#3.3.7">§3.3.7</a>). 1264280405SrpauloLocal variables are <em>lexically scoped</em>: 1265280405Srpaulolocal variables can be freely accessed by functions 1266280405Srpaulodefined inside their scope (see <a href="#3.5">§3.5</a>). 1267280405Srpaulo 1268280405Srpaulo 1269280405Srpaulo<p> 1270280405SrpauloBefore the first assignment to a variable, its value is <b>nil</b>. 1271280405Srpaulo 1272280405Srpaulo 1273280405Srpaulo<p> 1274280405SrpauloSquare brackets are used to index a table: 1275280405Srpaulo 1276280405Srpaulo<pre> 1277280405Srpaulo var ::= prefixexp ‘<b>[</b>’ exp ‘<b>]</b>’ 1278280405Srpaulo</pre><p> 1279280405SrpauloThe meaning of accesses to table fields can be changed via metatables. 1280280405SrpauloAn access to an indexed variable <code>t[i]</code> is equivalent to 1281280405Srpauloa call <code>gettable_event(t,i)</code>. 1282280405Srpaulo(See <a href="#2.4">§2.4</a> for a complete description of the 1283280405Srpaulo<code>gettable_event</code> function. 1284280405SrpauloThis function is not defined or callable in Lua. 1285280405SrpauloWe use it here only for explanatory purposes.) 1286280405Srpaulo 1287280405Srpaulo 1288280405Srpaulo<p> 1289280405SrpauloThe syntax <code>var.Name</code> is just syntactic sugar for 1290280405Srpaulo<code>var["Name"]</code>: 1291280405Srpaulo 1292280405Srpaulo<pre> 1293280405Srpaulo var ::= prefixexp ‘<b>.</b>’ Name 1294280405Srpaulo</pre> 1295280405Srpaulo 1296280405Srpaulo<p> 1297280405SrpauloAn access to a global variable <code>x</code> 1298280405Srpaulois equivalent to <code>_ENV.x</code>. 1299280405SrpauloDue to the way that chunks are compiled, 1300280405Srpaulo<code>_ENV</code> is never a global name (see <a href="#2.2">§2.2</a>). 1301280405Srpaulo 1302280405Srpaulo 1303280405Srpaulo 1304280405Srpaulo 1305280405Srpaulo 1306280405Srpaulo<h2>3.3 – <a name="3.3">Statements</a></h2> 1307280405Srpaulo 1308280405Srpaulo<p> 1309280405SrpauloLua supports an almost conventional set of statements, 1310280405Srpaulosimilar to those in Pascal or C. 1311280405SrpauloThis set includes 1312280405Srpauloassignments, control structures, function calls, 1313280405Srpauloand variable declarations. 1314280405Srpaulo 1315280405Srpaulo 1316280405Srpaulo 1317280405Srpaulo<h3>3.3.1 – <a name="3.3.1">Blocks</a></h3> 1318280405Srpaulo 1319280405Srpaulo<p> 1320280405SrpauloA block is a list of statements, 1321280405Srpaulowhich are executed sequentially: 1322280405Srpaulo 1323280405Srpaulo<pre> 1324280405Srpaulo block ::= {stat} 1325280405Srpaulo</pre><p> 1326280405SrpauloLua has <em>empty statements</em> 1327280405Srpaulothat allow you to separate statements with semicolons, 1328280405Srpaulostart a block with a semicolon 1329280405Srpauloor write two semicolons in sequence: 1330280405Srpaulo 1331280405Srpaulo<pre> 1332280405Srpaulo stat ::= ‘<b>;</b>’ 1333280405Srpaulo</pre> 1334280405Srpaulo 1335280405Srpaulo<p> 1336280405SrpauloFunction calls and assignments 1337280405Srpaulocan start with an open parenthesis. 1338280405SrpauloThis possibility leads to an ambiguity in Lua's grammar. 1339280405SrpauloConsider the following fragment: 1340280405Srpaulo 1341280405Srpaulo<pre> 1342280405Srpaulo a = b + c 1343280405Srpaulo (print or io.write)('done') 1344280405Srpaulo</pre><p> 1345280405SrpauloThe grammar could see it in two ways: 1346280405Srpaulo 1347280405Srpaulo<pre> 1348280405Srpaulo a = b + c(print or io.write)('done') 1349280405Srpaulo 1350280405Srpaulo a = b + c; (print or io.write)('done') 1351280405Srpaulo</pre><p> 1352280405SrpauloThe current parser always sees such constructions 1353280405Srpauloin the first way, 1354280405Srpaulointerpreting the open parenthesis 1355280405Srpauloas the start of the arguments to a call. 1356280405SrpauloTo avoid this ambiguity, 1357280405Srpauloit is a good practice to always precede with a semicolon 1358280405Srpaulostatements that start with a parenthesis: 1359280405Srpaulo 1360280405Srpaulo<pre> 1361280405Srpaulo ;(print or io.write)('done') 1362280405Srpaulo</pre> 1363280405Srpaulo 1364280405Srpaulo<p> 1365280405SrpauloA block can be explicitly delimited to produce a single statement: 1366280405Srpaulo 1367280405Srpaulo<pre> 1368280405Srpaulo stat ::= <b>do</b> block <b>end</b> 1369280405Srpaulo</pre><p> 1370280405SrpauloExplicit blocks are useful 1371280405Srpauloto control the scope of variable declarations. 1372280405SrpauloExplicit blocks are also sometimes used to 1373280405Srpauloadd a <b>return</b> statement in the middle 1374280405Srpauloof another block (see <a href="#3.3.4">§3.3.4</a>). 1375280405Srpaulo 1376280405Srpaulo 1377280405Srpaulo 1378280405Srpaulo 1379280405Srpaulo 1380280405Srpaulo<h3>3.3.2 – <a name="3.3.2">Chunks</a></h3> 1381280405Srpaulo 1382280405Srpaulo<p> 1383280405SrpauloThe unit of compilation of Lua is called a <em>chunk</em>. 1384280405SrpauloSyntactically, 1385280405Srpauloa chunk is simply a block: 1386280405Srpaulo 1387280405Srpaulo<pre> 1388280405Srpaulo chunk ::= block 1389280405Srpaulo</pre> 1390280405Srpaulo 1391280405Srpaulo<p> 1392280405SrpauloLua handles a chunk as the body of an anonymous function 1393280405Srpaulowith a variable number of arguments 1394280405Srpaulo(see <a href="#3.4.11">§3.4.11</a>). 1395280405SrpauloAs such, chunks can define local variables, 1396280405Srpauloreceive arguments, and return values. 1397280405SrpauloMoreover, such anonymous function is compiled as in the 1398280405Srpauloscope of an external local variable called <code>_ENV</code> (see <a href="#2.2">§2.2</a>). 1399280405SrpauloThe resulting function always has <code>_ENV</code> as its only upvalue, 1400280405Srpauloeven if it does not use that variable. 1401280405Srpaulo 1402280405Srpaulo 1403280405Srpaulo<p> 1404280405SrpauloA chunk can be stored in a file or in a string inside the host program. 1405280405SrpauloTo execute a chunk, 1406280405SrpauloLua first <em>loads</em> it, 1407280405Srpauloprecompiling the chunk's code into instructions for a virtual machine, 1408280405Srpauloand then Lua executes the compiled code 1409280405Srpaulowith an interpreter for the virtual machine. 1410280405Srpaulo 1411280405Srpaulo 1412280405Srpaulo<p> 1413280405SrpauloChunks can also be precompiled into binary form; 1414280405Srpaulosee program <code>luac</code> and function <a href="#pdf-string.dump"><code>string.dump</code></a> for details. 1415280405SrpauloPrograms in source and compiled forms are interchangeable; 1416280405SrpauloLua automatically detects the file type and acts accordingly (see <a href="#pdf-load"><code>load</code></a>). 1417280405Srpaulo 1418280405Srpaulo 1419280405Srpaulo 1420280405Srpaulo 1421280405Srpaulo 1422280405Srpaulo<h3>3.3.3 – <a name="3.3.3">Assignment</a></h3> 1423280405Srpaulo 1424280405Srpaulo<p> 1425280405SrpauloLua allows multiple assignments. 1426280405SrpauloTherefore, the syntax for assignment 1427280405Srpaulodefines a list of variables on the left side 1428280405Srpauloand a list of expressions on the right side. 1429280405SrpauloThe elements in both lists are separated by commas: 1430280405Srpaulo 1431280405Srpaulo<pre> 1432280405Srpaulo stat ::= varlist ‘<b>=</b>’ explist 1433280405Srpaulo varlist ::= var {‘<b>,</b>’ var} 1434280405Srpaulo explist ::= exp {‘<b>,</b>’ exp} 1435280405Srpaulo</pre><p> 1436280405SrpauloExpressions are discussed in <a href="#3.4">§3.4</a>. 1437280405Srpaulo 1438280405Srpaulo 1439280405Srpaulo<p> 1440280405SrpauloBefore the assignment, 1441280405Srpaulothe list of values is <em>adjusted</em> to the length of 1442280405Srpaulothe list of variables. 1443280405SrpauloIf there are more values than needed, 1444280405Srpaulothe excess values are thrown away. 1445280405SrpauloIf there are fewer values than needed, 1446280405Srpaulothe list is extended with as many <b>nil</b>'s as needed. 1447280405SrpauloIf the list of expressions ends with a function call, 1448280405Srpaulothen all values returned by that call enter the list of values, 1449280405Srpaulobefore the adjustment 1450280405Srpaulo(except when the call is enclosed in parentheses; see <a href="#3.4">§3.4</a>). 1451280405Srpaulo 1452280405Srpaulo 1453280405Srpaulo<p> 1454280405SrpauloThe assignment statement first evaluates all its expressions 1455280405Srpauloand only then the assignments are performed. 1456280405SrpauloThus the code 1457280405Srpaulo 1458280405Srpaulo<pre> 1459280405Srpaulo i = 3 1460280405Srpaulo i, a[i] = i+1, 20 1461280405Srpaulo</pre><p> 1462280405Srpaulosets <code>a[3]</code> to 20, without affecting <code>a[4]</code> 1463280405Srpaulobecause the <code>i</code> in <code>a[i]</code> is evaluated (to 3) 1464280405Srpaulobefore it is assigned 4. 1465280405SrpauloSimilarly, the line 1466280405Srpaulo 1467280405Srpaulo<pre> 1468280405Srpaulo x, y = y, x 1469280405Srpaulo</pre><p> 1470280405Srpauloexchanges the values of <code>x</code> and <code>y</code>, 1471280405Srpauloand 1472280405Srpaulo 1473280405Srpaulo<pre> 1474280405Srpaulo x, y, z = y, z, x 1475280405Srpaulo</pre><p> 1476280405Srpaulocyclically permutes the values of <code>x</code>, <code>y</code>, and <code>z</code>. 1477280405Srpaulo 1478280405Srpaulo 1479280405Srpaulo<p> 1480280405SrpauloThe meaning of assignments to global variables 1481280405Srpauloand table fields can be changed via metatables. 1482280405SrpauloAn assignment to an indexed variable <code>t[i] = val</code> is equivalent to 1483280405Srpaulo<code>settable_event(t,i,val)</code>. 1484280405Srpaulo(See <a href="#2.4">§2.4</a> for a complete description of the 1485280405Srpaulo<code>settable_event</code> function. 1486280405SrpauloThis function is not defined or callable in Lua. 1487280405SrpauloWe use it here only for explanatory purposes.) 1488280405Srpaulo 1489280405Srpaulo 1490280405Srpaulo<p> 1491280405SrpauloAn assignment to a global name <code>x = val</code> 1492280405Srpaulois equivalent to the assignment 1493280405Srpaulo<code>_ENV.x = val</code> (see <a href="#2.2">§2.2</a>). 1494280405Srpaulo 1495280405Srpaulo 1496280405Srpaulo 1497280405Srpaulo 1498280405Srpaulo 1499280405Srpaulo<h3>3.3.4 – <a name="3.3.4">Control Structures</a></h3><p> 1500280405SrpauloThe control structures 1501280405Srpaulo<b>if</b>, <b>while</b>, and <b>repeat</b> have the usual meaning and 1502280405Srpaulofamiliar syntax: 1503280405Srpaulo 1504280405Srpaulo 1505280405Srpaulo 1506280405Srpaulo 1507280405Srpaulo<pre> 1508280405Srpaulo stat ::= <b>while</b> exp <b>do</b> block <b>end</b> 1509280405Srpaulo stat ::= <b>repeat</b> block <b>until</b> exp 1510280405Srpaulo stat ::= <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> 1511280405Srpaulo</pre><p> 1512280405SrpauloLua also has a <b>for</b> statement, in two flavors (see <a href="#3.3.5">§3.3.5</a>). 1513280405Srpaulo 1514280405Srpaulo 1515280405Srpaulo<p> 1516280405SrpauloThe condition expression of a 1517280405Srpaulocontrol structure can return any value. 1518280405SrpauloBoth <b>false</b> and <b>nil</b> are considered false. 1519280405SrpauloAll values different from <b>nil</b> and <b>false</b> are considered true 1520280405Srpaulo(in particular, the number 0 and the empty string are also true). 1521280405Srpaulo 1522280405Srpaulo 1523280405Srpaulo<p> 1524280405SrpauloIn the <b>repeat</b>–<b>until</b> loop, 1525280405Srpaulothe inner block does not end at the <b>until</b> keyword, 1526280405Srpaulobut only after the condition. 1527280405SrpauloSo, the condition can refer to local variables 1528280405Srpaulodeclared inside the loop block. 1529280405Srpaulo 1530280405Srpaulo 1531280405Srpaulo<p> 1532280405SrpauloThe <b>goto</b> statement transfers the program control to a label. 1533280405SrpauloFor syntactical reasons, 1534280405Srpaulolabels in Lua are considered statements too: 1535280405Srpaulo 1536280405Srpaulo 1537280405Srpaulo 1538280405Srpaulo<pre> 1539280405Srpaulo stat ::= <b>goto</b> Name 1540280405Srpaulo stat ::= label 1541280405Srpaulo label ::= ‘<b>::</b>’ Name ‘<b>::</b>’ 1542280405Srpaulo</pre> 1543280405Srpaulo 1544280405Srpaulo<p> 1545280405SrpauloA label is visible in the entire block where it is defined, 1546280405Srpauloexcept 1547280405Srpauloinside nested blocks where a label with the same name is defined and 1548280405Srpauloinside nested functions. 1549280405SrpauloA goto may jump to any visible label as long as it does not 1550280405Srpauloenter into the scope of a local variable. 1551280405Srpaulo 1552280405Srpaulo 1553280405Srpaulo<p> 1554280405SrpauloLabels and empty statements are called <em>void statements</em>, 1555280405Srpauloas they perform no actions. 1556280405Srpaulo 1557280405Srpaulo 1558280405Srpaulo<p> 1559280405SrpauloThe <b>break</b> statement terminates the execution of a 1560280405Srpaulo<b>while</b>, <b>repeat</b>, or <b>for</b> loop, 1561280405Srpauloskipping to the next statement after the loop: 1562280405Srpaulo 1563280405Srpaulo 1564280405Srpaulo<pre> 1565280405Srpaulo stat ::= <b>break</b> 1566280405Srpaulo</pre><p> 1567280405SrpauloA <b>break</b> ends the innermost enclosing loop. 1568280405Srpaulo 1569280405Srpaulo 1570280405Srpaulo<p> 1571280405SrpauloThe <b>return</b> statement is used to return values 1572280405Srpaulofrom a function or a chunk 1573280405Srpaulo(which is an anonymous function). 1574280405Srpaulo 1575280405SrpauloFunctions can return more than one value, 1576280405Srpauloso the syntax for the <b>return</b> statement is 1577280405Srpaulo 1578280405Srpaulo<pre> 1579280405Srpaulo stat ::= <b>return</b> [explist] [‘<b>;</b>’] 1580280405Srpaulo</pre> 1581280405Srpaulo 1582280405Srpaulo<p> 1583280405SrpauloThe <b>return</b> statement can only be written 1584280405Srpauloas the last statement of a block. 1585280405SrpauloIf it is really necessary to <b>return</b> in the middle of a block, 1586280405Srpaulothen an explicit inner block can be used, 1587280405Srpauloas in the idiom <code>do return end</code>, 1588280405Srpaulobecause now <b>return</b> is the last statement in its (inner) block. 1589280405Srpaulo 1590280405Srpaulo 1591280405Srpaulo 1592280405Srpaulo 1593280405Srpaulo 1594280405Srpaulo<h3>3.3.5 – <a name="3.3.5">For Statement</a></h3> 1595280405Srpaulo 1596280405Srpaulo<p> 1597280405Srpaulo 1598280405SrpauloThe <b>for</b> statement has two forms: 1599326344Simpone numerical and one generic. 1600280405Srpaulo 1601280405Srpaulo 1602280405Srpaulo<p> 1603326344SimpThe numerical <b>for</b> loop repeats a block of code while a 1604280405Srpaulocontrol variable runs through an arithmetic progression. 1605280405SrpauloIt has the following syntax: 1606280405Srpaulo 1607280405Srpaulo<pre> 1608280405Srpaulo stat ::= <b>for</b> Name ‘<b>=</b>’ exp ‘<b>,</b>’ exp [‘<b>,</b>’ exp] <b>do</b> block <b>end</b> 1609280405Srpaulo</pre><p> 1610280405SrpauloThe <em>block</em> is repeated for <em>name</em> starting at the value of 1611280405Srpaulothe first <em>exp</em>, until it passes the second <em>exp</em> by steps of the 1612280405Srpaulothird <em>exp</em>. 1613280405SrpauloMore precisely, a <b>for</b> statement like 1614280405Srpaulo 1615280405Srpaulo<pre> 1616280405Srpaulo for v = <em>e1</em>, <em>e2</em>, <em>e3</em> do <em>block</em> end 1617280405Srpaulo</pre><p> 1618280405Srpaulois equivalent to the code: 1619280405Srpaulo 1620280405Srpaulo<pre> 1621280405Srpaulo do 1622280405Srpaulo local <em>var</em>, <em>limit</em>, <em>step</em> = tonumber(<em>e1</em>), tonumber(<em>e2</em>), tonumber(<em>e3</em>) 1623280405Srpaulo if not (<em>var</em> and <em>limit</em> and <em>step</em>) then error() end 1624280405Srpaulo <em>var</em> = <em>var</em> - <em>step</em> 1625280405Srpaulo while true do 1626280405Srpaulo <em>var</em> = <em>var</em> + <em>step</em> 1627280405Srpaulo if (<em>step</em> >= 0 and <em>var</em> > <em>limit</em>) or (<em>step</em> < 0 and <em>var</em> < <em>limit</em>) then 1628280405Srpaulo break 1629280405Srpaulo end 1630280405Srpaulo local v = <em>var</em> 1631280405Srpaulo <em>block</em> 1632280405Srpaulo end 1633280405Srpaulo end 1634280405Srpaulo</pre> 1635280405Srpaulo 1636280405Srpaulo<p> 1637280405SrpauloNote the following: 1638280405Srpaulo 1639280405Srpaulo<ul> 1640280405Srpaulo 1641280405Srpaulo<li> 1642280405SrpauloAll three control expressions are evaluated only once, 1643280405Srpaulobefore the loop starts. 1644280405SrpauloThey must all result in numbers. 1645280405Srpaulo</li> 1646280405Srpaulo 1647280405Srpaulo<li> 1648280405Srpaulo<code><em>var</em></code>, <code><em>limit</em></code>, and <code><em>step</em></code> are invisible variables. 1649280405SrpauloThe names shown here are for explanatory purposes only. 1650280405Srpaulo</li> 1651280405Srpaulo 1652280405Srpaulo<li> 1653280405SrpauloIf the third expression (the step) is absent, 1654280405Srpaulothen a step of 1 is used. 1655280405Srpaulo</li> 1656280405Srpaulo 1657280405Srpaulo<li> 1658280405SrpauloYou can use <b>break</b> and <b>goto</b> to exit a <b>for</b> loop. 1659280405Srpaulo</li> 1660280405Srpaulo 1661280405Srpaulo<li> 1662280405SrpauloThe loop variable <code>v</code> is local to the loop body. 1663280405SrpauloIf you need its value after the loop, 1664280405Srpauloassign it to another variable before exiting the loop. 1665280405Srpaulo</li> 1666280405Srpaulo 1667280405Srpaulo</ul> 1668280405Srpaulo 1669280405Srpaulo<p> 1670280405SrpauloThe generic <b>for</b> statement works over functions, 1671280405Srpaulocalled <em>iterators</em>. 1672280405SrpauloOn each iteration, the iterator function is called to produce a new value, 1673280405Srpaulostopping when this new value is <b>nil</b>. 1674280405SrpauloThe generic <b>for</b> loop has the following syntax: 1675280405Srpaulo 1676280405Srpaulo<pre> 1677280405Srpaulo stat ::= <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> 1678280405Srpaulo namelist ::= Name {‘<b>,</b>’ Name} 1679280405Srpaulo</pre><p> 1680280405SrpauloA <b>for</b> statement like 1681280405Srpaulo 1682280405Srpaulo<pre> 1683280405Srpaulo for <em>var_1</em>, ···, <em>var_n</em> in <em>explist</em> do <em>block</em> end 1684280405Srpaulo</pre><p> 1685280405Srpaulois equivalent to the code: 1686280405Srpaulo 1687280405Srpaulo<pre> 1688280405Srpaulo do 1689280405Srpaulo local <em>f</em>, <em>s</em>, <em>var</em> = <em>explist</em> 1690280405Srpaulo while true do 1691280405Srpaulo local <em>var_1</em>, ···, <em>var_n</em> = <em>f</em>(<em>s</em>, <em>var</em>) 1692280405Srpaulo if <em>var_1</em> == nil then break end 1693280405Srpaulo <em>var</em> = <em>var_1</em> 1694280405Srpaulo <em>block</em> 1695280405Srpaulo end 1696280405Srpaulo end 1697280405Srpaulo</pre><p> 1698280405SrpauloNote the following: 1699280405Srpaulo 1700280405Srpaulo<ul> 1701280405Srpaulo 1702280405Srpaulo<li> 1703280405Srpaulo<code><em>explist</em></code> is evaluated only once. 1704280405SrpauloIts results are an <em>iterator</em> function, 1705280405Srpauloa <em>state</em>, 1706280405Srpauloand an initial value for the first <em>iterator variable</em>. 1707280405Srpaulo</li> 1708280405Srpaulo 1709280405Srpaulo<li> 1710280405Srpaulo<code><em>f</em></code>, <code><em>s</em></code>, and <code><em>var</em></code> are invisible variables. 1711280405SrpauloThe names are here for explanatory purposes only. 1712280405Srpaulo</li> 1713280405Srpaulo 1714280405Srpaulo<li> 1715280405SrpauloYou can use <b>break</b> to exit a <b>for</b> loop. 1716280405Srpaulo</li> 1717280405Srpaulo 1718280405Srpaulo<li> 1719280405SrpauloThe loop variables <code><em>var_i</em></code> are local to the loop; 1720280405Srpauloyou cannot use their values after the <b>for</b> ends. 1721280405SrpauloIf you need these values, 1722280405Srpaulothen assign them to other variables before breaking or exiting the loop. 1723280405Srpaulo</li> 1724280405Srpaulo 1725280405Srpaulo</ul> 1726280405Srpaulo 1727280405Srpaulo 1728280405Srpaulo 1729280405Srpaulo 1730280405Srpaulo<h3>3.3.6 – <a name="3.3.6">Function Calls as Statements</a></h3><p> 1731280405SrpauloTo allow possible side-effects, 1732280405Srpaulofunction calls can be executed as statements: 1733280405Srpaulo 1734280405Srpaulo<pre> 1735280405Srpaulo stat ::= functioncall 1736280405Srpaulo</pre><p> 1737280405SrpauloIn this case, all returned values are thrown away. 1738280405SrpauloFunction calls are explained in <a href="#3.4.10">§3.4.10</a>. 1739280405Srpaulo 1740280405Srpaulo 1741280405Srpaulo 1742280405Srpaulo 1743280405Srpaulo 1744280405Srpaulo<h3>3.3.7 – <a name="3.3.7">Local Declarations</a></h3><p> 1745280405SrpauloLocal variables can be declared anywhere inside a block. 1746280405SrpauloThe declaration can include an initial assignment: 1747280405Srpaulo 1748280405Srpaulo<pre> 1749280405Srpaulo stat ::= <b>local</b> namelist [‘<b>=</b>’ explist] 1750280405Srpaulo</pre><p> 1751280405SrpauloIf present, an initial assignment has the same semantics 1752280405Srpauloof a multiple assignment (see <a href="#3.3.3">§3.3.3</a>). 1753280405SrpauloOtherwise, all variables are initialized with <b>nil</b>. 1754280405Srpaulo 1755280405Srpaulo 1756280405Srpaulo<p> 1757280405SrpauloA chunk is also a block (see <a href="#3.3.2">§3.3.2</a>), 1758280405Srpauloand so local variables can be declared in a chunk outside any explicit block. 1759280405Srpaulo 1760280405Srpaulo 1761280405Srpaulo<p> 1762280405SrpauloThe visibility rules for local variables are explained in <a href="#3.5">§3.5</a>. 1763280405Srpaulo 1764280405Srpaulo 1765280405Srpaulo 1766280405Srpaulo 1767280405Srpaulo 1768280405Srpaulo 1769280405Srpaulo 1770280405Srpaulo<h2>3.4 – <a name="3.4">Expressions</a></h2> 1771280405Srpaulo 1772280405Srpaulo<p> 1773280405SrpauloThe basic expressions in Lua are the following: 1774280405Srpaulo 1775280405Srpaulo<pre> 1776280405Srpaulo exp ::= prefixexp 1777280405Srpaulo exp ::= <b>nil</b> | <b>false</b> | <b>true</b> 1778280405Srpaulo exp ::= Numeral 1779280405Srpaulo exp ::= LiteralString 1780280405Srpaulo exp ::= functiondef 1781280405Srpaulo exp ::= tableconstructor 1782280405Srpaulo exp ::= ‘<b>...</b>’ 1783280405Srpaulo exp ::= exp binop exp 1784280405Srpaulo exp ::= unop exp 1785280405Srpaulo prefixexp ::= var | functioncall | ‘<b>(</b>’ exp ‘<b>)</b>’ 1786280405Srpaulo</pre> 1787280405Srpaulo 1788280405Srpaulo<p> 1789280405SrpauloNumerals and literal strings are explained in <a href="#3.1">§3.1</a>; 1790280405Srpaulovariables are explained in <a href="#3.2">§3.2</a>; 1791280405Srpaulofunction definitions are explained in <a href="#3.4.11">§3.4.11</a>; 1792280405Srpaulofunction calls are explained in <a href="#3.4.10">§3.4.10</a>; 1793280405Srpaulotable constructors are explained in <a href="#3.4.9">§3.4.9</a>. 1794280405SrpauloVararg expressions, 1795280405Srpaulodenoted by three dots ('<code>...</code>'), can only be used when 1796280405Srpaulodirectly inside a vararg function; 1797280405Srpaulothey are explained in <a href="#3.4.11">§3.4.11</a>. 1798280405Srpaulo 1799280405Srpaulo 1800280405Srpaulo<p> 1801280405SrpauloBinary operators comprise arithmetic operators (see <a href="#3.4.1">§3.4.1</a>), 1802280405Srpaulobitwise operators (see <a href="#3.4.2">§3.4.2</a>), 1803280405Srpaulorelational operators (see <a href="#3.4.4">§3.4.4</a>), logical operators (see <a href="#3.4.5">§3.4.5</a>), 1804280405Srpauloand the concatenation operator (see <a href="#3.4.6">§3.4.6</a>). 1805280405SrpauloUnary operators comprise the unary minus (see <a href="#3.4.1">§3.4.1</a>), 1806326344Simpthe unary bitwise NOT (see <a href="#3.4.2">§3.4.2</a>), 1807280405Srpaulothe unary logical <b>not</b> (see <a href="#3.4.5">§3.4.5</a>), 1808280405Srpauloand the unary <em>length operator</em> (see <a href="#3.4.7">§3.4.7</a>). 1809280405Srpaulo 1810280405Srpaulo 1811280405Srpaulo<p> 1812280405SrpauloBoth function calls and vararg expressions can result in multiple values. 1813280405SrpauloIf a function call is used as a statement (see <a href="#3.3.6">§3.3.6</a>), 1814280405Srpaulothen its return list is adjusted to zero elements, 1815280405Srpaulothus discarding all returned values. 1816280405SrpauloIf an expression is used as the last (or the only) element 1817280405Srpauloof a list of expressions, 1818280405Srpaulothen no adjustment is made 1819280405Srpaulo(unless the expression is enclosed in parentheses). 1820280405SrpauloIn all other contexts, 1821280405SrpauloLua adjusts the result list to one element, 1822280405Srpauloeither discarding all values except the first one 1823280405Srpauloor adding a single <b>nil</b> if there are no values. 1824280405Srpaulo 1825280405Srpaulo 1826280405Srpaulo<p> 1827280405SrpauloHere are some examples: 1828280405Srpaulo 1829280405Srpaulo<pre> 1830280405Srpaulo f() -- adjusted to 0 results 1831280405Srpaulo g(f(), x) -- f() is adjusted to 1 result 1832280405Srpaulo g(x, f()) -- g gets x plus all results from f() 1833280405Srpaulo a,b,c = f(), x -- f() is adjusted to 1 result (c gets nil) 1834280405Srpaulo a,b = ... -- a gets the first vararg parameter, b gets 1835280405Srpaulo -- the second (both a and b can get nil if there 1836280405Srpaulo -- is no corresponding vararg parameter) 1837280405Srpaulo 1838280405Srpaulo a,b,c = x, f() -- f() is adjusted to 2 results 1839280405Srpaulo a,b,c = f() -- f() is adjusted to 3 results 1840280405Srpaulo return f() -- returns all results from f() 1841280405Srpaulo return ... -- returns all received vararg parameters 1842280405Srpaulo return x,y,f() -- returns x, y, and all results from f() 1843280405Srpaulo {f()} -- creates a list with all results from f() 1844280405Srpaulo {...} -- creates a list with all vararg parameters 1845280405Srpaulo {f(), nil} -- f() is adjusted to 1 result 1846280405Srpaulo</pre> 1847280405Srpaulo 1848280405Srpaulo<p> 1849280405SrpauloAny expression enclosed in parentheses always results in only one value. 1850280405SrpauloThus, 1851280405Srpaulo<code>(f(x,y,z))</code> is always a single value, 1852280405Srpauloeven if <code>f</code> returns several values. 1853280405Srpaulo(The value of <code>(f(x,y,z))</code> is the first value returned by <code>f</code> 1854280405Srpauloor <b>nil</b> if <code>f</code> does not return any values.) 1855280405Srpaulo 1856280405Srpaulo 1857280405Srpaulo 1858280405Srpaulo<h3>3.4.1 – <a name="3.4.1">Arithmetic Operators</a></h3><p> 1859280405SrpauloLua supports the following arithmetic operators: 1860280405Srpaulo 1861280405Srpaulo<ul> 1862280405Srpaulo<li><b><code>+</code>: </b>addition</li> 1863280405Srpaulo<li><b><code>-</code>: </b>subtraction</li> 1864280405Srpaulo<li><b><code>*</code>: </b>multiplication</li> 1865280405Srpaulo<li><b><code>/</code>: </b>float division</li> 1866280405Srpaulo<li><b><code>//</code>: </b>floor division</li> 1867280405Srpaulo<li><b><code>%</code>: </b>modulo</li> 1868280405Srpaulo<li><b><code>^</code>: </b>exponentiation</li> 1869280405Srpaulo<li><b><code>-</code>: </b>unary minus</li> 1870280405Srpaulo</ul> 1871280405Srpaulo 1872280405Srpaulo<p> 1873280405SrpauloWith the exception of exponentiation and float division, 1874280405Srpaulothe arithmetic operators work as follows: 1875280405SrpauloIf both operands are integers, 1876280405Srpaulothe operation is performed over integers and the result is an integer. 1877280405SrpauloOtherwise, if both operands are numbers 1878280405Srpauloor strings that can be converted to 1879280405Srpaulonumbers (see <a href="#3.4.3">§3.4.3</a>), 1880280405Srpaulothen they are converted to floats, 1881280405Srpaulothe operation is performed following the usual rules 1882280405Srpaulofor floating-point arithmetic 1883280405Srpaulo(usually the IEEE 754 standard), 1884280405Srpauloand the result is a float. 1885280405Srpaulo 1886280405Srpaulo 1887280405Srpaulo<p> 1888280405SrpauloExponentiation and float division (<code>/</code>) 1889280405Srpauloalways convert their operands to floats 1890280405Srpauloand the result is always a float. 1891280405SrpauloExponentiation uses the ISO C function <code>pow</code>, 1892280405Srpauloso that it works for non-integer exponents too. 1893280405Srpaulo 1894280405Srpaulo 1895280405Srpaulo<p> 1896326344SimpFloor division (<code>//</code>) is a division 1897326344Simpthat rounds the quotient towards minus infinity, 1898280405Srpaulothat is, the floor of the division of its operands. 1899280405Srpaulo 1900280405Srpaulo 1901280405Srpaulo<p> 1902280405SrpauloModulo is defined as the remainder of a division 1903326344Simpthat rounds the quotient towards minus infinity (floor division). 1904280405Srpaulo 1905280405Srpaulo 1906280405Srpaulo<p> 1907280405SrpauloIn case of overflows in integer arithmetic, 1908280405Srpauloall operations <em>wrap around</em>, 1909280405Srpauloaccording to the usual rules of two-complement arithmetic. 1910280405Srpaulo(In other words, 1911280405Srpaulothey return the unique representable integer 1912280405Srpaulothat is equal modulo <em>2<sup>64</sup></em> to the mathematical result.) 1913280405Srpaulo 1914280405Srpaulo 1915280405Srpaulo 1916280405Srpaulo<h3>3.4.2 – <a name="3.4.2">Bitwise Operators</a></h3><p> 1917280405SrpauloLua supports the following bitwise operators: 1918280405Srpaulo 1919280405Srpaulo<ul> 1920326344Simp<li><b><code>&</code>: </b>bitwise AND</li> 1921326344Simp<li><b><code>|</code>: </b>bitwise OR</li> 1922326344Simp<li><b><code>~</code>: </b>bitwise exclusive OR</li> 1923280405Srpaulo<li><b><code>>></code>: </b>right shift</li> 1924280405Srpaulo<li><b><code><<</code>: </b>left shift</li> 1925326344Simp<li><b><code>~</code>: </b>unary bitwise NOT</li> 1926280405Srpaulo</ul> 1927280405Srpaulo 1928280405Srpaulo<p> 1929280405SrpauloAll bitwise operations convert its operands to integers 1930280405Srpaulo(see <a href="#3.4.3">§3.4.3</a>), 1931280405Srpaulooperate on all bits of those integers, 1932280405Srpauloand result in an integer. 1933280405Srpaulo 1934280405Srpaulo 1935280405Srpaulo<p> 1936280405SrpauloBoth right and left shifts fill the vacant bits with zeros. 1937280405SrpauloNegative displacements shift to the other direction; 1938280405Srpaulodisplacements with absolute values equal to or higher than 1939280405Srpaulothe number of bits in an integer 1940280405Srpauloresult in zero (as all bits are shifted out). 1941280405Srpaulo 1942280405Srpaulo 1943280405Srpaulo 1944280405Srpaulo 1945280405Srpaulo 1946280405Srpaulo<h3>3.4.3 – <a name="3.4.3">Coercions and Conversions</a></h3><p> 1947280405SrpauloLua provides some automatic conversions between some 1948280405Srpaulotypes and representations at run time. 1949280405SrpauloBitwise operators always convert float operands to integers. 1950280405SrpauloExponentiation and float division 1951280405Srpauloalways convert integer operands to floats. 1952280405SrpauloAll other arithmetic operations applied to mixed numbers 1953280405Srpaulo(integers and floats) convert the integer operand to a float; 1954280405Srpaulothis is called the <em>usual rule</em>. 1955280405SrpauloThe C API also converts both integers to floats and 1956280405Srpaulofloats to integers, as needed. 1957280405SrpauloMoreover, string concatenation accepts numbers as arguments, 1958326344Simpbesides strings. 1959280405Srpaulo 1960280405Srpaulo 1961280405Srpaulo<p> 1962280405SrpauloLua also converts strings to numbers, 1963280405Srpaulowhenever a number is expected. 1964280405Srpaulo 1965280405Srpaulo 1966280405Srpaulo<p> 1967280405SrpauloIn a conversion from integer to float, 1968280405Srpauloif the integer value has an exact representation as a float, 1969280405Srpaulothat is the result. 1970280405SrpauloOtherwise, 1971280405Srpaulothe conversion gets the nearest higher or 1972280405Srpaulothe nearest lower representable value. 1973280405SrpauloThis kind of conversion never fails. 1974280405Srpaulo 1975280405Srpaulo 1976280405Srpaulo<p> 1977280405SrpauloThe conversion from float to integer 1978280405Srpaulochecks whether the float has an exact representation as an integer 1979280405Srpaulo(that is, the float has an integral value and 1980280405Srpauloit is in the range of integer representation). 1981280405SrpauloIf it does, that representation is the result. 1982280405SrpauloOtherwise, the conversion fails. 1983280405Srpaulo 1984280405Srpaulo 1985280405Srpaulo<p> 1986280405SrpauloThe conversion from strings to numbers goes as follows: 1987280405SrpauloFirst, the string is converted to an integer or a float, 1988280405Srpaulofollowing its syntax and the rules of the Lua lexer. 1989280405Srpaulo(The string may have also leading and trailing spaces and a sign.) 1990326344SimpThen, the resulting number (float or integer) 1991326344Simpis converted to the type (float or integer) required by the context 1992326344Simp(e.g., the operation that forced the conversion). 1993280405Srpaulo 1994280405Srpaulo 1995280405Srpaulo<p> 1996326344SimpAll conversions from strings to numbers 1997326344Simpaccept both a dot and the current locale mark 1998326344Simpas the radix character. 1999326344Simp(The Lua lexer, however, accepts only a dot.) 2000326344Simp 2001326344Simp 2002326344Simp<p> 2003280405SrpauloThe conversion from numbers to strings uses a 2004280405Srpaulonon-specified human-readable format. 2005280405SrpauloFor complete control over how numbers are converted to strings, 2006280405Srpaulouse the <code>format</code> function from the string library 2007280405Srpaulo(see <a href="#pdf-string.format"><code>string.format</code></a>). 2008280405Srpaulo 2009280405Srpaulo 2010280405Srpaulo 2011280405Srpaulo 2012280405Srpaulo 2013280405Srpaulo<h3>3.4.4 – <a name="3.4.4">Relational Operators</a></h3><p> 2014280405SrpauloLua supports the following relational operators: 2015280405Srpaulo 2016280405Srpaulo<ul> 2017280405Srpaulo<li><b><code>==</code>: </b>equality</li> 2018280405Srpaulo<li><b><code>~=</code>: </b>inequality</li> 2019280405Srpaulo<li><b><code><</code>: </b>less than</li> 2020280405Srpaulo<li><b><code>></code>: </b>greater than</li> 2021280405Srpaulo<li><b><code><=</code>: </b>less or equal</li> 2022280405Srpaulo<li><b><code>>=</code>: </b>greater or equal</li> 2023280405Srpaulo</ul><p> 2024280405SrpauloThese operators always result in <b>false</b> or <b>true</b>. 2025280405Srpaulo 2026280405Srpaulo 2027280405Srpaulo<p> 2028280405SrpauloEquality (<code>==</code>) first compares the type of its operands. 2029280405SrpauloIf the types are different, then the result is <b>false</b>. 2030280405SrpauloOtherwise, the values of the operands are compared. 2031280405SrpauloStrings are compared in the obvious way. 2032326344SimpNumbers are equal if they denote the same mathematical value. 2033280405Srpaulo 2034280405Srpaulo 2035280405Srpaulo<p> 2036280405SrpauloTables, userdata, and threads 2037280405Srpauloare compared by reference: 2038280405Srpaulotwo objects are considered equal only if they are the same object. 2039280405SrpauloEvery time you create a new object 2040280405Srpaulo(a table, userdata, or thread), 2041280405Srpaulothis new object is different from any previously existing object. 2042280405SrpauloClosures with the same reference are always equal. 2043280405SrpauloClosures with any detectable difference 2044280405Srpaulo(different behavior, different definition) are always different. 2045280405Srpaulo 2046280405Srpaulo 2047280405Srpaulo<p> 2048280405SrpauloYou can change the way that Lua compares tables and userdata 2049280405Srpauloby using the "eq" metamethod (see <a href="#2.4">§2.4</a>). 2050280405Srpaulo 2051280405Srpaulo 2052280405Srpaulo<p> 2053280405SrpauloEquality comparisons do not convert strings to numbers 2054280405Srpauloor vice versa. 2055280405SrpauloThus, <code>"0"==0</code> evaluates to <b>false</b>, 2056280405Srpauloand <code>t[0]</code> and <code>t["0"]</code> denote different 2057280405Srpauloentries in a table. 2058280405Srpaulo 2059280405Srpaulo 2060280405Srpaulo<p> 2061280405SrpauloThe operator <code>~=</code> is exactly the negation of equality (<code>==</code>). 2062280405Srpaulo 2063280405Srpaulo 2064280405Srpaulo<p> 2065280405SrpauloThe order operators work as follows. 2066280405SrpauloIf both arguments are numbers, 2067326344Simpthen they are compared according to their mathematical values 2068326344Simp(regardless of their subtypes). 2069280405SrpauloOtherwise, if both arguments are strings, 2070280405Srpaulothen their values are compared according to the current locale. 2071280405SrpauloOtherwise, Lua tries to call the "lt" or the "le" 2072280405Srpaulometamethod (see <a href="#2.4">§2.4</a>). 2073280405SrpauloA comparison <code>a > b</code> is translated to <code>b < a</code> 2074280405Srpauloand <code>a >= b</code> is translated to <code>b <= a</code>. 2075280405Srpaulo 2076280405Srpaulo 2077326344Simp<p> 2078326344SimpFollowing the IEEE 754 standard, 2079326344SimpNaN is considered neither smaller than, 2080326344Simpnor equal to, nor greater than any value (including itself). 2081280405Srpaulo 2082280405Srpaulo 2083280405Srpaulo 2084326344Simp 2085326344Simp 2086280405Srpaulo<h3>3.4.5 – <a name="3.4.5">Logical Operators</a></h3><p> 2087280405SrpauloThe logical operators in Lua are 2088280405Srpaulo<b>and</b>, <b>or</b>, and <b>not</b>. 2089280405SrpauloLike the control structures (see <a href="#3.3.4">§3.3.4</a>), 2090280405Srpauloall logical operators consider both <b>false</b> and <b>nil</b> as false 2091280405Srpauloand anything else as true. 2092280405Srpaulo 2093280405Srpaulo 2094280405Srpaulo<p> 2095280405SrpauloThe negation operator <b>not</b> always returns <b>false</b> or <b>true</b>. 2096280405SrpauloThe conjunction operator <b>and</b> returns its first argument 2097280405Srpauloif this value is <b>false</b> or <b>nil</b>; 2098280405Srpaulootherwise, <b>and</b> returns its second argument. 2099280405SrpauloThe disjunction operator <b>or</b> returns its first argument 2100280405Srpauloif this value is different from <b>nil</b> and <b>false</b>; 2101280405Srpaulootherwise, <b>or</b> returns its second argument. 2102280405SrpauloBoth <b>and</b> and <b>or</b> use short-circuit evaluation; 2103280405Srpaulothat is, 2104280405Srpaulothe second operand is evaluated only if necessary. 2105280405SrpauloHere are some examples: 2106280405Srpaulo 2107280405Srpaulo<pre> 2108280405Srpaulo 10 or 20 --> 10 2109280405Srpaulo 10 or error() --> 10 2110280405Srpaulo nil or "a" --> "a" 2111280405Srpaulo nil and 10 --> nil 2112280405Srpaulo false and error() --> false 2113280405Srpaulo false and nil --> false 2114280405Srpaulo false or nil --> nil 2115280405Srpaulo 10 and 20 --> 20 2116280405Srpaulo</pre><p> 2117280405Srpaulo(In this manual, 2118280405Srpaulo<code>--></code> indicates the result of the preceding expression.) 2119280405Srpaulo 2120280405Srpaulo 2121280405Srpaulo 2122280405Srpaulo 2123280405Srpaulo 2124280405Srpaulo<h3>3.4.6 – <a name="3.4.6">Concatenation</a></h3><p> 2125280405SrpauloThe string concatenation operator in Lua is 2126280405Srpaulodenoted by two dots ('<code>..</code>'). 2127280405SrpauloIf both operands are strings or numbers, then they are converted to 2128280405Srpaulostrings according to the rules described in <a href="#3.4.3">§3.4.3</a>. 2129280405SrpauloOtherwise, the <code>__concat</code> metamethod is called (see <a href="#2.4">§2.4</a>). 2130280405Srpaulo 2131280405Srpaulo 2132280405Srpaulo 2133280405Srpaulo 2134280405Srpaulo 2135280405Srpaulo<h3>3.4.7 – <a name="3.4.7">The Length Operator</a></h3> 2136280405Srpaulo 2137280405Srpaulo<p> 2138280405SrpauloThe length operator is denoted by the unary prefix operator <code>#</code>. 2139326344Simp 2140326344Simp 2141326344Simp<p> 2142280405SrpauloThe length of a string is its number of bytes 2143280405Srpaulo(that is, the usual meaning of string length when each 2144280405Srpaulocharacter is one byte). 2145280405Srpaulo 2146280405Srpaulo 2147280405Srpaulo<p> 2148326344SimpThe length operator applied on a table 2149326344Simpreturns a border in that table. 2150326344SimpA <em>border</em> in a table <code>t</code> is any natural number 2151326344Simpthat satisfies the following condition: 2152280405Srpaulo 2153326344Simp<pre> 2154326344Simp (border == 0 or t[border] ~= nil) and t[border + 1] == nil 2155326344Simp</pre><p> 2156326344SimpIn words, 2157326344Simpa border is any (natural) index in a table 2158326344Simpwhere a non-nil value is followed by a nil value 2159326344Simp(or zero, when index 1 is nil). 2160280405Srpaulo 2161326344Simp 2162280405Srpaulo<p> 2163326344SimpA table with exactly one border is called a <em>sequence</em>. 2164326344SimpFor instance, the table <code>{10, 20, 30, 40, 50}</code> is a sequence, 2165326344Simpas it has only one border (5). 2166326344SimpThe table <code>{10, 20, 30, nil, 50}</code> has two borders (3 and 5), 2167326344Simpand therefore it is not a sequence. 2168326344SimpThe table <code>{nil, 20, 30, nil, nil, 60, nil}</code> 2169326344Simphas three borders (0, 3, and 6), 2170326344Simpso it is not a sequence, too. 2171326344SimpThe table <code>{}</code> is a sequence with border 0. 2172326344SimpNote that non-natural keys do not interfere 2173280405Srpaulowith whether a table is a sequence. 2174280405Srpaulo 2175280405Srpaulo 2176326344Simp<p> 2177326344SimpWhen <code>t</code> is a sequence, 2178326344Simp<code>#t</code> returns its only border, 2179326344Simpwhich corresponds to the intuitive notion of the length of the sequence. 2180326344SimpWhen <code>t</code> is not a sequence, 2181326344Simp<code>#t</code> can return any of its borders. 2182326344Simp(The exact one depends on details of 2183326344Simpthe internal representation of the table, 2184326344Simpwhich in turn can depend on how the table was populated and 2185326344Simpthe memory addresses of its non-numeric keys.) 2186280405Srpaulo 2187280405Srpaulo 2188326344Simp<p> 2189326344SimpThe computation of the length of a table 2190326344Simphas a guaranteed worst time of <em>O(log n)</em>, 2191326344Simpwhere <em>n</em> is the largest natural key in the table. 2192280405Srpaulo 2193326344Simp 2194326344Simp<p> 2195326344SimpA program can modify the behavior of the length operator for 2196326344Simpany value but strings through the <code>__len</code> metamethod (see <a href="#2.4">§2.4</a>). 2197326344Simp 2198326344Simp 2199326344Simp 2200326344Simp 2201326344Simp 2202280405Srpaulo<h3>3.4.8 – <a name="3.4.8">Precedence</a></h3><p> 2203280405SrpauloOperator precedence in Lua follows the table below, 2204280405Srpaulofrom lower to higher priority: 2205280405Srpaulo 2206280405Srpaulo<pre> 2207280405Srpaulo or 2208280405Srpaulo and 2209280405Srpaulo < > <= >= ~= == 2210280405Srpaulo | 2211280405Srpaulo ~ 2212280405Srpaulo & 2213280405Srpaulo << >> 2214280405Srpaulo .. 2215280405Srpaulo + - 2216280405Srpaulo * / // % 2217280405Srpaulo unary operators (not # - ~) 2218280405Srpaulo ^ 2219280405Srpaulo</pre><p> 2220280405SrpauloAs usual, 2221280405Srpauloyou can use parentheses to change the precedences of an expression. 2222280405SrpauloThe concatenation ('<code>..</code>') and exponentiation ('<code>^</code>') 2223280405Srpaulooperators are right associative. 2224280405SrpauloAll other binary operators are left associative. 2225280405Srpaulo 2226280405Srpaulo 2227280405Srpaulo 2228280405Srpaulo 2229280405Srpaulo 2230280405Srpaulo<h3>3.4.9 – <a name="3.4.9">Table Constructors</a></h3><p> 2231280405SrpauloTable constructors are expressions that create tables. 2232280405SrpauloEvery time a constructor is evaluated, a new table is created. 2233280405SrpauloA constructor can be used to create an empty table 2234280405Srpauloor to create a table and initialize some of its fields. 2235280405SrpauloThe general syntax for constructors is 2236280405Srpaulo 2237280405Srpaulo<pre> 2238280405Srpaulo tableconstructor ::= ‘<b>{</b>’ [fieldlist] ‘<b>}</b>’ 2239280405Srpaulo fieldlist ::= field {fieldsep field} [fieldsep] 2240280405Srpaulo field ::= ‘<b>[</b>’ exp ‘<b>]</b>’ ‘<b>=</b>’ exp | Name ‘<b>=</b>’ exp | exp 2241280405Srpaulo fieldsep ::= ‘<b>,</b>’ | ‘<b>;</b>’ 2242280405Srpaulo</pre> 2243280405Srpaulo 2244280405Srpaulo<p> 2245280405SrpauloEach field of the form <code>[exp1] = exp2</code> adds to the new table an entry 2246280405Srpaulowith key <code>exp1</code> and value <code>exp2</code>. 2247280405SrpauloA field of the form <code>name = exp</code> is equivalent to 2248280405Srpaulo<code>["name"] = exp</code>. 2249280405SrpauloFinally, fields of the form <code>exp</code> are equivalent to 2250280405Srpaulo<code>[i] = exp</code>, where <code>i</code> are consecutive integers 2251280405Srpaulostarting with 1. 2252280405SrpauloFields in the other formats do not affect this counting. 2253280405SrpauloFor example, 2254280405Srpaulo 2255280405Srpaulo<pre> 2256280405Srpaulo a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 } 2257280405Srpaulo</pre><p> 2258280405Srpaulois equivalent to 2259280405Srpaulo 2260280405Srpaulo<pre> 2261280405Srpaulo do 2262280405Srpaulo local t = {} 2263280405Srpaulo t[f(1)] = g 2264280405Srpaulo t[1] = "x" -- 1st exp 2265280405Srpaulo t[2] = "y" -- 2nd exp 2266280405Srpaulo t.x = 1 -- t["x"] = 1 2267280405Srpaulo t[3] = f(x) -- 3rd exp 2268280405Srpaulo t[30] = 23 2269280405Srpaulo t[4] = 45 -- 4th exp 2270280405Srpaulo a = t 2271280405Srpaulo end 2272280405Srpaulo</pre> 2273280405Srpaulo 2274280405Srpaulo<p> 2275280405SrpauloThe order of the assignments in a constructor is undefined. 2276280405Srpaulo(This order would be relevant only when there are repeated keys.) 2277280405Srpaulo 2278280405Srpaulo 2279280405Srpaulo<p> 2280280405SrpauloIf the last field in the list has the form <code>exp</code> 2281280405Srpauloand the expression is a function call or a vararg expression, 2282280405Srpaulothen all values returned by this expression enter the list consecutively 2283280405Srpaulo(see <a href="#3.4.10">§3.4.10</a>). 2284280405Srpaulo 2285280405Srpaulo 2286280405Srpaulo<p> 2287280405SrpauloThe field list can have an optional trailing separator, 2288280405Srpauloas a convenience for machine-generated code. 2289280405Srpaulo 2290280405Srpaulo 2291280405Srpaulo 2292280405Srpaulo 2293280405Srpaulo 2294280405Srpaulo<h3>3.4.10 – <a name="3.4.10">Function Calls</a></h3><p> 2295280405SrpauloA function call in Lua has the following syntax: 2296280405Srpaulo 2297280405Srpaulo<pre> 2298280405Srpaulo functioncall ::= prefixexp args 2299280405Srpaulo</pre><p> 2300280405SrpauloIn a function call, 2301280405Srpaulofirst prefixexp and args are evaluated. 2302280405SrpauloIf the value of prefixexp has type <em>function</em>, 2303280405Srpaulothen this function is called 2304280405Srpaulowith the given arguments. 2305280405SrpauloOtherwise, the prefixexp "call" metamethod is called, 2306280405Srpaulohaving as first parameter the value of prefixexp, 2307280405Srpaulofollowed by the original call arguments 2308280405Srpaulo(see <a href="#2.4">§2.4</a>). 2309280405Srpaulo 2310280405Srpaulo 2311280405Srpaulo<p> 2312280405SrpauloThe form 2313280405Srpaulo 2314280405Srpaulo<pre> 2315280405Srpaulo functioncall ::= prefixexp ‘<b>:</b>’ Name args 2316280405Srpaulo</pre><p> 2317280405Srpaulocan be used to call "methods". 2318280405SrpauloA call <code>v:name(<em>args</em>)</code> 2319280405Srpaulois syntactic sugar for <code>v.name(v,<em>args</em>)</code>, 2320280405Srpauloexcept that <code>v</code> is evaluated only once. 2321280405Srpaulo 2322280405Srpaulo 2323280405Srpaulo<p> 2324280405SrpauloArguments have the following syntax: 2325280405Srpaulo 2326280405Srpaulo<pre> 2327280405Srpaulo args ::= ‘<b>(</b>’ [explist] ‘<b>)</b>’ 2328280405Srpaulo args ::= tableconstructor 2329280405Srpaulo args ::= LiteralString 2330280405Srpaulo</pre><p> 2331280405SrpauloAll argument expressions are evaluated before the call. 2332280405SrpauloA call of the form <code>f{<em>fields</em>}</code> is 2333280405Srpaulosyntactic sugar for <code>f({<em>fields</em>})</code>; 2334280405Srpaulothat is, the argument list is a single new table. 2335280405SrpauloA call of the form <code>f'<em>string</em>'</code> 2336280405Srpaulo(or <code>f"<em>string</em>"</code> or <code>f[[<em>string</em>]]</code>) 2337280405Srpaulois syntactic sugar for <code>f('<em>string</em>')</code>; 2338280405Srpaulothat is, the argument list is a single literal string. 2339280405Srpaulo 2340280405Srpaulo 2341280405Srpaulo<p> 2342280405SrpauloA call of the form <code>return <em>functioncall</em></code> is called 2343280405Srpauloa <em>tail call</em>. 2344280405SrpauloLua implements <em>proper tail calls</em> 2345280405Srpaulo(or <em>proper tail recursion</em>): 2346280405Srpauloin a tail call, 2347280405Srpaulothe called function reuses the stack entry of the calling function. 2348280405SrpauloTherefore, there is no limit on the number of nested tail calls that 2349280405Srpauloa program can execute. 2350280405SrpauloHowever, a tail call erases any debug information about the 2351280405Srpaulocalling function. 2352280405SrpauloNote that a tail call only happens with a particular syntax, 2353280405Srpaulowhere the <b>return</b> has one single function call as argument; 2354280405Srpaulothis syntax makes the calling function return exactly 2355280405Srpaulothe returns of the called function. 2356280405SrpauloSo, none of the following examples are tail calls: 2357280405Srpaulo 2358280405Srpaulo<pre> 2359280405Srpaulo return (f(x)) -- results adjusted to 1 2360280405Srpaulo return 2 * f(x) 2361280405Srpaulo return x, f(x) -- additional results 2362280405Srpaulo f(x); return -- results discarded 2363280405Srpaulo return x or f(x) -- results adjusted to 1 2364280405Srpaulo</pre> 2365280405Srpaulo 2366280405Srpaulo 2367280405Srpaulo 2368280405Srpaulo 2369280405Srpaulo<h3>3.4.11 – <a name="3.4.11">Function Definitions</a></h3> 2370280405Srpaulo 2371280405Srpaulo<p> 2372280405SrpauloThe syntax for function definition is 2373280405Srpaulo 2374280405Srpaulo<pre> 2375280405Srpaulo functiondef ::= <b>function</b> funcbody 2376280405Srpaulo funcbody ::= ‘<b>(</b>’ [parlist] ‘<b>)</b>’ block <b>end</b> 2377280405Srpaulo</pre> 2378280405Srpaulo 2379280405Srpaulo<p> 2380280405SrpauloThe following syntactic sugar simplifies function definitions: 2381280405Srpaulo 2382280405Srpaulo<pre> 2383280405Srpaulo stat ::= <b>function</b> funcname funcbody 2384280405Srpaulo stat ::= <b>local</b> <b>function</b> Name funcbody 2385280405Srpaulo funcname ::= Name {‘<b>.</b>’ Name} [‘<b>:</b>’ Name] 2386280405Srpaulo</pre><p> 2387280405SrpauloThe statement 2388280405Srpaulo 2389280405Srpaulo<pre> 2390280405Srpaulo function f () <em>body</em> end 2391280405Srpaulo</pre><p> 2392280405Srpaulotranslates to 2393280405Srpaulo 2394280405Srpaulo<pre> 2395280405Srpaulo f = function () <em>body</em> end 2396280405Srpaulo</pre><p> 2397280405SrpauloThe statement 2398280405Srpaulo 2399280405Srpaulo<pre> 2400280405Srpaulo function t.a.b.c.f () <em>body</em> end 2401280405Srpaulo</pre><p> 2402280405Srpaulotranslates to 2403280405Srpaulo 2404280405Srpaulo<pre> 2405280405Srpaulo t.a.b.c.f = function () <em>body</em> end 2406280405Srpaulo</pre><p> 2407280405SrpauloThe statement 2408280405Srpaulo 2409280405Srpaulo<pre> 2410280405Srpaulo local function f () <em>body</em> end 2411280405Srpaulo</pre><p> 2412280405Srpaulotranslates to 2413280405Srpaulo 2414280405Srpaulo<pre> 2415280405Srpaulo local f; f = function () <em>body</em> end 2416280405Srpaulo</pre><p> 2417280405Srpaulonot to 2418280405Srpaulo 2419280405Srpaulo<pre> 2420280405Srpaulo local f = function () <em>body</em> end 2421280405Srpaulo</pre><p> 2422280405Srpaulo(This only makes a difference when the body of the function 2423280405Srpaulocontains references to <code>f</code>.) 2424280405Srpaulo 2425280405Srpaulo 2426280405Srpaulo<p> 2427280405SrpauloA function definition is an executable expression, 2428280405Srpaulowhose value has type <em>function</em>. 2429280405SrpauloWhen Lua precompiles a chunk, 2430280405Srpauloall its function bodies are precompiled too. 2431280405SrpauloThen, whenever Lua executes the function definition, 2432280405Srpaulothe function is <em>instantiated</em> (or <em>closed</em>). 2433280405SrpauloThis function instance (or <em>closure</em>) 2434280405Srpaulois the final value of the expression. 2435280405Srpaulo 2436280405Srpaulo 2437280405Srpaulo<p> 2438280405SrpauloParameters act as local variables that are 2439280405Srpauloinitialized with the argument values: 2440280405Srpaulo 2441280405Srpaulo<pre> 2442280405Srpaulo parlist ::= namelist [‘<b>,</b>’ ‘<b>...</b>’] | ‘<b>...</b>’ 2443280405Srpaulo</pre><p> 2444280405SrpauloWhen a function is called, 2445280405Srpaulothe list of arguments is adjusted to 2446280405Srpaulothe length of the list of parameters, 2447280405Srpaulounless the function is a <em>vararg function</em>, 2448280405Srpaulowhich is indicated by three dots ('<code>...</code>') 2449280405Srpauloat the end of its parameter list. 2450280405SrpauloA vararg function does not adjust its argument list; 2451280405Srpauloinstead, it collects all extra arguments and supplies them 2452280405Srpauloto the function through a <em>vararg expression</em>, 2453280405Srpaulowhich is also written as three dots. 2454280405SrpauloThe value of this expression is a list of all actual extra arguments, 2455280405Srpaulosimilar to a function with multiple results. 2456280405SrpauloIf a vararg expression is used inside another expression 2457280405Srpauloor in the middle of a list of expressions, 2458280405Srpaulothen its return list is adjusted to one element. 2459280405SrpauloIf the expression is used as the last element of a list of expressions, 2460280405Srpaulothen no adjustment is made 2461280405Srpaulo(unless that last expression is enclosed in parentheses). 2462280405Srpaulo 2463280405Srpaulo 2464280405Srpaulo<p> 2465280405SrpauloAs an example, consider the following definitions: 2466280405Srpaulo 2467280405Srpaulo<pre> 2468280405Srpaulo function f(a, b) end 2469280405Srpaulo function g(a, b, ...) end 2470280405Srpaulo function r() return 1,2,3 end 2471280405Srpaulo</pre><p> 2472280405SrpauloThen, we have the following mapping from arguments to parameters and 2473280405Srpauloto the vararg expression: 2474280405Srpaulo 2475280405Srpaulo<pre> 2476280405Srpaulo CALL PARAMETERS 2477280405Srpaulo 2478280405Srpaulo f(3) a=3, b=nil 2479280405Srpaulo f(3, 4) a=3, b=4 2480280405Srpaulo f(3, 4, 5) a=3, b=4 2481280405Srpaulo f(r(), 10) a=1, b=10 2482280405Srpaulo f(r()) a=1, b=2 2483280405Srpaulo 2484280405Srpaulo g(3) a=3, b=nil, ... --> (nothing) 2485280405Srpaulo g(3, 4) a=3, b=4, ... --> (nothing) 2486280405Srpaulo g(3, 4, 5, 8) a=3, b=4, ... --> 5 8 2487280405Srpaulo g(5, r()) a=5, b=1, ... --> 2 3 2488280405Srpaulo</pre> 2489280405Srpaulo 2490280405Srpaulo<p> 2491280405SrpauloResults are returned using the <b>return</b> statement (see <a href="#3.3.4">§3.3.4</a>). 2492280405SrpauloIf control reaches the end of a function 2493280405Srpaulowithout encountering a <b>return</b> statement, 2494280405Srpaulothen the function returns with no results. 2495280405Srpaulo 2496280405Srpaulo 2497280405Srpaulo<p> 2498280405Srpaulo 2499280405SrpauloThere is a system-dependent limit on the number of values 2500280405Srpaulothat a function may return. 2501280405SrpauloThis limit is guaranteed to be larger than 1000. 2502280405Srpaulo 2503280405Srpaulo 2504280405Srpaulo<p> 2505280405SrpauloThe <em>colon</em> syntax 2506280405Srpaulois used for defining <em>methods</em>, 2507280405Srpaulothat is, functions that have an implicit extra parameter <code>self</code>. 2508280405SrpauloThus, the statement 2509280405Srpaulo 2510280405Srpaulo<pre> 2511280405Srpaulo function t.a.b.c:f (<em>params</em>) <em>body</em> end 2512280405Srpaulo</pre><p> 2513280405Srpaulois syntactic sugar for 2514280405Srpaulo 2515280405Srpaulo<pre> 2516280405Srpaulo t.a.b.c.f = function (self, <em>params</em>) <em>body</em> end 2517280405Srpaulo</pre> 2518280405Srpaulo 2519280405Srpaulo 2520280405Srpaulo 2521280405Srpaulo 2522280405Srpaulo 2523280405Srpaulo 2524280405Srpaulo<h2>3.5 – <a name="3.5">Visibility Rules</a></h2> 2525280405Srpaulo 2526280405Srpaulo<p> 2527280405Srpaulo 2528280405SrpauloLua is a lexically scoped language. 2529280405SrpauloThe scope of a local variable begins at the first statement after 2530280405Srpauloits declaration and lasts until the last non-void statement 2531280405Srpauloof the innermost block that includes the declaration. 2532280405SrpauloConsider the following example: 2533280405Srpaulo 2534280405Srpaulo<pre> 2535280405Srpaulo x = 10 -- global variable 2536280405Srpaulo do -- new block 2537280405Srpaulo local x = x -- new 'x', with value 10 2538280405Srpaulo print(x) --> 10 2539280405Srpaulo x = x+1 2540280405Srpaulo do -- another block 2541280405Srpaulo local x = x+1 -- another 'x' 2542280405Srpaulo print(x) --> 12 2543280405Srpaulo end 2544280405Srpaulo print(x) --> 11 2545280405Srpaulo end 2546280405Srpaulo print(x) --> 10 (the global one) 2547280405Srpaulo</pre> 2548280405Srpaulo 2549280405Srpaulo<p> 2550280405SrpauloNotice that, in a declaration like <code>local x = x</code>, 2551280405Srpaulothe new <code>x</code> being declared is not in scope yet, 2552280405Srpauloand so the second <code>x</code> refers to the outside variable. 2553280405Srpaulo 2554280405Srpaulo 2555280405Srpaulo<p> 2556280405SrpauloBecause of the lexical scoping rules, 2557280405Srpaulolocal variables can be freely accessed by functions 2558280405Srpaulodefined inside their scope. 2559280405SrpauloA local variable used by an inner function is called 2560280405Srpauloan <em>upvalue</em>, or <em>external local variable</em>, 2561280405Srpauloinside the inner function. 2562280405Srpaulo 2563280405Srpaulo 2564280405Srpaulo<p> 2565280405SrpauloNotice that each execution of a <b>local</b> statement 2566280405Srpaulodefines new local variables. 2567280405SrpauloConsider the following example: 2568280405Srpaulo 2569280405Srpaulo<pre> 2570280405Srpaulo a = {} 2571280405Srpaulo local x = 20 2572280405Srpaulo for i=1,10 do 2573280405Srpaulo local y = 0 2574280405Srpaulo a[i] = function () y=y+1; return x+y end 2575280405Srpaulo end 2576280405Srpaulo</pre><p> 2577280405SrpauloThe loop creates ten closures 2578280405Srpaulo(that is, ten instances of the anonymous function). 2579280405SrpauloEach of these closures uses a different <code>y</code> variable, 2580280405Srpaulowhile all of them share the same <code>x</code>. 2581280405Srpaulo 2582280405Srpaulo 2583280405Srpaulo 2584280405Srpaulo 2585280405Srpaulo 2586280405Srpaulo<h1>4 – <a name="4">The Application Program Interface</a></h1> 2587280405Srpaulo 2588280405Srpaulo<p> 2589280405Srpaulo 2590280405SrpauloThis section describes the C API for Lua, that is, 2591280405Srpaulothe set of C functions available to the host program to communicate 2592280405Srpaulowith Lua. 2593280405SrpauloAll API functions and related types and constants 2594280405Srpauloare declared in the header file <a name="pdf-lua.h"><code>lua.h</code></a>. 2595280405Srpaulo 2596280405Srpaulo 2597280405Srpaulo<p> 2598280405SrpauloEven when we use the term "function", 2599280405Srpauloany facility in the API may be provided as a macro instead. 2600280405SrpauloExcept where stated otherwise, 2601280405Srpauloall such macros use each of their arguments exactly once 2602280405Srpaulo(except for the first argument, which is always a Lua state), 2603280405Srpauloand so do not generate any hidden side-effects. 2604280405Srpaulo 2605280405Srpaulo 2606280405Srpaulo<p> 2607280405SrpauloAs in most C libraries, 2608280405Srpaulothe Lua API functions do not check their arguments for validity or consistency. 2609280405SrpauloHowever, you can change this behavior by compiling Lua 2610280405Srpaulowith the macro <a name="pdf-LUA_USE_APICHECK"><code>LUA_USE_APICHECK</code></a> defined. 2611280405Srpaulo 2612280405Srpaulo 2613326344Simp<p> 2614326344SimpThe Lua library is fully reentrant: 2615326344Simpit has no global variables. 2616326344SimpIt keeps all information it needs in a dynamic structure, 2617326344Simpcalled the <em>Lua state</em>. 2618280405Srpaulo 2619326344Simp 2620326344Simp<p> 2621326344SimpEach Lua state has one or more threads, 2622326344Simpwhich correspond to independent, cooperative lines of execution. 2623326344SimpThe type <a href="#lua_State"><code>lua_State</code></a> (despite its name) refers to a thread. 2624326344Simp(Indirectly, through the thread, it also refers to the 2625326344SimpLua state associated to the thread.) 2626326344Simp 2627326344Simp 2628326344Simp<p> 2629326344SimpA pointer to a thread must be passed as the first argument to 2630326344Simpevery function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>, 2631326344Simpwhich creates a Lua state from scratch and returns a pointer 2632326344Simpto the <em>main thread</em> in the new state. 2633326344Simp 2634326344Simp 2635326344Simp 2636280405Srpaulo<h2>4.1 – <a name="4.1">The Stack</a></h2> 2637280405Srpaulo 2638280405Srpaulo<p> 2639280405SrpauloLua uses a <em>virtual stack</em> to pass values to and from C. 2640280405SrpauloEach element in this stack represents a Lua value 2641280405Srpaulo(<b>nil</b>, number, string, etc.). 2642326344SimpFunctions in the API can access this stack through the 2643326344SimpLua state parameter that they receive. 2644280405Srpaulo 2645280405Srpaulo 2646280405Srpaulo<p> 2647280405SrpauloWhenever Lua calls C, the called function gets a new stack, 2648280405Srpaulowhich is independent of previous stacks and of stacks of 2649280405SrpauloC functions that are still active. 2650280405SrpauloThis stack initially contains any arguments to the C function 2651326344Simpand it is where the C function can store temporary 2652326344SimpLua values and must push its results 2653280405Srpauloto be returned to the caller (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 2654280405Srpaulo 2655280405Srpaulo 2656280405Srpaulo<p> 2657280405SrpauloFor convenience, 2658280405Srpaulomost query operations in the API do not follow a strict stack discipline. 2659280405SrpauloInstead, they can refer to any element in the stack 2660280405Srpauloby using an <em>index</em>: 2661280405SrpauloA positive index represents an absolute stack position 2662280405Srpaulo(starting at 1); 2663280405Srpauloa negative index represents an offset relative to the top of the stack. 2664280405SrpauloMore specifically, if the stack has <em>n</em> elements, 2665280405Srpaulothen index 1 represents the first element 2666280405Srpaulo(that is, the element that was pushed onto the stack first) 2667280405Srpauloand 2668280405Srpauloindex <em>n</em> represents the last element; 2669280405Srpauloindex -1 also represents the last element 2670280405Srpaulo(that is, the element at the top) 2671280405Srpauloand index <em>-n</em> represents the first element. 2672280405Srpaulo 2673280405Srpaulo 2674280405Srpaulo 2675280405Srpaulo 2676280405Srpaulo 2677280405Srpaulo<h2>4.2 – <a name="4.2">Stack Size</a></h2> 2678280405Srpaulo 2679280405Srpaulo<p> 2680280405SrpauloWhen you interact with the Lua API, 2681280405Srpauloyou are responsible for ensuring consistency. 2682280405SrpauloIn particular, 2683280405Srpaulo<em>you are responsible for controlling stack overflow</em>. 2684280405SrpauloYou can use the function <a href="#lua_checkstack"><code>lua_checkstack</code></a> 2685280405Srpauloto ensure that the stack has enough space for pushing new elements. 2686280405Srpaulo 2687280405Srpaulo 2688280405Srpaulo<p> 2689280405SrpauloWhenever Lua calls C, 2690280405Srpauloit ensures that the stack has space for 2691280405Srpauloat least <a name="pdf-LUA_MINSTACK"><code>LUA_MINSTACK</code></a> extra slots. 2692280405Srpaulo<code>LUA_MINSTACK</code> is defined as 20, 2693280405Srpauloso that usually you do not have to worry about stack space 2694280405Srpaulounless your code has loops pushing elements onto the stack. 2695280405Srpaulo 2696280405Srpaulo 2697280405Srpaulo<p> 2698280405SrpauloWhen you call a Lua function 2699280405Srpaulowithout a fixed number of results (see <a href="#lua_call"><code>lua_call</code></a>), 2700280405SrpauloLua ensures that the stack has enough space for all results, 2701280405Srpaulobut it does not ensure any extra space. 2702280405SrpauloSo, before pushing anything in the stack after such a call 2703280405Srpauloyou should use <a href="#lua_checkstack"><code>lua_checkstack</code></a>. 2704280405Srpaulo 2705280405Srpaulo 2706280405Srpaulo 2707280405Srpaulo 2708280405Srpaulo 2709280405Srpaulo<h2>4.3 – <a name="4.3">Valid and Acceptable Indices</a></h2> 2710280405Srpaulo 2711280405Srpaulo<p> 2712280405SrpauloAny function in the API that receives stack indices 2713280405Srpauloworks only with <em>valid indices</em> or <em>acceptable indices</em>. 2714280405Srpaulo 2715280405Srpaulo 2716280405Srpaulo<p> 2717280405SrpauloA <em>valid index</em> is an index that refers to a 2718326344Simpposition that stores a modifiable Lua value. 2719326344SimpIt comprises stack indices between 1 and the stack top 2720326344Simp(<code>1 ≤ abs(index) ≤ top</code>) 2721280405Srpaulo 2722326344Simpplus <em>pseudo-indices</em>, 2723326344Simpwhich represent some positions that are accessible to C code 2724326344Simpbut that are not in the stack. 2725326344SimpPseudo-indices are used to access the registry (see <a href="#4.5">§4.5</a>) 2726280405Srpauloand the upvalues of a C function (see <a href="#4.4">§4.4</a>). 2727280405Srpaulo 2728280405Srpaulo 2729280405Srpaulo<p> 2730326344SimpFunctions that do not need a specific mutable position, 2731326344Simpbut only a value (e.g., query functions), 2732280405Srpaulocan be called with acceptable indices. 2733280405SrpauloAn <em>acceptable index</em> can be any valid index, 2734280405Srpaulobut it also can be any positive index after the stack top 2735280405Srpaulowithin the space allocated for the stack, 2736280405Srpaulothat is, indices up to the stack size. 2737280405Srpaulo(Note that 0 is never an acceptable index.) 2738280405SrpauloExcept when noted otherwise, 2739280405Srpaulofunctions in the API work with acceptable indices. 2740280405Srpaulo 2741280405Srpaulo 2742280405Srpaulo<p> 2743280405SrpauloAcceptable indices serve to avoid extra tests 2744280405Srpauloagainst the stack top when querying the stack. 2745280405SrpauloFor instance, a C function can query its third argument 2746280405Srpaulowithout the need to first check whether there is a third argument, 2747280405Srpaulothat is, without the need to check whether 3 is a valid index. 2748280405Srpaulo 2749280405Srpaulo 2750280405Srpaulo<p> 2751280405SrpauloFor functions that can be called with acceptable indices, 2752280405Srpauloany non-valid index is treated as if it 2753280405Srpaulocontains a value of a virtual type <a name="pdf-LUA_TNONE"><code>LUA_TNONE</code></a>, 2754280405Srpaulowhich behaves like a nil value. 2755280405Srpaulo 2756280405Srpaulo 2757280405Srpaulo 2758280405Srpaulo 2759280405Srpaulo 2760280405Srpaulo<h2>4.4 – <a name="4.4">C Closures</a></h2> 2761280405Srpaulo 2762280405Srpaulo<p> 2763280405SrpauloWhen a C function is created, 2764280405Srpauloit is possible to associate some values with it, 2765280405Srpaulothus creating a <em>C closure</em> 2766280405Srpaulo(see <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>); 2767280405Srpaulothese values are called <em>upvalues</em> and are 2768280405Srpauloaccessible to the function whenever it is called. 2769280405Srpaulo 2770280405Srpaulo 2771280405Srpaulo<p> 2772280405SrpauloWhenever a C function is called, 2773280405Srpauloits upvalues are located at specific pseudo-indices. 2774280405SrpauloThese pseudo-indices are produced by the macro 2775280405Srpaulo<a href="#lua_upvalueindex"><code>lua_upvalueindex</code></a>. 2776326344SimpThe first upvalue associated with a function is at index 2777280405Srpaulo<code>lua_upvalueindex(1)</code>, and so on. 2778280405SrpauloAny access to <code>lua_upvalueindex(<em>n</em>)</code>, 2779280405Srpaulowhere <em>n</em> is greater than the number of upvalues of the 2780326344Simpcurrent function 2781326344Simp(but not greater than 256, 2782326344Simpwhich is one plus the maximum number of upvalues in a closure), 2783280405Srpauloproduces an acceptable but invalid index. 2784280405Srpaulo 2785280405Srpaulo 2786280405Srpaulo 2787280405Srpaulo 2788280405Srpaulo 2789280405Srpaulo<h2>4.5 – <a name="4.5">Registry</a></h2> 2790280405Srpaulo 2791280405Srpaulo<p> 2792280405SrpauloLua provides a <em>registry</em>, 2793280405Srpauloa predefined table that can be used by any C code to 2794280405Srpaulostore whatever Lua values it needs to store. 2795280405SrpauloThe registry table is always located at pseudo-index 2796326344Simp<a name="pdf-LUA_REGISTRYINDEX"><code>LUA_REGISTRYINDEX</code></a>. 2797280405SrpauloAny C library can store data into this table, 2798280405Srpaulobut it must take care to choose keys 2799280405Srpaulothat are different from those used 2800280405Srpauloby other libraries, to avoid collisions. 2801280405SrpauloTypically, you should use as key a string containing your library name, 2802280405Srpauloor a light userdata with the address of a C object in your code, 2803280405Srpauloor any Lua object created by your code. 2804280405SrpauloAs with variable names, 2805280405Srpaulostring keys starting with an underscore followed by 2806280405Srpaulouppercase letters are reserved for Lua. 2807280405Srpaulo 2808280405Srpaulo 2809280405Srpaulo<p> 2810280405SrpauloThe integer keys in the registry are used 2811280405Srpauloby the reference mechanism (see <a href="#luaL_ref"><code>luaL_ref</code></a>) 2812280405Srpauloand by some predefined values. 2813280405SrpauloTherefore, integer keys must not be used for other purposes. 2814280405Srpaulo 2815280405Srpaulo 2816280405Srpaulo<p> 2817280405SrpauloWhen you create a new Lua state, 2818280405Srpauloits registry comes with some predefined values. 2819280405SrpauloThese predefined values are indexed with integer keys 2820280405Srpaulodefined as constants in <code>lua.h</code>. 2821280405SrpauloThe following constants are defined: 2822280405Srpaulo 2823280405Srpaulo<ul> 2824280405Srpaulo<li><b><a name="pdf-LUA_RIDX_MAINTHREAD"><code>LUA_RIDX_MAINTHREAD</code></a>: </b> At this index the registry has 2825280405Srpaulothe main thread of the state. 2826280405Srpaulo(The main thread is the one created together with the state.) 2827280405Srpaulo</li> 2828280405Srpaulo 2829280405Srpaulo<li><b><a name="pdf-LUA_RIDX_GLOBALS"><code>LUA_RIDX_GLOBALS</code></a>: </b> At this index the registry has 2830280405Srpaulothe global environment. 2831280405Srpaulo</li> 2832280405Srpaulo</ul> 2833280405Srpaulo 2834280405Srpaulo 2835280405Srpaulo 2836280405Srpaulo 2837280405Srpaulo<h2>4.6 – <a name="4.6">Error Handling in C</a></h2> 2838280405Srpaulo 2839280405Srpaulo<p> 2840280405SrpauloInternally, Lua uses the C <code>longjmp</code> facility to handle errors. 2841280405Srpaulo(Lua will use exceptions if you compile it as C++; 2842280405Srpaulosearch for <code>LUAI_THROW</code> in the source code for details.) 2843280405SrpauloWhen Lua faces any error 2844326344Simp(such as a memory allocation error or a type error) 2845280405Srpauloit <em>raises</em> an error; 2846280405Srpaulothat is, it does a long jump. 2847280405SrpauloA <em>protected environment</em> uses <code>setjmp</code> 2848280405Srpauloto set a recovery point; 2849280405Srpauloany error jumps to the most recent active recovery point. 2850280405Srpaulo 2851280405Srpaulo 2852280405Srpaulo<p> 2853326344SimpInside a C function you can raise an error by calling <a href="#lua_error"><code>lua_error</code></a>. 2854326344Simp 2855326344Simp 2856326344Simp<p> 2857326344SimpMost functions in the API can raise an error, 2858326344Simpfor instance due to a memory allocation error. 2859326344SimpThe documentation for each function indicates whether 2860326344Simpit can raise errors. 2861326344Simp 2862326344Simp 2863326344Simp<p> 2864280405SrpauloIf an error happens outside any protected environment, 2865280405SrpauloLua calls a <em>panic function</em> (see <a href="#lua_atpanic"><code>lua_atpanic</code></a>) 2866280405Srpauloand then calls <code>abort</code>, 2867280405Srpaulothus exiting the host application. 2868280405SrpauloYour panic function can avoid this exit by 2869280405Srpaulonever returning 2870280405Srpaulo(e.g., doing a long jump to your own recovery point outside Lua). 2871280405Srpaulo 2872280405Srpaulo 2873280405Srpaulo<p> 2874326344SimpThe panic function, 2875326344Simpas its name implies, 2876326344Simpis a mechanism of last resort. 2877326344SimpPrograms should avoid it. 2878326344SimpAs a general rule, 2879326344Simpwhen a C function is called by Lua with a Lua state, 2880326344Simpit can do whatever it wants on that Lua state, 2881326344Simpas it should be already protected. 2882326344SimpHowever, 2883326344Simpwhen C code operates on other Lua states 2884326344Simp(e.g., a Lua parameter to the function, 2885326344Simpa Lua state stored in the registry, or 2886326344Simpthe result of <a href="#lua_newthread"><code>lua_newthread</code></a>), 2887326344Simpit should use them only in API calls that cannot raise errors. 2888326344Simp 2889326344Simp 2890326344Simp<p> 2891280405SrpauloThe panic function runs as if it were a message handler (see <a href="#2.3">§2.3</a>); 2892326344Simpin particular, the error object is at the top of the stack. 2893280405SrpauloHowever, there is no guarantee about stack space. 2894280405SrpauloTo push anything on the stack, 2895280405Srpaulothe panic function must first check the available space (see <a href="#4.2">§4.2</a>). 2896280405Srpaulo 2897280405Srpaulo 2898280405Srpaulo 2899280405Srpaulo 2900280405Srpaulo 2901280405Srpaulo<h2>4.7 – <a name="4.7">Handling Yields in C</a></h2> 2902280405Srpaulo 2903280405Srpaulo<p> 2904280405SrpauloInternally, Lua uses the C <code>longjmp</code> facility to yield a coroutine. 2905326344SimpTherefore, if a C function <code>foo</code> calls an API function 2906280405Srpauloand this API function yields 2907280405Srpaulo(directly or indirectly by calling another function that yields), 2908280405SrpauloLua cannot return to <code>foo</code> any more, 2909280405Srpaulobecause the <code>longjmp</code> removes its frame from the C stack. 2910280405Srpaulo 2911280405Srpaulo 2912280405Srpaulo<p> 2913280405SrpauloTo avoid this kind of problem, 2914280405SrpauloLua raises an error whenever it tries to yield across an API call, 2915280405Srpauloexcept for three functions: 2916280405Srpaulo<a href="#lua_yieldk"><code>lua_yieldk</code></a>, <a href="#lua_callk"><code>lua_callk</code></a>, and <a href="#lua_pcallk"><code>lua_pcallk</code></a>. 2917280405SrpauloAll those functions receive a <em>continuation function</em> 2918280405Srpaulo(as a parameter named <code>k</code>) to continue execution after a yield. 2919280405Srpaulo 2920280405Srpaulo 2921280405Srpaulo<p> 2922280405SrpauloWe need to set some terminology to explain continuations. 2923326344SimpWe have a C function called from Lua which we will call 2924280405Srpaulothe <em>original function</em>. 2925280405SrpauloThis original function then calls one of those three functions in the C API, 2926280405Srpaulowhich we will call the <em>callee function</em>, 2927280405Srpaulothat then yields the current thread. 2928280405Srpaulo(This can happen when the callee function is <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 2929280405Srpauloor when the callee function is either <a href="#lua_callk"><code>lua_callk</code></a> or <a href="#lua_pcallk"><code>lua_pcallk</code></a> 2930280405Srpauloand the function called by them yields.) 2931280405Srpaulo 2932280405Srpaulo 2933280405Srpaulo<p> 2934280405SrpauloSuppose the running thread yields while executing the callee function. 2935280405SrpauloAfter the thread resumes, 2936280405Srpauloit eventually will finish running the callee function. 2937280405SrpauloHowever, 2938280405Srpaulothe callee function cannot return to the original function, 2939280405Srpaulobecause its frame in the C stack was destroyed by the yield. 2940280405SrpauloInstead, Lua calls a <em>continuation function</em>, 2941280405Srpaulowhich was given as an argument to the callee function. 2942280405SrpauloAs the name implies, 2943280405Srpaulothe continuation function should continue the task 2944280405Srpauloof the original function. 2945280405Srpaulo 2946280405Srpaulo 2947280405Srpaulo<p> 2948280405SrpauloAs an illustration, consider the following function: 2949280405Srpaulo 2950280405Srpaulo<pre> 2951280405Srpaulo int original_function (lua_State *L) { 2952280405Srpaulo ... /* code 1 */ 2953280405Srpaulo status = lua_pcall(L, n, m, h); /* calls Lua */ 2954280405Srpaulo ... /* code 2 */ 2955280405Srpaulo } 2956280405Srpaulo</pre><p> 2957280405SrpauloNow we want to allow 2958280405Srpaulothe Lua code being run by <a href="#lua_pcall"><code>lua_pcall</code></a> to yield. 2959280405SrpauloFirst, we can rewrite our function like here: 2960280405Srpaulo 2961280405Srpaulo<pre> 2962280405Srpaulo int k (lua_State *L, int status, lua_KContext ctx) { 2963280405Srpaulo ... /* code 2 */ 2964280405Srpaulo } 2965280405Srpaulo 2966280405Srpaulo int original_function (lua_State *L) { 2967280405Srpaulo ... /* code 1 */ 2968280405Srpaulo return k(L, lua_pcall(L, n, m, h), ctx); 2969280405Srpaulo } 2970280405Srpaulo</pre><p> 2971280405SrpauloIn the above code, 2972280405Srpaulothe new function <code>k</code> is a 2973280405Srpaulo<em>continuation function</em> (with type <a href="#lua_KFunction"><code>lua_KFunction</code></a>), 2974280405Srpaulowhich should do all the work that the original function 2975280405Srpaulowas doing after calling <a href="#lua_pcall"><code>lua_pcall</code></a>. 2976280405SrpauloNow, we must inform Lua that it must call <code>k</code> if the Lua code 2977280405Srpaulobeing executed by <a href="#lua_pcall"><code>lua_pcall</code></a> gets interrupted in some way 2978280405Srpaulo(errors or yielding), 2979280405Srpauloso we rewrite the code as here, 2980280405Srpauloreplacing <a href="#lua_pcall"><code>lua_pcall</code></a> by <a href="#lua_pcallk"><code>lua_pcallk</code></a>: 2981280405Srpaulo 2982280405Srpaulo<pre> 2983280405Srpaulo int original_function (lua_State *L) { 2984280405Srpaulo ... /* code 1 */ 2985280405Srpaulo return k(L, lua_pcallk(L, n, m, h, ctx2, k), ctx1); 2986280405Srpaulo } 2987280405Srpaulo</pre><p> 2988280405SrpauloNote the external, explicit call to the continuation: 2989280405SrpauloLua will call the continuation only if needed, that is, 2990280405Srpauloin case of errors or resuming after a yield. 2991280405SrpauloIf the called function returns normally without ever yielding, 2992280405Srpaulo<a href="#lua_pcallk"><code>lua_pcallk</code></a> (and <a href="#lua_callk"><code>lua_callk</code></a>) will also return normally. 2993280405Srpaulo(Of course, instead of calling the continuation in that case, 2994280405Srpauloyou can do the equivalent work directly inside the original function.) 2995280405Srpaulo 2996280405Srpaulo 2997280405Srpaulo<p> 2998280405SrpauloBesides the Lua state, 2999280405Srpaulothe continuation function has two other parameters: 3000280405Srpaulothe final status of the call plus the context value (<code>ctx</code>) that 3001280405Srpaulowas passed originally to <a href="#lua_pcallk"><code>lua_pcallk</code></a>. 3002280405Srpaulo(Lua does not use this context value; 3003280405Srpauloit only passes this value from the original function to the 3004280405Srpaulocontinuation function.) 3005280405SrpauloFor <a href="#lua_pcallk"><code>lua_pcallk</code></a>, 3006280405Srpaulothe status is the same value that would be returned by <a href="#lua_pcallk"><code>lua_pcallk</code></a>, 3007280405Srpauloexcept that it is <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when being executed after a yield 3008280405Srpaulo(instead of <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>). 3009280405SrpauloFor <a href="#lua_yieldk"><code>lua_yieldk</code></a> and <a href="#lua_callk"><code>lua_callk</code></a>, 3010280405Srpaulothe status is always <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when Lua calls the continuation. 3011280405Srpaulo(For these two functions, 3012280405SrpauloLua will not call the continuation in case of errors, 3013280405Srpaulobecause they do not handle errors.) 3014280405SrpauloSimilarly, when using <a href="#lua_callk"><code>lua_callk</code></a>, 3015280405Srpauloyou should call the continuation function 3016280405Srpaulowith <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> as the status. 3017280405Srpaulo(For <a href="#lua_yieldk"><code>lua_yieldk</code></a>, there is not much point in calling 3018280405Srpaulodirectly the continuation function, 3019280405Srpaulobecause <a href="#lua_yieldk"><code>lua_yieldk</code></a> usually does not return.) 3020280405Srpaulo 3021280405Srpaulo 3022280405Srpaulo<p> 3023280405SrpauloLua treats the continuation function as if it were the original function. 3024280405SrpauloThe continuation function receives the same Lua stack 3025280405Srpaulofrom the original function, 3026280405Srpauloin the same state it would be if the callee function had returned. 3027280405Srpaulo(For instance, 3028280405Srpauloafter a <a href="#lua_callk"><code>lua_callk</code></a> the function and its arguments are 3029280405Srpauloremoved from the stack and replaced by the results from the call.) 3030280405SrpauloIt also has the same upvalues. 3031280405SrpauloWhatever it returns is handled by Lua as if it were the return 3032280405Srpauloof the original function. 3033280405Srpaulo 3034280405Srpaulo 3035280405Srpaulo 3036280405Srpaulo 3037280405Srpaulo 3038280405Srpaulo<h2>4.8 – <a name="4.8">Functions and Types</a></h2> 3039280405Srpaulo 3040280405Srpaulo<p> 3041280405SrpauloHere we list all functions and types from the C API in 3042280405Srpauloalphabetical order. 3043280405SrpauloEach function has an indicator like this: 3044280405Srpaulo<span class="apii">[-o, +p, <em>x</em>]</span> 3045280405Srpaulo 3046280405Srpaulo 3047280405Srpaulo<p> 3048280405SrpauloThe first field, <code>o</code>, 3049280405Srpaulois how many elements the function pops from the stack. 3050280405SrpauloThe second field, <code>p</code>, 3051280405Srpaulois how many elements the function pushes onto the stack. 3052280405Srpaulo(Any function always pushes its results after popping its arguments.) 3053280405SrpauloA field in the form <code>x|y</code> means the function can push (or pop) 3054280405Srpaulo<code>x</code> or <code>y</code> elements, 3055280405Srpaulodepending on the situation; 3056280405Srpauloan interrogation mark '<code>?</code>' means that 3057280405Srpaulowe cannot know how many elements the function pops/pushes 3058280405Srpauloby looking only at its arguments 3059280405Srpaulo(e.g., they may depend on what is on the stack). 3060280405SrpauloThe third field, <code>x</code>, 3061280405Srpaulotells whether the function may raise errors: 3062280405Srpaulo'<code>-</code>' means the function never raises any error; 3063326344Simp'<code>m</code>' means the function may raise out-of-memory errors 3064326344Simpand errors running a <code>__gc</code> metamethod; 3065326344Simp'<code>e</code>' means the function may raise any errors 3066326344Simp(it can run arbitrary Lua code, 3067326344Simpeither directly or through metamethods); 3068280405Srpaulo'<code>v</code>' means the function may raise an error on purpose. 3069280405Srpaulo 3070280405Srpaulo 3071280405Srpaulo 3072280405Srpaulo<hr><h3><a name="lua_absindex"><code>lua_absindex</code></a></h3><p> 3073280405Srpaulo<span class="apii">[-0, +0, –]</span> 3074280405Srpaulo<pre>int lua_absindex (lua_State *L, int idx);</pre> 3075280405Srpaulo 3076280405Srpaulo<p> 3077326344SimpConverts the acceptable index <code>idx</code> 3078326344Simpinto an equivalent absolute index 3079280405Srpaulo(that is, one that does not depend on the stack top). 3080280405Srpaulo 3081280405Srpaulo 3082280405Srpaulo 3083280405Srpaulo 3084280405Srpaulo 3085280405Srpaulo<hr><h3><a name="lua_Alloc"><code>lua_Alloc</code></a></h3> 3086280405Srpaulo<pre>typedef void * (*lua_Alloc) (void *ud, 3087280405Srpaulo void *ptr, 3088280405Srpaulo size_t osize, 3089280405Srpaulo size_t nsize);</pre> 3090280405Srpaulo 3091280405Srpaulo<p> 3092280405SrpauloThe type of the memory-allocation function used by Lua states. 3093280405SrpauloThe allocator function must provide a 3094280405Srpaulofunctionality similar to <code>realloc</code>, 3095280405Srpaulobut not exactly the same. 3096280405SrpauloIts arguments are 3097280405Srpaulo<code>ud</code>, an opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>; 3098280405Srpaulo<code>ptr</code>, a pointer to the block being allocated/reallocated/freed; 3099280405Srpaulo<code>osize</code>, the original size of the block or some code about what 3100280405Srpaulois being allocated; 3101280405Srpauloand <code>nsize</code>, the new size of the block. 3102280405Srpaulo 3103280405Srpaulo 3104280405Srpaulo<p> 3105280405SrpauloWhen <code>ptr</code> is not <code>NULL</code>, 3106280405Srpaulo<code>osize</code> is the size of the block pointed by <code>ptr</code>, 3107280405Srpaulothat is, the size given when it was allocated or reallocated. 3108280405Srpaulo 3109280405Srpaulo 3110280405Srpaulo<p> 3111280405SrpauloWhen <code>ptr</code> is <code>NULL</code>, 3112280405Srpaulo<code>osize</code> encodes the kind of object that Lua is allocating. 3113280405Srpaulo<code>osize</code> is any of 3114280405Srpaulo<a href="#pdf-LUA_TSTRING"><code>LUA_TSTRING</code></a>, <a href="#pdf-LUA_TTABLE"><code>LUA_TTABLE</code></a>, <a href="#pdf-LUA_TFUNCTION"><code>LUA_TFUNCTION</code></a>, 3115280405Srpaulo<a href="#pdf-LUA_TUSERDATA"><code>LUA_TUSERDATA</code></a>, or <a href="#pdf-LUA_TTHREAD"><code>LUA_TTHREAD</code></a> when (and only when) 3116280405SrpauloLua is creating a new object of that type. 3117280405SrpauloWhen <code>osize</code> is some other value, 3118280405SrpauloLua is allocating memory for something else. 3119280405Srpaulo 3120280405Srpaulo 3121280405Srpaulo<p> 3122280405SrpauloLua assumes the following behavior from the allocator function: 3123280405Srpaulo 3124280405Srpaulo 3125280405Srpaulo<p> 3126280405SrpauloWhen <code>nsize</code> is zero, 3127280405Srpaulothe allocator must behave like <code>free</code> 3128280405Srpauloand return <code>NULL</code>. 3129280405Srpaulo 3130280405Srpaulo 3131280405Srpaulo<p> 3132280405SrpauloWhen <code>nsize</code> is not zero, 3133280405Srpaulothe allocator must behave like <code>realloc</code>. 3134280405SrpauloThe allocator returns <code>NULL</code> 3135280405Srpauloif and only if it cannot fulfill the request. 3136280405SrpauloLua assumes that the allocator never fails when 3137280405Srpaulo<code>osize >= nsize</code>. 3138280405Srpaulo 3139280405Srpaulo 3140280405Srpaulo<p> 3141280405SrpauloHere is a simple implementation for the allocator function. 3142280405SrpauloIt is used in the auxiliary library by <a href="#luaL_newstate"><code>luaL_newstate</code></a>. 3143280405Srpaulo 3144280405Srpaulo<pre> 3145280405Srpaulo static void *l_alloc (void *ud, void *ptr, size_t osize, 3146280405Srpaulo size_t nsize) { 3147280405Srpaulo (void)ud; (void)osize; /* not used */ 3148280405Srpaulo if (nsize == 0) { 3149280405Srpaulo free(ptr); 3150280405Srpaulo return NULL; 3151280405Srpaulo } 3152280405Srpaulo else 3153280405Srpaulo return realloc(ptr, nsize); 3154280405Srpaulo } 3155280405Srpaulo</pre><p> 3156280405SrpauloNote that Standard C ensures 3157280405Srpaulothat <code>free(NULL)</code> has no effect and that 3158280405Srpaulo<code>realloc(NULL,size)</code> is equivalent to <code>malloc(size)</code>. 3159280405SrpauloThis code assumes that <code>realloc</code> does not fail when shrinking a block. 3160280405Srpaulo(Although Standard C does not ensure this behavior, 3161280405Srpauloit seems to be a safe assumption.) 3162280405Srpaulo 3163280405Srpaulo 3164280405Srpaulo 3165280405Srpaulo 3166280405Srpaulo 3167280405Srpaulo<hr><h3><a name="lua_arith"><code>lua_arith</code></a></h3><p> 3168280405Srpaulo<span class="apii">[-(2|1), +1, <em>e</em>]</span> 3169280405Srpaulo<pre>void lua_arith (lua_State *L, int op);</pre> 3170280405Srpaulo 3171280405Srpaulo<p> 3172280405SrpauloPerforms an arithmetic or bitwise operation over the two values 3173280405Srpaulo(or one, in the case of negations) 3174280405Srpauloat the top of the stack, 3175280405Srpaulowith the value at the top being the second operand, 3176280405Srpaulopops these values, and pushes the result of the operation. 3177280405SrpauloThe function follows the semantics of the corresponding Lua operator 3178280405Srpaulo(that is, it may call metamethods). 3179280405Srpaulo 3180280405Srpaulo 3181280405Srpaulo<p> 3182280405SrpauloThe value of <code>op</code> must be one of the following constants: 3183280405Srpaulo 3184280405Srpaulo<ul> 3185280405Srpaulo 3186280405Srpaulo<li><b><a name="pdf-LUA_OPADD"><code>LUA_OPADD</code></a>: </b> performs addition (<code>+</code>)</li> 3187280405Srpaulo<li><b><a name="pdf-LUA_OPSUB"><code>LUA_OPSUB</code></a>: </b> performs subtraction (<code>-</code>)</li> 3188280405Srpaulo<li><b><a name="pdf-LUA_OPMUL"><code>LUA_OPMUL</code></a>: </b> performs multiplication (<code>*</code>)</li> 3189280405Srpaulo<li><b><a name="pdf-LUA_OPDIV"><code>LUA_OPDIV</code></a>: </b> performs float division (<code>/</code>)</li> 3190280405Srpaulo<li><b><a name="pdf-LUA_OPIDIV"><code>LUA_OPIDIV</code></a>: </b> performs floor division (<code>//</code>)</li> 3191280405Srpaulo<li><b><a name="pdf-LUA_OPMOD"><code>LUA_OPMOD</code></a>: </b> performs modulo (<code>%</code>)</li> 3192280405Srpaulo<li><b><a name="pdf-LUA_OPPOW"><code>LUA_OPPOW</code></a>: </b> performs exponentiation (<code>^</code>)</li> 3193280405Srpaulo<li><b><a name="pdf-LUA_OPUNM"><code>LUA_OPUNM</code></a>: </b> performs mathematical negation (unary <code>-</code>)</li> 3194326344Simp<li><b><a name="pdf-LUA_OPBNOT"><code>LUA_OPBNOT</code></a>: </b> performs bitwise NOT (<code>~</code>)</li> 3195326344Simp<li><b><a name="pdf-LUA_OPBAND"><code>LUA_OPBAND</code></a>: </b> performs bitwise AND (<code>&</code>)</li> 3196326344Simp<li><b><a name="pdf-LUA_OPBOR"><code>LUA_OPBOR</code></a>: </b> performs bitwise OR (<code>|</code>)</li> 3197326344Simp<li><b><a name="pdf-LUA_OPBXOR"><code>LUA_OPBXOR</code></a>: </b> performs bitwise exclusive OR (<code>~</code>)</li> 3198280405Srpaulo<li><b><a name="pdf-LUA_OPSHL"><code>LUA_OPSHL</code></a>: </b> performs left shift (<code><<</code>)</li> 3199280405Srpaulo<li><b><a name="pdf-LUA_OPSHR"><code>LUA_OPSHR</code></a>: </b> performs right shift (<code>>></code>)</li> 3200280405Srpaulo 3201280405Srpaulo</ul> 3202280405Srpaulo 3203280405Srpaulo 3204280405Srpaulo 3205280405Srpaulo 3206280405Srpaulo<hr><h3><a name="lua_atpanic"><code>lua_atpanic</code></a></h3><p> 3207280405Srpaulo<span class="apii">[-0, +0, –]</span> 3208280405Srpaulo<pre>lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);</pre> 3209280405Srpaulo 3210280405Srpaulo<p> 3211280405SrpauloSets a new panic function and returns the old one (see <a href="#4.6">§4.6</a>). 3212280405Srpaulo 3213280405Srpaulo 3214280405Srpaulo 3215280405Srpaulo 3216280405Srpaulo 3217280405Srpaulo<hr><h3><a name="lua_call"><code>lua_call</code></a></h3><p> 3218280405Srpaulo<span class="apii">[-(nargs+1), +nresults, <em>e</em>]</span> 3219280405Srpaulo<pre>void lua_call (lua_State *L, int nargs, int nresults);</pre> 3220280405Srpaulo 3221280405Srpaulo<p> 3222280405SrpauloCalls a function. 3223280405Srpaulo 3224280405Srpaulo 3225280405Srpaulo<p> 3226280405SrpauloTo call a function you must use the following protocol: 3227280405Srpaulofirst, the function to be called is pushed onto the stack; 3228280405Srpaulothen, the arguments to the function are pushed 3229280405Srpauloin direct order; 3230280405Srpaulothat is, the first argument is pushed first. 3231280405SrpauloFinally you call <a href="#lua_call"><code>lua_call</code></a>; 3232280405Srpaulo<code>nargs</code> is the number of arguments that you pushed onto the stack. 3233280405SrpauloAll arguments and the function value are popped from the stack 3234280405Srpaulowhen the function is called. 3235280405SrpauloThe function results are pushed onto the stack when the function returns. 3236280405SrpauloThe number of results is adjusted to <code>nresults</code>, 3237280405Srpaulounless <code>nresults</code> is <a name="pdf-LUA_MULTRET"><code>LUA_MULTRET</code></a>. 3238326344SimpIn this case, all results from the function are pushed; 3239326344SimpLua takes care that the returned values fit into the stack space, 3240326344Simpbut it does not ensure any extra space in the stack. 3241280405SrpauloThe function results are pushed onto the stack in direct order 3242280405Srpaulo(the first result is pushed first), 3243280405Srpauloso that after the call the last result is on the top of the stack. 3244280405Srpaulo 3245280405Srpaulo 3246280405Srpaulo<p> 3247280405SrpauloAny error inside the called function is propagated upwards 3248280405Srpaulo(with a <code>longjmp</code>). 3249280405Srpaulo 3250280405Srpaulo 3251280405Srpaulo<p> 3252280405SrpauloThe following example shows how the host program can do the 3253280405Srpauloequivalent to this Lua code: 3254280405Srpaulo 3255280405Srpaulo<pre> 3256280405Srpaulo a = f("how", t.x, 14) 3257280405Srpaulo</pre><p> 3258280405SrpauloHere it is in C: 3259280405Srpaulo 3260280405Srpaulo<pre> 3261280405Srpaulo lua_getglobal(L, "f"); /* function to be called */ 3262280405Srpaulo lua_pushliteral(L, "how"); /* 1st argument */ 3263280405Srpaulo lua_getglobal(L, "t"); /* table to be indexed */ 3264280405Srpaulo lua_getfield(L, -1, "x"); /* push result of t.x (2nd arg) */ 3265280405Srpaulo lua_remove(L, -2); /* remove 't' from the stack */ 3266280405Srpaulo lua_pushinteger(L, 14); /* 3rd argument */ 3267280405Srpaulo lua_call(L, 3, 1); /* call 'f' with 3 arguments and 1 result */ 3268280405Srpaulo lua_setglobal(L, "a"); /* set global 'a' */ 3269280405Srpaulo</pre><p> 3270280405SrpauloNote that the code above is <em>balanced</em>: 3271280405Srpauloat its end, the stack is back to its original configuration. 3272280405SrpauloThis is considered good programming practice. 3273280405Srpaulo 3274280405Srpaulo 3275280405Srpaulo 3276280405Srpaulo 3277280405Srpaulo 3278280405Srpaulo<hr><h3><a name="lua_callk"><code>lua_callk</code></a></h3><p> 3279280405Srpaulo<span class="apii">[-(nargs + 1), +nresults, <em>e</em>]</span> 3280280405Srpaulo<pre>void lua_callk (lua_State *L, 3281280405Srpaulo int nargs, 3282280405Srpaulo int nresults, 3283280405Srpaulo lua_KContext ctx, 3284280405Srpaulo lua_KFunction k);</pre> 3285280405Srpaulo 3286280405Srpaulo<p> 3287280405SrpauloThis function behaves exactly like <a href="#lua_call"><code>lua_call</code></a>, 3288280405Srpaulobut allows the called function to yield (see <a href="#4.7">§4.7</a>). 3289280405Srpaulo 3290280405Srpaulo 3291280405Srpaulo 3292280405Srpaulo 3293280405Srpaulo 3294280405Srpaulo<hr><h3><a name="lua_CFunction"><code>lua_CFunction</code></a></h3> 3295280405Srpaulo<pre>typedef int (*lua_CFunction) (lua_State *L);</pre> 3296280405Srpaulo 3297280405Srpaulo<p> 3298280405SrpauloType for C functions. 3299280405Srpaulo 3300280405Srpaulo 3301280405Srpaulo<p> 3302280405SrpauloIn order to communicate properly with Lua, 3303280405Srpauloa C function must use the following protocol, 3304280405Srpaulowhich defines the way parameters and results are passed: 3305280405Srpauloa C function receives its arguments from Lua in its stack 3306280405Srpauloin direct order (the first argument is pushed first). 3307280405SrpauloSo, when the function starts, 3308280405Srpaulo<code>lua_gettop(L)</code> returns the number of arguments received by the function. 3309280405SrpauloThe first argument (if any) is at index 1 3310280405Srpauloand its last argument is at index <code>lua_gettop(L)</code>. 3311280405SrpauloTo return values to Lua, a C function just pushes them onto the stack, 3312280405Srpauloin direct order (the first result is pushed first), 3313280405Srpauloand returns the number of results. 3314280405SrpauloAny other value in the stack below the results will be properly 3315280405Srpaulodiscarded by Lua. 3316280405SrpauloLike a Lua function, a C function called by Lua can also return 3317280405Srpaulomany results. 3318280405Srpaulo 3319280405Srpaulo 3320280405Srpaulo<p> 3321280405SrpauloAs an example, the following function receives a variable number 3322326344Simpof numeric arguments and returns their average and their sum: 3323280405Srpaulo 3324280405Srpaulo<pre> 3325280405Srpaulo static int foo (lua_State *L) { 3326280405Srpaulo int n = lua_gettop(L); /* number of arguments */ 3327280405Srpaulo lua_Number sum = 0.0; 3328280405Srpaulo int i; 3329280405Srpaulo for (i = 1; i <= n; i++) { 3330280405Srpaulo if (!lua_isnumber(L, i)) { 3331280405Srpaulo lua_pushliteral(L, "incorrect argument"); 3332280405Srpaulo lua_error(L); 3333280405Srpaulo } 3334280405Srpaulo sum += lua_tonumber(L, i); 3335280405Srpaulo } 3336280405Srpaulo lua_pushnumber(L, sum/n); /* first result */ 3337280405Srpaulo lua_pushnumber(L, sum); /* second result */ 3338280405Srpaulo return 2; /* number of results */ 3339280405Srpaulo } 3340280405Srpaulo</pre> 3341280405Srpaulo 3342280405Srpaulo 3343280405Srpaulo 3344280405Srpaulo 3345280405Srpaulo<hr><h3><a name="lua_checkstack"><code>lua_checkstack</code></a></h3><p> 3346280405Srpaulo<span class="apii">[-0, +0, –]</span> 3347280405Srpaulo<pre>int lua_checkstack (lua_State *L, int n);</pre> 3348280405Srpaulo 3349280405Srpaulo<p> 3350326344SimpEnsures that the stack has space for at least <code>n</code> extra slots 3351326344Simp(that is, that you can safely push up to <code>n</code> values into it). 3352280405SrpauloIt returns false if it cannot fulfill the request, 3353280405Srpauloeither because it would cause the stack 3354280405Srpauloto be larger than a fixed maximum size 3355280405Srpaulo(typically at least several thousand elements) or 3356280405Srpaulobecause it cannot allocate memory for the extra space. 3357280405SrpauloThis function never shrinks the stack; 3358326344Simpif the stack already has space for the extra slots, 3359280405Srpauloit is left unchanged. 3360280405Srpaulo 3361280405Srpaulo 3362280405Srpaulo 3363280405Srpaulo 3364280405Srpaulo 3365280405Srpaulo<hr><h3><a name="lua_close"><code>lua_close</code></a></h3><p> 3366280405Srpaulo<span class="apii">[-0, +0, –]</span> 3367280405Srpaulo<pre>void lua_close (lua_State *L);</pre> 3368280405Srpaulo 3369280405Srpaulo<p> 3370280405SrpauloDestroys all objects in the given Lua state 3371280405Srpaulo(calling the corresponding garbage-collection metamethods, if any) 3372280405Srpauloand frees all dynamic memory used by this state. 3373280405SrpauloOn several platforms, you may not need to call this function, 3374280405Srpaulobecause all resources are naturally released when the host program ends. 3375280405SrpauloOn the other hand, long-running programs that create multiple states, 3376280405Srpaulosuch as daemons or web servers, 3377280405Srpaulowill probably need to close states as soon as they are not needed. 3378280405Srpaulo 3379280405Srpaulo 3380280405Srpaulo 3381280405Srpaulo 3382280405Srpaulo 3383280405Srpaulo<hr><h3><a name="lua_compare"><code>lua_compare</code></a></h3><p> 3384280405Srpaulo<span class="apii">[-0, +0, <em>e</em>]</span> 3385280405Srpaulo<pre>int lua_compare (lua_State *L, int index1, int index2, int op);</pre> 3386280405Srpaulo 3387280405Srpaulo<p> 3388280405SrpauloCompares two Lua values. 3389280405SrpauloReturns 1 if the value at index <code>index1</code> satisfies <code>op</code> 3390280405Srpaulowhen compared with the value at index <code>index2</code>, 3391280405Srpaulofollowing the semantics of the corresponding Lua operator 3392280405Srpaulo(that is, it may call metamethods). 3393280405SrpauloOtherwise returns 0. 3394280405SrpauloAlso returns 0 if any of the indices is not valid. 3395280405Srpaulo 3396280405Srpaulo 3397280405Srpaulo<p> 3398280405SrpauloThe value of <code>op</code> must be one of the following constants: 3399280405Srpaulo 3400280405Srpaulo<ul> 3401280405Srpaulo 3402280405Srpaulo<li><b><a name="pdf-LUA_OPEQ"><code>LUA_OPEQ</code></a>: </b> compares for equality (<code>==</code>)</li> 3403280405Srpaulo<li><b><a name="pdf-LUA_OPLT"><code>LUA_OPLT</code></a>: </b> compares for less than (<code><</code>)</li> 3404280405Srpaulo<li><b><a name="pdf-LUA_OPLE"><code>LUA_OPLE</code></a>: </b> compares for less or equal (<code><=</code>)</li> 3405280405Srpaulo 3406280405Srpaulo</ul> 3407280405Srpaulo 3408280405Srpaulo 3409280405Srpaulo 3410280405Srpaulo 3411280405Srpaulo<hr><h3><a name="lua_concat"><code>lua_concat</code></a></h3><p> 3412280405Srpaulo<span class="apii">[-n, +1, <em>e</em>]</span> 3413280405Srpaulo<pre>void lua_concat (lua_State *L, int n);</pre> 3414280405Srpaulo 3415280405Srpaulo<p> 3416280405SrpauloConcatenates the <code>n</code> values at the top of the stack, 3417280405Srpaulopops them, and leaves the result at the top. 3418280405SrpauloIf <code>n</code> is 1, the result is the single value on the stack 3419280405Srpaulo(that is, the function does nothing); 3420280405Srpauloif <code>n</code> is 0, the result is the empty string. 3421280405SrpauloConcatenation is performed following the usual semantics of Lua 3422280405Srpaulo(see <a href="#3.4.6">§3.4.6</a>). 3423280405Srpaulo 3424280405Srpaulo 3425280405Srpaulo 3426280405Srpaulo 3427280405Srpaulo 3428280405Srpaulo<hr><h3><a name="lua_copy"><code>lua_copy</code></a></h3><p> 3429280405Srpaulo<span class="apii">[-0, +0, –]</span> 3430280405Srpaulo<pre>void lua_copy (lua_State *L, int fromidx, int toidx);</pre> 3431280405Srpaulo 3432280405Srpaulo<p> 3433280405SrpauloCopies the element at index <code>fromidx</code> 3434280405Srpaulointo the valid index <code>toidx</code>, 3435280405Srpauloreplacing the value at that position. 3436280405SrpauloValues at other positions are not affected. 3437280405Srpaulo 3438280405Srpaulo 3439280405Srpaulo 3440280405Srpaulo 3441280405Srpaulo 3442280405Srpaulo<hr><h3><a name="lua_createtable"><code>lua_createtable</code></a></h3><p> 3443326344Simp<span class="apii">[-0, +1, <em>m</em>]</span> 3444280405Srpaulo<pre>void lua_createtable (lua_State *L, int narr, int nrec);</pre> 3445280405Srpaulo 3446280405Srpaulo<p> 3447280405SrpauloCreates a new empty table and pushes it onto the stack. 3448280405SrpauloParameter <code>narr</code> is a hint for how many elements the table 3449280405Srpaulowill have as a sequence; 3450280405Srpauloparameter <code>nrec</code> is a hint for how many other elements 3451280405Srpaulothe table will have. 3452280405SrpauloLua may use these hints to preallocate memory for the new table. 3453326344SimpThis preallocation is useful for performance when you know in advance 3454280405Srpaulohow many elements the table will have. 3455280405SrpauloOtherwise you can use the function <a href="#lua_newtable"><code>lua_newtable</code></a>. 3456280405Srpaulo 3457280405Srpaulo 3458280405Srpaulo 3459280405Srpaulo 3460280405Srpaulo 3461280405Srpaulo<hr><h3><a name="lua_dump"><code>lua_dump</code></a></h3><p> 3462326344Simp<span class="apii">[-0, +0, –]</span> 3463280405Srpaulo<pre>int lua_dump (lua_State *L, 3464280405Srpaulo lua_Writer writer, 3465280405Srpaulo void *data, 3466280405Srpaulo int strip);</pre> 3467280405Srpaulo 3468280405Srpaulo<p> 3469280405SrpauloDumps a function as a binary chunk. 3470280405SrpauloReceives a Lua function on the top of the stack 3471280405Srpauloand produces a binary chunk that, 3472280405Srpauloif loaded again, 3473280405Srpauloresults in a function equivalent to the one dumped. 3474280405SrpauloAs it produces parts of the chunk, 3475280405Srpaulo<a href="#lua_dump"><code>lua_dump</code></a> calls function <code>writer</code> (see <a href="#lua_Writer"><code>lua_Writer</code></a>) 3476280405Srpaulowith the given <code>data</code> 3477280405Srpauloto write them. 3478280405Srpaulo 3479280405Srpaulo 3480280405Srpaulo<p> 3481280405SrpauloIf <code>strip</code> is true, 3482326344Simpthe binary representation may not include all debug information 3483326344Simpabout the function, 3484326344Simpto save space. 3485280405Srpaulo 3486280405Srpaulo 3487280405Srpaulo<p> 3488280405SrpauloThe value returned is the error code returned by the last 3489280405Srpaulocall to the writer; 3490280405Srpaulo0 means no errors. 3491280405Srpaulo 3492280405Srpaulo 3493280405Srpaulo<p> 3494280405SrpauloThis function does not pop the Lua function from the stack. 3495280405Srpaulo 3496280405Srpaulo 3497280405Srpaulo 3498280405Srpaulo 3499280405Srpaulo 3500280405Srpaulo<hr><h3><a name="lua_error"><code>lua_error</code></a></h3><p> 3501280405Srpaulo<span class="apii">[-1, +0, <em>v</em>]</span> 3502280405Srpaulo<pre>int lua_error (lua_State *L);</pre> 3503280405Srpaulo 3504280405Srpaulo<p> 3505280405SrpauloGenerates a Lua error, 3506280405Srpaulousing the value at the top of the stack as the error object. 3507280405SrpauloThis function does a long jump, 3508280405Srpauloand therefore never returns 3509280405Srpaulo(see <a href="#luaL_error"><code>luaL_error</code></a>). 3510280405Srpaulo 3511280405Srpaulo 3512280405Srpaulo 3513280405Srpaulo 3514280405Srpaulo 3515280405Srpaulo<hr><h3><a name="lua_gc"><code>lua_gc</code></a></h3><p> 3516326344Simp<span class="apii">[-0, +0, <em>m</em>]</span> 3517280405Srpaulo<pre>int lua_gc (lua_State *L, int what, int data);</pre> 3518280405Srpaulo 3519280405Srpaulo<p> 3520280405SrpauloControls the garbage collector. 3521280405Srpaulo 3522280405Srpaulo 3523280405Srpaulo<p> 3524280405SrpauloThis function performs several tasks, 3525280405Srpauloaccording to the value of the parameter <code>what</code>: 3526280405Srpaulo 3527280405Srpaulo<ul> 3528280405Srpaulo 3529280405Srpaulo<li><b><code>LUA_GCSTOP</code>: </b> 3530280405Srpaulostops the garbage collector. 3531280405Srpaulo</li> 3532280405Srpaulo 3533280405Srpaulo<li><b><code>LUA_GCRESTART</code>: </b> 3534280405Srpaulorestarts the garbage collector. 3535280405Srpaulo</li> 3536280405Srpaulo 3537280405Srpaulo<li><b><code>LUA_GCCOLLECT</code>: </b> 3538280405Srpauloperforms a full garbage-collection cycle. 3539280405Srpaulo</li> 3540280405Srpaulo 3541280405Srpaulo<li><b><code>LUA_GCCOUNT</code>: </b> 3542280405Srpauloreturns the current amount of memory (in Kbytes) in use by Lua. 3543280405Srpaulo</li> 3544280405Srpaulo 3545280405Srpaulo<li><b><code>LUA_GCCOUNTB</code>: </b> 3546280405Srpauloreturns the remainder of dividing the current amount of bytes of 3547280405Srpaulomemory in use by Lua by 1024. 3548280405Srpaulo</li> 3549280405Srpaulo 3550280405Srpaulo<li><b><code>LUA_GCSTEP</code>: </b> 3551280405Srpauloperforms an incremental step of garbage collection. 3552280405Srpaulo</li> 3553280405Srpaulo 3554280405Srpaulo<li><b><code>LUA_GCSETPAUSE</code>: </b> 3555280405Srpaulosets <code>data</code> as the new value 3556280405Srpaulofor the <em>pause</em> of the collector (see <a href="#2.5">§2.5</a>) 3557280405Srpauloand returns the previous value of the pause. 3558280405Srpaulo</li> 3559280405Srpaulo 3560280405Srpaulo<li><b><code>LUA_GCSETSTEPMUL</code>: </b> 3561280405Srpaulosets <code>data</code> as the new value for the <em>step multiplier</em> of 3562280405Srpaulothe collector (see <a href="#2.5">§2.5</a>) 3563280405Srpauloand returns the previous value of the step multiplier. 3564280405Srpaulo</li> 3565280405Srpaulo 3566280405Srpaulo<li><b><code>LUA_GCISRUNNING</code>: </b> 3567280405Srpauloreturns a boolean that tells whether the collector is running 3568280405Srpaulo(i.e., not stopped). 3569280405Srpaulo</li> 3570280405Srpaulo 3571280405Srpaulo</ul> 3572280405Srpaulo 3573280405Srpaulo<p> 3574280405SrpauloFor more details about these options, 3575280405Srpaulosee <a href="#pdf-collectgarbage"><code>collectgarbage</code></a>. 3576280405Srpaulo 3577280405Srpaulo 3578280405Srpaulo 3579280405Srpaulo 3580280405Srpaulo 3581280405Srpaulo<hr><h3><a name="lua_getallocf"><code>lua_getallocf</code></a></h3><p> 3582280405Srpaulo<span class="apii">[-0, +0, –]</span> 3583280405Srpaulo<pre>lua_Alloc lua_getallocf (lua_State *L, void **ud);</pre> 3584280405Srpaulo 3585280405Srpaulo<p> 3586280405SrpauloReturns the memory-allocation function of a given state. 3587280405SrpauloIf <code>ud</code> is not <code>NULL</code>, Lua stores in <code>*ud</code> the 3588280405Srpauloopaque pointer given when the memory-allocator function was set. 3589280405Srpaulo 3590280405Srpaulo 3591280405Srpaulo 3592280405Srpaulo 3593280405Srpaulo 3594280405Srpaulo<hr><h3><a name="lua_getfield"><code>lua_getfield</code></a></h3><p> 3595280405Srpaulo<span class="apii">[-0, +1, <em>e</em>]</span> 3596280405Srpaulo<pre>int lua_getfield (lua_State *L, int index, const char *k);</pre> 3597280405Srpaulo 3598280405Srpaulo<p> 3599280405SrpauloPushes onto the stack the value <code>t[k]</code>, 3600280405Srpaulowhere <code>t</code> is the value at the given index. 3601280405SrpauloAs in Lua, this function may trigger a metamethod 3602280405Srpaulofor the "index" event (see <a href="#2.4">§2.4</a>). 3603280405Srpaulo 3604280405Srpaulo 3605280405Srpaulo<p> 3606280405SrpauloReturns the type of the pushed value. 3607280405Srpaulo 3608280405Srpaulo 3609280405Srpaulo 3610280405Srpaulo 3611280405Srpaulo 3612280405Srpaulo<hr><h3><a name="lua_getextraspace"><code>lua_getextraspace</code></a></h3><p> 3613280405Srpaulo<span class="apii">[-0, +0, –]</span> 3614280405Srpaulo<pre>void *lua_getextraspace (lua_State *L);</pre> 3615280405Srpaulo 3616280405Srpaulo<p> 3617280405SrpauloReturns a pointer to a raw memory area associated with the 3618280405Srpaulogiven Lua state. 3619280405SrpauloThe application can use this area for any purpose; 3620280405SrpauloLua does not use it for anything. 3621280405Srpaulo 3622280405Srpaulo 3623280405Srpaulo<p> 3624280405SrpauloEach new thread has this area initialized with a copy 3625280405Srpauloof the area of the main thread. 3626280405Srpaulo 3627280405Srpaulo 3628280405Srpaulo<p> 3629280405SrpauloBy default, this area has the size of a pointer to void, 3630280405Srpaulobut you can recompile Lua with a different size for this area. 3631280405Srpaulo(See <code>LUA_EXTRASPACE</code> in <code>luaconf.h</code>.) 3632280405Srpaulo 3633280405Srpaulo 3634280405Srpaulo 3635280405Srpaulo 3636280405Srpaulo 3637280405Srpaulo<hr><h3><a name="lua_getglobal"><code>lua_getglobal</code></a></h3><p> 3638280405Srpaulo<span class="apii">[-0, +1, <em>e</em>]</span> 3639280405Srpaulo<pre>int lua_getglobal (lua_State *L, const char *name);</pre> 3640280405Srpaulo 3641280405Srpaulo<p> 3642280405SrpauloPushes onto the stack the value of the global <code>name</code>. 3643280405SrpauloReturns the type of that value. 3644280405Srpaulo 3645280405Srpaulo 3646280405Srpaulo 3647280405Srpaulo 3648280405Srpaulo 3649280405Srpaulo<hr><h3><a name="lua_geti"><code>lua_geti</code></a></h3><p> 3650280405Srpaulo<span class="apii">[-0, +1, <em>e</em>]</span> 3651280405Srpaulo<pre>int lua_geti (lua_State *L, int index, lua_Integer i);</pre> 3652280405Srpaulo 3653280405Srpaulo<p> 3654280405SrpauloPushes onto the stack the value <code>t[i]</code>, 3655280405Srpaulowhere <code>t</code> is the value at the given index. 3656280405SrpauloAs in Lua, this function may trigger a metamethod 3657280405Srpaulofor the "index" event (see <a href="#2.4">§2.4</a>). 3658280405Srpaulo 3659280405Srpaulo 3660280405Srpaulo<p> 3661280405SrpauloReturns the type of the pushed value. 3662280405Srpaulo 3663280405Srpaulo 3664280405Srpaulo 3665280405Srpaulo 3666280405Srpaulo 3667280405Srpaulo<hr><h3><a name="lua_getmetatable"><code>lua_getmetatable</code></a></h3><p> 3668280405Srpaulo<span class="apii">[-0, +(0|1), –]</span> 3669280405Srpaulo<pre>int lua_getmetatable (lua_State *L, int index);</pre> 3670280405Srpaulo 3671280405Srpaulo<p> 3672280405SrpauloIf the value at the given index has a metatable, 3673280405Srpaulothe function pushes that metatable onto the stack and returns 1. 3674280405SrpauloOtherwise, 3675280405Srpaulothe function returns 0 and pushes nothing on the stack. 3676280405Srpaulo 3677280405Srpaulo 3678280405Srpaulo 3679280405Srpaulo 3680280405Srpaulo 3681280405Srpaulo<hr><h3><a name="lua_gettable"><code>lua_gettable</code></a></h3><p> 3682280405Srpaulo<span class="apii">[-1, +1, <em>e</em>]</span> 3683280405Srpaulo<pre>int lua_gettable (lua_State *L, int index);</pre> 3684280405Srpaulo 3685280405Srpaulo<p> 3686280405SrpauloPushes onto the stack the value <code>t[k]</code>, 3687280405Srpaulowhere <code>t</code> is the value at the given index 3688280405Srpauloand <code>k</code> is the value at the top of the stack. 3689280405Srpaulo 3690280405Srpaulo 3691280405Srpaulo<p> 3692280405SrpauloThis function pops the key from the stack, 3693280405Srpaulopushing the resulting value in its place. 3694280405SrpauloAs in Lua, this function may trigger a metamethod 3695280405Srpaulofor the "index" event (see <a href="#2.4">§2.4</a>). 3696280405Srpaulo 3697280405Srpaulo 3698280405Srpaulo<p> 3699280405SrpauloReturns the type of the pushed value. 3700280405Srpaulo 3701280405Srpaulo 3702280405Srpaulo 3703280405Srpaulo 3704280405Srpaulo 3705280405Srpaulo<hr><h3><a name="lua_gettop"><code>lua_gettop</code></a></h3><p> 3706280405Srpaulo<span class="apii">[-0, +0, –]</span> 3707280405Srpaulo<pre>int lua_gettop (lua_State *L);</pre> 3708280405Srpaulo 3709280405Srpaulo<p> 3710280405SrpauloReturns the index of the top element in the stack. 3711280405SrpauloBecause indices start at 1, 3712280405Srpaulothis result is equal to the number of elements in the stack; 3713280405Srpauloin particular, 0 means an empty stack. 3714280405Srpaulo 3715280405Srpaulo 3716280405Srpaulo 3717280405Srpaulo 3718280405Srpaulo 3719280405Srpaulo<hr><h3><a name="lua_getuservalue"><code>lua_getuservalue</code></a></h3><p> 3720280405Srpaulo<span class="apii">[-0, +1, –]</span> 3721280405Srpaulo<pre>int lua_getuservalue (lua_State *L, int index);</pre> 3722280405Srpaulo 3723280405Srpaulo<p> 3724326344SimpPushes onto the stack the Lua value associated with the full userdata 3725280405Srpauloat the given index. 3726280405Srpaulo 3727280405Srpaulo 3728280405Srpaulo<p> 3729280405SrpauloReturns the type of the pushed value. 3730280405Srpaulo 3731280405Srpaulo 3732280405Srpaulo 3733280405Srpaulo 3734280405Srpaulo 3735280405Srpaulo<hr><h3><a name="lua_insert"><code>lua_insert</code></a></h3><p> 3736280405Srpaulo<span class="apii">[-1, +1, –]</span> 3737280405Srpaulo<pre>void lua_insert (lua_State *L, int index);</pre> 3738280405Srpaulo 3739280405Srpaulo<p> 3740280405SrpauloMoves the top element into the given valid index, 3741280405Srpauloshifting up the elements above this index to open space. 3742280405SrpauloThis function cannot be called with a pseudo-index, 3743280405Srpaulobecause a pseudo-index is not an actual stack position. 3744280405Srpaulo 3745280405Srpaulo 3746280405Srpaulo 3747280405Srpaulo 3748280405Srpaulo 3749280405Srpaulo<hr><h3><a name="lua_Integer"><code>lua_Integer</code></a></h3> 3750280405Srpaulo<pre>typedef ... lua_Integer;</pre> 3751280405Srpaulo 3752280405Srpaulo<p> 3753280405SrpauloThe type of integers in Lua. 3754280405Srpaulo 3755280405Srpaulo 3756280405Srpaulo<p> 3757280405SrpauloBy default this type is <code>long long</code>, 3758280405Srpaulo(usually a 64-bit two-complement integer), 3759280405Srpaulobut that can be changed to <code>long</code> or <code>int</code> 3760280405Srpaulo(usually a 32-bit two-complement integer). 3761326344Simp(See <code>LUA_INT_TYPE</code> in <code>luaconf.h</code>.) 3762280405Srpaulo 3763280405Srpaulo 3764280405Srpaulo<p> 3765280405SrpauloLua also defines the constants 3766280405Srpaulo<a name="pdf-LUA_MININTEGER"><code>LUA_MININTEGER</code></a> and <a name="pdf-LUA_MAXINTEGER"><code>LUA_MAXINTEGER</code></a>, 3767280405Srpaulowith the minimum and the maximum values that fit in this type. 3768280405Srpaulo 3769280405Srpaulo 3770280405Srpaulo 3771280405Srpaulo 3772280405Srpaulo 3773280405Srpaulo<hr><h3><a name="lua_isboolean"><code>lua_isboolean</code></a></h3><p> 3774280405Srpaulo<span class="apii">[-0, +0, –]</span> 3775280405Srpaulo<pre>int lua_isboolean (lua_State *L, int index);</pre> 3776280405Srpaulo 3777280405Srpaulo<p> 3778280405SrpauloReturns 1 if the value at the given index is a boolean, 3779280405Srpauloand 0 otherwise. 3780280405Srpaulo 3781280405Srpaulo 3782280405Srpaulo 3783280405Srpaulo 3784280405Srpaulo 3785280405Srpaulo<hr><h3><a name="lua_iscfunction"><code>lua_iscfunction</code></a></h3><p> 3786280405Srpaulo<span class="apii">[-0, +0, –]</span> 3787280405Srpaulo<pre>int lua_iscfunction (lua_State *L, int index);</pre> 3788280405Srpaulo 3789280405Srpaulo<p> 3790280405SrpauloReturns 1 if the value at the given index is a C function, 3791280405Srpauloand 0 otherwise. 3792280405Srpaulo 3793280405Srpaulo 3794280405Srpaulo 3795280405Srpaulo 3796280405Srpaulo 3797280405Srpaulo<hr><h3><a name="lua_isfunction"><code>lua_isfunction</code></a></h3><p> 3798280405Srpaulo<span class="apii">[-0, +0, –]</span> 3799280405Srpaulo<pre>int lua_isfunction (lua_State *L, int index);</pre> 3800280405Srpaulo 3801280405Srpaulo<p> 3802280405SrpauloReturns 1 if the value at the given index is a function 3803280405Srpaulo(either C or Lua), and 0 otherwise. 3804280405Srpaulo 3805280405Srpaulo 3806280405Srpaulo 3807280405Srpaulo 3808280405Srpaulo 3809280405Srpaulo<hr><h3><a name="lua_isinteger"><code>lua_isinteger</code></a></h3><p> 3810280405Srpaulo<span class="apii">[-0, +0, –]</span> 3811280405Srpaulo<pre>int lua_isinteger (lua_State *L, int index);</pre> 3812280405Srpaulo 3813280405Srpaulo<p> 3814280405SrpauloReturns 1 if the value at the given index is an integer 3815280405Srpaulo(that is, the value is a number and is represented as an integer), 3816280405Srpauloand 0 otherwise. 3817280405Srpaulo 3818280405Srpaulo 3819280405Srpaulo 3820280405Srpaulo 3821280405Srpaulo 3822280405Srpaulo<hr><h3><a name="lua_islightuserdata"><code>lua_islightuserdata</code></a></h3><p> 3823280405Srpaulo<span class="apii">[-0, +0, –]</span> 3824280405Srpaulo<pre>int lua_islightuserdata (lua_State *L, int index);</pre> 3825280405Srpaulo 3826280405Srpaulo<p> 3827280405SrpauloReturns 1 if the value at the given index is a light userdata, 3828280405Srpauloand 0 otherwise. 3829280405Srpaulo 3830280405Srpaulo 3831280405Srpaulo 3832280405Srpaulo 3833280405Srpaulo 3834280405Srpaulo<hr><h3><a name="lua_isnil"><code>lua_isnil</code></a></h3><p> 3835280405Srpaulo<span class="apii">[-0, +0, –]</span> 3836280405Srpaulo<pre>int lua_isnil (lua_State *L, int index);</pre> 3837280405Srpaulo 3838280405Srpaulo<p> 3839280405SrpauloReturns 1 if the value at the given index is <b>nil</b>, 3840280405Srpauloand 0 otherwise. 3841280405Srpaulo 3842280405Srpaulo 3843280405Srpaulo 3844280405Srpaulo 3845280405Srpaulo 3846280405Srpaulo<hr><h3><a name="lua_isnone"><code>lua_isnone</code></a></h3><p> 3847280405Srpaulo<span class="apii">[-0, +0, –]</span> 3848280405Srpaulo<pre>int lua_isnone (lua_State *L, int index);</pre> 3849280405Srpaulo 3850280405Srpaulo<p> 3851280405SrpauloReturns 1 if the given index is not valid, 3852280405Srpauloand 0 otherwise. 3853280405Srpaulo 3854280405Srpaulo 3855280405Srpaulo 3856280405Srpaulo 3857280405Srpaulo 3858280405Srpaulo<hr><h3><a name="lua_isnoneornil"><code>lua_isnoneornil</code></a></h3><p> 3859280405Srpaulo<span class="apii">[-0, +0, –]</span> 3860280405Srpaulo<pre>int lua_isnoneornil (lua_State *L, int index);</pre> 3861280405Srpaulo 3862280405Srpaulo<p> 3863280405SrpauloReturns 1 if the given index is not valid 3864280405Srpauloor if the value at this index is <b>nil</b>, 3865280405Srpauloand 0 otherwise. 3866280405Srpaulo 3867280405Srpaulo 3868280405Srpaulo 3869280405Srpaulo 3870280405Srpaulo 3871280405Srpaulo<hr><h3><a name="lua_isnumber"><code>lua_isnumber</code></a></h3><p> 3872280405Srpaulo<span class="apii">[-0, +0, –]</span> 3873280405Srpaulo<pre>int lua_isnumber (lua_State *L, int index);</pre> 3874280405Srpaulo 3875280405Srpaulo<p> 3876280405SrpauloReturns 1 if the value at the given index is a number 3877280405Srpauloor a string convertible to a number, 3878280405Srpauloand 0 otherwise. 3879280405Srpaulo 3880280405Srpaulo 3881280405Srpaulo 3882280405Srpaulo 3883280405Srpaulo 3884280405Srpaulo<hr><h3><a name="lua_isstring"><code>lua_isstring</code></a></h3><p> 3885280405Srpaulo<span class="apii">[-0, +0, –]</span> 3886280405Srpaulo<pre>int lua_isstring (lua_State *L, int index);</pre> 3887280405Srpaulo 3888280405Srpaulo<p> 3889280405SrpauloReturns 1 if the value at the given index is a string 3890280405Srpauloor a number (which is always convertible to a string), 3891280405Srpauloand 0 otherwise. 3892280405Srpaulo 3893280405Srpaulo 3894280405Srpaulo 3895280405Srpaulo 3896280405Srpaulo 3897280405Srpaulo<hr><h3><a name="lua_istable"><code>lua_istable</code></a></h3><p> 3898280405Srpaulo<span class="apii">[-0, +0, –]</span> 3899280405Srpaulo<pre>int lua_istable (lua_State *L, int index);</pre> 3900280405Srpaulo 3901280405Srpaulo<p> 3902280405SrpauloReturns 1 if the value at the given index is a table, 3903280405Srpauloand 0 otherwise. 3904280405Srpaulo 3905280405Srpaulo 3906280405Srpaulo 3907280405Srpaulo 3908280405Srpaulo 3909280405Srpaulo<hr><h3><a name="lua_isthread"><code>lua_isthread</code></a></h3><p> 3910280405Srpaulo<span class="apii">[-0, +0, –]</span> 3911280405Srpaulo<pre>int lua_isthread (lua_State *L, int index);</pre> 3912280405Srpaulo 3913280405Srpaulo<p> 3914280405SrpauloReturns 1 if the value at the given index is a thread, 3915280405Srpauloand 0 otherwise. 3916280405Srpaulo 3917280405Srpaulo 3918280405Srpaulo 3919280405Srpaulo 3920280405Srpaulo 3921280405Srpaulo<hr><h3><a name="lua_isuserdata"><code>lua_isuserdata</code></a></h3><p> 3922280405Srpaulo<span class="apii">[-0, +0, –]</span> 3923280405Srpaulo<pre>int lua_isuserdata (lua_State *L, int index);</pre> 3924280405Srpaulo 3925280405Srpaulo<p> 3926280405SrpauloReturns 1 if the value at the given index is a userdata 3927280405Srpaulo(either full or light), and 0 otherwise. 3928280405Srpaulo 3929280405Srpaulo 3930280405Srpaulo 3931280405Srpaulo 3932280405Srpaulo 3933280405Srpaulo<hr><h3><a name="lua_isyieldable"><code>lua_isyieldable</code></a></h3><p> 3934280405Srpaulo<span class="apii">[-0, +0, –]</span> 3935280405Srpaulo<pre>int lua_isyieldable (lua_State *L);</pre> 3936280405Srpaulo 3937280405Srpaulo<p> 3938280405SrpauloReturns 1 if the given coroutine can yield, 3939280405Srpauloand 0 otherwise. 3940280405Srpaulo 3941280405Srpaulo 3942280405Srpaulo 3943280405Srpaulo 3944280405Srpaulo 3945280405Srpaulo<hr><h3><a name="lua_KContext"><code>lua_KContext</code></a></h3> 3946280405Srpaulo<pre>typedef ... lua_KContext;</pre> 3947280405Srpaulo 3948280405Srpaulo<p> 3949280405SrpauloThe type for continuation-function contexts. 3950326344SimpIt must be a numeric type. 3951280405SrpauloThis type is defined as <code>intptr_t</code> 3952280405Srpaulowhen <code>intptr_t</code> is available, 3953280405Srpauloso that it can store pointers too. 3954280405SrpauloOtherwise, it is defined as <code>ptrdiff_t</code>. 3955280405Srpaulo 3956280405Srpaulo 3957280405Srpaulo 3958280405Srpaulo 3959280405Srpaulo 3960280405Srpaulo<hr><h3><a name="lua_KFunction"><code>lua_KFunction</code></a></h3> 3961280405Srpaulo<pre>typedef int (*lua_KFunction) (lua_State *L, int status, lua_KContext ctx);</pre> 3962280405Srpaulo 3963280405Srpaulo<p> 3964280405SrpauloType for continuation functions (see <a href="#4.7">§4.7</a>). 3965280405Srpaulo 3966280405Srpaulo 3967280405Srpaulo 3968280405Srpaulo 3969280405Srpaulo 3970280405Srpaulo<hr><h3><a name="lua_len"><code>lua_len</code></a></h3><p> 3971280405Srpaulo<span class="apii">[-0, +1, <em>e</em>]</span> 3972280405Srpaulo<pre>void lua_len (lua_State *L, int index);</pre> 3973280405Srpaulo 3974280405Srpaulo<p> 3975280405SrpauloReturns the length of the value at the given index. 3976280405SrpauloIt is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">§3.4.7</a>) and 3977280405Srpaulomay trigger a metamethod for the "length" event (see <a href="#2.4">§2.4</a>). 3978280405SrpauloThe result is pushed on the stack. 3979280405Srpaulo 3980280405Srpaulo 3981280405Srpaulo 3982280405Srpaulo 3983280405Srpaulo 3984280405Srpaulo<hr><h3><a name="lua_load"><code>lua_load</code></a></h3><p> 3985280405Srpaulo<span class="apii">[-0, +1, –]</span> 3986280405Srpaulo<pre>int lua_load (lua_State *L, 3987280405Srpaulo lua_Reader reader, 3988280405Srpaulo void *data, 3989280405Srpaulo const char *chunkname, 3990280405Srpaulo const char *mode);</pre> 3991280405Srpaulo 3992280405Srpaulo<p> 3993280405SrpauloLoads a Lua chunk without running it. 3994280405SrpauloIf there are no errors, 3995280405Srpaulo<code>lua_load</code> pushes the compiled chunk as a Lua 3996280405Srpaulofunction on top of the stack. 3997280405SrpauloOtherwise, it pushes an error message. 3998280405Srpaulo 3999280405Srpaulo 4000280405Srpaulo<p> 4001280405SrpauloThe return values of <code>lua_load</code> are: 4002280405Srpaulo 4003280405Srpaulo<ul> 4004280405Srpaulo 4005280405Srpaulo<li><b><a href="#pdf-LUA_OK"><code>LUA_OK</code></a>: </b> no errors;</li> 4006280405Srpaulo 4007280405Srpaulo<li><b><a name="pdf-LUA_ERRSYNTAX"><code>LUA_ERRSYNTAX</code></a>: </b> 4008280405Srpaulosyntax error during precompilation;</li> 4009280405Srpaulo 4010280405Srpaulo<li><b><a href="#pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>: </b> 4011326344Simpmemory allocation (out-of-memory) error;</li> 4012280405Srpaulo 4013280405Srpaulo<li><b><a href="#pdf-LUA_ERRGCMM"><code>LUA_ERRGCMM</code></a>: </b> 4014280405Srpauloerror while running a <code>__gc</code> metamethod. 4015280405Srpaulo(This error has no relation with the chunk being loaded. 4016280405SrpauloIt is generated by the garbage collector.) 4017280405Srpaulo</li> 4018280405Srpaulo 4019280405Srpaulo</ul> 4020280405Srpaulo 4021280405Srpaulo<p> 4022280405SrpauloThe <code>lua_load</code> function uses a user-supplied <code>reader</code> function 4023280405Srpauloto read the chunk (see <a href="#lua_Reader"><code>lua_Reader</code></a>). 4024280405SrpauloThe <code>data</code> argument is an opaque value passed to the reader function. 4025280405Srpaulo 4026280405Srpaulo 4027280405Srpaulo<p> 4028280405SrpauloThe <code>chunkname</code> argument gives a name to the chunk, 4029280405Srpaulowhich is used for error messages and in debug information (see <a href="#4.9">§4.9</a>). 4030280405Srpaulo 4031280405Srpaulo 4032280405Srpaulo<p> 4033280405Srpaulo<code>lua_load</code> automatically detects whether the chunk is text or binary 4034280405Srpauloand loads it accordingly (see program <code>luac</code>). 4035280405SrpauloThe string <code>mode</code> works as in function <a href="#pdf-load"><code>load</code></a>, 4036280405Srpaulowith the addition that 4037280405Srpauloa <code>NULL</code> value is equivalent to the string "<code>bt</code>". 4038280405Srpaulo 4039280405Srpaulo 4040280405Srpaulo<p> 4041280405Srpaulo<code>lua_load</code> uses the stack internally, 4042280405Srpauloso the reader function must always leave the stack 4043280405Srpaulounmodified when returning. 4044280405Srpaulo 4045280405Srpaulo 4046280405Srpaulo<p> 4047280405SrpauloIf the resulting function has upvalues, 4048280405Srpauloits first upvalue is set to the value of the global environment 4049280405Srpaulostored at index <code>LUA_RIDX_GLOBALS</code> in the registry (see <a href="#4.5">§4.5</a>). 4050280405SrpauloWhen loading main chunks, 4051280405Srpaulothis upvalue will be the <code>_ENV</code> variable (see <a href="#2.2">§2.2</a>). 4052280405SrpauloOther upvalues are initialized with <b>nil</b>. 4053280405Srpaulo 4054280405Srpaulo 4055280405Srpaulo 4056280405Srpaulo 4057280405Srpaulo 4058280405Srpaulo<hr><h3><a name="lua_newstate"><code>lua_newstate</code></a></h3><p> 4059280405Srpaulo<span class="apii">[-0, +0, –]</span> 4060280405Srpaulo<pre>lua_State *lua_newstate (lua_Alloc f, void *ud);</pre> 4061280405Srpaulo 4062280405Srpaulo<p> 4063280405SrpauloCreates a new thread running in a new, independent state. 4064280405SrpauloReturns <code>NULL</code> if it cannot create the thread or the state 4065280405Srpaulo(due to lack of memory). 4066280405SrpauloThe argument <code>f</code> is the allocator function; 4067326344SimpLua does all memory allocation for this state 4068326344Simpthrough this function (see <a href="#lua_Alloc"><code>lua_Alloc</code></a>). 4069280405SrpauloThe second argument, <code>ud</code>, is an opaque pointer that Lua 4070280405Srpaulopasses to the allocator in every call. 4071280405Srpaulo 4072280405Srpaulo 4073280405Srpaulo 4074280405Srpaulo 4075280405Srpaulo 4076280405Srpaulo<hr><h3><a name="lua_newtable"><code>lua_newtable</code></a></h3><p> 4077326344Simp<span class="apii">[-0, +1, <em>m</em>]</span> 4078280405Srpaulo<pre>void lua_newtable (lua_State *L);</pre> 4079280405Srpaulo 4080280405Srpaulo<p> 4081280405SrpauloCreates a new empty table and pushes it onto the stack. 4082280405SrpauloIt is equivalent to <code>lua_createtable(L, 0, 0)</code>. 4083280405Srpaulo 4084280405Srpaulo 4085280405Srpaulo 4086280405Srpaulo 4087280405Srpaulo 4088280405Srpaulo<hr><h3><a name="lua_newthread"><code>lua_newthread</code></a></h3><p> 4089326344Simp<span class="apii">[-0, +1, <em>m</em>]</span> 4090280405Srpaulo<pre>lua_State *lua_newthread (lua_State *L);</pre> 4091280405Srpaulo 4092280405Srpaulo<p> 4093280405SrpauloCreates a new thread, pushes it on the stack, 4094280405Srpauloand returns a pointer to a <a href="#lua_State"><code>lua_State</code></a> that represents this new thread. 4095280405SrpauloThe new thread returned by this function shares with the original thread 4096280405Srpauloits global environment, 4097280405Srpaulobut has an independent execution stack. 4098280405Srpaulo 4099280405Srpaulo 4100280405Srpaulo<p> 4101280405SrpauloThere is no explicit function to close or to destroy a thread. 4102280405SrpauloThreads are subject to garbage collection, 4103280405Srpaulolike any Lua object. 4104280405Srpaulo 4105280405Srpaulo 4106280405Srpaulo 4107280405Srpaulo 4108280405Srpaulo 4109280405Srpaulo<hr><h3><a name="lua_newuserdata"><code>lua_newuserdata</code></a></h3><p> 4110326344Simp<span class="apii">[-0, +1, <em>m</em>]</span> 4111280405Srpaulo<pre>void *lua_newuserdata (lua_State *L, size_t size);</pre> 4112280405Srpaulo 4113280405Srpaulo<p> 4114280405SrpauloThis function allocates a new block of memory with the given size, 4115280405Srpaulopushes onto the stack a new full userdata with the block address, 4116280405Srpauloand returns this address. 4117280405SrpauloThe host program can freely use this memory. 4118280405Srpaulo 4119280405Srpaulo 4120280405Srpaulo 4121280405Srpaulo 4122280405Srpaulo 4123280405Srpaulo<hr><h3><a name="lua_next"><code>lua_next</code></a></h3><p> 4124280405Srpaulo<span class="apii">[-1, +(2|0), <em>e</em>]</span> 4125280405Srpaulo<pre>int lua_next (lua_State *L, int index);</pre> 4126280405Srpaulo 4127280405Srpaulo<p> 4128280405SrpauloPops a key from the stack, 4129280405Srpauloand pushes a key–value pair from the table at the given index 4130280405Srpaulo(the "next" pair after the given key). 4131280405SrpauloIf there are no more elements in the table, 4132280405Srpaulothen <a href="#lua_next"><code>lua_next</code></a> returns 0 (and pushes nothing). 4133280405Srpaulo 4134280405Srpaulo 4135280405Srpaulo<p> 4136280405SrpauloA typical traversal looks like this: 4137280405Srpaulo 4138280405Srpaulo<pre> 4139280405Srpaulo /* table is in the stack at index 't' */ 4140280405Srpaulo lua_pushnil(L); /* first key */ 4141280405Srpaulo while (lua_next(L, t) != 0) { 4142280405Srpaulo /* uses 'key' (at index -2) and 'value' (at index -1) */ 4143280405Srpaulo printf("%s - %s\n", 4144280405Srpaulo lua_typename(L, lua_type(L, -2)), 4145280405Srpaulo lua_typename(L, lua_type(L, -1))); 4146280405Srpaulo /* removes 'value'; keeps 'key' for next iteration */ 4147280405Srpaulo lua_pop(L, 1); 4148280405Srpaulo } 4149280405Srpaulo</pre> 4150280405Srpaulo 4151280405Srpaulo<p> 4152280405SrpauloWhile traversing a table, 4153280405Srpaulodo not call <a href="#lua_tolstring"><code>lua_tolstring</code></a> directly on a key, 4154280405Srpaulounless you know that the key is actually a string. 4155280405SrpauloRecall that <a href="#lua_tolstring"><code>lua_tolstring</code></a> may change 4156280405Srpaulothe value at the given index; 4157280405Srpaulothis confuses the next call to <a href="#lua_next"><code>lua_next</code></a>. 4158280405Srpaulo 4159280405Srpaulo 4160280405Srpaulo<p> 4161280405SrpauloSee function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying 4162280405Srpaulothe table during its traversal. 4163280405Srpaulo 4164280405Srpaulo 4165280405Srpaulo 4166280405Srpaulo 4167280405Srpaulo 4168280405Srpaulo<hr><h3><a name="lua_Number"><code>lua_Number</code></a></h3> 4169326344Simp<pre>typedef ... lua_Number;</pre> 4170280405Srpaulo 4171280405Srpaulo<p> 4172280405SrpauloThe type of floats in Lua. 4173280405Srpaulo 4174280405Srpaulo 4175280405Srpaulo<p> 4176280405SrpauloBy default this type is double, 4177326344Simpbut that can be changed to a single float or a long double. 4178326344Simp(See <code>LUA_FLOAT_TYPE</code> in <code>luaconf.h</code>.) 4179280405Srpaulo 4180280405Srpaulo 4181280405Srpaulo 4182280405Srpaulo 4183280405Srpaulo 4184280405Srpaulo<hr><h3><a name="lua_numbertointeger"><code>lua_numbertointeger</code></a></h3> 4185280405Srpaulo<pre>int lua_numbertointeger (lua_Number n, lua_Integer *p);</pre> 4186280405Srpaulo 4187280405Srpaulo<p> 4188280405SrpauloConverts a Lua float to a Lua integer. 4189280405SrpauloThis macro assumes that <code>n</code> has an integral value. 4190280405SrpauloIf that value is within the range of Lua integers, 4191280405Srpauloit is converted to an integer and assigned to <code>*p</code>. 4192280405SrpauloThe macro results in a boolean indicating whether the 4193280405Srpauloconversion was successful. 4194280405Srpaulo(Note that this range test can be tricky to do 4195280405Srpaulocorrectly without this macro, 4196280405Srpaulodue to roundings.) 4197280405Srpaulo 4198280405Srpaulo 4199280405Srpaulo<p> 4200280405SrpauloThis macro may evaluate its arguments more than once. 4201280405Srpaulo 4202280405Srpaulo 4203280405Srpaulo 4204280405Srpaulo 4205280405Srpaulo 4206280405Srpaulo<hr><h3><a name="lua_pcall"><code>lua_pcall</code></a></h3><p> 4207280405Srpaulo<span class="apii">[-(nargs + 1), +(nresults|1), –]</span> 4208280405Srpaulo<pre>int lua_pcall (lua_State *L, int nargs, int nresults, int msgh);</pre> 4209280405Srpaulo 4210280405Srpaulo<p> 4211280405SrpauloCalls a function in protected mode. 4212280405Srpaulo 4213280405Srpaulo 4214280405Srpaulo<p> 4215280405SrpauloBoth <code>nargs</code> and <code>nresults</code> have the same meaning as 4216280405Srpauloin <a href="#lua_call"><code>lua_call</code></a>. 4217280405SrpauloIf there are no errors during the call, 4218280405Srpaulo<a href="#lua_pcall"><code>lua_pcall</code></a> behaves exactly like <a href="#lua_call"><code>lua_call</code></a>. 4219280405SrpauloHowever, if there is any error, 4220280405Srpaulo<a href="#lua_pcall"><code>lua_pcall</code></a> catches it, 4221326344Simppushes a single value on the stack (the error object), 4222280405Srpauloand returns an error code. 4223280405SrpauloLike <a href="#lua_call"><code>lua_call</code></a>, 4224280405Srpaulo<a href="#lua_pcall"><code>lua_pcall</code></a> always removes the function 4225280405Srpauloand its arguments from the stack. 4226280405Srpaulo 4227280405Srpaulo 4228280405Srpaulo<p> 4229280405SrpauloIf <code>msgh</code> is 0, 4230326344Simpthen the error object returned on the stack 4231326344Simpis exactly the original error object. 4232280405SrpauloOtherwise, <code>msgh</code> is the stack index of a 4233280405Srpaulo<em>message handler</em>. 4234326344Simp(This index cannot be a pseudo-index.) 4235280405SrpauloIn case of runtime errors, 4236326344Simpthis function will be called with the error object 4237326344Simpand its return value will be the object 4238280405Srpauloreturned on the stack by <a href="#lua_pcall"><code>lua_pcall</code></a>. 4239280405Srpaulo 4240280405Srpaulo 4241280405Srpaulo<p> 4242280405SrpauloTypically, the message handler is used to add more debug 4243326344Simpinformation to the error object, such as a stack traceback. 4244280405SrpauloSuch information cannot be gathered after the return of <a href="#lua_pcall"><code>lua_pcall</code></a>, 4245280405Srpaulosince by then the stack has unwound. 4246280405Srpaulo 4247280405Srpaulo 4248280405Srpaulo<p> 4249280405SrpauloThe <a href="#lua_pcall"><code>lua_pcall</code></a> function returns one of the following constants 4250280405Srpaulo(defined in <code>lua.h</code>): 4251280405Srpaulo 4252280405Srpaulo<ul> 4253280405Srpaulo 4254280405Srpaulo<li><b><a name="pdf-LUA_OK"><code>LUA_OK</code></a> (0): </b> 4255280405Srpaulosuccess.</li> 4256280405Srpaulo 4257280405Srpaulo<li><b><a name="pdf-LUA_ERRRUN"><code>LUA_ERRRUN</code></a>: </b> 4258280405Srpauloa runtime error. 4259280405Srpaulo</li> 4260280405Srpaulo 4261280405Srpaulo<li><b><a name="pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>: </b> 4262280405Srpaulomemory allocation error. 4263280405SrpauloFor such errors, Lua does not call the message handler. 4264280405Srpaulo</li> 4265280405Srpaulo 4266280405Srpaulo<li><b><a name="pdf-LUA_ERRERR"><code>LUA_ERRERR</code></a>: </b> 4267280405Srpauloerror while running the message handler. 4268280405Srpaulo</li> 4269280405Srpaulo 4270280405Srpaulo<li><b><a name="pdf-LUA_ERRGCMM"><code>LUA_ERRGCMM</code></a>: </b> 4271280405Srpauloerror while running a <code>__gc</code> metamethod. 4272326344SimpFor such errors, Lua does not call the message handler 4273326344Simp(as this kind of error typically has no relation 4274326344Simpwith the function being called). 4275280405Srpaulo</li> 4276280405Srpaulo 4277280405Srpaulo</ul> 4278280405Srpaulo 4279280405Srpaulo 4280280405Srpaulo 4281280405Srpaulo 4282280405Srpaulo<hr><h3><a name="lua_pcallk"><code>lua_pcallk</code></a></h3><p> 4283280405Srpaulo<span class="apii">[-(nargs + 1), +(nresults|1), –]</span> 4284280405Srpaulo<pre>int lua_pcallk (lua_State *L, 4285280405Srpaulo int nargs, 4286280405Srpaulo int nresults, 4287280405Srpaulo int msgh, 4288280405Srpaulo lua_KContext ctx, 4289280405Srpaulo lua_KFunction k);</pre> 4290280405Srpaulo 4291280405Srpaulo<p> 4292280405SrpauloThis function behaves exactly like <a href="#lua_pcall"><code>lua_pcall</code></a>, 4293280405Srpaulobut allows the called function to yield (see <a href="#4.7">§4.7</a>). 4294280405Srpaulo 4295280405Srpaulo 4296280405Srpaulo 4297280405Srpaulo 4298280405Srpaulo 4299280405Srpaulo<hr><h3><a name="lua_pop"><code>lua_pop</code></a></h3><p> 4300280405Srpaulo<span class="apii">[-n, +0, –]</span> 4301280405Srpaulo<pre>void lua_pop (lua_State *L, int n);</pre> 4302280405Srpaulo 4303280405Srpaulo<p> 4304280405SrpauloPops <code>n</code> elements from the stack. 4305280405Srpaulo 4306280405Srpaulo 4307280405Srpaulo 4308280405Srpaulo 4309280405Srpaulo 4310280405Srpaulo<hr><h3><a name="lua_pushboolean"><code>lua_pushboolean</code></a></h3><p> 4311280405Srpaulo<span class="apii">[-0, +1, –]</span> 4312280405Srpaulo<pre>void lua_pushboolean (lua_State *L, int b);</pre> 4313280405Srpaulo 4314280405Srpaulo<p> 4315280405SrpauloPushes a boolean value with value <code>b</code> onto the stack. 4316280405Srpaulo 4317280405Srpaulo 4318280405Srpaulo 4319280405Srpaulo 4320280405Srpaulo 4321280405Srpaulo<hr><h3><a name="lua_pushcclosure"><code>lua_pushcclosure</code></a></h3><p> 4322326344Simp<span class="apii">[-n, +1, <em>m</em>]</span> 4323280405Srpaulo<pre>void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);</pre> 4324280405Srpaulo 4325280405Srpaulo<p> 4326280405SrpauloPushes a new C closure onto the stack. 4327280405Srpaulo 4328280405Srpaulo 4329280405Srpaulo<p> 4330280405SrpauloWhen a C function is created, 4331280405Srpauloit is possible to associate some values with it, 4332280405Srpaulothus creating a C closure (see <a href="#4.4">§4.4</a>); 4333280405Srpaulothese values are then accessible to the function whenever it is called. 4334280405SrpauloTo associate values with a C function, 4335280405Srpaulofirst these values must be pushed onto the stack 4336280405Srpaulo(when there are multiple values, the first value is pushed first). 4337280405SrpauloThen <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> 4338280405Srpaulois called to create and push the C function onto the stack, 4339280405Srpaulowith the argument <code>n</code> telling how many values will be 4340280405Srpauloassociated with the function. 4341280405Srpaulo<a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> also pops these values from the stack. 4342280405Srpaulo 4343280405Srpaulo 4344280405Srpaulo<p> 4345280405SrpauloThe maximum value for <code>n</code> is 255. 4346280405Srpaulo 4347280405Srpaulo 4348280405Srpaulo<p> 4349280405SrpauloWhen <code>n</code> is zero, 4350326344Simpthis function creates a <em>light C function</em>, 4351280405Srpaulowhich is just a pointer to the C function. 4352280405SrpauloIn that case, it never raises a memory error. 4353280405Srpaulo 4354280405Srpaulo 4355280405Srpaulo 4356280405Srpaulo 4357280405Srpaulo 4358280405Srpaulo<hr><h3><a name="lua_pushcfunction"><code>lua_pushcfunction</code></a></h3><p> 4359280405Srpaulo<span class="apii">[-0, +1, –]</span> 4360280405Srpaulo<pre>void lua_pushcfunction (lua_State *L, lua_CFunction f);</pre> 4361280405Srpaulo 4362280405Srpaulo<p> 4363280405SrpauloPushes a C function onto the stack. 4364326344SimpThis function receives a pointer to a C function 4365280405Srpauloand pushes onto the stack a Lua value of type <code>function</code> that, 4366280405Srpaulowhen called, invokes the corresponding C function. 4367280405Srpaulo 4368280405Srpaulo 4369280405Srpaulo<p> 4370326344SimpAny function to be callable by Lua must 4371280405Srpaulofollow the correct protocol to receive its parameters 4372280405Srpauloand return its results (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 4373280405Srpaulo 4374280405Srpaulo 4375280405Srpaulo 4376280405Srpaulo 4377280405Srpaulo 4378280405Srpaulo<hr><h3><a name="lua_pushfstring"><code>lua_pushfstring</code></a></h3><p> 4379280405Srpaulo<span class="apii">[-0, +1, <em>e</em>]</span> 4380280405Srpaulo<pre>const char *lua_pushfstring (lua_State *L, const char *fmt, ...);</pre> 4381280405Srpaulo 4382280405Srpaulo<p> 4383280405SrpauloPushes onto the stack a formatted string 4384280405Srpauloand returns a pointer to this string. 4385280405SrpauloIt is similar to the ISO C function <code>sprintf</code>, 4386280405Srpaulobut has some important differences: 4387280405Srpaulo 4388280405Srpaulo<ul> 4389280405Srpaulo 4390280405Srpaulo<li> 4391280405SrpauloYou do not have to allocate space for the result: 4392280405Srpaulothe result is a Lua string and Lua takes care of memory allocation 4393280405Srpaulo(and deallocation, through garbage collection). 4394280405Srpaulo</li> 4395280405Srpaulo 4396280405Srpaulo<li> 4397280405SrpauloThe conversion specifiers are quite restricted. 4398280405SrpauloThere are no flags, widths, or precisions. 4399280405SrpauloThe conversion specifiers can only be 4400280405Srpaulo'<code>%%</code>' (inserts the character '<code>%</code>'), 4401280405Srpaulo'<code>%s</code>' (inserts a zero-terminated string, with no size restrictions), 4402280405Srpaulo'<code>%f</code>' (inserts a <a href="#lua_Number"><code>lua_Number</code></a>), 4403326344Simp'<code>%I</code>' (inserts a <a href="#lua_Integer"><code>lua_Integer</code></a>), 4404280405Srpaulo'<code>%p</code>' (inserts a pointer as a hexadecimal numeral), 4405280405Srpaulo'<code>%d</code>' (inserts an <code>int</code>), 4406280405Srpaulo'<code>%c</code>' (inserts an <code>int</code> as a one-byte character), and 4407280405Srpaulo'<code>%U</code>' (inserts a <code>long int</code> as a UTF-8 byte sequence). 4408280405Srpaulo</li> 4409280405Srpaulo 4410280405Srpaulo</ul> 4411280405Srpaulo 4412326344Simp<p> 4413326344SimpUnlike other push functions, 4414326344Simpthis function checks for the stack space it needs, 4415326344Simpincluding the slot for its result. 4416280405Srpaulo 4417280405Srpaulo 4418280405Srpaulo 4419326344Simp 4420326344Simp 4421280405Srpaulo<hr><h3><a name="lua_pushglobaltable"><code>lua_pushglobaltable</code></a></h3><p> 4422280405Srpaulo<span class="apii">[-0, +1, –]</span> 4423280405Srpaulo<pre>void lua_pushglobaltable (lua_State *L);</pre> 4424280405Srpaulo 4425280405Srpaulo<p> 4426280405SrpauloPushes the global environment onto the stack. 4427280405Srpaulo 4428280405Srpaulo 4429280405Srpaulo 4430280405Srpaulo 4431280405Srpaulo 4432280405Srpaulo<hr><h3><a name="lua_pushinteger"><code>lua_pushinteger</code></a></h3><p> 4433280405Srpaulo<span class="apii">[-0, +1, –]</span> 4434280405Srpaulo<pre>void lua_pushinteger (lua_State *L, lua_Integer n);</pre> 4435280405Srpaulo 4436280405Srpaulo<p> 4437280405SrpauloPushes an integer with value <code>n</code> onto the stack. 4438280405Srpaulo 4439280405Srpaulo 4440280405Srpaulo 4441280405Srpaulo 4442280405Srpaulo 4443280405Srpaulo<hr><h3><a name="lua_pushlightuserdata"><code>lua_pushlightuserdata</code></a></h3><p> 4444280405Srpaulo<span class="apii">[-0, +1, –]</span> 4445280405Srpaulo<pre>void lua_pushlightuserdata (lua_State *L, void *p);</pre> 4446280405Srpaulo 4447280405Srpaulo<p> 4448280405SrpauloPushes a light userdata onto the stack. 4449280405Srpaulo 4450280405Srpaulo 4451280405Srpaulo<p> 4452280405SrpauloUserdata represent C values in Lua. 4453280405SrpauloA <em>light userdata</em> represents a pointer, a <code>void*</code>. 4454280405SrpauloIt is a value (like a number): 4455280405Srpauloyou do not create it, it has no individual metatable, 4456280405Srpauloand it is not collected (as it was never created). 4457280405SrpauloA light userdata is equal to "any" 4458280405Srpaulolight userdata with the same C address. 4459280405Srpaulo 4460280405Srpaulo 4461280405Srpaulo 4462280405Srpaulo 4463280405Srpaulo 4464280405Srpaulo<hr><h3><a name="lua_pushliteral"><code>lua_pushliteral</code></a></h3><p> 4465326344Simp<span class="apii">[-0, +1, <em>m</em>]</span> 4466280405Srpaulo<pre>const char *lua_pushliteral (lua_State *L, const char *s);</pre> 4467280405Srpaulo 4468280405Srpaulo<p> 4469326344SimpThis macro is equivalent to <a href="#lua_pushstring"><code>lua_pushstring</code></a>, 4470326344Simpbut should be used only when <code>s</code> is a literal string. 4471280405Srpaulo 4472280405Srpaulo 4473280405Srpaulo 4474280405Srpaulo 4475280405Srpaulo 4476280405Srpaulo<hr><h3><a name="lua_pushlstring"><code>lua_pushlstring</code></a></h3><p> 4477326344Simp<span class="apii">[-0, +1, <em>m</em>]</span> 4478280405Srpaulo<pre>const char *lua_pushlstring (lua_State *L, const char *s, size_t len);</pre> 4479280405Srpaulo 4480280405Srpaulo<p> 4481280405SrpauloPushes the string pointed to by <code>s</code> with size <code>len</code> 4482280405Srpauloonto the stack. 4483280405SrpauloLua makes (or reuses) an internal copy of the given string, 4484280405Srpauloso the memory at <code>s</code> can be freed or reused immediately after 4485280405Srpaulothe function returns. 4486280405SrpauloThe string can contain any binary data, 4487280405Srpauloincluding embedded zeros. 4488280405Srpaulo 4489280405Srpaulo 4490280405Srpaulo<p> 4491280405SrpauloReturns a pointer to the internal copy of the string. 4492280405Srpaulo 4493280405Srpaulo 4494280405Srpaulo 4495280405Srpaulo 4496280405Srpaulo 4497280405Srpaulo<hr><h3><a name="lua_pushnil"><code>lua_pushnil</code></a></h3><p> 4498280405Srpaulo<span class="apii">[-0, +1, –]</span> 4499280405Srpaulo<pre>void lua_pushnil (lua_State *L);</pre> 4500280405Srpaulo 4501280405Srpaulo<p> 4502280405SrpauloPushes a nil value onto the stack. 4503280405Srpaulo 4504280405Srpaulo 4505280405Srpaulo 4506280405Srpaulo 4507280405Srpaulo 4508280405Srpaulo<hr><h3><a name="lua_pushnumber"><code>lua_pushnumber</code></a></h3><p> 4509280405Srpaulo<span class="apii">[-0, +1, –]</span> 4510280405Srpaulo<pre>void lua_pushnumber (lua_State *L, lua_Number n);</pre> 4511280405Srpaulo 4512280405Srpaulo<p> 4513280405SrpauloPushes a float with value <code>n</code> onto the stack. 4514280405Srpaulo 4515280405Srpaulo 4516280405Srpaulo 4517280405Srpaulo 4518280405Srpaulo 4519280405Srpaulo<hr><h3><a name="lua_pushstring"><code>lua_pushstring</code></a></h3><p> 4520326344Simp<span class="apii">[-0, +1, <em>m</em>]</span> 4521280405Srpaulo<pre>const char *lua_pushstring (lua_State *L, const char *s);</pre> 4522280405Srpaulo 4523280405Srpaulo<p> 4524280405SrpauloPushes the zero-terminated string pointed to by <code>s</code> 4525280405Srpauloonto the stack. 4526280405SrpauloLua makes (or reuses) an internal copy of the given string, 4527280405Srpauloso the memory at <code>s</code> can be freed or reused immediately after 4528280405Srpaulothe function returns. 4529280405Srpaulo 4530280405Srpaulo 4531280405Srpaulo<p> 4532280405SrpauloReturns a pointer to the internal copy of the string. 4533280405Srpaulo 4534280405Srpaulo 4535280405Srpaulo<p> 4536280405SrpauloIf <code>s</code> is <code>NULL</code>, pushes <b>nil</b> and returns <code>NULL</code>. 4537280405Srpaulo 4538280405Srpaulo 4539280405Srpaulo 4540280405Srpaulo 4541280405Srpaulo 4542280405Srpaulo<hr><h3><a name="lua_pushthread"><code>lua_pushthread</code></a></h3><p> 4543280405Srpaulo<span class="apii">[-0, +1, –]</span> 4544280405Srpaulo<pre>int lua_pushthread (lua_State *L);</pre> 4545280405Srpaulo 4546280405Srpaulo<p> 4547280405SrpauloPushes the thread represented by <code>L</code> onto the stack. 4548280405SrpauloReturns 1 if this thread is the main thread of its state. 4549280405Srpaulo 4550280405Srpaulo 4551280405Srpaulo 4552280405Srpaulo 4553280405Srpaulo 4554280405Srpaulo<hr><h3><a name="lua_pushvalue"><code>lua_pushvalue</code></a></h3><p> 4555280405Srpaulo<span class="apii">[-0, +1, –]</span> 4556280405Srpaulo<pre>void lua_pushvalue (lua_State *L, int index);</pre> 4557280405Srpaulo 4558280405Srpaulo<p> 4559280405SrpauloPushes a copy of the element at the given index 4560280405Srpauloonto the stack. 4561280405Srpaulo 4562280405Srpaulo 4563280405Srpaulo 4564280405Srpaulo 4565280405Srpaulo 4566280405Srpaulo<hr><h3><a name="lua_pushvfstring"><code>lua_pushvfstring</code></a></h3><p> 4567326344Simp<span class="apii">[-0, +1, <em>m</em>]</span> 4568280405Srpaulo<pre>const char *lua_pushvfstring (lua_State *L, 4569280405Srpaulo const char *fmt, 4570280405Srpaulo va_list argp);</pre> 4571280405Srpaulo 4572280405Srpaulo<p> 4573280405SrpauloEquivalent to <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>, except that it receives a <code>va_list</code> 4574280405Srpauloinstead of a variable number of arguments. 4575280405Srpaulo 4576280405Srpaulo 4577280405Srpaulo 4578280405Srpaulo 4579280405Srpaulo 4580280405Srpaulo<hr><h3><a name="lua_rawequal"><code>lua_rawequal</code></a></h3><p> 4581280405Srpaulo<span class="apii">[-0, +0, –]</span> 4582280405Srpaulo<pre>int lua_rawequal (lua_State *L, int index1, int index2);</pre> 4583280405Srpaulo 4584280405Srpaulo<p> 4585280405SrpauloReturns 1 if the two values in indices <code>index1</code> and 4586280405Srpaulo<code>index2</code> are primitively equal 4587326344Simp(that is, without calling the <code>__eq</code> metamethod). 4588280405SrpauloOtherwise returns 0. 4589280405SrpauloAlso returns 0 if any of the indices are not valid. 4590280405Srpaulo 4591280405Srpaulo 4592280405Srpaulo 4593280405Srpaulo 4594280405Srpaulo 4595280405Srpaulo<hr><h3><a name="lua_rawget"><code>lua_rawget</code></a></h3><p> 4596280405Srpaulo<span class="apii">[-1, +1, –]</span> 4597280405Srpaulo<pre>int lua_rawget (lua_State *L, int index);</pre> 4598280405Srpaulo 4599280405Srpaulo<p> 4600280405SrpauloSimilar to <a href="#lua_gettable"><code>lua_gettable</code></a>, but does a raw access 4601280405Srpaulo(i.e., without metamethods). 4602280405Srpaulo 4603280405Srpaulo 4604280405Srpaulo 4605280405Srpaulo 4606280405Srpaulo 4607280405Srpaulo<hr><h3><a name="lua_rawgeti"><code>lua_rawgeti</code></a></h3><p> 4608280405Srpaulo<span class="apii">[-0, +1, –]</span> 4609280405Srpaulo<pre>int lua_rawgeti (lua_State *L, int index, lua_Integer n);</pre> 4610280405Srpaulo 4611280405Srpaulo<p> 4612280405SrpauloPushes onto the stack the value <code>t[n]</code>, 4613280405Srpaulowhere <code>t</code> is the table at the given index. 4614326344SimpThe access is raw, 4615326344Simpthat is, it does not invoke the <code>__index</code> metamethod. 4616280405Srpaulo 4617280405Srpaulo 4618280405Srpaulo<p> 4619280405SrpauloReturns the type of the pushed value. 4620280405Srpaulo 4621280405Srpaulo 4622280405Srpaulo 4623280405Srpaulo 4624280405Srpaulo 4625280405Srpaulo<hr><h3><a name="lua_rawgetp"><code>lua_rawgetp</code></a></h3><p> 4626280405Srpaulo<span class="apii">[-0, +1, –]</span> 4627280405Srpaulo<pre>int lua_rawgetp (lua_State *L, int index, const void *p);</pre> 4628280405Srpaulo 4629280405Srpaulo<p> 4630280405SrpauloPushes onto the stack the value <code>t[k]</code>, 4631280405Srpaulowhere <code>t</code> is the table at the given index and 4632280405Srpaulo<code>k</code> is the pointer <code>p</code> represented as a light userdata. 4633280405SrpauloThe access is raw; 4634326344Simpthat is, it does not invoke the <code>__index</code> metamethod. 4635280405Srpaulo 4636280405Srpaulo 4637280405Srpaulo<p> 4638280405SrpauloReturns the type of the pushed value. 4639280405Srpaulo 4640280405Srpaulo 4641280405Srpaulo 4642280405Srpaulo 4643280405Srpaulo 4644280405Srpaulo<hr><h3><a name="lua_rawlen"><code>lua_rawlen</code></a></h3><p> 4645280405Srpaulo<span class="apii">[-0, +0, –]</span> 4646280405Srpaulo<pre>size_t lua_rawlen (lua_State *L, int index);</pre> 4647280405Srpaulo 4648280405Srpaulo<p> 4649280405SrpauloReturns the raw "length" of the value at the given index: 4650280405Srpaulofor strings, this is the string length; 4651280405Srpaulofor tables, this is the result of the length operator ('<code>#</code>') 4652280405Srpaulowith no metamethods; 4653280405Srpaulofor userdata, this is the size of the block of memory allocated 4654280405Srpaulofor the userdata; 4655280405Srpaulofor other values, it is 0. 4656280405Srpaulo 4657280405Srpaulo 4658280405Srpaulo 4659280405Srpaulo 4660280405Srpaulo 4661280405Srpaulo<hr><h3><a name="lua_rawset"><code>lua_rawset</code></a></h3><p> 4662326344Simp<span class="apii">[-2, +0, <em>m</em>]</span> 4663280405Srpaulo<pre>void lua_rawset (lua_State *L, int index);</pre> 4664280405Srpaulo 4665280405Srpaulo<p> 4666280405SrpauloSimilar to <a href="#lua_settable"><code>lua_settable</code></a>, but does a raw assignment 4667280405Srpaulo(i.e., without metamethods). 4668280405Srpaulo 4669280405Srpaulo 4670280405Srpaulo 4671280405Srpaulo 4672280405Srpaulo 4673280405Srpaulo<hr><h3><a name="lua_rawseti"><code>lua_rawseti</code></a></h3><p> 4674326344Simp<span class="apii">[-1, +0, <em>m</em>]</span> 4675280405Srpaulo<pre>void lua_rawseti (lua_State *L, int index, lua_Integer i);</pre> 4676280405Srpaulo 4677280405Srpaulo<p> 4678280405SrpauloDoes the equivalent of <code>t[i] = v</code>, 4679280405Srpaulowhere <code>t</code> is the table at the given index 4680280405Srpauloand <code>v</code> is the value at the top of the stack. 4681280405Srpaulo 4682280405Srpaulo 4683280405Srpaulo<p> 4684280405SrpauloThis function pops the value from the stack. 4685326344SimpThe assignment is raw, 4686326344Simpthat is, it does not invoke the <code>__newindex</code> metamethod. 4687280405Srpaulo 4688280405Srpaulo 4689280405Srpaulo 4690280405Srpaulo 4691280405Srpaulo 4692280405Srpaulo<hr><h3><a name="lua_rawsetp"><code>lua_rawsetp</code></a></h3><p> 4693326344Simp<span class="apii">[-1, +0, <em>m</em>]</span> 4694280405Srpaulo<pre>void lua_rawsetp (lua_State *L, int index, const void *p);</pre> 4695280405Srpaulo 4696280405Srpaulo<p> 4697326344SimpDoes the equivalent of <code>t[p] = v</code>, 4698280405Srpaulowhere <code>t</code> is the table at the given index, 4699326344Simp<code>p</code> is encoded as a light userdata, 4700280405Srpauloand <code>v</code> is the value at the top of the stack. 4701280405Srpaulo 4702280405Srpaulo 4703280405Srpaulo<p> 4704280405SrpauloThis function pops the value from the stack. 4705326344SimpThe assignment is raw, 4706326344Simpthat is, it does not invoke <code>__newindex</code> metamethod. 4707280405Srpaulo 4708280405Srpaulo 4709280405Srpaulo 4710280405Srpaulo 4711280405Srpaulo 4712280405Srpaulo<hr><h3><a name="lua_Reader"><code>lua_Reader</code></a></h3> 4713280405Srpaulo<pre>typedef const char * (*lua_Reader) (lua_State *L, 4714280405Srpaulo void *data, 4715280405Srpaulo size_t *size);</pre> 4716280405Srpaulo 4717280405Srpaulo<p> 4718280405SrpauloThe reader function used by <a href="#lua_load"><code>lua_load</code></a>. 4719280405SrpauloEvery time it needs another piece of the chunk, 4720280405Srpaulo<a href="#lua_load"><code>lua_load</code></a> calls the reader, 4721280405Srpaulopassing along its <code>data</code> parameter. 4722280405SrpauloThe reader must return a pointer to a block of memory 4723280405Srpaulowith a new piece of the chunk 4724280405Srpauloand set <code>size</code> to the block size. 4725280405SrpauloThe block must exist until the reader function is called again. 4726280405SrpauloTo signal the end of the chunk, 4727280405Srpaulothe reader must return <code>NULL</code> or set <code>size</code> to zero. 4728280405SrpauloThe reader function may return pieces of any size greater than zero. 4729280405Srpaulo 4730280405Srpaulo 4731280405Srpaulo 4732280405Srpaulo 4733280405Srpaulo 4734280405Srpaulo<hr><h3><a name="lua_register"><code>lua_register</code></a></h3><p> 4735280405Srpaulo<span class="apii">[-0, +0, <em>e</em>]</span> 4736280405Srpaulo<pre>void lua_register (lua_State *L, const char *name, lua_CFunction f);</pre> 4737280405Srpaulo 4738280405Srpaulo<p> 4739326344SimpSets the C function <code>f</code> as the new value of global <code>name</code>. 4740280405SrpauloIt is defined as a macro: 4741280405Srpaulo 4742280405Srpaulo<pre> 4743280405Srpaulo #define lua_register(L,n,f) \ 4744280405Srpaulo (lua_pushcfunction(L, f), lua_setglobal(L, n)) 4745280405Srpaulo</pre> 4746280405Srpaulo 4747280405Srpaulo 4748280405Srpaulo 4749280405Srpaulo 4750280405Srpaulo<hr><h3><a name="lua_remove"><code>lua_remove</code></a></h3><p> 4751280405Srpaulo<span class="apii">[-1, +0, –]</span> 4752280405Srpaulo<pre>void lua_remove (lua_State *L, int index);</pre> 4753280405Srpaulo 4754280405Srpaulo<p> 4755280405SrpauloRemoves the element at the given valid index, 4756280405Srpauloshifting down the elements above this index to fill the gap. 4757280405SrpauloThis function cannot be called with a pseudo-index, 4758280405Srpaulobecause a pseudo-index is not an actual stack position. 4759280405Srpaulo 4760280405Srpaulo 4761280405Srpaulo 4762280405Srpaulo 4763280405Srpaulo 4764280405Srpaulo<hr><h3><a name="lua_replace"><code>lua_replace</code></a></h3><p> 4765280405Srpaulo<span class="apii">[-1, +0, –]</span> 4766280405Srpaulo<pre>void lua_replace (lua_State *L, int index);</pre> 4767280405Srpaulo 4768280405Srpaulo<p> 4769280405SrpauloMoves the top element into the given valid index 4770280405Srpaulowithout shifting any element 4771326344Simp(therefore replacing the value at that given index), 4772280405Srpauloand then pops the top element. 4773280405Srpaulo 4774280405Srpaulo 4775280405Srpaulo 4776280405Srpaulo 4777280405Srpaulo 4778280405Srpaulo<hr><h3><a name="lua_resume"><code>lua_resume</code></a></h3><p> 4779280405Srpaulo<span class="apii">[-?, +?, –]</span> 4780280405Srpaulo<pre>int lua_resume (lua_State *L, lua_State *from, int nargs);</pre> 4781280405Srpaulo 4782280405Srpaulo<p> 4783326344SimpStarts and resumes a coroutine in the given thread <code>L</code>. 4784280405Srpaulo 4785280405Srpaulo 4786280405Srpaulo<p> 4787280405SrpauloTo start a coroutine, 4788280405Srpauloyou push onto the thread stack the main function plus any arguments; 4789280405Srpaulothen you call <a href="#lua_resume"><code>lua_resume</code></a>, 4790280405Srpaulowith <code>nargs</code> being the number of arguments. 4791280405SrpauloThis call returns when the coroutine suspends or finishes its execution. 4792280405SrpauloWhen it returns, the stack contains all values passed to <a href="#lua_yield"><code>lua_yield</code></a>, 4793280405Srpauloor all values returned by the body function. 4794280405Srpaulo<a href="#lua_resume"><code>lua_resume</code></a> returns 4795280405Srpaulo<a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the coroutine yields, 4796280405Srpaulo<a href="#pdf-LUA_OK"><code>LUA_OK</code></a> if the coroutine finishes its execution 4797280405Srpaulowithout errors, 4798280405Srpauloor an error code in case of errors (see <a href="#lua_pcall"><code>lua_pcall</code></a>). 4799280405Srpaulo 4800280405Srpaulo 4801280405Srpaulo<p> 4802280405SrpauloIn case of errors, 4803280405Srpaulothe stack is not unwound, 4804280405Srpauloso you can use the debug API over it. 4805326344SimpThe error object is on the top of the stack. 4806280405Srpaulo 4807280405Srpaulo 4808280405Srpaulo<p> 4809280405SrpauloTo resume a coroutine, 4810280405Srpauloyou remove any results from the last <a href="#lua_yield"><code>lua_yield</code></a>, 4811280405Srpauloput on its stack only the values to 4812280405Srpaulobe passed as results from <code>yield</code>, 4813280405Srpauloand then call <a href="#lua_resume"><code>lua_resume</code></a>. 4814280405Srpaulo 4815280405Srpaulo 4816280405Srpaulo<p> 4817280405SrpauloThe parameter <code>from</code> represents the coroutine that is resuming <code>L</code>. 4818280405SrpauloIf there is no such coroutine, 4819280405Srpaulothis parameter can be <code>NULL</code>. 4820280405Srpaulo 4821280405Srpaulo 4822280405Srpaulo 4823280405Srpaulo 4824280405Srpaulo 4825280405Srpaulo<hr><h3><a name="lua_rotate"><code>lua_rotate</code></a></h3><p> 4826280405Srpaulo<span class="apii">[-0, +0, –]</span> 4827280405Srpaulo<pre>void lua_rotate (lua_State *L, int idx, int n);</pre> 4828280405Srpaulo 4829280405Srpaulo<p> 4830326344SimpRotates the stack elements between the valid index <code>idx</code> 4831326344Simpand the top of the stack. 4832326344SimpThe elements are rotated <code>n</code> positions in the direction of the top, 4833326344Simpfor a positive <code>n</code>, 4834280405Srpauloor <code>-n</code> positions in the direction of the bottom, 4835280405Srpaulofor a negative <code>n</code>. 4836280405SrpauloThe absolute value of <code>n</code> must not be greater than the size 4837280405Srpauloof the slice being rotated. 4838326344SimpThis function cannot be called with a pseudo-index, 4839326344Simpbecause a pseudo-index is not an actual stack position. 4840280405Srpaulo 4841280405Srpaulo 4842280405Srpaulo 4843280405Srpaulo 4844280405Srpaulo 4845280405Srpaulo<hr><h3><a name="lua_setallocf"><code>lua_setallocf</code></a></h3><p> 4846280405Srpaulo<span class="apii">[-0, +0, –]</span> 4847280405Srpaulo<pre>void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);</pre> 4848280405Srpaulo 4849280405Srpaulo<p> 4850280405SrpauloChanges the allocator function of a given state to <code>f</code> 4851280405Srpaulowith user data <code>ud</code>. 4852280405Srpaulo 4853280405Srpaulo 4854280405Srpaulo 4855280405Srpaulo 4856280405Srpaulo 4857280405Srpaulo<hr><h3><a name="lua_setfield"><code>lua_setfield</code></a></h3><p> 4858280405Srpaulo<span class="apii">[-1, +0, <em>e</em>]</span> 4859280405Srpaulo<pre>void lua_setfield (lua_State *L, int index, const char *k);</pre> 4860280405Srpaulo 4861280405Srpaulo<p> 4862280405SrpauloDoes the equivalent to <code>t[k] = v</code>, 4863280405Srpaulowhere <code>t</code> is the value at the given index 4864280405Srpauloand <code>v</code> is the value at the top of the stack. 4865280405Srpaulo 4866280405Srpaulo 4867280405Srpaulo<p> 4868280405SrpauloThis function pops the value from the stack. 4869280405SrpauloAs in Lua, this function may trigger a metamethod 4870280405Srpaulofor the "newindex" event (see <a href="#2.4">§2.4</a>). 4871280405Srpaulo 4872280405Srpaulo 4873280405Srpaulo 4874280405Srpaulo 4875280405Srpaulo 4876280405Srpaulo<hr><h3><a name="lua_setglobal"><code>lua_setglobal</code></a></h3><p> 4877280405Srpaulo<span class="apii">[-1, +0, <em>e</em>]</span> 4878280405Srpaulo<pre>void lua_setglobal (lua_State *L, const char *name);</pre> 4879280405Srpaulo 4880280405Srpaulo<p> 4881280405SrpauloPops a value from the stack and 4882280405Srpaulosets it as the new value of global <code>name</code>. 4883280405Srpaulo 4884280405Srpaulo 4885280405Srpaulo 4886280405Srpaulo 4887280405Srpaulo 4888280405Srpaulo<hr><h3><a name="lua_seti"><code>lua_seti</code></a></h3><p> 4889280405Srpaulo<span class="apii">[-1, +0, <em>e</em>]</span> 4890280405Srpaulo<pre>void lua_seti (lua_State *L, int index, lua_Integer n);</pre> 4891280405Srpaulo 4892280405Srpaulo<p> 4893280405SrpauloDoes the equivalent to <code>t[n] = v</code>, 4894280405Srpaulowhere <code>t</code> is the value at the given index 4895280405Srpauloand <code>v</code> is the value at the top of the stack. 4896280405Srpaulo 4897280405Srpaulo 4898280405Srpaulo<p> 4899280405SrpauloThis function pops the value from the stack. 4900280405SrpauloAs in Lua, this function may trigger a metamethod 4901280405Srpaulofor the "newindex" event (see <a href="#2.4">§2.4</a>). 4902280405Srpaulo 4903280405Srpaulo 4904280405Srpaulo 4905280405Srpaulo 4906280405Srpaulo 4907280405Srpaulo<hr><h3><a name="lua_setmetatable"><code>lua_setmetatable</code></a></h3><p> 4908280405Srpaulo<span class="apii">[-1, +0, –]</span> 4909280405Srpaulo<pre>void lua_setmetatable (lua_State *L, int index);</pre> 4910280405Srpaulo 4911280405Srpaulo<p> 4912280405SrpauloPops a table from the stack and 4913280405Srpaulosets it as the new metatable for the value at the given index. 4914280405Srpaulo 4915280405Srpaulo 4916280405Srpaulo 4917280405Srpaulo 4918280405Srpaulo 4919280405Srpaulo<hr><h3><a name="lua_settable"><code>lua_settable</code></a></h3><p> 4920280405Srpaulo<span class="apii">[-2, +0, <em>e</em>]</span> 4921280405Srpaulo<pre>void lua_settable (lua_State *L, int index);</pre> 4922280405Srpaulo 4923280405Srpaulo<p> 4924280405SrpauloDoes the equivalent to <code>t[k] = v</code>, 4925280405Srpaulowhere <code>t</code> is the value at the given index, 4926280405Srpaulo<code>v</code> is the value at the top of the stack, 4927280405Srpauloand <code>k</code> is the value just below the top. 4928280405Srpaulo 4929280405Srpaulo 4930280405Srpaulo<p> 4931280405SrpauloThis function pops both the key and the value from the stack. 4932280405SrpauloAs in Lua, this function may trigger a metamethod 4933280405Srpaulofor the "newindex" event (see <a href="#2.4">§2.4</a>). 4934280405Srpaulo 4935280405Srpaulo 4936280405Srpaulo 4937280405Srpaulo 4938280405Srpaulo 4939280405Srpaulo<hr><h3><a name="lua_settop"><code>lua_settop</code></a></h3><p> 4940280405Srpaulo<span class="apii">[-?, +?, –]</span> 4941280405Srpaulo<pre>void lua_settop (lua_State *L, int index);</pre> 4942280405Srpaulo 4943280405Srpaulo<p> 4944280405SrpauloAccepts any index, or 0, 4945280405Srpauloand sets the stack top to this index. 4946280405SrpauloIf the new top is larger than the old one, 4947280405Srpaulothen the new elements are filled with <b>nil</b>. 4948280405SrpauloIf <code>index</code> is 0, then all stack elements are removed. 4949280405Srpaulo 4950280405Srpaulo 4951280405Srpaulo 4952280405Srpaulo 4953280405Srpaulo 4954280405Srpaulo<hr><h3><a name="lua_setuservalue"><code>lua_setuservalue</code></a></h3><p> 4955280405Srpaulo<span class="apii">[-1, +0, –]</span> 4956280405Srpaulo<pre>void lua_setuservalue (lua_State *L, int index);</pre> 4957280405Srpaulo 4958280405Srpaulo<p> 4959280405SrpauloPops a value from the stack and sets it as 4960326344Simpthe new value associated to the full userdata at the given index. 4961280405Srpaulo 4962280405Srpaulo 4963280405Srpaulo 4964280405Srpaulo 4965280405Srpaulo 4966280405Srpaulo<hr><h3><a name="lua_State"><code>lua_State</code></a></h3> 4967280405Srpaulo<pre>typedef struct lua_State lua_State;</pre> 4968280405Srpaulo 4969280405Srpaulo<p> 4970280405SrpauloAn opaque structure that points to a thread and indirectly 4971280405Srpaulo(through the thread) to the whole state of a Lua interpreter. 4972280405SrpauloThe Lua library is fully reentrant: 4973280405Srpauloit has no global variables. 4974280405SrpauloAll information about a state is accessible through this structure. 4975280405Srpaulo 4976280405Srpaulo 4977280405Srpaulo<p> 4978280405SrpauloA pointer to this structure must be passed as the first argument to 4979280405Srpauloevery function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>, 4980280405Srpaulowhich creates a Lua state from scratch. 4981280405Srpaulo 4982280405Srpaulo 4983280405Srpaulo 4984280405Srpaulo 4985280405Srpaulo 4986280405Srpaulo<hr><h3><a name="lua_status"><code>lua_status</code></a></h3><p> 4987280405Srpaulo<span class="apii">[-0, +0, –]</span> 4988280405Srpaulo<pre>int lua_status (lua_State *L);</pre> 4989280405Srpaulo 4990280405Srpaulo<p> 4991280405SrpauloReturns the status of the thread <code>L</code>. 4992280405Srpaulo 4993280405Srpaulo 4994280405Srpaulo<p> 4995280405SrpauloThe status can be 0 (<a href="#pdf-LUA_OK"><code>LUA_OK</code></a>) for a normal thread, 4996280405Srpauloan error code if the thread finished the execution 4997280405Srpauloof a <a href="#lua_resume"><code>lua_resume</code></a> with an error, 4998280405Srpauloor <a name="pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the thread is suspended. 4999280405Srpaulo 5000280405Srpaulo 5001280405Srpaulo<p> 5002280405SrpauloYou can only call functions in threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>. 5003280405SrpauloYou can resume threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> 5004280405Srpaulo(to start a new coroutine) or <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> 5005280405Srpaulo(to resume a coroutine). 5006280405Srpaulo 5007280405Srpaulo 5008280405Srpaulo 5009280405Srpaulo 5010280405Srpaulo 5011280405Srpaulo<hr><h3><a name="lua_stringtonumber"><code>lua_stringtonumber</code></a></h3><p> 5012280405Srpaulo<span class="apii">[-0, +1, –]</span> 5013280405Srpaulo<pre>size_t lua_stringtonumber (lua_State *L, const char *s);</pre> 5014280405Srpaulo 5015280405Srpaulo<p> 5016280405SrpauloConverts the zero-terminated string <code>s</code> to a number, 5017280405Srpaulopushes that number into the stack, 5018280405Srpauloand returns the total size of the string, 5019280405Srpaulothat is, its length plus one. 5020280405SrpauloThe conversion can result in an integer or a float, 5021280405Srpauloaccording to the lexical conventions of Lua (see <a href="#3.1">§3.1</a>). 5022280405SrpauloThe string may have leading and trailing spaces and a sign. 5023280405SrpauloIf the string is not a valid numeral, 5024280405Srpauloreturns 0 and pushes nothing. 5025280405Srpaulo(Note that the result can be used as a boolean, 5026280405Srpaulotrue if the conversion succeeds.) 5027280405Srpaulo 5028280405Srpaulo 5029280405Srpaulo 5030280405Srpaulo 5031280405Srpaulo 5032280405Srpaulo<hr><h3><a name="lua_toboolean"><code>lua_toboolean</code></a></h3><p> 5033280405Srpaulo<span class="apii">[-0, +0, –]</span> 5034280405Srpaulo<pre>int lua_toboolean (lua_State *L, int index);</pre> 5035280405Srpaulo 5036280405Srpaulo<p> 5037280405SrpauloConverts the Lua value at the given index to a C boolean 5038280405Srpaulovalue (0 or 1). 5039280405SrpauloLike all tests in Lua, 5040280405Srpaulo<a href="#lua_toboolean"><code>lua_toboolean</code></a> returns true for any Lua value 5041280405Srpaulodifferent from <b>false</b> and <b>nil</b>; 5042280405Srpaulootherwise it returns false. 5043280405Srpaulo(If you want to accept only actual boolean values, 5044280405Srpaulouse <a href="#lua_isboolean"><code>lua_isboolean</code></a> to test the value's type.) 5045280405Srpaulo 5046280405Srpaulo 5047280405Srpaulo 5048280405Srpaulo 5049280405Srpaulo 5050280405Srpaulo<hr><h3><a name="lua_tocfunction"><code>lua_tocfunction</code></a></h3><p> 5051280405Srpaulo<span class="apii">[-0, +0, –]</span> 5052280405Srpaulo<pre>lua_CFunction lua_tocfunction (lua_State *L, int index);</pre> 5053280405Srpaulo 5054280405Srpaulo<p> 5055280405SrpauloConverts a value at the given index to a C function. 5056280405SrpauloThat value must be a C function; 5057280405Srpaulootherwise, returns <code>NULL</code>. 5058280405Srpaulo 5059280405Srpaulo 5060280405Srpaulo 5061280405Srpaulo 5062280405Srpaulo 5063280405Srpaulo<hr><h3><a name="lua_tointeger"><code>lua_tointeger</code></a></h3><p> 5064280405Srpaulo<span class="apii">[-0, +0, –]</span> 5065280405Srpaulo<pre>lua_Integer lua_tointeger (lua_State *L, int index);</pre> 5066280405Srpaulo 5067280405Srpaulo<p> 5068280405SrpauloEquivalent to <a href="#lua_tointegerx"><code>lua_tointegerx</code></a> with <code>isnum</code> equal to <code>NULL</code>. 5069280405Srpaulo 5070280405Srpaulo 5071280405Srpaulo 5072280405Srpaulo 5073280405Srpaulo 5074280405Srpaulo<hr><h3><a name="lua_tointegerx"><code>lua_tointegerx</code></a></h3><p> 5075280405Srpaulo<span class="apii">[-0, +0, –]</span> 5076280405Srpaulo<pre>lua_Integer lua_tointegerx (lua_State *L, int index, int *isnum);</pre> 5077280405Srpaulo 5078280405Srpaulo<p> 5079280405SrpauloConverts the Lua value at the given index 5080280405Srpauloto the signed integral type <a href="#lua_Integer"><code>lua_Integer</code></a>. 5081280405SrpauloThe Lua value must be an integer, 5082280405Srpauloor a number or string convertible to an integer (see <a href="#3.4.3">§3.4.3</a>); 5083280405Srpaulootherwise, <code>lua_tointegerx</code> returns 0. 5084280405Srpaulo 5085280405Srpaulo 5086280405Srpaulo<p> 5087280405SrpauloIf <code>isnum</code> is not <code>NULL</code>, 5088280405Srpauloits referent is assigned a boolean value that 5089280405Srpauloindicates whether the operation succeeded. 5090280405Srpaulo 5091280405Srpaulo 5092280405Srpaulo 5093280405Srpaulo 5094280405Srpaulo 5095280405Srpaulo<hr><h3><a name="lua_tolstring"><code>lua_tolstring</code></a></h3><p> 5096326344Simp<span class="apii">[-0, +0, <em>m</em>]</span> 5097280405Srpaulo<pre>const char *lua_tolstring (lua_State *L, int index, size_t *len);</pre> 5098280405Srpaulo 5099280405Srpaulo<p> 5100280405SrpauloConverts the Lua value at the given index to a C string. 5101280405SrpauloIf <code>len</code> is not <code>NULL</code>, 5102326344Simpit sets <code>*len</code> with the string length. 5103280405SrpauloThe Lua value must be a string or a number; 5104280405Srpaulootherwise, the function returns <code>NULL</code>. 5105280405SrpauloIf the value is a number, 5106280405Srpaulothen <code>lua_tolstring</code> also 5107280405Srpaulo<em>changes the actual value in the stack to a string</em>. 5108280405Srpaulo(This change confuses <a href="#lua_next"><code>lua_next</code></a> 5109280405Srpaulowhen <code>lua_tolstring</code> is applied to keys during a table traversal.) 5110280405Srpaulo 5111280405Srpaulo 5112280405Srpaulo<p> 5113326344Simp<code>lua_tolstring</code> returns a pointer 5114280405Srpauloto a string inside the Lua state. 5115280405SrpauloThis string always has a zero ('<code>\0</code>') 5116280405Srpauloafter its last character (as in C), 5117280405Srpaulobut can contain other zeros in its body. 5118280405Srpaulo 5119280405Srpaulo 5120280405Srpaulo<p> 5121280405SrpauloBecause Lua has garbage collection, 5122280405Srpaulothere is no guarantee that the pointer returned by <code>lua_tolstring</code> 5123280405Srpaulowill be valid after the corresponding Lua value is removed from the stack. 5124280405Srpaulo 5125280405Srpaulo 5126280405Srpaulo 5127280405Srpaulo 5128280405Srpaulo 5129280405Srpaulo<hr><h3><a name="lua_tonumber"><code>lua_tonumber</code></a></h3><p> 5130280405Srpaulo<span class="apii">[-0, +0, –]</span> 5131280405Srpaulo<pre>lua_Number lua_tonumber (lua_State *L, int index);</pre> 5132280405Srpaulo 5133280405Srpaulo<p> 5134280405SrpauloEquivalent to <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> with <code>isnum</code> equal to <code>NULL</code>. 5135280405Srpaulo 5136280405Srpaulo 5137280405Srpaulo 5138280405Srpaulo 5139280405Srpaulo 5140280405Srpaulo<hr><h3><a name="lua_tonumberx"><code>lua_tonumberx</code></a></h3><p> 5141280405Srpaulo<span class="apii">[-0, +0, –]</span> 5142280405Srpaulo<pre>lua_Number lua_tonumberx (lua_State *L, int index, int *isnum);</pre> 5143280405Srpaulo 5144280405Srpaulo<p> 5145280405SrpauloConverts the Lua value at the given index 5146280405Srpauloto the C type <a href="#lua_Number"><code>lua_Number</code></a> (see <a href="#lua_Number"><code>lua_Number</code></a>). 5147280405SrpauloThe Lua value must be a number or a string convertible to a number 5148280405Srpaulo(see <a href="#3.4.3">§3.4.3</a>); 5149280405Srpaulootherwise, <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> returns 0. 5150280405Srpaulo 5151280405Srpaulo 5152280405Srpaulo<p> 5153280405SrpauloIf <code>isnum</code> is not <code>NULL</code>, 5154280405Srpauloits referent is assigned a boolean value that 5155280405Srpauloindicates whether the operation succeeded. 5156280405Srpaulo 5157280405Srpaulo 5158280405Srpaulo 5159280405Srpaulo 5160280405Srpaulo 5161280405Srpaulo<hr><h3><a name="lua_topointer"><code>lua_topointer</code></a></h3><p> 5162280405Srpaulo<span class="apii">[-0, +0, –]</span> 5163280405Srpaulo<pre>const void *lua_topointer (lua_State *L, int index);</pre> 5164280405Srpaulo 5165280405Srpaulo<p> 5166280405SrpauloConverts the value at the given index to a generic 5167280405SrpauloC pointer (<code>void*</code>). 5168280405SrpauloThe value can be a userdata, a table, a thread, or a function; 5169280405Srpaulootherwise, <code>lua_topointer</code> returns <code>NULL</code>. 5170280405SrpauloDifferent objects will give different pointers. 5171280405SrpauloThere is no way to convert the pointer back to its original value. 5172280405Srpaulo 5173280405Srpaulo 5174280405Srpaulo<p> 5175326344SimpTypically this function is used only for hashing and debug information. 5176280405Srpaulo 5177280405Srpaulo 5178280405Srpaulo 5179280405Srpaulo 5180280405Srpaulo 5181280405Srpaulo<hr><h3><a name="lua_tostring"><code>lua_tostring</code></a></h3><p> 5182326344Simp<span class="apii">[-0, +0, <em>m</em>]</span> 5183280405Srpaulo<pre>const char *lua_tostring (lua_State *L, int index);</pre> 5184280405Srpaulo 5185280405Srpaulo<p> 5186280405SrpauloEquivalent to <a href="#lua_tolstring"><code>lua_tolstring</code></a> with <code>len</code> equal to <code>NULL</code>. 5187280405Srpaulo 5188280405Srpaulo 5189280405Srpaulo 5190280405Srpaulo 5191280405Srpaulo 5192280405Srpaulo<hr><h3><a name="lua_tothread"><code>lua_tothread</code></a></h3><p> 5193280405Srpaulo<span class="apii">[-0, +0, –]</span> 5194280405Srpaulo<pre>lua_State *lua_tothread (lua_State *L, int index);</pre> 5195280405Srpaulo 5196280405Srpaulo<p> 5197280405SrpauloConverts the value at the given index to a Lua thread 5198280405Srpaulo(represented as <code>lua_State*</code>). 5199280405SrpauloThis value must be a thread; 5200280405Srpaulootherwise, the function returns <code>NULL</code>. 5201280405Srpaulo 5202280405Srpaulo 5203280405Srpaulo 5204280405Srpaulo 5205280405Srpaulo 5206280405Srpaulo<hr><h3><a name="lua_touserdata"><code>lua_touserdata</code></a></h3><p> 5207280405Srpaulo<span class="apii">[-0, +0, –]</span> 5208280405Srpaulo<pre>void *lua_touserdata (lua_State *L, int index);</pre> 5209280405Srpaulo 5210280405Srpaulo<p> 5211280405SrpauloIf the value at the given index is a full userdata, 5212280405Srpauloreturns its block address. 5213280405SrpauloIf the value is a light userdata, 5214280405Srpauloreturns its pointer. 5215280405SrpauloOtherwise, returns <code>NULL</code>. 5216280405Srpaulo 5217280405Srpaulo 5218280405Srpaulo 5219280405Srpaulo 5220280405Srpaulo 5221280405Srpaulo<hr><h3><a name="lua_type"><code>lua_type</code></a></h3><p> 5222280405Srpaulo<span class="apii">[-0, +0, –]</span> 5223280405Srpaulo<pre>int lua_type (lua_State *L, int index);</pre> 5224280405Srpaulo 5225280405Srpaulo<p> 5226280405SrpauloReturns the type of the value in the given valid index, 5227280405Srpauloor <code>LUA_TNONE</code> for a non-valid (but acceptable) index. 5228280405SrpauloThe types returned by <a href="#lua_type"><code>lua_type</code></a> are coded by the following constants 5229280405Srpaulodefined in <code>lua.h</code>: 5230326344Simp<a name="pdf-LUA_TNIL"><code>LUA_TNIL</code></a> (0), 5231280405Srpaulo<a name="pdf-LUA_TNUMBER"><code>LUA_TNUMBER</code></a>, 5232280405Srpaulo<a name="pdf-LUA_TBOOLEAN"><code>LUA_TBOOLEAN</code></a>, 5233280405Srpaulo<a name="pdf-LUA_TSTRING"><code>LUA_TSTRING</code></a>, 5234280405Srpaulo<a name="pdf-LUA_TTABLE"><code>LUA_TTABLE</code></a>, 5235280405Srpaulo<a name="pdf-LUA_TFUNCTION"><code>LUA_TFUNCTION</code></a>, 5236280405Srpaulo<a name="pdf-LUA_TUSERDATA"><code>LUA_TUSERDATA</code></a>, 5237280405Srpaulo<a name="pdf-LUA_TTHREAD"><code>LUA_TTHREAD</code></a>, 5238280405Srpauloand 5239280405Srpaulo<a name="pdf-LUA_TLIGHTUSERDATA"><code>LUA_TLIGHTUSERDATA</code></a>. 5240280405Srpaulo 5241280405Srpaulo 5242280405Srpaulo 5243280405Srpaulo 5244280405Srpaulo 5245280405Srpaulo<hr><h3><a name="lua_typename"><code>lua_typename</code></a></h3><p> 5246280405Srpaulo<span class="apii">[-0, +0, –]</span> 5247280405Srpaulo<pre>const char *lua_typename (lua_State *L, int tp);</pre> 5248280405Srpaulo 5249280405Srpaulo<p> 5250280405SrpauloReturns the name of the type encoded by the value <code>tp</code>, 5251280405Srpaulowhich must be one the values returned by <a href="#lua_type"><code>lua_type</code></a>. 5252280405Srpaulo 5253280405Srpaulo 5254280405Srpaulo 5255280405Srpaulo 5256280405Srpaulo 5257280405Srpaulo<hr><h3><a name="lua_Unsigned"><code>lua_Unsigned</code></a></h3> 5258280405Srpaulo<pre>typedef ... lua_Unsigned;</pre> 5259280405Srpaulo 5260280405Srpaulo<p> 5261280405SrpauloThe unsigned version of <a href="#lua_Integer"><code>lua_Integer</code></a>. 5262280405Srpaulo 5263280405Srpaulo 5264280405Srpaulo 5265280405Srpaulo 5266280405Srpaulo 5267280405Srpaulo<hr><h3><a name="lua_upvalueindex"><code>lua_upvalueindex</code></a></h3><p> 5268280405Srpaulo<span class="apii">[-0, +0, –]</span> 5269280405Srpaulo<pre>int lua_upvalueindex (int i);</pre> 5270280405Srpaulo 5271280405Srpaulo<p> 5272280405SrpauloReturns the pseudo-index that represents the <code>i</code>-th upvalue of 5273280405Srpaulothe running function (see <a href="#4.4">§4.4</a>). 5274280405Srpaulo 5275280405Srpaulo 5276280405Srpaulo 5277280405Srpaulo 5278280405Srpaulo 5279280405Srpaulo<hr><h3><a name="lua_version"><code>lua_version</code></a></h3><p> 5280326344Simp<span class="apii">[-0, +0, –]</span> 5281280405Srpaulo<pre>const lua_Number *lua_version (lua_State *L);</pre> 5282280405Srpaulo 5283280405Srpaulo<p> 5284326344SimpReturns the address of the version number 5285326344Simp(a C static variable) 5286326344Simpstored in the Lua core. 5287280405SrpauloWhen called with a valid <a href="#lua_State"><code>lua_State</code></a>, 5288280405Srpauloreturns the address of the version used to create that state. 5289280405SrpauloWhen called with <code>NULL</code>, 5290280405Srpauloreturns the address of the version running the call. 5291280405Srpaulo 5292280405Srpaulo 5293280405Srpaulo 5294280405Srpaulo 5295280405Srpaulo 5296280405Srpaulo<hr><h3><a name="lua_Writer"><code>lua_Writer</code></a></h3> 5297280405Srpaulo<pre>typedef int (*lua_Writer) (lua_State *L, 5298280405Srpaulo const void* p, 5299280405Srpaulo size_t sz, 5300280405Srpaulo void* ud);</pre> 5301280405Srpaulo 5302280405Srpaulo<p> 5303280405SrpauloThe type of the writer function used by <a href="#lua_dump"><code>lua_dump</code></a>. 5304280405SrpauloEvery time it produces another piece of chunk, 5305280405Srpaulo<a href="#lua_dump"><code>lua_dump</code></a> calls the writer, 5306280405Srpaulopassing along the buffer to be written (<code>p</code>), 5307280405Srpauloits size (<code>sz</code>), 5308280405Srpauloand the <code>data</code> parameter supplied to <a href="#lua_dump"><code>lua_dump</code></a>. 5309280405Srpaulo 5310280405Srpaulo 5311280405Srpaulo<p> 5312280405SrpauloThe writer returns an error code: 5313280405Srpaulo0 means no errors; 5314280405Srpauloany other value means an error and stops <a href="#lua_dump"><code>lua_dump</code></a> from 5315280405Srpaulocalling the writer again. 5316280405Srpaulo 5317280405Srpaulo 5318280405Srpaulo 5319280405Srpaulo 5320280405Srpaulo 5321280405Srpaulo<hr><h3><a name="lua_xmove"><code>lua_xmove</code></a></h3><p> 5322280405Srpaulo<span class="apii">[-?, +?, –]</span> 5323280405Srpaulo<pre>void lua_xmove (lua_State *from, lua_State *to, int n);</pre> 5324280405Srpaulo 5325280405Srpaulo<p> 5326280405SrpauloExchange values between different threads of the same state. 5327280405Srpaulo 5328280405Srpaulo 5329280405Srpaulo<p> 5330280405SrpauloThis function pops <code>n</code> values from the stack <code>from</code>, 5331280405Srpauloand pushes them onto the stack <code>to</code>. 5332280405Srpaulo 5333280405Srpaulo 5334280405Srpaulo 5335280405Srpaulo 5336280405Srpaulo 5337280405Srpaulo<hr><h3><a name="lua_yield"><code>lua_yield</code></a></h3><p> 5338280405Srpaulo<span class="apii">[-?, +?, <em>e</em>]</span> 5339280405Srpaulo<pre>int lua_yield (lua_State *L, int nresults);</pre> 5340280405Srpaulo 5341280405Srpaulo<p> 5342280405SrpauloThis function is equivalent to <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 5343280405Srpaulobut it has no continuation (see <a href="#4.7">§4.7</a>). 5344280405SrpauloTherefore, when the thread resumes, 5345280405Srpauloit continues the function that called 5346280405Srpaulothe function calling <code>lua_yield</code>. 5347280405Srpaulo 5348280405Srpaulo 5349280405Srpaulo 5350280405Srpaulo 5351280405Srpaulo 5352280405Srpaulo<hr><h3><a name="lua_yieldk"><code>lua_yieldk</code></a></h3><p> 5353280405Srpaulo<span class="apii">[-?, +?, <em>e</em>]</span> 5354280405Srpaulo<pre>int lua_yieldk (lua_State *L, 5355280405Srpaulo int nresults, 5356280405Srpaulo lua_KContext ctx, 5357280405Srpaulo lua_KFunction k);</pre> 5358280405Srpaulo 5359280405Srpaulo<p> 5360280405SrpauloYields a coroutine (thread). 5361280405Srpaulo 5362280405Srpaulo 5363280405Srpaulo<p> 5364280405SrpauloWhen a C function calls <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 5365280405Srpaulothe running coroutine suspends its execution, 5366280405Srpauloand the call to <a href="#lua_resume"><code>lua_resume</code></a> that started this coroutine returns. 5367280405SrpauloThe parameter <code>nresults</code> is the number of values from the stack 5368280405Srpaulothat will be passed as results to <a href="#lua_resume"><code>lua_resume</code></a>. 5369280405Srpaulo 5370280405Srpaulo 5371280405Srpaulo<p> 5372280405SrpauloWhen the coroutine is resumed again, 5373280405SrpauloLua calls the given continuation function <code>k</code> to continue 5374326344Simpthe execution of the C function that yielded (see <a href="#4.7">§4.7</a>). 5375280405SrpauloThis continuation function receives the same stack 5376280405Srpaulofrom the previous function, 5377280405Srpaulowith the <code>n</code> results removed and 5378280405Srpauloreplaced by the arguments passed to <a href="#lua_resume"><code>lua_resume</code></a>. 5379280405SrpauloMoreover, 5380280405Srpaulothe continuation function receives the value <code>ctx</code> 5381280405Srpaulothat was passed to <a href="#lua_yieldk"><code>lua_yieldk</code></a>. 5382280405Srpaulo 5383280405Srpaulo 5384280405Srpaulo<p> 5385280405SrpauloUsually, this function does not return; 5386280405Srpaulowhen the coroutine eventually resumes, 5387280405Srpauloit continues executing the continuation function. 5388280405SrpauloHowever, there is one special case, 5389280405Srpaulowhich is when this function is called 5390326344Simpfrom inside a line or a count hook (see <a href="#4.9">§4.9</a>). 5391280405SrpauloIn that case, <code>lua_yieldk</code> should be called with no continuation 5392326344Simp(probably in the form of <a href="#lua_yield"><code>lua_yield</code></a>) and no results, 5393280405Srpauloand the hook should return immediately after the call. 5394280405SrpauloLua will yield and, 5395280405Srpaulowhen the coroutine resumes again, 5396280405Srpauloit will continue the normal execution 5397280405Srpauloof the (Lua) function that triggered the hook. 5398280405Srpaulo 5399280405Srpaulo 5400280405Srpaulo<p> 5401280405SrpauloThis function can raise an error if it is called from a thread 5402280405Srpaulowith a pending C call with no continuation function, 5403280405Srpauloor it is called from a thread that is not running inside a resume 5404280405Srpaulo(e.g., the main thread). 5405280405Srpaulo 5406280405Srpaulo 5407280405Srpaulo 5408280405Srpaulo 5409280405Srpaulo 5410280405Srpaulo 5411280405Srpaulo 5412280405Srpaulo<h2>4.9 – <a name="4.9">The Debug Interface</a></h2> 5413280405Srpaulo 5414280405Srpaulo<p> 5415280405SrpauloLua has no built-in debugging facilities. 5416280405SrpauloInstead, it offers a special interface 5417280405Srpauloby means of functions and <em>hooks</em>. 5418280405SrpauloThis interface allows the construction of different 5419280405Srpaulokinds of debuggers, profilers, and other tools 5420280405Srpaulothat need "inside information" from the interpreter. 5421280405Srpaulo 5422280405Srpaulo 5423280405Srpaulo 5424280405Srpaulo<hr><h3><a name="lua_Debug"><code>lua_Debug</code></a></h3> 5425280405Srpaulo<pre>typedef struct lua_Debug { 5426280405Srpaulo int event; 5427280405Srpaulo const char *name; /* (n) */ 5428280405Srpaulo const char *namewhat; /* (n) */ 5429280405Srpaulo const char *what; /* (S) */ 5430280405Srpaulo const char *source; /* (S) */ 5431280405Srpaulo int currentline; /* (l) */ 5432280405Srpaulo int linedefined; /* (S) */ 5433280405Srpaulo int lastlinedefined; /* (S) */ 5434280405Srpaulo unsigned char nups; /* (u) number of upvalues */ 5435280405Srpaulo unsigned char nparams; /* (u) number of parameters */ 5436280405Srpaulo char isvararg; /* (u) */ 5437280405Srpaulo char istailcall; /* (t) */ 5438280405Srpaulo char short_src[LUA_IDSIZE]; /* (S) */ 5439280405Srpaulo /* private part */ 5440280405Srpaulo <em>other fields</em> 5441280405Srpaulo} lua_Debug;</pre> 5442280405Srpaulo 5443280405Srpaulo<p> 5444280405SrpauloA structure used to carry different pieces of 5445280405Srpauloinformation about a function or an activation record. 5446280405Srpaulo<a href="#lua_getstack"><code>lua_getstack</code></a> fills only the private part 5447280405Srpauloof this structure, for later use. 5448280405SrpauloTo fill the other fields of <a href="#lua_Debug"><code>lua_Debug</code></a> with useful information, 5449280405Srpaulocall <a href="#lua_getinfo"><code>lua_getinfo</code></a>. 5450280405Srpaulo 5451280405Srpaulo 5452280405Srpaulo<p> 5453280405SrpauloThe fields of <a href="#lua_Debug"><code>lua_Debug</code></a> have the following meaning: 5454280405Srpaulo 5455280405Srpaulo<ul> 5456280405Srpaulo 5457280405Srpaulo<li><b><code>source</code>: </b> 5458280405Srpaulothe name of the chunk that created the function. 5459280405SrpauloIf <code>source</code> starts with a '<code>@</code>', 5460280405Srpauloit means that the function was defined in a file where 5461280405Srpaulothe file name follows the '<code>@</code>'. 5462280405SrpauloIf <code>source</code> starts with a '<code>=</code>', 5463280405Srpaulothe remainder of its contents describe the source in a user-dependent manner. 5464280405SrpauloOtherwise, 5465280405Srpaulothe function was defined in a string where 5466280405Srpaulo<code>source</code> is that string. 5467280405Srpaulo</li> 5468280405Srpaulo 5469280405Srpaulo<li><b><code>short_src</code>: </b> 5470280405Srpauloa "printable" version of <code>source</code>, to be used in error messages. 5471280405Srpaulo</li> 5472280405Srpaulo 5473280405Srpaulo<li><b><code>linedefined</code>: </b> 5474280405Srpaulothe line number where the definition of the function starts. 5475280405Srpaulo</li> 5476280405Srpaulo 5477280405Srpaulo<li><b><code>lastlinedefined</code>: </b> 5478280405Srpaulothe line number where the definition of the function ends. 5479280405Srpaulo</li> 5480280405Srpaulo 5481280405Srpaulo<li><b><code>what</code>: </b> 5482280405Srpaulothe string <code>"Lua"</code> if the function is a Lua function, 5483280405Srpaulo<code>"C"</code> if it is a C function, 5484280405Srpaulo<code>"main"</code> if it is the main part of a chunk. 5485280405Srpaulo</li> 5486280405Srpaulo 5487280405Srpaulo<li><b><code>currentline</code>: </b> 5488280405Srpaulothe current line where the given function is executing. 5489280405SrpauloWhen no line information is available, 5490280405Srpaulo<code>currentline</code> is set to -1. 5491280405Srpaulo</li> 5492280405Srpaulo 5493280405Srpaulo<li><b><code>name</code>: </b> 5494280405Srpauloa reasonable name for the given function. 5495280405SrpauloBecause functions in Lua are first-class values, 5496280405Srpaulothey do not have a fixed name: 5497280405Srpaulosome functions can be the value of multiple global variables, 5498280405Srpaulowhile others can be stored only in a table field. 5499280405SrpauloThe <code>lua_getinfo</code> function checks how the function was 5500280405Srpaulocalled to find a suitable name. 5501280405SrpauloIf it cannot find a name, 5502280405Srpaulothen <code>name</code> is set to <code>NULL</code>. 5503280405Srpaulo</li> 5504280405Srpaulo 5505280405Srpaulo<li><b><code>namewhat</code>: </b> 5506280405Srpauloexplains the <code>name</code> field. 5507280405SrpauloThe value of <code>namewhat</code> can be 5508280405Srpaulo<code>"global"</code>, <code>"local"</code>, <code>"method"</code>, 5509280405Srpaulo<code>"field"</code>, <code>"upvalue"</code>, or <code>""</code> (the empty string), 5510280405Srpauloaccording to how the function was called. 5511280405Srpaulo(Lua uses the empty string when no other option seems to apply.) 5512280405Srpaulo</li> 5513280405Srpaulo 5514280405Srpaulo<li><b><code>istailcall</code>: </b> 5515280405Srpaulotrue if this function invocation was called by a tail call. 5516280405SrpauloIn this case, the caller of this level is not in the stack. 5517280405Srpaulo</li> 5518280405Srpaulo 5519280405Srpaulo<li><b><code>nups</code>: </b> 5520280405Srpaulothe number of upvalues of the function. 5521280405Srpaulo</li> 5522280405Srpaulo 5523280405Srpaulo<li><b><code>nparams</code>: </b> 5524280405Srpaulothe number of fixed parameters of the function 5525280405Srpaulo(always 0 for C functions). 5526280405Srpaulo</li> 5527280405Srpaulo 5528280405Srpaulo<li><b><code>isvararg</code>: </b> 5529280405Srpaulotrue if the function is a vararg function 5530280405Srpaulo(always true for C functions). 5531280405Srpaulo</li> 5532280405Srpaulo 5533280405Srpaulo</ul> 5534280405Srpaulo 5535280405Srpaulo 5536280405Srpaulo 5537280405Srpaulo 5538280405Srpaulo<hr><h3><a name="lua_gethook"><code>lua_gethook</code></a></h3><p> 5539280405Srpaulo<span class="apii">[-0, +0, –]</span> 5540280405Srpaulo<pre>lua_Hook lua_gethook (lua_State *L);</pre> 5541280405Srpaulo 5542280405Srpaulo<p> 5543280405SrpauloReturns the current hook function. 5544280405Srpaulo 5545280405Srpaulo 5546280405Srpaulo 5547280405Srpaulo 5548280405Srpaulo 5549280405Srpaulo<hr><h3><a name="lua_gethookcount"><code>lua_gethookcount</code></a></h3><p> 5550280405Srpaulo<span class="apii">[-0, +0, –]</span> 5551280405Srpaulo<pre>int lua_gethookcount (lua_State *L);</pre> 5552280405Srpaulo 5553280405Srpaulo<p> 5554280405SrpauloReturns the current hook count. 5555280405Srpaulo 5556280405Srpaulo 5557280405Srpaulo 5558280405Srpaulo 5559280405Srpaulo 5560280405Srpaulo<hr><h3><a name="lua_gethookmask"><code>lua_gethookmask</code></a></h3><p> 5561280405Srpaulo<span class="apii">[-0, +0, –]</span> 5562280405Srpaulo<pre>int lua_gethookmask (lua_State *L);</pre> 5563280405Srpaulo 5564280405Srpaulo<p> 5565280405SrpauloReturns the current hook mask. 5566280405Srpaulo 5567280405Srpaulo 5568280405Srpaulo 5569280405Srpaulo 5570280405Srpaulo 5571280405Srpaulo<hr><h3><a name="lua_getinfo"><code>lua_getinfo</code></a></h3><p> 5572280405Srpaulo<span class="apii">[-(0|1), +(0|1|2), <em>e</em>]</span> 5573280405Srpaulo<pre>int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar);</pre> 5574280405Srpaulo 5575280405Srpaulo<p> 5576280405SrpauloGets information about a specific function or function invocation. 5577280405Srpaulo 5578280405Srpaulo 5579280405Srpaulo<p> 5580280405SrpauloTo get information about a function invocation, 5581280405Srpaulothe parameter <code>ar</code> must be a valid activation record that was 5582280405Srpaulofilled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or 5583280405Srpaulogiven as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>). 5584280405Srpaulo 5585280405Srpaulo 5586280405Srpaulo<p> 5587280405SrpauloTo get information about a function you push it onto the stack 5588280405Srpauloand start the <code>what</code> string with the character '<code>></code>'. 5589280405Srpaulo(In that case, 5590280405Srpaulo<code>lua_getinfo</code> pops the function from the top of the stack.) 5591280405SrpauloFor instance, to know in which line a function <code>f</code> was defined, 5592280405Srpauloyou can write the following code: 5593280405Srpaulo 5594280405Srpaulo<pre> 5595280405Srpaulo lua_Debug ar; 5596280405Srpaulo lua_getglobal(L, "f"); /* get global 'f' */ 5597280405Srpaulo lua_getinfo(L, ">S", &ar); 5598280405Srpaulo printf("%d\n", ar.linedefined); 5599280405Srpaulo</pre> 5600280405Srpaulo 5601280405Srpaulo<p> 5602280405SrpauloEach character in the string <code>what</code> 5603280405Srpauloselects some fields of the structure <code>ar</code> to be filled or 5604280405Srpauloa value to be pushed on the stack: 5605280405Srpaulo 5606280405Srpaulo<ul> 5607280405Srpaulo 5608280405Srpaulo<li><b>'<code>n</code>': </b> fills in the field <code>name</code> and <code>namewhat</code>; 5609280405Srpaulo</li> 5610280405Srpaulo 5611280405Srpaulo<li><b>'<code>S</code>': </b> 5612280405Srpaulofills in the fields <code>source</code>, <code>short_src</code>, 5613280405Srpaulo<code>linedefined</code>, <code>lastlinedefined</code>, and <code>what</code>; 5614280405Srpaulo</li> 5615280405Srpaulo 5616280405Srpaulo<li><b>'<code>l</code>': </b> fills in the field <code>currentline</code>; 5617280405Srpaulo</li> 5618280405Srpaulo 5619280405Srpaulo<li><b>'<code>t</code>': </b> fills in the field <code>istailcall</code>; 5620280405Srpaulo</li> 5621280405Srpaulo 5622280405Srpaulo<li><b>'<code>u</code>': </b> fills in the fields 5623280405Srpaulo<code>nups</code>, <code>nparams</code>, and <code>isvararg</code>; 5624280405Srpaulo</li> 5625280405Srpaulo 5626280405Srpaulo<li><b>'<code>f</code>': </b> 5627280405Srpaulopushes onto the stack the function that is 5628280405Srpaulorunning at the given level; 5629280405Srpaulo</li> 5630280405Srpaulo 5631280405Srpaulo<li><b>'<code>L</code>': </b> 5632280405Srpaulopushes onto the stack a table whose indices are the 5633280405Srpaulonumbers of the lines that are valid on the function. 5634280405Srpaulo(A <em>valid line</em> is a line with some associated code, 5635280405Srpaulothat is, a line where you can put a break point. 5636280405SrpauloNon-valid lines include empty lines and comments.) 5637280405Srpaulo 5638280405Srpaulo 5639280405Srpaulo<p> 5640280405SrpauloIf this option is given together with option '<code>f</code>', 5641280405Srpauloits table is pushed after the function. 5642280405Srpaulo</li> 5643280405Srpaulo 5644280405Srpaulo</ul> 5645280405Srpaulo 5646280405Srpaulo<p> 5647280405SrpauloThis function returns 0 on error 5648280405Srpaulo(for instance, an invalid option in <code>what</code>). 5649280405Srpaulo 5650280405Srpaulo 5651280405Srpaulo 5652280405Srpaulo 5653280405Srpaulo 5654280405Srpaulo<hr><h3><a name="lua_getlocal"><code>lua_getlocal</code></a></h3><p> 5655280405Srpaulo<span class="apii">[-0, +(0|1), –]</span> 5656280405Srpaulo<pre>const char *lua_getlocal (lua_State *L, const lua_Debug *ar, int n);</pre> 5657280405Srpaulo 5658280405Srpaulo<p> 5659280405SrpauloGets information about a local variable of 5660280405Srpauloa given activation record or a given function. 5661280405Srpaulo 5662280405Srpaulo 5663280405Srpaulo<p> 5664280405SrpauloIn the first case, 5665280405Srpaulothe parameter <code>ar</code> must be a valid activation record that was 5666280405Srpaulofilled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or 5667280405Srpaulogiven as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>). 5668280405SrpauloThe index <code>n</code> selects which local variable to inspect; 5669280405Srpaulosee <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for details about variable indices 5670280405Srpauloand names. 5671280405Srpaulo 5672280405Srpaulo 5673280405Srpaulo<p> 5674280405Srpaulo<a href="#lua_getlocal"><code>lua_getlocal</code></a> pushes the variable's value onto the stack 5675280405Srpauloand returns its name. 5676280405Srpaulo 5677280405Srpaulo 5678280405Srpaulo<p> 5679280405SrpauloIn the second case, <code>ar</code> must be <code>NULL</code> and the function 5680280405Srpauloto be inspected must be at the top of the stack. 5681280405SrpauloIn this case, only parameters of Lua functions are visible 5682280405Srpaulo(as there is no information about what variables are active) 5683280405Srpauloand no values are pushed onto the stack. 5684280405Srpaulo 5685280405Srpaulo 5686280405Srpaulo<p> 5687280405SrpauloReturns <code>NULL</code> (and pushes nothing) 5688280405Srpaulowhen the index is greater than 5689280405Srpaulothe number of active local variables. 5690280405Srpaulo 5691280405Srpaulo 5692280405Srpaulo 5693280405Srpaulo 5694280405Srpaulo 5695280405Srpaulo<hr><h3><a name="lua_getstack"><code>lua_getstack</code></a></h3><p> 5696280405Srpaulo<span class="apii">[-0, +0, –]</span> 5697280405Srpaulo<pre>int lua_getstack (lua_State *L, int level, lua_Debug *ar);</pre> 5698280405Srpaulo 5699280405Srpaulo<p> 5700280405SrpauloGets information about the interpreter runtime stack. 5701280405Srpaulo 5702280405Srpaulo 5703280405Srpaulo<p> 5704280405SrpauloThis function fills parts of a <a href="#lua_Debug"><code>lua_Debug</code></a> structure with 5705280405Srpauloan identification of the <em>activation record</em> 5706280405Srpauloof the function executing at a given level. 5707280405SrpauloLevel 0 is the current running function, 5708280405Srpaulowhereas level <em>n+1</em> is the function that has called level <em>n</em> 5709280405Srpaulo(except for tail calls, which do not count on the stack). 5710280405SrpauloWhen there are no errors, <a href="#lua_getstack"><code>lua_getstack</code></a> returns 1; 5711280405Srpaulowhen called with a level greater than the stack depth, 5712280405Srpauloit returns 0. 5713280405Srpaulo 5714280405Srpaulo 5715280405Srpaulo 5716280405Srpaulo 5717280405Srpaulo 5718280405Srpaulo<hr><h3><a name="lua_getupvalue"><code>lua_getupvalue</code></a></h3><p> 5719280405Srpaulo<span class="apii">[-0, +(0|1), –]</span> 5720280405Srpaulo<pre>const char *lua_getupvalue (lua_State *L, int funcindex, int n);</pre> 5721280405Srpaulo 5722280405Srpaulo<p> 5723326344SimpGets information about the <code>n</code>-th upvalue 5724326344Simpof the closure at index <code>funcindex</code>. 5725326344SimpIt pushes the upvalue's value onto the stack 5726280405Srpauloand returns its name. 5727326344SimpReturns <code>NULL</code> (and pushes nothing) 5728326344Simpwhen the index <code>n</code> is greater than the number of upvalues. 5729280405Srpaulo 5730280405Srpaulo 5731280405Srpaulo<p> 5732280405SrpauloFor C functions, this function uses the empty string <code>""</code> 5733280405Srpauloas a name for all upvalues. 5734326344Simp(For Lua functions, 5735326344Simpupvalues are the external local variables that the function uses, 5736326344Simpand that are consequently included in its closure.) 5737280405Srpaulo 5738280405Srpaulo 5739326344Simp<p> 5740326344SimpUpvalues have no particular order, 5741326344Simpas they are active through the whole function. 5742326344SimpThey are numbered in an arbitrary order. 5743280405Srpaulo 5744280405Srpaulo 5745280405Srpaulo 5746326344Simp 5747326344Simp 5748280405Srpaulo<hr><h3><a name="lua_Hook"><code>lua_Hook</code></a></h3> 5749280405Srpaulo<pre>typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar);</pre> 5750280405Srpaulo 5751280405Srpaulo<p> 5752280405SrpauloType for debugging hook functions. 5753280405Srpaulo 5754280405Srpaulo 5755280405Srpaulo<p> 5756280405SrpauloWhenever a hook is called, its <code>ar</code> argument has its field 5757280405Srpaulo<code>event</code> set to the specific event that triggered the hook. 5758280405SrpauloLua identifies these events with the following constants: 5759280405Srpaulo<a name="pdf-LUA_HOOKCALL"><code>LUA_HOOKCALL</code></a>, <a name="pdf-LUA_HOOKRET"><code>LUA_HOOKRET</code></a>, 5760280405Srpaulo<a name="pdf-LUA_HOOKTAILCALL"><code>LUA_HOOKTAILCALL</code></a>, <a name="pdf-LUA_HOOKLINE"><code>LUA_HOOKLINE</code></a>, 5761280405Srpauloand <a name="pdf-LUA_HOOKCOUNT"><code>LUA_HOOKCOUNT</code></a>. 5762280405SrpauloMoreover, for line events, the field <code>currentline</code> is also set. 5763280405SrpauloTo get the value of any other field in <code>ar</code>, 5764280405Srpaulothe hook must call <a href="#lua_getinfo"><code>lua_getinfo</code></a>. 5765280405Srpaulo 5766280405Srpaulo 5767280405Srpaulo<p> 5768280405SrpauloFor call events, <code>event</code> can be <code>LUA_HOOKCALL</code>, 5769280405Srpaulothe normal value, or <code>LUA_HOOKTAILCALL</code>, for a tail call; 5770280405Srpauloin this case, there will be no corresponding return event. 5771280405Srpaulo 5772280405Srpaulo 5773280405Srpaulo<p> 5774280405SrpauloWhile Lua is running a hook, it disables other calls to hooks. 5775280405SrpauloTherefore, if a hook calls back Lua to execute a function or a chunk, 5776280405Srpaulothis execution occurs without any calls to hooks. 5777280405Srpaulo 5778280405Srpaulo 5779280405Srpaulo<p> 5780280405SrpauloHook functions cannot have continuations, 5781280405Srpaulothat is, they cannot call <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 5782280405Srpaulo<a href="#lua_pcallk"><code>lua_pcallk</code></a>, or <a href="#lua_callk"><code>lua_callk</code></a> with a non-null <code>k</code>. 5783280405Srpaulo 5784280405Srpaulo 5785280405Srpaulo<p> 5786280405SrpauloHook functions can yield under the following conditions: 5787326344SimpOnly count and line events can yield; 5788326344Simpto yield, a hook function must finish its execution 5789326344Simpcalling <a href="#lua_yield"><code>lua_yield</code></a> with <code>nresults</code> equal to zero 5790326344Simp(that is, with no values). 5791280405Srpaulo 5792280405Srpaulo 5793280405Srpaulo 5794280405Srpaulo 5795280405Srpaulo 5796280405Srpaulo<hr><h3><a name="lua_sethook"><code>lua_sethook</code></a></h3><p> 5797280405Srpaulo<span class="apii">[-0, +0, –]</span> 5798280405Srpaulo<pre>void lua_sethook (lua_State *L, lua_Hook f, int mask, int count);</pre> 5799280405Srpaulo 5800280405Srpaulo<p> 5801280405SrpauloSets the debugging hook function. 5802280405Srpaulo 5803280405Srpaulo 5804280405Srpaulo<p> 5805280405SrpauloArgument <code>f</code> is the hook function. 5806280405Srpaulo<code>mask</code> specifies on which events the hook will be called: 5807326344Simpit is formed by a bitwise OR of the constants 5808280405Srpaulo<a name="pdf-LUA_MASKCALL"><code>LUA_MASKCALL</code></a>, 5809280405Srpaulo<a name="pdf-LUA_MASKRET"><code>LUA_MASKRET</code></a>, 5810280405Srpaulo<a name="pdf-LUA_MASKLINE"><code>LUA_MASKLINE</code></a>, 5811280405Srpauloand <a name="pdf-LUA_MASKCOUNT"><code>LUA_MASKCOUNT</code></a>. 5812280405SrpauloThe <code>count</code> argument is only meaningful when the mask 5813280405Srpauloincludes <code>LUA_MASKCOUNT</code>. 5814280405SrpauloFor each event, the hook is called as explained below: 5815280405Srpaulo 5816280405Srpaulo<ul> 5817280405Srpaulo 5818280405Srpaulo<li><b>The call hook: </b> is called when the interpreter calls a function. 5819280405SrpauloThe hook is called just after Lua enters the new function, 5820280405Srpaulobefore the function gets its arguments. 5821280405Srpaulo</li> 5822280405Srpaulo 5823280405Srpaulo<li><b>The return hook: </b> is called when the interpreter returns from a function. 5824280405SrpauloThe hook is called just before Lua leaves the function. 5825280405SrpauloThere is no standard way to access the values 5826280405Srpauloto be returned by the function. 5827280405Srpaulo</li> 5828280405Srpaulo 5829280405Srpaulo<li><b>The line hook: </b> is called when the interpreter is about to 5830280405Srpaulostart the execution of a new line of code, 5831280405Srpauloor when it jumps back in the code (even to the same line). 5832280405Srpaulo(This event only happens while Lua is executing a Lua function.) 5833280405Srpaulo</li> 5834280405Srpaulo 5835280405Srpaulo<li><b>The count hook: </b> is called after the interpreter executes every 5836280405Srpaulo<code>count</code> instructions. 5837280405Srpaulo(This event only happens while Lua is executing a Lua function.) 5838280405Srpaulo</li> 5839280405Srpaulo 5840280405Srpaulo</ul> 5841280405Srpaulo 5842280405Srpaulo<p> 5843280405SrpauloA hook is disabled by setting <code>mask</code> to zero. 5844280405Srpaulo 5845280405Srpaulo 5846280405Srpaulo 5847280405Srpaulo 5848280405Srpaulo 5849280405Srpaulo<hr><h3><a name="lua_setlocal"><code>lua_setlocal</code></a></h3><p> 5850280405Srpaulo<span class="apii">[-(0|1), +0, –]</span> 5851280405Srpaulo<pre>const char *lua_setlocal (lua_State *L, const lua_Debug *ar, int n);</pre> 5852280405Srpaulo 5853280405Srpaulo<p> 5854280405SrpauloSets the value of a local variable of a given activation record. 5855326344SimpIt assigns the value at the top of the stack 5856280405Srpauloto the variable and returns its name. 5857280405SrpauloIt also pops the value from the stack. 5858280405Srpaulo 5859280405Srpaulo 5860280405Srpaulo<p> 5861280405SrpauloReturns <code>NULL</code> (and pops nothing) 5862280405Srpaulowhen the index is greater than 5863280405Srpaulothe number of active local variables. 5864280405Srpaulo 5865280405Srpaulo 5866326344Simp<p> 5867326344SimpParameters <code>ar</code> and <code>n</code> are as in function <a href="#lua_getlocal"><code>lua_getlocal</code></a>. 5868280405Srpaulo 5869280405Srpaulo 5870280405Srpaulo 5871326344Simp 5872326344Simp 5873280405Srpaulo<hr><h3><a name="lua_setupvalue"><code>lua_setupvalue</code></a></h3><p> 5874280405Srpaulo<span class="apii">[-(0|1), +0, –]</span> 5875280405Srpaulo<pre>const char *lua_setupvalue (lua_State *L, int funcindex, int n);</pre> 5876280405Srpaulo 5877280405Srpaulo<p> 5878280405SrpauloSets the value of a closure's upvalue. 5879280405SrpauloIt assigns the value at the top of the stack 5880280405Srpauloto the upvalue and returns its name. 5881280405SrpauloIt also pops the value from the stack. 5882280405Srpaulo 5883280405Srpaulo 5884280405Srpaulo<p> 5885280405SrpauloReturns <code>NULL</code> (and pops nothing) 5886326344Simpwhen the index <code>n</code> is greater than the number of upvalues. 5887280405Srpaulo 5888280405Srpaulo 5889326344Simp<p> 5890326344SimpParameters <code>funcindex</code> and <code>n</code> are as in function <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>. 5891280405Srpaulo 5892280405Srpaulo 5893280405Srpaulo 5894326344Simp 5895326344Simp 5896280405Srpaulo<hr><h3><a name="lua_upvalueid"><code>lua_upvalueid</code></a></h3><p> 5897280405Srpaulo<span class="apii">[-0, +0, –]</span> 5898280405Srpaulo<pre>void *lua_upvalueid (lua_State *L, int funcindex, int n);</pre> 5899280405Srpaulo 5900280405Srpaulo<p> 5901280405SrpauloReturns a unique identifier for the upvalue numbered <code>n</code> 5902280405Srpaulofrom the closure at index <code>funcindex</code>. 5903280405Srpaulo 5904280405Srpaulo 5905280405Srpaulo<p> 5906280405SrpauloThese unique identifiers allow a program to check whether different 5907280405Srpauloclosures share upvalues. 5908280405SrpauloLua closures that share an upvalue 5909280405Srpaulo(that is, that access a same external local variable) 5910280405Srpaulowill return identical ids for those upvalue indices. 5911280405Srpaulo 5912280405Srpaulo 5913326344Simp<p> 5914326344SimpParameters <code>funcindex</code> and <code>n</code> are as in function <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>, 5915326344Simpbut <code>n</code> cannot be greater than the number of upvalues. 5916280405Srpaulo 5917280405Srpaulo 5918280405Srpaulo 5919326344Simp 5920326344Simp 5921280405Srpaulo<hr><h3><a name="lua_upvaluejoin"><code>lua_upvaluejoin</code></a></h3><p> 5922280405Srpaulo<span class="apii">[-0, +0, –]</span> 5923280405Srpaulo<pre>void lua_upvaluejoin (lua_State *L, int funcindex1, int n1, 5924280405Srpaulo int funcindex2, int n2);</pre> 5925280405Srpaulo 5926280405Srpaulo<p> 5927280405SrpauloMake the <code>n1</code>-th upvalue of the Lua closure at index <code>funcindex1</code> 5928280405Srpaulorefer to the <code>n2</code>-th upvalue of the Lua closure at index <code>funcindex2</code>. 5929280405Srpaulo 5930280405Srpaulo 5931280405Srpaulo 5932280405Srpaulo 5933280405Srpaulo 5934280405Srpaulo 5935280405Srpaulo 5936280405Srpaulo<h1>5 – <a name="5">The Auxiliary Library</a></h1> 5937280405Srpaulo 5938280405Srpaulo<p> 5939280405Srpaulo 5940280405SrpauloThe <em>auxiliary library</em> provides several convenient functions 5941280405Srpauloto interface C with Lua. 5942280405SrpauloWhile the basic API provides the primitive functions for all 5943280405Srpaulointeractions between C and Lua, 5944280405Srpaulothe auxiliary library provides higher-level functions for some 5945280405Srpaulocommon tasks. 5946280405Srpaulo 5947280405Srpaulo 5948280405Srpaulo<p> 5949280405SrpauloAll functions and types from the auxiliary library 5950280405Srpauloare defined in header file <code>lauxlib.h</code> and 5951280405Srpaulohave a prefix <code>luaL_</code>. 5952280405Srpaulo 5953280405Srpaulo 5954280405Srpaulo<p> 5955280405SrpauloAll functions in the auxiliary library are built on 5956280405Srpaulotop of the basic API, 5957280405Srpauloand so they provide nothing that cannot be done with that API. 5958280405SrpauloNevertheless, the use of the auxiliary library ensures 5959280405Srpaulomore consistency to your code. 5960280405Srpaulo 5961280405Srpaulo 5962280405Srpaulo<p> 5963280405SrpauloSeveral functions in the auxiliary library use internally some 5964280405Srpauloextra stack slots. 5965280405SrpauloWhen a function in the auxiliary library uses less than five slots, 5966280405Srpauloit does not check the stack size; 5967280405Srpauloit simply assumes that there are enough slots. 5968280405Srpaulo 5969280405Srpaulo 5970280405Srpaulo<p> 5971280405SrpauloSeveral functions in the auxiliary library are used to 5972280405Srpaulocheck C function arguments. 5973280405SrpauloBecause the error message is formatted for arguments 5974280405Srpaulo(e.g., "<code>bad argument #1</code>"), 5975280405Srpauloyou should not use these functions for other stack values. 5976280405Srpaulo 5977280405Srpaulo 5978280405Srpaulo<p> 5979280405SrpauloFunctions called <code>luaL_check*</code> 5980280405Srpauloalways raise an error if the check is not satisfied. 5981280405Srpaulo 5982280405Srpaulo 5983280405Srpaulo 5984280405Srpaulo<h2>5.1 – <a name="5.1">Functions and Types</a></h2> 5985280405Srpaulo 5986280405Srpaulo<p> 5987280405SrpauloHere we list all functions and types from the auxiliary library 5988280405Srpauloin alphabetical order. 5989280405Srpaulo 5990280405Srpaulo 5991280405Srpaulo 5992280405Srpaulo<hr><h3><a name="luaL_addchar"><code>luaL_addchar</code></a></h3><p> 5993326344Simp<span class="apii">[-?, +?, <em>m</em>]</span> 5994280405Srpaulo<pre>void luaL_addchar (luaL_Buffer *B, char c);</pre> 5995280405Srpaulo 5996280405Srpaulo<p> 5997280405SrpauloAdds the byte <code>c</code> to the buffer <code>B</code> 5998280405Srpaulo(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 5999280405Srpaulo 6000280405Srpaulo 6001280405Srpaulo 6002280405Srpaulo 6003280405Srpaulo 6004280405Srpaulo<hr><h3><a name="luaL_addlstring"><code>luaL_addlstring</code></a></h3><p> 6005326344Simp<span class="apii">[-?, +?, <em>m</em>]</span> 6006280405Srpaulo<pre>void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l);</pre> 6007280405Srpaulo 6008280405Srpaulo<p> 6009280405SrpauloAdds the string pointed to by <code>s</code> with length <code>l</code> to 6010280405Srpaulothe buffer <code>B</code> 6011280405Srpaulo(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6012280405SrpauloThe string can contain embedded zeros. 6013280405Srpaulo 6014280405Srpaulo 6015280405Srpaulo 6016280405Srpaulo 6017280405Srpaulo 6018280405Srpaulo<hr><h3><a name="luaL_addsize"><code>luaL_addsize</code></a></h3><p> 6019326344Simp<span class="apii">[-?, +?, –]</span> 6020280405Srpaulo<pre>void luaL_addsize (luaL_Buffer *B, size_t n);</pre> 6021280405Srpaulo 6022280405Srpaulo<p> 6023280405SrpauloAdds to the buffer <code>B</code> (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>) 6024280405Srpauloa string of length <code>n</code> previously copied to the 6025280405Srpaulobuffer area (see <a href="#luaL_prepbuffer"><code>luaL_prepbuffer</code></a>). 6026280405Srpaulo 6027280405Srpaulo 6028280405Srpaulo 6029280405Srpaulo 6030280405Srpaulo 6031280405Srpaulo<hr><h3><a name="luaL_addstring"><code>luaL_addstring</code></a></h3><p> 6032326344Simp<span class="apii">[-?, +?, <em>m</em>]</span> 6033280405Srpaulo<pre>void luaL_addstring (luaL_Buffer *B, const char *s);</pre> 6034280405Srpaulo 6035280405Srpaulo<p> 6036280405SrpauloAdds the zero-terminated string pointed to by <code>s</code> 6037280405Srpauloto the buffer <code>B</code> 6038280405Srpaulo(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6039280405Srpaulo 6040280405Srpaulo 6041280405Srpaulo 6042280405Srpaulo 6043280405Srpaulo 6044280405Srpaulo<hr><h3><a name="luaL_addvalue"><code>luaL_addvalue</code></a></h3><p> 6045326344Simp<span class="apii">[-1, +?, <em>m</em>]</span> 6046280405Srpaulo<pre>void luaL_addvalue (luaL_Buffer *B);</pre> 6047280405Srpaulo 6048280405Srpaulo<p> 6049280405SrpauloAdds the value at the top of the stack 6050280405Srpauloto the buffer <code>B</code> 6051280405Srpaulo(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6052280405SrpauloPops the value. 6053280405Srpaulo 6054280405Srpaulo 6055280405Srpaulo<p> 6056280405SrpauloThis is the only function on string buffers that can (and must) 6057280405Srpaulobe called with an extra element on the stack, 6058280405Srpaulowhich is the value to be added to the buffer. 6059280405Srpaulo 6060280405Srpaulo 6061280405Srpaulo 6062280405Srpaulo 6063280405Srpaulo 6064280405Srpaulo<hr><h3><a name="luaL_argcheck"><code>luaL_argcheck</code></a></h3><p> 6065280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span> 6066280405Srpaulo<pre>void luaL_argcheck (lua_State *L, 6067280405Srpaulo int cond, 6068280405Srpaulo int arg, 6069280405Srpaulo const char *extramsg);</pre> 6070280405Srpaulo 6071280405Srpaulo<p> 6072280405SrpauloChecks whether <code>cond</code> is true. 6073280405SrpauloIf it is not, raises an error with a standard message (see <a href="#luaL_argerror"><code>luaL_argerror</code></a>). 6074280405Srpaulo 6075280405Srpaulo 6076280405Srpaulo 6077280405Srpaulo 6078280405Srpaulo 6079280405Srpaulo<hr><h3><a name="luaL_argerror"><code>luaL_argerror</code></a></h3><p> 6080280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span> 6081280405Srpaulo<pre>int luaL_argerror (lua_State *L, int arg, const char *extramsg);</pre> 6082280405Srpaulo 6083280405Srpaulo<p> 6084280405SrpauloRaises an error reporting a problem with argument <code>arg</code> 6085326344Simpof the C function that called it, 6086280405Srpaulousing a standard message 6087280405Srpaulothat includes <code>extramsg</code> as a comment: 6088280405Srpaulo 6089280405Srpaulo<pre> 6090280405Srpaulo bad argument #<em>arg</em> to '<em>funcname</em>' (<em>extramsg</em>) 6091280405Srpaulo</pre><p> 6092280405SrpauloThis function never returns. 6093280405Srpaulo 6094280405Srpaulo 6095280405Srpaulo 6096280405Srpaulo 6097280405Srpaulo 6098280405Srpaulo<hr><h3><a name="luaL_Buffer"><code>luaL_Buffer</code></a></h3> 6099280405Srpaulo<pre>typedef struct luaL_Buffer luaL_Buffer;</pre> 6100280405Srpaulo 6101280405Srpaulo<p> 6102280405SrpauloType for a <em>string buffer</em>. 6103280405Srpaulo 6104280405Srpaulo 6105280405Srpaulo<p> 6106280405SrpauloA string buffer allows C code to build Lua strings piecemeal. 6107280405SrpauloIts pattern of use is as follows: 6108280405Srpaulo 6109280405Srpaulo<ul> 6110280405Srpaulo 6111280405Srpaulo<li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li> 6112280405Srpaulo 6113280405Srpaulo<li>Then initialize it with a call <code>luaL_buffinit(L, &b)</code>.</li> 6114280405Srpaulo 6115280405Srpaulo<li> 6116280405SrpauloThen add string pieces to the buffer calling any of 6117280405Srpaulothe <code>luaL_add*</code> functions. 6118280405Srpaulo</li> 6119280405Srpaulo 6120280405Srpaulo<li> 6121280405SrpauloFinish by calling <code>luaL_pushresult(&b)</code>. 6122280405SrpauloThis call leaves the final string on the top of the stack. 6123280405Srpaulo</li> 6124280405Srpaulo 6125280405Srpaulo</ul> 6126280405Srpaulo 6127280405Srpaulo<p> 6128280405SrpauloIf you know beforehand the total size of the resulting string, 6129280405Srpauloyou can use the buffer like this: 6130280405Srpaulo 6131280405Srpaulo<ul> 6132280405Srpaulo 6133280405Srpaulo<li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li> 6134280405Srpaulo 6135280405Srpaulo<li>Then initialize it and preallocate a space of 6136280405Srpaulosize <code>sz</code> with a call <code>luaL_buffinitsize(L, &b, sz)</code>.</li> 6137280405Srpaulo 6138280405Srpaulo<li>Then copy the string into that space.</li> 6139280405Srpaulo 6140280405Srpaulo<li> 6141280405SrpauloFinish by calling <code>luaL_pushresultsize(&b, sz)</code>, 6142280405Srpaulowhere <code>sz</code> is the total size of the resulting string 6143280405Srpaulocopied into that space. 6144280405Srpaulo</li> 6145280405Srpaulo 6146280405Srpaulo</ul> 6147280405Srpaulo 6148280405Srpaulo<p> 6149280405SrpauloDuring its normal operation, 6150280405Srpauloa string buffer uses a variable number of stack slots. 6151280405SrpauloSo, while using a buffer, you cannot assume that you know where 6152280405Srpaulothe top of the stack is. 6153280405SrpauloYou can use the stack between successive calls to buffer operations 6154280405Srpauloas long as that use is balanced; 6155280405Srpaulothat is, 6156280405Srpaulowhen you call a buffer operation, 6157280405Srpaulothe stack is at the same level 6158280405Srpauloit was immediately after the previous buffer operation. 6159280405Srpaulo(The only exception to this rule is <a href="#luaL_addvalue"><code>luaL_addvalue</code></a>.) 6160280405SrpauloAfter calling <a href="#luaL_pushresult"><code>luaL_pushresult</code></a> the stack is back to its 6161280405Srpaulolevel when the buffer was initialized, 6162280405Srpauloplus the final string on its top. 6163280405Srpaulo 6164280405Srpaulo 6165280405Srpaulo 6166280405Srpaulo 6167280405Srpaulo 6168280405Srpaulo<hr><h3><a name="luaL_buffinit"><code>luaL_buffinit</code></a></h3><p> 6169280405Srpaulo<span class="apii">[-0, +0, –]</span> 6170280405Srpaulo<pre>void luaL_buffinit (lua_State *L, luaL_Buffer *B);</pre> 6171280405Srpaulo 6172280405Srpaulo<p> 6173280405SrpauloInitializes a buffer <code>B</code>. 6174280405SrpauloThis function does not allocate any space; 6175280405Srpaulothe buffer must be declared as a variable 6176280405Srpaulo(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6177280405Srpaulo 6178280405Srpaulo 6179280405Srpaulo 6180280405Srpaulo 6181280405Srpaulo 6182280405Srpaulo<hr><h3><a name="luaL_buffinitsize"><code>luaL_buffinitsize</code></a></h3><p> 6183326344Simp<span class="apii">[-?, +?, <em>m</em>]</span> 6184280405Srpaulo<pre>char *luaL_buffinitsize (lua_State *L, luaL_Buffer *B, size_t sz);</pre> 6185280405Srpaulo 6186280405Srpaulo<p> 6187280405SrpauloEquivalent to the sequence 6188280405Srpaulo<a href="#luaL_buffinit"><code>luaL_buffinit</code></a>, <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a>. 6189280405Srpaulo 6190280405Srpaulo 6191280405Srpaulo 6192280405Srpaulo 6193280405Srpaulo 6194280405Srpaulo<hr><h3><a name="luaL_callmeta"><code>luaL_callmeta</code></a></h3><p> 6195280405Srpaulo<span class="apii">[-0, +(0|1), <em>e</em>]</span> 6196280405Srpaulo<pre>int luaL_callmeta (lua_State *L, int obj, const char *e);</pre> 6197280405Srpaulo 6198280405Srpaulo<p> 6199280405SrpauloCalls a metamethod. 6200280405Srpaulo 6201280405Srpaulo 6202280405Srpaulo<p> 6203280405SrpauloIf the object at index <code>obj</code> has a metatable and this 6204280405Srpaulometatable has a field <code>e</code>, 6205280405Srpaulothis function calls this field passing the object as its only argument. 6206280405SrpauloIn this case this function returns true and pushes onto the 6207280405Srpaulostack the value returned by the call. 6208280405SrpauloIf there is no metatable or no metamethod, 6209280405Srpaulothis function returns false (without pushing any value on the stack). 6210280405Srpaulo 6211280405Srpaulo 6212280405Srpaulo 6213280405Srpaulo 6214280405Srpaulo 6215280405Srpaulo<hr><h3><a name="luaL_checkany"><code>luaL_checkany</code></a></h3><p> 6216280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span> 6217280405Srpaulo<pre>void luaL_checkany (lua_State *L, int arg);</pre> 6218280405Srpaulo 6219280405Srpaulo<p> 6220280405SrpauloChecks whether the function has an argument 6221280405Srpauloof any type (including <b>nil</b>) at position <code>arg</code>. 6222280405Srpaulo 6223280405Srpaulo 6224280405Srpaulo 6225280405Srpaulo 6226280405Srpaulo 6227280405Srpaulo<hr><h3><a name="luaL_checkinteger"><code>luaL_checkinteger</code></a></h3><p> 6228280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span> 6229280405Srpaulo<pre>lua_Integer luaL_checkinteger (lua_State *L, int arg);</pre> 6230280405Srpaulo 6231280405Srpaulo<p> 6232280405SrpauloChecks whether the function argument <code>arg</code> is an integer 6233280405Srpaulo(or can be converted to an integer) 6234280405Srpauloand returns this integer cast to a <a href="#lua_Integer"><code>lua_Integer</code></a>. 6235280405Srpaulo 6236280405Srpaulo 6237280405Srpaulo 6238280405Srpaulo 6239280405Srpaulo 6240280405Srpaulo<hr><h3><a name="luaL_checklstring"><code>luaL_checklstring</code></a></h3><p> 6241280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span> 6242280405Srpaulo<pre>const char *luaL_checklstring (lua_State *L, int arg, size_t *l);</pre> 6243280405Srpaulo 6244280405Srpaulo<p> 6245280405SrpauloChecks whether the function argument <code>arg</code> is a string 6246280405Srpauloand returns this string; 6247280405Srpauloif <code>l</code> is not <code>NULL</code> fills <code>*l</code> 6248280405Srpaulowith the string's length. 6249280405Srpaulo 6250280405Srpaulo 6251280405Srpaulo<p> 6252280405SrpauloThis function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, 6253280405Srpauloso all conversions and caveats of that function apply here. 6254280405Srpaulo 6255280405Srpaulo 6256280405Srpaulo 6257280405Srpaulo 6258280405Srpaulo 6259280405Srpaulo<hr><h3><a name="luaL_checknumber"><code>luaL_checknumber</code></a></h3><p> 6260280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span> 6261280405Srpaulo<pre>lua_Number luaL_checknumber (lua_State *L, int arg);</pre> 6262280405Srpaulo 6263280405Srpaulo<p> 6264280405SrpauloChecks whether the function argument <code>arg</code> is a number 6265280405Srpauloand returns this number. 6266280405Srpaulo 6267280405Srpaulo 6268280405Srpaulo 6269280405Srpaulo 6270280405Srpaulo 6271280405Srpaulo<hr><h3><a name="luaL_checkoption"><code>luaL_checkoption</code></a></h3><p> 6272280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span> 6273280405Srpaulo<pre>int luaL_checkoption (lua_State *L, 6274280405Srpaulo int arg, 6275280405Srpaulo const char *def, 6276280405Srpaulo const char *const lst[]);</pre> 6277280405Srpaulo 6278280405Srpaulo<p> 6279280405SrpauloChecks whether the function argument <code>arg</code> is a string and 6280280405Srpaulosearches for this string in the array <code>lst</code> 6281280405Srpaulo(which must be NULL-terminated). 6282280405SrpauloReturns the index in the array where the string was found. 6283280405SrpauloRaises an error if the argument is not a string or 6284280405Srpauloif the string cannot be found. 6285280405Srpaulo 6286280405Srpaulo 6287280405Srpaulo<p> 6288280405SrpauloIf <code>def</code> is not <code>NULL</code>, 6289280405Srpaulothe function uses <code>def</code> as a default value when 6290280405Srpaulothere is no argument <code>arg</code> or when this argument is <b>nil</b>. 6291280405Srpaulo 6292280405Srpaulo 6293280405Srpaulo<p> 6294280405SrpauloThis is a useful function for mapping strings to C enums. 6295280405Srpaulo(The usual convention in Lua libraries is 6296280405Srpauloto use strings instead of numbers to select options.) 6297280405Srpaulo 6298280405Srpaulo 6299280405Srpaulo 6300280405Srpaulo 6301280405Srpaulo 6302280405Srpaulo<hr><h3><a name="luaL_checkstack"><code>luaL_checkstack</code></a></h3><p> 6303280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span> 6304280405Srpaulo<pre>void luaL_checkstack (lua_State *L, int sz, const char *msg);</pre> 6305280405Srpaulo 6306280405Srpaulo<p> 6307280405SrpauloGrows the stack size to <code>top + sz</code> elements, 6308280405Srpauloraising an error if the stack cannot grow to that size. 6309280405Srpaulo<code>msg</code> is an additional text to go into the error message 6310280405Srpaulo(or <code>NULL</code> for no additional text). 6311280405Srpaulo 6312280405Srpaulo 6313280405Srpaulo 6314280405Srpaulo 6315280405Srpaulo 6316280405Srpaulo<hr><h3><a name="luaL_checkstring"><code>luaL_checkstring</code></a></h3><p> 6317280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span> 6318280405Srpaulo<pre>const char *luaL_checkstring (lua_State *L, int arg);</pre> 6319280405Srpaulo 6320280405Srpaulo<p> 6321280405SrpauloChecks whether the function argument <code>arg</code> is a string 6322280405Srpauloand returns this string. 6323280405Srpaulo 6324280405Srpaulo 6325280405Srpaulo<p> 6326280405SrpauloThis function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, 6327280405Srpauloso all conversions and caveats of that function apply here. 6328280405Srpaulo 6329280405Srpaulo 6330280405Srpaulo 6331280405Srpaulo 6332280405Srpaulo 6333280405Srpaulo<hr><h3><a name="luaL_checktype"><code>luaL_checktype</code></a></h3><p> 6334280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span> 6335280405Srpaulo<pre>void luaL_checktype (lua_State *L, int arg, int t);</pre> 6336280405Srpaulo 6337280405Srpaulo<p> 6338280405SrpauloChecks whether the function argument <code>arg</code> has type <code>t</code>. 6339280405SrpauloSee <a href="#lua_type"><code>lua_type</code></a> for the encoding of types for <code>t</code>. 6340280405Srpaulo 6341280405Srpaulo 6342280405Srpaulo 6343280405Srpaulo 6344280405Srpaulo 6345280405Srpaulo<hr><h3><a name="luaL_checkudata"><code>luaL_checkudata</code></a></h3><p> 6346280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span> 6347280405Srpaulo<pre>void *luaL_checkudata (lua_State *L, int arg, const char *tname);</pre> 6348280405Srpaulo 6349280405Srpaulo<p> 6350280405SrpauloChecks whether the function argument <code>arg</code> is a userdata 6351280405Srpauloof the type <code>tname</code> (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>) and 6352280405Srpauloreturns the userdata address (see <a href="#lua_touserdata"><code>lua_touserdata</code></a>). 6353280405Srpaulo 6354280405Srpaulo 6355280405Srpaulo 6356280405Srpaulo 6357280405Srpaulo 6358280405Srpaulo<hr><h3><a name="luaL_checkversion"><code>luaL_checkversion</code></a></h3><p> 6359326344Simp<span class="apii">[-0, +0, <em>v</em>]</span> 6360280405Srpaulo<pre>void luaL_checkversion (lua_State *L);</pre> 6361280405Srpaulo 6362280405Srpaulo<p> 6363280405SrpauloChecks whether the core running the call, 6364280405Srpaulothe core that created the Lua state, 6365280405Srpauloand the code making the call are all using the same version of Lua. 6366280405SrpauloAlso checks whether the core running the call 6367280405Srpauloand the core that created the Lua state 6368280405Srpauloare using the same address space. 6369280405Srpaulo 6370280405Srpaulo 6371280405Srpaulo 6372280405Srpaulo 6373280405Srpaulo 6374280405Srpaulo<hr><h3><a name="luaL_dofile"><code>luaL_dofile</code></a></h3><p> 6375280405Srpaulo<span class="apii">[-0, +?, <em>e</em>]</span> 6376280405Srpaulo<pre>int luaL_dofile (lua_State *L, const char *filename);</pre> 6377280405Srpaulo 6378280405Srpaulo<p> 6379280405SrpauloLoads and runs the given file. 6380280405SrpauloIt is defined as the following macro: 6381280405Srpaulo 6382280405Srpaulo<pre> 6383280405Srpaulo (luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0)) 6384280405Srpaulo</pre><p> 6385280405SrpauloIt returns false if there are no errors 6386280405Srpauloor true in case of errors. 6387280405Srpaulo 6388280405Srpaulo 6389280405Srpaulo 6390280405Srpaulo 6391280405Srpaulo 6392280405Srpaulo<hr><h3><a name="luaL_dostring"><code>luaL_dostring</code></a></h3><p> 6393280405Srpaulo<span class="apii">[-0, +?, –]</span> 6394280405Srpaulo<pre>int luaL_dostring (lua_State *L, const char *str);</pre> 6395280405Srpaulo 6396280405Srpaulo<p> 6397280405SrpauloLoads and runs the given string. 6398280405SrpauloIt is defined as the following macro: 6399280405Srpaulo 6400280405Srpaulo<pre> 6401280405Srpaulo (luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0)) 6402280405Srpaulo</pre><p> 6403280405SrpauloIt returns false if there are no errors 6404280405Srpauloor true in case of errors. 6405280405Srpaulo 6406280405Srpaulo 6407280405Srpaulo 6408280405Srpaulo 6409280405Srpaulo 6410280405Srpaulo<hr><h3><a name="luaL_error"><code>luaL_error</code></a></h3><p> 6411280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span> 6412280405Srpaulo<pre>int luaL_error (lua_State *L, const char *fmt, ...);</pre> 6413280405Srpaulo 6414280405Srpaulo<p> 6415280405SrpauloRaises an error. 6416280405SrpauloThe error message format is given by <code>fmt</code> 6417280405Srpauloplus any extra arguments, 6418280405Srpaulofollowing the same rules of <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>. 6419280405SrpauloIt also adds at the beginning of the message the file name and 6420280405Srpaulothe line number where the error occurred, 6421280405Srpauloif this information is available. 6422280405Srpaulo 6423280405Srpaulo 6424280405Srpaulo<p> 6425280405SrpauloThis function never returns, 6426280405Srpaulobut it is an idiom to use it in C functions 6427280405Srpauloas <code>return luaL_error(<em>args</em>)</code>. 6428280405Srpaulo 6429280405Srpaulo 6430280405Srpaulo 6431280405Srpaulo 6432280405Srpaulo 6433280405Srpaulo<hr><h3><a name="luaL_execresult"><code>luaL_execresult</code></a></h3><p> 6434326344Simp<span class="apii">[-0, +3, <em>m</em>]</span> 6435280405Srpaulo<pre>int luaL_execresult (lua_State *L, int stat);</pre> 6436280405Srpaulo 6437280405Srpaulo<p> 6438280405SrpauloThis function produces the return values for 6439280405Srpauloprocess-related functions in the standard library 6440280405Srpaulo(<a href="#pdf-os.execute"><code>os.execute</code></a> and <a href="#pdf-io.close"><code>io.close</code></a>). 6441280405Srpaulo 6442280405Srpaulo 6443280405Srpaulo 6444280405Srpaulo 6445280405Srpaulo 6446280405Srpaulo<hr><h3><a name="luaL_fileresult"><code>luaL_fileresult</code></a></h3><p> 6447326344Simp<span class="apii">[-0, +(1|3), <em>m</em>]</span> 6448280405Srpaulo<pre>int luaL_fileresult (lua_State *L, int stat, const char *fname);</pre> 6449280405Srpaulo 6450280405Srpaulo<p> 6451280405SrpauloThis function produces the return values for 6452280405Srpaulofile-related functions in the standard library 6453280405Srpaulo(<a href="#pdf-io.open"><code>io.open</code></a>, <a href="#pdf-os.rename"><code>os.rename</code></a>, <a href="#pdf-file:seek"><code>file:seek</code></a>, etc.). 6454280405Srpaulo 6455280405Srpaulo 6456280405Srpaulo 6457280405Srpaulo 6458280405Srpaulo 6459280405Srpaulo<hr><h3><a name="luaL_getmetafield"><code>luaL_getmetafield</code></a></h3><p> 6460326344Simp<span class="apii">[-0, +(0|1), <em>m</em>]</span> 6461280405Srpaulo<pre>int luaL_getmetafield (lua_State *L, int obj, const char *e);</pre> 6462280405Srpaulo 6463280405Srpaulo<p> 6464280405SrpauloPushes onto the stack the field <code>e</code> from the metatable 6465280405Srpauloof the object at index <code>obj</code> and returns the type of pushed value. 6466280405SrpauloIf the object does not have a metatable, 6467280405Srpauloor if the metatable does not have this field, 6468280405Srpaulopushes nothing and returns <code>LUA_TNIL</code>. 6469280405Srpaulo 6470280405Srpaulo 6471280405Srpaulo 6472280405Srpaulo 6473280405Srpaulo 6474280405Srpaulo<hr><h3><a name="luaL_getmetatable"><code>luaL_getmetatable</code></a></h3><p> 6475326344Simp<span class="apii">[-0, +1, <em>m</em>]</span> 6476280405Srpaulo<pre>int luaL_getmetatable (lua_State *L, const char *tname);</pre> 6477280405Srpaulo 6478280405Srpaulo<p> 6479280405SrpauloPushes onto the stack the metatable associated with name <code>tname</code> 6480326344Simpin the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>) 6481326344Simp(<b>nil</b> if there is no metatable associated with that name). 6482326344SimpReturns the type of the pushed value. 6483280405Srpaulo 6484280405Srpaulo 6485280405Srpaulo 6486280405Srpaulo 6487280405Srpaulo 6488280405Srpaulo<hr><h3><a name="luaL_getsubtable"><code>luaL_getsubtable</code></a></h3><p> 6489280405Srpaulo<span class="apii">[-0, +1, <em>e</em>]</span> 6490280405Srpaulo<pre>int luaL_getsubtable (lua_State *L, int idx, const char *fname);</pre> 6491280405Srpaulo 6492280405Srpaulo<p> 6493280405SrpauloEnsures that the value <code>t[fname]</code>, 6494280405Srpaulowhere <code>t</code> is the value at index <code>idx</code>, 6495280405Srpaulois a table, 6496280405Srpauloand pushes that table onto the stack. 6497280405SrpauloReturns true if it finds a previous table there 6498280405Srpauloand false if it creates a new table. 6499280405Srpaulo 6500280405Srpaulo 6501280405Srpaulo 6502280405Srpaulo 6503280405Srpaulo 6504280405Srpaulo<hr><h3><a name="luaL_gsub"><code>luaL_gsub</code></a></h3><p> 6505326344Simp<span class="apii">[-0, +1, <em>m</em>]</span> 6506280405Srpaulo<pre>const char *luaL_gsub (lua_State *L, 6507280405Srpaulo const char *s, 6508280405Srpaulo const char *p, 6509280405Srpaulo const char *r);</pre> 6510280405Srpaulo 6511280405Srpaulo<p> 6512280405SrpauloCreates a copy of string <code>s</code> by replacing 6513280405Srpauloany occurrence of the string <code>p</code> 6514280405Srpaulowith the string <code>r</code>. 6515280405SrpauloPushes the resulting string on the stack and returns it. 6516280405Srpaulo 6517280405Srpaulo 6518280405Srpaulo 6519280405Srpaulo 6520280405Srpaulo 6521280405Srpaulo<hr><h3><a name="luaL_len"><code>luaL_len</code></a></h3><p> 6522280405Srpaulo<span class="apii">[-0, +0, <em>e</em>]</span> 6523280405Srpaulo<pre>lua_Integer luaL_len (lua_State *L, int index);</pre> 6524280405Srpaulo 6525280405Srpaulo<p> 6526280405SrpauloReturns the "length" of the value at the given index 6527280405Srpauloas a number; 6528280405Srpauloit is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">§3.4.7</a>). 6529280405SrpauloRaises an error if the result of the operation is not an integer. 6530280405Srpaulo(This case only can happen through metamethods.) 6531280405Srpaulo 6532280405Srpaulo 6533280405Srpaulo 6534280405Srpaulo 6535280405Srpaulo 6536280405Srpaulo<hr><h3><a name="luaL_loadbuffer"><code>luaL_loadbuffer</code></a></h3><p> 6537280405Srpaulo<span class="apii">[-0, +1, –]</span> 6538280405Srpaulo<pre>int luaL_loadbuffer (lua_State *L, 6539280405Srpaulo const char *buff, 6540280405Srpaulo size_t sz, 6541280405Srpaulo const char *name);</pre> 6542280405Srpaulo 6543280405Srpaulo<p> 6544280405SrpauloEquivalent to <a href="#luaL_loadbufferx"><code>luaL_loadbufferx</code></a> with <code>mode</code> equal to <code>NULL</code>. 6545280405Srpaulo 6546280405Srpaulo 6547280405Srpaulo 6548280405Srpaulo 6549280405Srpaulo 6550280405Srpaulo<hr><h3><a name="luaL_loadbufferx"><code>luaL_loadbufferx</code></a></h3><p> 6551280405Srpaulo<span class="apii">[-0, +1, –]</span> 6552280405Srpaulo<pre>int luaL_loadbufferx (lua_State *L, 6553280405Srpaulo const char *buff, 6554280405Srpaulo size_t sz, 6555280405Srpaulo const char *name, 6556280405Srpaulo const char *mode);</pre> 6557280405Srpaulo 6558280405Srpaulo<p> 6559280405SrpauloLoads a buffer as a Lua chunk. 6560280405SrpauloThis function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the 6561280405Srpaulobuffer pointed to by <code>buff</code> with size <code>sz</code>. 6562280405Srpaulo 6563280405Srpaulo 6564280405Srpaulo<p> 6565280405SrpauloThis function returns the same results as <a href="#lua_load"><code>lua_load</code></a>. 6566280405Srpaulo<code>name</code> is the chunk name, 6567280405Srpauloused for debug information and error messages. 6568280405SrpauloThe string <code>mode</code> works as in function <a href="#lua_load"><code>lua_load</code></a>. 6569280405Srpaulo 6570280405Srpaulo 6571280405Srpaulo 6572280405Srpaulo 6573280405Srpaulo 6574280405Srpaulo<hr><h3><a name="luaL_loadfile"><code>luaL_loadfile</code></a></h3><p> 6575326344Simp<span class="apii">[-0, +1, <em>m</em>]</span> 6576280405Srpaulo<pre>int luaL_loadfile (lua_State *L, const char *filename);</pre> 6577280405Srpaulo 6578280405Srpaulo<p> 6579280405SrpauloEquivalent to <a href="#luaL_loadfilex"><code>luaL_loadfilex</code></a> with <code>mode</code> equal to <code>NULL</code>. 6580280405Srpaulo 6581280405Srpaulo 6582280405Srpaulo 6583280405Srpaulo 6584280405Srpaulo 6585280405Srpaulo<hr><h3><a name="luaL_loadfilex"><code>luaL_loadfilex</code></a></h3><p> 6586326344Simp<span class="apii">[-0, +1, <em>m</em>]</span> 6587280405Srpaulo<pre>int luaL_loadfilex (lua_State *L, const char *filename, 6588280405Srpaulo const char *mode);</pre> 6589280405Srpaulo 6590280405Srpaulo<p> 6591280405SrpauloLoads a file as a Lua chunk. 6592280405SrpauloThis function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the file 6593280405Srpaulonamed <code>filename</code>. 6594280405SrpauloIf <code>filename</code> is <code>NULL</code>, 6595280405Srpaulothen it loads from the standard input. 6596280405SrpauloThe first line in the file is ignored if it starts with a <code>#</code>. 6597280405Srpaulo 6598280405Srpaulo 6599280405Srpaulo<p> 6600280405SrpauloThe string <code>mode</code> works as in function <a href="#lua_load"><code>lua_load</code></a>. 6601280405Srpaulo 6602280405Srpaulo 6603280405Srpaulo<p> 6604280405SrpauloThis function returns the same results as <a href="#lua_load"><code>lua_load</code></a>, 6605280405Srpaulobut it has an extra error code <a name="pdf-LUA_ERRFILE"><code>LUA_ERRFILE</code></a> 6606326344Simpfor file-related errors 6607326344Simp(e.g., it cannot open or read the file). 6608280405Srpaulo 6609280405Srpaulo 6610280405Srpaulo<p> 6611280405SrpauloAs <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk; 6612280405Srpauloit does not run it. 6613280405Srpaulo 6614280405Srpaulo 6615280405Srpaulo 6616280405Srpaulo 6617280405Srpaulo 6618280405Srpaulo<hr><h3><a name="luaL_loadstring"><code>luaL_loadstring</code></a></h3><p> 6619280405Srpaulo<span class="apii">[-0, +1, –]</span> 6620280405Srpaulo<pre>int luaL_loadstring (lua_State *L, const char *s);</pre> 6621280405Srpaulo 6622280405Srpaulo<p> 6623280405SrpauloLoads a string as a Lua chunk. 6624280405SrpauloThis function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in 6625280405Srpaulothe zero-terminated string <code>s</code>. 6626280405Srpaulo 6627280405Srpaulo 6628280405Srpaulo<p> 6629280405SrpauloThis function returns the same results as <a href="#lua_load"><code>lua_load</code></a>. 6630280405Srpaulo 6631280405Srpaulo 6632280405Srpaulo<p> 6633280405SrpauloAlso as <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk; 6634280405Srpauloit does not run it. 6635280405Srpaulo 6636280405Srpaulo 6637280405Srpaulo 6638280405Srpaulo 6639280405Srpaulo 6640280405Srpaulo<hr><h3><a name="luaL_newlib"><code>luaL_newlib</code></a></h3><p> 6641326344Simp<span class="apii">[-0, +1, <em>m</em>]</span> 6642280405Srpaulo<pre>void luaL_newlib (lua_State *L, const luaL_Reg l[]);</pre> 6643280405Srpaulo 6644280405Srpaulo<p> 6645280405SrpauloCreates a new table and registers there 6646280405Srpaulothe functions in list <code>l</code>. 6647280405Srpaulo 6648280405Srpaulo 6649280405Srpaulo<p> 6650280405SrpauloIt is implemented as the following macro: 6651280405Srpaulo 6652280405Srpaulo<pre> 6653280405Srpaulo (luaL_newlibtable(L,l), luaL_setfuncs(L,l,0)) 6654280405Srpaulo</pre><p> 6655280405SrpauloThe array <code>l</code> must be the actual array, 6656280405Srpaulonot a pointer to it. 6657280405Srpaulo 6658280405Srpaulo 6659280405Srpaulo 6660280405Srpaulo 6661280405Srpaulo 6662280405Srpaulo<hr><h3><a name="luaL_newlibtable"><code>luaL_newlibtable</code></a></h3><p> 6663326344Simp<span class="apii">[-0, +1, <em>m</em>]</span> 6664280405Srpaulo<pre>void luaL_newlibtable (lua_State *L, const luaL_Reg l[]);</pre> 6665280405Srpaulo 6666280405Srpaulo<p> 6667280405SrpauloCreates a new table with a size optimized 6668280405Srpauloto store all entries in the array <code>l</code> 6669280405Srpaulo(but does not actually store them). 6670280405SrpauloIt is intended to be used in conjunction with <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a> 6671280405Srpaulo(see <a href="#luaL_newlib"><code>luaL_newlib</code></a>). 6672280405Srpaulo 6673280405Srpaulo 6674280405Srpaulo<p> 6675280405SrpauloIt is implemented as a macro. 6676280405SrpauloThe array <code>l</code> must be the actual array, 6677280405Srpaulonot a pointer to it. 6678280405Srpaulo 6679280405Srpaulo 6680280405Srpaulo 6681280405Srpaulo 6682280405Srpaulo 6683280405Srpaulo<hr><h3><a name="luaL_newmetatable"><code>luaL_newmetatable</code></a></h3><p> 6684326344Simp<span class="apii">[-0, +1, <em>m</em>]</span> 6685280405Srpaulo<pre>int luaL_newmetatable (lua_State *L, const char *tname);</pre> 6686280405Srpaulo 6687280405Srpaulo<p> 6688280405SrpauloIf the registry already has the key <code>tname</code>, 6689280405Srpauloreturns 0. 6690280405SrpauloOtherwise, 6691280405Srpaulocreates a new table to be used as a metatable for userdata, 6692280405Srpauloadds to this new table the pair <code>__name = tname</code>, 6693280405Srpauloadds to the registry the pair <code>[tname] = new table</code>, 6694280405Srpauloand returns 1. 6695280405Srpaulo(The entry <code>__name</code> is used by some error-reporting functions.) 6696280405Srpaulo 6697280405Srpaulo 6698280405Srpaulo<p> 6699280405SrpauloIn both cases pushes onto the stack the final value associated 6700280405Srpaulowith <code>tname</code> in the registry. 6701280405Srpaulo 6702280405Srpaulo 6703280405Srpaulo 6704280405Srpaulo 6705280405Srpaulo 6706280405Srpaulo<hr><h3><a name="luaL_newstate"><code>luaL_newstate</code></a></h3><p> 6707280405Srpaulo<span class="apii">[-0, +0, –]</span> 6708280405Srpaulo<pre>lua_State *luaL_newstate (void);</pre> 6709280405Srpaulo 6710280405Srpaulo<p> 6711280405SrpauloCreates a new Lua state. 6712280405SrpauloIt calls <a href="#lua_newstate"><code>lua_newstate</code></a> with an 6713280405Srpauloallocator based on the standard C <code>realloc</code> function 6714280405Srpauloand then sets a panic function (see <a href="#4.6">§4.6</a>) that prints 6715280405Srpauloan error message to the standard error output in case of fatal 6716280405Srpauloerrors. 6717280405Srpaulo 6718280405Srpaulo 6719280405Srpaulo<p> 6720280405SrpauloReturns the new state, 6721280405Srpauloor <code>NULL</code> if there is a memory allocation error. 6722280405Srpaulo 6723280405Srpaulo 6724280405Srpaulo 6725280405Srpaulo 6726280405Srpaulo 6727280405Srpaulo<hr><h3><a name="luaL_openlibs"><code>luaL_openlibs</code></a></h3><p> 6728280405Srpaulo<span class="apii">[-0, +0, <em>e</em>]</span> 6729280405Srpaulo<pre>void luaL_openlibs (lua_State *L);</pre> 6730280405Srpaulo 6731280405Srpaulo<p> 6732280405SrpauloOpens all standard Lua libraries into the given state. 6733280405Srpaulo 6734280405Srpaulo 6735280405Srpaulo 6736280405Srpaulo 6737280405Srpaulo 6738326344Simp<hr><h3><a name="luaL_opt"><code>luaL_opt</code></a></h3><p> 6739326344Simp<span class="apii">[-0, +0, <em>e</em>]</span> 6740326344Simp<pre>T luaL_opt (L, func, arg, dflt);</pre> 6741326344Simp 6742326344Simp<p> 6743326344SimpThis macro is defined as follows: 6744326344Simp 6745326344Simp<pre> 6746326344Simp (lua_isnoneornil(L,(arg)) ? (dflt) : func(L,(arg))) 6747326344Simp</pre><p> 6748326344SimpIn words, if the argument <code>arg</code> is nil or absent, 6749326344Simpthe macro results in the default <code>dflt</code>. 6750326344SimpOtherwise, it results in the result of calling <code>func</code> 6751326344Simpwith the state <code>L</code> and the argument index <code>arg</code> as 6752326344Simpparameters. 6753326344SimpNote that it evaluates the expression <code>dflt</code> only if needed. 6754326344Simp 6755326344Simp 6756326344Simp 6757326344Simp 6758326344Simp 6759280405Srpaulo<hr><h3><a name="luaL_optinteger"><code>luaL_optinteger</code></a></h3><p> 6760280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span> 6761280405Srpaulo<pre>lua_Integer luaL_optinteger (lua_State *L, 6762280405Srpaulo int arg, 6763280405Srpaulo lua_Integer d);</pre> 6764280405Srpaulo 6765280405Srpaulo<p> 6766280405SrpauloIf the function argument <code>arg</code> is an integer 6767280405Srpaulo(or convertible to an integer), 6768280405Srpauloreturns this integer. 6769280405SrpauloIf this argument is absent or is <b>nil</b>, 6770280405Srpauloreturns <code>d</code>. 6771280405SrpauloOtherwise, raises an error. 6772280405Srpaulo 6773280405Srpaulo 6774280405Srpaulo 6775280405Srpaulo 6776280405Srpaulo 6777280405Srpaulo<hr><h3><a name="luaL_optlstring"><code>luaL_optlstring</code></a></h3><p> 6778280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span> 6779280405Srpaulo<pre>const char *luaL_optlstring (lua_State *L, 6780280405Srpaulo int arg, 6781280405Srpaulo const char *d, 6782280405Srpaulo size_t *l);</pre> 6783280405Srpaulo 6784280405Srpaulo<p> 6785280405SrpauloIf the function argument <code>arg</code> is a string, 6786280405Srpauloreturns this string. 6787280405SrpauloIf this argument is absent or is <b>nil</b>, 6788280405Srpauloreturns <code>d</code>. 6789280405SrpauloOtherwise, raises an error. 6790280405Srpaulo 6791280405Srpaulo 6792280405Srpaulo<p> 6793280405SrpauloIf <code>l</code> is not <code>NULL</code>, 6794280405Srpaulofills the position <code>*l</code> with the result's length. 6795326344SimpIf the result is <code>NULL</code> 6796326344Simp(only possible when returning <code>d</code> and <code>d == NULL</code>), 6797326344Simpits length is considered zero. 6798280405Srpaulo 6799280405Srpaulo 6800326344Simp<p> 6801326344SimpThis function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, 6802326344Simpso all conversions and caveats of that function apply here. 6803280405Srpaulo 6804280405Srpaulo 6805280405Srpaulo 6806326344Simp 6807326344Simp 6808280405Srpaulo<hr><h3><a name="luaL_optnumber"><code>luaL_optnumber</code></a></h3><p> 6809280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span> 6810280405Srpaulo<pre>lua_Number luaL_optnumber (lua_State *L, int arg, lua_Number d);</pre> 6811280405Srpaulo 6812280405Srpaulo<p> 6813280405SrpauloIf the function argument <code>arg</code> is a number, 6814280405Srpauloreturns this number. 6815280405SrpauloIf this argument is absent or is <b>nil</b>, 6816280405Srpauloreturns <code>d</code>. 6817280405SrpauloOtherwise, raises an error. 6818280405Srpaulo 6819280405Srpaulo 6820280405Srpaulo 6821280405Srpaulo 6822280405Srpaulo 6823280405Srpaulo<hr><h3><a name="luaL_optstring"><code>luaL_optstring</code></a></h3><p> 6824280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span> 6825280405Srpaulo<pre>const char *luaL_optstring (lua_State *L, 6826280405Srpaulo int arg, 6827280405Srpaulo const char *d);</pre> 6828280405Srpaulo 6829280405Srpaulo<p> 6830280405SrpauloIf the function argument <code>arg</code> is a string, 6831280405Srpauloreturns this string. 6832280405SrpauloIf this argument is absent or is <b>nil</b>, 6833280405Srpauloreturns <code>d</code>. 6834280405SrpauloOtherwise, raises an error. 6835280405Srpaulo 6836280405Srpaulo 6837280405Srpaulo 6838280405Srpaulo 6839280405Srpaulo 6840280405Srpaulo<hr><h3><a name="luaL_prepbuffer"><code>luaL_prepbuffer</code></a></h3><p> 6841326344Simp<span class="apii">[-?, +?, <em>m</em>]</span> 6842280405Srpaulo<pre>char *luaL_prepbuffer (luaL_Buffer *B);</pre> 6843280405Srpaulo 6844280405Srpaulo<p> 6845280405SrpauloEquivalent to <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a> 6846280405Srpaulowith the predefined size <a name="pdf-LUAL_BUFFERSIZE"><code>LUAL_BUFFERSIZE</code></a>. 6847280405Srpaulo 6848280405Srpaulo 6849280405Srpaulo 6850280405Srpaulo 6851280405Srpaulo 6852280405Srpaulo<hr><h3><a name="luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a></h3><p> 6853326344Simp<span class="apii">[-?, +?, <em>m</em>]</span> 6854280405Srpaulo<pre>char *luaL_prepbuffsize (luaL_Buffer *B, size_t sz);</pre> 6855280405Srpaulo 6856280405Srpaulo<p> 6857280405SrpauloReturns an address to a space of size <code>sz</code> 6858280405Srpaulowhere you can copy a string to be added to buffer <code>B</code> 6859280405Srpaulo(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6860280405SrpauloAfter copying the string into this space you must call 6861280405Srpaulo<a href="#luaL_addsize"><code>luaL_addsize</code></a> with the size of the string to actually add 6862280405Srpauloit to the buffer. 6863280405Srpaulo 6864280405Srpaulo 6865280405Srpaulo 6866280405Srpaulo 6867280405Srpaulo 6868280405Srpaulo<hr><h3><a name="luaL_pushresult"><code>luaL_pushresult</code></a></h3><p> 6869326344Simp<span class="apii">[-?, +1, <em>m</em>]</span> 6870280405Srpaulo<pre>void luaL_pushresult (luaL_Buffer *B);</pre> 6871280405Srpaulo 6872280405Srpaulo<p> 6873280405SrpauloFinishes the use of buffer <code>B</code> leaving the final string on 6874280405Srpaulothe top of the stack. 6875280405Srpaulo 6876280405Srpaulo 6877280405Srpaulo 6878280405Srpaulo 6879280405Srpaulo 6880280405Srpaulo<hr><h3><a name="luaL_pushresultsize"><code>luaL_pushresultsize</code></a></h3><p> 6881326344Simp<span class="apii">[-?, +1, <em>m</em>]</span> 6882280405Srpaulo<pre>void luaL_pushresultsize (luaL_Buffer *B, size_t sz);</pre> 6883280405Srpaulo 6884280405Srpaulo<p> 6885280405SrpauloEquivalent to the sequence <a href="#luaL_addsize"><code>luaL_addsize</code></a>, <a href="#luaL_pushresult"><code>luaL_pushresult</code></a>. 6886280405Srpaulo 6887280405Srpaulo 6888280405Srpaulo 6889280405Srpaulo 6890280405Srpaulo 6891280405Srpaulo<hr><h3><a name="luaL_ref"><code>luaL_ref</code></a></h3><p> 6892326344Simp<span class="apii">[-1, +0, <em>m</em>]</span> 6893280405Srpaulo<pre>int luaL_ref (lua_State *L, int t);</pre> 6894280405Srpaulo 6895280405Srpaulo<p> 6896280405SrpauloCreates and returns a <em>reference</em>, 6897280405Srpauloin the table at index <code>t</code>, 6898280405Srpaulofor the object at the top of the stack (and pops the object). 6899280405Srpaulo 6900280405Srpaulo 6901280405Srpaulo<p> 6902280405SrpauloA reference is a unique integer key. 6903280405SrpauloAs long as you do not manually add integer keys into table <code>t</code>, 6904280405Srpaulo<a href="#luaL_ref"><code>luaL_ref</code></a> ensures the uniqueness of the key it returns. 6905280405SrpauloYou can retrieve an object referred by reference <code>r</code> 6906280405Srpauloby calling <code>lua_rawgeti(L, t, r)</code>. 6907280405SrpauloFunction <a href="#luaL_unref"><code>luaL_unref</code></a> frees a reference and its associated object. 6908280405Srpaulo 6909280405Srpaulo 6910280405Srpaulo<p> 6911280405SrpauloIf the object at the top of the stack is <b>nil</b>, 6912280405Srpaulo<a href="#luaL_ref"><code>luaL_ref</code></a> returns the constant <a name="pdf-LUA_REFNIL"><code>LUA_REFNIL</code></a>. 6913280405SrpauloThe constant <a name="pdf-LUA_NOREF"><code>LUA_NOREF</code></a> is guaranteed to be different 6914280405Srpaulofrom any reference returned by <a href="#luaL_ref"><code>luaL_ref</code></a>. 6915280405Srpaulo 6916280405Srpaulo 6917280405Srpaulo 6918280405Srpaulo 6919280405Srpaulo 6920280405Srpaulo<hr><h3><a name="luaL_Reg"><code>luaL_Reg</code></a></h3> 6921280405Srpaulo<pre>typedef struct luaL_Reg { 6922280405Srpaulo const char *name; 6923280405Srpaulo lua_CFunction func; 6924280405Srpaulo} luaL_Reg;</pre> 6925280405Srpaulo 6926280405Srpaulo<p> 6927280405SrpauloType for arrays of functions to be registered by 6928280405Srpaulo<a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a>. 6929280405Srpaulo<code>name</code> is the function name and <code>func</code> is a pointer to 6930280405Srpaulothe function. 6931280405SrpauloAny array of <a href="#luaL_Reg"><code>luaL_Reg</code></a> must end with a sentinel entry 6932280405Srpauloin which both <code>name</code> and <code>func</code> are <code>NULL</code>. 6933280405Srpaulo 6934280405Srpaulo 6935280405Srpaulo 6936280405Srpaulo 6937280405Srpaulo 6938280405Srpaulo<hr><h3><a name="luaL_requiref"><code>luaL_requiref</code></a></h3><p> 6939280405Srpaulo<span class="apii">[-0, +1, <em>e</em>]</span> 6940280405Srpaulo<pre>void luaL_requiref (lua_State *L, const char *modname, 6941280405Srpaulo lua_CFunction openf, int glb);</pre> 6942280405Srpaulo 6943280405Srpaulo<p> 6944280405SrpauloIf <code>modname</code> is not already present in <a href="#pdf-package.loaded"><code>package.loaded</code></a>, 6945280405Srpaulocalls function <code>openf</code> with string <code>modname</code> as an argument 6946280405Srpauloand sets the call result in <code>package.loaded[modname]</code>, 6947280405Srpauloas if that function has been called through <a href="#pdf-require"><code>require</code></a>. 6948280405Srpaulo 6949280405Srpaulo 6950280405Srpaulo<p> 6951280405SrpauloIf <code>glb</code> is true, 6952280405Srpauloalso stores the module into global <code>modname</code>. 6953280405Srpaulo 6954280405Srpaulo 6955280405Srpaulo<p> 6956280405SrpauloLeaves a copy of the module on the stack. 6957280405Srpaulo 6958280405Srpaulo 6959280405Srpaulo 6960280405Srpaulo 6961280405Srpaulo 6962280405Srpaulo<hr><h3><a name="luaL_setfuncs"><code>luaL_setfuncs</code></a></h3><p> 6963326344Simp<span class="apii">[-nup, +0, <em>m</em>]</span> 6964280405Srpaulo<pre>void luaL_setfuncs (lua_State *L, const luaL_Reg *l, int nup);</pre> 6965280405Srpaulo 6966280405Srpaulo<p> 6967280405SrpauloRegisters all functions in the array <code>l</code> 6968280405Srpaulo(see <a href="#luaL_Reg"><code>luaL_Reg</code></a>) into the table on the top of the stack 6969280405Srpaulo(below optional upvalues, see next). 6970280405Srpaulo 6971280405Srpaulo 6972280405Srpaulo<p> 6973280405SrpauloWhen <code>nup</code> is not zero, 6974280405Srpauloall functions are created sharing <code>nup</code> upvalues, 6975280405Srpaulowhich must be previously pushed on the stack 6976280405Srpauloon top of the library table. 6977280405SrpauloThese values are popped from the stack after the registration. 6978280405Srpaulo 6979280405Srpaulo 6980280405Srpaulo 6981280405Srpaulo 6982280405Srpaulo 6983280405Srpaulo<hr><h3><a name="luaL_setmetatable"><code>luaL_setmetatable</code></a></h3><p> 6984280405Srpaulo<span class="apii">[-0, +0, –]</span> 6985280405Srpaulo<pre>void luaL_setmetatable (lua_State *L, const char *tname);</pre> 6986280405Srpaulo 6987280405Srpaulo<p> 6988280405SrpauloSets the metatable of the object at the top of the stack 6989280405Srpauloas the metatable associated with name <code>tname</code> 6990280405Srpauloin the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). 6991280405Srpaulo 6992280405Srpaulo 6993280405Srpaulo 6994280405Srpaulo 6995280405Srpaulo 6996280405Srpaulo<hr><h3><a name="luaL_Stream"><code>luaL_Stream</code></a></h3> 6997280405Srpaulo<pre>typedef struct luaL_Stream { 6998280405Srpaulo FILE *f; 6999280405Srpaulo lua_CFunction closef; 7000280405Srpaulo} luaL_Stream;</pre> 7001280405Srpaulo 7002280405Srpaulo<p> 7003280405SrpauloThe standard representation for file handles, 7004280405Srpaulowhich is used by the standard I/O library. 7005280405Srpaulo 7006280405Srpaulo 7007280405Srpaulo<p> 7008280405SrpauloA file handle is implemented as a full userdata, 7009280405Srpaulowith a metatable called <code>LUA_FILEHANDLE</code> 7010280405Srpaulo(where <code>LUA_FILEHANDLE</code> is a macro with the actual metatable's name). 7011280405SrpauloThe metatable is created by the I/O library 7012280405Srpaulo(see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). 7013280405Srpaulo 7014280405Srpaulo 7015280405Srpaulo<p> 7016280405SrpauloThis userdata must start with the structure <code>luaL_Stream</code>; 7017280405Srpauloit can contain other data after this initial structure. 7018280405SrpauloField <code>f</code> points to the corresponding C stream 7019280405Srpaulo(or it can be <code>NULL</code> to indicate an incompletely created handle). 7020280405SrpauloField <code>closef</code> points to a Lua function 7021280405Srpaulothat will be called to close the stream 7022280405Srpaulowhen the handle is closed or collected; 7023280405Srpaulothis function receives the file handle as its sole argument and 7024280405Srpaulomust return either <b>true</b> (in case of success) 7025280405Srpauloor <b>nil</b> plus an error message (in case of error). 7026280405SrpauloOnce Lua calls this field, 7027326344Simpit changes the field value to <code>NULL</code> 7028280405Srpauloto signal that the handle is closed. 7029280405Srpaulo 7030280405Srpaulo 7031280405Srpaulo 7032280405Srpaulo 7033280405Srpaulo 7034280405Srpaulo<hr><h3><a name="luaL_testudata"><code>luaL_testudata</code></a></h3><p> 7035326344Simp<span class="apii">[-0, +0, <em>m</em>]</span> 7036280405Srpaulo<pre>void *luaL_testudata (lua_State *L, int arg, const char *tname);</pre> 7037280405Srpaulo 7038280405Srpaulo<p> 7039280405SrpauloThis function works like <a href="#luaL_checkudata"><code>luaL_checkudata</code></a>, 7040280405Srpauloexcept that, when the test fails, 7041280405Srpauloit returns <code>NULL</code> instead of raising an error. 7042280405Srpaulo 7043280405Srpaulo 7044280405Srpaulo 7045280405Srpaulo 7046280405Srpaulo 7047280405Srpaulo<hr><h3><a name="luaL_tolstring"><code>luaL_tolstring</code></a></h3><p> 7048280405Srpaulo<span class="apii">[-0, +1, <em>e</em>]</span> 7049280405Srpaulo<pre>const char *luaL_tolstring (lua_State *L, int idx, size_t *len);</pre> 7050280405Srpaulo 7051280405Srpaulo<p> 7052280405SrpauloConverts any Lua value at the given index to a C string 7053280405Srpauloin a reasonable format. 7054280405SrpauloThe resulting string is pushed onto the stack and also 7055280405Srpauloreturned by the function. 7056280405SrpauloIf <code>len</code> is not <code>NULL</code>, 7057280405Srpaulothe function also sets <code>*len</code> with the string length. 7058280405Srpaulo 7059280405Srpaulo 7060280405Srpaulo<p> 7061326344SimpIf the value has a metatable with a <code>__tostring</code> field, 7062280405Srpaulothen <code>luaL_tolstring</code> calls the corresponding metamethod 7063280405Srpaulowith the value as argument, 7064280405Srpauloand uses the result of the call as its result. 7065280405Srpaulo 7066280405Srpaulo 7067280405Srpaulo 7068280405Srpaulo 7069280405Srpaulo 7070280405Srpaulo<hr><h3><a name="luaL_traceback"><code>luaL_traceback</code></a></h3><p> 7071326344Simp<span class="apii">[-0, +1, <em>m</em>]</span> 7072280405Srpaulo<pre>void luaL_traceback (lua_State *L, lua_State *L1, const char *msg, 7073280405Srpaulo int level);</pre> 7074280405Srpaulo 7075280405Srpaulo<p> 7076280405SrpauloCreates and pushes a traceback of the stack <code>L1</code>. 7077280405SrpauloIf <code>msg</code> is not <code>NULL</code> it is appended 7078280405Srpauloat the beginning of the traceback. 7079280405SrpauloThe <code>level</code> parameter tells at which level 7080280405Srpauloto start the traceback. 7081280405Srpaulo 7082280405Srpaulo 7083280405Srpaulo 7084280405Srpaulo 7085280405Srpaulo 7086280405Srpaulo<hr><h3><a name="luaL_typename"><code>luaL_typename</code></a></h3><p> 7087280405Srpaulo<span class="apii">[-0, +0, –]</span> 7088280405Srpaulo<pre>const char *luaL_typename (lua_State *L, int index);</pre> 7089280405Srpaulo 7090280405Srpaulo<p> 7091280405SrpauloReturns the name of the type of the value at the given index. 7092280405Srpaulo 7093280405Srpaulo 7094280405Srpaulo 7095280405Srpaulo 7096280405Srpaulo 7097280405Srpaulo<hr><h3><a name="luaL_unref"><code>luaL_unref</code></a></h3><p> 7098280405Srpaulo<span class="apii">[-0, +0, –]</span> 7099280405Srpaulo<pre>void luaL_unref (lua_State *L, int t, int ref);</pre> 7100280405Srpaulo 7101280405Srpaulo<p> 7102280405SrpauloReleases reference <code>ref</code> from the table at index <code>t</code> 7103280405Srpaulo(see <a href="#luaL_ref"><code>luaL_ref</code></a>). 7104280405SrpauloThe entry is removed from the table, 7105280405Srpauloso that the referred object can be collected. 7106280405SrpauloThe reference <code>ref</code> is also freed to be used again. 7107280405Srpaulo 7108280405Srpaulo 7109280405Srpaulo<p> 7110280405SrpauloIf <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>, 7111280405Srpaulo<a href="#luaL_unref"><code>luaL_unref</code></a> does nothing. 7112280405Srpaulo 7113280405Srpaulo 7114280405Srpaulo 7115280405Srpaulo 7116280405Srpaulo 7117280405Srpaulo<hr><h3><a name="luaL_where"><code>luaL_where</code></a></h3><p> 7118326344Simp<span class="apii">[-0, +1, <em>m</em>]</span> 7119280405Srpaulo<pre>void luaL_where (lua_State *L, int lvl);</pre> 7120280405Srpaulo 7121280405Srpaulo<p> 7122280405SrpauloPushes onto the stack a string identifying the current position 7123280405Srpauloof the control at level <code>lvl</code> in the call stack. 7124280405SrpauloTypically this string has the following format: 7125280405Srpaulo 7126280405Srpaulo<pre> 7127280405Srpaulo <em>chunkname</em>:<em>currentline</em>: 7128280405Srpaulo</pre><p> 7129280405SrpauloLevel 0 is the running function, 7130280405Srpaulolevel 1 is the function that called the running function, 7131280405Srpauloetc. 7132280405Srpaulo 7133280405Srpaulo 7134280405Srpaulo<p> 7135280405SrpauloThis function is used to build a prefix for error messages. 7136280405Srpaulo 7137280405Srpaulo 7138280405Srpaulo 7139280405Srpaulo 7140280405Srpaulo 7141280405Srpaulo 7142280405Srpaulo 7143280405Srpaulo<h1>6 – <a name="6">Standard Libraries</a></h1> 7144280405Srpaulo 7145280405Srpaulo<p> 7146280405SrpauloThe standard Lua libraries provide useful functions 7147280405Srpaulothat are implemented directly through the C API. 7148280405SrpauloSome of these functions provide essential services to the language 7149280405Srpaulo(e.g., <a href="#pdf-type"><code>type</code></a> and <a href="#pdf-getmetatable"><code>getmetatable</code></a>); 7150280405Srpauloothers provide access to "outside" services (e.g., I/O); 7151280405Srpauloand others could be implemented in Lua itself, 7152280405Srpaulobut are quite useful or have critical performance requirements that 7153280405Srpaulodeserve an implementation in C (e.g., <a href="#pdf-table.sort"><code>table.sort</code></a>). 7154280405Srpaulo 7155280405Srpaulo 7156280405Srpaulo<p> 7157280405SrpauloAll libraries are implemented through the official C API 7158280405Srpauloand are provided as separate C modules. 7159280405SrpauloCurrently, Lua has the following standard libraries: 7160280405Srpaulo 7161280405Srpaulo<ul> 7162280405Srpaulo 7163280405Srpaulo<li>basic library (<a href="#6.1">§6.1</a>);</li> 7164280405Srpaulo 7165280405Srpaulo<li>coroutine library (<a href="#6.2">§6.2</a>);</li> 7166280405Srpaulo 7167280405Srpaulo<li>package library (<a href="#6.3">§6.3</a>);</li> 7168280405Srpaulo 7169280405Srpaulo<li>string manipulation (<a href="#6.4">§6.4</a>);</li> 7170280405Srpaulo 7171280405Srpaulo<li>basic UTF-8 support (<a href="#6.5">§6.5</a>);</li> 7172280405Srpaulo 7173280405Srpaulo<li>table manipulation (<a href="#6.6">§6.6</a>);</li> 7174280405Srpaulo 7175280405Srpaulo<li>mathematical functions (<a href="#6.7">§6.7</a>) (sin, log, etc.);</li> 7176280405Srpaulo 7177280405Srpaulo<li>input and output (<a href="#6.8">§6.8</a>);</li> 7178280405Srpaulo 7179280405Srpaulo<li>operating system facilities (<a href="#6.9">§6.9</a>);</li> 7180280405Srpaulo 7181280405Srpaulo<li>debug facilities (<a href="#6.10">§6.10</a>).</li> 7182280405Srpaulo 7183280405Srpaulo</ul><p> 7184280405SrpauloExcept for the basic and the package libraries, 7185280405Srpauloeach library provides all its functions as fields of a global table 7186280405Srpauloor as methods of its objects. 7187280405Srpaulo 7188280405Srpaulo 7189280405Srpaulo<p> 7190280405SrpauloTo have access to these libraries, 7191280405Srpaulothe C host program should call the <a href="#luaL_openlibs"><code>luaL_openlibs</code></a> function, 7192280405Srpaulowhich opens all standard libraries. 7193280405SrpauloAlternatively, 7194280405Srpaulothe host program can open them individually by using 7195280405Srpaulo<a href="#luaL_requiref"><code>luaL_requiref</code></a> to call 7196280405Srpaulo<a name="pdf-luaopen_base"><code>luaopen_base</code></a> (for the basic library), 7197280405Srpaulo<a name="pdf-luaopen_package"><code>luaopen_package</code></a> (for the package library), 7198280405Srpaulo<a name="pdf-luaopen_coroutine"><code>luaopen_coroutine</code></a> (for the coroutine library), 7199280405Srpaulo<a name="pdf-luaopen_string"><code>luaopen_string</code></a> (for the string library), 7200280405Srpaulo<a name="pdf-luaopen_utf8"><code>luaopen_utf8</code></a> (for the UTF8 library), 7201280405Srpaulo<a name="pdf-luaopen_table"><code>luaopen_table</code></a> (for the table library), 7202280405Srpaulo<a name="pdf-luaopen_math"><code>luaopen_math</code></a> (for the mathematical library), 7203280405Srpaulo<a name="pdf-luaopen_io"><code>luaopen_io</code></a> (for the I/O library), 7204280405Srpaulo<a name="pdf-luaopen_os"><code>luaopen_os</code></a> (for the operating system library), 7205280405Srpauloand <a name="pdf-luaopen_debug"><code>luaopen_debug</code></a> (for the debug library). 7206280405SrpauloThese functions are declared in <a name="pdf-lualib.h"><code>lualib.h</code></a>. 7207280405Srpaulo 7208280405Srpaulo 7209280405Srpaulo 7210280405Srpaulo<h2>6.1 – <a name="6.1">Basic Functions</a></h2> 7211280405Srpaulo 7212280405Srpaulo<p> 7213280405SrpauloThe basic library provides core functions to Lua. 7214280405SrpauloIf you do not include this library in your application, 7215280405Srpauloyou should check carefully whether you need to provide 7216280405Srpauloimplementations for some of its facilities. 7217280405Srpaulo 7218280405Srpaulo 7219280405Srpaulo<p> 7220280405Srpaulo<hr><h3><a name="pdf-assert"><code>assert (v [, message])</code></a></h3> 7221280405Srpaulo 7222280405Srpaulo 7223280405Srpaulo<p> 7224280405SrpauloCalls <a href="#pdf-error"><code>error</code></a> if 7225280405Srpaulothe value of its argument <code>v</code> is false (i.e., <b>nil</b> or <b>false</b>); 7226280405Srpaulootherwise, returns all its arguments. 7227280405SrpauloIn case of error, 7228280405Srpaulo<code>message</code> is the error object; 7229280405Srpaulowhen absent, it defaults to "<code>assertion failed!</code>" 7230280405Srpaulo 7231280405Srpaulo 7232280405Srpaulo 7233280405Srpaulo 7234280405Srpaulo<p> 7235280405Srpaulo<hr><h3><a name="pdf-collectgarbage"><code>collectgarbage ([opt [, arg]])</code></a></h3> 7236280405Srpaulo 7237280405Srpaulo 7238280405Srpaulo<p> 7239280405SrpauloThis function is a generic interface to the garbage collector. 7240280405SrpauloIt performs different functions according to its first argument, <code>opt</code>: 7241280405Srpaulo 7242280405Srpaulo<ul> 7243280405Srpaulo 7244280405Srpaulo<li><b>"<code>collect</code>": </b> 7245280405Srpauloperforms a full garbage-collection cycle. 7246280405SrpauloThis is the default option. 7247280405Srpaulo</li> 7248280405Srpaulo 7249280405Srpaulo<li><b>"<code>stop</code>": </b> 7250280405Srpaulostops automatic execution of the garbage collector. 7251280405SrpauloThe collector will run only when explicitly invoked, 7252280405Srpaulountil a call to restart it. 7253280405Srpaulo</li> 7254280405Srpaulo 7255280405Srpaulo<li><b>"<code>restart</code>": </b> 7256280405Srpaulorestarts automatic execution of the garbage collector. 7257280405Srpaulo</li> 7258280405Srpaulo 7259280405Srpaulo<li><b>"<code>count</code>": </b> 7260280405Srpauloreturns the total memory in use by Lua in Kbytes. 7261280405SrpauloThe value has a fractional part, 7262280405Srpauloso that it multiplied by 1024 7263280405Srpaulogives the exact number of bytes in use by Lua 7264280405Srpaulo(except for overflows). 7265280405Srpaulo</li> 7266280405Srpaulo 7267280405Srpaulo<li><b>"<code>step</code>": </b> 7268280405Srpauloperforms a garbage-collection step. 7269280405SrpauloThe step "size" is controlled by <code>arg</code>. 7270280405SrpauloWith a zero value, 7271280405Srpaulothe collector will perform one basic (indivisible) step. 7272280405SrpauloFor non-zero values, 7273280405Srpaulothe collector will perform as if that amount of memory 7274280405Srpaulo(in KBytes) had been allocated by Lua. 7275280405SrpauloReturns <b>true</b> if the step finished a collection cycle. 7276280405Srpaulo</li> 7277280405Srpaulo 7278280405Srpaulo<li><b>"<code>setpause</code>": </b> 7279280405Srpaulosets <code>arg</code> as the new value for the <em>pause</em> of 7280280405Srpaulothe collector (see <a href="#2.5">§2.5</a>). 7281280405SrpauloReturns the previous value for <em>pause</em>. 7282280405Srpaulo</li> 7283280405Srpaulo 7284280405Srpaulo<li><b>"<code>setstepmul</code>": </b> 7285280405Srpaulosets <code>arg</code> as the new value for the <em>step multiplier</em> of 7286280405Srpaulothe collector (see <a href="#2.5">§2.5</a>). 7287280405SrpauloReturns the previous value for <em>step</em>. 7288280405Srpaulo</li> 7289280405Srpaulo 7290280405Srpaulo<li><b>"<code>isrunning</code>": </b> 7291280405Srpauloreturns a boolean that tells whether the collector is running 7292280405Srpaulo(i.e., not stopped). 7293280405Srpaulo</li> 7294280405Srpaulo 7295280405Srpaulo</ul> 7296280405Srpaulo 7297280405Srpaulo 7298280405Srpaulo 7299280405Srpaulo<p> 7300280405Srpaulo<hr><h3><a name="pdf-dofile"><code>dofile ([filename])</code></a></h3> 7301280405SrpauloOpens the named file and executes its contents as a Lua chunk. 7302280405SrpauloWhen called without arguments, 7303280405Srpaulo<code>dofile</code> executes the contents of the standard input (<code>stdin</code>). 7304280405SrpauloReturns all values returned by the chunk. 7305280405SrpauloIn case of errors, <code>dofile</code> propagates the error 7306280405Srpauloto its caller (that is, <code>dofile</code> does not run in protected mode). 7307280405Srpaulo 7308280405Srpaulo 7309280405Srpaulo 7310280405Srpaulo 7311280405Srpaulo<p> 7312280405Srpaulo<hr><h3><a name="pdf-error"><code>error (message [, level])</code></a></h3> 7313280405SrpauloTerminates the last protected function called 7314280405Srpauloand returns <code>message</code> as the error object. 7315280405SrpauloFunction <code>error</code> never returns. 7316280405Srpaulo 7317280405Srpaulo 7318280405Srpaulo<p> 7319280405SrpauloUsually, <code>error</code> adds some information about the error position 7320280405Srpauloat the beginning of the message, if the message is a string. 7321280405SrpauloThe <code>level</code> argument specifies how to get the error position. 7322280405SrpauloWith level 1 (the default), the error position is where the 7323280405Srpaulo<code>error</code> function was called. 7324280405SrpauloLevel 2 points the error to where the function 7325280405Srpaulothat called <code>error</code> was called; and so on. 7326280405SrpauloPassing a level 0 avoids the addition of error position information 7327280405Srpauloto the message. 7328280405Srpaulo 7329280405Srpaulo 7330280405Srpaulo 7331280405Srpaulo 7332280405Srpaulo<p> 7333280405Srpaulo<hr><h3><a name="pdf-_G"><code>_G</code></a></h3> 7334280405SrpauloA global variable (not a function) that 7335280405Srpauloholds the global environment (see <a href="#2.2">§2.2</a>). 7336280405SrpauloLua itself does not use this variable; 7337280405Srpaulochanging its value does not affect any environment, 7338280405Srpaulonor vice versa. 7339280405Srpaulo 7340280405Srpaulo 7341280405Srpaulo 7342280405Srpaulo 7343280405Srpaulo<p> 7344280405Srpaulo<hr><h3><a name="pdf-getmetatable"><code>getmetatable (object)</code></a></h3> 7345280405Srpaulo 7346280405Srpaulo 7347280405Srpaulo<p> 7348280405SrpauloIf <code>object</code> does not have a metatable, returns <b>nil</b>. 7349280405SrpauloOtherwise, 7350326344Simpif the object's metatable has a <code>__metatable</code> field, 7351280405Srpauloreturns the associated value. 7352280405SrpauloOtherwise, returns the metatable of the given object. 7353280405Srpaulo 7354280405Srpaulo 7355280405Srpaulo 7356280405Srpaulo 7357280405Srpaulo<p> 7358280405Srpaulo<hr><h3><a name="pdf-ipairs"><code>ipairs (t)</code></a></h3> 7359280405Srpaulo 7360280405Srpaulo 7361280405Srpaulo<p> 7362280405SrpauloReturns three values (an iterator function, the table <code>t</code>, and 0) 7363280405Srpauloso that the construction 7364280405Srpaulo 7365280405Srpaulo<pre> 7366280405Srpaulo for i,v in ipairs(t) do <em>body</em> end 7367280405Srpaulo</pre><p> 7368280405Srpaulowill iterate over the key–value pairs 7369280405Srpaulo(<code>1,t[1]</code>), (<code>2,t[2]</code>), ..., 7370280405Srpauloup to the first nil value. 7371280405Srpaulo 7372280405Srpaulo 7373280405Srpaulo 7374280405Srpaulo 7375280405Srpaulo<p> 7376280405Srpaulo<hr><h3><a name="pdf-load"><code>load (chunk [, chunkname [, mode [, env]]])</code></a></h3> 7377280405Srpaulo 7378280405Srpaulo 7379280405Srpaulo<p> 7380280405SrpauloLoads a chunk. 7381280405Srpaulo 7382280405Srpaulo 7383280405Srpaulo<p> 7384280405SrpauloIf <code>chunk</code> is a string, the chunk is this string. 7385280405SrpauloIf <code>chunk</code> is a function, 7386280405Srpaulo<code>load</code> calls it repeatedly to get the chunk pieces. 7387280405SrpauloEach call to <code>chunk</code> must return a string that concatenates 7388280405Srpaulowith previous results. 7389280405SrpauloA return of an empty string, <b>nil</b>, or no value signals the end of the chunk. 7390280405Srpaulo 7391280405Srpaulo 7392280405Srpaulo<p> 7393280405SrpauloIf there are no syntactic errors, 7394280405Srpauloreturns the compiled chunk as a function; 7395280405Srpaulootherwise, returns <b>nil</b> plus the error message. 7396280405Srpaulo 7397280405Srpaulo 7398280405Srpaulo<p> 7399280405SrpauloIf the resulting function has upvalues, 7400280405Srpaulothe first upvalue is set to the value of <code>env</code>, 7401280405Srpauloif that parameter is given, 7402280405Srpauloor to the value of the global environment. 7403280405SrpauloOther upvalues are initialized with <b>nil</b>. 7404280405Srpaulo(When you load a main chunk, 7405280405Srpaulothe resulting function will always have exactly one upvalue, 7406280405Srpaulothe <code>_ENV</code> variable (see <a href="#2.2">§2.2</a>). 7407280405SrpauloHowever, 7408280405Srpaulowhen you load a binary chunk created from a function (see <a href="#pdf-string.dump"><code>string.dump</code></a>), 7409280405Srpaulothe resulting function can have an arbitrary number of upvalues.) 7410280405SrpauloAll upvalues are fresh, that is, 7411280405Srpaulothey are not shared with any other function. 7412280405Srpaulo 7413280405Srpaulo 7414280405Srpaulo<p> 7415280405Srpaulo<code>chunkname</code> is used as the name of the chunk for error messages 7416280405Srpauloand debug information (see <a href="#4.9">§4.9</a>). 7417280405SrpauloWhen absent, 7418280405Srpauloit defaults to <code>chunk</code>, if <code>chunk</code> is a string, 7419280405Srpauloor to "<code>=(load)</code>" otherwise. 7420280405Srpaulo 7421280405Srpaulo 7422280405Srpaulo<p> 7423280405SrpauloThe string <code>mode</code> controls whether the chunk can be text or binary 7424280405Srpaulo(that is, a precompiled chunk). 7425280405SrpauloIt may be the string "<code>b</code>" (only binary chunks), 7426280405Srpaulo"<code>t</code>" (only text chunks), 7427280405Srpauloor "<code>bt</code>" (both binary and text). 7428280405SrpauloThe default is "<code>bt</code>". 7429280405Srpaulo 7430280405Srpaulo 7431280405Srpaulo<p> 7432280405SrpauloLua does not check the consistency of binary chunks. 7433280405SrpauloMaliciously crafted binary chunks can crash 7434280405Srpaulothe interpreter. 7435280405Srpaulo 7436280405Srpaulo 7437280405Srpaulo 7438280405Srpaulo 7439280405Srpaulo<p> 7440280405Srpaulo<hr><h3><a name="pdf-loadfile"><code>loadfile ([filename [, mode [, env]]])</code></a></h3> 7441280405Srpaulo 7442280405Srpaulo 7443280405Srpaulo<p> 7444280405SrpauloSimilar to <a href="#pdf-load"><code>load</code></a>, 7445280405Srpaulobut gets the chunk from file <code>filename</code> 7446280405Srpauloor from the standard input, 7447280405Srpauloif no file name is given. 7448280405Srpaulo 7449280405Srpaulo 7450280405Srpaulo 7451280405Srpaulo 7452280405Srpaulo<p> 7453280405Srpaulo<hr><h3><a name="pdf-next"><code>next (table [, index])</code></a></h3> 7454280405Srpaulo 7455280405Srpaulo 7456280405Srpaulo<p> 7457280405SrpauloAllows a program to traverse all fields of a table. 7458280405SrpauloIts first argument is a table and its second argument 7459280405Srpaulois an index in this table. 7460280405Srpaulo<code>next</code> returns the next index of the table 7461280405Srpauloand its associated value. 7462280405SrpauloWhen called with <b>nil</b> as its second argument, 7463280405Srpaulo<code>next</code> returns an initial index 7464280405Srpauloand its associated value. 7465280405SrpauloWhen called with the last index, 7466280405Srpauloor with <b>nil</b> in an empty table, 7467280405Srpaulo<code>next</code> returns <b>nil</b>. 7468280405SrpauloIf the second argument is absent, then it is interpreted as <b>nil</b>. 7469280405SrpauloIn particular, 7470280405Srpauloyou can use <code>next(t)</code> to check whether a table is empty. 7471280405Srpaulo 7472280405Srpaulo 7473280405Srpaulo<p> 7474280405SrpauloThe order in which the indices are enumerated is not specified, 7475280405Srpaulo<em>even for numeric indices</em>. 7476326344Simp(To traverse a table in numerical order, 7477280405Srpaulouse a numerical <b>for</b>.) 7478280405Srpaulo 7479280405Srpaulo 7480280405Srpaulo<p> 7481280405SrpauloThe behavior of <code>next</code> is undefined if, 7482280405Srpauloduring the traversal, 7483280405Srpauloyou assign any value to a non-existent field in the table. 7484280405SrpauloYou may however modify existing fields. 7485280405SrpauloIn particular, you may clear existing fields. 7486280405Srpaulo 7487280405Srpaulo 7488280405Srpaulo 7489280405Srpaulo 7490280405Srpaulo<p> 7491280405Srpaulo<hr><h3><a name="pdf-pairs"><code>pairs (t)</code></a></h3> 7492280405Srpaulo 7493280405Srpaulo 7494280405Srpaulo<p> 7495280405SrpauloIf <code>t</code> has a metamethod <code>__pairs</code>, 7496280405Srpaulocalls it with <code>t</code> as argument and returns the first three 7497280405Srpauloresults from the call. 7498280405Srpaulo 7499280405Srpaulo 7500280405Srpaulo<p> 7501280405SrpauloOtherwise, 7502280405Srpauloreturns three values: the <a href="#pdf-next"><code>next</code></a> function, the table <code>t</code>, and <b>nil</b>, 7503280405Srpauloso that the construction 7504280405Srpaulo 7505280405Srpaulo<pre> 7506280405Srpaulo for k,v in pairs(t) do <em>body</em> end 7507280405Srpaulo</pre><p> 7508280405Srpaulowill iterate over all key–value pairs of table <code>t</code>. 7509280405Srpaulo 7510280405Srpaulo 7511280405Srpaulo<p> 7512280405SrpauloSee function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying 7513280405Srpaulothe table during its traversal. 7514280405Srpaulo 7515280405Srpaulo 7516280405Srpaulo 7517280405Srpaulo 7518280405Srpaulo<p> 7519280405Srpaulo<hr><h3><a name="pdf-pcall"><code>pcall (f [, arg1, ···])</code></a></h3> 7520280405Srpaulo 7521280405Srpaulo 7522280405Srpaulo<p> 7523280405SrpauloCalls function <code>f</code> with 7524280405Srpaulothe given arguments in <em>protected mode</em>. 7525280405SrpauloThis means that any error inside <code>f</code> is not propagated; 7526280405Srpauloinstead, <code>pcall</code> catches the error 7527280405Srpauloand returns a status code. 7528280405SrpauloIts first result is the status code (a boolean), 7529280405Srpaulowhich is true if the call succeeds without errors. 7530280405SrpauloIn such case, <code>pcall</code> also returns all results from the call, 7531280405Srpauloafter this first result. 7532280405SrpauloIn case of any error, <code>pcall</code> returns <b>false</b> plus the error message. 7533280405Srpaulo 7534280405Srpaulo 7535280405Srpaulo 7536280405Srpaulo 7537280405Srpaulo<p> 7538280405Srpaulo<hr><h3><a name="pdf-print"><code>print (···)</code></a></h3> 7539280405SrpauloReceives any number of arguments 7540280405Srpauloand prints their values to <code>stdout</code>, 7541280405Srpaulousing the <a href="#pdf-tostring"><code>tostring</code></a> function to convert each argument to a string. 7542280405Srpaulo<code>print</code> is not intended for formatted output, 7543280405Srpaulobut only as a quick way to show a value, 7544280405Srpaulofor instance for debugging. 7545280405SrpauloFor complete control over the output, 7546280405Srpaulouse <a href="#pdf-string.format"><code>string.format</code></a> and <a href="#pdf-io.write"><code>io.write</code></a>. 7547280405Srpaulo 7548280405Srpaulo 7549280405Srpaulo 7550280405Srpaulo 7551280405Srpaulo<p> 7552280405Srpaulo<hr><h3><a name="pdf-rawequal"><code>rawequal (v1, v2)</code></a></h3> 7553280405SrpauloChecks whether <code>v1</code> is equal to <code>v2</code>, 7554326344Simpwithout invoking the <code>__eq</code> metamethod. 7555280405SrpauloReturns a boolean. 7556280405Srpaulo 7557280405Srpaulo 7558280405Srpaulo 7559280405Srpaulo 7560280405Srpaulo<p> 7561280405Srpaulo<hr><h3><a name="pdf-rawget"><code>rawget (table, index)</code></a></h3> 7562280405SrpauloGets the real value of <code>table[index]</code>, 7563326344Simpwithout invoking the <code>__index</code> metamethod. 7564280405Srpaulo<code>table</code> must be a table; 7565280405Srpaulo<code>index</code> may be any value. 7566280405Srpaulo 7567280405Srpaulo 7568280405Srpaulo 7569280405Srpaulo 7570280405Srpaulo<p> 7571280405Srpaulo<hr><h3><a name="pdf-rawlen"><code>rawlen (v)</code></a></h3> 7572280405SrpauloReturns the length of the object <code>v</code>, 7573280405Srpaulowhich must be a table or a string, 7574326344Simpwithout invoking the <code>__len</code> metamethod. 7575280405SrpauloReturns an integer. 7576280405Srpaulo 7577280405Srpaulo 7578280405Srpaulo 7579280405Srpaulo 7580280405Srpaulo<p> 7581280405Srpaulo<hr><h3><a name="pdf-rawset"><code>rawset (table, index, value)</code></a></h3> 7582280405SrpauloSets the real value of <code>table[index]</code> to <code>value</code>, 7583326344Simpwithout invoking the <code>__newindex</code> metamethod. 7584280405Srpaulo<code>table</code> must be a table, 7585280405Srpaulo<code>index</code> any value different from <b>nil</b> and NaN, 7586280405Srpauloand <code>value</code> any Lua value. 7587280405Srpaulo 7588280405Srpaulo 7589280405Srpaulo<p> 7590280405SrpauloThis function returns <code>table</code>. 7591280405Srpaulo 7592280405Srpaulo 7593280405Srpaulo 7594280405Srpaulo 7595280405Srpaulo<p> 7596280405Srpaulo<hr><h3><a name="pdf-select"><code>select (index, ···)</code></a></h3> 7597280405Srpaulo 7598280405Srpaulo 7599280405Srpaulo<p> 7600280405SrpauloIf <code>index</code> is a number, 7601280405Srpauloreturns all arguments after argument number <code>index</code>; 7602280405Srpauloa negative number indexes from the end (-1 is the last argument). 7603280405SrpauloOtherwise, <code>index</code> must be the string <code>"#"</code>, 7604280405Srpauloand <code>select</code> returns the total number of extra arguments it received. 7605280405Srpaulo 7606280405Srpaulo 7607280405Srpaulo 7608280405Srpaulo 7609280405Srpaulo<p> 7610280405Srpaulo<hr><h3><a name="pdf-setmetatable"><code>setmetatable (table, metatable)</code></a></h3> 7611280405Srpaulo 7612280405Srpaulo 7613280405Srpaulo<p> 7614280405SrpauloSets the metatable for the given table. 7615326344Simp(To change the metatable of other types from Lua code, 7616326344Simpyou must use the debug library (<a href="#6.10">§6.10</a>).) 7617280405SrpauloIf <code>metatable</code> is <b>nil</b>, 7618280405Srpauloremoves the metatable of the given table. 7619326344SimpIf the original metatable has a <code>__metatable</code> field, 7620280405Srpauloraises an error. 7621280405Srpaulo 7622280405Srpaulo 7623280405Srpaulo<p> 7624280405SrpauloThis function returns <code>table</code>. 7625280405Srpaulo 7626280405Srpaulo 7627280405Srpaulo 7628280405Srpaulo 7629280405Srpaulo<p> 7630280405Srpaulo<hr><h3><a name="pdf-tonumber"><code>tonumber (e [, base])</code></a></h3> 7631280405Srpaulo 7632280405Srpaulo 7633280405Srpaulo<p> 7634280405SrpauloWhen called with no <code>base</code>, 7635280405Srpaulo<code>tonumber</code> tries to convert its argument to a number. 7636280405SrpauloIf the argument is already a number or 7637280405Srpauloa string convertible to a number, 7638280405Srpaulothen <code>tonumber</code> returns this number; 7639280405Srpaulootherwise, it returns <b>nil</b>. 7640280405Srpaulo 7641280405Srpaulo 7642280405Srpaulo<p> 7643280405SrpauloThe conversion of strings can result in integers or floats, 7644280405Srpauloaccording to the lexical conventions of Lua (see <a href="#3.1">§3.1</a>). 7645280405Srpaulo(The string may have leading and trailing spaces and a sign.) 7646280405Srpaulo 7647280405Srpaulo 7648280405Srpaulo<p> 7649280405SrpauloWhen called with <code>base</code>, 7650280405Srpaulothen <code>e</code> must be a string to be interpreted as 7651280405Srpauloan integer numeral in that base. 7652280405SrpauloThe base may be any integer between 2 and 36, inclusive. 7653280405SrpauloIn bases above 10, the letter '<code>A</code>' (in either upper or lower case) 7654280405Srpaulorepresents 10, '<code>B</code>' represents 11, and so forth, 7655280405Srpaulowith '<code>Z</code>' representing 35. 7656280405SrpauloIf the string <code>e</code> is not a valid numeral in the given base, 7657280405Srpaulothe function returns <b>nil</b>. 7658280405Srpaulo 7659280405Srpaulo 7660280405Srpaulo 7661280405Srpaulo 7662280405Srpaulo<p> 7663280405Srpaulo<hr><h3><a name="pdf-tostring"><code>tostring (v)</code></a></h3> 7664280405SrpauloReceives a value of any type and 7665280405Srpauloconverts it to a string in a human-readable format. 7666280405Srpaulo(For complete control of how numbers are converted, 7667280405Srpaulouse <a href="#pdf-string.format"><code>string.format</code></a>.) 7668280405Srpaulo 7669280405Srpaulo 7670280405Srpaulo<p> 7671326344SimpIf the metatable of <code>v</code> has a <code>__tostring</code> field, 7672280405Srpaulothen <code>tostring</code> calls the corresponding value 7673280405Srpaulowith <code>v</code> as argument, 7674280405Srpauloand uses the result of the call as its result. 7675280405Srpaulo 7676280405Srpaulo 7677280405Srpaulo 7678280405Srpaulo 7679280405Srpaulo<p> 7680280405Srpaulo<hr><h3><a name="pdf-type"><code>type (v)</code></a></h3> 7681280405SrpauloReturns the type of its only argument, coded as a string. 7682280405SrpauloThe possible results of this function are 7683280405Srpaulo"<code>nil</code>" (a string, not the value <b>nil</b>), 7684280405Srpaulo"<code>number</code>", 7685280405Srpaulo"<code>string</code>", 7686280405Srpaulo"<code>boolean</code>", 7687280405Srpaulo"<code>table</code>", 7688280405Srpaulo"<code>function</code>", 7689280405Srpaulo"<code>thread</code>", 7690280405Srpauloand "<code>userdata</code>". 7691280405Srpaulo 7692280405Srpaulo 7693280405Srpaulo 7694280405Srpaulo 7695280405Srpaulo<p> 7696280405Srpaulo<hr><h3><a name="pdf-_VERSION"><code>_VERSION</code></a></h3> 7697326344Simp 7698326344Simp 7699326344Simp<p> 7700280405SrpauloA global variable (not a function) that 7701326344Simpholds a string containing the running Lua version. 7702280405SrpauloThe current value of this variable is "<code>Lua 5.3</code>". 7703280405Srpaulo 7704280405Srpaulo 7705280405Srpaulo 7706280405Srpaulo 7707280405Srpaulo<p> 7708280405Srpaulo<hr><h3><a name="pdf-xpcall"><code>xpcall (f, msgh [, arg1, ···])</code></a></h3> 7709280405Srpaulo 7710280405Srpaulo 7711280405Srpaulo<p> 7712280405SrpauloThis function is similar to <a href="#pdf-pcall"><code>pcall</code></a>, 7713280405Srpauloexcept that it sets a new message handler <code>msgh</code>. 7714280405Srpaulo 7715280405Srpaulo 7716280405Srpaulo 7717280405Srpaulo 7718280405Srpaulo 7719280405Srpaulo 7720280405Srpaulo 7721280405Srpaulo<h2>6.2 – <a name="6.2">Coroutine Manipulation</a></h2> 7722280405Srpaulo 7723280405Srpaulo<p> 7724326344SimpThis library comprises the operations to manipulate coroutines, 7725326344Simpwhich come inside the table <a name="pdf-coroutine"><code>coroutine</code></a>. 7726280405SrpauloSee <a href="#2.6">§2.6</a> for a general description of coroutines. 7727280405Srpaulo 7728280405Srpaulo 7729280405Srpaulo<p> 7730280405Srpaulo<hr><h3><a name="pdf-coroutine.create"><code>coroutine.create (f)</code></a></h3> 7731280405Srpaulo 7732280405Srpaulo 7733280405Srpaulo<p> 7734280405SrpauloCreates a new coroutine, with body <code>f</code>. 7735326344Simp<code>f</code> must be a function. 7736280405SrpauloReturns this new coroutine, 7737280405Srpauloan object with type <code>"thread"</code>. 7738280405Srpaulo 7739280405Srpaulo 7740280405Srpaulo 7741280405Srpaulo 7742280405Srpaulo<p> 7743280405Srpaulo<hr><h3><a name="pdf-coroutine.isyieldable"><code>coroutine.isyieldable ()</code></a></h3> 7744280405Srpaulo 7745280405Srpaulo 7746280405Srpaulo<p> 7747280405SrpauloReturns true when the running coroutine can yield. 7748280405Srpaulo 7749280405Srpaulo 7750280405Srpaulo<p> 7751280405SrpauloA running coroutine is yieldable if it is not the main thread and 7752326344Simpit is not inside a non-yieldable C function. 7753280405Srpaulo 7754280405Srpaulo 7755280405Srpaulo 7756280405Srpaulo 7757280405Srpaulo<p> 7758280405Srpaulo<hr><h3><a name="pdf-coroutine.resume"><code>coroutine.resume (co [, val1, ···])</code></a></h3> 7759280405Srpaulo 7760280405Srpaulo 7761280405Srpaulo<p> 7762280405SrpauloStarts or continues the execution of coroutine <code>co</code>. 7763280405SrpauloThe first time you resume a coroutine, 7764280405Srpauloit starts running its body. 7765280405SrpauloThe values <code>val1</code>, ... are passed 7766280405Srpauloas the arguments to the body function. 7767280405SrpauloIf the coroutine has yielded, 7768280405Srpaulo<code>resume</code> restarts it; 7769280405Srpaulothe values <code>val1</code>, ... are passed 7770280405Srpauloas the results from the yield. 7771280405Srpaulo 7772280405Srpaulo 7773280405Srpaulo<p> 7774280405SrpauloIf the coroutine runs without any errors, 7775280405Srpaulo<code>resume</code> returns <b>true</b> plus any values passed to <code>yield</code> 7776280405Srpaulo(when the coroutine yields) or any values returned by the body function 7777280405Srpaulo(when the coroutine terminates). 7778280405SrpauloIf there is any error, 7779280405Srpaulo<code>resume</code> returns <b>false</b> plus the error message. 7780280405Srpaulo 7781280405Srpaulo 7782280405Srpaulo 7783280405Srpaulo 7784280405Srpaulo<p> 7785280405Srpaulo<hr><h3><a name="pdf-coroutine.running"><code>coroutine.running ()</code></a></h3> 7786280405Srpaulo 7787280405Srpaulo 7788280405Srpaulo<p> 7789280405SrpauloReturns the running coroutine plus a boolean, 7790280405Srpaulotrue when the running coroutine is the main one. 7791280405Srpaulo 7792280405Srpaulo 7793280405Srpaulo 7794280405Srpaulo 7795280405Srpaulo<p> 7796280405Srpaulo<hr><h3><a name="pdf-coroutine.status"><code>coroutine.status (co)</code></a></h3> 7797280405Srpaulo 7798280405Srpaulo 7799280405Srpaulo<p> 7800280405SrpauloReturns the status of coroutine <code>co</code>, as a string: 7801280405Srpaulo<code>"running"</code>, 7802280405Srpauloif the coroutine is running (that is, it called <code>status</code>); 7803280405Srpaulo<code>"suspended"</code>, if the coroutine is suspended in a call to <code>yield</code>, 7804280405Srpauloor if it has not started running yet; 7805280405Srpaulo<code>"normal"</code> if the coroutine is active but not running 7806280405Srpaulo(that is, it has resumed another coroutine); 7807280405Srpauloand <code>"dead"</code> if the coroutine has finished its body function, 7808280405Srpauloor if it has stopped with an error. 7809280405Srpaulo 7810280405Srpaulo 7811280405Srpaulo 7812280405Srpaulo 7813280405Srpaulo<p> 7814280405Srpaulo<hr><h3><a name="pdf-coroutine.wrap"><code>coroutine.wrap (f)</code></a></h3> 7815280405Srpaulo 7816280405Srpaulo 7817280405Srpaulo<p> 7818280405SrpauloCreates a new coroutine, with body <code>f</code>. 7819326344Simp<code>f</code> must be a function. 7820280405SrpauloReturns a function that resumes the coroutine each time it is called. 7821280405SrpauloAny arguments passed to the function behave as the 7822280405Srpauloextra arguments to <code>resume</code>. 7823280405SrpauloReturns the same values returned by <code>resume</code>, 7824280405Srpauloexcept the first boolean. 7825280405SrpauloIn case of error, propagates the error. 7826280405Srpaulo 7827280405Srpaulo 7828280405Srpaulo 7829280405Srpaulo 7830280405Srpaulo<p> 7831280405Srpaulo<hr><h3><a name="pdf-coroutine.yield"><code>coroutine.yield (···)</code></a></h3> 7832280405Srpaulo 7833280405Srpaulo 7834280405Srpaulo<p> 7835280405SrpauloSuspends the execution of the calling coroutine. 7836280405SrpauloAny arguments to <code>yield</code> are passed as extra results to <code>resume</code>. 7837280405Srpaulo 7838280405Srpaulo 7839280405Srpaulo 7840280405Srpaulo 7841280405Srpaulo 7842280405Srpaulo 7843280405Srpaulo 7844280405Srpaulo<h2>6.3 – <a name="6.3">Modules</a></h2> 7845280405Srpaulo 7846280405Srpaulo<p> 7847280405SrpauloThe package library provides basic 7848280405Srpaulofacilities for loading modules in Lua. 7849280405SrpauloIt exports one function directly in the global environment: 7850280405Srpaulo<a href="#pdf-require"><code>require</code></a>. 7851280405SrpauloEverything else is exported in a table <a name="pdf-package"><code>package</code></a>. 7852280405Srpaulo 7853280405Srpaulo 7854280405Srpaulo<p> 7855280405Srpaulo<hr><h3><a name="pdf-require"><code>require (modname)</code></a></h3> 7856280405Srpaulo 7857280405Srpaulo 7858280405Srpaulo<p> 7859280405SrpauloLoads the given module. 7860280405SrpauloThe function starts by looking into the <a href="#pdf-package.loaded"><code>package.loaded</code></a> table 7861280405Srpauloto determine whether <code>modname</code> is already loaded. 7862280405SrpauloIf it is, then <code>require</code> returns the value stored 7863280405Srpauloat <code>package.loaded[modname]</code>. 7864280405SrpauloOtherwise, it tries to find a <em>loader</em> for the module. 7865280405Srpaulo 7866280405Srpaulo 7867280405Srpaulo<p> 7868280405SrpauloTo find a loader, 7869280405Srpaulo<code>require</code> is guided by the <a href="#pdf-package.searchers"><code>package.searchers</code></a> sequence. 7870280405SrpauloBy changing this sequence, 7871280405Srpaulowe can change how <code>require</code> looks for a module. 7872280405SrpauloThe following explanation is based on the default configuration 7873280405Srpaulofor <a href="#pdf-package.searchers"><code>package.searchers</code></a>. 7874280405Srpaulo 7875280405Srpaulo 7876280405Srpaulo<p> 7877280405SrpauloFirst <code>require</code> queries <code>package.preload[modname]</code>. 7878280405SrpauloIf it has a value, 7879280405Srpaulothis value (which must be a function) is the loader. 7880280405SrpauloOtherwise <code>require</code> searches for a Lua loader using the 7881280405Srpaulopath stored in <a href="#pdf-package.path"><code>package.path</code></a>. 7882280405SrpauloIf that also fails, it searches for a C loader using the 7883280405Srpaulopath stored in <a href="#pdf-package.cpath"><code>package.cpath</code></a>. 7884280405SrpauloIf that also fails, 7885280405Srpauloit tries an <em>all-in-one</em> loader (see <a href="#pdf-package.searchers"><code>package.searchers</code></a>). 7886280405Srpaulo 7887280405Srpaulo 7888280405Srpaulo<p> 7889280405SrpauloOnce a loader is found, 7890280405Srpaulo<code>require</code> calls the loader with two arguments: 7891280405Srpaulo<code>modname</code> and an extra value dependent on how it got the loader. 7892280405Srpaulo(If the loader came from a file, 7893280405Srpaulothis extra value is the file name.) 7894280405SrpauloIf the loader returns any non-nil value, 7895280405Srpaulo<code>require</code> assigns the returned value to <code>package.loaded[modname]</code>. 7896280405SrpauloIf the loader does not return a non-nil value and 7897280405Srpaulohas not assigned any value to <code>package.loaded[modname]</code>, 7898280405Srpaulothen <code>require</code> assigns <b>true</b> to this entry. 7899280405SrpauloIn any case, <code>require</code> returns the 7900280405Srpaulofinal value of <code>package.loaded[modname]</code>. 7901280405Srpaulo 7902280405Srpaulo 7903280405Srpaulo<p> 7904280405SrpauloIf there is any error loading or running the module, 7905280405Srpauloor if it cannot find any loader for the module, 7906280405Srpaulothen <code>require</code> raises an error. 7907280405Srpaulo 7908280405Srpaulo 7909280405Srpaulo 7910280405Srpaulo 7911280405Srpaulo<p> 7912280405Srpaulo<hr><h3><a name="pdf-package.config"><code>package.config</code></a></h3> 7913280405Srpaulo 7914280405Srpaulo 7915280405Srpaulo<p> 7916280405SrpauloA string describing some compile-time configurations for packages. 7917280405SrpauloThis string is a sequence of lines: 7918280405Srpaulo 7919280405Srpaulo<ul> 7920280405Srpaulo 7921280405Srpaulo<li>The first line is the directory separator string. 7922280405SrpauloDefault is '<code>\</code>' for Windows and '<code>/</code>' for all other systems.</li> 7923280405Srpaulo 7924280405Srpaulo<li>The second line is the character that separates templates in a path. 7925280405SrpauloDefault is '<code>;</code>'.</li> 7926280405Srpaulo 7927280405Srpaulo<li>The third line is the string that marks the 7928280405Srpaulosubstitution points in a template. 7929280405SrpauloDefault is '<code>?</code>'.</li> 7930280405Srpaulo 7931280405Srpaulo<li>The fourth line is a string that, in a path in Windows, 7932280405Srpaulois replaced by the executable's directory. 7933280405SrpauloDefault is '<code>!</code>'.</li> 7934280405Srpaulo 7935280405Srpaulo<li>The fifth line is a mark to ignore all text after it 7936280405Srpaulowhen building the <code>luaopen_</code> function name. 7937280405SrpauloDefault is '<code>-</code>'.</li> 7938280405Srpaulo 7939280405Srpaulo</ul> 7940280405Srpaulo 7941280405Srpaulo 7942280405Srpaulo 7943280405Srpaulo<p> 7944280405Srpaulo<hr><h3><a name="pdf-package.cpath"><code>package.cpath</code></a></h3> 7945280405Srpaulo 7946280405Srpaulo 7947280405Srpaulo<p> 7948280405SrpauloThe path used by <a href="#pdf-require"><code>require</code></a> to search for a C loader. 7949280405Srpaulo 7950280405Srpaulo 7951280405Srpaulo<p> 7952280405SrpauloLua initializes the C path <a href="#pdf-package.cpath"><code>package.cpath</code></a> in the same way 7953280405Srpauloit initializes the Lua path <a href="#pdf-package.path"><code>package.path</code></a>, 7954326344Simpusing the environment variable <a name="pdf-LUA_CPATH_5_3"><code>LUA_CPATH_5_3</code></a>, 7955326344Simpor the environment variable <a name="pdf-LUA_CPATH"><code>LUA_CPATH</code></a>, 7956280405Srpauloor a default path defined in <code>luaconf.h</code>. 7957280405Srpaulo 7958280405Srpaulo 7959280405Srpaulo 7960280405Srpaulo 7961280405Srpaulo<p> 7962280405Srpaulo<hr><h3><a name="pdf-package.loaded"><code>package.loaded</code></a></h3> 7963280405Srpaulo 7964280405Srpaulo 7965280405Srpaulo<p> 7966280405SrpauloA table used by <a href="#pdf-require"><code>require</code></a> to control which 7967280405Srpaulomodules are already loaded. 7968280405SrpauloWhen you require a module <code>modname</code> and 7969280405Srpaulo<code>package.loaded[modname]</code> is not false, 7970280405Srpaulo<a href="#pdf-require"><code>require</code></a> simply returns the value stored there. 7971280405Srpaulo 7972280405Srpaulo 7973280405Srpaulo<p> 7974280405SrpauloThis variable is only a reference to the real table; 7975280405Srpauloassignments to this variable do not change the 7976280405Srpaulotable used by <a href="#pdf-require"><code>require</code></a>. 7977280405Srpaulo 7978280405Srpaulo 7979280405Srpaulo 7980280405Srpaulo 7981280405Srpaulo<p> 7982280405Srpaulo<hr><h3><a name="pdf-package.loadlib"><code>package.loadlib (libname, funcname)</code></a></h3> 7983280405Srpaulo 7984280405Srpaulo 7985280405Srpaulo<p> 7986280405SrpauloDynamically links the host program with the C library <code>libname</code>. 7987280405Srpaulo 7988280405Srpaulo 7989280405Srpaulo<p> 7990280405SrpauloIf <code>funcname</code> is "<code>*</code>", 7991280405Srpaulothen it only links with the library, 7992280405Srpaulomaking the symbols exported by the library 7993280405Srpauloavailable to other dynamically linked libraries. 7994280405SrpauloOtherwise, 7995280405Srpauloit looks for a function <code>funcname</code> inside the library 7996280405Srpauloand returns this function as a C function. 7997280405SrpauloSo, <code>funcname</code> must follow the <a href="#lua_CFunction"><code>lua_CFunction</code></a> prototype 7998280405Srpaulo(see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 7999280405Srpaulo 8000280405Srpaulo 8001280405Srpaulo<p> 8002280405SrpauloThis is a low-level function. 8003280405SrpauloIt completely bypasses the package and module system. 8004280405SrpauloUnlike <a href="#pdf-require"><code>require</code></a>, 8005280405Srpauloit does not perform any path searching and 8006280405Srpaulodoes not automatically adds extensions. 8007280405Srpaulo<code>libname</code> must be the complete file name of the C library, 8008280405Srpauloincluding if necessary a path and an extension. 8009280405Srpaulo<code>funcname</code> must be the exact name exported by the C library 8010280405Srpaulo(which may depend on the C compiler and linker used). 8011280405Srpaulo 8012280405Srpaulo 8013280405Srpaulo<p> 8014280405SrpauloThis function is not supported by Standard C. 8015280405SrpauloAs such, it is only available on some platforms 8016280405Srpaulo(Windows, Linux, Mac OS X, Solaris, BSD, 8017280405Srpauloplus other Unix systems that support the <code>dlfcn</code> standard). 8018280405Srpaulo 8019280405Srpaulo 8020280405Srpaulo 8021280405Srpaulo 8022280405Srpaulo<p> 8023280405Srpaulo<hr><h3><a name="pdf-package.path"><code>package.path</code></a></h3> 8024280405Srpaulo 8025280405Srpaulo 8026280405Srpaulo<p> 8027280405SrpauloThe path used by <a href="#pdf-require"><code>require</code></a> to search for a Lua loader. 8028280405Srpaulo 8029280405Srpaulo 8030280405Srpaulo<p> 8031280405SrpauloAt start-up, Lua initializes this variable with 8032280405Srpaulothe value of the environment variable <a name="pdf-LUA_PATH_5_3"><code>LUA_PATH_5_3</code></a> or 8033280405Srpaulothe environment variable <a name="pdf-LUA_PATH"><code>LUA_PATH</code></a> or 8034280405Srpaulowith a default path defined in <code>luaconf.h</code>, 8035280405Srpauloif those environment variables are not defined. 8036280405SrpauloAny "<code>;;</code>" in the value of the environment variable 8037280405Srpaulois replaced by the default path. 8038280405Srpaulo 8039280405Srpaulo 8040280405Srpaulo 8041280405Srpaulo 8042280405Srpaulo<p> 8043280405Srpaulo<hr><h3><a name="pdf-package.preload"><code>package.preload</code></a></h3> 8044280405Srpaulo 8045280405Srpaulo 8046280405Srpaulo<p> 8047280405SrpauloA table to store loaders for specific modules 8048280405Srpaulo(see <a href="#pdf-require"><code>require</code></a>). 8049280405Srpaulo 8050280405Srpaulo 8051280405Srpaulo<p> 8052280405SrpauloThis variable is only a reference to the real table; 8053280405Srpauloassignments to this variable do not change the 8054280405Srpaulotable used by <a href="#pdf-require"><code>require</code></a>. 8055280405Srpaulo 8056280405Srpaulo 8057280405Srpaulo 8058280405Srpaulo 8059280405Srpaulo<p> 8060280405Srpaulo<hr><h3><a name="pdf-package.searchers"><code>package.searchers</code></a></h3> 8061280405Srpaulo 8062280405Srpaulo 8063280405Srpaulo<p> 8064280405SrpauloA table used by <a href="#pdf-require"><code>require</code></a> to control how to load modules. 8065280405Srpaulo 8066280405Srpaulo 8067280405Srpaulo<p> 8068280405SrpauloEach entry in this table is a <em>searcher function</em>. 8069280405SrpauloWhen looking for a module, 8070280405Srpaulo<a href="#pdf-require"><code>require</code></a> calls each of these searchers in ascending order, 8071280405Srpaulowith the module name (the argument given to <a href="#pdf-require"><code>require</code></a>) as its 8072280405Srpaulosole parameter. 8073280405SrpauloThe function can return another function (the module <em>loader</em>) 8074280405Srpauloplus an extra value that will be passed to that loader, 8075280405Srpauloor a string explaining why it did not find that module 8076280405Srpaulo(or <b>nil</b> if it has nothing to say). 8077280405Srpaulo 8078280405Srpaulo 8079280405Srpaulo<p> 8080280405SrpauloLua initializes this table with four searcher functions. 8081280405Srpaulo 8082280405Srpaulo 8083280405Srpaulo<p> 8084280405SrpauloThe first searcher simply looks for a loader in the 8085280405Srpaulo<a href="#pdf-package.preload"><code>package.preload</code></a> table. 8086280405Srpaulo 8087280405Srpaulo 8088280405Srpaulo<p> 8089280405SrpauloThe second searcher looks for a loader as a Lua library, 8090280405Srpaulousing the path stored at <a href="#pdf-package.path"><code>package.path</code></a>. 8091280405SrpauloThe search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. 8092280405Srpaulo 8093280405Srpaulo 8094280405Srpaulo<p> 8095280405SrpauloThe third searcher looks for a loader as a C library, 8096280405Srpaulousing the path given by the variable <a href="#pdf-package.cpath"><code>package.cpath</code></a>. 8097280405SrpauloAgain, 8098280405Srpaulothe search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. 8099280405SrpauloFor instance, 8100280405Srpauloif the C path is the string 8101280405Srpaulo 8102280405Srpaulo<pre> 8103280405Srpaulo "./?.so;./?.dll;/usr/local/?/init.so" 8104280405Srpaulo</pre><p> 8105280405Srpaulothe searcher for module <code>foo</code> 8106280405Srpaulowill try to open the files <code>./foo.so</code>, <code>./foo.dll</code>, 8107280405Srpauloand <code>/usr/local/foo/init.so</code>, in that order. 8108280405SrpauloOnce it finds a C library, 8109280405Srpaulothis searcher first uses a dynamic link facility to link the 8110280405Srpauloapplication with the library. 8111280405SrpauloThen it tries to find a C function inside the library to 8112280405Srpaulobe used as the loader. 8113280405SrpauloThe name of this C function is the string "<code>luaopen_</code>" 8114280405Srpauloconcatenated with a copy of the module name where each dot 8115280405Srpaulois replaced by an underscore. 8116280405SrpauloMoreover, if the module name has a hyphen, 8117280405Srpauloits suffix after (and including) the first hyphen is removed. 8118280405SrpauloFor instance, if the module name is <code>a.b.c-v2.1</code>, 8119280405Srpaulothe function name will be <code>luaopen_a_b_c</code>. 8120280405Srpaulo 8121280405Srpaulo 8122280405Srpaulo<p> 8123280405SrpauloThe fourth searcher tries an <em>all-in-one loader</em>. 8124280405SrpauloIt searches the C path for a library for 8125280405Srpaulothe root name of the given module. 8126280405SrpauloFor instance, when requiring <code>a.b.c</code>, 8127280405Srpauloit will search for a C library for <code>a</code>. 8128280405SrpauloIf found, it looks into it for an open function for 8129280405Srpaulothe submodule; 8130280405Srpauloin our example, that would be <code>luaopen_a_b_c</code>. 8131280405SrpauloWith this facility, a package can pack several C submodules 8132280405Srpaulointo one single library, 8133280405Srpaulowith each submodule keeping its original open function. 8134280405Srpaulo 8135280405Srpaulo 8136280405Srpaulo<p> 8137280405SrpauloAll searchers except the first one (preload) return as the extra value 8138280405Srpaulothe file name where the module was found, 8139280405Srpauloas returned by <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. 8140280405SrpauloThe first searcher returns no extra value. 8141280405Srpaulo 8142280405Srpaulo 8143280405Srpaulo 8144280405Srpaulo 8145280405Srpaulo<p> 8146280405Srpaulo<hr><h3><a name="pdf-package.searchpath"><code>package.searchpath (name, path [, sep [, rep]])</code></a></h3> 8147280405Srpaulo 8148280405Srpaulo 8149280405Srpaulo<p> 8150280405SrpauloSearches for the given <code>name</code> in the given <code>path</code>. 8151280405Srpaulo 8152280405Srpaulo 8153280405Srpaulo<p> 8154280405SrpauloA path is a string containing a sequence of 8155280405Srpaulo<em>templates</em> separated by semicolons. 8156280405SrpauloFor each template, 8157280405Srpaulothe function replaces each interrogation mark (if any) 8158280405Srpauloin the template with a copy of <code>name</code> 8159280405Srpaulowherein all occurrences of <code>sep</code> 8160280405Srpaulo(a dot, by default) 8161280405Srpaulowere replaced by <code>rep</code> 8162280405Srpaulo(the system's directory separator, by default), 8163280405Srpauloand then tries to open the resulting file name. 8164280405Srpaulo 8165280405Srpaulo 8166280405Srpaulo<p> 8167280405SrpauloFor instance, if the path is the string 8168280405Srpaulo 8169280405Srpaulo<pre> 8170280405Srpaulo "./?.lua;./?.lc;/usr/local/?/init.lua" 8171280405Srpaulo</pre><p> 8172280405Srpaulothe search for the name <code>foo.a</code> 8173280405Srpaulowill try to open the files 8174280405Srpaulo<code>./foo/a.lua</code>, <code>./foo/a.lc</code>, and 8175280405Srpaulo<code>/usr/local/foo/a/init.lua</code>, in that order. 8176280405Srpaulo 8177280405Srpaulo 8178280405Srpaulo<p> 8179280405SrpauloReturns the resulting name of the first file that it can 8180280405Srpauloopen in read mode (after closing the file), 8181280405Srpauloor <b>nil</b> plus an error message if none succeeds. 8182280405Srpaulo(This error message lists all file names it tried to open.) 8183280405Srpaulo 8184280405Srpaulo 8185280405Srpaulo 8186280405Srpaulo 8187280405Srpaulo 8188280405Srpaulo 8189280405Srpaulo 8190280405Srpaulo<h2>6.4 – <a name="6.4">String Manipulation</a></h2> 8191280405Srpaulo 8192280405Srpaulo<p> 8193280405SrpauloThis library provides generic functions for string manipulation, 8194280405Srpaulosuch as finding and extracting substrings, and pattern matching. 8195280405SrpauloWhen indexing a string in Lua, the first character is at position 1 8196280405Srpaulo(not at 0, as in C). 8197280405SrpauloIndices are allowed to be negative and are interpreted as indexing backwards, 8198280405Srpaulofrom the end of the string. 8199280405SrpauloThus, the last character is at position -1, and so on. 8200280405Srpaulo 8201280405Srpaulo 8202280405Srpaulo<p> 8203280405SrpauloThe string library provides all its functions inside the table 8204280405Srpaulo<a name="pdf-string"><code>string</code></a>. 8205280405SrpauloIt also sets a metatable for strings 8206280405Srpaulowhere the <code>__index</code> field points to the <code>string</code> table. 8207280405SrpauloTherefore, you can use the string functions in object-oriented style. 8208280405SrpauloFor instance, <code>string.byte(s,i)</code> 8209280405Srpaulocan be written as <code>s:byte(i)</code>. 8210280405Srpaulo 8211280405Srpaulo 8212280405Srpaulo<p> 8213280405SrpauloThe string library assumes one-byte character encodings. 8214280405Srpaulo 8215280405Srpaulo 8216280405Srpaulo<p> 8217280405Srpaulo<hr><h3><a name="pdf-string.byte"><code>string.byte (s [, i [, j]])</code></a></h3> 8218326344SimpReturns the internal numeric codes of the characters <code>s[i]</code>, 8219280405Srpaulo<code>s[i+1]</code>, ..., <code>s[j]</code>. 8220280405SrpauloThe default value for <code>i</code> is 1; 8221280405Srpaulothe default value for <code>j</code> is <code>i</code>. 8222280405SrpauloThese indices are corrected 8223280405Srpaulofollowing the same rules of function <a href="#pdf-string.sub"><code>string.sub</code></a>. 8224280405Srpaulo 8225280405Srpaulo 8226280405Srpaulo<p> 8227326344SimpNumeric codes are not necessarily portable across platforms. 8228280405Srpaulo 8229280405Srpaulo 8230280405Srpaulo 8231280405Srpaulo 8232280405Srpaulo<p> 8233280405Srpaulo<hr><h3><a name="pdf-string.char"><code>string.char (···)</code></a></h3> 8234280405SrpauloReceives zero or more integers. 8235280405SrpauloReturns a string with length equal to the number of arguments, 8236326344Simpin which each character has the internal numeric code equal 8237280405Srpauloto its corresponding argument. 8238280405Srpaulo 8239280405Srpaulo 8240280405Srpaulo<p> 8241326344SimpNumeric codes are not necessarily portable across platforms. 8242280405Srpaulo 8243280405Srpaulo 8244280405Srpaulo 8245280405Srpaulo 8246280405Srpaulo<p> 8247280405Srpaulo<hr><h3><a name="pdf-string.dump"><code>string.dump (function [, strip])</code></a></h3> 8248280405Srpaulo 8249280405Srpaulo 8250280405Srpaulo<p> 8251280405SrpauloReturns a string containing a binary representation 8252280405Srpaulo(a <em>binary chunk</em>) 8253280405Srpauloof the given function, 8254280405Srpauloso that a later <a href="#pdf-load"><code>load</code></a> on this string returns 8255280405Srpauloa copy of the function (but with new upvalues). 8256280405SrpauloIf <code>strip</code> is a true value, 8257326344Simpthe binary representation may not include all debug information 8258326344Simpabout the function, 8259326344Simpto save space. 8260280405Srpaulo 8261280405Srpaulo 8262280405Srpaulo<p> 8263280405SrpauloFunctions with upvalues have only their number of upvalues saved. 8264280405SrpauloWhen (re)loaded, 8265280405Srpaulothose upvalues receive fresh instances containing <b>nil</b>. 8266280405Srpaulo(You can use the debug library to serialize 8267280405Srpauloand reload the upvalues of a function 8268280405Srpauloin a way adequate to your needs.) 8269280405Srpaulo 8270280405Srpaulo 8271280405Srpaulo 8272280405Srpaulo 8273280405Srpaulo<p> 8274280405Srpaulo<hr><h3><a name="pdf-string.find"><code>string.find (s, pattern [, init [, plain]])</code></a></h3> 8275280405Srpaulo 8276280405Srpaulo 8277280405Srpaulo<p> 8278280405SrpauloLooks for the first match of 8279280405Srpaulo<code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) in the string <code>s</code>. 8280280405SrpauloIf it finds a match, then <code>find</code> returns the indices of <code>s</code> 8281280405Srpaulowhere this occurrence starts and ends; 8282280405Srpaulootherwise, it returns <b>nil</b>. 8283326344SimpA third, optional numeric argument <code>init</code> specifies 8284280405Srpaulowhere to start the search; 8285280405Srpauloits default value is 1 and can be negative. 8286280405SrpauloA value of <b>true</b> as a fourth, optional argument <code>plain</code> 8287280405Srpauloturns off the pattern matching facilities, 8288280405Srpauloso the function does a plain "find substring" operation, 8289280405Srpaulowith no characters in <code>pattern</code> being considered magic. 8290280405SrpauloNote that if <code>plain</code> is given, then <code>init</code> must be given as well. 8291280405Srpaulo 8292280405Srpaulo 8293280405Srpaulo<p> 8294280405SrpauloIf the pattern has captures, 8295280405Srpaulothen in a successful match 8296280405Srpaulothe captured values are also returned, 8297280405Srpauloafter the two indices. 8298280405Srpaulo 8299280405Srpaulo 8300280405Srpaulo 8301280405Srpaulo 8302280405Srpaulo<p> 8303280405Srpaulo<hr><h3><a name="pdf-string.format"><code>string.format (formatstring, ···)</code></a></h3> 8304280405Srpaulo 8305280405Srpaulo 8306280405Srpaulo<p> 8307280405SrpauloReturns a formatted version of its variable number of arguments 8308280405Srpaulofollowing the description given in its first argument (which must be a string). 8309280405SrpauloThe format string follows the same rules as the ISO C function <code>sprintf</code>. 8310280405SrpauloThe only differences are that the options/modifiers 8311280405Srpaulo<code>*</code>, <code>h</code>, <code>L</code>, <code>l</code>, <code>n</code>, 8312280405Srpauloand <code>p</code> are not supported 8313280405Srpauloand that there is an extra option, <code>q</code>. 8314326344Simp 8315326344Simp 8316326344Simp<p> 8317280405SrpauloThe <code>q</code> option formats a string between double quotes, 8318280405Srpaulousing escape sequences when necessary to ensure that 8319280405Srpauloit can safely be read back by the Lua interpreter. 8320280405SrpauloFor instance, the call 8321280405Srpaulo 8322280405Srpaulo<pre> 8323280405Srpaulo string.format('%q', 'a string with "quotes" and \n new line') 8324280405Srpaulo</pre><p> 8325280405Srpaulomay produce the string: 8326280405Srpaulo 8327280405Srpaulo<pre> 8328280405Srpaulo "a string with \"quotes\" and \ 8329280405Srpaulo new line" 8330280405Srpaulo</pre> 8331280405Srpaulo 8332280405Srpaulo<p> 8333280405SrpauloOptions 8334326344Simp<code>A</code>, <code>a</code>, <code>E</code>, <code>e</code>, <code>f</code>, 8335280405Srpaulo<code>G</code>, and <code>g</code> all expect a number as argument. 8336280405SrpauloOptions <code>c</code>, <code>d</code>, 8337280405Srpaulo<code>i</code>, <code>o</code>, <code>u</code>, <code>X</code>, and <code>x</code> 8338280405Srpauloexpect an integer. 8339326344SimpWhen Lua is compiled with a C89 compiler, 8340326344Simpoptions <code>A</code> and <code>a</code> (hexadecimal floats) 8341326344Simpdo not support any modifier (flags, width, length). 8342326344Simp 8343326344Simp 8344326344Simp<p> 8345326344SimpOption <code>s</code> expects a string; 8346326344Simpif its argument is not a string, 8347280405Srpauloit is converted to one following the same rules of <a href="#pdf-tostring"><code>tostring</code></a>. 8348326344SimpIf the option has any modifier (flags, width, length), 8349326344Simpthe string argument should not contain embedded zeros. 8350280405Srpaulo 8351280405Srpaulo 8352280405Srpaulo 8353280405Srpaulo 8354280405Srpaulo<p> 8355280405Srpaulo<hr><h3><a name="pdf-string.gmatch"><code>string.gmatch (s, pattern)</code></a></h3> 8356280405SrpauloReturns an iterator function that, 8357280405Srpauloeach time it is called, 8358280405Srpauloreturns the next captures from <code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) 8359280405Srpauloover the string <code>s</code>. 8360280405SrpauloIf <code>pattern</code> specifies no captures, 8361280405Srpaulothen the whole match is produced in each call. 8362280405Srpaulo 8363280405Srpaulo 8364280405Srpaulo<p> 8365280405SrpauloAs an example, the following loop 8366280405Srpaulowill iterate over all the words from string <code>s</code>, 8367280405Srpauloprinting one per line: 8368280405Srpaulo 8369280405Srpaulo<pre> 8370280405Srpaulo s = "hello world from Lua" 8371280405Srpaulo for w in string.gmatch(s, "%a+") do 8372280405Srpaulo print(w) 8373280405Srpaulo end 8374280405Srpaulo</pre><p> 8375280405SrpauloThe next example collects all pairs <code>key=value</code> from the 8376280405Srpaulogiven string into a table: 8377280405Srpaulo 8378280405Srpaulo<pre> 8379280405Srpaulo t = {} 8380280405Srpaulo s = "from=world, to=Lua" 8381280405Srpaulo for k, v in string.gmatch(s, "(%w+)=(%w+)") do 8382280405Srpaulo t[k] = v 8383280405Srpaulo end 8384280405Srpaulo</pre> 8385280405Srpaulo 8386280405Srpaulo<p> 8387280405SrpauloFor this function, a caret '<code>^</code>' at the start of a pattern does not 8388280405Srpaulowork as an anchor, as this would prevent the iteration. 8389280405Srpaulo 8390280405Srpaulo 8391280405Srpaulo 8392280405Srpaulo 8393280405Srpaulo<p> 8394280405Srpaulo<hr><h3><a name="pdf-string.gsub"><code>string.gsub (s, pattern, repl [, n])</code></a></h3> 8395280405SrpauloReturns a copy of <code>s</code> 8396280405Srpauloin which all (or the first <code>n</code>, if given) 8397280405Srpaulooccurrences of the <code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) have been 8398280405Srpauloreplaced by a replacement string specified by <code>repl</code>, 8399280405Srpaulowhich can be a string, a table, or a function. 8400280405Srpaulo<code>gsub</code> also returns, as its second value, 8401280405Srpaulothe total number of matches that occurred. 8402280405SrpauloThe name <code>gsub</code> comes from <em>Global SUBstitution</em>. 8403280405Srpaulo 8404280405Srpaulo 8405280405Srpaulo<p> 8406280405SrpauloIf <code>repl</code> is a string, then its value is used for replacement. 8407280405SrpauloThe character <code>%</code> works as an escape character: 8408280405Srpauloany sequence in <code>repl</code> of the form <code>%<em>d</em></code>, 8409280405Srpaulowith <em>d</em> between 1 and 9, 8410280405Srpaulostands for the value of the <em>d</em>-th captured substring. 8411280405SrpauloThe sequence <code>%0</code> stands for the whole match. 8412280405SrpauloThe sequence <code>%%</code> stands for a single <code>%</code>. 8413280405Srpaulo 8414280405Srpaulo 8415280405Srpaulo<p> 8416280405SrpauloIf <code>repl</code> is a table, then the table is queried for every match, 8417280405Srpaulousing the first capture as the key. 8418280405Srpaulo 8419280405Srpaulo 8420280405Srpaulo<p> 8421280405SrpauloIf <code>repl</code> is a function, then this function is called every time a 8422280405Srpaulomatch occurs, with all captured substrings passed as arguments, 8423280405Srpauloin order. 8424280405Srpaulo 8425280405Srpaulo 8426280405Srpaulo<p> 8427280405SrpauloIn any case, 8428280405Srpauloif the pattern specifies no captures, 8429280405Srpaulothen it behaves as if the whole pattern was inside a capture. 8430280405Srpaulo 8431280405Srpaulo 8432280405Srpaulo<p> 8433280405SrpauloIf the value returned by the table query or by the function call 8434280405Srpaulois a string or a number, 8435280405Srpaulothen it is used as the replacement string; 8436280405Srpaulootherwise, if it is <b>false</b> or <b>nil</b>, 8437280405Srpaulothen there is no replacement 8438280405Srpaulo(that is, the original match is kept in the string). 8439280405Srpaulo 8440280405Srpaulo 8441280405Srpaulo<p> 8442280405SrpauloHere are some examples: 8443280405Srpaulo 8444280405Srpaulo<pre> 8445280405Srpaulo x = string.gsub("hello world", "(%w+)", "%1 %1") 8446280405Srpaulo --> x="hello hello world world" 8447280405Srpaulo 8448280405Srpaulo x = string.gsub("hello world", "%w+", "%0 %0", 1) 8449280405Srpaulo --> x="hello hello world" 8450280405Srpaulo 8451280405Srpaulo x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1") 8452280405Srpaulo --> x="world hello Lua from" 8453280405Srpaulo 8454280405Srpaulo x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv) 8455280405Srpaulo --> x="home = /home/roberto, user = roberto" 8456280405Srpaulo 8457280405Srpaulo x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s) 8458280405Srpaulo return load(s)() 8459280405Srpaulo end) 8460280405Srpaulo --> x="4+5 = 9" 8461280405Srpaulo 8462280405Srpaulo local t = {name="lua", version="5.3"} 8463280405Srpaulo x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t) 8464280405Srpaulo --> x="lua-5.3.tar.gz" 8465280405Srpaulo</pre> 8466280405Srpaulo 8467280405Srpaulo 8468280405Srpaulo 8469280405Srpaulo<p> 8470280405Srpaulo<hr><h3><a name="pdf-string.len"><code>string.len (s)</code></a></h3> 8471280405SrpauloReceives a string and returns its length. 8472280405SrpauloThe empty string <code>""</code> has length 0. 8473280405SrpauloEmbedded zeros are counted, 8474280405Srpauloso <code>"a\000bc\000"</code> has length 5. 8475280405Srpaulo 8476280405Srpaulo 8477280405Srpaulo 8478280405Srpaulo 8479280405Srpaulo<p> 8480280405Srpaulo<hr><h3><a name="pdf-string.lower"><code>string.lower (s)</code></a></h3> 8481280405SrpauloReceives a string and returns a copy of this string with all 8482280405Srpaulouppercase letters changed to lowercase. 8483280405SrpauloAll other characters are left unchanged. 8484280405SrpauloThe definition of what an uppercase letter is depends on the current locale. 8485280405Srpaulo 8486280405Srpaulo 8487280405Srpaulo 8488280405Srpaulo 8489280405Srpaulo<p> 8490280405Srpaulo<hr><h3><a name="pdf-string.match"><code>string.match (s, pattern [, init])</code></a></h3> 8491280405SrpauloLooks for the first <em>match</em> of 8492280405Srpaulo<code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) in the string <code>s</code>. 8493280405SrpauloIf it finds one, then <code>match</code> returns 8494280405Srpaulothe captures from the pattern; 8495280405Srpaulootherwise it returns <b>nil</b>. 8496280405SrpauloIf <code>pattern</code> specifies no captures, 8497280405Srpaulothen the whole match is returned. 8498326344SimpA third, optional numeric argument <code>init</code> specifies 8499280405Srpaulowhere to start the search; 8500280405Srpauloits default value is 1 and can be negative. 8501280405Srpaulo 8502280405Srpaulo 8503280405Srpaulo 8504280405Srpaulo 8505280405Srpaulo<p> 8506280405Srpaulo<hr><h3><a name="pdf-string.pack"><code>string.pack (fmt, v1, v2, ···)</code></a></h3> 8507280405Srpaulo 8508280405Srpaulo 8509280405Srpaulo<p> 8510280405SrpauloReturns a binary string containing the values <code>v1</code>, <code>v2</code>, etc. 8511280405Srpaulopacked (that is, serialized in binary form) 8512326344Simpaccording to the format string <code>fmt</code> (see <a href="#6.4.2">§6.4.2</a>). 8513280405Srpaulo 8514280405Srpaulo 8515280405Srpaulo 8516280405Srpaulo 8517280405Srpaulo<p> 8518280405Srpaulo<hr><h3><a name="pdf-string.packsize"><code>string.packsize (fmt)</code></a></h3> 8519280405Srpaulo 8520280405Srpaulo 8521280405Srpaulo<p> 8522280405SrpauloReturns the size of a string resulting from <a href="#pdf-string.pack"><code>string.pack</code></a> 8523280405Srpaulowith the given format. 8524280405SrpauloThe format string cannot have the variable-length options 8525280405Srpaulo'<code>s</code>' or '<code>z</code>' (see <a href="#6.4.2">§6.4.2</a>). 8526280405Srpaulo 8527280405Srpaulo 8528280405Srpaulo 8529280405Srpaulo 8530280405Srpaulo<p> 8531280405Srpaulo<hr><h3><a name="pdf-string.rep"><code>string.rep (s, n [, sep])</code></a></h3> 8532280405SrpauloReturns a string that is the concatenation of <code>n</code> copies of 8533280405Srpaulothe string <code>s</code> separated by the string <code>sep</code>. 8534280405SrpauloThe default value for <code>sep</code> is the empty string 8535280405Srpaulo(that is, no separator). 8536280405SrpauloReturns the empty string if <code>n</code> is not positive. 8537280405Srpaulo 8538280405Srpaulo 8539326344Simp<p> 8540326344Simp(Note that it is very easy to exhaust the memory of your machine 8541326344Simpwith a single call to this function.) 8542280405Srpaulo 8543280405Srpaulo 8544326344Simp 8545326344Simp 8546280405Srpaulo<p> 8547280405Srpaulo<hr><h3><a name="pdf-string.reverse"><code>string.reverse (s)</code></a></h3> 8548280405SrpauloReturns a string that is the string <code>s</code> reversed. 8549280405Srpaulo 8550280405Srpaulo 8551280405Srpaulo 8552280405Srpaulo 8553280405Srpaulo<p> 8554280405Srpaulo<hr><h3><a name="pdf-string.sub"><code>string.sub (s, i [, j])</code></a></h3> 8555280405SrpauloReturns the substring of <code>s</code> that 8556280405Srpaulostarts at <code>i</code> and continues until <code>j</code>; 8557280405Srpaulo<code>i</code> and <code>j</code> can be negative. 8558280405SrpauloIf <code>j</code> is absent, then it is assumed to be equal to -1 8559280405Srpaulo(which is the same as the string length). 8560280405SrpauloIn particular, 8561280405Srpaulothe call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code> 8562280405Srpaulowith length <code>j</code>, 8563326344Simpand <code>string.sub(s, -i)</code> (for a positive <code>i</code>) 8564326344Simpreturns a suffix of <code>s</code> 8565280405Srpaulowith length <code>i</code>. 8566280405Srpaulo 8567280405Srpaulo 8568280405Srpaulo<p> 8569280405SrpauloIf, after the translation of negative indices, 8570280405Srpaulo<code>i</code> is less than 1, 8571280405Srpauloit is corrected to 1. 8572280405SrpauloIf <code>j</code> is greater than the string length, 8573280405Srpauloit is corrected to that length. 8574280405SrpauloIf, after these corrections, 8575280405Srpaulo<code>i</code> is greater than <code>j</code>, 8576280405Srpaulothe function returns the empty string. 8577280405Srpaulo 8578280405Srpaulo 8579280405Srpaulo 8580280405Srpaulo 8581280405Srpaulo<p> 8582280405Srpaulo<hr><h3><a name="pdf-string.unpack"><code>string.unpack (fmt, s [, pos])</code></a></h3> 8583280405Srpaulo 8584280405Srpaulo 8585280405Srpaulo<p> 8586280405SrpauloReturns the values packed in string <code>s</code> (see <a href="#pdf-string.pack"><code>string.pack</code></a>) 8587280405Srpauloaccording to the format string <code>fmt</code> (see <a href="#6.4.2">§6.4.2</a>). 8588280405SrpauloAn optional <code>pos</code> marks where 8589280405Srpauloto start reading in <code>s</code> (default is 1). 8590280405SrpauloAfter the read values, 8591280405Srpaulothis function also returns the index of the first unread byte in <code>s</code>. 8592280405Srpaulo 8593280405Srpaulo 8594280405Srpaulo 8595280405Srpaulo 8596280405Srpaulo<p> 8597280405Srpaulo<hr><h3><a name="pdf-string.upper"><code>string.upper (s)</code></a></h3> 8598280405SrpauloReceives a string and returns a copy of this string with all 8599280405Srpaulolowercase letters changed to uppercase. 8600280405SrpauloAll other characters are left unchanged. 8601280405SrpauloThe definition of what a lowercase letter is depends on the current locale. 8602280405Srpaulo 8603280405Srpaulo 8604280405Srpaulo 8605280405Srpaulo 8606280405Srpaulo 8607280405Srpaulo<h3>6.4.1 – <a name="6.4.1">Patterns</a></h3> 8608280405Srpaulo 8609280405Srpaulo<p> 8610280405SrpauloPatterns in Lua are described by regular strings, 8611280405Srpaulowhich are interpreted as patterns by the pattern-matching functions 8612280405Srpaulo<a href="#pdf-string.find"><code>string.find</code></a>, 8613280405Srpaulo<a href="#pdf-string.gmatch"><code>string.gmatch</code></a>, 8614280405Srpaulo<a href="#pdf-string.gsub"><code>string.gsub</code></a>, 8615280405Srpauloand <a href="#pdf-string.match"><code>string.match</code></a>. 8616280405SrpauloThis section describes the syntax and the meaning 8617280405Srpaulo(that is, what they match) of these strings. 8618280405Srpaulo 8619280405Srpaulo 8620280405Srpaulo 8621280405Srpaulo<h4>Character Class:</h4><p> 8622280405SrpauloA <em>character class</em> is used to represent a set of characters. 8623280405SrpauloThe following combinations are allowed in describing a character class: 8624280405Srpaulo 8625280405Srpaulo<ul> 8626280405Srpaulo 8627280405Srpaulo<li><b><em>x</em>: </b> 8628280405Srpaulo(where <em>x</em> is not one of the <em>magic characters</em> 8629280405Srpaulo<code>^$()%.[]*+-?</code>) 8630280405Srpaulorepresents the character <em>x</em> itself. 8631280405Srpaulo</li> 8632280405Srpaulo 8633280405Srpaulo<li><b><code>.</code>: </b> (a dot) represents all characters.</li> 8634280405Srpaulo 8635280405Srpaulo<li><b><code>%a</code>: </b> represents all letters.</li> 8636280405Srpaulo 8637280405Srpaulo<li><b><code>%c</code>: </b> represents all control characters.</li> 8638280405Srpaulo 8639280405Srpaulo<li><b><code>%d</code>: </b> represents all digits.</li> 8640280405Srpaulo 8641280405Srpaulo<li><b><code>%g</code>: </b> represents all printable characters except space.</li> 8642280405Srpaulo 8643280405Srpaulo<li><b><code>%l</code>: </b> represents all lowercase letters.</li> 8644280405Srpaulo 8645280405Srpaulo<li><b><code>%p</code>: </b> represents all punctuation characters.</li> 8646280405Srpaulo 8647280405Srpaulo<li><b><code>%s</code>: </b> represents all space characters.</li> 8648280405Srpaulo 8649280405Srpaulo<li><b><code>%u</code>: </b> represents all uppercase letters.</li> 8650280405Srpaulo 8651280405Srpaulo<li><b><code>%w</code>: </b> represents all alphanumeric characters.</li> 8652280405Srpaulo 8653280405Srpaulo<li><b><code>%x</code>: </b> represents all hexadecimal digits.</li> 8654280405Srpaulo 8655280405Srpaulo<li><b><code>%<em>x</em></code>: </b> (where <em>x</em> is any non-alphanumeric character) 8656280405Srpaulorepresents the character <em>x</em>. 8657280405SrpauloThis is the standard way to escape the magic characters. 8658280405SrpauloAny non-alphanumeric character 8659326344Simp(including all punctuation characters, even the non-magical) 8660280405Srpaulocan be preceded by a '<code>%</code>' 8661280405Srpaulowhen used to represent itself in a pattern. 8662280405Srpaulo</li> 8663280405Srpaulo 8664280405Srpaulo<li><b><code>[<em>set</em>]</code>: </b> 8665280405Srpaulorepresents the class which is the union of all 8666280405Srpaulocharacters in <em>set</em>. 8667280405SrpauloA range of characters can be specified by 8668280405Srpauloseparating the end characters of the range, 8669280405Srpauloin ascending order, with a '<code>-</code>'. 8670280405SrpauloAll classes <code>%</code><em>x</em> described above can also be used as 8671280405Srpaulocomponents in <em>set</em>. 8672280405SrpauloAll other characters in <em>set</em> represent themselves. 8673280405SrpauloFor example, <code>[%w_]</code> (or <code>[_%w]</code>) 8674280405Srpaulorepresents all alphanumeric characters plus the underscore, 8675280405Srpaulo<code>[0-7]</code> represents the octal digits, 8676280405Srpauloand <code>[0-7%l%-]</code> represents the octal digits plus 8677280405Srpaulothe lowercase letters plus the '<code>-</code>' character. 8678280405Srpaulo 8679280405Srpaulo 8680280405Srpaulo<p> 8681326344SimpYou can put a closing square bracket in a set 8682326344Simpby positioning it as the first character in the set. 8683326344SimpYou can put an hyphen in a set 8684326344Simpby positioning it as the first or the last character in the set. 8685326344Simp(You can also use an escape for both cases.) 8686326344Simp 8687326344Simp 8688326344Simp<p> 8689280405SrpauloThe interaction between ranges and classes is not defined. 8690280405SrpauloTherefore, patterns like <code>[%a-z]</code> or <code>[a-%%]</code> 8691280405Srpaulohave no meaning. 8692280405Srpaulo</li> 8693280405Srpaulo 8694280405Srpaulo<li><b><code>[^<em>set</em>]</code>: </b> 8695280405Srpaulorepresents the complement of <em>set</em>, 8696280405Srpaulowhere <em>set</em> is interpreted as above. 8697280405Srpaulo</li> 8698280405Srpaulo 8699280405Srpaulo</ul><p> 8700280405SrpauloFor all classes represented by single letters (<code>%a</code>, <code>%c</code>, etc.), 8701280405Srpaulothe corresponding uppercase letter represents the complement of the class. 8702280405SrpauloFor instance, <code>%S</code> represents all non-space characters. 8703280405Srpaulo 8704280405Srpaulo 8705280405Srpaulo<p> 8706280405SrpauloThe definitions of letter, space, and other character groups 8707280405Srpaulodepend on the current locale. 8708280405SrpauloIn particular, the class <code>[a-z]</code> may not be equivalent to <code>%l</code>. 8709280405Srpaulo 8710280405Srpaulo 8711280405Srpaulo 8712280405Srpaulo 8713280405Srpaulo 8714280405Srpaulo<h4>Pattern Item:</h4><p> 8715280405SrpauloA <em>pattern item</em> can be 8716280405Srpaulo 8717280405Srpaulo<ul> 8718280405Srpaulo 8719280405Srpaulo<li> 8720280405Srpauloa single character class, 8721280405Srpaulowhich matches any single character in the class; 8722280405Srpaulo</li> 8723280405Srpaulo 8724280405Srpaulo<li> 8725280405Srpauloa single character class followed by '<code>*</code>', 8726280405Srpaulowhich matches zero or more repetitions of characters in the class. 8727280405SrpauloThese repetition items will always match the longest possible sequence; 8728280405Srpaulo</li> 8729280405Srpaulo 8730280405Srpaulo<li> 8731280405Srpauloa single character class followed by '<code>+</code>', 8732280405Srpaulowhich matches one or more repetitions of characters in the class. 8733280405SrpauloThese repetition items will always match the longest possible sequence; 8734280405Srpaulo</li> 8735280405Srpaulo 8736280405Srpaulo<li> 8737280405Srpauloa single character class followed by '<code>-</code>', 8738280405Srpaulowhich also matches zero or more repetitions of characters in the class. 8739280405SrpauloUnlike '<code>*</code>', 8740280405Srpaulothese repetition items will always match the shortest possible sequence; 8741280405Srpaulo</li> 8742280405Srpaulo 8743280405Srpaulo<li> 8744280405Srpauloa single character class followed by '<code>?</code>', 8745280405Srpaulowhich matches zero or one occurrence of a character in the class. 8746280405SrpauloIt always matches one occurrence if possible; 8747280405Srpaulo</li> 8748280405Srpaulo 8749280405Srpaulo<li> 8750280405Srpaulo<code>%<em>n</em></code>, for <em>n</em> between 1 and 9; 8751280405Srpaulosuch item matches a substring equal to the <em>n</em>-th captured string 8752280405Srpaulo(see below); 8753280405Srpaulo</li> 8754280405Srpaulo 8755280405Srpaulo<li> 8756280405Srpaulo<code>%b<em>xy</em></code>, where <em>x</em> and <em>y</em> are two distinct characters; 8757280405Srpaulosuch item matches strings that start with <em>x</em>, end with <em>y</em>, 8758280405Srpauloand where the <em>x</em> and <em>y</em> are <em>balanced</em>. 8759280405SrpauloThis means that, if one reads the string from left to right, 8760280405Srpaulocounting <em>+1</em> for an <em>x</em> and <em>-1</em> for a <em>y</em>, 8761280405Srpaulothe ending <em>y</em> is the first <em>y</em> where the count reaches 0. 8762280405SrpauloFor instance, the item <code>%b()</code> matches expressions with 8763280405Srpaulobalanced parentheses. 8764280405Srpaulo</li> 8765280405Srpaulo 8766280405Srpaulo<li> 8767280405Srpaulo<code>%f[<em>set</em>]</code>, a <em>frontier pattern</em>; 8768280405Srpaulosuch item matches an empty string at any position such that 8769280405Srpaulothe next character belongs to <em>set</em> 8770280405Srpauloand the previous character does not belong to <em>set</em>. 8771280405SrpauloThe set <em>set</em> is interpreted as previously described. 8772280405SrpauloThe beginning and the end of the subject are handled as if 8773280405Srpaulothey were the character '<code>\0</code>'. 8774280405Srpaulo</li> 8775280405Srpaulo 8776280405Srpaulo</ul> 8777280405Srpaulo 8778280405Srpaulo 8779280405Srpaulo 8780280405Srpaulo 8781280405Srpaulo<h4>Pattern:</h4><p> 8782280405SrpauloA <em>pattern</em> is a sequence of pattern items. 8783280405SrpauloA caret '<code>^</code>' at the beginning of a pattern anchors the match at the 8784280405Srpaulobeginning of the subject string. 8785280405SrpauloA '<code>$</code>' at the end of a pattern anchors the match at the 8786280405Srpauloend of the subject string. 8787280405SrpauloAt other positions, 8788280405Srpaulo'<code>^</code>' and '<code>$</code>' have no special meaning and represent themselves. 8789280405Srpaulo 8790280405Srpaulo 8791280405Srpaulo 8792280405Srpaulo 8793280405Srpaulo 8794280405Srpaulo<h4>Captures:</h4><p> 8795280405SrpauloA pattern can contain sub-patterns enclosed in parentheses; 8796280405Srpaulothey describe <em>captures</em>. 8797280405SrpauloWhen a match succeeds, the substrings of the subject string 8798280405Srpaulothat match captures are stored (<em>captured</em>) for future use. 8799280405SrpauloCaptures are numbered according to their left parentheses. 8800280405SrpauloFor instance, in the pattern <code>"(a*(.)%w(%s*))"</code>, 8801280405Srpaulothe part of the string matching <code>"a*(.)%w(%s*)"</code> is 8802280405Srpaulostored as the first capture (and therefore has number 1); 8803280405Srpaulothe character matching "<code>.</code>" is captured with number 2, 8804280405Srpauloand the part matching "<code>%s*</code>" has number 3. 8805280405Srpaulo 8806280405Srpaulo 8807280405Srpaulo<p> 8808280405SrpauloAs a special case, the empty capture <code>()</code> captures 8809280405Srpaulothe current string position (a number). 8810280405SrpauloFor instance, if we apply the pattern <code>"()aa()"</code> on the 8811280405Srpaulostring <code>"flaaap"</code>, there will be two captures: 3 and 5. 8812280405Srpaulo 8813280405Srpaulo 8814280405Srpaulo 8815280405Srpaulo 8816280405Srpaulo 8817280405Srpaulo 8818280405Srpaulo 8819280405Srpaulo<h3>6.4.2 – <a name="6.4.2">Format Strings for Pack and Unpack</a></h3> 8820280405Srpaulo 8821280405Srpaulo<p> 8822280405SrpauloThe first argument to <a href="#pdf-string.pack"><code>string.pack</code></a>, 8823280405Srpaulo<a href="#pdf-string.packsize"><code>string.packsize</code></a>, and <a href="#pdf-string.unpack"><code>string.unpack</code></a> 8824280405Srpaulois a format string, 8825280405Srpaulowhich describes the layout of the structure being created or read. 8826280405Srpaulo 8827280405Srpaulo 8828280405Srpaulo<p> 8829280405SrpauloA format string is a sequence of conversion options. 8830280405SrpauloThe conversion options are as follows: 8831280405Srpaulo 8832280405Srpaulo<ul> 8833280405Srpaulo<li><b><code><</code>: </b>sets little endian</li> 8834280405Srpaulo<li><b><code>></code>: </b>sets big endian</li> 8835280405Srpaulo<li><b><code>=</code>: </b>sets native endian</li> 8836280405Srpaulo<li><b><code>![<em>n</em>]</code>: </b>sets maximum alignment to <code>n</code> 8837280405Srpaulo(default is native alignment)</li> 8838280405Srpaulo<li><b><code>b</code>: </b>a signed byte (<code>char</code>)</li> 8839280405Srpaulo<li><b><code>B</code>: </b>an unsigned byte (<code>char</code>)</li> 8840280405Srpaulo<li><b><code>h</code>: </b>a signed <code>short</code> (native size)</li> 8841280405Srpaulo<li><b><code>H</code>: </b>an unsigned <code>short</code> (native size)</li> 8842280405Srpaulo<li><b><code>l</code>: </b>a signed <code>long</code> (native size)</li> 8843280405Srpaulo<li><b><code>L</code>: </b>an unsigned <code>long</code> (native size)</li> 8844280405Srpaulo<li><b><code>j</code>: </b>a <code>lua_Integer</code></li> 8845280405Srpaulo<li><b><code>J</code>: </b>a <code>lua_Unsigned</code></li> 8846280405Srpaulo<li><b><code>T</code>: </b>a <code>size_t</code> (native size)</li> 8847280405Srpaulo<li><b><code>i[<em>n</em>]</code>: </b>a signed <code>int</code> with <code>n</code> bytes 8848280405Srpaulo(default is native size)</li> 8849280405Srpaulo<li><b><code>I[<em>n</em>]</code>: </b>an unsigned <code>int</code> with <code>n</code> bytes 8850280405Srpaulo(default is native size)</li> 8851280405Srpaulo<li><b><code>f</code>: </b>a <code>float</code> (native size)</li> 8852280405Srpaulo<li><b><code>d</code>: </b>a <code>double</code> (native size)</li> 8853280405Srpaulo<li><b><code>n</code>: </b>a <code>lua_Number</code></li> 8854280405Srpaulo<li><b><code>c<em>n</em></code>: </b>a fixed-sized string with <code>n</code> bytes</li> 8855280405Srpaulo<li><b><code>z</code>: </b>a zero-terminated string</li> 8856280405Srpaulo<li><b><code>s[<em>n</em>]</code>: </b>a string preceded by its length 8857280405Srpaulocoded as an unsigned integer with <code>n</code> bytes 8858280405Srpaulo(default is a <code>size_t</code>)</li> 8859280405Srpaulo<li><b><code>x</code>: </b>one byte of padding</li> 8860280405Srpaulo<li><b><code>X<em>op</em></code>: </b>an empty item that aligns 8861280405Srpauloaccording to option <code>op</code> 8862280405Srpaulo(which is otherwise ignored)</li> 8863280405Srpaulo<li><b>'<code> </code>': </b>(empty space) ignored</li> 8864280405Srpaulo</ul><p> 8865280405Srpaulo(A "<code>[<em>n</em>]</code>" means an optional integral numeral.) 8866280405SrpauloExcept for padding, spaces, and configurations 8867280405Srpaulo(options "<code>xX <=>!</code>"), 8868280405Srpauloeach option corresponds to an argument (in <a href="#pdf-string.pack"><code>string.pack</code></a>) 8869280405Srpauloor a result (in <a href="#pdf-string.unpack"><code>string.unpack</code></a>). 8870280405Srpaulo 8871280405Srpaulo 8872280405Srpaulo<p> 8873280405SrpauloFor options "<code>!<em>n</em></code>", "<code>s<em>n</em></code>", "<code>i<em>n</em></code>", and "<code>I<em>n</em></code>", 8874280405Srpaulo<code>n</code> can be any integer between 1 and 16. 8875280405SrpauloAll integral options check overflows; 8876280405Srpaulo<a href="#pdf-string.pack"><code>string.pack</code></a> checks whether the given value fits in the given size; 8877280405Srpaulo<a href="#pdf-string.unpack"><code>string.unpack</code></a> checks whether the read value fits in a Lua integer. 8878280405Srpaulo 8879280405Srpaulo 8880280405Srpaulo<p> 8881280405SrpauloAny format string starts as if prefixed by "<code>!1=</code>", 8882280405Srpaulothat is, 8883280405Srpaulowith maximum alignment of 1 (no alignment) 8884280405Srpauloand native endianness. 8885280405Srpaulo 8886280405Srpaulo 8887280405Srpaulo<p> 8888280405SrpauloAlignment works as follows: 8889280405SrpauloFor each option, 8890280405Srpaulothe format gets extra padding until the data starts 8891280405Srpauloat an offset that is a multiple of the minimum between the 8892280405Srpaulooption size and the maximum alignment; 8893280405Srpaulothis minimum must be a power of 2. 8894280405SrpauloOptions "<code>c</code>" and "<code>z</code>" are not aligned; 8895280405Srpaulooption "<code>s</code>" follows the alignment of its starting integer. 8896280405Srpaulo 8897280405Srpaulo 8898280405Srpaulo<p> 8899280405SrpauloAll padding is filled with zeros by <a href="#pdf-string.pack"><code>string.pack</code></a> 8900280405Srpaulo(and ignored by <a href="#pdf-string.unpack"><code>string.unpack</code></a>). 8901280405Srpaulo 8902280405Srpaulo 8903280405Srpaulo 8904280405Srpaulo 8905280405Srpaulo 8906280405Srpaulo 8907280405Srpaulo 8908280405Srpaulo<h2>6.5 – <a name="6.5">UTF-8 Support</a></h2> 8909280405Srpaulo 8910280405Srpaulo<p> 8911280405SrpauloThis library provides basic support for UTF-8 encoding. 8912280405SrpauloIt provides all its functions inside the table <a name="pdf-utf8"><code>utf8</code></a>. 8913280405SrpauloThis library does not provide any support for Unicode other 8914280405Srpaulothan the handling of the encoding. 8915280405SrpauloAny operation that needs the meaning of a character, 8916280405Srpaulosuch as character classification, is outside its scope. 8917280405Srpaulo 8918280405Srpaulo 8919280405Srpaulo<p> 8920280405SrpauloUnless stated otherwise, 8921280405Srpauloall functions that expect a byte position as a parameter 8922280405Srpauloassume that the given position is either the start of a byte sequence 8923280405Srpauloor one plus the length of the subject string. 8924280405SrpauloAs in the string library, 8925280405Srpaulonegative indices count from the end of the string. 8926280405Srpaulo 8927280405Srpaulo 8928280405Srpaulo<p> 8929280405Srpaulo<hr><h3><a name="pdf-utf8.char"><code>utf8.char (···)</code></a></h3> 8930280405SrpauloReceives zero or more integers, 8931280405Srpauloconverts each one to its corresponding UTF-8 byte sequence 8932280405Srpauloand returns a string with the concatenation of all these sequences. 8933280405Srpaulo 8934280405Srpaulo 8935280405Srpaulo 8936280405Srpaulo 8937280405Srpaulo<p> 8938280405Srpaulo<hr><h3><a name="pdf-utf8.charpattern"><code>utf8.charpattern</code></a></h3> 8939280405SrpauloThe pattern (a string, not a function) "<code>[\0-\x7F\xC2-\xF4][\x80-\xBF]*</code>" 8940280405Srpaulo(see <a href="#6.4.1">§6.4.1</a>), 8941280405Srpaulowhich matches exactly one UTF-8 byte sequence, 8942280405Srpauloassuming that the subject is a valid UTF-8 string. 8943280405Srpaulo 8944280405Srpaulo 8945280405Srpaulo 8946280405Srpaulo 8947280405Srpaulo<p> 8948280405Srpaulo<hr><h3><a name="pdf-utf8.codes"><code>utf8.codes (s)</code></a></h3> 8949280405Srpaulo 8950280405Srpaulo 8951280405Srpaulo<p> 8952280405SrpauloReturns values so that the construction 8953280405Srpaulo 8954280405Srpaulo<pre> 8955280405Srpaulo for p, c in utf8.codes(s) do <em>body</em> end 8956280405Srpaulo</pre><p> 8957280405Srpaulowill iterate over all characters in string <code>s</code>, 8958280405Srpaulowith <code>p</code> being the position (in bytes) and <code>c</code> the code point 8959280405Srpauloof each character. 8960280405SrpauloIt raises an error if it meets any invalid byte sequence. 8961280405Srpaulo 8962280405Srpaulo 8963280405Srpaulo 8964280405Srpaulo 8965280405Srpaulo<p> 8966280405Srpaulo<hr><h3><a name="pdf-utf8.codepoint"><code>utf8.codepoint (s [, i [, j]])</code></a></h3> 8967280405SrpauloReturns the codepoints (as integers) from all characters in <code>s</code> 8968280405Srpaulothat start between byte position <code>i</code> and <code>j</code> (both included). 8969280405SrpauloThe default for <code>i</code> is 1 and for <code>j</code> is <code>i</code>. 8970280405SrpauloIt raises an error if it meets any invalid byte sequence. 8971280405Srpaulo 8972280405Srpaulo 8973280405Srpaulo 8974280405Srpaulo 8975280405Srpaulo<p> 8976280405Srpaulo<hr><h3><a name="pdf-utf8.len"><code>utf8.len (s [, i [, j]])</code></a></h3> 8977280405SrpauloReturns the number of UTF-8 characters in string <code>s</code> 8978280405Srpaulothat start between positions <code>i</code> and <code>j</code> (both inclusive). 8979280405SrpauloThe default for <code>i</code> is 1 and for <code>j</code> is -1. 8980280405SrpauloIf it finds any invalid byte sequence, 8981326344Simpreturns a false value plus the position of the first invalid byte. 8982280405Srpaulo 8983280405Srpaulo 8984280405Srpaulo 8985280405Srpaulo 8986280405Srpaulo<p> 8987280405Srpaulo<hr><h3><a name="pdf-utf8.offset"><code>utf8.offset (s, n [, i])</code></a></h3> 8988280405SrpauloReturns the position (in bytes) where the encoding of the 8989280405Srpaulo<code>n</code>-th character of <code>s</code> 8990280405Srpaulo(counting from position <code>i</code>) starts. 8991280405SrpauloA negative <code>n</code> gets characters before position <code>i</code>. 8992280405SrpauloThe default for <code>i</code> is 1 when <code>n</code> is non-negative 8993280405Srpauloand <code>#s + 1</code> otherwise, 8994280405Srpauloso that <code>utf8.offset(s, -n)</code> gets the offset of the 8995280405Srpaulo<code>n</code>-th character from the end of the string. 8996280405SrpauloIf the specified character is neither in the subject 8997280405Srpaulonor right after its end, 8998280405Srpaulothe function returns <b>nil</b>. 8999280405Srpaulo 9000280405Srpaulo 9001280405Srpaulo<p> 9002280405SrpauloAs a special case, 9003280405Srpaulowhen <code>n</code> is 0 the function returns the start of the encoding 9004280405Srpauloof the character that contains the <code>i</code>-th byte of <code>s</code>. 9005280405Srpaulo 9006280405Srpaulo 9007280405Srpaulo<p> 9008280405SrpauloThis function assumes that <code>s</code> is a valid UTF-8 string. 9009280405Srpaulo 9010280405Srpaulo 9011280405Srpaulo 9012280405Srpaulo 9013280405Srpaulo 9014280405Srpaulo 9015280405Srpaulo 9016280405Srpaulo<h2>6.6 – <a name="6.6">Table Manipulation</a></h2> 9017280405Srpaulo 9018280405Srpaulo<p> 9019280405SrpauloThis library provides generic functions for table manipulation. 9020280405SrpauloIt provides all its functions inside the table <a name="pdf-table"><code>table</code></a>. 9021280405Srpaulo 9022280405Srpaulo 9023280405Srpaulo<p> 9024280405SrpauloRemember that, whenever an operation needs the length of a table, 9025326344Simpall caveats about the length operator apply (see <a href="#3.4.7">§3.4.7</a>). 9026280405SrpauloAll functions ignore non-numeric keys 9027280405Srpauloin the tables given as arguments. 9028280405Srpaulo 9029280405Srpaulo 9030280405Srpaulo<p> 9031280405Srpaulo<hr><h3><a name="pdf-table.concat"><code>table.concat (list [, sep [, i [, j]]])</code></a></h3> 9032280405Srpaulo 9033280405Srpaulo 9034280405Srpaulo<p> 9035280405SrpauloGiven a list where all elements are strings or numbers, 9036280405Srpauloreturns the string <code>list[i]..sep..list[i+1] ··· sep..list[j]</code>. 9037280405SrpauloThe default value for <code>sep</code> is the empty string, 9038280405Srpaulothe default for <code>i</code> is 1, 9039280405Srpauloand the default for <code>j</code> is <code>#list</code>. 9040280405SrpauloIf <code>i</code> is greater than <code>j</code>, returns the empty string. 9041280405Srpaulo 9042280405Srpaulo 9043280405Srpaulo 9044280405Srpaulo 9045280405Srpaulo<p> 9046280405Srpaulo<hr><h3><a name="pdf-table.insert"><code>table.insert (list, [pos,] value)</code></a></h3> 9047280405Srpaulo 9048280405Srpaulo 9049280405Srpaulo<p> 9050280405SrpauloInserts element <code>value</code> at position <code>pos</code> in <code>list</code>, 9051280405Srpauloshifting up the elements 9052280405Srpaulo<code>list[pos], list[pos+1], ···, list[#list]</code>. 9053280405SrpauloThe default value for <code>pos</code> is <code>#list+1</code>, 9054280405Srpauloso that a call <code>table.insert(t,x)</code> inserts <code>x</code> at the end 9055280405Srpauloof list <code>t</code>. 9056280405Srpaulo 9057280405Srpaulo 9058280405Srpaulo 9059280405Srpaulo 9060280405Srpaulo<p> 9061280405Srpaulo<hr><h3><a name="pdf-table.move"><code>table.move (a1, f, e, t [,a2])</code></a></h3> 9062280405Srpaulo 9063280405Srpaulo 9064280405Srpaulo<p> 9065326344SimpMoves elements from table <code>a1</code> to table <code>a2</code>, 9066326344Simpperforming the equivalent to the following 9067280405Srpaulomultiple assignment: 9068280405Srpaulo<code>a2[t],··· = a1[f],···,a1[e]</code>. 9069280405SrpauloThe default for <code>a2</code> is <code>a1</code>. 9070280405SrpauloThe destination range can overlap with the source range. 9071326344SimpThe number of elements to be moved must fit in a Lua integer. 9072280405Srpaulo 9073280405Srpaulo 9074326344Simp<p> 9075326344SimpReturns the destination table <code>a2</code>. 9076280405Srpaulo 9077280405Srpaulo 9078326344Simp 9079326344Simp 9080280405Srpaulo<p> 9081280405Srpaulo<hr><h3><a name="pdf-table.pack"><code>table.pack (···)</code></a></h3> 9082280405Srpaulo 9083280405Srpaulo 9084280405Srpaulo<p> 9085280405SrpauloReturns a new table with all parameters stored into keys 1, 2, etc. 9086280405Srpauloand with a field "<code>n</code>" with the total number of parameters. 9087280405SrpauloNote that the resulting table may not be a sequence. 9088280405Srpaulo 9089280405Srpaulo 9090280405Srpaulo 9091280405Srpaulo 9092280405Srpaulo<p> 9093280405Srpaulo<hr><h3><a name="pdf-table.remove"><code>table.remove (list [, pos])</code></a></h3> 9094280405Srpaulo 9095280405Srpaulo 9096280405Srpaulo<p> 9097280405SrpauloRemoves from <code>list</code> the element at position <code>pos</code>, 9098280405Srpauloreturning the value of the removed element. 9099280405SrpauloWhen <code>pos</code> is an integer between 1 and <code>#list</code>, 9100280405Srpauloit shifts down the elements 9101280405Srpaulo<code>list[pos+1], list[pos+2], ···, list[#list]</code> 9102280405Srpauloand erases element <code>list[#list]</code>; 9103280405SrpauloThe index <code>pos</code> can also be 0 when <code>#list</code> is 0, 9104280405Srpauloor <code>#list + 1</code>; 9105280405Srpauloin those cases, the function erases the element <code>list[pos]</code>. 9106280405Srpaulo 9107280405Srpaulo 9108280405Srpaulo<p> 9109280405SrpauloThe default value for <code>pos</code> is <code>#list</code>, 9110280405Srpauloso that a call <code>table.remove(l)</code> removes the last element 9111280405Srpauloof list <code>l</code>. 9112280405Srpaulo 9113280405Srpaulo 9114280405Srpaulo 9115280405Srpaulo 9116280405Srpaulo<p> 9117280405Srpaulo<hr><h3><a name="pdf-table.sort"><code>table.sort (list [, comp])</code></a></h3> 9118280405Srpaulo 9119280405Srpaulo 9120280405Srpaulo<p> 9121280405SrpauloSorts list elements in a given order, <em>in-place</em>, 9122280405Srpaulofrom <code>list[1]</code> to <code>list[#list]</code>. 9123280405SrpauloIf <code>comp</code> is given, 9124280405Srpaulothen it must be a function that receives two list elements 9125280405Srpauloand returns true when the first element must come 9126280405Srpaulobefore the second in the final order 9127326344Simp(so that, after the sort, 9128326344Simp<code>i < j</code> implies <code>not comp(list[j],list[i])</code>). 9129280405SrpauloIf <code>comp</code> is not given, 9130280405Srpaulothen the standard Lua operator <code><</code> is used instead. 9131280405Srpaulo 9132280405Srpaulo 9133280405Srpaulo<p> 9134326344SimpNote that the <code>comp</code> function must define 9135326344Simpa strict partial order over the elements in the list; 9136326344Simpthat is, it must be asymmetric and transitive. 9137326344SimpOtherwise, no valid sort may be possible. 9138326344Simp 9139326344Simp 9140326344Simp<p> 9141326344SimpThe sort algorithm is not stable: 9142326344Simpelements considered equal by the given order 9143280405Srpaulomay have their relative positions changed by the sort. 9144280405Srpaulo 9145280405Srpaulo 9146280405Srpaulo 9147280405Srpaulo 9148280405Srpaulo<p> 9149280405Srpaulo<hr><h3><a name="pdf-table.unpack"><code>table.unpack (list [, i [, j]])</code></a></h3> 9150280405Srpaulo 9151280405Srpaulo 9152280405Srpaulo<p> 9153280405SrpauloReturns the elements from the given list. 9154280405SrpauloThis function is equivalent to 9155280405Srpaulo 9156280405Srpaulo<pre> 9157280405Srpaulo return list[i], list[i+1], ···, list[j] 9158280405Srpaulo</pre><p> 9159280405SrpauloBy default, <code>i</code> is 1 and <code>j</code> is <code>#list</code>. 9160280405Srpaulo 9161280405Srpaulo 9162280405Srpaulo 9163280405Srpaulo 9164280405Srpaulo 9165280405Srpaulo 9166280405Srpaulo 9167280405Srpaulo<h2>6.7 – <a name="6.7">Mathematical Functions</a></h2> 9168280405Srpaulo 9169280405Srpaulo<p> 9170280405SrpauloThis library provides basic mathematical functions. 9171280405SrpauloIt provides all its functions and constants inside the table <a name="pdf-math"><code>math</code></a>. 9172280405SrpauloFunctions with the annotation "<code>integer/float</code>" give 9173280405Srpaulointeger results for integer arguments 9174280405Srpauloand float results for float (or mixed) arguments. 9175280405SrpauloRounding functions 9176280405Srpaulo(<a href="#pdf-math.ceil"><code>math.ceil</code></a>, <a href="#pdf-math.floor"><code>math.floor</code></a>, and <a href="#pdf-math.modf"><code>math.modf</code></a>) 9177280405Srpauloreturn an integer when the result fits in the range of an integer, 9178280405Srpauloor a float otherwise. 9179280405Srpaulo 9180280405Srpaulo 9181280405Srpaulo<p> 9182280405Srpaulo<hr><h3><a name="pdf-math.abs"><code>math.abs (x)</code></a></h3> 9183280405Srpaulo 9184280405Srpaulo 9185280405Srpaulo<p> 9186280405SrpauloReturns the absolute value of <code>x</code>. (integer/float) 9187280405Srpaulo 9188280405Srpaulo 9189280405Srpaulo 9190280405Srpaulo 9191280405Srpaulo<p> 9192280405Srpaulo<hr><h3><a name="pdf-math.acos"><code>math.acos (x)</code></a></h3> 9193280405Srpaulo 9194280405Srpaulo 9195280405Srpaulo<p> 9196280405SrpauloReturns the arc cosine of <code>x</code> (in radians). 9197280405Srpaulo 9198280405Srpaulo 9199280405Srpaulo 9200280405Srpaulo 9201280405Srpaulo<p> 9202280405Srpaulo<hr><h3><a name="pdf-math.asin"><code>math.asin (x)</code></a></h3> 9203280405Srpaulo 9204280405Srpaulo 9205280405Srpaulo<p> 9206280405SrpauloReturns the arc sine of <code>x</code> (in radians). 9207280405Srpaulo 9208280405Srpaulo 9209280405Srpaulo 9210280405Srpaulo 9211280405Srpaulo<p> 9212280405Srpaulo<hr><h3><a name="pdf-math.atan"><code>math.atan (y [, x])</code></a></h3> 9213280405Srpaulo 9214280405Srpaulo 9215280405Srpaulo<p> 9216280405Srpaulo 9217280405SrpauloReturns the arc tangent of <code>y/x</code> (in radians), 9218280405Srpaulobut uses the signs of both parameters to find the 9219280405Srpauloquadrant of the result. 9220280405Srpaulo(It also handles correctly the case of <code>x</code> being zero.) 9221280405Srpaulo 9222280405Srpaulo 9223280405Srpaulo<p> 9224280405SrpauloThe default value for <code>x</code> is 1, 9225280405Srpauloso that the call <code>math.atan(y)</code> 9226280405Srpauloreturns the arc tangent of <code>y</code>. 9227280405Srpaulo 9228280405Srpaulo 9229280405Srpaulo 9230280405Srpaulo 9231280405Srpaulo<p> 9232280405Srpaulo<hr><h3><a name="pdf-math.ceil"><code>math.ceil (x)</code></a></h3> 9233280405Srpaulo 9234280405Srpaulo 9235280405Srpaulo<p> 9236280405SrpauloReturns the smallest integral value larger than or equal to <code>x</code>. 9237280405Srpaulo 9238280405Srpaulo 9239280405Srpaulo 9240280405Srpaulo 9241280405Srpaulo<p> 9242280405Srpaulo<hr><h3><a name="pdf-math.cos"><code>math.cos (x)</code></a></h3> 9243280405Srpaulo 9244280405Srpaulo 9245280405Srpaulo<p> 9246280405SrpauloReturns the cosine of <code>x</code> (assumed to be in radians). 9247280405Srpaulo 9248280405Srpaulo 9249280405Srpaulo 9250280405Srpaulo 9251280405Srpaulo<p> 9252280405Srpaulo<hr><h3><a name="pdf-math.deg"><code>math.deg (x)</code></a></h3> 9253280405Srpaulo 9254280405Srpaulo 9255280405Srpaulo<p> 9256280405SrpauloConverts the angle <code>x</code> from radians to degrees. 9257280405Srpaulo 9258280405Srpaulo 9259280405Srpaulo 9260280405Srpaulo 9261280405Srpaulo<p> 9262280405Srpaulo<hr><h3><a name="pdf-math.exp"><code>math.exp (x)</code></a></h3> 9263280405Srpaulo 9264280405Srpaulo 9265280405Srpaulo<p> 9266280405SrpauloReturns the value <em>e<sup>x</sup></em> 9267280405Srpaulo(where <code>e</code> is the base of natural logarithms). 9268280405Srpaulo 9269280405Srpaulo 9270280405Srpaulo 9271280405Srpaulo 9272280405Srpaulo<p> 9273280405Srpaulo<hr><h3><a name="pdf-math.floor"><code>math.floor (x)</code></a></h3> 9274280405Srpaulo 9275280405Srpaulo 9276280405Srpaulo<p> 9277280405SrpauloReturns the largest integral value smaller than or equal to <code>x</code>. 9278280405Srpaulo 9279280405Srpaulo 9280280405Srpaulo 9281280405Srpaulo 9282280405Srpaulo<p> 9283280405Srpaulo<hr><h3><a name="pdf-math.fmod"><code>math.fmod (x, y)</code></a></h3> 9284280405Srpaulo 9285280405Srpaulo 9286280405Srpaulo<p> 9287280405SrpauloReturns the remainder of the division of <code>x</code> by <code>y</code> 9288280405Srpaulothat rounds the quotient towards zero. (integer/float) 9289280405Srpaulo 9290280405Srpaulo 9291280405Srpaulo 9292280405Srpaulo 9293280405Srpaulo<p> 9294280405Srpaulo<hr><h3><a name="pdf-math.huge"><code>math.huge</code></a></h3> 9295280405Srpaulo 9296280405Srpaulo 9297280405Srpaulo<p> 9298280405SrpauloThe float value <code>HUGE_VAL</code>, 9299326344Simpa value larger than any other numeric value. 9300280405Srpaulo 9301280405Srpaulo 9302280405Srpaulo 9303280405Srpaulo 9304280405Srpaulo<p> 9305280405Srpaulo<hr><h3><a name="pdf-math.log"><code>math.log (x [, base])</code></a></h3> 9306280405Srpaulo 9307280405Srpaulo 9308280405Srpaulo<p> 9309280405SrpauloReturns the logarithm of <code>x</code> in the given base. 9310280405SrpauloThe default for <code>base</code> is <em>e</em> 9311280405Srpaulo(so that the function returns the natural logarithm of <code>x</code>). 9312280405Srpaulo 9313280405Srpaulo 9314280405Srpaulo 9315280405Srpaulo 9316280405Srpaulo<p> 9317280405Srpaulo<hr><h3><a name="pdf-math.max"><code>math.max (x, ···)</code></a></h3> 9318280405Srpaulo 9319280405Srpaulo 9320280405Srpaulo<p> 9321280405SrpauloReturns the argument with the maximum value, 9322280405Srpauloaccording to the Lua operator <code><</code>. (integer/float) 9323280405Srpaulo 9324280405Srpaulo 9325280405Srpaulo 9326280405Srpaulo 9327280405Srpaulo<p> 9328280405Srpaulo<hr><h3><a name="pdf-math.maxinteger"><code>math.maxinteger</code></a></h3> 9329280405SrpauloAn integer with the maximum value for an integer. 9330280405Srpaulo 9331280405Srpaulo 9332280405Srpaulo 9333280405Srpaulo 9334280405Srpaulo<p> 9335280405Srpaulo<hr><h3><a name="pdf-math.min"><code>math.min (x, ···)</code></a></h3> 9336280405Srpaulo 9337280405Srpaulo 9338280405Srpaulo<p> 9339280405SrpauloReturns the argument with the minimum value, 9340280405Srpauloaccording to the Lua operator <code><</code>. (integer/float) 9341280405Srpaulo 9342280405Srpaulo 9343280405Srpaulo 9344280405Srpaulo 9345280405Srpaulo<p> 9346280405Srpaulo<hr><h3><a name="pdf-math.mininteger"><code>math.mininteger</code></a></h3> 9347280405SrpauloAn integer with the minimum value for an integer. 9348280405Srpaulo 9349280405Srpaulo 9350280405Srpaulo 9351280405Srpaulo 9352280405Srpaulo<p> 9353280405Srpaulo<hr><h3><a name="pdf-math.modf"><code>math.modf (x)</code></a></h3> 9354280405Srpaulo 9355280405Srpaulo 9356280405Srpaulo<p> 9357280405SrpauloReturns the integral part of <code>x</code> and the fractional part of <code>x</code>. 9358280405SrpauloIts second result is always a float. 9359280405Srpaulo 9360280405Srpaulo 9361280405Srpaulo 9362280405Srpaulo 9363280405Srpaulo<p> 9364280405Srpaulo<hr><h3><a name="pdf-math.pi"><code>math.pi</code></a></h3> 9365280405Srpaulo 9366280405Srpaulo 9367280405Srpaulo<p> 9368280405SrpauloThe value of <em>π</em>. 9369280405Srpaulo 9370280405Srpaulo 9371280405Srpaulo 9372280405Srpaulo 9373280405Srpaulo<p> 9374280405Srpaulo<hr><h3><a name="pdf-math.rad"><code>math.rad (x)</code></a></h3> 9375280405Srpaulo 9376280405Srpaulo 9377280405Srpaulo<p> 9378280405SrpauloConverts the angle <code>x</code> from degrees to radians. 9379280405Srpaulo 9380280405Srpaulo 9381280405Srpaulo 9382280405Srpaulo 9383280405Srpaulo<p> 9384280405Srpaulo<hr><h3><a name="pdf-math.random"><code>math.random ([m [, n]])</code></a></h3> 9385280405Srpaulo 9386280405Srpaulo 9387280405Srpaulo<p> 9388280405SrpauloWhen called without arguments, 9389280405Srpauloreturns a pseudo-random float with uniform distribution 9390280405Srpauloin the range <em>[0,1)</em>. 9391280405SrpauloWhen called with two integers <code>m</code> and <code>n</code>, 9392280405Srpaulo<code>math.random</code> returns a pseudo-random integer 9393280405Srpaulowith uniform distribution in the range <em>[m, n]</em>. 9394326344Simp(The value <em>n-m</em> cannot be negative and must fit in a Lua integer.) 9395280405SrpauloThe call <code>math.random(n)</code> is equivalent to <code>math.random(1,n)</code>. 9396280405Srpaulo 9397280405Srpaulo 9398280405Srpaulo<p> 9399280405SrpauloThis function is an interface to the underling 9400280405Srpaulopseudo-random generator function provided by C. 9401280405Srpaulo 9402280405Srpaulo 9403280405Srpaulo 9404280405Srpaulo 9405280405Srpaulo<p> 9406280405Srpaulo<hr><h3><a name="pdf-math.randomseed"><code>math.randomseed (x)</code></a></h3> 9407280405Srpaulo 9408280405Srpaulo 9409280405Srpaulo<p> 9410280405SrpauloSets <code>x</code> as the "seed" 9411280405Srpaulofor the pseudo-random generator: 9412280405Srpauloequal seeds produce equal sequences of numbers. 9413280405Srpaulo 9414280405Srpaulo 9415280405Srpaulo 9416280405Srpaulo 9417280405Srpaulo<p> 9418280405Srpaulo<hr><h3><a name="pdf-math.sin"><code>math.sin (x)</code></a></h3> 9419280405Srpaulo 9420280405Srpaulo 9421280405Srpaulo<p> 9422280405SrpauloReturns the sine of <code>x</code> (assumed to be in radians). 9423280405Srpaulo 9424280405Srpaulo 9425280405Srpaulo 9426280405Srpaulo 9427280405Srpaulo<p> 9428280405Srpaulo<hr><h3><a name="pdf-math.sqrt"><code>math.sqrt (x)</code></a></h3> 9429280405Srpaulo 9430280405Srpaulo 9431280405Srpaulo<p> 9432280405SrpauloReturns the square root of <code>x</code>. 9433280405Srpaulo(You can also use the expression <code>x^0.5</code> to compute this value.) 9434280405Srpaulo 9435280405Srpaulo 9436280405Srpaulo 9437280405Srpaulo 9438280405Srpaulo<p> 9439280405Srpaulo<hr><h3><a name="pdf-math.tan"><code>math.tan (x)</code></a></h3> 9440280405Srpaulo 9441280405Srpaulo 9442280405Srpaulo<p> 9443280405SrpauloReturns the tangent of <code>x</code> (assumed to be in radians). 9444280405Srpaulo 9445280405Srpaulo 9446280405Srpaulo 9447280405Srpaulo 9448280405Srpaulo<p> 9449280405Srpaulo<hr><h3><a name="pdf-math.tointeger"><code>math.tointeger (x)</code></a></h3> 9450280405Srpaulo 9451280405Srpaulo 9452280405Srpaulo<p> 9453280405SrpauloIf the value <code>x</code> is convertible to an integer, 9454280405Srpauloreturns that integer. 9455280405SrpauloOtherwise, returns <b>nil</b>. 9456280405Srpaulo 9457280405Srpaulo 9458280405Srpaulo 9459280405Srpaulo 9460280405Srpaulo<p> 9461280405Srpaulo<hr><h3><a name="pdf-math.type"><code>math.type (x)</code></a></h3> 9462280405Srpaulo 9463280405Srpaulo 9464280405Srpaulo<p> 9465280405SrpauloReturns "<code>integer</code>" if <code>x</code> is an integer, 9466280405Srpaulo"<code>float</code>" if it is a float, 9467280405Srpauloor <b>nil</b> if <code>x</code> is not a number. 9468280405Srpaulo 9469280405Srpaulo 9470280405Srpaulo 9471280405Srpaulo 9472280405Srpaulo<p> 9473280405Srpaulo<hr><h3><a name="pdf-math.ult"><code>math.ult (m, n)</code></a></h3> 9474280405Srpaulo 9475280405Srpaulo 9476280405Srpaulo<p> 9477280405SrpauloReturns a boolean, 9478326344Simptrue if and only if integer <code>m</code> is below integer <code>n</code> when 9479280405Srpaulothey are compared as unsigned integers. 9480280405Srpaulo 9481280405Srpaulo 9482280405Srpaulo 9483280405Srpaulo 9484280405Srpaulo 9485280405Srpaulo 9486280405Srpaulo 9487280405Srpaulo<h2>6.8 – <a name="6.8">Input and Output Facilities</a></h2> 9488280405Srpaulo 9489280405Srpaulo<p> 9490280405SrpauloThe I/O library provides two different styles for file manipulation. 9491280405SrpauloThe first one uses implicit file handles; 9492280405Srpaulothat is, there are operations to set a default input file and a 9493280405Srpaulodefault output file, 9494280405Srpauloand all input/output operations are over these default files. 9495280405SrpauloThe second style uses explicit file handles. 9496280405Srpaulo 9497280405Srpaulo 9498280405Srpaulo<p> 9499280405SrpauloWhen using implicit file handles, 9500280405Srpauloall operations are supplied by table <a name="pdf-io"><code>io</code></a>. 9501280405SrpauloWhen using explicit file handles, 9502280405Srpaulothe operation <a href="#pdf-io.open"><code>io.open</code></a> returns a file handle 9503280405Srpauloand then all operations are supplied as methods of the file handle. 9504280405Srpaulo 9505280405Srpaulo 9506280405Srpaulo<p> 9507280405SrpauloThe table <code>io</code> also provides 9508280405Srpaulothree predefined file handles with their usual meanings from C: 9509280405Srpaulo<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>. 9510280405SrpauloThe I/O library never closes these files. 9511280405Srpaulo 9512280405Srpaulo 9513280405Srpaulo<p> 9514280405SrpauloUnless otherwise stated, 9515280405Srpauloall I/O functions return <b>nil</b> on failure 9516280405Srpaulo(plus an error message as a second result and 9517280405Srpauloa system-dependent error code as a third result) 9518280405Srpauloand some value different from <b>nil</b> on success. 9519280405SrpauloOn non-POSIX systems, 9520280405Srpaulothe computation of the error message and error code 9521280405Srpauloin case of errors 9522280405Srpaulomay be not thread safe, 9523280405Srpaulobecause they rely on the global C variable <code>errno</code>. 9524280405Srpaulo 9525280405Srpaulo 9526280405Srpaulo<p> 9527280405Srpaulo<hr><h3><a name="pdf-io.close"><code>io.close ([file])</code></a></h3> 9528280405Srpaulo 9529280405Srpaulo 9530280405Srpaulo<p> 9531280405SrpauloEquivalent to <code>file:close()</code>. 9532280405SrpauloWithout a <code>file</code>, closes the default output file. 9533280405Srpaulo 9534280405Srpaulo 9535280405Srpaulo 9536280405Srpaulo 9537280405Srpaulo<p> 9538280405Srpaulo<hr><h3><a name="pdf-io.flush"><code>io.flush ()</code></a></h3> 9539280405Srpaulo 9540280405Srpaulo 9541280405Srpaulo<p> 9542280405SrpauloEquivalent to <code>io.output():flush()</code>. 9543280405Srpaulo 9544280405Srpaulo 9545280405Srpaulo 9546280405Srpaulo 9547280405Srpaulo<p> 9548280405Srpaulo<hr><h3><a name="pdf-io.input"><code>io.input ([file])</code></a></h3> 9549280405Srpaulo 9550280405Srpaulo 9551280405Srpaulo<p> 9552280405SrpauloWhen called with a file name, it opens the named file (in text mode), 9553280405Srpauloand sets its handle as the default input file. 9554280405SrpauloWhen called with a file handle, 9555280405Srpauloit simply sets this file handle as the default input file. 9556280405SrpauloWhen called without parameters, 9557280405Srpauloit returns the current default input file. 9558280405Srpaulo 9559280405Srpaulo 9560280405Srpaulo<p> 9561280405SrpauloIn case of errors this function raises the error, 9562280405Srpauloinstead of returning an error code. 9563280405Srpaulo 9564280405Srpaulo 9565280405Srpaulo 9566280405Srpaulo 9567280405Srpaulo<p> 9568326344Simp<hr><h3><a name="pdf-io.lines"><code>io.lines ([filename, ···])</code></a></h3> 9569280405Srpaulo 9570280405Srpaulo 9571280405Srpaulo<p> 9572280405SrpauloOpens the given file name in read mode 9573280405Srpauloand returns an iterator function that 9574280405Srpauloworks like <code>file:lines(···)</code> over the opened file. 9575280405SrpauloWhen the iterator function detects the end of file, 9576280405Srpauloit returns no values (to finish the loop) and automatically closes the file. 9577280405Srpaulo 9578280405Srpaulo 9579280405Srpaulo<p> 9580280405SrpauloThe call <code>io.lines()</code> (with no file name) is equivalent 9581280405Srpauloto <code>io.input():lines("*l")</code>; 9582280405Srpaulothat is, it iterates over the lines of the default input file. 9583280405SrpauloIn this case it does not close the file when the loop ends. 9584280405Srpaulo 9585280405Srpaulo 9586280405Srpaulo<p> 9587280405SrpauloIn case of errors this function raises the error, 9588280405Srpauloinstead of returning an error code. 9589280405Srpaulo 9590280405Srpaulo 9591280405Srpaulo 9592280405Srpaulo 9593280405Srpaulo<p> 9594280405Srpaulo<hr><h3><a name="pdf-io.open"><code>io.open (filename [, mode])</code></a></h3> 9595280405Srpaulo 9596280405Srpaulo 9597280405Srpaulo<p> 9598280405SrpauloThis function opens a file, 9599280405Srpauloin the mode specified in the string <code>mode</code>. 9600326344SimpIn case of success, 9601326344Simpit returns a new file handle. 9602280405Srpaulo 9603280405Srpaulo 9604280405Srpaulo<p> 9605280405SrpauloThe <code>mode</code> string can be any of the following: 9606280405Srpaulo 9607280405Srpaulo<ul> 9608280405Srpaulo<li><b>"<code>r</code>": </b> read mode (the default);</li> 9609280405Srpaulo<li><b>"<code>w</code>": </b> write mode;</li> 9610280405Srpaulo<li><b>"<code>a</code>": </b> append mode;</li> 9611280405Srpaulo<li><b>"<code>r+</code>": </b> update mode, all previous data is preserved;</li> 9612280405Srpaulo<li><b>"<code>w+</code>": </b> update mode, all previous data is erased;</li> 9613280405Srpaulo<li><b>"<code>a+</code>": </b> append update mode, previous data is preserved, 9614280405Srpaulo writing is only allowed at the end of file.</li> 9615280405Srpaulo</ul><p> 9616280405SrpauloThe <code>mode</code> string can also have a '<code>b</code>' at the end, 9617280405Srpaulowhich is needed in some systems to open the file in binary mode. 9618280405Srpaulo 9619280405Srpaulo 9620280405Srpaulo 9621280405Srpaulo 9622280405Srpaulo<p> 9623280405Srpaulo<hr><h3><a name="pdf-io.output"><code>io.output ([file])</code></a></h3> 9624280405Srpaulo 9625280405Srpaulo 9626280405Srpaulo<p> 9627280405SrpauloSimilar to <a href="#pdf-io.input"><code>io.input</code></a>, but operates over the default output file. 9628280405Srpaulo 9629280405Srpaulo 9630280405Srpaulo 9631280405Srpaulo 9632280405Srpaulo<p> 9633280405Srpaulo<hr><h3><a name="pdf-io.popen"><code>io.popen (prog [, mode])</code></a></h3> 9634280405Srpaulo 9635280405Srpaulo 9636280405Srpaulo<p> 9637280405SrpauloThis function is system dependent and is not available 9638280405Srpauloon all platforms. 9639280405Srpaulo 9640280405Srpaulo 9641280405Srpaulo<p> 9642280405SrpauloStarts program <code>prog</code> in a separated process and returns 9643280405Srpauloa file handle that you can use to read data from this program 9644280405Srpaulo(if <code>mode</code> is <code>"r"</code>, the default) 9645280405Srpauloor to write data to this program 9646280405Srpaulo(if <code>mode</code> is <code>"w"</code>). 9647280405Srpaulo 9648280405Srpaulo 9649280405Srpaulo 9650280405Srpaulo 9651280405Srpaulo<p> 9652280405Srpaulo<hr><h3><a name="pdf-io.read"><code>io.read (···)</code></a></h3> 9653280405Srpaulo 9654280405Srpaulo 9655280405Srpaulo<p> 9656280405SrpauloEquivalent to <code>io.input():read(···)</code>. 9657280405Srpaulo 9658280405Srpaulo 9659280405Srpaulo 9660280405Srpaulo 9661280405Srpaulo<p> 9662280405Srpaulo<hr><h3><a name="pdf-io.tmpfile"><code>io.tmpfile ()</code></a></h3> 9663280405Srpaulo 9664280405Srpaulo 9665280405Srpaulo<p> 9666326344SimpIn case of success, 9667326344Simpreturns a handle for a temporary file. 9668280405SrpauloThis file is opened in update mode 9669280405Srpauloand it is automatically removed when the program ends. 9670280405Srpaulo 9671280405Srpaulo 9672280405Srpaulo 9673280405Srpaulo 9674280405Srpaulo<p> 9675280405Srpaulo<hr><h3><a name="pdf-io.type"><code>io.type (obj)</code></a></h3> 9676280405Srpaulo 9677280405Srpaulo 9678280405Srpaulo<p> 9679280405SrpauloChecks whether <code>obj</code> is a valid file handle. 9680280405SrpauloReturns the string <code>"file"</code> if <code>obj</code> is an open file handle, 9681280405Srpaulo<code>"closed file"</code> if <code>obj</code> is a closed file handle, 9682280405Srpauloor <b>nil</b> if <code>obj</code> is not a file handle. 9683280405Srpaulo 9684280405Srpaulo 9685280405Srpaulo 9686280405Srpaulo 9687280405Srpaulo<p> 9688280405Srpaulo<hr><h3><a name="pdf-io.write"><code>io.write (···)</code></a></h3> 9689280405Srpaulo 9690280405Srpaulo 9691280405Srpaulo<p> 9692280405SrpauloEquivalent to <code>io.output():write(···)</code>. 9693280405Srpaulo 9694280405Srpaulo 9695280405Srpaulo 9696280405Srpaulo 9697280405Srpaulo<p> 9698280405Srpaulo<hr><h3><a name="pdf-file:close"><code>file:close ()</code></a></h3> 9699280405Srpaulo 9700280405Srpaulo 9701280405Srpaulo<p> 9702280405SrpauloCloses <code>file</code>. 9703280405SrpauloNote that files are automatically closed when 9704280405Srpaulotheir handles are garbage collected, 9705280405Srpaulobut that takes an unpredictable amount of time to happen. 9706280405Srpaulo 9707280405Srpaulo 9708280405Srpaulo<p> 9709280405SrpauloWhen closing a file handle created with <a href="#pdf-io.popen"><code>io.popen</code></a>, 9710280405Srpaulo<a href="#pdf-file:close"><code>file:close</code></a> returns the same values 9711280405Srpauloreturned by <a href="#pdf-os.execute"><code>os.execute</code></a>. 9712280405Srpaulo 9713280405Srpaulo 9714280405Srpaulo 9715280405Srpaulo 9716280405Srpaulo<p> 9717280405Srpaulo<hr><h3><a name="pdf-file:flush"><code>file:flush ()</code></a></h3> 9718280405Srpaulo 9719280405Srpaulo 9720280405Srpaulo<p> 9721280405SrpauloSaves any written data to <code>file</code>. 9722280405Srpaulo 9723280405Srpaulo 9724280405Srpaulo 9725280405Srpaulo 9726280405Srpaulo<p> 9727280405Srpaulo<hr><h3><a name="pdf-file:lines"><code>file:lines (···)</code></a></h3> 9728280405Srpaulo 9729280405Srpaulo 9730280405Srpaulo<p> 9731280405SrpauloReturns an iterator function that, 9732280405Srpauloeach time it is called, 9733280405Srpauloreads the file according to the given formats. 9734280405SrpauloWhen no format is given, 9735280405Srpaulouses "<code>l</code>" as a default. 9736280405SrpauloAs an example, the construction 9737280405Srpaulo 9738280405Srpaulo<pre> 9739280405Srpaulo for c in file:lines(1) do <em>body</em> end 9740280405Srpaulo</pre><p> 9741280405Srpaulowill iterate over all characters of the file, 9742280405Srpaulostarting at the current position. 9743280405SrpauloUnlike <a href="#pdf-io.lines"><code>io.lines</code></a>, this function does not close the file 9744280405Srpaulowhen the loop ends. 9745280405Srpaulo 9746280405Srpaulo 9747280405Srpaulo<p> 9748280405SrpauloIn case of errors this function raises the error, 9749280405Srpauloinstead of returning an error code. 9750280405Srpaulo 9751280405Srpaulo 9752280405Srpaulo 9753280405Srpaulo 9754280405Srpaulo<p> 9755280405Srpaulo<hr><h3><a name="pdf-file:read"><code>file:read (···)</code></a></h3> 9756280405Srpaulo 9757280405Srpaulo 9758280405Srpaulo<p> 9759280405SrpauloReads the file <code>file</code>, 9760280405Srpauloaccording to the given formats, which specify what to read. 9761280405SrpauloFor each format, 9762280405Srpaulothe function returns a string or a number with the characters read, 9763280405Srpauloor <b>nil</b> if it cannot read data with the specified format. 9764280405Srpaulo(In this latter case, 9765280405Srpaulothe function does not read subsequent formats.) 9766280405SrpauloWhen called without formats, 9767280405Srpauloit uses a default format that reads the next line 9768280405Srpaulo(see below). 9769280405Srpaulo 9770280405Srpaulo 9771280405Srpaulo<p> 9772280405SrpauloThe available formats are 9773280405Srpaulo 9774280405Srpaulo<ul> 9775280405Srpaulo 9776280405Srpaulo<li><b>"<code>n</code>": </b> 9777280405Srpauloreads a numeral and returns it as a float or an integer, 9778280405Srpaulofollowing the lexical conventions of Lua. 9779280405Srpaulo(The numeral may have leading spaces and a sign.) 9780280405SrpauloThis format always reads the longest input sequence that 9781326344Simpis a valid prefix for a numeral; 9782326344Simpif that prefix does not form a valid numeral 9783280405Srpaulo(e.g., an empty string, "<code>0x</code>", or "<code>3.4e-</code>"), 9784280405Srpauloit is discarded and the function returns <b>nil</b>. 9785280405Srpaulo</li> 9786280405Srpaulo 9787280405Srpaulo<li><b>"<code>a</code>": </b> 9788280405Srpauloreads the whole file, starting at the current position. 9789280405SrpauloOn end of file, it returns the empty string. 9790280405Srpaulo</li> 9791280405Srpaulo 9792280405Srpaulo<li><b>"<code>l</code>": </b> 9793280405Srpauloreads the next line skipping the end of line, 9794280405Srpauloreturning <b>nil</b> on end of file. 9795280405SrpauloThis is the default format. 9796280405Srpaulo</li> 9797280405Srpaulo 9798280405Srpaulo<li><b>"<code>L</code>": </b> 9799280405Srpauloreads the next line keeping the end-of-line character (if present), 9800280405Srpauloreturning <b>nil</b> on end of file. 9801280405Srpaulo</li> 9802280405Srpaulo 9803280405Srpaulo<li><b><em>number</em>: </b> 9804280405Srpauloreads a string with up to this number of bytes, 9805280405Srpauloreturning <b>nil</b> on end of file. 9806280405SrpauloIf <code>number</code> is zero, 9807280405Srpauloit reads nothing and returns an empty string, 9808280405Srpauloor <b>nil</b> on end of file. 9809280405Srpaulo</li> 9810280405Srpaulo 9811280405Srpaulo</ul><p> 9812280405SrpauloThe formats "<code>l</code>" and "<code>L</code>" should be used only for text files. 9813280405Srpaulo 9814280405Srpaulo 9815280405Srpaulo 9816280405Srpaulo 9817280405Srpaulo<p> 9818280405Srpaulo<hr><h3><a name="pdf-file:seek"><code>file:seek ([whence [, offset]])</code></a></h3> 9819280405Srpaulo 9820280405Srpaulo 9821280405Srpaulo<p> 9822280405SrpauloSets and gets the file position, 9823280405Srpaulomeasured from the beginning of the file, 9824280405Srpauloto the position given by <code>offset</code> plus a base 9825280405Srpaulospecified by the string <code>whence</code>, as follows: 9826280405Srpaulo 9827280405Srpaulo<ul> 9828280405Srpaulo<li><b>"<code>set</code>": </b> base is position 0 (beginning of the file);</li> 9829280405Srpaulo<li><b>"<code>cur</code>": </b> base is current position;</li> 9830280405Srpaulo<li><b>"<code>end</code>": </b> base is end of file;</li> 9831280405Srpaulo</ul><p> 9832280405SrpauloIn case of success, <code>seek</code> returns the final file position, 9833280405Srpaulomeasured in bytes from the beginning of the file. 9834280405SrpauloIf <code>seek</code> fails, it returns <b>nil</b>, 9835280405Srpauloplus a string describing the error. 9836280405Srpaulo 9837280405Srpaulo 9838280405Srpaulo<p> 9839280405SrpauloThe default value for <code>whence</code> is <code>"cur"</code>, 9840280405Srpauloand for <code>offset</code> is 0. 9841280405SrpauloTherefore, the call <code>file:seek()</code> returns the current 9842280405Srpaulofile position, without changing it; 9843280405Srpaulothe call <code>file:seek("set")</code> sets the position to the 9844280405Srpaulobeginning of the file (and returns 0); 9845280405Srpauloand the call <code>file:seek("end")</code> sets the position to the 9846280405Srpauloend of the file, and returns its size. 9847280405Srpaulo 9848280405Srpaulo 9849280405Srpaulo 9850280405Srpaulo 9851280405Srpaulo<p> 9852280405Srpaulo<hr><h3><a name="pdf-file:setvbuf"><code>file:setvbuf (mode [, size])</code></a></h3> 9853280405Srpaulo 9854280405Srpaulo 9855280405Srpaulo<p> 9856280405SrpauloSets the buffering mode for an output file. 9857280405SrpauloThere are three available modes: 9858280405Srpaulo 9859280405Srpaulo<ul> 9860280405Srpaulo 9861280405Srpaulo<li><b>"<code>no</code>": </b> 9862280405Srpaulono buffering; the result of any output operation appears immediately. 9863280405Srpaulo</li> 9864280405Srpaulo 9865280405Srpaulo<li><b>"<code>full</code>": </b> 9866280405Srpaulofull buffering; output operation is performed only 9867280405Srpaulowhen the buffer is full or when 9868280405Srpauloyou explicitly <code>flush</code> the file (see <a href="#pdf-io.flush"><code>io.flush</code></a>). 9869280405Srpaulo</li> 9870280405Srpaulo 9871280405Srpaulo<li><b>"<code>line</code>": </b> 9872280405Srpauloline buffering; output is buffered until a newline is output 9873280405Srpauloor there is any input from some special files 9874280405Srpaulo(such as a terminal device). 9875280405Srpaulo</li> 9876280405Srpaulo 9877280405Srpaulo</ul><p> 9878280405SrpauloFor the last two cases, <code>size</code> 9879280405Srpaulospecifies the size of the buffer, in bytes. 9880280405SrpauloThe default is an appropriate size. 9881280405Srpaulo 9882280405Srpaulo 9883280405Srpaulo 9884280405Srpaulo 9885280405Srpaulo<p> 9886280405Srpaulo<hr><h3><a name="pdf-file:write"><code>file:write (···)</code></a></h3> 9887280405Srpaulo 9888280405Srpaulo 9889280405Srpaulo<p> 9890280405SrpauloWrites the value of each of its arguments to <code>file</code>. 9891280405SrpauloThe arguments must be strings or numbers. 9892280405Srpaulo 9893280405Srpaulo 9894280405Srpaulo<p> 9895280405SrpauloIn case of success, this function returns <code>file</code>. 9896280405SrpauloOtherwise it returns <b>nil</b> plus a string describing the error. 9897280405Srpaulo 9898280405Srpaulo 9899280405Srpaulo 9900280405Srpaulo 9901280405Srpaulo 9902280405Srpaulo 9903280405Srpaulo 9904280405Srpaulo<h2>6.9 – <a name="6.9">Operating System Facilities</a></h2> 9905280405Srpaulo 9906280405Srpaulo<p> 9907280405SrpauloThis library is implemented through table <a name="pdf-os"><code>os</code></a>. 9908280405Srpaulo 9909280405Srpaulo 9910280405Srpaulo<p> 9911280405Srpaulo<hr><h3><a name="pdf-os.clock"><code>os.clock ()</code></a></h3> 9912280405Srpaulo 9913280405Srpaulo 9914280405Srpaulo<p> 9915280405SrpauloReturns an approximation of the amount in seconds of CPU time 9916280405Srpauloused by the program. 9917280405Srpaulo 9918280405Srpaulo 9919280405Srpaulo 9920280405Srpaulo 9921280405Srpaulo<p> 9922280405Srpaulo<hr><h3><a name="pdf-os.date"><code>os.date ([format [, time]])</code></a></h3> 9923280405Srpaulo 9924280405Srpaulo 9925280405Srpaulo<p> 9926280405SrpauloReturns a string or a table containing date and time, 9927280405Srpauloformatted according to the given string <code>format</code>. 9928280405Srpaulo 9929280405Srpaulo 9930280405Srpaulo<p> 9931280405SrpauloIf the <code>time</code> argument is present, 9932280405Srpaulothis is the time to be formatted 9933280405Srpaulo(see the <a href="#pdf-os.time"><code>os.time</code></a> function for a description of this value). 9934280405SrpauloOtherwise, <code>date</code> formats the current time. 9935280405Srpaulo 9936280405Srpaulo 9937280405Srpaulo<p> 9938280405SrpauloIf <code>format</code> starts with '<code>!</code>', 9939280405Srpaulothen the date is formatted in Coordinated Universal Time. 9940280405SrpauloAfter this optional character, 9941280405Srpauloif <code>format</code> is the string "<code>*t</code>", 9942280405Srpaulothen <code>date</code> returns a table with the following fields: 9943326344Simp<code>year</code>, <code>month</code> (1–12), <code>day</code> (1–31), 9944280405Srpaulo<code>hour</code> (0–23), <code>min</code> (0–59), <code>sec</code> (0–61), 9945326344Simp<code>wday</code> (weekday, 1–7, Sunday is 1), 9946326344Simp<code>yday</code> (day of the year, 1–366), 9947280405Srpauloand <code>isdst</code> (daylight saving flag, a boolean). 9948280405SrpauloThis last field may be absent 9949280405Srpauloif the information is not available. 9950280405Srpaulo 9951280405Srpaulo 9952280405Srpaulo<p> 9953280405SrpauloIf <code>format</code> is not "<code>*t</code>", 9954280405Srpaulothen <code>date</code> returns the date as a string, 9955280405Srpauloformatted according to the same rules as the ISO C function <code>strftime</code>. 9956280405Srpaulo 9957280405Srpaulo 9958280405Srpaulo<p> 9959280405SrpauloWhen called without arguments, 9960280405Srpaulo<code>date</code> returns a reasonable date and time representation that depends on 9961326344Simpthe host system and on the current locale. 9962326344Simp(More specifically, <code>os.date()</code> is equivalent to <code>os.date("%c")</code>.) 9963280405Srpaulo 9964280405Srpaulo 9965280405Srpaulo<p> 9966280405SrpauloOn non-POSIX systems, 9967280405Srpaulothis function may be not thread safe 9968280405Srpaulobecause of its reliance on C function <code>gmtime</code> and C function <code>localtime</code>. 9969280405Srpaulo 9970280405Srpaulo 9971280405Srpaulo 9972280405Srpaulo 9973280405Srpaulo<p> 9974280405Srpaulo<hr><h3><a name="pdf-os.difftime"><code>os.difftime (t2, t1)</code></a></h3> 9975280405Srpaulo 9976280405Srpaulo 9977280405Srpaulo<p> 9978280405SrpauloReturns the difference, in seconds, 9979280405Srpaulofrom time <code>t1</code> to time <code>t2</code> 9980280405Srpaulo(where the times are values returned by <a href="#pdf-os.time"><code>os.time</code></a>). 9981280405SrpauloIn POSIX, Windows, and some other systems, 9982280405Srpaulothis value is exactly <code>t2</code><em>-</em><code>t1</code>. 9983280405Srpaulo 9984280405Srpaulo 9985280405Srpaulo 9986280405Srpaulo 9987280405Srpaulo<p> 9988280405Srpaulo<hr><h3><a name="pdf-os.execute"><code>os.execute ([command])</code></a></h3> 9989280405Srpaulo 9990280405Srpaulo 9991280405Srpaulo<p> 9992280405SrpauloThis function is equivalent to the ISO C function <code>system</code>. 9993280405SrpauloIt passes <code>command</code> to be executed by an operating system shell. 9994280405SrpauloIts first result is <b>true</b> 9995280405Srpauloif the command terminated successfully, 9996280405Srpauloor <b>nil</b> otherwise. 9997280405SrpauloAfter this first result 9998280405Srpaulothe function returns a string plus a number, 9999280405Srpauloas follows: 10000280405Srpaulo 10001280405Srpaulo<ul> 10002280405Srpaulo 10003280405Srpaulo<li><b>"<code>exit</code>": </b> 10004280405Srpaulothe command terminated normally; 10005280405Srpaulothe following number is the exit status of the command. 10006280405Srpaulo</li> 10007280405Srpaulo 10008280405Srpaulo<li><b>"<code>signal</code>": </b> 10009280405Srpaulothe command was terminated by a signal; 10010280405Srpaulothe following number is the signal that terminated the command. 10011280405Srpaulo</li> 10012280405Srpaulo 10013280405Srpaulo</ul> 10014280405Srpaulo 10015280405Srpaulo<p> 10016280405SrpauloWhen called without a <code>command</code>, 10017280405Srpaulo<code>os.execute</code> returns a boolean that is true if a shell is available. 10018280405Srpaulo 10019280405Srpaulo 10020280405Srpaulo 10021280405Srpaulo 10022280405Srpaulo<p> 10023280405Srpaulo<hr><h3><a name="pdf-os.exit"><code>os.exit ([code [, close]])</code></a></h3> 10024280405Srpaulo 10025280405Srpaulo 10026280405Srpaulo<p> 10027280405SrpauloCalls the ISO C function <code>exit</code> to terminate the host program. 10028280405SrpauloIf <code>code</code> is <b>true</b>, 10029280405Srpaulothe returned status is <code>EXIT_SUCCESS</code>; 10030280405Srpauloif <code>code</code> is <b>false</b>, 10031280405Srpaulothe returned status is <code>EXIT_FAILURE</code>; 10032280405Srpauloif <code>code</code> is a number, 10033280405Srpaulothe returned status is this number. 10034280405SrpauloThe default value for <code>code</code> is <b>true</b>. 10035280405Srpaulo 10036280405Srpaulo 10037280405Srpaulo<p> 10038280405SrpauloIf the optional second argument <code>close</code> is true, 10039280405Srpaulocloses the Lua state before exiting. 10040280405Srpaulo 10041280405Srpaulo 10042280405Srpaulo 10043280405Srpaulo 10044280405Srpaulo<p> 10045280405Srpaulo<hr><h3><a name="pdf-os.getenv"><code>os.getenv (varname)</code></a></h3> 10046280405Srpaulo 10047280405Srpaulo 10048280405Srpaulo<p> 10049280405SrpauloReturns the value of the process environment variable <code>varname</code>, 10050280405Srpauloor <b>nil</b> if the variable is not defined. 10051280405Srpaulo 10052280405Srpaulo 10053280405Srpaulo 10054280405Srpaulo 10055280405Srpaulo<p> 10056280405Srpaulo<hr><h3><a name="pdf-os.remove"><code>os.remove (filename)</code></a></h3> 10057280405Srpaulo 10058280405Srpaulo 10059280405Srpaulo<p> 10060280405SrpauloDeletes the file (or empty directory, on POSIX systems) 10061280405Srpaulowith the given name. 10062280405SrpauloIf this function fails, it returns <b>nil</b>, 10063280405Srpauloplus a string describing the error and the error code. 10064326344SimpOtherwise, it returns true. 10065280405Srpaulo 10066280405Srpaulo 10067280405Srpaulo 10068280405Srpaulo 10069280405Srpaulo<p> 10070280405Srpaulo<hr><h3><a name="pdf-os.rename"><code>os.rename (oldname, newname)</code></a></h3> 10071280405Srpaulo 10072280405Srpaulo 10073280405Srpaulo<p> 10074326344SimpRenames the file or directory named <code>oldname</code> to <code>newname</code>. 10075280405SrpauloIf this function fails, it returns <b>nil</b>, 10076280405Srpauloplus a string describing the error and the error code. 10077326344SimpOtherwise, it returns true. 10078280405Srpaulo 10079280405Srpaulo 10080280405Srpaulo 10081280405Srpaulo 10082280405Srpaulo<p> 10083280405Srpaulo<hr><h3><a name="pdf-os.setlocale"><code>os.setlocale (locale [, category])</code></a></h3> 10084280405Srpaulo 10085280405Srpaulo 10086280405Srpaulo<p> 10087280405SrpauloSets the current locale of the program. 10088280405Srpaulo<code>locale</code> is a system-dependent string specifying a locale; 10089280405Srpaulo<code>category</code> is an optional string describing which category to change: 10090280405Srpaulo<code>"all"</code>, <code>"collate"</code>, <code>"ctype"</code>, 10091280405Srpaulo<code>"monetary"</code>, <code>"numeric"</code>, or <code>"time"</code>; 10092280405Srpaulothe default category is <code>"all"</code>. 10093280405SrpauloThe function returns the name of the new locale, 10094280405Srpauloor <b>nil</b> if the request cannot be honored. 10095280405Srpaulo 10096280405Srpaulo 10097280405Srpaulo<p> 10098280405SrpauloIf <code>locale</code> is the empty string, 10099280405Srpaulothe current locale is set to an implementation-defined native locale. 10100280405SrpauloIf <code>locale</code> is the string "<code>C</code>", 10101280405Srpaulothe current locale is set to the standard C locale. 10102280405Srpaulo 10103280405Srpaulo 10104280405Srpaulo<p> 10105280405SrpauloWhen called with <b>nil</b> as the first argument, 10106280405Srpaulothis function only returns the name of the current locale 10107280405Srpaulofor the given category. 10108280405Srpaulo 10109280405Srpaulo 10110280405Srpaulo<p> 10111280405SrpauloThis function may be not thread safe 10112280405Srpaulobecause of its reliance on C function <code>setlocale</code>. 10113280405Srpaulo 10114280405Srpaulo 10115280405Srpaulo 10116280405Srpaulo 10117280405Srpaulo<p> 10118280405Srpaulo<hr><h3><a name="pdf-os.time"><code>os.time ([table])</code></a></h3> 10119280405Srpaulo 10120280405Srpaulo 10121280405Srpaulo<p> 10122280405SrpauloReturns the current time when called without arguments, 10123326344Simpor a time representing the local date and time specified by the given table. 10124280405SrpauloThis table must have fields <code>year</code>, <code>month</code>, and <code>day</code>, 10125280405Srpauloand may have fields 10126280405Srpaulo<code>hour</code> (default is 12), 10127280405Srpaulo<code>min</code> (default is 0), 10128280405Srpaulo<code>sec</code> (default is 0), 10129280405Srpauloand <code>isdst</code> (default is <b>nil</b>). 10130326344SimpOther fields are ignored. 10131280405SrpauloFor a description of these fields, see the <a href="#pdf-os.date"><code>os.date</code></a> function. 10132280405Srpaulo 10133280405Srpaulo 10134280405Srpaulo<p> 10135326344SimpThe values in these fields do not need to be inside their valid ranges. 10136326344SimpFor instance, if <code>sec</code> is -10, 10137326344Simpit means -10 seconds from the time specified by the other fields; 10138326344Simpif <code>hour</code> is 1000, 10139326344Simpit means +1000 hours from the time specified by the other fields. 10140326344Simp 10141326344Simp 10142326344Simp<p> 10143280405SrpauloThe returned value is a number, whose meaning depends on your system. 10144280405SrpauloIn POSIX, Windows, and some other systems, 10145280405Srpaulothis number counts the number 10146280405Srpauloof seconds since some given start time (the "epoch"). 10147280405SrpauloIn other systems, the meaning is not specified, 10148280405Srpauloand the number returned by <code>time</code> can be used only as an argument to 10149280405Srpaulo<a href="#pdf-os.date"><code>os.date</code></a> and <a href="#pdf-os.difftime"><code>os.difftime</code></a>. 10150280405Srpaulo 10151280405Srpaulo 10152280405Srpaulo 10153280405Srpaulo 10154280405Srpaulo<p> 10155280405Srpaulo<hr><h3><a name="pdf-os.tmpname"><code>os.tmpname ()</code></a></h3> 10156280405Srpaulo 10157280405Srpaulo 10158280405Srpaulo<p> 10159280405SrpauloReturns a string with a file name that can 10160280405Srpaulobe used for a temporary file. 10161280405SrpauloThe file must be explicitly opened before its use 10162280405Srpauloand explicitly removed when no longer needed. 10163280405Srpaulo 10164280405Srpaulo 10165280405Srpaulo<p> 10166280405SrpauloOn POSIX systems, 10167280405Srpaulothis function also creates a file with that name, 10168280405Srpauloto avoid security risks. 10169280405Srpaulo(Someone else might create the file with wrong permissions 10170280405Srpauloin the time between getting the name and creating the file.) 10171280405SrpauloYou still have to open the file to use it 10172280405Srpauloand to remove it (even if you do not use it). 10173280405Srpaulo 10174280405Srpaulo 10175280405Srpaulo<p> 10176280405SrpauloWhen possible, 10177280405Srpauloyou may prefer to use <a href="#pdf-io.tmpfile"><code>io.tmpfile</code></a>, 10178280405Srpaulowhich automatically removes the file when the program ends. 10179280405Srpaulo 10180280405Srpaulo 10181280405Srpaulo 10182280405Srpaulo 10183280405Srpaulo 10184280405Srpaulo 10185280405Srpaulo 10186280405Srpaulo<h2>6.10 – <a name="6.10">The Debug Library</a></h2> 10187280405Srpaulo 10188280405Srpaulo<p> 10189280405SrpauloThis library provides 10190280405Srpaulothe functionality of the debug interface (<a href="#4.9">§4.9</a>) to Lua programs. 10191280405SrpauloYou should exert care when using this library. 10192280405SrpauloSeveral of its functions 10193280405Srpauloviolate basic assumptions about Lua code 10194280405Srpaulo(e.g., that variables local to a function 10195280405Srpaulocannot be accessed from outside; 10196280405Srpaulothat userdata metatables cannot be changed by Lua code; 10197280405Srpaulothat Lua programs do not crash) 10198280405Srpauloand therefore can compromise otherwise secure code. 10199280405SrpauloMoreover, some functions in this library may be slow. 10200280405Srpaulo 10201280405Srpaulo 10202280405Srpaulo<p> 10203280405SrpauloAll functions in this library are provided 10204280405Srpauloinside the <a name="pdf-debug"><code>debug</code></a> table. 10205280405SrpauloAll functions that operate over a thread 10206280405Srpaulohave an optional first argument which is the 10207280405Srpaulothread to operate over. 10208280405SrpauloThe default is always the current thread. 10209280405Srpaulo 10210280405Srpaulo 10211280405Srpaulo<p> 10212280405Srpaulo<hr><h3><a name="pdf-debug.debug"><code>debug.debug ()</code></a></h3> 10213280405Srpaulo 10214280405Srpaulo 10215280405Srpaulo<p> 10216280405SrpauloEnters an interactive mode with the user, 10217280405Srpaulorunning each string that the user enters. 10218280405SrpauloUsing simple commands and other debug facilities, 10219280405Srpaulothe user can inspect global and local variables, 10220280405Srpaulochange their values, evaluate expressions, and so on. 10221280405SrpauloA line containing only the word <code>cont</code> finishes this function, 10222280405Srpauloso that the caller continues its execution. 10223280405Srpaulo 10224280405Srpaulo 10225280405Srpaulo<p> 10226280405SrpauloNote that commands for <code>debug.debug</code> are not lexically nested 10227280405Srpaulowithin any function and so have no direct access to local variables. 10228280405Srpaulo 10229280405Srpaulo 10230280405Srpaulo 10231280405Srpaulo 10232280405Srpaulo<p> 10233280405Srpaulo<hr><h3><a name="pdf-debug.gethook"><code>debug.gethook ([thread])</code></a></h3> 10234280405Srpaulo 10235280405Srpaulo 10236280405Srpaulo<p> 10237280405SrpauloReturns the current hook settings of the thread, as three values: 10238280405Srpaulothe current hook function, the current hook mask, 10239280405Srpauloand the current hook count 10240280405Srpaulo(as set by the <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> function). 10241280405Srpaulo 10242280405Srpaulo 10243280405Srpaulo 10244280405Srpaulo 10245280405Srpaulo<p> 10246280405Srpaulo<hr><h3><a name="pdf-debug.getinfo"><code>debug.getinfo ([thread,] f [, what])</code></a></h3> 10247280405Srpaulo 10248280405Srpaulo 10249280405Srpaulo<p> 10250280405SrpauloReturns a table with information about a function. 10251280405SrpauloYou can give the function directly 10252280405Srpauloor you can give a number as the value of <code>f</code>, 10253280405Srpaulowhich means the function running at level <code>f</code> of the call stack 10254280405Srpauloof the given thread: 10255280405Srpaulolevel 0 is the current function (<code>getinfo</code> itself); 10256280405Srpaulolevel 1 is the function that called <code>getinfo</code> 10257280405Srpaulo(except for tail calls, which do not count on the stack); 10258280405Srpauloand so on. 10259280405SrpauloIf <code>f</code> is a number larger than the number of active functions, 10260280405Srpaulothen <code>getinfo</code> returns <b>nil</b>. 10261280405Srpaulo 10262280405Srpaulo 10263280405Srpaulo<p> 10264280405SrpauloThe returned table can contain all the fields returned by <a href="#lua_getinfo"><code>lua_getinfo</code></a>, 10265280405Srpaulowith the string <code>what</code> describing which fields to fill in. 10266280405SrpauloThe default for <code>what</code> is to get all information available, 10267280405Srpauloexcept the table of valid lines. 10268280405SrpauloIf present, 10269280405Srpaulothe option '<code>f</code>' 10270280405Srpauloadds a field named <code>func</code> with the function itself. 10271280405SrpauloIf present, 10272280405Srpaulothe option '<code>L</code>' 10273280405Srpauloadds a field named <code>activelines</code> with the table of 10274280405Srpaulovalid lines. 10275280405Srpaulo 10276280405Srpaulo 10277280405Srpaulo<p> 10278280405SrpauloFor instance, the expression <code>debug.getinfo(1,"n").name</code> returns 10279326344Simpa name for the current function, 10280280405Srpauloif a reasonable name can be found, 10281280405Srpauloand the expression <code>debug.getinfo(print)</code> 10282280405Srpauloreturns a table with all available information 10283280405Srpauloabout the <a href="#pdf-print"><code>print</code></a> function. 10284280405Srpaulo 10285280405Srpaulo 10286280405Srpaulo 10287280405Srpaulo 10288280405Srpaulo<p> 10289280405Srpaulo<hr><h3><a name="pdf-debug.getlocal"><code>debug.getlocal ([thread,] f, local)</code></a></h3> 10290280405Srpaulo 10291280405Srpaulo 10292280405Srpaulo<p> 10293280405SrpauloThis function returns the name and the value of the local variable 10294280405Srpaulowith index <code>local</code> of the function at level <code>f</code> of the stack. 10295280405SrpauloThis function accesses not only explicit local variables, 10296280405Srpaulobut also parameters, temporaries, etc. 10297280405Srpaulo 10298280405Srpaulo 10299280405Srpaulo<p> 10300280405SrpauloThe first parameter or local variable has index 1, and so on, 10301280405Srpaulofollowing the order that they are declared in the code, 10302280405Srpaulocounting only the variables that are active 10303280405Srpauloin the current scope of the function. 10304280405SrpauloNegative indices refer to vararg parameters; 10305280405Srpaulo-1 is the first vararg parameter. 10306280405SrpauloThe function returns <b>nil</b> if there is no variable with the given index, 10307280405Srpauloand raises an error when called with a level out of range. 10308280405Srpaulo(You can call <a href="#pdf-debug.getinfo"><code>debug.getinfo</code></a> to check whether the level is valid.) 10309280405Srpaulo 10310280405Srpaulo 10311280405Srpaulo<p> 10312280405SrpauloVariable names starting with '<code>(</code>' (open parenthesis) 10313280405Srpaulorepresent variables with no known names 10314280405Srpaulo(internal variables such as loop control variables, 10315280405Srpauloand variables from chunks saved without debug information). 10316280405Srpaulo 10317280405Srpaulo 10318280405Srpaulo<p> 10319280405SrpauloThe parameter <code>f</code> may also be a function. 10320280405SrpauloIn that case, <code>getlocal</code> returns only the name of function parameters. 10321280405Srpaulo 10322280405Srpaulo 10323280405Srpaulo 10324280405Srpaulo 10325280405Srpaulo<p> 10326280405Srpaulo<hr><h3><a name="pdf-debug.getmetatable"><code>debug.getmetatable (value)</code></a></h3> 10327280405Srpaulo 10328280405Srpaulo 10329280405Srpaulo<p> 10330280405SrpauloReturns the metatable of the given <code>value</code> 10331280405Srpauloor <b>nil</b> if it does not have a metatable. 10332280405Srpaulo 10333280405Srpaulo 10334280405Srpaulo 10335280405Srpaulo 10336280405Srpaulo<p> 10337280405Srpaulo<hr><h3><a name="pdf-debug.getregistry"><code>debug.getregistry ()</code></a></h3> 10338280405Srpaulo 10339280405Srpaulo 10340280405Srpaulo<p> 10341280405SrpauloReturns the registry table (see <a href="#4.5">§4.5</a>). 10342280405Srpaulo 10343280405Srpaulo 10344280405Srpaulo 10345280405Srpaulo 10346280405Srpaulo<p> 10347280405Srpaulo<hr><h3><a name="pdf-debug.getupvalue"><code>debug.getupvalue (f, up)</code></a></h3> 10348280405Srpaulo 10349280405Srpaulo 10350280405Srpaulo<p> 10351280405SrpauloThis function returns the name and the value of the upvalue 10352280405Srpaulowith index <code>up</code> of the function <code>f</code>. 10353280405SrpauloThe function returns <b>nil</b> if there is no upvalue with the given index. 10354280405Srpaulo 10355280405Srpaulo 10356280405Srpaulo<p> 10357280405SrpauloVariable names starting with '<code>(</code>' (open parenthesis) 10358280405Srpaulorepresent variables with no known names 10359280405Srpaulo(variables from chunks saved without debug information). 10360280405Srpaulo 10361280405Srpaulo 10362280405Srpaulo 10363280405Srpaulo 10364280405Srpaulo<p> 10365280405Srpaulo<hr><h3><a name="pdf-debug.getuservalue"><code>debug.getuservalue (u)</code></a></h3> 10366280405Srpaulo 10367280405Srpaulo 10368280405Srpaulo<p> 10369280405SrpauloReturns the Lua value associated to <code>u</code>. 10370326344SimpIf <code>u</code> is not a full userdata, 10371280405Srpauloreturns <b>nil</b>. 10372280405Srpaulo 10373280405Srpaulo 10374280405Srpaulo 10375280405Srpaulo 10376280405Srpaulo<p> 10377280405Srpaulo<hr><h3><a name="pdf-debug.sethook"><code>debug.sethook ([thread,] hook, mask [, count])</code></a></h3> 10378280405Srpaulo 10379280405Srpaulo 10380280405Srpaulo<p> 10381280405SrpauloSets the given function as a hook. 10382280405SrpauloThe string <code>mask</code> and the number <code>count</code> describe 10383280405Srpaulowhen the hook will be called. 10384280405SrpauloThe string mask may have any combination of the following characters, 10385280405Srpaulowith the given meaning: 10386280405Srpaulo 10387280405Srpaulo<ul> 10388280405Srpaulo<li><b>'<code>c</code>': </b> the hook is called every time Lua calls a function;</li> 10389280405Srpaulo<li><b>'<code>r</code>': </b> the hook is called every time Lua returns from a function;</li> 10390280405Srpaulo<li><b>'<code>l</code>': </b> the hook is called every time Lua enters a new line of code.</li> 10391280405Srpaulo</ul><p> 10392280405SrpauloMoreover, 10393280405Srpaulowith a <code>count</code> different from zero, 10394280405Srpaulothe hook is called also after every <code>count</code> instructions. 10395280405Srpaulo 10396280405Srpaulo 10397280405Srpaulo<p> 10398280405SrpauloWhen called without arguments, 10399280405Srpaulo<a href="#pdf-debug.sethook"><code>debug.sethook</code></a> turns off the hook. 10400280405Srpaulo 10401280405Srpaulo 10402280405Srpaulo<p> 10403280405SrpauloWhen the hook is called, its first parameter is a string 10404280405Srpaulodescribing the event that has triggered its call: 10405280405Srpaulo<code>"call"</code> (or <code>"tail call"</code>), 10406280405Srpaulo<code>"return"</code>, 10407280405Srpaulo<code>"line"</code>, and <code>"count"</code>. 10408280405SrpauloFor line events, 10409280405Srpaulothe hook also gets the new line number as its second parameter. 10410280405SrpauloInside a hook, 10411280405Srpauloyou can call <code>getinfo</code> with level 2 to get more information about 10412280405Srpaulothe running function 10413280405Srpaulo(level 0 is the <code>getinfo</code> function, 10414280405Srpauloand level 1 is the hook function). 10415280405Srpaulo 10416280405Srpaulo 10417280405Srpaulo 10418280405Srpaulo 10419280405Srpaulo<p> 10420280405Srpaulo<hr><h3><a name="pdf-debug.setlocal"><code>debug.setlocal ([thread,] level, local, value)</code></a></h3> 10421280405Srpaulo 10422280405Srpaulo 10423280405Srpaulo<p> 10424280405SrpauloThis function assigns the value <code>value</code> to the local variable 10425280405Srpaulowith index <code>local</code> of the function at level <code>level</code> of the stack. 10426280405SrpauloThe function returns <b>nil</b> if there is no local 10427280405Srpaulovariable with the given index, 10428280405Srpauloand raises an error when called with a <code>level</code> out of range. 10429280405Srpaulo(You can call <code>getinfo</code> to check whether the level is valid.) 10430280405SrpauloOtherwise, it returns the name of the local variable. 10431280405Srpaulo 10432280405Srpaulo 10433280405Srpaulo<p> 10434280405SrpauloSee <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for more information about 10435280405Srpaulovariable indices and names. 10436280405Srpaulo 10437280405Srpaulo 10438280405Srpaulo 10439280405Srpaulo 10440280405Srpaulo<p> 10441280405Srpaulo<hr><h3><a name="pdf-debug.setmetatable"><code>debug.setmetatable (value, table)</code></a></h3> 10442280405Srpaulo 10443280405Srpaulo 10444280405Srpaulo<p> 10445280405SrpauloSets the metatable for the given <code>value</code> to the given <code>table</code> 10446280405Srpaulo(which can be <b>nil</b>). 10447280405SrpauloReturns <code>value</code>. 10448280405Srpaulo 10449280405Srpaulo 10450280405Srpaulo 10451280405Srpaulo 10452280405Srpaulo<p> 10453280405Srpaulo<hr><h3><a name="pdf-debug.setupvalue"><code>debug.setupvalue (f, up, value)</code></a></h3> 10454280405Srpaulo 10455280405Srpaulo 10456280405Srpaulo<p> 10457280405SrpauloThis function assigns the value <code>value</code> to the upvalue 10458280405Srpaulowith index <code>up</code> of the function <code>f</code>. 10459280405SrpauloThe function returns <b>nil</b> if there is no upvalue 10460280405Srpaulowith the given index. 10461280405SrpauloOtherwise, it returns the name of the upvalue. 10462280405Srpaulo 10463280405Srpaulo 10464280405Srpaulo 10465280405Srpaulo 10466280405Srpaulo<p> 10467280405Srpaulo<hr><h3><a name="pdf-debug.setuservalue"><code>debug.setuservalue (udata, value)</code></a></h3> 10468280405Srpaulo 10469280405Srpaulo 10470280405Srpaulo<p> 10471280405SrpauloSets the given <code>value</code> as 10472280405Srpaulothe Lua value associated to the given <code>udata</code>. 10473280405Srpaulo<code>udata</code> must be a full userdata. 10474280405Srpaulo 10475280405Srpaulo 10476280405Srpaulo<p> 10477280405SrpauloReturns <code>udata</code>. 10478280405Srpaulo 10479280405Srpaulo 10480280405Srpaulo 10481280405Srpaulo 10482280405Srpaulo<p> 10483280405Srpaulo<hr><h3><a name="pdf-debug.traceback"><code>debug.traceback ([thread,] [message [, level]])</code></a></h3> 10484280405Srpaulo 10485280405Srpaulo 10486280405Srpaulo<p> 10487280405SrpauloIf <code>message</code> is present but is neither a string nor <b>nil</b>, 10488280405Srpaulothis function returns <code>message</code> without further processing. 10489280405SrpauloOtherwise, 10490280405Srpauloit returns a string with a traceback of the call stack. 10491280405SrpauloThe optional <code>message</code> string is appended 10492280405Srpauloat the beginning of the traceback. 10493280405SrpauloAn optional <code>level</code> number tells at which level 10494280405Srpauloto start the traceback 10495280405Srpaulo(default is 1, the function calling <code>traceback</code>). 10496280405Srpaulo 10497280405Srpaulo 10498280405Srpaulo 10499280405Srpaulo 10500280405Srpaulo<p> 10501280405Srpaulo<hr><h3><a name="pdf-debug.upvalueid"><code>debug.upvalueid (f, n)</code></a></h3> 10502280405Srpaulo 10503280405Srpaulo 10504280405Srpaulo<p> 10505280405SrpauloReturns a unique identifier (as a light userdata) 10506280405Srpaulofor the upvalue numbered <code>n</code> 10507280405Srpaulofrom the given function. 10508280405Srpaulo 10509280405Srpaulo 10510280405Srpaulo<p> 10511280405SrpauloThese unique identifiers allow a program to check whether different 10512280405Srpauloclosures share upvalues. 10513280405SrpauloLua closures that share an upvalue 10514280405Srpaulo(that is, that access a same external local variable) 10515280405Srpaulowill return identical ids for those upvalue indices. 10516280405Srpaulo 10517280405Srpaulo 10518280405Srpaulo 10519280405Srpaulo 10520280405Srpaulo<p> 10521280405Srpaulo<hr><h3><a name="pdf-debug.upvaluejoin"><code>debug.upvaluejoin (f1, n1, f2, n2)</code></a></h3> 10522280405Srpaulo 10523280405Srpaulo 10524280405Srpaulo<p> 10525280405SrpauloMake the <code>n1</code>-th upvalue of the Lua closure <code>f1</code> 10526280405Srpaulorefer to the <code>n2</code>-th upvalue of the Lua closure <code>f2</code>. 10527280405Srpaulo 10528280405Srpaulo 10529280405Srpaulo 10530280405Srpaulo 10531280405Srpaulo 10532280405Srpaulo 10533280405Srpaulo 10534280405Srpaulo<h1>7 – <a name="7">Lua Standalone</a></h1> 10535280405Srpaulo 10536280405Srpaulo<p> 10537280405SrpauloAlthough Lua has been designed as an extension language, 10538280405Srpauloto be embedded in a host C program, 10539280405Srpauloit is also frequently used as a standalone language. 10540280405SrpauloAn interpreter for Lua as a standalone language, 10541280405Srpaulocalled simply <code>lua</code>, 10542280405Srpaulois provided with the standard distribution. 10543280405SrpauloThe standalone interpreter includes 10544280405Srpauloall standard libraries, including the debug library. 10545280405SrpauloIts usage is: 10546280405Srpaulo 10547280405Srpaulo<pre> 10548280405Srpaulo lua [options] [script [args]] 10549280405Srpaulo</pre><p> 10550280405SrpauloThe options are: 10551280405Srpaulo 10552280405Srpaulo<ul> 10553280405Srpaulo<li><b><code>-e <em>stat</em></code>: </b> executes string <em>stat</em>;</li> 10554280405Srpaulo<li><b><code>-l <em>mod</em></code>: </b> "requires" <em>mod</em>;</li> 10555280405Srpaulo<li><b><code>-i</code>: </b> enters interactive mode after running <em>script</em>;</li> 10556280405Srpaulo<li><b><code>-v</code>: </b> prints version information;</li> 10557280405Srpaulo<li><b><code>-E</code>: </b> ignores environment variables;</li> 10558280405Srpaulo<li><b><code>--</code>: </b> stops handling options;</li> 10559280405Srpaulo<li><b><code>-</code>: </b> executes <code>stdin</code> as a file and stops handling options.</li> 10560280405Srpaulo</ul><p> 10561280405SrpauloAfter handling its options, <code>lua</code> runs the given <em>script</em>. 10562280405SrpauloWhen called without arguments, 10563280405Srpaulo<code>lua</code> behaves as <code>lua -v -i</code> 10564280405Srpaulowhen the standard input (<code>stdin</code>) is a terminal, 10565280405Srpauloand as <code>lua -</code> otherwise. 10566280405Srpaulo 10567280405Srpaulo 10568280405Srpaulo<p> 10569326344SimpWhen called without option <code>-E</code>, 10570280405Srpaulothe interpreter checks for an environment variable <a name="pdf-LUA_INIT_5_3"><code>LUA_INIT_5_3</code></a> 10571280405Srpaulo(or <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a> if the versioned name is not defined) 10572280405Srpaulobefore running any argument. 10573280405SrpauloIf the variable content has the format <code>@<em>filename</em></code>, 10574280405Srpaulothen <code>lua</code> executes the file. 10575280405SrpauloOtherwise, <code>lua</code> executes the string itself. 10576280405Srpaulo 10577280405Srpaulo 10578280405Srpaulo<p> 10579280405SrpauloWhen called with option <code>-E</code>, 10580280405Srpaulobesides ignoring <code>LUA_INIT</code>, 10581280405SrpauloLua also ignores 10582280405Srpaulothe values of <code>LUA_PATH</code> and <code>LUA_CPATH</code>, 10583280405Srpaulosetting the values of 10584280405Srpaulo<a href="#pdf-package.path"><code>package.path</code></a> and <a href="#pdf-package.cpath"><code>package.cpath</code></a> 10585280405Srpaulowith the default paths defined in <code>luaconf.h</code>. 10586280405Srpaulo 10587280405Srpaulo 10588280405Srpaulo<p> 10589280405SrpauloAll options are handled in order, except <code>-i</code> and <code>-E</code>. 10590280405SrpauloFor instance, an invocation like 10591280405Srpaulo 10592280405Srpaulo<pre> 10593280405Srpaulo $ lua -e'a=1' -e 'print(a)' script.lua 10594280405Srpaulo</pre><p> 10595280405Srpaulowill first set <code>a</code> to 1, then print the value of <code>a</code>, 10596280405Srpauloand finally run the file <code>script.lua</code> with no arguments. 10597280405Srpaulo(Here <code>$</code> is the shell prompt. Your prompt may be different.) 10598280405Srpaulo 10599280405Srpaulo 10600280405Srpaulo<p> 10601280405SrpauloBefore running any code, 10602280405Srpaulo<code>lua</code> collects all command-line arguments 10603280405Srpauloin a global table called <code>arg</code>. 10604280405SrpauloThe script name goes to index 0, 10605280405Srpaulothe first argument after the script name goes to index 1, 10606280405Srpauloand so on. 10607280405SrpauloAny arguments before the script name 10608280405Srpaulo(that is, the interpreter name plus its options) 10609280405Srpaulogo to negative indices. 10610280405SrpauloFor instance, in the call 10611280405Srpaulo 10612280405Srpaulo<pre> 10613280405Srpaulo $ lua -la b.lua t1 t2 10614280405Srpaulo</pre><p> 10615280405Srpaulothe table is like this: 10616280405Srpaulo 10617280405Srpaulo<pre> 10618280405Srpaulo arg = { [-2] = "lua", [-1] = "-la", 10619280405Srpaulo [0] = "b.lua", 10620280405Srpaulo [1] = "t1", [2] = "t2" } 10621280405Srpaulo</pre><p> 10622280405SrpauloIf there is no script in the call, 10623280405Srpaulothe interpreter name goes to index 0, 10624280405Srpaulofollowed by the other arguments. 10625280405SrpauloFor instance, the call 10626280405Srpaulo 10627280405Srpaulo<pre> 10628280405Srpaulo $ lua -e "print(arg[1])" 10629280405Srpaulo</pre><p> 10630280405Srpaulowill print "<code>-e</code>". 10631280405SrpauloIf there is a script, 10632280405Srpaulothe script is called with parameters 10633280405Srpaulo<code>arg[1]</code>, ···, <code>arg[#arg]</code>. 10634280405Srpaulo(Like all chunks in Lua, 10635280405Srpaulothe script is compiled as a vararg function.) 10636280405Srpaulo 10637280405Srpaulo 10638280405Srpaulo<p> 10639280405SrpauloIn interactive mode, 10640280405SrpauloLua repeatedly prompts and waits for a line. 10641280405SrpauloAfter reading a line, 10642280405SrpauloLua first try to interpret the line as an expression. 10643280405SrpauloIf it succeeds, it prints its value. 10644280405SrpauloOtherwise, it interprets the line as a statement. 10645280405SrpauloIf you write an incomplete statement, 10646280405Srpaulothe interpreter waits for its completion 10647280405Srpauloby issuing a different prompt. 10648280405Srpaulo 10649280405Srpaulo 10650280405Srpaulo<p> 10651326344SimpIf the global variable <a name="pdf-_PROMPT"><code>_PROMPT</code></a> contains a string, 10652326344Simpthen its value is used as the prompt. 10653326344SimpSimilarly, if the global variable <a name="pdf-_PROMPT2"><code>_PROMPT2</code></a> contains a string, 10654326344Simpits value is used as the secondary prompt 10655326344Simp(issued during incomplete statements). 10656326344Simp 10657326344Simp 10658326344Simp<p> 10659280405SrpauloIn case of unprotected errors in the script, 10660280405Srpaulothe interpreter reports the error to the standard error stream. 10661326344SimpIf the error object is not a string but 10662280405Srpaulohas a metamethod <code>__tostring</code>, 10663280405Srpaulothe interpreter calls this metamethod to produce the final message. 10664280405SrpauloOtherwise, the interpreter converts the error object to a string 10665280405Srpauloand adds a stack traceback to it. 10666280405Srpaulo 10667280405Srpaulo 10668280405Srpaulo<p> 10669280405SrpauloWhen finishing normally, 10670280405Srpaulothe interpreter closes its main Lua state 10671280405Srpaulo(see <a href="#lua_close"><code>lua_close</code></a>). 10672280405SrpauloThe script can avoid this step by 10673280405Srpaulocalling <a href="#pdf-os.exit"><code>os.exit</code></a> to terminate. 10674280405Srpaulo 10675280405Srpaulo 10676280405Srpaulo<p> 10677280405SrpauloTo allow the use of Lua as a 10678280405Srpauloscript interpreter in Unix systems, 10679280405Srpaulothe standalone interpreter skips 10680280405Srpaulothe first line of a chunk if it starts with <code>#</code>. 10681280405SrpauloTherefore, Lua scripts can be made into executable programs 10682280405Srpauloby using <code>chmod +x</code> and the <code>#!</code> form, 10683280405Srpauloas in 10684280405Srpaulo 10685280405Srpaulo<pre> 10686280405Srpaulo #!/usr/local/bin/lua 10687280405Srpaulo</pre><p> 10688280405Srpaulo(Of course, 10689280405Srpaulothe location of the Lua interpreter may be different in your machine. 10690280405SrpauloIf <code>lua</code> is in your <code>PATH</code>, 10691280405Srpaulothen 10692280405Srpaulo 10693280405Srpaulo<pre> 10694280405Srpaulo #!/usr/bin/env lua 10695280405Srpaulo</pre><p> 10696280405Srpaulois a more portable solution.) 10697280405Srpaulo 10698280405Srpaulo 10699280405Srpaulo 10700280405Srpaulo<h1>8 – <a name="8">Incompatibilities with the Previous Version</a></h1> 10701280405Srpaulo 10702280405Srpaulo<p> 10703280405SrpauloHere we list the incompatibilities that you may find when moving a program 10704280405Srpaulofrom Lua 5.2 to Lua 5.3. 10705280405SrpauloYou can avoid some incompatibilities by compiling Lua with 10706280405Srpauloappropriate options (see file <code>luaconf.h</code>). 10707280405SrpauloHowever, 10708280405Srpauloall these compatibility options will be removed in the future. 10709280405Srpaulo 10710280405Srpaulo 10711280405Srpaulo<p> 10712280405SrpauloLua versions can always change the C API in ways that 10713280405Srpaulodo not imply source-code changes in a program, 10714280405Srpaulosuch as the numeric values for constants 10715280405Srpauloor the implementation of functions as macros. 10716280405SrpauloTherefore, 10717280405Srpauloyou should not assume that binaries are compatible between 10718280405Srpaulodifferent Lua versions. 10719280405SrpauloAlways recompile clients of the Lua API when 10720280405Srpaulousing a new version. 10721280405Srpaulo 10722280405Srpaulo 10723280405Srpaulo<p> 10724280405SrpauloSimilarly, Lua versions can always change the internal representation 10725280405Srpauloof precompiled chunks; 10726280405Srpauloprecompiled chunks are not compatible between different Lua versions. 10727280405Srpaulo 10728280405Srpaulo 10729280405Srpaulo<p> 10730280405SrpauloThe standard paths in the official distribution may 10731280405Srpaulochange between versions. 10732280405Srpaulo 10733280405Srpaulo 10734280405Srpaulo 10735280405Srpaulo<h2>8.1 – <a name="8.1">Changes in the Language</a></h2> 10736280405Srpaulo<ul> 10737280405Srpaulo 10738280405Srpaulo<li> 10739280405SrpauloThe main difference between Lua 5.2 and Lua 5.3 is the 10740280405Srpaulointroduction of an integer subtype for numbers. 10741280405SrpauloAlthough this change should not affect "normal" computations, 10742280405Srpaulosome computations 10743280405Srpaulo(mainly those that involve some kind of overflow) 10744280405Srpaulocan give different results. 10745280405Srpaulo 10746280405Srpaulo 10747280405Srpaulo<p> 10748280405SrpauloYou can fix these differences by forcing a number to be a float 10749280405Srpaulo(in Lua 5.2 all numbers were float), 10750280405Srpauloin particular writing constants with an ending <code>.0</code> 10751280405Srpauloor using <code>x = x + 0.0</code> to convert a variable. 10752280405Srpaulo(This recommendation is only for a quick fix 10753280405Srpaulofor an occasional incompatibility; 10754280405Srpauloit is not a general guideline for good programming. 10755280405SrpauloFor good programming, 10756280405Srpaulouse floats where you need floats 10757280405Srpauloand integers where you need integers.) 10758280405Srpaulo</li> 10759280405Srpaulo 10760280405Srpaulo<li> 10761280405SrpauloThe conversion of a float to a string now adds a <code>.0</code> suffix 10762280405Srpauloto the result if it looks like an integer. 10763280405Srpaulo(For instance, the float 2.0 will be printed as <code>2.0</code>, 10764280405Srpaulonot as <code>2</code>.) 10765280405SrpauloYou should always use an explicit format 10766280405Srpaulowhen you need a specific format for numbers. 10767280405Srpaulo 10768280405Srpaulo 10769280405Srpaulo<p> 10770280405Srpaulo(Formally this is not an incompatibility, 10771280405Srpaulobecause Lua does not specify how numbers are formatted as strings, 10772280405Srpaulobut some programs assumed a specific format.) 10773280405Srpaulo</li> 10774280405Srpaulo 10775280405Srpaulo<li> 10776280405SrpauloThe generational mode for the garbage collector was removed. 10777280405Srpaulo(It was an experimental feature in Lua 5.2.) 10778280405Srpaulo</li> 10779280405Srpaulo 10780280405Srpaulo</ul> 10781280405Srpaulo 10782280405Srpaulo 10783280405Srpaulo 10784280405Srpaulo 10785280405Srpaulo<h2>8.2 – <a name="8.2">Changes in the Libraries</a></h2> 10786280405Srpaulo<ul> 10787280405Srpaulo 10788280405Srpaulo<li> 10789280405SrpauloThe <code>bit32</code> library has been deprecated. 10790280405SrpauloIt is easy to require a compatible external library or, 10791280405Srpaulobetter yet, to replace its functions with appropriate bitwise operations. 10792280405Srpaulo(Keep in mind that <code>bit32</code> operates on 32-bit integers, 10793326344Simpwhile the bitwise operators in Lua 5.3 operate on Lua integers, 10794326344Simpwhich by default have 64 bits.) 10795280405Srpaulo</li> 10796280405Srpaulo 10797280405Srpaulo<li> 10798280405SrpauloThe Table library now respects metamethods 10799280405Srpaulofor setting and getting elements. 10800280405Srpaulo</li> 10801280405Srpaulo 10802280405Srpaulo<li> 10803280405SrpauloThe <a href="#pdf-ipairs"><code>ipairs</code></a> iterator now respects metamethods and 10804280405Srpauloits <code>__ipairs</code> metamethod has been deprecated. 10805280405Srpaulo</li> 10806280405Srpaulo 10807280405Srpaulo<li> 10808280405SrpauloOption names in <a href="#pdf-io.read"><code>io.read</code></a> do not have a starting '<code>*</code>' anymore. 10809326344SimpFor compatibility, Lua will continue to accept (and ignore) this character. 10810280405Srpaulo</li> 10811280405Srpaulo 10812280405Srpaulo<li> 10813280405SrpauloThe following functions were deprecated in the mathematical library: 10814280405Srpaulo<code>atan2</code>, <code>cosh</code>, <code>sinh</code>, <code>tanh</code>, <code>pow</code>, 10815280405Srpaulo<code>frexp</code>, and <code>ldexp</code>. 10816280405SrpauloYou can replace <code>math.pow(x,y)</code> with <code>x^y</code>; 10817280405Srpauloyou can replace <code>math.atan2</code> with <code>math.atan</code>, 10818280405Srpaulowhich now accepts one or two parameters; 10819280405Srpauloyou can replace <code>math.ldexp(x,exp)</code> with <code>x * 2.0^exp</code>. 10820280405SrpauloFor the other operations, 10821280405Srpauloyou can either use an external library or 10822280405Srpauloimplement them in Lua. 10823280405Srpaulo</li> 10824280405Srpaulo 10825280405Srpaulo<li> 10826280405SrpauloThe searcher for C loaders used by <a href="#pdf-require"><code>require</code></a> 10827280405Srpaulochanged the way it handles versioned names. 10828280405SrpauloNow, the version should come after the module name 10829280405Srpaulo(as is usual in most other tools). 10830280405SrpauloFor compatibility, that searcher still tries the old format 10831280405Srpauloif it cannot find an open function according to the new style. 10832280405Srpaulo(Lua 5.2 already worked that way, 10833280405Srpaulobut it did not document the change.) 10834280405Srpaulo</li> 10835280405Srpaulo 10836326344Simp<li> 10837326344SimpThe call <code>collectgarbage("count")</code> now returns only one result. 10838326344Simp(You can compute that second result from the fractional part 10839326344Simpof the first result.) 10840326344Simp</li> 10841326344Simp 10842280405Srpaulo</ul> 10843280405Srpaulo 10844280405Srpaulo 10845280405Srpaulo 10846280405Srpaulo 10847280405Srpaulo<h2>8.3 – <a name="8.3">Changes in the API</a></h2> 10848280405Srpaulo 10849280405Srpaulo 10850280405Srpaulo<ul> 10851280405Srpaulo 10852280405Srpaulo<li> 10853280405SrpauloContinuation functions now receive as parameters what they needed 10854280405Srpauloto get through <code>lua_getctx</code>, 10855280405Srpauloso <code>lua_getctx</code> has been removed. 10856280405SrpauloAdapt your code accordingly. 10857280405Srpaulo</li> 10858280405Srpaulo 10859280405Srpaulo<li> 10860280405SrpauloFunction <a href="#lua_dump"><code>lua_dump</code></a> has an extra parameter, <code>strip</code>. 10861280405SrpauloUse 0 as the value of this parameter to get the old behavior. 10862280405Srpaulo</li> 10863280405Srpaulo 10864280405Srpaulo<li> 10865280405SrpauloFunctions to inject/project unsigned integers 10866280405Srpaulo(<code>lua_pushunsigned</code>, <code>lua_tounsigned</code>, <code>lua_tounsignedx</code>, 10867280405Srpaulo<code>luaL_checkunsigned</code>, <code>luaL_optunsigned</code>) 10868280405Srpaulowere deprecated. 10869280405SrpauloUse their signed equivalents with a type cast. 10870280405Srpaulo</li> 10871280405Srpaulo 10872280405Srpaulo<li> 10873280405SrpauloMacros to project non-default integer types 10874280405Srpaulo(<code>luaL_checkint</code>, <code>luaL_optint</code>, <code>luaL_checklong</code>, <code>luaL_optlong</code>) 10875280405Srpaulowere deprecated. 10876280405SrpauloUse their equivalent over <a href="#lua_Integer"><code>lua_Integer</code></a> with a type cast 10877280405Srpaulo(or, when possible, use <a href="#lua_Integer"><code>lua_Integer</code></a> in your code). 10878280405Srpaulo</li> 10879280405Srpaulo 10880280405Srpaulo</ul> 10881280405Srpaulo 10882280405Srpaulo 10883280405Srpaulo 10884280405Srpaulo 10885280405Srpaulo<h1>9 – <a name="9">The Complete Syntax of Lua</a></h1> 10886280405Srpaulo 10887280405Srpaulo<p> 10888280405SrpauloHere is the complete syntax of Lua in extended BNF. 10889280405SrpauloAs usual in extended BNF, 10890280405Srpaulo{A} means 0 or more As, 10891280405Srpauloand [A] means an optional A. 10892280405Srpaulo(For operator precedences, see <a href="#3.4.8">§3.4.8</a>; 10893280405Srpaulofor a description of the terminals 10894280405SrpauloName, Numeral, 10895280405Srpauloand LiteralString, see <a href="#3.1">§3.1</a>.) 10896280405Srpaulo 10897280405Srpaulo 10898280405Srpaulo 10899280405Srpaulo 10900280405Srpaulo<pre> 10901280405Srpaulo 10902280405Srpaulo chunk ::= block 10903280405Srpaulo 10904280405Srpaulo block ::= {stat} [retstat] 10905280405Srpaulo 10906280405Srpaulo stat ::= ‘<b>;</b>’ | 10907280405Srpaulo varlist ‘<b>=</b>’ explist | 10908280405Srpaulo functioncall | 10909280405Srpaulo label | 10910280405Srpaulo <b>break</b> | 10911280405Srpaulo <b>goto</b> Name | 10912280405Srpaulo <b>do</b> block <b>end</b> | 10913280405Srpaulo <b>while</b> exp <b>do</b> block <b>end</b> | 10914280405Srpaulo <b>repeat</b> block <b>until</b> exp | 10915280405Srpaulo <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> | 10916280405Srpaulo <b>for</b> Name ‘<b>=</b>’ exp ‘<b>,</b>’ exp [‘<b>,</b>’ exp] <b>do</b> block <b>end</b> | 10917280405Srpaulo <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> | 10918280405Srpaulo <b>function</b> funcname funcbody | 10919280405Srpaulo <b>local</b> <b>function</b> Name funcbody | 10920280405Srpaulo <b>local</b> namelist [‘<b>=</b>’ explist] 10921280405Srpaulo 10922280405Srpaulo retstat ::= <b>return</b> [explist] [‘<b>;</b>’] 10923280405Srpaulo 10924280405Srpaulo label ::= ‘<b>::</b>’ Name ‘<b>::</b>’ 10925280405Srpaulo 10926280405Srpaulo funcname ::= Name {‘<b>.</b>’ Name} [‘<b>:</b>’ Name] 10927280405Srpaulo 10928280405Srpaulo varlist ::= var {‘<b>,</b>’ var} 10929280405Srpaulo 10930280405Srpaulo var ::= Name | prefixexp ‘<b>[</b>’ exp ‘<b>]</b>’ | prefixexp ‘<b>.</b>’ Name 10931280405Srpaulo 10932280405Srpaulo namelist ::= Name {‘<b>,</b>’ Name} 10933280405Srpaulo 10934280405Srpaulo explist ::= exp {‘<b>,</b>’ exp} 10935280405Srpaulo 10936280405Srpaulo exp ::= <b>nil</b> | <b>false</b> | <b>true</b> | Numeral | LiteralString | ‘<b>...</b>’ | functiondef | 10937280405Srpaulo prefixexp | tableconstructor | exp binop exp | unop exp 10938280405Srpaulo 10939280405Srpaulo prefixexp ::= var | functioncall | ‘<b>(</b>’ exp ‘<b>)</b>’ 10940280405Srpaulo 10941280405Srpaulo functioncall ::= prefixexp args | prefixexp ‘<b>:</b>’ Name args 10942280405Srpaulo 10943280405Srpaulo args ::= ‘<b>(</b>’ [explist] ‘<b>)</b>’ | tableconstructor | LiteralString 10944280405Srpaulo 10945280405Srpaulo functiondef ::= <b>function</b> funcbody 10946280405Srpaulo 10947280405Srpaulo funcbody ::= ‘<b>(</b>’ [parlist] ‘<b>)</b>’ block <b>end</b> 10948280405Srpaulo 10949280405Srpaulo parlist ::= namelist [‘<b>,</b>’ ‘<b>...</b>’] | ‘<b>...</b>’ 10950280405Srpaulo 10951280405Srpaulo tableconstructor ::= ‘<b>{</b>’ [fieldlist] ‘<b>}</b>’ 10952280405Srpaulo 10953280405Srpaulo fieldlist ::= field {fieldsep field} [fieldsep] 10954280405Srpaulo 10955280405Srpaulo field ::= ‘<b>[</b>’ exp ‘<b>]</b>’ ‘<b>=</b>’ exp | Name ‘<b>=</b>’ exp | exp 10956280405Srpaulo 10957280405Srpaulo fieldsep ::= ‘<b>,</b>’ | ‘<b>;</b>’ 10958280405Srpaulo 10959280405Srpaulo binop ::= ‘<b>+</b>’ | ‘<b>-</b>’ | ‘<b>*</b>’ | ‘<b>/</b>’ | ‘<b>//</b>’ | ‘<b>^</b>’ | ‘<b>%</b>’ | 10960280405Srpaulo ‘<b>&</b>’ | ‘<b>~</b>’ | ‘<b>|</b>’ | ‘<b>>></b>’ | ‘<b><<</b>’ | ‘<b>..</b>’ | 10961280405Srpaulo ‘<b><</b>’ | ‘<b><=</b>’ | ‘<b>></b>’ | ‘<b>>=</b>’ | ‘<b>==</b>’ | ‘<b>~=</b>’ | 10962280405Srpaulo <b>and</b> | <b>or</b> 10963280405Srpaulo 10964280405Srpaulo unop ::= ‘<b>-</b>’ | <b>not</b> | ‘<b>#</b>’ | ‘<b>~</b>’ 10965280405Srpaulo 10966280405Srpaulo</pre> 10967280405Srpaulo 10968280405Srpaulo<p> 10969280405Srpaulo 10970280405Srpaulo 10971280405Srpaulo 10972280405Srpaulo 10973280405Srpaulo 10974280405Srpaulo 10975280405Srpaulo 10976326344Simp<P CLASS="footer"> 10977280405SrpauloLast update: 10978326344SimpMon Jan 9 13:30:53 BRST 2017 10979326344Simp</P> 10980280405Srpaulo<!-- 10981326344SimpLast change: revised for Lua 5.3.4 10982280405Srpaulo--> 10983280405Srpaulo 10984280405Srpaulo</body></html> 10985280405Srpaulo 10986