manual.html revision 1.9
1 1.1 mbalmer <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2 1.4 mbalmer <HTML> 3 1.4 mbalmer <HEAD> 4 1.9 nikita <TITLE>Lua 5.4 Reference Manual</TITLE> 5 1.4 mbalmer <LINK REL="stylesheet" TYPE="text/css" HREF="lua.css"> 6 1.4 mbalmer <LINK REL="stylesheet" TYPE="text/css" HREF="manual.css"> 7 1.1 mbalmer <META HTTP-EQUIV="content-type" CONTENT="text/html; charset=iso-8859-1"> 8 1.4 mbalmer </HEAD> 9 1.1 mbalmer 10 1.4 mbalmer <BODY> 11 1.1 mbalmer 12 1.4 mbalmer <H1> 13 1.4 mbalmer <A HREF="http://www.lua.org/"><IMG SRC="logo.gif" ALT="Lua"></A> 14 1.9 nikita Lua 5.4 Reference Manual 15 1.4 mbalmer </H1> 16 1.1 mbalmer 17 1.4 mbalmer <P> 18 1.1 mbalmer by Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes 19 1.4 mbalmer 20 1.4 mbalmer <P> 21 1.4 mbalmer <SMALL> 22 1.9 nikita Copyright © 2020–2022 Lua.org, PUC-Rio. 23 1.1 mbalmer Freely available under the terms of the 24 1.2 lneto <a href="http://www.lua.org/license.html">Lua license</a>. 25 1.4 mbalmer </SMALL> 26 1.1 mbalmer 27 1.4 mbalmer <DIV CLASS="menubar"> 28 1.4 mbalmer <A HREF="contents.html#contents">contents</A> 29 1.4 mbalmer · 30 1.4 mbalmer <A HREF="contents.html#index">index</A> 31 1.1 mbalmer · 32 1.4 mbalmer <A HREF="http://www.lua.org/manual/">other versions</A> 33 1.4 mbalmer </DIV> 34 1.1 mbalmer 35 1.1 mbalmer <!-- ====================================================================== --> 36 1.1 mbalmer <p> 37 1.1 mbalmer 38 1.9 nikita <!-- Id: manual.of --> 39 1.1 mbalmer 40 1.1 mbalmer 41 1.1 mbalmer 42 1.1 mbalmer 43 1.2 lneto <h1>1 – <a name="1">Introduction</a></h1> 44 1.1 mbalmer 45 1.1 mbalmer <p> 46 1.6 salazar Lua is a powerful, efficient, lightweight, embeddable scripting language. 47 1.6 salazar It supports procedural programming, 48 1.6 salazar object-oriented programming, functional programming, 49 1.6 salazar data-driven programming, and data description. 50 1.6 salazar 51 1.6 salazar 52 1.6 salazar <p> 53 1.6 salazar Lua combines simple procedural syntax with powerful data description 54 1.6 salazar constructs based on associative arrays and extensible semantics. 55 1.6 salazar Lua is dynamically typed, 56 1.6 salazar runs by interpreting bytecode with a register-based 57 1.6 salazar virtual machine, 58 1.6 salazar and has automatic memory management with 59 1.9 nikita a generational garbage collection, 60 1.6 salazar making it ideal for configuration, scripting, 61 1.6 salazar and rapid prototyping. 62 1.6 salazar 63 1.6 salazar 64 1.6 salazar <p> 65 1.2 lneto Lua is implemented as a library, written in <em>clean C</em>, 66 1.2 lneto the common subset of Standard C and C++. 67 1.6 salazar The Lua distribution includes a host program called <code>lua</code>, 68 1.6 salazar which uses the Lua library to offer a complete, 69 1.6 salazar standalone Lua interpreter, 70 1.6 salazar for interactive or batch use. 71 1.6 salazar Lua is intended to be used both as a powerful, lightweight, 72 1.6 salazar embeddable scripting language for any program that needs one, 73 1.6 salazar and as a powerful but lightweight and efficient stand-alone language. 74 1.1 mbalmer 75 1.1 mbalmer 76 1.1 mbalmer <p> 77 1.3 lneto As an extension language, Lua has no notion of a "main" program: 78 1.6 salazar it works <em>embedded</em> in a host client, 79 1.1 mbalmer called the <em>embedding program</em> or simply the <em>host</em>. 80 1.6 salazar (Frequently, this host is the stand-alone <code>lua</code> program.) 81 1.2 lneto The host program can invoke functions to execute a piece of Lua code, 82 1.1 mbalmer can write and read Lua variables, 83 1.1 mbalmer and can register C functions to be called by Lua code. 84 1.1 mbalmer Through the use of C functions, Lua can be augmented to cope with 85 1.1 mbalmer a wide range of different domains, 86 1.1 mbalmer thus creating customized programming languages sharing a syntactical framework. 87 1.1 mbalmer 88 1.1 mbalmer 89 1.1 mbalmer <p> 90 1.1 mbalmer Lua is free software, 91 1.1 mbalmer and is provided as usual with no guarantees, 92 1.1 mbalmer as stated in its license. 93 1.1 mbalmer The implementation described in this manual is available 94 1.1 mbalmer at Lua's official web site, <code>www.lua.org</code>. 95 1.1 mbalmer 96 1.1 mbalmer 97 1.1 mbalmer <p> 98 1.1 mbalmer Like any other reference manual, 99 1.1 mbalmer this document is dry in places. 100 1.1 mbalmer For a discussion of the decisions behind the design of Lua, 101 1.1 mbalmer see the technical papers available at Lua's web site. 102 1.1 mbalmer For a detailed introduction to programming in Lua, 103 1.2 lneto see Roberto's book, <em>Programming in Lua</em>. 104 1.1 mbalmer 105 1.1 mbalmer 106 1.1 mbalmer 107 1.2 lneto <h1>2 – <a name="2">Basic Concepts</a></h1> 108 1.1 mbalmer 109 1.9 nikita 110 1.9 nikita 111 1.1 mbalmer <p> 112 1.2 lneto This section describes the basic concepts of the language. 113 1.1 mbalmer 114 1.1 mbalmer 115 1.1 mbalmer 116 1.9 nikita 117 1.9 nikita 118 1.2 lneto <h2>2.1 – <a name="2.1">Values and Types</a></h2> 119 1.1 mbalmer 120 1.1 mbalmer <p> 121 1.9 nikita Lua is a dynamically typed language. 122 1.1 mbalmer This means that 123 1.1 mbalmer variables do not have types; only values do. 124 1.1 mbalmer There are no type definitions in the language. 125 1.1 mbalmer All values carry their own type. 126 1.1 mbalmer 127 1.1 mbalmer 128 1.1 mbalmer <p> 129 1.9 nikita All values in Lua are first-class values. 130 1.1 mbalmer This means that all values can be stored in variables, 131 1.1 mbalmer passed as arguments to other functions, and returned as results. 132 1.1 mbalmer 133 1.1 mbalmer 134 1.1 mbalmer <p> 135 1.1 mbalmer There are eight basic types in Lua: 136 1.1 mbalmer <em>nil</em>, <em>boolean</em>, <em>number</em>, 137 1.1 mbalmer <em>string</em>, <em>function</em>, <em>userdata</em>, 138 1.1 mbalmer <em>thread</em>, and <em>table</em>. 139 1.4 mbalmer The type <em>nil</em> has one single value, <b>nil</b>, 140 1.1 mbalmer whose main property is to be different from any other value; 141 1.9 nikita it often represents the absence of a useful value. 142 1.4 mbalmer The type <em>boolean</em> has two values, <b>false</b> and <b>true</b>. 143 1.1 mbalmer Both <b>nil</b> and <b>false</b> make a condition false; 144 1.9 nikita they are collectively called <em>false values</em>. 145 1.9 nikita Any other value makes a condition true. 146 1.9 nikita Despite its name, 147 1.9 nikita <b>false</b> is frequently used as an alternative to <b>nil</b>, 148 1.9 nikita with the key difference that <b>false</b> behaves 149 1.9 nikita like a regular value in a table, 150 1.9 nikita while a <b>nil</b> in a table represents an absent key. 151 1.9 nikita 152 1.9 nikita 153 1.9 nikita <p> 154 1.4 mbalmer The type <em>number</em> represents both 155 1.9 nikita integer numbers and real (floating-point) numbers, 156 1.9 nikita using two subtypes: <em>integer</em> and <em>float</em>. 157 1.9 nikita Standard Lua uses 64-bit integers and double-precision (64-bit) floats, 158 1.9 nikita but you can also compile Lua so that it 159 1.9 nikita uses 32-bit integers and/or single-precision (32-bit) floats. 160 1.9 nikita The option with 32 bits for both integers and floats 161 1.9 nikita is particularly attractive 162 1.9 nikita for small machines and embedded systems. 163 1.9 nikita (See macro <code>LUA_32BITS</code> in file <code>luaconf.h</code>.) 164 1.9 nikita 165 1.1 mbalmer 166 1.9 nikita <p> 167 1.9 nikita Unless stated otherwise, 168 1.9 nikita any overflow when manipulating integer values <em>wrap around</em>, 169 1.9 nikita according to the usual rules of two-complement arithmetic. 170 1.9 nikita (In other words, 171 1.9 nikita the actual result is the unique representable integer 172 1.9 nikita that is equal modulo <em>2<sup>n</sup></em> to the mathematical result, 173 1.9 nikita where <em>n</em> is the number of bits of the integer type.) 174 1.2 lneto 175 1.2 lneto 176 1.2 lneto <p> 177 1.9 nikita Lua has explicit rules about when each subtype is used, 178 1.2 lneto but it also converts between them automatically as needed (see <a href="#3.4.3">§3.4.3</a>). 179 1.2 lneto Therefore, 180 1.3 lneto the programmer may choose to mostly ignore the difference 181 1.2 lneto between integers and floats 182 1.3 lneto or to assume complete control over the representation of each number. 183 1.9 nikita 184 1.9 nikita 185 1.9 nikita <p> 186 1.9 nikita The type <em>string</em> represents immutable sequences of bytes. 187 1.9 nikita 188 1.9 nikita Lua is 8-bit clean: 189 1.9 nikita strings can contain any 8-bit value, 190 1.9 nikita including embedded zeros ('<code>\0</code>'). 191 1.9 nikita Lua is also encoding-agnostic; 192 1.9 nikita it makes no assumptions about the contents of a string. 193 1.9 nikita The length of any string in Lua must fit in a Lua integer. 194 1.1 mbalmer 195 1.1 mbalmer 196 1.1 mbalmer <p> 197 1.1 mbalmer Lua can call (and manipulate) functions written in Lua and 198 1.3 lneto functions written in C (see <a href="#3.4.10">§3.4.10</a>). 199 1.3 lneto Both are represented by the type <em>function</em>. 200 1.1 mbalmer 201 1.1 mbalmer 202 1.1 mbalmer <p> 203 1.1 mbalmer The type <em>userdata</em> is provided to allow arbitrary C data to 204 1.1 mbalmer be stored in Lua variables. 205 1.3 lneto A userdata value represents a block of raw memory. 206 1.2 lneto There are two kinds of userdata: 207 1.3 lneto <em>full userdata</em>, 208 1.3 lneto which is an object with a block of memory managed by Lua, 209 1.3 lneto and <em>light userdata</em>, 210 1.3 lneto which is simply a C pointer value. 211 1.2 lneto Userdata has no predefined operations in Lua, 212 1.1 mbalmer except assignment and identity test. 213 1.2 lneto By using <em>metatables</em>, 214 1.2 lneto the programmer can define operations for full userdata values 215 1.2 lneto (see <a href="#2.4">§2.4</a>). 216 1.1 mbalmer Userdata values cannot be created or modified in Lua, 217 1.1 mbalmer only through the C API. 218 1.9 nikita This guarantees the integrity of data owned by 219 1.9 nikita the host program and C libraries. 220 1.1 mbalmer 221 1.1 mbalmer 222 1.1 mbalmer <p> 223 1.1 mbalmer The type <em>thread</em> represents independent threads of execution 224 1.2 lneto and it is used to implement coroutines (see <a href="#2.6">§2.6</a>). 225 1.3 lneto Lua threads are not related to operating-system threads. 226 1.1 mbalmer Lua supports coroutines on all systems, 227 1.3 lneto even those that do not support threads natively. 228 1.1 mbalmer 229 1.1 mbalmer 230 1.1 mbalmer <p> 231 1.1 mbalmer The type <em>table</em> implements associative arrays, 232 1.8 alnsn that is, arrays that can have as indices not only numbers, 233 1.8 alnsn but any Lua value except <b>nil</b> and NaN. 234 1.9 nikita (<em>Not a Number</em> is a special floating-point value 235 1.9 nikita used by the IEEE 754 standard to represent 236 1.9 nikita undefined numerical results, such as <code>0/0</code>.) 237 1.1 mbalmer Tables can be <em>heterogeneous</em>; 238 1.1 mbalmer that is, they can contain values of all types (except <b>nil</b>). 239 1.9 nikita Any key associated to the value <b>nil</b> is not considered part of the table. 240 1.2 lneto Conversely, any key that is not part of a table has 241 1.2 lneto an associated value <b>nil</b>. 242 1.2 lneto 243 1.2 lneto 244 1.2 lneto <p> 245 1.3 lneto Tables are the sole data-structuring mechanism in Lua; 246 1.7 mbalmer they can be used to represent ordinary arrays, lists, 247 1.1 mbalmer symbol tables, sets, records, graphs, trees, etc. 248 1.1 mbalmer To represent records, Lua uses the field name as an index. 249 1.1 mbalmer The language supports this representation by 250 1.1 mbalmer providing <code>a.name</code> as syntactic sugar for <code>a["name"]</code>. 251 1.1 mbalmer There are several convenient ways to create tables in Lua 252 1.2 lneto (see <a href="#3.4.9">§3.4.9</a>). 253 1.2 lneto 254 1.2 lneto 255 1.2 lneto <p> 256 1.1 mbalmer Like indices, 257 1.2 lneto the values of table fields can be of any type. 258 1.1 mbalmer In particular, 259 1.1 mbalmer because functions are first-class values, 260 1.1 mbalmer table fields can contain functions. 261 1.2 lneto Thus tables can also carry <em>methods</em> (see <a href="#3.4.11">§3.4.11</a>). 262 1.2 lneto 263 1.2 lneto 264 1.2 lneto <p> 265 1.2 lneto The indexing of tables follows 266 1.2 lneto the definition of raw equality in the language. 267 1.2 lneto The expressions <code>a[i]</code> and <code>a[j]</code> 268 1.2 lneto denote the same table element 269 1.2 lneto if and only if <code>i</code> and <code>j</code> are raw equal 270 1.2 lneto (that is, equal without metamethods). 271 1.2 lneto In particular, floats with integral values 272 1.2 lneto are equal to their respective integers 273 1.2 lneto (e.g., <code>1.0 == 1</code>). 274 1.2 lneto To avoid ambiguities, 275 1.9 nikita any float used as a key that is equal to an integer 276 1.9 nikita is converted to that integer. 277 1.2 lneto For instance, if you write <code>a[2.0] = true</code>, 278 1.9 nikita the actual key inserted into the table will be the integer <code>2</code>. 279 1.1 mbalmer 280 1.1 mbalmer 281 1.1 mbalmer <p> 282 1.1 mbalmer Tables, functions, threads, and (full) userdata values are <em>objects</em>: 283 1.1 mbalmer variables do not actually <em>contain</em> these values, 284 1.1 mbalmer only <em>references</em> to them. 285 1.1 mbalmer Assignment, parameter passing, and function returns 286 1.1 mbalmer always manipulate references to such values; 287 1.1 mbalmer these operations do not imply any kind of copy. 288 1.1 mbalmer 289 1.1 mbalmer 290 1.1 mbalmer <p> 291 1.1 mbalmer The library function <a href="#pdf-type"><code>type</code></a> returns a string describing the type 292 1.9 nikita of a given value (see <a href="#pdf-type"><code>type</code></a>). 293 1.2 lneto 294 1.1 mbalmer 295 1.1 mbalmer 296 1.1 mbalmer 297 1.2 lneto 298 1.2 lneto <h2>2.2 – <a name="2.2">Environments and the Global Environment</a></h2> 299 1.1 mbalmer 300 1.1 mbalmer <p> 301 1.9 nikita As we will discuss further in <a href="#3.2">§3.2</a> and <a href="#3.3.3">§3.3.3</a>, 302 1.3 lneto any reference to a free name 303 1.3 lneto (that is, a name not bound to any declaration) <code>var</code> 304 1.3 lneto is syntactically translated to <code>_ENV.var</code>. 305 1.2 lneto Moreover, every chunk is compiled in the scope of 306 1.3 lneto an external local variable named <code>_ENV</code> (see <a href="#3.3.2">§3.3.2</a>), 307 1.3 lneto so <code>_ENV</code> itself is never a free name in a chunk. 308 1.1 mbalmer 309 1.1 mbalmer 310 1.2 lneto <p> 311 1.2 lneto Despite the existence of this external <code>_ENV</code> variable and 312 1.3 lneto the translation of free names, 313 1.2 lneto <code>_ENV</code> is a completely regular name. 314 1.2 lneto In particular, 315 1.2 lneto you can define new variables and parameters with that name. 316 1.3 lneto Each reference to a free name uses the <code>_ENV</code> that is 317 1.2 lneto visible at that point in the program, 318 1.2 lneto following the usual visibility rules of Lua (see <a href="#3.5">§3.5</a>). 319 1.1 mbalmer 320 1.1 mbalmer 321 1.2 lneto <p> 322 1.2 lneto Any table used as the value of <code>_ENV</code> is called an <em>environment</em>. 323 1.1 mbalmer 324 1.1 mbalmer 325 1.2 lneto <p> 326 1.2 lneto Lua keeps a distinguished environment called the <em>global environment</em>. 327 1.9 nikita This value is kept at a special index in the C registry (see <a href="#4.3">§4.3</a>). 328 1.3 lneto In Lua, the global variable <a href="#pdf-_G"><code>_G</code></a> is initialized with this same value. 329 1.9 nikita (<a href="#pdf-_G"><code>_G</code></a> is never used internally, 330 1.9 nikita so changing its value will affect only your own code.) 331 1.1 mbalmer 332 1.1 mbalmer 333 1.1 mbalmer <p> 334 1.3 lneto When Lua loads a chunk, 335 1.9 nikita the default value for its <code>_ENV</code> variable 336 1.3 lneto is the global environment (see <a href="#pdf-load"><code>load</code></a>). 337 1.2 lneto Therefore, by default, 338 1.3 lneto free names in Lua code refer to entries in the global environment 339 1.9 nikita and, therefore, they are also called <em>global variables</em>. 340 1.2 lneto Moreover, all standard libraries are loaded in the global environment 341 1.3 lneto and some functions there operate on that environment. 342 1.2 lneto You can use <a href="#pdf-load"><code>load</code></a> (or <a href="#pdf-loadfile"><code>loadfile</code></a>) 343 1.2 lneto to load a chunk with a different environment. 344 1.2 lneto (In C, you have to load the chunk and then change the value 345 1.9 nikita of its first upvalue; see <a href="#lua_setupvalue"><code>lua_setupvalue</code></a>.) 346 1.1 mbalmer 347 1.1 mbalmer 348 1.1 mbalmer 349 1.1 mbalmer 350 1.1 mbalmer 351 1.2 lneto <h2>2.3 – <a name="2.3">Error Handling</a></h2> 352 1.1 mbalmer 353 1.1 mbalmer <p> 354 1.9 nikita Several operations in Lua can <em>raise</em> an error. 355 1.9 nikita An error interrupts the normal flow of the program, 356 1.9 nikita which can continue by <em>catching</em> the error. 357 1.9 nikita 358 1.9 nikita 359 1.9 nikita <p> 360 1.9 nikita Lua code can explicitly raise an error by calling the 361 1.9 nikita <a href="#pdf-error"><code>error</code></a> function. 362 1.9 nikita (This function never returns.) 363 1.9 nikita 364 1.9 nikita 365 1.9 nikita <p> 366 1.9 nikita To catch errors in Lua, 367 1.9 nikita you can do a <em>protected call</em>, 368 1.9 nikita using <a href="#pdf-pcall"><code>pcall</code></a> (or <a href="#pdf-xpcall"><code>xpcall</code></a>). 369 1.9 nikita The function <a href="#pdf-pcall"><code>pcall</code></a> calls a given function in <em>protected mode</em>. 370 1.9 nikita Any error while running the function stops its execution, 371 1.9 nikita and control returns immediately to <code>pcall</code>, 372 1.9 nikita which returns a status code. 373 1.9 nikita 374 1.9 nikita 375 1.9 nikita <p> 376 1.2 lneto Because Lua is an embedded extension language, 377 1.9 nikita Lua code starts running by a call 378 1.9 nikita from C code in the host program. 379 1.3 lneto (When you use Lua standalone, 380 1.3 lneto the <code>lua</code> application is the host program.) 381 1.9 nikita Usually, this call is protected; 382 1.9 nikita so, when an otherwise unprotected error occurs during 383 1.2 lneto the compilation or execution of a Lua chunk, 384 1.2 lneto control returns to the host, 385 1.9 nikita which can take appropriate measures, 386 1.9 nikita such as printing an error message. 387 1.1 mbalmer 388 1.1 mbalmer 389 1.1 mbalmer <p> 390 1.2 lneto Whenever there is an error, 391 1.9 nikita an <em>error object</em> 392 1.2 lneto is propagated with information about the error. 393 1.3 lneto Lua itself only generates errors whose error object is a string, 394 1.2 lneto but programs may generate errors with 395 1.3 lneto any value as the error object. 396 1.3 lneto It is up to the Lua program or its host to handle such error objects. 397 1.9 nikita For historical reasons, 398 1.9 nikita an error object is often called an <em>error message</em>, 399 1.9 nikita even though it does not have to be a string. 400 1.1 mbalmer 401 1.1 mbalmer 402 1.1 mbalmer <p> 403 1.9 nikita When you use <a href="#pdf-xpcall"><code>xpcall</code></a> (or <a href="#lua_pcall"><code>lua_pcall</code></a>, in C) 404 1.2 lneto you may give a <em>message handler</em> 405 1.2 lneto to be called in case of errors. 406 1.6 salazar This function is called with the original error object 407 1.6 salazar and returns a new error object. 408 1.2 lneto It is called before the error unwinds the stack, 409 1.2 lneto so that it can gather more information about the error, 410 1.2 lneto for instance by inspecting the stack and creating a stack traceback. 411 1.2 lneto This message handler is still protected by the protected call; 412 1.2 lneto so, an error inside the message handler 413 1.2 lneto will call the message handler again. 414 1.3 lneto If this loop goes on for too long, 415 1.3 lneto Lua breaks it and returns an appropriate message. 416 1.9 nikita The message handler is called only for regular runtime errors. 417 1.7 mbalmer It is not called for memory-allocation errors 418 1.9 nikita nor for errors while running finalizers or other message handlers. 419 1.9 nikita 420 1.9 nikita 421 1.9 nikita <p> 422 1.9 nikita Lua also offers a system of <em>warnings</em> (see <a href="#pdf-warn"><code>warn</code></a>). 423 1.9 nikita Unlike errors, warnings do not interfere 424 1.9 nikita in any way with program execution. 425 1.9 nikita They typically only generate a message to the user, 426 1.9 nikita although this behavior can be adapted from C (see <a href="#lua_setwarnf"><code>lua_setwarnf</code></a>). 427 1.1 mbalmer 428 1.1 mbalmer 429 1.1 mbalmer 430 1.1 mbalmer 431 1.1 mbalmer 432 1.2 lneto <h2>2.4 – <a name="2.4">Metatables and Metamethods</a></h2> 433 1.1 mbalmer 434 1.2 lneto <p> 435 1.2 lneto Every value in Lua can have a <em>metatable</em>. 436 1.2 lneto This <em>metatable</em> is an ordinary Lua table 437 1.2 lneto that defines the behavior of the original value 438 1.9 nikita under certain events. 439 1.2 lneto You can change several aspects of the behavior 440 1.9 nikita of a value by setting specific fields in its metatable. 441 1.2 lneto For instance, when a non-numeric value is the operand of an addition, 442 1.9 nikita Lua checks for a function in the field <code>__add</code> of the value's metatable. 443 1.2 lneto If it finds one, 444 1.2 lneto Lua calls this function to perform the addition. 445 1.1 mbalmer 446 1.1 mbalmer 447 1.1 mbalmer <p> 448 1.6 salazar The key for each event in a metatable is a string 449 1.6 salazar with the event name prefixed by two underscores; 450 1.9 nikita the corresponding value is called a <em>metavalue</em>. 451 1.9 nikita For most events, the metavalue must be a function, 452 1.9 nikita which is then called a <em>metamethod</em>. 453 1.9 nikita In the previous example, the key is the string "<code>__add</code>" 454 1.2 lneto and the metamethod is the function that performs the addition. 455 1.8 alnsn Unless stated otherwise, 456 1.9 nikita a metamethod may in fact be any callable value, 457 1.9 nikita which is either a function or a value with a <code>__call</code> metamethod. 458 1.1 mbalmer 459 1.1 mbalmer 460 1.2 lneto <p> 461 1.2 lneto You can query the metatable of any value 462 1.2 lneto using the <a href="#pdf-getmetatable"><code>getmetatable</code></a> function. 463 1.6 salazar Lua queries metamethods in metatables using a raw access (see <a href="#pdf-rawget"><code>rawget</code></a>). 464 1.1 mbalmer 465 1.1 mbalmer 466 1.1 mbalmer <p> 467 1.2 lneto You can replace the metatable of tables 468 1.2 lneto using the <a href="#pdf-setmetatable"><code>setmetatable</code></a> function. 469 1.9 nikita You cannot change the metatable of other types from Lua code, 470 1.9 nikita except by using the debug library (<a href="#6.10">§6.10</a>). 471 1.1 mbalmer 472 1.1 mbalmer 473 1.1 mbalmer <p> 474 1.9 nikita Tables and full userdata have individual metatables, 475 1.9 nikita although multiple tables and userdata can share their metatables. 476 1.2 lneto Values of all other types share one single metatable per type; 477 1.2 lneto that is, there is one single metatable for all numbers, 478 1.2 lneto one for all strings, etc. 479 1.2 lneto By default, a value has no metatable, 480 1.2 lneto but the string library sets a metatable for the string type (see <a href="#6.4">§6.4</a>). 481 1.1 mbalmer 482 1.1 mbalmer 483 1.1 mbalmer <p> 484 1.9 nikita A detailed list of operations controlled by metatables is given next. 485 1.9 nikita Each event is identified by its corresponding key. 486 1.9 nikita By convention, all metatable keys used by Lua are composed by 487 1.9 nikita two underscores followed by lowercase Latin letters. 488 1.6 salazar 489 1.6 salazar 490 1.1 mbalmer 491 1.2 lneto <ul> 492 1.1 mbalmer 493 1.6 salazar <li><b><code>__add</code>: </b> 494 1.6 salazar the addition (<code>+</code>) operation. 495 1.9 nikita If any operand for an addition is not a number, 496 1.2 lneto Lua will try to call a metamethod. 497 1.9 nikita It starts by checking the first operand (even if it is a number); 498 1.9 nikita if that operand does not define a metamethod for <code>__add</code>, 499 1.2 lneto then Lua will check the second operand. 500 1.3 lneto If Lua can find a metamethod, 501 1.2 lneto it calls the metamethod with the two operands as arguments, 502 1.2 lneto and the result of the call 503 1.2 lneto (adjusted to one value) 504 1.2 lneto is the result of the operation. 505 1.9 nikita Otherwise, if no metamethod is found, 506 1.9 nikita Lua raises an error. 507 1.2 lneto </li> 508 1.1 mbalmer 509 1.6 salazar <li><b><code>__sub</code>: </b> 510 1.6 salazar the subtraction (<code>-</code>) operation. 511 1.6 salazar Behavior similar to the addition operation. 512 1.2 lneto </li> 513 1.1 mbalmer 514 1.6 salazar <li><b><code>__mul</code>: </b> 515 1.6 salazar the multiplication (<code>*</code>) operation. 516 1.6 salazar Behavior similar to the addition operation. 517 1.2 lneto </li> 518 1.1 mbalmer 519 1.6 salazar <li><b><code>__div</code>: </b> 520 1.6 salazar the division (<code>/</code>) operation. 521 1.6 salazar Behavior similar to the addition operation. 522 1.2 lneto </li> 523 1.1 mbalmer 524 1.6 salazar <li><b><code>__mod</code>: </b> 525 1.6 salazar the modulo (<code>%</code>) operation. 526 1.6 salazar Behavior similar to the addition operation. 527 1.2 lneto </li> 528 1.1 mbalmer 529 1.6 salazar <li><b><code>__pow</code>: </b> 530 1.6 salazar the exponentiation (<code>^</code>) operation. 531 1.6 salazar Behavior similar to the addition operation. 532 1.2 lneto </li> 533 1.1 mbalmer 534 1.6 salazar <li><b><code>__unm</code>: </b> 535 1.6 salazar the negation (unary <code>-</code>) operation. 536 1.6 salazar Behavior similar to the addition operation. 537 1.2 lneto </li> 538 1.1 mbalmer 539 1.6 salazar <li><b><code>__idiv</code>: </b> 540 1.6 salazar the floor division (<code>//</code>) operation. 541 1.6 salazar Behavior similar to the addition operation. 542 1.2 lneto </li> 543 1.1 mbalmer 544 1.6 salazar <li><b><code>__band</code>: </b> 545 1.6 salazar the bitwise AND (<code>&</code>) operation. 546 1.6 salazar Behavior similar to the addition operation, 547 1.3 lneto except that Lua will try a metamethod 548 1.4 mbalmer if any operand is neither an integer 549 1.9 nikita nor a float coercible to an integer (see <a href="#3.4.3">§3.4.3</a>). 550 1.2 lneto </li> 551 1.1 mbalmer 552 1.6 salazar <li><b><code>__bor</code>: </b> 553 1.6 salazar the bitwise OR (<code>|</code>) operation. 554 1.6 salazar Behavior similar to the bitwise AND operation. 555 1.2 lneto </li> 556 1.1 mbalmer 557 1.6 salazar <li><b><code>__bxor</code>: </b> 558 1.6 salazar the bitwise exclusive OR (binary <code>~</code>) operation. 559 1.6 salazar Behavior similar to the bitwise AND operation. 560 1.2 lneto </li> 561 1.1 mbalmer 562 1.6 salazar <li><b><code>__bnot</code>: </b> 563 1.6 salazar the bitwise NOT (unary <code>~</code>) operation. 564 1.6 salazar Behavior similar to the bitwise AND operation. 565 1.2 lneto </li> 566 1.1 mbalmer 567 1.6 salazar <li><b><code>__shl</code>: </b> 568 1.6 salazar the bitwise left shift (<code><<</code>) operation. 569 1.6 salazar Behavior similar to the bitwise AND operation. 570 1.2 lneto </li> 571 1.1 mbalmer 572 1.6 salazar <li><b><code>__shr</code>: </b> 573 1.6 salazar the bitwise right shift (<code>>></code>) operation. 574 1.6 salazar Behavior similar to the bitwise AND operation. 575 1.2 lneto </li> 576 1.1 mbalmer 577 1.6 salazar <li><b><code>__concat</code>: </b> 578 1.6 salazar the concatenation (<code>..</code>) operation. 579 1.6 salazar Behavior similar to the addition operation, 580 1.2 lneto except that Lua will try a metamethod 581 1.4 mbalmer if any operand is neither a string nor a number 582 1.2 lneto (which is always coercible to a string). 583 1.2 lneto </li> 584 1.2 lneto 585 1.6 salazar <li><b><code>__len</code>: </b> 586 1.6 salazar the length (<code>#</code>) operation. 587 1.2 lneto If the object is not a string, 588 1.2 lneto Lua will try its metamethod. 589 1.2 lneto If there is a metamethod, 590 1.2 lneto Lua calls it with the object as argument, 591 1.2 lneto and the result of the call 592 1.2 lneto (always adjusted to one value) 593 1.2 lneto is the result of the operation. 594 1.2 lneto If there is no metamethod but the object is a table, 595 1.2 lneto then Lua uses the table length operation (see <a href="#3.4.7">§3.4.7</a>). 596 1.2 lneto Otherwise, Lua raises an error. 597 1.2 lneto </li> 598 1.1 mbalmer 599 1.6 salazar <li><b><code>__eq</code>: </b> 600 1.6 salazar the equal (<code>==</code>) operation. 601 1.6 salazar Behavior similar to the addition operation, 602 1.2 lneto except that Lua will try a metamethod only when the values 603 1.2 lneto being compared are either both tables or both full userdata 604 1.2 lneto and they are not primitively equal. 605 1.2 lneto The result of the call is always converted to a boolean. 606 1.2 lneto </li> 607 1.1 mbalmer 608 1.6 salazar <li><b><code>__lt</code>: </b> 609 1.6 salazar the less than (<code><</code>) operation. 610 1.6 salazar Behavior similar to the addition operation, 611 1.2 lneto except that Lua will try a metamethod only when the values 612 1.2 lneto being compared are neither both numbers nor both strings. 613 1.9 nikita Moreover, the result of the call is always converted to a boolean. 614 1.2 lneto </li> 615 1.2 lneto 616 1.6 salazar <li><b><code>__le</code>: </b> 617 1.6 salazar the less equal (<code><=</code>) operation. 618 1.9 nikita Behavior similar to the less than operation. 619 1.2 lneto </li> 620 1.1 mbalmer 621 1.6 salazar <li><b><code>__index</code>: </b> 622 1.8 alnsn The indexing access operation <code>table[key]</code>. 623 1.2 lneto This event happens when <code>table</code> is not a table or 624 1.2 lneto when <code>key</code> is not present in <code>table</code>. 625 1.9 nikita The metavalue is looked up in the metatable of <code>table</code>. 626 1.1 mbalmer 627 1.1 mbalmer 628 1.1 mbalmer <p> 629 1.9 nikita The metavalue for this event can be either a function, a table, 630 1.9 nikita or any value with an <code>__index</code> metavalue. 631 1.2 lneto If it is a function, 632 1.6 salazar it is called with <code>table</code> and <code>key</code> as arguments, 633 1.6 salazar and the result of the call 634 1.6 salazar (adjusted to one value) 635 1.6 salazar is the result of the operation. 636 1.9 nikita Otherwise, 637 1.9 nikita the final result is the result of indexing this metavalue with <code>key</code>. 638 1.9 nikita This indexing is regular, not raw, 639 1.9 nikita and therefore can trigger another <code>__index</code> metavalue. 640 1.2 lneto </li> 641 1.2 lneto 642 1.6 salazar <li><b><code>__newindex</code>: </b> 643 1.2 lneto The indexing assignment <code>table[key] = value</code>. 644 1.2 lneto Like the index event, 645 1.2 lneto this event happens when <code>table</code> is not a table or 646 1.2 lneto when <code>key</code> is not present in <code>table</code>. 647 1.9 nikita The metavalue is looked up in the metatable of <code>table</code>. 648 1.1 mbalmer 649 1.1 mbalmer 650 1.1 mbalmer <p> 651 1.3 lneto Like with indexing, 652 1.9 nikita the metavalue for this event can be either a function, a table, 653 1.9 nikita or any value with an <code>__newindex</code> metavalue. 654 1.2 lneto If it is a function, 655 1.2 lneto it is called with <code>table</code>, <code>key</code>, and <code>value</code> as arguments. 656 1.9 nikita Otherwise, 657 1.9 nikita Lua repeats the indexing assignment over this metavalue 658 1.9 nikita with the same key and value. 659 1.9 nikita This assignment is regular, not raw, 660 1.9 nikita and therefore can trigger another <code>__newindex</code> metavalue. 661 1.1 mbalmer 662 1.1 mbalmer 663 1.2 lneto <p> 664 1.9 nikita Whenever a <code>__newindex</code> metavalue is invoked, 665 1.2 lneto Lua does not perform the primitive assignment. 666 1.9 nikita If needed, 667 1.2 lneto the metamethod itself can call <a href="#pdf-rawset"><code>rawset</code></a> 668 1.9 nikita to do the assignment. 669 1.2 lneto </li> 670 1.1 mbalmer 671 1.6 salazar <li><b><code>__call</code>: </b> 672 1.2 lneto The call operation <code>func(args)</code>. 673 1.2 lneto This event happens when Lua tries to call a non-function value 674 1.2 lneto (that is, <code>func</code> is not a function). 675 1.2 lneto The metamethod is looked up in <code>func</code>. 676 1.2 lneto If present, 677 1.2 lneto the metamethod is called with <code>func</code> as its first argument, 678 1.2 lneto followed by the arguments of the original call (<code>args</code>). 679 1.6 salazar All results of the call 680 1.9 nikita are the results of the operation. 681 1.9 nikita This is the only metamethod that allows multiple results. 682 1.2 lneto </li> 683 1.1 mbalmer 684 1.2 lneto </ul> 685 1.1 mbalmer 686 1.4 mbalmer <p> 687 1.9 nikita In addition to the previous list, 688 1.9 nikita the interpreter also respects the following keys in metatables: 689 1.9 nikita <code>__gc</code> (see <a href="#2.5.3">§2.5.3</a>), 690 1.9 nikita <code>__close</code> (see <a href="#3.3.8">§3.3.8</a>), 691 1.9 nikita <code>__mode</code> (see <a href="#2.5.4">§2.5.4</a>), 692 1.9 nikita and <code>__name</code>. 693 1.9 nikita (The entry <code>__name</code>, 694 1.9 nikita when it contains a string, 695 1.9 nikita may be used by <a href="#pdf-tostring"><code>tostring</code></a> and in error messages.) 696 1.9 nikita 697 1.9 nikita 698 1.9 nikita <p> 699 1.9 nikita For the unary operators (negation, length, and bitwise NOT), 700 1.9 nikita the metamethod is computed and called with a dummy second operand, 701 1.9 nikita equal to the first one. 702 1.9 nikita This extra operand is only to simplify Lua's internals 703 1.9 nikita (by making these operators behave like a binary operation) 704 1.9 nikita and may be removed in future versions. 705 1.9 nikita For most uses this extra operand is irrelevant. 706 1.4 mbalmer 707 1.4 mbalmer 708 1.6 salazar <p> 709 1.6 salazar Because metatables are regular tables, 710 1.6 salazar they can contain arbitrary fields, 711 1.6 salazar not only the event names defined above. 712 1.6 salazar Some functions in the standard library 713 1.6 salazar (e.g., <a href="#pdf-tostring"><code>tostring</code></a>) 714 1.6 salazar use other fields in metatables for their own purposes. 715 1.6 salazar 716 1.6 salazar 717 1.9 nikita <p> 718 1.9 nikita It is a good practice to add all needed metamethods to a table 719 1.9 nikita before setting it as a metatable of some object. 720 1.9 nikita In particular, the <code>__gc</code> metamethod works only when this order 721 1.9 nikita is followed (see <a href="#2.5.3">§2.5.3</a>). 722 1.9 nikita It is also a good practice to set the metatable of an object 723 1.9 nikita right after its creation. 724 1.9 nikita 725 1.9 nikita 726 1.1 mbalmer 727 1.1 mbalmer 728 1.1 mbalmer 729 1.2 lneto <h2>2.5 – <a name="2.5">Garbage Collection</a></h2> 730 1.1 mbalmer 731 1.9 nikita 732 1.9 nikita 733 1.1 mbalmer <p> 734 1.2 lneto Lua performs automatic memory management. 735 1.2 lneto This means that 736 1.3 lneto you do not have to worry about allocating memory for new objects 737 1.3 lneto or freeing it when the objects are no longer needed. 738 1.2 lneto Lua manages memory automatically by running 739 1.9 nikita a <em>garbage collector</em> to collect all <em>dead</em> objects. 740 1.2 lneto All memory used by Lua is subject to automatic management: 741 1.2 lneto strings, tables, userdata, functions, threads, internal structures, etc. 742 1.1 mbalmer 743 1.2 lneto 744 1.2 lneto <p> 745 1.9 nikita An object is considered <em>dead</em> 746 1.9 nikita as soon as the collector can be sure the object 747 1.9 nikita will not be accessed again in the normal execution of the program. 748 1.9 nikita ("Normal execution" here excludes finalizers, 749 1.9 nikita which can resurrect dead objects (see <a href="#2.5.3">§2.5.3</a>), 750 1.9 nikita and excludes also operations using the debug library.) 751 1.9 nikita Note that the time when the collector can be sure that an object 752 1.9 nikita is dead may not coincide with the programmer's expectations. 753 1.9 nikita The only guarantees are that Lua will not collect an object 754 1.9 nikita that may still be accessed in the normal execution of the program, 755 1.9 nikita and it will eventually collect an object 756 1.9 nikita that is inaccessible from Lua. 757 1.9 nikita (Here, 758 1.9 nikita <em>inaccessible from Lua</em> means that neither a variable nor 759 1.9 nikita another live object refer to the object.) 760 1.9 nikita Because Lua has no knowledge about C code, 761 1.9 nikita it never collects objects accessible through the registry (see <a href="#4.3">§4.3</a>), 762 1.9 nikita which includes the global environment (see <a href="#2.2">§2.2</a>). 763 1.9 nikita 764 1.9 nikita 765 1.9 nikita <p> 766 1.9 nikita The garbage collector (GC) in Lua can work in two modes: 767 1.9 nikita incremental and generational. 768 1.9 nikita 769 1.9 nikita 770 1.9 nikita <p> 771 1.9 nikita The default GC mode with the default parameters 772 1.9 nikita are adequate for most uses. 773 1.9 nikita However, programs that waste a large proportion of their time 774 1.9 nikita allocating and freeing memory can benefit from other settings. 775 1.9 nikita Keep in mind that the GC behavior is non-portable 776 1.9 nikita both across platforms and across different Lua releases; 777 1.9 nikita therefore, optimal settings are also non-portable. 778 1.9 nikita 779 1.9 nikita 780 1.9 nikita <p> 781 1.9 nikita You can change the GC mode and parameters by calling 782 1.9 nikita <a href="#lua_gc"><code>lua_gc</code></a> in C 783 1.9 nikita or <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> in Lua. 784 1.9 nikita You can also use these functions to control 785 1.9 nikita the collector directly (e.g., to stop and restart it). 786 1.9 nikita 787 1.9 nikita 788 1.9 nikita 789 1.9 nikita 790 1.9 nikita 791 1.9 nikita <h3>2.5.1 – <a name="2.5.1">Incremental Garbage Collection</a></h3> 792 1.9 nikita 793 1.9 nikita <p> 794 1.9 nikita In incremental mode, 795 1.9 nikita each GC cycle performs a mark-and-sweep collection in small steps 796 1.9 nikita interleaved with the program's execution. 797 1.9 nikita In this mode, 798 1.9 nikita the collector uses three numbers to control its garbage-collection cycles: 799 1.9 nikita the <em>garbage-collector pause</em>, 800 1.9 nikita the <em>garbage-collector step multiplier</em>, 801 1.9 nikita and the <em>garbage-collector step size</em>. 802 1.1 mbalmer 803 1.1 mbalmer 804 1.1 mbalmer <p> 805 1.2 lneto The garbage-collector pause 806 1.2 lneto controls how long the collector waits before starting a new cycle. 807 1.9 nikita The collector starts a new cycle when the use of memory 808 1.9 nikita hits <em>n%</em> of the use after the previous collection. 809 1.2 lneto Larger values make the collector less aggressive. 810 1.9 nikita Values equal to or less than 100 mean the collector will not wait to 811 1.2 lneto start a new cycle. 812 1.2 lneto A value of 200 means that the collector waits for the total memory in use 813 1.2 lneto to double before starting a new cycle. 814 1.9 nikita The default value is 200; the maximum value is 1000. 815 1.2 lneto 816 1.1 mbalmer 817 1.2 lneto <p> 818 1.2 lneto The garbage-collector step multiplier 819 1.9 nikita controls the speed of the collector relative to 820 1.9 nikita memory allocation, 821 1.9 nikita that is, 822 1.9 nikita how many elements it marks or sweeps for each 823 1.9 nikita kilobyte of memory allocated. 824 1.2 lneto Larger values make the collector more aggressive but also increase 825 1.2 lneto the size of each incremental step. 826 1.9 nikita You should not use values less than 100, 827 1.3 lneto because they make the collector too slow and 828 1.2 lneto can result in the collector never finishing a cycle. 829 1.9 nikita The default value is 100; the maximum value is 1000. 830 1.9 nikita 831 1.9 nikita 832 1.9 nikita <p> 833 1.9 nikita The garbage-collector step size controls the 834 1.9 nikita size of each incremental step, 835 1.9 nikita specifically how many bytes the interpreter allocates 836 1.9 nikita before performing a step. 837 1.9 nikita This parameter is logarithmic: 838 1.9 nikita A value of <em>n</em> means the interpreter will allocate <em>2<sup>n</sup></em> 839 1.9 nikita bytes between steps and perform equivalent work during the step. 840 1.9 nikita A large value (e.g., 60) makes the collector a stop-the-world 841 1.9 nikita (non-incremental) collector. 842 1.9 nikita The default value is 13, 843 1.9 nikita which means steps of approximately 8 Kbytes. 844 1.9 nikita 845 1.9 nikita 846 1.9 nikita 847 1.9 nikita 848 1.1 mbalmer 849 1.9 nikita <h3>2.5.2 – <a name="2.5.2">Generational Garbage Collection</a></h3> 850 1.1 mbalmer 851 1.2 lneto <p> 852 1.9 nikita In generational mode, 853 1.9 nikita the collector does frequent <em>minor</em> collections, 854 1.9 nikita which traverses only objects recently created. 855 1.9 nikita If after a minor collection the use of memory is still above a limit, 856 1.9 nikita the collector does a stop-the-world <em>major</em> collection, 857 1.9 nikita which traverses all objects. 858 1.9 nikita The generational mode uses two parameters: 859 1.9 nikita the <em>minor multiplier</em> and the <em>the major multiplier</em>. 860 1.1 mbalmer 861 1.1 mbalmer 862 1.2 lneto <p> 863 1.9 nikita The minor multiplier controls the frequency of minor collections. 864 1.9 nikita For a minor multiplier <em>x</em>, 865 1.9 nikita a new minor collection will be done when memory 866 1.9 nikita grows <em>x%</em> larger than the memory in use after the previous major 867 1.9 nikita collection. 868 1.9 nikita For instance, for a multiplier of 20, 869 1.9 nikita the collector will do a minor collection when the use of memory 870 1.9 nikita gets 20% larger than the use after the previous major collection. 871 1.9 nikita The default value is 20; the maximum value is 200. 872 1.9 nikita 873 1.9 nikita 874 1.9 nikita <p> 875 1.9 nikita The major multiplier controls the frequency of major collections. 876 1.9 nikita For a major multiplier <em>x</em>, 877 1.9 nikita a new major collection will be done when memory 878 1.9 nikita grows <em>x%</em> larger than the memory in use after the previous major 879 1.9 nikita collection. 880 1.9 nikita For instance, for a multiplier of 100, 881 1.9 nikita the collector will do a major collection when the use of memory 882 1.9 nikita gets larger than twice the use after the previous collection. 883 1.9 nikita The default value is 100; the maximum value is 1000. 884 1.9 nikita 885 1.9 nikita 886 1.1 mbalmer 887 1.1 mbalmer 888 1.1 mbalmer 889 1.9 nikita <h3>2.5.3 – <a name="2.5.3">Garbage-Collection Metamethods</a></h3> 890 1.1 mbalmer 891 1.2 lneto <p> 892 1.2 lneto You can set garbage-collector metamethods for tables 893 1.2 lneto and, using the C API, 894 1.2 lneto for full userdata (see <a href="#2.4">§2.4</a>). 895 1.9 nikita These metamethods, called <em>finalizers</em>, 896 1.9 nikita are called when the garbage collector detects that the 897 1.9 nikita corresponding table or userdata is dead. 898 1.2 lneto Finalizers allow you to coordinate Lua's garbage collection 899 1.9 nikita with external resource management such as closing files, 900 1.9 nikita network or database connections, 901 1.9 nikita or freeing your own memory. 902 1.1 mbalmer 903 1.1 mbalmer 904 1.1 mbalmer <p> 905 1.2 lneto For an object (table or userdata) to be finalized when collected, 906 1.2 lneto you must <em>mark</em> it for finalization. 907 1.1 mbalmer 908 1.2 lneto You mark an object for finalization when you set its metatable 909 1.9 nikita and the metatable has a <code>__gc</code> metamethod. 910 1.2 lneto Note that if you set a metatable without a <code>__gc</code> field 911 1.2 lneto and later create that field in the metatable, 912 1.2 lneto the object will not be marked for finalization. 913 1.1 mbalmer 914 1.1 mbalmer 915 1.2 lneto <p> 916 1.9 nikita When a marked object becomes dead, 917 1.2 lneto it is not collected immediately by the garbage collector. 918 1.2 lneto Instead, Lua puts it in a list. 919 1.2 lneto After the collection, 920 1.3 lneto Lua goes through that list. 921 1.3 lneto For each object in the list, 922 1.3 lneto it checks the object's <code>__gc</code> metamethod: 923 1.9 nikita If it is present, 924 1.9 nikita Lua calls it with the object as its single argument. 925 1.1 mbalmer 926 1.1 mbalmer 927 1.2 lneto <p> 928 1.2 lneto At the end of each garbage-collection cycle, 929 1.9 nikita the finalizers are called in 930 1.3 lneto the reverse order that the objects were marked for finalization, 931 1.2 lneto among those collected in that cycle; 932 1.2 lneto that is, the first finalizer to be called is the one associated 933 1.2 lneto with the object marked last in the program. 934 1.2 lneto The execution of each finalizer may occur at any point during 935 1.2 lneto the execution of the regular code. 936 1.1 mbalmer 937 1.1 mbalmer 938 1.2 lneto <p> 939 1.2 lneto Because the object being collected must still be used by the finalizer, 940 1.3 lneto that object (and other objects accessible only through it) 941 1.2 lneto must be <em>resurrected</em> by Lua. 942 1.2 lneto Usually, this resurrection is transient, 943 1.2 lneto and the object memory is freed in the next garbage-collection cycle. 944 1.2 lneto However, if the finalizer stores the object in some global place 945 1.2 lneto (e.g., a global variable), 946 1.3 lneto then the resurrection is permanent. 947 1.2 lneto Moreover, if the finalizer marks a finalizing object for finalization again, 948 1.2 lneto its finalizer will be called again in the next cycle where the 949 1.9 nikita object is dead. 950 1.2 lneto In any case, 951 1.4 mbalmer the object memory is freed only in a GC cycle where 952 1.9 nikita the object is dead and not marked for finalization. 953 1.1 mbalmer 954 1.1 mbalmer 955 1.2 lneto <p> 956 1.2 lneto When you close a state (see <a href="#lua_close"><code>lua_close</code></a>), 957 1.2 lneto Lua calls the finalizers of all objects marked for finalization, 958 1.2 lneto following the reverse order that they were marked. 959 1.2 lneto If any finalizer marks objects for collection during that phase, 960 1.2 lneto these marks have no effect. 961 1.1 mbalmer 962 1.1 mbalmer 963 1.9 nikita <p> 964 1.9 nikita Finalizers cannot yield nor run the garbage collector. 965 1.9 nikita Because they can run in unpredictable times, 966 1.9 nikita it is good practice to restrict each finalizer 967 1.9 nikita to the minimum necessary to properly release 968 1.9 nikita its associated resource. 969 1.1 mbalmer 970 1.1 mbalmer 971 1.9 nikita <p> 972 1.9 nikita Any error while running a finalizer generates a warning; 973 1.9 nikita the error is not propagated. 974 1.9 nikita 975 1.1 mbalmer 976 1.9 nikita 977 1.9 nikita 978 1.9 nikita 979 1.9 nikita <h3>2.5.4 – <a name="2.5.4">Weak Tables</a></h3> 980 1.2 lneto 981 1.2 lneto <p> 982 1.2 lneto A <em>weak table</em> is a table whose elements are 983 1.2 lneto <em>weak references</em>. 984 1.2 lneto A weak reference is ignored by the garbage collector. 985 1.2 lneto In other words, 986 1.2 lneto if the only references to an object are weak references, 987 1.2 lneto then the garbage collector will collect that object. 988 1.2 lneto 989 1.2 lneto 990 1.2 lneto <p> 991 1.2 lneto A weak table can have weak keys, weak values, or both. 992 1.4 mbalmer A table with weak values allows the collection of its values, 993 1.4 mbalmer but prevents the collection of its keys. 994 1.2 lneto A table with both weak keys and weak values allows the collection of 995 1.2 lneto both keys and values. 996 1.2 lneto In any case, if either the key or the value is collected, 997 1.2 lneto the whole pair is removed from the table. 998 1.2 lneto The weakness of a table is controlled by the 999 1.2 lneto <code>__mode</code> field of its metatable. 1000 1.9 nikita This metavalue, if present, must be one of the following strings: 1001 1.9 nikita "<code>k</code>", for a table with weak keys; 1002 1.9 nikita "<code>v</code>", for a table with weak values; 1003 1.9 nikita or "<code>kv</code>", for a table with both weak keys and values. 1004 1.1 mbalmer 1005 1.1 mbalmer 1006 1.2 lneto <p> 1007 1.2 lneto A table with weak keys and strong values 1008 1.2 lneto is also called an <em>ephemeron table</em>. 1009 1.2 lneto In an ephemeron table, 1010 1.2 lneto a value is considered reachable only if its key is reachable. 1011 1.2 lneto In particular, 1012 1.2 lneto if the only reference to a key comes through its value, 1013 1.2 lneto the pair is removed. 1014 1.1 mbalmer 1015 1.1 mbalmer 1016 1.2 lneto <p> 1017 1.2 lneto Any change in the weakness of a table may take effect only 1018 1.2 lneto at the next collect cycle. 1019 1.2 lneto In particular, if you change the weakness to a stronger mode, 1020 1.2 lneto Lua may still collect some items from that table 1021 1.2 lneto before the change takes effect. 1022 1.1 mbalmer 1023 1.1 mbalmer 1024 1.2 lneto <p> 1025 1.2 lneto Only objects that have an explicit construction 1026 1.2 lneto are removed from weak tables. 1027 1.7 mbalmer Values, such as numbers and light C functions, 1028 1.2 lneto are not subject to garbage collection, 1029 1.2 lneto and therefore are not removed from weak tables 1030 1.3 lneto (unless their associated values are collected). 1031 1.2 lneto Although strings are subject to garbage collection, 1032 1.9 nikita they do not have an explicit construction and 1033 1.9 nikita their equality is by value; 1034 1.9 nikita they behave more like values than like objects. 1035 1.9 nikita Therefore, they are not removed from weak tables. 1036 1.1 mbalmer 1037 1.1 mbalmer 1038 1.1 mbalmer <p> 1039 1.2 lneto Resurrected objects 1040 1.2 lneto (that is, objects being finalized 1041 1.2 lneto and objects accessible only through objects being finalized) 1042 1.2 lneto have a special behavior in weak tables. 1043 1.2 lneto They are removed from weak values before running their finalizers, 1044 1.2 lneto but are removed from weak keys only in the next collection 1045 1.2 lneto after running their finalizers, when such objects are actually freed. 1046 1.2 lneto This behavior allows the finalizer to access properties 1047 1.2 lneto associated with the object through weak tables. 1048 1.1 mbalmer 1049 1.1 mbalmer 1050 1.1 mbalmer <p> 1051 1.2 lneto If a weak table is among the resurrected objects in a collection cycle, 1052 1.2 lneto it may not be properly cleared until the next cycle. 1053 1.1 mbalmer 1054 1.1 mbalmer 1055 1.1 mbalmer 1056 1.1 mbalmer 1057 1.1 mbalmer 1058 1.1 mbalmer 1059 1.1 mbalmer 1060 1.2 lneto <h2>2.6 – <a name="2.6">Coroutines</a></h2> 1061 1.1 mbalmer 1062 1.1 mbalmer <p> 1063 1.2 lneto Lua supports coroutines, 1064 1.2 lneto also called <em>collaborative multithreading</em>. 1065 1.2 lneto A coroutine in Lua represents an independent thread of execution. 1066 1.2 lneto Unlike threads in multithread systems, however, 1067 1.2 lneto a coroutine only suspends its execution by explicitly calling 1068 1.2 lneto a yield function. 1069 1.1 mbalmer 1070 1.1 mbalmer 1071 1.1 mbalmer <p> 1072 1.2 lneto You create a coroutine by calling <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>. 1073 1.2 lneto Its sole argument is a function 1074 1.2 lneto that is the main function of the coroutine. 1075 1.2 lneto The <code>create</code> function only creates a new coroutine and 1076 1.2 lneto returns a handle to it (an object of type <em>thread</em>); 1077 1.2 lneto it does not start the coroutine. 1078 1.1 mbalmer 1079 1.1 mbalmer 1080 1.1 mbalmer <p> 1081 1.2 lneto You execute a coroutine by calling <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. 1082 1.2 lneto When you first call <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>, 1083 1.2 lneto passing as its first argument 1084 1.2 lneto a thread returned by <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>, 1085 1.4 mbalmer the coroutine starts its execution by 1086 1.4 mbalmer calling its main function. 1087 1.3 lneto Extra arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> are passed 1088 1.4 mbalmer as arguments to that function. 1089 1.2 lneto After the coroutine starts running, 1090 1.2 lneto it runs until it terminates or <em>yields</em>. 1091 1.1 mbalmer 1092 1.1 mbalmer 1093 1.1 mbalmer <p> 1094 1.2 lneto A coroutine can terminate its execution in two ways: 1095 1.2 lneto normally, when its main function returns 1096 1.2 lneto (explicitly or implicitly, after the last instruction); 1097 1.2 lneto and abnormally, if there is an unprotected error. 1098 1.3 lneto In case of normal termination, 1099 1.3 lneto <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>true</b>, 1100 1.2 lneto plus any values returned by the coroutine main function. 1101 1.2 lneto In case of errors, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>false</b> 1102 1.9 nikita plus the error object. 1103 1.9 nikita In this case, the coroutine does not unwind its stack, 1104 1.9 nikita so that it is possible to inspect it after the error 1105 1.9 nikita with the debug API. 1106 1.1 mbalmer 1107 1.1 mbalmer 1108 1.1 mbalmer <p> 1109 1.2 lneto A coroutine yields by calling <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>. 1110 1.2 lneto When a coroutine yields, 1111 1.2 lneto the corresponding <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns immediately, 1112 1.2 lneto even if the yield happens inside nested function calls 1113 1.2 lneto (that is, not in the main function, 1114 1.2 lneto but in a function directly or indirectly called by the main function). 1115 1.2 lneto In the case of a yield, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> also returns <b>true</b>, 1116 1.2 lneto plus any values passed to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>. 1117 1.2 lneto The next time you resume the same coroutine, 1118 1.2 lneto it continues its execution from the point where it yielded, 1119 1.2 lneto with the call to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a> returning any extra 1120 1.2 lneto arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. 1121 1.1 mbalmer 1122 1.1 mbalmer 1123 1.1 mbalmer <p> 1124 1.2 lneto Like <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>, 1125 1.2 lneto the <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> function also creates a coroutine, 1126 1.2 lneto but instead of returning the coroutine itself, 1127 1.2 lneto it returns a function that, when called, resumes the coroutine. 1128 1.2 lneto Any arguments passed to this function 1129 1.2 lneto go as extra arguments to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. 1130 1.2 lneto <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>, 1131 1.2 lneto except the first one (the boolean error code). 1132 1.2 lneto Unlike <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>, 1133 1.9 nikita the function created by <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> 1134 1.9 nikita propagates any error to the caller. 1135 1.9 nikita In this case, 1136 1.9 nikita the function also closes the coroutine (see <a href="#pdf-coroutine.close"><code>coroutine.close</code></a>). 1137 1.1 mbalmer 1138 1.1 mbalmer 1139 1.2 lneto <p> 1140 1.2 lneto As an example of how coroutines work, 1141 1.2 lneto consider the following code: 1142 1.1 mbalmer 1143 1.1 mbalmer <pre> 1144 1.2 lneto function foo (a) 1145 1.2 lneto print("foo", a) 1146 1.2 lneto return coroutine.yield(2*a) 1147 1.2 lneto end 1148 1.2 lneto 1149 1.2 lneto co = coroutine.create(function (a,b) 1150 1.2 lneto print("co-body", a, b) 1151 1.2 lneto local r = foo(a+1) 1152 1.2 lneto print("co-body", r) 1153 1.2 lneto local r, s = coroutine.yield(a+b, a-b) 1154 1.2 lneto print("co-body", r, s) 1155 1.2 lneto return b, "end" 1156 1.2 lneto end) 1157 1.2 lneto 1158 1.2 lneto print("main", coroutine.resume(co, 1, 10)) 1159 1.2 lneto print("main", coroutine.resume(co, "r")) 1160 1.2 lneto print("main", coroutine.resume(co, "x", "y")) 1161 1.2 lneto print("main", coroutine.resume(co, "x", "y")) 1162 1.1 mbalmer </pre><p> 1163 1.2 lneto When you run it, it produces the following output: 1164 1.1 mbalmer 1165 1.2 lneto <pre> 1166 1.2 lneto co-body 1 10 1167 1.2 lneto foo 2 1168 1.2 lneto main true 4 1169 1.2 lneto co-body r 1170 1.2 lneto main true 11 -9 1171 1.2 lneto co-body x y 1172 1.2 lneto main true 10 end 1173 1.2 lneto main false cannot resume dead coroutine 1174 1.2 lneto </pre> 1175 1.1 mbalmer 1176 1.2 lneto <p> 1177 1.2 lneto You can also create and manipulate coroutines through the C API: 1178 1.2 lneto see functions <a href="#lua_newthread"><code>lua_newthread</code></a>, <a href="#lua_resume"><code>lua_resume</code></a>, 1179 1.2 lneto and <a href="#lua_yield"><code>lua_yield</code></a>. 1180 1.1 mbalmer 1181 1.1 mbalmer 1182 1.1 mbalmer 1183 1.1 mbalmer 1184 1.1 mbalmer 1185 1.2 lneto <h1>3 – <a name="3">The Language</a></h1> 1186 1.1 mbalmer 1187 1.9 nikita 1188 1.9 nikita 1189 1.1 mbalmer <p> 1190 1.2 lneto This section describes the lexis, the syntax, and the semantics of Lua. 1191 1.2 lneto In other words, 1192 1.2 lneto this section describes 1193 1.2 lneto which tokens are valid, 1194 1.2 lneto how they can be combined, 1195 1.2 lneto and what their combinations mean. 1196 1.1 mbalmer 1197 1.1 mbalmer 1198 1.1 mbalmer <p> 1199 1.2 lneto Language constructs will be explained using the usual extended BNF notation, 1200 1.2 lneto in which 1201 1.2 lneto {<em>a</em>} means 0 or more <em>a</em>'s, and 1202 1.2 lneto [<em>a</em>] means an optional <em>a</em>. 1203 1.2 lneto Non-terminals are shown like non-terminal, 1204 1.2 lneto keywords are shown like <b>kword</b>, 1205 1.2 lneto and other terminal symbols are shown like ‘<b>=</b>’. 1206 1.2 lneto The complete syntax of Lua can be found in <a href="#9">§9</a> 1207 1.2 lneto at the end of this manual. 1208 1.1 mbalmer 1209 1.1 mbalmer 1210 1.1 mbalmer 1211 1.9 nikita 1212 1.9 nikita 1213 1.2 lneto <h2>3.1 – <a name="3.1">Lexical Conventions</a></h2> 1214 1.1 mbalmer 1215 1.1 mbalmer <p> 1216 1.2 lneto Lua is a free-form language. 1217 1.9 nikita It ignores spaces and comments between lexical elements (tokens), 1218 1.9 nikita except as delimiters between two tokens. 1219 1.9 nikita In source code, 1220 1.9 nikita Lua recognizes as spaces the standard ASCII whitespace 1221 1.9 nikita characters space, form feed, newline, 1222 1.9 nikita carriage return, horizontal tab, and vertical tab. 1223 1.1 mbalmer 1224 1.1 mbalmer 1225 1.1 mbalmer <p> 1226 1.2 lneto <em>Names</em> 1227 1.2 lneto (also called <em>identifiers</em>) 1228 1.9 nikita in Lua can be any string of Latin letters, 1229 1.9 nikita Arabic-Indic digits, and underscores, 1230 1.5 lneto not beginning with a digit and 1231 1.5 lneto not being a reserved word. 1232 1.2 lneto Identifiers are used to name variables, table fields, and labels. 1233 1.1 mbalmer 1234 1.1 mbalmer 1235 1.2 lneto <p> 1236 1.2 lneto The following <em>keywords</em> are reserved 1237 1.2 lneto and cannot be used as names: 1238 1.1 mbalmer 1239 1.1 mbalmer 1240 1.2 lneto <pre> 1241 1.2 lneto and break do else elseif end 1242 1.2 lneto false for function goto if in 1243 1.2 lneto local nil not or repeat return 1244 1.2 lneto then true until while 1245 1.2 lneto </pre> 1246 1.1 mbalmer 1247 1.2 lneto <p> 1248 1.2 lneto Lua is a case-sensitive language: 1249 1.2 lneto <code>and</code> is a reserved word, but <code>And</code> and <code>AND</code> 1250 1.2 lneto are two different, valid names. 1251 1.2 lneto As a convention, 1252 1.7 mbalmer programs should avoid creating 1253 1.2 lneto names that start with an underscore followed by 1254 1.2 lneto one or more uppercase letters (such as <a href="#pdf-_VERSION"><code>_VERSION</code></a>). 1255 1.1 mbalmer 1256 1.1 mbalmer 1257 1.1 mbalmer <p> 1258 1.2 lneto The following strings denote other tokens: 1259 1.1 mbalmer 1260 1.1 mbalmer <pre> 1261 1.2 lneto + - * / % ^ # 1262 1.2 lneto & ~ | << >> // 1263 1.2 lneto == ~= <= >= < > = 1264 1.2 lneto ( ) { } [ ] :: 1265 1.2 lneto ; : , . .. ... 1266 1.2 lneto </pre> 1267 1.1 mbalmer 1268 1.1 mbalmer <p> 1269 1.7 mbalmer A <em>short literal string</em> 1270 1.2 lneto can be delimited by matching single or double quotes, 1271 1.2 lneto and can contain the following C-like escape sequences: 1272 1.2 lneto '<code>\a</code>' (bell), 1273 1.2 lneto '<code>\b</code>' (backspace), 1274 1.2 lneto '<code>\f</code>' (form feed), 1275 1.2 lneto '<code>\n</code>' (newline), 1276 1.2 lneto '<code>\r</code>' (carriage return), 1277 1.2 lneto '<code>\t</code>' (horizontal tab), 1278 1.2 lneto '<code>\v</code>' (vertical tab), 1279 1.2 lneto '<code>\\</code>' (backslash), 1280 1.2 lneto '<code>\"</code>' (quotation mark [double quote]), 1281 1.2 lneto and '<code>\'</code>' (apostrophe [single quote]). 1282 1.7 mbalmer A backslash followed by a line break 1283 1.2 lneto results in a newline in the string. 1284 1.2 lneto The escape sequence '<code>\z</code>' skips the following span 1285 1.9 nikita of whitespace characters, 1286 1.2 lneto including line breaks; 1287 1.2 lneto it is particularly useful to break and indent a long literal string 1288 1.2 lneto into multiple lines without adding the newlines and spaces 1289 1.2 lneto into the string contents. 1290 1.7 mbalmer A short literal string cannot contain unescaped line breaks 1291 1.7 mbalmer nor escapes not forming a valid escape sequence. 1292 1.1 mbalmer 1293 1.1 mbalmer 1294 1.1 mbalmer <p> 1295 1.9 nikita We can specify any byte in a short literal string, 1296 1.9 nikita including embedded zeros, 1297 1.9 nikita by its numeric value. 1298 1.3 lneto This can be done 1299 1.3 lneto with the escape sequence <code>\x<em>XX</em></code>, 1300 1.2 lneto where <em>XX</em> is a sequence of exactly two hexadecimal digits, 1301 1.2 lneto or with the escape sequence <code>\<em>ddd</em></code>, 1302 1.2 lneto where <em>ddd</em> is a sequence of up to three decimal digits. 1303 1.3 lneto (Note that if a decimal escape sequence is to be followed by a digit, 1304 1.2 lneto it must be expressed using exactly three digits.) 1305 1.1 mbalmer 1306 1.1 mbalmer 1307 1.2 lneto <p> 1308 1.2 lneto The UTF-8 encoding of a Unicode character 1309 1.2 lneto can be inserted in a literal string with 1310 1.2 lneto the escape sequence <code>\u{<em>XXX</em>}</code> 1311 1.9 nikita (with mandatory enclosing braces), 1312 1.2 lneto where <em>XXX</em> is a sequence of one or more hexadecimal digits 1313 1.2 lneto representing the character code point. 1314 1.9 nikita This code point can be any value less than <em>2<sup>31</sup></em>. 1315 1.9 nikita (Lua uses the original UTF-8 specification here, 1316 1.9 nikita which is not restricted to valid Unicode code points.) 1317 1.1 mbalmer 1318 1.1 mbalmer 1319 1.2 lneto <p> 1320 1.2 lneto Literal strings can also be defined using a long format 1321 1.2 lneto enclosed by <em>long brackets</em>. 1322 1.2 lneto We define an <em>opening long bracket of level <em>n</em></em> as an opening 1323 1.2 lneto square bracket followed by <em>n</em> equal signs followed by another 1324 1.2 lneto opening square bracket. 1325 1.2 lneto So, an opening long bracket of level 0 is written as <code>[[</code>, 1326 1.2 lneto an opening long bracket of level 1 is written as <code>[=[</code>, 1327 1.2 lneto and so on. 1328 1.2 lneto A <em>closing long bracket</em> is defined similarly; 1329 1.2 lneto for instance, 1330 1.2 lneto a closing long bracket of level 4 is written as <code>]====]</code>. 1331 1.2 lneto A <em>long literal</em> starts with an opening long bracket of any level and 1332 1.2 lneto ends at the first closing long bracket of the same level. 1333 1.3 lneto It can contain any text except a closing bracket of the same level. 1334 1.2 lneto Literals in this bracketed form can run for several lines, 1335 1.2 lneto do not interpret any escape sequences, 1336 1.2 lneto and ignore long brackets of any other level. 1337 1.2 lneto Any kind of end-of-line sequence 1338 1.2 lneto (carriage return, newline, carriage return followed by newline, 1339 1.2 lneto or newline followed by carriage return) 1340 1.2 lneto is converted to a simple newline. 1341 1.9 nikita When the opening long bracket is immediately followed by a newline, 1342 1.9 nikita the newline is not included in the string. 1343 1.1 mbalmer 1344 1.1 mbalmer 1345 1.2 lneto <p> 1346 1.2 lneto As an example, in a system using ASCII 1347 1.2 lneto (in which '<code>a</code>' is coded as 97, 1348 1.2 lneto newline is coded as 10, and '<code>1</code>' is coded as 49), 1349 1.2 lneto the five literal strings below denote the same string: 1350 1.1 mbalmer 1351 1.1 mbalmer <pre> 1352 1.2 lneto a = 'alo\n123"' 1353 1.2 lneto a = "alo\n123\"" 1354 1.2 lneto a = '\97lo\10\04923"' 1355 1.2 lneto a = [[alo 1356 1.2 lneto 123"]] 1357 1.2 lneto a = [==[ 1358 1.2 lneto alo 1359 1.2 lneto 123"]==] 1360 1.1 mbalmer </pre> 1361 1.1 mbalmer 1362 1.1 mbalmer <p> 1363 1.7 mbalmer Any byte in a literal string not 1364 1.7 mbalmer explicitly affected by the previous rules represents itself. 1365 1.7 mbalmer However, Lua opens files for parsing in text mode, 1366 1.9 nikita and the system's file functions may have problems with 1367 1.7 mbalmer some control characters. 1368 1.7 mbalmer So, it is safer to represent 1369 1.9 nikita binary data as a quoted literal with 1370 1.7 mbalmer explicit escape sequences for the non-text characters. 1371 1.7 mbalmer 1372 1.7 mbalmer 1373 1.7 mbalmer <p> 1374 1.4 mbalmer A <em>numeric constant</em> (or <em>numeral</em>) 1375 1.3 lneto can be written with an optional fractional part 1376 1.2 lneto and an optional decimal exponent, 1377 1.2 lneto marked by a letter '<code>e</code>' or '<code>E</code>'. 1378 1.2 lneto Lua also accepts hexadecimal constants, 1379 1.2 lneto which start with <code>0x</code> or <code>0X</code>. 1380 1.2 lneto Hexadecimal constants also accept an optional fractional part 1381 1.2 lneto plus an optional binary exponent, 1382 1.2 lneto marked by a letter '<code>p</code>' or '<code>P</code>'. 1383 1.9 nikita 1384 1.9 nikita 1385 1.9 nikita <p> 1386 1.7 mbalmer A numeric constant with a radix point or an exponent 1387 1.2 lneto denotes a float; 1388 1.6 salazar otherwise, 1389 1.9 nikita if its value fits in an integer or it is a hexadecimal constant, 1390 1.9 nikita it denotes an integer; 1391 1.9 nikita otherwise (that is, a decimal integer numeral that overflows), 1392 1.9 nikita it denotes a float. 1393 1.9 nikita Hexadecimal numerals with neither a radix point nor an exponent 1394 1.9 nikita always denote an integer value; 1395 1.9 nikita if the value overflows, it <em>wraps around</em> 1396 1.9 nikita to fit into a valid integer. 1397 1.9 nikita 1398 1.9 nikita 1399 1.9 nikita <p> 1400 1.2 lneto Examples of valid integer constants are 1401 1.1 mbalmer 1402 1.1 mbalmer <pre> 1403 1.2 lneto 3 345 0xff 0xBEBADA 1404 1.1 mbalmer </pre><p> 1405 1.2 lneto Examples of valid float constants are 1406 1.1 mbalmer 1407 1.1 mbalmer <pre> 1408 1.2 lneto 3.0 3.1416 314.16e-2 0.31416E1 34e1 1409 1.2 lneto 0x0.1E 0xA23p-4 0X1.921FB54442D18P+1 1410 1.1 mbalmer </pre> 1411 1.1 mbalmer 1412 1.1 mbalmer <p> 1413 1.2 lneto A <em>comment</em> starts with a double hyphen (<code>--</code>) 1414 1.2 lneto anywhere outside a string. 1415 1.2 lneto If the text immediately after <code>--</code> is not an opening long bracket, 1416 1.2 lneto the comment is a <em>short comment</em>, 1417 1.2 lneto which runs until the end of the line. 1418 1.2 lneto Otherwise, it is a <em>long comment</em>, 1419 1.2 lneto which runs until the corresponding closing long bracket. 1420 1.2 lneto 1421 1.1 mbalmer 1422 1.1 mbalmer 1423 1.1 mbalmer 1424 1.1 mbalmer 1425 1.2 lneto <h2>3.2 – <a name="3.2">Variables</a></h2> 1426 1.1 mbalmer 1427 1.2 lneto <p> 1428 1.2 lneto Variables are places that store values. 1429 1.2 lneto There are three kinds of variables in Lua: 1430 1.2 lneto global variables, local variables, and table fields. 1431 1.1 mbalmer 1432 1.1 mbalmer 1433 1.2 lneto <p> 1434 1.2 lneto A single name can denote a global variable or a local variable 1435 1.2 lneto (or a function's formal parameter, 1436 1.2 lneto which is a particular kind of local variable): 1437 1.1 mbalmer 1438 1.1 mbalmer <pre> 1439 1.2 lneto var ::= Name 1440 1.1 mbalmer </pre><p> 1441 1.9 nikita Name denotes identifiers (see <a href="#3.1">§3.1</a>). 1442 1.1 mbalmer 1443 1.1 mbalmer 1444 1.1 mbalmer <p> 1445 1.2 lneto Any variable name is assumed to be global unless explicitly declared 1446 1.2 lneto as a local (see <a href="#3.3.7">§3.3.7</a>). 1447 1.2 lneto Local variables are <em>lexically scoped</em>: 1448 1.2 lneto local variables can be freely accessed by functions 1449 1.2 lneto defined inside their scope (see <a href="#3.5">§3.5</a>). 1450 1.2 lneto 1451 1.1 mbalmer 1452 1.2 lneto <p> 1453 1.2 lneto Before the first assignment to a variable, its value is <b>nil</b>. 1454 1.1 mbalmer 1455 1.1 mbalmer 1456 1.1 mbalmer <p> 1457 1.2 lneto Square brackets are used to index a table: 1458 1.1 mbalmer 1459 1.1 mbalmer <pre> 1460 1.2 lneto var ::= prefixexp ‘<b>[</b>’ exp ‘<b>]</b>’ 1461 1.1 mbalmer </pre><p> 1462 1.8 alnsn The meaning of accesses to table fields can be changed via metatables 1463 1.8 alnsn (see <a href="#2.4">§2.4</a>). 1464 1.1 mbalmer 1465 1.1 mbalmer 1466 1.1 mbalmer <p> 1467 1.2 lneto The syntax <code>var.Name</code> is just syntactic sugar for 1468 1.2 lneto <code>var["Name"]</code>: 1469 1.1 mbalmer 1470 1.1 mbalmer <pre> 1471 1.2 lneto var ::= prefixexp ‘<b>.</b>’ Name 1472 1.2 lneto </pre> 1473 1.1 mbalmer 1474 1.1 mbalmer <p> 1475 1.2 lneto An access to a global variable <code>x</code> 1476 1.2 lneto is equivalent to <code>_ENV.x</code>. 1477 1.2 lneto Due to the way that chunks are compiled, 1478 1.9 nikita the variable <code>_ENV</code> itself is never global (see <a href="#2.2">§2.2</a>). 1479 1.1 mbalmer 1480 1.1 mbalmer 1481 1.1 mbalmer 1482 1.1 mbalmer 1483 1.1 mbalmer 1484 1.2 lneto <h2>3.3 – <a name="3.3">Statements</a></h2> 1485 1.1 mbalmer 1486 1.9 nikita 1487 1.9 nikita 1488 1.1 mbalmer <p> 1489 1.2 lneto Lua supports an almost conventional set of statements, 1490 1.9 nikita similar to those in other conventional languages. 1491 1.2 lneto This set includes 1492 1.9 nikita blocks, assignments, control structures, function calls, 1493 1.2 lneto and variable declarations. 1494 1.2 lneto 1495 1.2 lneto 1496 1.1 mbalmer 1497 1.9 nikita 1498 1.9 nikita 1499 1.2 lneto <h3>3.3.1 – <a name="3.3.1">Blocks</a></h3> 1500 1.1 mbalmer 1501 1.1 mbalmer <p> 1502 1.2 lneto A block is a list of statements, 1503 1.2 lneto which are executed sequentially: 1504 1.1 mbalmer 1505 1.1 mbalmer <pre> 1506 1.2 lneto block ::= {stat} 1507 1.1 mbalmer </pre><p> 1508 1.2 lneto Lua has <em>empty statements</em> 1509 1.2 lneto that allow you to separate statements with semicolons, 1510 1.2 lneto start a block with a semicolon 1511 1.2 lneto or write two semicolons in sequence: 1512 1.1 mbalmer 1513 1.1 mbalmer <pre> 1514 1.2 lneto stat ::= ‘<b>;</b>’ 1515 1.2 lneto </pre> 1516 1.2 lneto 1517 1.2 lneto <p> 1518 1.9 nikita Both function calls and assignments 1519 1.2 lneto can start with an open parenthesis. 1520 1.2 lneto This possibility leads to an ambiguity in Lua's grammar. 1521 1.2 lneto Consider the following fragment: 1522 1.1 mbalmer 1523 1.1 mbalmer <pre> 1524 1.2 lneto a = b + c 1525 1.2 lneto (print or io.write)('done') 1526 1.1 mbalmer </pre><p> 1527 1.9 nikita The grammar could see this fragment in two ways: 1528 1.1 mbalmer 1529 1.1 mbalmer <pre> 1530 1.2 lneto a = b + c(print or io.write)('done') 1531 1.2 lneto 1532 1.2 lneto a = b + c; (print or io.write)('done') 1533 1.1 mbalmer </pre><p> 1534 1.2 lneto The current parser always sees such constructions 1535 1.2 lneto in the first way, 1536 1.2 lneto interpreting the open parenthesis 1537 1.2 lneto as the start of the arguments to a call. 1538 1.2 lneto To avoid this ambiguity, 1539 1.2 lneto it is a good practice to always precede with a semicolon 1540 1.2 lneto statements that start with a parenthesis: 1541 1.1 mbalmer 1542 1.1 mbalmer <pre> 1543 1.2 lneto ;(print or io.write)('done') 1544 1.2 lneto </pre> 1545 1.2 lneto 1546 1.2 lneto <p> 1547 1.2 lneto A block can be explicitly delimited to produce a single statement: 1548 1.1 mbalmer 1549 1.1 mbalmer <pre> 1550 1.2 lneto stat ::= <b>do</b> block <b>end</b> 1551 1.1 mbalmer </pre><p> 1552 1.2 lneto Explicit blocks are useful 1553 1.2 lneto to control the scope of variable declarations. 1554 1.2 lneto Explicit blocks are also sometimes used to 1555 1.2 lneto add a <b>return</b> statement in the middle 1556 1.2 lneto of another block (see <a href="#3.3.4">§3.3.4</a>). 1557 1.2 lneto 1558 1.2 lneto 1559 1.2 lneto 1560 1.2 lneto 1561 1.2 lneto 1562 1.2 lneto <h3>3.3.2 – <a name="3.3.2">Chunks</a></h3> 1563 1.2 lneto 1564 1.2 lneto <p> 1565 1.2 lneto The unit of compilation of Lua is called a <em>chunk</em>. 1566 1.2 lneto Syntactically, 1567 1.2 lneto a chunk is simply a block: 1568 1.1 mbalmer 1569 1.1 mbalmer <pre> 1570 1.2 lneto chunk ::= block 1571 1.2 lneto </pre> 1572 1.1 mbalmer 1573 1.2 lneto <p> 1574 1.2 lneto Lua handles a chunk as the body of an anonymous function 1575 1.2 lneto with a variable number of arguments 1576 1.2 lneto (see <a href="#3.4.11">§3.4.11</a>). 1577 1.2 lneto As such, chunks can define local variables, 1578 1.2 lneto receive arguments, and return values. 1579 1.2 lneto Moreover, such anonymous function is compiled as in the 1580 1.2 lneto scope of an external local variable called <code>_ENV</code> (see <a href="#2.2">§2.2</a>). 1581 1.9 nikita The resulting function always has <code>_ENV</code> as its only external variable, 1582 1.2 lneto even if it does not use that variable. 1583 1.1 mbalmer 1584 1.1 mbalmer 1585 1.1 mbalmer <p> 1586 1.2 lneto A chunk can be stored in a file or in a string inside the host program. 1587 1.2 lneto To execute a chunk, 1588 1.3 lneto Lua first <em>loads</em> it, 1589 1.3 lneto precompiling the chunk's code into instructions for a virtual machine, 1590 1.3 lneto and then Lua executes the compiled code 1591 1.2 lneto with an interpreter for the virtual machine. 1592 1.1 mbalmer 1593 1.1 mbalmer 1594 1.1 mbalmer <p> 1595 1.2 lneto Chunks can also be precompiled into binary form; 1596 1.9 nikita see the program <code>luac</code> and the function <a href="#pdf-string.dump"><code>string.dump</code></a> for details. 1597 1.2 lneto Programs in source and compiled forms are interchangeable; 1598 1.2 lneto Lua automatically detects the file type and acts accordingly (see <a href="#pdf-load"><code>load</code></a>). 1599 1.2 lneto 1600 1.2 lneto 1601 1.2 lneto 1602 1.1 mbalmer 1603 1.1 mbalmer 1604 1.2 lneto <h3>3.3.3 – <a name="3.3.3">Assignment</a></h3> 1605 1.1 mbalmer 1606 1.1 mbalmer <p> 1607 1.2 lneto Lua allows multiple assignments. 1608 1.2 lneto Therefore, the syntax for assignment 1609 1.2 lneto defines a list of variables on the left side 1610 1.2 lneto and a list of expressions on the right side. 1611 1.2 lneto The elements in both lists are separated by commas: 1612 1.1 mbalmer 1613 1.1 mbalmer <pre> 1614 1.2 lneto stat ::= varlist ‘<b>=</b>’ explist 1615 1.2 lneto varlist ::= var {‘<b>,</b>’ var} 1616 1.2 lneto explist ::= exp {‘<b>,</b>’ exp} 1617 1.1 mbalmer </pre><p> 1618 1.2 lneto Expressions are discussed in <a href="#3.4">§3.4</a>. 1619 1.1 mbalmer 1620 1.1 mbalmer 1621 1.1 mbalmer <p> 1622 1.2 lneto Before the assignment, 1623 1.2 lneto the list of values is <em>adjusted</em> to the length of 1624 1.2 lneto the list of variables. 1625 1.2 lneto If there are more values than needed, 1626 1.2 lneto the excess values are thrown away. 1627 1.2 lneto If there are fewer values than needed, 1628 1.9 nikita the list is extended with <b>nil</b>'s. 1629 1.2 lneto If the list of expressions ends with a function call, 1630 1.2 lneto then all values returned by that call enter the list of values, 1631 1.2 lneto before the adjustment 1632 1.2 lneto (except when the call is enclosed in parentheses; see <a href="#3.4">§3.4</a>). 1633 1.1 mbalmer 1634 1.1 mbalmer 1635 1.1 mbalmer <p> 1636 1.9 nikita If a variable is both assigned and read 1637 1.9 nikita inside a multiple assignment, 1638 1.9 nikita Lua ensures all reads get the value of the variable 1639 1.9 nikita before the assignment. 1640 1.2 lneto Thus the code 1641 1.1 mbalmer 1642 1.1 mbalmer <pre> 1643 1.2 lneto i = 3 1644 1.2 lneto i, a[i] = i+1, 20 1645 1.1 mbalmer </pre><p> 1646 1.2 lneto sets <code>a[3]</code> to 20, without affecting <code>a[4]</code> 1647 1.2 lneto because the <code>i</code> in <code>a[i]</code> is evaluated (to 3) 1648 1.2 lneto before it is assigned 4. 1649 1.2 lneto Similarly, the line 1650 1.1 mbalmer 1651 1.1 mbalmer <pre> 1652 1.2 lneto x, y = y, x 1653 1.2 lneto </pre><p> 1654 1.2 lneto exchanges the values of <code>x</code> and <code>y</code>, 1655 1.2 lneto and 1656 1.1 mbalmer 1657 1.2 lneto <pre> 1658 1.2 lneto x, y, z = y, z, x 1659 1.2 lneto </pre><p> 1660 1.2 lneto cyclically permutes the values of <code>x</code>, <code>y</code>, and <code>z</code>. 1661 1.1 mbalmer 1662 1.1 mbalmer 1663 1.2 lneto <p> 1664 1.9 nikita Note that this guarantee covers only accesses 1665 1.9 nikita syntactically inside the assignment statement. 1666 1.9 nikita If a function or a metamethod called during the assignment 1667 1.9 nikita changes the value of a variable, 1668 1.9 nikita Lua gives no guarantees about the order of that access. 1669 1.9 nikita 1670 1.9 nikita 1671 1.9 nikita <p> 1672 1.8 alnsn An assignment to a global name <code>x = val</code> 1673 1.8 alnsn is equivalent to the assignment 1674 1.8 alnsn <code>_ENV.x = val</code> (see <a href="#2.2">§2.2</a>). 1675 1.1 mbalmer 1676 1.1 mbalmer 1677 1.2 lneto <p> 1678 1.8 alnsn The meaning of assignments to table fields and 1679 1.8 alnsn global variables (which are actually table fields, too) 1680 1.8 alnsn can be changed via metatables (see <a href="#2.4">§2.4</a>). 1681 1.1 mbalmer 1682 1.1 mbalmer 1683 1.1 mbalmer 1684 1.1 mbalmer 1685 1.1 mbalmer 1686 1.2 lneto <h3>3.3.4 – <a name="3.3.4">Control Structures</a></h3><p> 1687 1.2 lneto The control structures 1688 1.2 lneto <b>if</b>, <b>while</b>, and <b>repeat</b> have the usual meaning and 1689 1.2 lneto familiar syntax: 1690 1.1 mbalmer 1691 1.1 mbalmer 1692 1.1 mbalmer 1693 1.1 mbalmer 1694 1.1 mbalmer <pre> 1695 1.2 lneto stat ::= <b>while</b> exp <b>do</b> block <b>end</b> 1696 1.2 lneto stat ::= <b>repeat</b> block <b>until</b> exp 1697 1.2 lneto stat ::= <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> 1698 1.1 mbalmer </pre><p> 1699 1.2 lneto Lua also has a <b>for</b> statement, in two flavors (see <a href="#3.3.5">§3.3.5</a>). 1700 1.1 mbalmer 1701 1.1 mbalmer 1702 1.2 lneto <p> 1703 1.2 lneto The condition expression of a 1704 1.2 lneto control structure can return any value. 1705 1.9 nikita Both <b>false</b> and <b>nil</b> test false. 1706 1.9 nikita All values different from <b>nil</b> and <b>false</b> test true. 1707 1.9 nikita In particular, the number 0 and the empty string also test true. 1708 1.1 mbalmer 1709 1.1 mbalmer 1710 1.1 mbalmer <p> 1711 1.2 lneto In the <b>repeat</b>–<b>until</b> loop, 1712 1.2 lneto the inner block does not end at the <b>until</b> keyword, 1713 1.2 lneto but only after the condition. 1714 1.2 lneto So, the condition can refer to local variables 1715 1.2 lneto declared inside the loop block. 1716 1.1 mbalmer 1717 1.1 mbalmer 1718 1.1 mbalmer <p> 1719 1.2 lneto The <b>goto</b> statement transfers the program control to a label. 1720 1.2 lneto For syntactical reasons, 1721 1.2 lneto labels in Lua are considered statements too: 1722 1.1 mbalmer 1723 1.1 mbalmer 1724 1.1 mbalmer 1725 1.2 lneto <pre> 1726 1.2 lneto stat ::= <b>goto</b> Name 1727 1.2 lneto stat ::= label 1728 1.2 lneto label ::= ‘<b>::</b>’ Name ‘<b>::</b>’ 1729 1.2 lneto </pre> 1730 1.1 mbalmer 1731 1.1 mbalmer <p> 1732 1.2 lneto A label is visible in the entire block where it is defined, 1733 1.9 nikita except inside nested functions. 1734 1.2 lneto A goto may jump to any visible label as long as it does not 1735 1.2 lneto enter into the scope of a local variable. 1736 1.9 nikita A label should not be declared 1737 1.9 nikita where a label with the same name is visible, 1738 1.9 nikita even if this other label has been declared in an enclosing block. 1739 1.1 mbalmer 1740 1.1 mbalmer 1741 1.1 mbalmer <p> 1742 1.2 lneto Labels and empty statements are called <em>void statements</em>, 1743 1.2 lneto as they perform no actions. 1744 1.1 mbalmer 1745 1.1 mbalmer 1746 1.1 mbalmer <p> 1747 1.2 lneto The <b>break</b> statement terminates the execution of a 1748 1.2 lneto <b>while</b>, <b>repeat</b>, or <b>for</b> loop, 1749 1.2 lneto skipping to the next statement after the loop: 1750 1.1 mbalmer 1751 1.1 mbalmer 1752 1.2 lneto <pre> 1753 1.2 lneto stat ::= <b>break</b> 1754 1.2 lneto </pre><p> 1755 1.2 lneto A <b>break</b> ends the innermost enclosing loop. 1756 1.1 mbalmer 1757 1.1 mbalmer 1758 1.1 mbalmer <p> 1759 1.2 lneto The <b>return</b> statement is used to return values 1760 1.3 lneto from a function or a chunk 1761 1.9 nikita (which is handled as an anonymous function). 1762 1.1 mbalmer 1763 1.2 lneto Functions can return more than one value, 1764 1.2 lneto so the syntax for the <b>return</b> statement is 1765 1.1 mbalmer 1766 1.2 lneto <pre> 1767 1.2 lneto stat ::= <b>return</b> [explist] [‘<b>;</b>’] 1768 1.2 lneto </pre> 1769 1.1 mbalmer 1770 1.1 mbalmer <p> 1771 1.2 lneto The <b>return</b> statement can only be written 1772 1.2 lneto as the last statement of a block. 1773 1.9 nikita If it is necessary to <b>return</b> in the middle of a block, 1774 1.2 lneto then an explicit inner block can be used, 1775 1.2 lneto as in the idiom <code>do return end</code>, 1776 1.2 lneto because now <b>return</b> is the last statement in its (inner) block. 1777 1.1 mbalmer 1778 1.1 mbalmer 1779 1.1 mbalmer 1780 1.1 mbalmer 1781 1.1 mbalmer 1782 1.2 lneto <h3>3.3.5 – <a name="3.3.5">For Statement</a></h3> 1783 1.1 mbalmer 1784 1.2 lneto <p> 1785 1.1 mbalmer 1786 1.2 lneto The <b>for</b> statement has two forms: 1787 1.4 mbalmer one numerical and one generic. 1788 1.1 mbalmer 1789 1.1 mbalmer 1790 1.9 nikita 1791 1.9 nikita <h4>The numerical <b>for</b> loop</h4> 1792 1.9 nikita 1793 1.2 lneto <p> 1794 1.4 mbalmer The numerical <b>for</b> loop repeats a block of code while a 1795 1.9 nikita control variable goes through an arithmetic progression. 1796 1.2 lneto It has the following syntax: 1797 1.1 mbalmer 1798 1.2 lneto <pre> 1799 1.2 lneto stat ::= <b>for</b> Name ‘<b>=</b>’ exp ‘<b>,</b>’ exp [‘<b>,</b>’ exp] <b>do</b> block <b>end</b> 1800 1.2 lneto </pre><p> 1801 1.9 nikita The given identifier (Name) defines the control variable, 1802 1.9 nikita which is a new variable local to the loop body (<em>block</em>). 1803 1.1 mbalmer 1804 1.1 mbalmer 1805 1.9 nikita <p> 1806 1.9 nikita The loop starts by evaluating once the three control expressions. 1807 1.9 nikita Their values are called respectively 1808 1.9 nikita the <em>initial value</em>, the <em>limit</em>, and the <em>step</em>. 1809 1.9 nikita If the step is absent, it defaults to 1. 1810 1.9 nikita 1811 1.2 lneto 1812 1.2 lneto <p> 1813 1.9 nikita If both the initial value and the step are integers, 1814 1.9 nikita the loop is done with integers; 1815 1.9 nikita note that the limit may not be an integer. 1816 1.9 nikita Otherwise, the three values are converted to 1817 1.9 nikita floats and the loop is done with floats. 1818 1.9 nikita Beware of floating-point accuracy in this case. 1819 1.1 mbalmer 1820 1.1 mbalmer 1821 1.9 nikita <p> 1822 1.9 nikita After that initialization, 1823 1.9 nikita the loop body is repeated with the value of the control variable 1824 1.9 nikita going through an arithmetic progression, 1825 1.9 nikita starting at the initial value, 1826 1.9 nikita with a common difference given by the step. 1827 1.9 nikita A negative step makes a decreasing sequence; 1828 1.9 nikita a step equal to zero raises an error. 1829 1.9 nikita The loop continues while the value is less than 1830 1.9 nikita or equal to the limit 1831 1.9 nikita (greater than or equal to for a negative step). 1832 1.9 nikita If the initial value is already greater than the limit 1833 1.9 nikita (or less than, if the step is negative), 1834 1.9 nikita the body is not executed. 1835 1.1 mbalmer 1836 1.1 mbalmer 1837 1.9 nikita <p> 1838 1.9 nikita For integer loops, 1839 1.9 nikita the control variable never wraps around; 1840 1.9 nikita instead, the loop ends in case of an overflow. 1841 1.1 mbalmer 1842 1.1 mbalmer 1843 1.9 nikita <p> 1844 1.9 nikita You should not change the value of the control variable 1845 1.9 nikita during the loop. 1846 1.2 lneto If you need its value after the loop, 1847 1.2 lneto assign it to another variable before exiting the loop. 1848 1.1 mbalmer 1849 1.9 nikita 1850 1.9 nikita 1851 1.9 nikita 1852 1.9 nikita 1853 1.9 nikita <h4>The generic <b>for</b> loop</h4> 1854 1.1 mbalmer 1855 1.2 lneto <p> 1856 1.2 lneto The generic <b>for</b> statement works over functions, 1857 1.2 lneto called <em>iterators</em>. 1858 1.2 lneto On each iteration, the iterator function is called to produce a new value, 1859 1.2 lneto stopping when this new value is <b>nil</b>. 1860 1.2 lneto The generic <b>for</b> loop has the following syntax: 1861 1.1 mbalmer 1862 1.2 lneto <pre> 1863 1.2 lneto stat ::= <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> 1864 1.2 lneto namelist ::= Name {‘<b>,</b>’ Name} 1865 1.2 lneto </pre><p> 1866 1.2 lneto A <b>for</b> statement like 1867 1.1 mbalmer 1868 1.2 lneto <pre> 1869 1.9 nikita for <em>var_1</em>, ···, <em>var_n</em> in <em>explist</em> do <em>body</em> end 1870 1.2 lneto </pre><p> 1871 1.9 nikita works as follows. 1872 1.9 nikita 1873 1.1 mbalmer 1874 1.9 nikita <p> 1875 1.9 nikita The names <em>var_i</em> declare loop variables local to the loop body. 1876 1.9 nikita The first of these variables is the <em>control variable</em>. 1877 1.2 lneto 1878 1.2 lneto 1879 1.9 nikita <p> 1880 1.9 nikita The loop starts by evaluating <em>explist</em> 1881 1.9 nikita to produce four values: 1882 1.9 nikita an <em>iterator function</em>, 1883 1.2 lneto a <em>state</em>, 1884 1.9 nikita an initial value for the control variable, 1885 1.9 nikita and a <em>closing value</em>. 1886 1.9 nikita 1887 1.9 nikita 1888 1.9 nikita <p> 1889 1.9 nikita Then, at each iteration, 1890 1.9 nikita Lua calls the iterator function with two arguments: 1891 1.9 nikita the state and the control variable. 1892 1.9 nikita The results from this call are then assigned to the loop variables, 1893 1.9 nikita following the rules of multiple assignments (see <a href="#3.3.3">§3.3.3</a>). 1894 1.9 nikita If the control variable becomes <b>nil</b>, 1895 1.9 nikita the loop terminates. 1896 1.9 nikita Otherwise, the body is executed and the loop goes 1897 1.9 nikita to the next iteration. 1898 1.9 nikita 1899 1.9 nikita 1900 1.9 nikita <p> 1901 1.9 nikita The closing value behaves like a 1902 1.9 nikita to-be-closed variable (see <a href="#3.3.8">§3.3.8</a>), 1903 1.9 nikita which can be used to release resources when the loop ends. 1904 1.9 nikita Otherwise, it does not interfere with the loop. 1905 1.9 nikita 1906 1.1 mbalmer 1907 1.9 nikita <p> 1908 1.9 nikita You should not change the value of the control variable 1909 1.9 nikita during the loop. 1910 1.1 mbalmer 1911 1.1 mbalmer 1912 1.1 mbalmer 1913 1.2 lneto 1914 1.2 lneto 1915 1.1 mbalmer 1916 1.1 mbalmer 1917 1.2 lneto <h3>3.3.6 – <a name="3.3.6">Function Calls as Statements</a></h3><p> 1918 1.2 lneto To allow possible side-effects, 1919 1.2 lneto function calls can be executed as statements: 1920 1.2 lneto 1921 1.1 mbalmer <pre> 1922 1.2 lneto stat ::= functioncall 1923 1.1 mbalmer </pre><p> 1924 1.2 lneto In this case, all returned values are thrown away. 1925 1.2 lneto Function calls are explained in <a href="#3.4.10">§3.4.10</a>. 1926 1.2 lneto 1927 1.2 lneto 1928 1.2 lneto 1929 1.1 mbalmer 1930 1.1 mbalmer 1931 1.2 lneto <h3>3.3.7 – <a name="3.3.7">Local Declarations</a></h3><p> 1932 1.2 lneto Local variables can be declared anywhere inside a block. 1933 1.9 nikita The declaration can include an initialization: 1934 1.1 mbalmer 1935 1.1 mbalmer <pre> 1936 1.9 nikita stat ::= <b>local</b> attnamelist [‘<b>=</b>’ explist] 1937 1.9 nikita attnamelist ::= Name attrib {‘<b>,</b>’ Name attrib} 1938 1.1 mbalmer </pre><p> 1939 1.2 lneto If present, an initial assignment has the same semantics 1940 1.2 lneto of a multiple assignment (see <a href="#3.3.3">§3.3.3</a>). 1941 1.2 lneto Otherwise, all variables are initialized with <b>nil</b>. 1942 1.2 lneto 1943 1.2 lneto 1944 1.2 lneto <p> 1945 1.9 nikita Each variable name may be postfixed by an attribute 1946 1.9 nikita (a name between angle brackets): 1947 1.9 nikita 1948 1.9 nikita <pre> 1949 1.9 nikita attrib ::= [‘<b><</b>’ Name ‘<b>></b>’] 1950 1.9 nikita </pre><p> 1951 1.9 nikita There are two possible attributes: 1952 1.9 nikita <code>const</code>, which declares a constant variable, 1953 1.9 nikita that is, a variable that cannot be assigned to 1954 1.9 nikita after its initialization; 1955 1.9 nikita and <code>close</code>, which declares a to-be-closed variable (see <a href="#3.3.8">§3.3.8</a>). 1956 1.9 nikita A list of variables can contain at most one to-be-closed variable. 1957 1.9 nikita 1958 1.9 nikita 1959 1.9 nikita <p> 1960 1.2 lneto A chunk is also a block (see <a href="#3.3.2">§3.3.2</a>), 1961 1.2 lneto and so local variables can be declared in a chunk outside any explicit block. 1962 1.1 mbalmer 1963 1.1 mbalmer 1964 1.2 lneto <p> 1965 1.2 lneto The visibility rules for local variables are explained in <a href="#3.5">§3.5</a>. 1966 1.2 lneto 1967 1.1 mbalmer 1968 1.1 mbalmer 1969 1.1 mbalmer 1970 1.1 mbalmer 1971 1.9 nikita <h3>3.3.8 – <a name="3.3.8">To-be-closed Variables</a></h3> 1972 1.9 nikita 1973 1.9 nikita <p> 1974 1.9 nikita A to-be-closed variable behaves like a constant local variable, 1975 1.9 nikita except that its value is <em>closed</em> whenever the variable 1976 1.9 nikita goes out of scope, including normal block termination, 1977 1.9 nikita exiting its block by <b>break</b>/<b>goto</b>/<b>return</b>, 1978 1.9 nikita or exiting by an error. 1979 1.9 nikita 1980 1.9 nikita 1981 1.9 nikita <p> 1982 1.9 nikita Here, to <em>close</em> a value means 1983 1.9 nikita to call its <code>__close</code> metamethod. 1984 1.9 nikita When calling the metamethod, 1985 1.9 nikita the value itself is passed as the first argument 1986 1.9 nikita and the error object that caused the exit (if any) 1987 1.9 nikita is passed as a second argument; 1988 1.9 nikita if there was no error, the second argument is <b>nil</b>. 1989 1.9 nikita 1990 1.9 nikita 1991 1.9 nikita <p> 1992 1.9 nikita The value assigned to a to-be-closed variable 1993 1.9 nikita must have a <code>__close</code> metamethod 1994 1.9 nikita or be a false value. 1995 1.9 nikita (<b>nil</b> and <b>false</b> are ignored as to-be-closed values.) 1996 1.9 nikita 1997 1.9 nikita 1998 1.9 nikita <p> 1999 1.9 nikita If several to-be-closed variables go out of scope at the same event, 2000 1.9 nikita they are closed in the reverse order that they were declared. 2001 1.9 nikita 2002 1.9 nikita 2003 1.9 nikita <p> 2004 1.9 nikita If there is any error while running a closing method, 2005 1.9 nikita that error is handled like an error in the regular code 2006 1.9 nikita where the variable was defined. 2007 1.9 nikita After an error, 2008 1.9 nikita the other pending closing methods will still be called. 2009 1.9 nikita 2010 1.9 nikita 2011 1.9 nikita <p> 2012 1.9 nikita If a coroutine yields and is never resumed again, 2013 1.9 nikita some variables may never go out of scope, 2014 1.9 nikita and therefore they will never be closed. 2015 1.9 nikita (These variables are the ones created inside the coroutine 2016 1.9 nikita and in scope at the point where the coroutine yielded.) 2017 1.9 nikita Similarly, if a coroutine ends with an error, 2018 1.9 nikita it does not unwind its stack, 2019 1.9 nikita so it does not close any variable. 2020 1.9 nikita In both cases, 2021 1.9 nikita you can either use finalizers 2022 1.9 nikita or call <a href="#pdf-coroutine.close"><code>coroutine.close</code></a> to close the variables. 2023 1.9 nikita However, if the coroutine was created 2024 1.9 nikita through <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a>, 2025 1.9 nikita then its corresponding function will close the coroutine 2026 1.9 nikita in case of errors. 2027 1.9 nikita 2028 1.9 nikita 2029 1.9 nikita 2030 1.9 nikita 2031 1.9 nikita 2032 1.1 mbalmer 2033 1.1 mbalmer 2034 1.2 lneto <h2>3.4 – <a name="3.4">Expressions</a></h2> 2035 1.1 mbalmer 2036 1.9 nikita 2037 1.9 nikita 2038 1.2 lneto <p> 2039 1.2 lneto The basic expressions in Lua are the following: 2040 1.1 mbalmer 2041 1.1 mbalmer <pre> 2042 1.2 lneto exp ::= prefixexp 2043 1.2 lneto exp ::= <b>nil</b> | <b>false</b> | <b>true</b> 2044 1.3 lneto exp ::= Numeral 2045 1.3 lneto exp ::= LiteralString 2046 1.2 lneto exp ::= functiondef 2047 1.2 lneto exp ::= tableconstructor 2048 1.2 lneto exp ::= ‘<b>...</b>’ 2049 1.2 lneto exp ::= exp binop exp 2050 1.2 lneto exp ::= unop exp 2051 1.2 lneto prefixexp ::= var | functioncall | ‘<b>(</b>’ exp ‘<b>)</b>’ 2052 1.2 lneto </pre> 2053 1.2 lneto 2054 1.2 lneto <p> 2055 1.3 lneto Numerals and literal strings are explained in <a href="#3.1">§3.1</a>; 2056 1.2 lneto variables are explained in <a href="#3.2">§3.2</a>; 2057 1.2 lneto function definitions are explained in <a href="#3.4.11">§3.4.11</a>; 2058 1.2 lneto function calls are explained in <a href="#3.4.10">§3.4.10</a>; 2059 1.2 lneto table constructors are explained in <a href="#3.4.9">§3.4.9</a>. 2060 1.2 lneto Vararg expressions, 2061 1.2 lneto denoted by three dots ('<code>...</code>'), can only be used when 2062 1.2 lneto directly inside a vararg function; 2063 1.2 lneto they are explained in <a href="#3.4.11">§3.4.11</a>. 2064 1.2 lneto 2065 1.1 mbalmer 2066 1.2 lneto <p> 2067 1.2 lneto Binary operators comprise arithmetic operators (see <a href="#3.4.1">§3.4.1</a>), 2068 1.2 lneto bitwise operators (see <a href="#3.4.2">§3.4.2</a>), 2069 1.2 lneto relational operators (see <a href="#3.4.4">§3.4.4</a>), logical operators (see <a href="#3.4.5">§3.4.5</a>), 2070 1.2 lneto and the concatenation operator (see <a href="#3.4.6">§3.4.6</a>). 2071 1.2 lneto Unary operators comprise the unary minus (see <a href="#3.4.1">§3.4.1</a>), 2072 1.6 salazar the unary bitwise NOT (see <a href="#3.4.2">§3.4.2</a>), 2073 1.3 lneto the unary logical <b>not</b> (see <a href="#3.4.5">§3.4.5</a>), 2074 1.2 lneto and the unary <em>length operator</em> (see <a href="#3.4.7">§3.4.7</a>). 2075 1.1 mbalmer 2076 1.1 mbalmer 2077 1.2 lneto <p> 2078 1.2 lneto Both function calls and vararg expressions can result in multiple values. 2079 1.2 lneto If a function call is used as a statement (see <a href="#3.3.6">§3.3.6</a>), 2080 1.2 lneto then its return list is adjusted to zero elements, 2081 1.2 lneto thus discarding all returned values. 2082 1.2 lneto If an expression is used as the last (or the only) element 2083 1.2 lneto of a list of expressions, 2084 1.2 lneto then no adjustment is made 2085 1.2 lneto (unless the expression is enclosed in parentheses). 2086 1.2 lneto In all other contexts, 2087 1.2 lneto Lua adjusts the result list to one element, 2088 1.2 lneto either discarding all values except the first one 2089 1.2 lneto or adding a single <b>nil</b> if there are no values. 2090 1.1 mbalmer 2091 1.1 mbalmer 2092 1.2 lneto <p> 2093 1.2 lneto Here are some examples: 2094 1.1 mbalmer 2095 1.1 mbalmer <pre> 2096 1.2 lneto f() -- adjusted to 0 results 2097 1.2 lneto g(f(), x) -- f() is adjusted to 1 result 2098 1.2 lneto g(x, f()) -- g gets x plus all results from f() 2099 1.2 lneto a,b,c = f(), x -- f() is adjusted to 1 result (c gets nil) 2100 1.8 alnsn a,b = ... -- a gets the first vararg argument, b gets 2101 1.2 lneto -- the second (both a and b can get nil if there 2102 1.8 alnsn -- is no corresponding vararg argument) 2103 1.2 lneto 2104 1.2 lneto a,b,c = x, f() -- f() is adjusted to 2 results 2105 1.2 lneto a,b,c = f() -- f() is adjusted to 3 results 2106 1.2 lneto return f() -- returns all results from f() 2107 1.8 alnsn return ... -- returns all received vararg arguments 2108 1.2 lneto return x,y,f() -- returns x, y, and all results from f() 2109 1.2 lneto {f()} -- creates a list with all results from f() 2110 1.8 alnsn {...} -- creates a list with all vararg arguments 2111 1.2 lneto {f(), nil} -- f() is adjusted to 1 result 2112 1.2 lneto </pre> 2113 1.2 lneto 2114 1.2 lneto <p> 2115 1.2 lneto Any expression enclosed in parentheses always results in only one value. 2116 1.2 lneto Thus, 2117 1.2 lneto <code>(f(x,y,z))</code> is always a single value, 2118 1.2 lneto even if <code>f</code> returns several values. 2119 1.2 lneto (The value of <code>(f(x,y,z))</code> is the first value returned by <code>f</code> 2120 1.2 lneto or <b>nil</b> if <code>f</code> does not return any values.) 2121 1.2 lneto 2122 1.1 mbalmer 2123 1.1 mbalmer 2124 1.9 nikita 2125 1.9 nikita 2126 1.2 lneto <h3>3.4.1 – <a name="3.4.1">Arithmetic Operators</a></h3><p> 2127 1.2 lneto Lua supports the following arithmetic operators: 2128 1.1 mbalmer 2129 1.3 lneto <ul> 2130 1.3 lneto <li><b><code>+</code>: </b>addition</li> 2131 1.3 lneto <li><b><code>-</code>: </b>subtraction</li> 2132 1.3 lneto <li><b><code>*</code>: </b>multiplication</li> 2133 1.3 lneto <li><b><code>/</code>: </b>float division</li> 2134 1.3 lneto <li><b><code>//</code>: </b>floor division</li> 2135 1.3 lneto <li><b><code>%</code>: </b>modulo</li> 2136 1.3 lneto <li><b><code>^</code>: </b>exponentiation</li> 2137 1.3 lneto <li><b><code>-</code>: </b>unary minus</li> 2138 1.3 lneto </ul> 2139 1.1 mbalmer 2140 1.2 lneto <p> 2141 1.3 lneto With the exception of exponentiation and float division, 2142 1.2 lneto the arithmetic operators work as follows: 2143 1.2 lneto If both operands are integers, 2144 1.2 lneto the operation is performed over integers and the result is an integer. 2145 1.9 nikita Otherwise, if both operands are numbers, 2146 1.2 lneto then they are converted to floats, 2147 1.9 nikita the operation is performed following the machine's rules 2148 1.2 lneto for floating-point arithmetic 2149 1.2 lneto (usually the IEEE 754 standard), 2150 1.2 lneto and the result is a float. 2151 1.9 nikita (The string library coerces strings to numbers in 2152 1.9 nikita arithmetic operations; see <a href="#3.4.3">§3.4.3</a> for details.) 2153 1.1 mbalmer 2154 1.1 mbalmer 2155 1.1 mbalmer <p> 2156 1.3 lneto Exponentiation and float division (<code>/</code>) 2157 1.2 lneto always convert their operands to floats 2158 1.2 lneto and the result is always a float. 2159 1.3 lneto Exponentiation uses the ISO C function <code>pow</code>, 2160 1.2 lneto so that it works for non-integer exponents too. 2161 1.1 mbalmer 2162 1.1 mbalmer 2163 1.1 mbalmer <p> 2164 1.7 mbalmer Floor division (<code>//</code>) is a division 2165 1.4 mbalmer that rounds the quotient towards minus infinity, 2166 1.9 nikita resulting in the floor of the division of its operands. 2167 1.1 mbalmer 2168 1.1 mbalmer 2169 1.1 mbalmer <p> 2170 1.2 lneto Modulo is defined as the remainder of a division 2171 1.4 mbalmer that rounds the quotient towards minus infinity (floor division). 2172 1.1 mbalmer 2173 1.1 mbalmer 2174 1.1 mbalmer <p> 2175 1.2 lneto In case of overflows in integer arithmetic, 2176 1.9 nikita all operations <em>wrap around</em>. 2177 1.2 lneto 2178 1.2 lneto 2179 1.2 lneto 2180 1.2 lneto <h3>3.4.2 – <a name="3.4.2">Bitwise Operators</a></h3><p> 2181 1.2 lneto Lua supports the following bitwise operators: 2182 1.1 mbalmer 2183 1.3 lneto <ul> 2184 1.6 salazar <li><b><code>&</code>: </b>bitwise AND</li> 2185 1.6 salazar <li><b><code>|</code>: </b>bitwise OR</li> 2186 1.6 salazar <li><b><code>~</code>: </b>bitwise exclusive OR</li> 2187 1.3 lneto <li><b><code>>></code>: </b>right shift</li> 2188 1.3 lneto <li><b><code><<</code>: </b>left shift</li> 2189 1.6 salazar <li><b><code>~</code>: </b>unary bitwise NOT</li> 2190 1.3 lneto </ul> 2191 1.1 mbalmer 2192 1.1 mbalmer <p> 2193 1.2 lneto All bitwise operations convert its operands to integers 2194 1.2 lneto (see <a href="#3.4.3">§3.4.3</a>), 2195 1.2 lneto operate on all bits of those integers, 2196 1.2 lneto and result in an integer. 2197 1.1 mbalmer 2198 1.1 mbalmer 2199 1.1 mbalmer <p> 2200 1.2 lneto Both right and left shifts fill the vacant bits with zeros. 2201 1.2 lneto Negative displacements shift to the other direction; 2202 1.2 lneto displacements with absolute values equal to or higher than 2203 1.2 lneto the number of bits in an integer 2204 1.3 lneto result in zero (as all bits are shifted out). 2205 1.2 lneto 2206 1.2 lneto 2207 1.2 lneto 2208 1.2 lneto 2209 1.2 lneto 2210 1.2 lneto <h3>3.4.3 – <a name="3.4.3">Coercions and Conversions</a></h3><p> 2211 1.2 lneto Lua provides some automatic conversions between some 2212 1.2 lneto types and representations at run time. 2213 1.3 lneto Bitwise operators always convert float operands to integers. 2214 1.3 lneto Exponentiation and float division 2215 1.3 lneto always convert integer operands to floats. 2216 1.3 lneto All other arithmetic operations applied to mixed numbers 2217 1.9 nikita (integers and floats) convert the integer operand to a float. 2218 1.2 lneto The C API also converts both integers to floats and 2219 1.2 lneto floats to integers, as needed. 2220 1.2 lneto Moreover, string concatenation accepts numbers as arguments, 2221 1.7 mbalmer besides strings. 2222 1.1 mbalmer 2223 1.1 mbalmer 2224 1.1 mbalmer <p> 2225 1.2 lneto In a conversion from integer to float, 2226 1.2 lneto if the integer value has an exact representation as a float, 2227 1.2 lneto that is the result. 2228 1.2 lneto Otherwise, 2229 1.3 lneto the conversion gets the nearest higher or 2230 1.3 lneto the nearest lower representable value. 2231 1.2 lneto This kind of conversion never fails. 2232 1.1 mbalmer 2233 1.1 mbalmer 2234 1.2 lneto <p> 2235 1.2 lneto The conversion from float to integer 2236 1.3 lneto checks whether the float has an exact representation as an integer 2237 1.3 lneto (that is, the float has an integral value and 2238 1.3 lneto it is in the range of integer representation). 2239 1.3 lneto If it does, that representation is the result. 2240 1.2 lneto Otherwise, the conversion fails. 2241 1.1 mbalmer 2242 1.1 mbalmer 2243 1.1 mbalmer <p> 2244 1.9 nikita Several places in Lua coerce strings to numbers when necessary. 2245 1.9 nikita In particular, 2246 1.9 nikita the string library sets metamethods that try to coerce 2247 1.9 nikita strings to numbers in all arithmetic operations. 2248 1.9 nikita If the conversion fails, 2249 1.9 nikita the library calls the metamethod of the other operand 2250 1.9 nikita (if present) or it raises an error. 2251 1.9 nikita Note that bitwise operators do not do this coercion. 2252 1.9 nikita 2253 1.9 nikita 2254 1.9 nikita <p> 2255 1.9 nikita Nonetheless, it is always a good practice not to rely on these 2256 1.9 nikita implicit coercions, as they are not always applied; 2257 1.9 nikita in particular, <code>"1"==1</code> is false and <code>"1"<1</code> raises an error 2258 1.9 nikita (see <a href="#3.4.4">§3.4.4</a>). 2259 1.9 nikita These coercions exist mainly for compatibility and may be removed 2260 1.9 nikita in future versions of the language. 2261 1.1 mbalmer 2262 1.1 mbalmer 2263 1.1 mbalmer <p> 2264 1.9 nikita A string is converted to an integer or a float 2265 1.9 nikita following its syntax and the rules of the Lua lexer. 2266 1.9 nikita The string may have also leading and trailing whitespaces and a sign. 2267 1.7 mbalmer All conversions from strings to numbers 2268 1.6 salazar accept both a dot and the current locale mark 2269 1.6 salazar as the radix character. 2270 1.6 salazar (The Lua lexer, however, accepts only a dot.) 2271 1.9 nikita If the string is not a valid numeral, 2272 1.9 nikita the conversion fails. 2273 1.9 nikita If necessary, the result of this first step is then converted 2274 1.9 nikita to a specific number subtype following the previous rules 2275 1.9 nikita for conversions between floats and integers. 2276 1.6 salazar 2277 1.6 salazar 2278 1.6 salazar <p> 2279 1.3 lneto The conversion from numbers to strings uses a 2280 1.3 lneto non-specified human-readable format. 2281 1.9 nikita To convert numbers to strings in any specific way, 2282 1.9 nikita use the function <a href="#pdf-string.format"><code>string.format</code></a>. 2283 1.2 lneto 2284 1.2 lneto 2285 1.2 lneto 2286 1.2 lneto 2287 1.2 lneto 2288 1.2 lneto <h3>3.4.4 – <a name="3.4.4">Relational Operators</a></h3><p> 2289 1.2 lneto Lua supports the following relational operators: 2290 1.3 lneto 2291 1.3 lneto <ul> 2292 1.3 lneto <li><b><code>==</code>: </b>equality</li> 2293 1.3 lneto <li><b><code>~=</code>: </b>inequality</li> 2294 1.3 lneto <li><b><code><</code>: </b>less than</li> 2295 1.3 lneto <li><b><code>></code>: </b>greater than</li> 2296 1.3 lneto <li><b><code><=</code>: </b>less or equal</li> 2297 1.3 lneto <li><b><code>>=</code>: </b>greater or equal</li> 2298 1.3 lneto </ul><p> 2299 1.2 lneto These operators always result in <b>false</b> or <b>true</b>. 2300 1.1 mbalmer 2301 1.1 mbalmer 2302 1.1 mbalmer <p> 2303 1.2 lneto Equality (<code>==</code>) first compares the type of its operands. 2304 1.2 lneto If the types are different, then the result is <b>false</b>. 2305 1.2 lneto Otherwise, the values of the operands are compared. 2306 1.9 nikita Strings are equal if they have the same byte content. 2307 1.4 mbalmer Numbers are equal if they denote the same mathematical value. 2308 1.1 mbalmer 2309 1.1 mbalmer 2310 1.1 mbalmer <p> 2311 1.2 lneto Tables, userdata, and threads 2312 1.2 lneto are compared by reference: 2313 1.2 lneto two objects are considered equal only if they are the same object. 2314 1.2 lneto Every time you create a new object 2315 1.9 nikita (a table, a userdata, or a thread), 2316 1.2 lneto this new object is different from any previously existing object. 2317 1.9 nikita A function is always equal to itself. 2318 1.9 nikita Functions with any detectable difference 2319 1.2 lneto (different behavior, different definition) are always different. 2320 1.9 nikita Functions created at different times but with no detectable differences 2321 1.8 alnsn may be classified as equal or not 2322 1.8 alnsn (depending on internal caching details). 2323 1.1 mbalmer 2324 1.1 mbalmer 2325 1.1 mbalmer <p> 2326 1.2 lneto You can change the way that Lua compares tables and userdata 2327 1.9 nikita by using the <code>__eq</code> metamethod (see <a href="#2.4">§2.4</a>). 2328 1.1 mbalmer 2329 1.1 mbalmer 2330 1.2 lneto <p> 2331 1.3 lneto Equality comparisons do not convert strings to numbers 2332 1.2 lneto or vice versa. 2333 1.2 lneto Thus, <code>"0"==0</code> evaluates to <b>false</b>, 2334 1.2 lneto and <code>t[0]</code> and <code>t["0"]</code> denote different 2335 1.2 lneto entries in a table. 2336 1.1 mbalmer 2337 1.1 mbalmer 2338 1.1 mbalmer <p> 2339 1.2 lneto The operator <code>~=</code> is exactly the negation of equality (<code>==</code>). 2340 1.1 mbalmer 2341 1.1 mbalmer 2342 1.2 lneto <p> 2343 1.2 lneto The order operators work as follows. 2344 1.2 lneto If both arguments are numbers, 2345 1.9 nikita then they are compared according to their mathematical values, 2346 1.9 nikita regardless of their subtypes. 2347 1.2 lneto Otherwise, if both arguments are strings, 2348 1.2 lneto then their values are compared according to the current locale. 2349 1.9 nikita Otherwise, Lua tries to call the <code>__lt</code> or the <code>__le</code> 2350 1.2 lneto metamethod (see <a href="#2.4">§2.4</a>). 2351 1.2 lneto A comparison <code>a > b</code> is translated to <code>b < a</code> 2352 1.2 lneto and <code>a >= b</code> is translated to <code>b <= a</code>. 2353 1.2 lneto 2354 1.2 lneto 2355 1.4 mbalmer <p> 2356 1.4 mbalmer Following the IEEE 754 standard, 2357 1.9 nikita the special value NaN is considered neither less than, 2358 1.9 nikita nor equal to, nor greater than any value, including itself. 2359 1.4 mbalmer 2360 1.4 mbalmer 2361 1.2 lneto 2362 1.2 lneto 2363 1.2 lneto 2364 1.2 lneto <h3>3.4.5 – <a name="3.4.5">Logical Operators</a></h3><p> 2365 1.2 lneto The logical operators in Lua are 2366 1.2 lneto <b>and</b>, <b>or</b>, and <b>not</b>. 2367 1.2 lneto Like the control structures (see <a href="#3.3.4">§3.3.4</a>), 2368 1.2 lneto all logical operators consider both <b>false</b> and <b>nil</b> as false 2369 1.2 lneto and anything else as true. 2370 1.2 lneto 2371 1.2 lneto 2372 1.2 lneto <p> 2373 1.2 lneto The negation operator <b>not</b> always returns <b>false</b> or <b>true</b>. 2374 1.2 lneto The conjunction operator <b>and</b> returns its first argument 2375 1.2 lneto if this value is <b>false</b> or <b>nil</b>; 2376 1.2 lneto otherwise, <b>and</b> returns its second argument. 2377 1.2 lneto The disjunction operator <b>or</b> returns its first argument 2378 1.2 lneto if this value is different from <b>nil</b> and <b>false</b>; 2379 1.2 lneto otherwise, <b>or</b> returns its second argument. 2380 1.2 lneto Both <b>and</b> and <b>or</b> use short-circuit evaluation; 2381 1.2 lneto that is, 2382 1.2 lneto the second operand is evaluated only if necessary. 2383 1.2 lneto Here are some examples: 2384 1.2 lneto 2385 1.2 lneto <pre> 2386 1.2 lneto 10 or 20 --> 10 2387 1.2 lneto 10 or error() --> 10 2388 1.2 lneto nil or "a" --> "a" 2389 1.2 lneto nil and 10 --> nil 2390 1.2 lneto false and error() --> false 2391 1.2 lneto false and nil --> false 2392 1.2 lneto false or nil --> nil 2393 1.2 lneto 10 and 20 --> 20 2394 1.9 nikita </pre> 2395 1.2 lneto 2396 1.2 lneto 2397 1.2 lneto 2398 1.2 lneto 2399 1.2 lneto <h3>3.4.6 – <a name="3.4.6">Concatenation</a></h3><p> 2400 1.2 lneto The string concatenation operator in Lua is 2401 1.2 lneto denoted by two dots ('<code>..</code>'). 2402 1.9 nikita If both operands are strings or numbers, 2403 1.9 nikita then the numbers are converted to strings 2404 1.9 nikita in a non-specified format (see <a href="#3.4.3">§3.4.3</a>). 2405 1.2 lneto Otherwise, the <code>__concat</code> metamethod is called (see <a href="#2.4">§2.4</a>). 2406 1.2 lneto 2407 1.2 lneto 2408 1.2 lneto 2409 1.2 lneto 2410 1.2 lneto 2411 1.2 lneto <h3>3.4.7 – <a name="3.4.7">The Length Operator</a></h3> 2412 1.2 lneto 2413 1.2 lneto <p> 2414 1.2 lneto The length operator is denoted by the unary prefix operator <code>#</code>. 2415 1.7 mbalmer 2416 1.7 mbalmer 2417 1.7 mbalmer <p> 2418 1.9 nikita The length of a string is its number of bytes. 2419 1.9 nikita (That is the usual meaning of string length when each 2420 1.9 nikita character is one byte.) 2421 1.2 lneto 2422 1.2 lneto 2423 1.2 lneto <p> 2424 1.7 mbalmer The length operator applied on a table 2425 1.7 mbalmer returns a border in that table. 2426 1.9 nikita A <em>border</em> in a table <code>t</code> is any non-negative integer 2427 1.7 mbalmer that satisfies the following condition: 2428 1.7 mbalmer 2429 1.7 mbalmer <pre> 2430 1.9 nikita (border == 0 or t[border] ~= nil) and 2431 1.9 nikita (t[border + 1] == nil or border == math.maxinteger) 2432 1.7 mbalmer </pre><p> 2433 1.7 mbalmer In words, 2434 1.9 nikita a border is any positive integer index present in the table 2435 1.9 nikita that is followed by an absent index, 2436 1.9 nikita plus two limit cases: 2437 1.9 nikita zero, when index 1 is absent; 2438 1.9 nikita and the maximum value for an integer, when that index is present. 2439 1.9 nikita Note that keys that are not positive integers 2440 1.9 nikita do not interfere with borders. 2441 1.7 mbalmer 2442 1.7 mbalmer 2443 1.7 mbalmer <p> 2444 1.7 mbalmer A table with exactly one border is called a <em>sequence</em>. 2445 1.7 mbalmer For instance, the table <code>{10, 20, 30, 40, 50}</code> is a sequence, 2446 1.7 mbalmer as it has only one border (5). 2447 1.7 mbalmer The table <code>{10, 20, 30, nil, 50}</code> has two borders (3 and 5), 2448 1.7 mbalmer and therefore it is not a sequence. 2449 1.9 nikita (The <b>nil</b> at index 4 is called a <em>hole</em>.) 2450 1.7 mbalmer The table <code>{nil, 20, 30, nil, nil, 60, nil}</code> 2451 1.7 mbalmer has three borders (0, 3, and 6), 2452 1.7 mbalmer so it is not a sequence, too. 2453 1.7 mbalmer The table <code>{}</code> is a sequence with border 0. 2454 1.7 mbalmer 2455 1.7 mbalmer 2456 1.7 mbalmer <p> 2457 1.7 mbalmer When <code>t</code> is a sequence, 2458 1.7 mbalmer <code>#t</code> returns its only border, 2459 1.7 mbalmer which corresponds to the intuitive notion of the length of the sequence. 2460 1.7 mbalmer When <code>t</code> is not a sequence, 2461 1.7 mbalmer <code>#t</code> can return any of its borders. 2462 1.7 mbalmer (The exact one depends on details of 2463 1.7 mbalmer the internal representation of the table, 2464 1.7 mbalmer which in turn can depend on how the table was populated and 2465 1.7 mbalmer the memory addresses of its non-numeric keys.) 2466 1.2 lneto 2467 1.2 lneto 2468 1.2 lneto <p> 2469 1.7 mbalmer The computation of the length of a table 2470 1.7 mbalmer has a guaranteed worst time of <em>O(log n)</em>, 2471 1.9 nikita where <em>n</em> is the largest integer key in the table. 2472 1.7 mbalmer 2473 1.2 lneto 2474 1.7 mbalmer <p> 2475 1.7 mbalmer A program can modify the behavior of the length operator for 2476 1.7 mbalmer any value but strings through the <code>__len</code> metamethod (see <a href="#2.4">§2.4</a>). 2477 1.2 lneto 2478 1.2 lneto 2479 1.2 lneto 2480 1.2 lneto 2481 1.2 lneto 2482 1.2 lneto <h3>3.4.8 – <a name="3.4.8">Precedence</a></h3><p> 2483 1.2 lneto Operator precedence in Lua follows the table below, 2484 1.2 lneto from lower to higher priority: 2485 1.2 lneto 2486 1.2 lneto <pre> 2487 1.2 lneto or 2488 1.2 lneto and 2489 1.2 lneto < > <= >= ~= == 2490 1.2 lneto | 2491 1.2 lneto ~ 2492 1.2 lneto & 2493 1.2 lneto << >> 2494 1.2 lneto .. 2495 1.2 lneto + - 2496 1.2 lneto * / // % 2497 1.2 lneto unary operators (not # - ~) 2498 1.2 lneto ^ 2499 1.2 lneto </pre><p> 2500 1.2 lneto As usual, 2501 1.2 lneto you can use parentheses to change the precedences of an expression. 2502 1.2 lneto The concatenation ('<code>..</code>') and exponentiation ('<code>^</code>') 2503 1.2 lneto operators are right associative. 2504 1.2 lneto All other binary operators are left associative. 2505 1.2 lneto 2506 1.2 lneto 2507 1.2 lneto 2508 1.2 lneto 2509 1.2 lneto 2510 1.2 lneto <h3>3.4.9 – <a name="3.4.9">Table Constructors</a></h3><p> 2511 1.2 lneto Table constructors are expressions that create tables. 2512 1.2 lneto Every time a constructor is evaluated, a new table is created. 2513 1.2 lneto A constructor can be used to create an empty table 2514 1.2 lneto or to create a table and initialize some of its fields. 2515 1.2 lneto The general syntax for constructors is 2516 1.2 lneto 2517 1.2 lneto <pre> 2518 1.2 lneto tableconstructor ::= ‘<b>{</b>’ [fieldlist] ‘<b>}</b>’ 2519 1.2 lneto fieldlist ::= field {fieldsep field} [fieldsep] 2520 1.2 lneto field ::= ‘<b>[</b>’ exp ‘<b>]</b>’ ‘<b>=</b>’ exp | Name ‘<b>=</b>’ exp | exp 2521 1.2 lneto fieldsep ::= ‘<b>,</b>’ | ‘<b>;</b>’ 2522 1.2 lneto </pre> 2523 1.2 lneto 2524 1.2 lneto <p> 2525 1.2 lneto Each field of the form <code>[exp1] = exp2</code> adds to the new table an entry 2526 1.2 lneto with key <code>exp1</code> and value <code>exp2</code>. 2527 1.2 lneto A field of the form <code>name = exp</code> is equivalent to 2528 1.2 lneto <code>["name"] = exp</code>. 2529 1.9 nikita Fields of the form <code>exp</code> are equivalent to 2530 1.3 lneto <code>[i] = exp</code>, where <code>i</code> are consecutive integers 2531 1.9 nikita starting with 1; 2532 1.9 nikita fields in the other formats do not affect this counting. 2533 1.2 lneto For example, 2534 1.2 lneto 2535 1.2 lneto <pre> 2536 1.2 lneto a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 } 2537 1.2 lneto </pre><p> 2538 1.2 lneto is equivalent to 2539 1.2 lneto 2540 1.2 lneto <pre> 2541 1.2 lneto do 2542 1.2 lneto local t = {} 2543 1.2 lneto t[f(1)] = g 2544 1.2 lneto t[1] = "x" -- 1st exp 2545 1.2 lneto t[2] = "y" -- 2nd exp 2546 1.2 lneto t.x = 1 -- t["x"] = 1 2547 1.2 lneto t[3] = f(x) -- 3rd exp 2548 1.2 lneto t[30] = 23 2549 1.2 lneto t[4] = 45 -- 4th exp 2550 1.2 lneto a = t 2551 1.2 lneto end 2552 1.2 lneto </pre> 2553 1.2 lneto 2554 1.2 lneto <p> 2555 1.3 lneto The order of the assignments in a constructor is undefined. 2556 1.3 lneto (This order would be relevant only when there are repeated keys.) 2557 1.3 lneto 2558 1.3 lneto 2559 1.3 lneto <p> 2560 1.2 lneto If the last field in the list has the form <code>exp</code> 2561 1.2 lneto and the expression is a function call or a vararg expression, 2562 1.2 lneto then all values returned by this expression enter the list consecutively 2563 1.2 lneto (see <a href="#3.4.10">§3.4.10</a>). 2564 1.2 lneto 2565 1.2 lneto 2566 1.2 lneto <p> 2567 1.2 lneto The field list can have an optional trailing separator, 2568 1.2 lneto as a convenience for machine-generated code. 2569 1.2 lneto 2570 1.2 lneto 2571 1.2 lneto 2572 1.2 lneto 2573 1.2 lneto 2574 1.2 lneto <h3>3.4.10 – <a name="3.4.10">Function Calls</a></h3><p> 2575 1.2 lneto A function call in Lua has the following syntax: 2576 1.2 lneto 2577 1.2 lneto <pre> 2578 1.2 lneto functioncall ::= prefixexp args 2579 1.2 lneto </pre><p> 2580 1.2 lneto In a function call, 2581 1.2 lneto first prefixexp and args are evaluated. 2582 1.2 lneto If the value of prefixexp has type <em>function</em>, 2583 1.2 lneto then this function is called 2584 1.2 lneto with the given arguments. 2585 1.9 nikita Otherwise, if present, 2586 1.9 nikita the prefixexp <code>__call</code> metamethod is called: 2587 1.9 nikita its first argument is the value of prefixexp, 2588 1.2 lneto followed by the original call arguments 2589 1.2 lneto (see <a href="#2.4">§2.4</a>). 2590 1.2 lneto 2591 1.2 lneto 2592 1.2 lneto <p> 2593 1.2 lneto The form 2594 1.2 lneto 2595 1.2 lneto <pre> 2596 1.2 lneto functioncall ::= prefixexp ‘<b>:</b>’ Name args 2597 1.2 lneto </pre><p> 2598 1.9 nikita can be used to emulate methods. 2599 1.2 lneto A call <code>v:name(<em>args</em>)</code> 2600 1.2 lneto is syntactic sugar for <code>v.name(v,<em>args</em>)</code>, 2601 1.2 lneto except that <code>v</code> is evaluated only once. 2602 1.2 lneto 2603 1.2 lneto 2604 1.2 lneto <p> 2605 1.2 lneto Arguments have the following syntax: 2606 1.2 lneto 2607 1.2 lneto <pre> 2608 1.2 lneto args ::= ‘<b>(</b>’ [explist] ‘<b>)</b>’ 2609 1.2 lneto args ::= tableconstructor 2610 1.3 lneto args ::= LiteralString 2611 1.2 lneto </pre><p> 2612 1.2 lneto All argument expressions are evaluated before the call. 2613 1.2 lneto A call of the form <code>f{<em>fields</em>}</code> is 2614 1.2 lneto syntactic sugar for <code>f({<em>fields</em>})</code>; 2615 1.2 lneto that is, the argument list is a single new table. 2616 1.2 lneto A call of the form <code>f'<em>string</em>'</code> 2617 1.2 lneto (or <code>f"<em>string</em>"</code> or <code>f[[<em>string</em>]]</code>) 2618 1.2 lneto is syntactic sugar for <code>f('<em>string</em>')</code>; 2619 1.2 lneto that is, the argument list is a single literal string. 2620 1.2 lneto 2621 1.2 lneto 2622 1.2 lneto <p> 2623 1.9 nikita A call of the form <code>return <em>functioncall</em></code> not in the 2624 1.9 nikita scope of a to-be-closed variable is called a <em>tail call</em>. 2625 1.2 lneto Lua implements <em>proper tail calls</em> 2626 1.2 lneto (or <em>proper tail recursion</em>): 2627 1.2 lneto in a tail call, 2628 1.2 lneto the called function reuses the stack entry of the calling function. 2629 1.2 lneto Therefore, there is no limit on the number of nested tail calls that 2630 1.2 lneto a program can execute. 2631 1.2 lneto However, a tail call erases any debug information about the 2632 1.2 lneto calling function. 2633 1.2 lneto Note that a tail call only happens with a particular syntax, 2634 1.9 nikita where the <b>return</b> has one single function call as argument, 2635 1.9 nikita and it is outside the scope of any to-be-closed variable. 2636 1.9 nikita This syntax makes the calling function return exactly 2637 1.9 nikita the returns of the called function, 2638 1.9 nikita without any intervening action. 2639 1.2 lneto So, none of the following examples are tail calls: 2640 1.2 lneto 2641 1.2 lneto <pre> 2642 1.2 lneto return (f(x)) -- results adjusted to 1 2643 1.9 nikita return 2 * f(x) -- result multiplied by 2 2644 1.2 lneto return x, f(x) -- additional results 2645 1.2 lneto f(x); return -- results discarded 2646 1.2 lneto return x or f(x) -- results adjusted to 1 2647 1.2 lneto </pre> 2648 1.2 lneto 2649 1.2 lneto 2650 1.2 lneto 2651 1.2 lneto 2652 1.2 lneto <h3>3.4.11 – <a name="3.4.11">Function Definitions</a></h3> 2653 1.2 lneto 2654 1.2 lneto <p> 2655 1.2 lneto The syntax for function definition is 2656 1.2 lneto 2657 1.2 lneto <pre> 2658 1.2 lneto functiondef ::= <b>function</b> funcbody 2659 1.2 lneto funcbody ::= ‘<b>(</b>’ [parlist] ‘<b>)</b>’ block <b>end</b> 2660 1.2 lneto </pre> 2661 1.2 lneto 2662 1.2 lneto <p> 2663 1.2 lneto The following syntactic sugar simplifies function definitions: 2664 1.2 lneto 2665 1.2 lneto <pre> 2666 1.2 lneto stat ::= <b>function</b> funcname funcbody 2667 1.2 lneto stat ::= <b>local</b> <b>function</b> Name funcbody 2668 1.2 lneto funcname ::= Name {‘<b>.</b>’ Name} [‘<b>:</b>’ Name] 2669 1.2 lneto </pre><p> 2670 1.2 lneto The statement 2671 1.2 lneto 2672 1.2 lneto <pre> 2673 1.2 lneto function f () <em>body</em> end 2674 1.2 lneto </pre><p> 2675 1.2 lneto translates to 2676 1.2 lneto 2677 1.2 lneto <pre> 2678 1.2 lneto f = function () <em>body</em> end 2679 1.2 lneto </pre><p> 2680 1.2 lneto The statement 2681 1.2 lneto 2682 1.2 lneto <pre> 2683 1.2 lneto function t.a.b.c.f () <em>body</em> end 2684 1.2 lneto </pre><p> 2685 1.2 lneto translates to 2686 1.2 lneto 2687 1.2 lneto <pre> 2688 1.2 lneto t.a.b.c.f = function () <em>body</em> end 2689 1.2 lneto </pre><p> 2690 1.2 lneto The statement 2691 1.2 lneto 2692 1.2 lneto <pre> 2693 1.2 lneto local function f () <em>body</em> end 2694 1.2 lneto </pre><p> 2695 1.2 lneto translates to 2696 1.2 lneto 2697 1.2 lneto <pre> 2698 1.2 lneto local f; f = function () <em>body</em> end 2699 1.2 lneto </pre><p> 2700 1.2 lneto not to 2701 1.2 lneto 2702 1.2 lneto <pre> 2703 1.2 lneto local f = function () <em>body</em> end 2704 1.2 lneto </pre><p> 2705 1.2 lneto (This only makes a difference when the body of the function 2706 1.2 lneto contains references to <code>f</code>.) 2707 1.2 lneto 2708 1.2 lneto 2709 1.2 lneto <p> 2710 1.2 lneto A function definition is an executable expression, 2711 1.2 lneto whose value has type <em>function</em>. 2712 1.2 lneto When Lua precompiles a chunk, 2713 1.9 nikita all its function bodies are precompiled too, 2714 1.9 nikita but they are not created yet. 2715 1.2 lneto Then, whenever Lua executes the function definition, 2716 1.2 lneto the function is <em>instantiated</em> (or <em>closed</em>). 2717 1.9 nikita This function instance, or <em>closure</em>, 2718 1.2 lneto is the final value of the expression. 2719 1.2 lneto 2720 1.2 lneto 2721 1.2 lneto <p> 2722 1.2 lneto Parameters act as local variables that are 2723 1.2 lneto initialized with the argument values: 2724 1.2 lneto 2725 1.2 lneto <pre> 2726 1.2 lneto parlist ::= namelist [‘<b>,</b>’ ‘<b>...</b>’] | ‘<b>...</b>’ 2727 1.2 lneto </pre><p> 2728 1.9 nikita When a Lua function is called, 2729 1.9 nikita it adjusts its list of arguments to 2730 1.9 nikita the length of its list of parameters, 2731 1.2 lneto unless the function is a <em>vararg function</em>, 2732 1.2 lneto which is indicated by three dots ('<code>...</code>') 2733 1.2 lneto at the end of its parameter list. 2734 1.2 lneto A vararg function does not adjust its argument list; 2735 1.2 lneto instead, it collects all extra arguments and supplies them 2736 1.2 lneto to the function through a <em>vararg expression</em>, 2737 1.2 lneto which is also written as three dots. 2738 1.2 lneto The value of this expression is a list of all actual extra arguments, 2739 1.2 lneto similar to a function with multiple results. 2740 1.2 lneto If a vararg expression is used inside another expression 2741 1.2 lneto or in the middle of a list of expressions, 2742 1.2 lneto then its return list is adjusted to one element. 2743 1.2 lneto If the expression is used as the last element of a list of expressions, 2744 1.2 lneto then no adjustment is made 2745 1.2 lneto (unless that last expression is enclosed in parentheses). 2746 1.2 lneto 2747 1.2 lneto 2748 1.2 lneto <p> 2749 1.2 lneto As an example, consider the following definitions: 2750 1.2 lneto 2751 1.2 lneto <pre> 2752 1.2 lneto function f(a, b) end 2753 1.2 lneto function g(a, b, ...) end 2754 1.2 lneto function r() return 1,2,3 end 2755 1.2 lneto </pre><p> 2756 1.2 lneto Then, we have the following mapping from arguments to parameters and 2757 1.2 lneto to the vararg expression: 2758 1.1 mbalmer 2759 1.1 mbalmer <pre> 2760 1.9 nikita CALL PARAMETERS 2761 1.2 lneto 2762 1.2 lneto f(3) a=3, b=nil 2763 1.2 lneto f(3, 4) a=3, b=4 2764 1.2 lneto f(3, 4, 5) a=3, b=4 2765 1.2 lneto f(r(), 10) a=1, b=10 2766 1.2 lneto f(r()) a=1, b=2 2767 1.2 lneto 2768 1.2 lneto g(3) a=3, b=nil, ... --> (nothing) 2769 1.2 lneto g(3, 4) a=3, b=4, ... --> (nothing) 2770 1.2 lneto g(3, 4, 5, 8) a=3, b=4, ... --> 5 8 2771 1.2 lneto g(5, r()) a=5, b=1, ... --> 2 3 2772 1.1 mbalmer </pre> 2773 1.1 mbalmer 2774 1.1 mbalmer <p> 2775 1.2 lneto Results are returned using the <b>return</b> statement (see <a href="#3.3.4">§3.3.4</a>). 2776 1.2 lneto If control reaches the end of a function 2777 1.2 lneto without encountering a <b>return</b> statement, 2778 1.2 lneto then the function returns with no results. 2779 1.1 mbalmer 2780 1.1 mbalmer 2781 1.1 mbalmer <p> 2782 1.1 mbalmer 2783 1.2 lneto There is a system-dependent limit on the number of values 2784 1.2 lneto that a function may return. 2785 1.9 nikita This limit is guaranteed to be greater than 1000. 2786 1.1 mbalmer 2787 1.1 mbalmer 2788 1.1 mbalmer <p> 2789 1.2 lneto The <em>colon</em> syntax 2790 1.9 nikita is used to emulate <em>methods</em>, 2791 1.9 nikita adding an implicit extra parameter <code>self</code> to the function. 2792 1.2 lneto Thus, the statement 2793 1.1 mbalmer 2794 1.2 lneto <pre> 2795 1.2 lneto function t.a.b.c:f (<em>params</em>) <em>body</em> end 2796 1.2 lneto </pre><p> 2797 1.2 lneto is syntactic sugar for 2798 1.1 mbalmer 2799 1.2 lneto <pre> 2800 1.2 lneto t.a.b.c.f = function (self, <em>params</em>) <em>body</em> end 2801 1.2 lneto </pre> 2802 1.1 mbalmer 2803 1.1 mbalmer 2804 1.1 mbalmer 2805 1.1 mbalmer 2806 1.1 mbalmer 2807 1.1 mbalmer 2808 1.2 lneto <h2>3.5 – <a name="3.5">Visibility Rules</a></h2> 2809 1.1 mbalmer 2810 1.1 mbalmer <p> 2811 1.1 mbalmer 2812 1.2 lneto Lua is a lexically scoped language. 2813 1.2 lneto The scope of a local variable begins at the first statement after 2814 1.2 lneto its declaration and lasts until the last non-void statement 2815 1.2 lneto of the innermost block that includes the declaration. 2816 1.2 lneto Consider the following example: 2817 1.1 mbalmer 2818 1.2 lneto <pre> 2819 1.2 lneto x = 10 -- global variable 2820 1.2 lneto do -- new block 2821 1.2 lneto local x = x -- new 'x', with value 10 2822 1.2 lneto print(x) --> 10 2823 1.2 lneto x = x+1 2824 1.2 lneto do -- another block 2825 1.2 lneto local x = x+1 -- another 'x' 2826 1.2 lneto print(x) --> 12 2827 1.2 lneto end 2828 1.2 lneto print(x) --> 11 2829 1.2 lneto end 2830 1.2 lneto print(x) --> 10 (the global one) 2831 1.2 lneto </pre> 2832 1.1 mbalmer 2833 1.1 mbalmer <p> 2834 1.2 lneto Notice that, in a declaration like <code>local x = x</code>, 2835 1.2 lneto the new <code>x</code> being declared is not in scope yet, 2836 1.2 lneto and so the second <code>x</code> refers to the outside variable. 2837 1.1 mbalmer 2838 1.1 mbalmer 2839 1.1 mbalmer <p> 2840 1.2 lneto Because of the lexical scoping rules, 2841 1.2 lneto local variables can be freely accessed by functions 2842 1.2 lneto defined inside their scope. 2843 1.9 nikita A local variable used by an inner function is called an <em>upvalue</em> 2844 1.9 nikita (or <em>external local variable</em>, or simply <em>external variable</em>) 2845 1.2 lneto inside the inner function. 2846 1.1 mbalmer 2847 1.1 mbalmer 2848 1.1 mbalmer <p> 2849 1.2 lneto Notice that each execution of a <b>local</b> statement 2850 1.2 lneto defines new local variables. 2851 1.2 lneto Consider the following example: 2852 1.1 mbalmer 2853 1.1 mbalmer <pre> 2854 1.2 lneto a = {} 2855 1.2 lneto local x = 20 2856 1.9 nikita for i = 1, 10 do 2857 1.2 lneto local y = 0 2858 1.9 nikita a[i] = function () y = y + 1; return x + y end 2859 1.1 mbalmer end 2860 1.1 mbalmer </pre><p> 2861 1.2 lneto The loop creates ten closures 2862 1.2 lneto (that is, ten instances of the anonymous function). 2863 1.2 lneto Each of these closures uses a different <code>y</code> variable, 2864 1.2 lneto while all of them share the same <code>x</code>. 2865 1.1 mbalmer 2866 1.1 mbalmer 2867 1.1 mbalmer 2868 1.1 mbalmer 2869 1.1 mbalmer 2870 1.2 lneto <h1>4 – <a name="4">The Application Program Interface</a></h1> 2871 1.1 mbalmer 2872 1.9 nikita 2873 1.9 nikita 2874 1.1 mbalmer <p> 2875 1.1 mbalmer 2876 1.1 mbalmer This section describes the C API for Lua, that is, 2877 1.1 mbalmer the set of C functions available to the host program to communicate 2878 1.1 mbalmer with Lua. 2879 1.1 mbalmer All API functions and related types and constants 2880 1.1 mbalmer are declared in the header file <a name="pdf-lua.h"><code>lua.h</code></a>. 2881 1.1 mbalmer 2882 1.1 mbalmer 2883 1.1 mbalmer <p> 2884 1.1 mbalmer Even when we use the term "function", 2885 1.1 mbalmer any facility in the API may be provided as a macro instead. 2886 1.2 lneto Except where stated otherwise, 2887 1.2 lneto all such macros use each of their arguments exactly once 2888 1.1 mbalmer (except for the first argument, which is always a Lua state), 2889 1.1 mbalmer and so do not generate any hidden side-effects. 2890 1.1 mbalmer 2891 1.1 mbalmer 2892 1.1 mbalmer <p> 2893 1.1 mbalmer As in most C libraries, 2894 1.9 nikita the Lua API functions do not check their arguments 2895 1.9 nikita for validity or consistency. 2896 1.1 mbalmer However, you can change this behavior by compiling Lua 2897 1.2 lneto with the macro <a name="pdf-LUA_USE_APICHECK"><code>LUA_USE_APICHECK</code></a> defined. 2898 1.1 mbalmer 2899 1.1 mbalmer 2900 1.7 mbalmer <p> 2901 1.7 mbalmer The Lua library is fully reentrant: 2902 1.7 mbalmer it has no global variables. 2903 1.7 mbalmer It keeps all information it needs in a dynamic structure, 2904 1.7 mbalmer called the <em>Lua state</em>. 2905 1.7 mbalmer 2906 1.7 mbalmer 2907 1.7 mbalmer <p> 2908 1.7 mbalmer Each Lua state has one or more threads, 2909 1.7 mbalmer which correspond to independent, cooperative lines of execution. 2910 1.7 mbalmer The type <a href="#lua_State"><code>lua_State</code></a> (despite its name) refers to a thread. 2911 1.7 mbalmer (Indirectly, through the thread, it also refers to the 2912 1.7 mbalmer Lua state associated to the thread.) 2913 1.7 mbalmer 2914 1.7 mbalmer 2915 1.7 mbalmer <p> 2916 1.7 mbalmer A pointer to a thread must be passed as the first argument to 2917 1.7 mbalmer every function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>, 2918 1.7 mbalmer which creates a Lua state from scratch and returns a pointer 2919 1.7 mbalmer to the <em>main thread</em> in the new state. 2920 1.7 mbalmer 2921 1.7 mbalmer 2922 1.1 mbalmer 2923 1.9 nikita 2924 1.9 nikita 2925 1.2 lneto <h2>4.1 – <a name="4.1">The Stack</a></h2> 2926 1.1 mbalmer 2927 1.9 nikita 2928 1.9 nikita 2929 1.1 mbalmer <p> 2930 1.1 mbalmer Lua uses a <em>virtual stack</em> to pass values to and from C. 2931 1.1 mbalmer Each element in this stack represents a Lua value 2932 1.1 mbalmer (<b>nil</b>, number, string, etc.). 2933 1.7 mbalmer Functions in the API can access this stack through the 2934 1.7 mbalmer Lua state parameter that they receive. 2935 1.1 mbalmer 2936 1.1 mbalmer 2937 1.1 mbalmer <p> 2938 1.1 mbalmer Whenever Lua calls C, the called function gets a new stack, 2939 1.1 mbalmer which is independent of previous stacks and of stacks of 2940 1.1 mbalmer C functions that are still active. 2941 1.1 mbalmer This stack initially contains any arguments to the C function 2942 1.7 mbalmer and it is where the C function can store temporary 2943 1.7 mbalmer Lua values and must push its results 2944 1.1 mbalmer to be returned to the caller (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 2945 1.1 mbalmer 2946 1.1 mbalmer 2947 1.1 mbalmer <p> 2948 1.1 mbalmer For convenience, 2949 1.1 mbalmer most query operations in the API do not follow a strict stack discipline. 2950 1.1 mbalmer Instead, they can refer to any element in the stack 2951 1.1 mbalmer by using an <em>index</em>: 2952 1.9 nikita A positive index represents an absolute stack position, 2953 1.9 nikita starting at 1 as the bottom of the stack; 2954 1.2 lneto a negative index represents an offset relative to the top of the stack. 2955 1.1 mbalmer More specifically, if the stack has <em>n</em> elements, 2956 1.1 mbalmer then index 1 represents the first element 2957 1.1 mbalmer (that is, the element that was pushed onto the stack first) 2958 1.1 mbalmer and 2959 1.1 mbalmer index <em>n</em> represents the last element; 2960 1.1 mbalmer index -1 also represents the last element 2961 1.1 mbalmer (that is, the element at the top) 2962 1.1 mbalmer and index <em>-n</em> represents the first element. 2963 1.1 mbalmer 2964 1.1 mbalmer 2965 1.1 mbalmer 2966 1.1 mbalmer 2967 1.1 mbalmer 2968 1.9 nikita <h3>4.1.1 – <a name="4.1.1">Stack Size</a></h3> 2969 1.1 mbalmer 2970 1.1 mbalmer <p> 2971 1.2 lneto When you interact with the Lua API, 2972 1.1 mbalmer you are responsible for ensuring consistency. 2973 1.1 mbalmer In particular, 2974 1.1 mbalmer <em>you are responsible for controlling stack overflow</em>. 2975 1.9 nikita When you call any API function, 2976 1.9 nikita you must ensure the stack has enough room to accommodate the results. 2977 1.9 nikita 2978 1.9 nikita 2979 1.9 nikita <p> 2980 1.9 nikita There is one exception to the above rule: 2981 1.9 nikita When you call a Lua function 2982 1.9 nikita without a fixed number of results (see <a href="#lua_call"><code>lua_call</code></a>), 2983 1.9 nikita Lua ensures that the stack has enough space for all results. 2984 1.9 nikita However, it does not ensure any extra space. 2985 1.9 nikita So, before pushing anything on the stack after such a call 2986 1.9 nikita you should use <a href="#lua_checkstack"><code>lua_checkstack</code></a>. 2987 1.1 mbalmer 2988 1.1 mbalmer 2989 1.1 mbalmer <p> 2990 1.1 mbalmer Whenever Lua calls C, 2991 1.3 lneto it ensures that the stack has space for 2992 1.9 nikita at least <a name="pdf-LUA_MINSTACK"><code>LUA_MINSTACK</code></a> extra elements; 2993 1.9 nikita that is, you can safely push up to <code>LUA_MINSTACK</code> values into it. 2994 1.1 mbalmer <code>LUA_MINSTACK</code> is defined as 20, 2995 1.1 mbalmer so that usually you do not have to worry about stack space 2996 1.1 mbalmer unless your code has loops pushing elements onto the stack. 2997 1.9 nikita Whenever necessary, 2998 1.9 nikita you can use the function <a href="#lua_checkstack"><code>lua_checkstack</code></a> 2999 1.9 nikita to ensure that the stack has enough space for pushing new elements. 3000 1.2 lneto 3001 1.2 lneto 3002 1.2 lneto 3003 1.2 lneto 3004 1.1 mbalmer 3005 1.9 nikita <h3>4.1.2 – <a name="4.1.2">Valid and Acceptable Indices</a></h3> 3006 1.1 mbalmer 3007 1.2 lneto <p> 3008 1.2 lneto Any function in the API that receives stack indices 3009 1.2 lneto works only with <em>valid indices</em> or <em>acceptable indices</em>. 3010 1.1 mbalmer 3011 1.1 mbalmer 3012 1.2 lneto <p> 3013 1.2 lneto A <em>valid index</em> is an index that refers to a 3014 1.4 mbalmer position that stores a modifiable Lua value. 3015 1.4 mbalmer It comprises stack indices between 1 and the stack top 3016 1.4 mbalmer (<code>1 ≤ abs(index) ≤ top</code>) 3017 1.4 mbalmer 3018 1.4 mbalmer plus <em>pseudo-indices</em>, 3019 1.4 mbalmer which represent some positions that are accessible to C code 3020 1.4 mbalmer but that are not in the stack. 3021 1.9 nikita Pseudo-indices are used to access the registry (see <a href="#4.3">§4.3</a>) 3022 1.9 nikita and the upvalues of a C function (see <a href="#4.2">§4.2</a>). 3023 1.2 lneto 3024 1.2 lneto 3025 1.2 lneto <p> 3026 1.4 mbalmer Functions that do not need a specific mutable position, 3027 1.4 mbalmer but only a value (e.g., query functions), 3028 1.2 lneto can be called with acceptable indices. 3029 1.2 lneto An <em>acceptable index</em> can be any valid index, 3030 1.2 lneto but it also can be any positive index after the stack top 3031 1.2 lneto within the space allocated for the stack, 3032 1.2 lneto that is, indices up to the stack size. 3033 1.2 lneto (Note that 0 is never an acceptable index.) 3034 1.9 nikita Indices to upvalues (see <a href="#4.2">§4.2</a>) greater than the real number 3035 1.9 nikita of upvalues in the current C function are also acceptable (but invalid). 3036 1.2 lneto Except when noted otherwise, 3037 1.2 lneto functions in the API work with acceptable indices. 3038 1.1 mbalmer 3039 1.1 mbalmer 3040 1.1 mbalmer <p> 3041 1.2 lneto Acceptable indices serve to avoid extra tests 3042 1.2 lneto against the stack top when querying the stack. 3043 1.2 lneto For instance, a C function can query its third argument 3044 1.9 nikita without the need to check whether there is a third argument, 3045 1.2 lneto that is, without the need to check whether 3 is a valid index. 3046 1.1 mbalmer 3047 1.1 mbalmer 3048 1.1 mbalmer <p> 3049 1.2 lneto For functions that can be called with acceptable indices, 3050 1.2 lneto any non-valid index is treated as if it 3051 1.2 lneto contains a value of a virtual type <a name="pdf-LUA_TNONE"><code>LUA_TNONE</code></a>, 3052 1.2 lneto which behaves like a nil value. 3053 1.1 mbalmer 3054 1.1 mbalmer 3055 1.1 mbalmer 3056 1.1 mbalmer 3057 1.1 mbalmer 3058 1.9 nikita <h3>4.1.3 – <a name="4.1.3">Pointers to strings</a></h3> 3059 1.9 nikita 3060 1.9 nikita <p> 3061 1.9 nikita Several functions in the API return pointers (<code>const char*</code>) 3062 1.9 nikita to Lua strings in the stack. 3063 1.9 nikita (See <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>, <a href="#lua_pushlstring"><code>lua_pushlstring</code></a>, 3064 1.9 nikita <a href="#lua_pushstring"><code>lua_pushstring</code></a>, and <a href="#lua_tolstring"><code>lua_tolstring</code></a>. 3065 1.9 nikita See also <a href="#luaL_checklstring"><code>luaL_checklstring</code></a>, <a href="#luaL_checkstring"><code>luaL_checkstring</code></a>, 3066 1.9 nikita and <a href="#luaL_tolstring"><code>luaL_tolstring</code></a> in the auxiliary library.) 3067 1.9 nikita 3068 1.9 nikita 3069 1.9 nikita <p> 3070 1.9 nikita In general, 3071 1.9 nikita Lua's garbage collection can free or move internal memory 3072 1.9 nikita and then invalidate pointers to internal strings. 3073 1.9 nikita To allow a safe use of these pointers, 3074 1.9 nikita The API guarantees that any pointer to a string in a stack index 3075 1.9 nikita is valid while the string value at that index is not removed from the stack. 3076 1.9 nikita (It can be moved to another index, though.) 3077 1.9 nikita When the index is a pseudo-index (referring to an upvalue), 3078 1.9 nikita the pointer is valid while the corresponding call is active and 3079 1.9 nikita the corresponding upvalue is not modified. 3080 1.9 nikita 3081 1.9 nikita 3082 1.9 nikita <p> 3083 1.9 nikita Some functions in the debug interface 3084 1.9 nikita also return pointers to strings, 3085 1.9 nikita namely <a href="#lua_getlocal"><code>lua_getlocal</code></a>, <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>, 3086 1.9 nikita <a href="#lua_setlocal"><code>lua_setlocal</code></a>, and <a href="#lua_setupvalue"><code>lua_setupvalue</code></a>. 3087 1.9 nikita For these functions, the pointer is guaranteed to 3088 1.9 nikita be valid while the caller function is active and 3089 1.9 nikita the given closure (if one was given) is in the stack. 3090 1.9 nikita 3091 1.9 nikita 3092 1.9 nikita <p> 3093 1.9 nikita Except for these guarantees, 3094 1.9 nikita the garbage collector is free to invalidate 3095 1.9 nikita any pointer to internal strings. 3096 1.9 nikita 3097 1.9 nikita 3098 1.9 nikita 3099 1.9 nikita 3100 1.9 nikita 3101 1.9 nikita 3102 1.9 nikita 3103 1.9 nikita <h2>4.2 – <a name="4.2">C Closures</a></h2> 3104 1.1 mbalmer 3105 1.1 mbalmer <p> 3106 1.1 mbalmer When a C function is created, 3107 1.1 mbalmer it is possible to associate some values with it, 3108 1.2 lneto thus creating a <em>C closure</em> 3109 1.2 lneto (see <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>); 3110 1.1 mbalmer these values are called <em>upvalues</em> and are 3111 1.2 lneto accessible to the function whenever it is called. 3112 1.1 mbalmer 3113 1.1 mbalmer 3114 1.1 mbalmer <p> 3115 1.1 mbalmer Whenever a C function is called, 3116 1.1 mbalmer its upvalues are located at specific pseudo-indices. 3117 1.1 mbalmer These pseudo-indices are produced by the macro 3118 1.2 lneto <a href="#lua_upvalueindex"><code>lua_upvalueindex</code></a>. 3119 1.4 mbalmer The first upvalue associated with a function is at index 3120 1.1 mbalmer <code>lua_upvalueindex(1)</code>, and so on. 3121 1.1 mbalmer Any access to <code>lua_upvalueindex(<em>n</em>)</code>, 3122 1.1 mbalmer where <em>n</em> is greater than the number of upvalues of the 3123 1.5 lneto current function 3124 1.5 lneto (but not greater than 256, 3125 1.5 lneto which is one plus the maximum number of upvalues in a closure), 3126 1.2 lneto produces an acceptable but invalid index. 3127 1.1 mbalmer 3128 1.1 mbalmer 3129 1.9 nikita <p> 3130 1.9 nikita A C closure can also change the values 3131 1.9 nikita of its corresponding upvalues. 3132 1.9 nikita 3133 1.1 mbalmer 3134 1.1 mbalmer 3135 1.1 mbalmer 3136 1.9 nikita 3137 1.9 nikita <h2>4.3 – <a name="4.3">Registry</a></h2> 3138 1.1 mbalmer 3139 1.1 mbalmer <p> 3140 1.1 mbalmer Lua provides a <em>registry</em>, 3141 1.2 lneto a predefined table that can be used by any C code to 3142 1.2 lneto store whatever Lua values it needs to store. 3143 1.9 nikita The registry table is always accessible at pseudo-index 3144 1.4 mbalmer <a name="pdf-LUA_REGISTRYINDEX"><code>LUA_REGISTRYINDEX</code></a>. 3145 1.1 mbalmer Any C library can store data into this table, 3146 1.2 lneto but it must take care to choose keys 3147 1.2 lneto that are different from those used 3148 1.1 mbalmer by other libraries, to avoid collisions. 3149 1.2 lneto Typically, you should use as key a string containing your library name, 3150 1.2 lneto or a light userdata with the address of a C object in your code, 3151 1.2 lneto or any Lua object created by your code. 3152 1.3 lneto As with variable names, 3153 1.2 lneto string keys starting with an underscore followed by 3154 1.2 lneto uppercase letters are reserved for Lua. 3155 1.1 mbalmer 3156 1.1 mbalmer 3157 1.1 mbalmer <p> 3158 1.3 lneto The integer keys in the registry are used 3159 1.3 lneto by the reference mechanism (see <a href="#luaL_ref"><code>luaL_ref</code></a>) 3160 1.2 lneto and by some predefined values. 3161 1.9 nikita Therefore, integer keys in the registry 3162 1.9 nikita must not be used for other purposes. 3163 1.2 lneto 3164 1.1 mbalmer 3165 1.2 lneto <p> 3166 1.2 lneto When you create a new Lua state, 3167 1.2 lneto its registry comes with some predefined values. 3168 1.2 lneto These predefined values are indexed with integer keys 3169 1.2 lneto defined as constants in <code>lua.h</code>. 3170 1.2 lneto The following constants are defined: 3171 1.2 lneto 3172 1.2 lneto <ul> 3173 1.2 lneto <li><b><a name="pdf-LUA_RIDX_MAINTHREAD"><code>LUA_RIDX_MAINTHREAD</code></a>: </b> At this index the registry has 3174 1.2 lneto the main thread of the state. 3175 1.2 lneto (The main thread is the one created together with the state.) 3176 1.2 lneto </li> 3177 1.1 mbalmer 3178 1.2 lneto <li><b><a name="pdf-LUA_RIDX_GLOBALS"><code>LUA_RIDX_GLOBALS</code></a>: </b> At this index the registry has 3179 1.2 lneto the global environment. 3180 1.2 lneto </li> 3181 1.2 lneto </ul> 3182 1.1 mbalmer 3183 1.1 mbalmer 3184 1.1 mbalmer 3185 1.2 lneto 3186 1.9 nikita <h2>4.4 – <a name="4.4">Error Handling in C</a></h2> 3187 1.9 nikita 3188 1.9 nikita 3189 1.1 mbalmer 3190 1.1 mbalmer <p> 3191 1.1 mbalmer Internally, Lua uses the C <code>longjmp</code> facility to handle errors. 3192 1.3 lneto (Lua will use exceptions if you compile it as C++; 3193 1.3 lneto search for <code>LUAI_THROW</code> in the source code for details.) 3194 1.9 nikita When Lua faces any error, 3195 1.9 nikita such as a memory allocation error or a type error, 3196 1.1 mbalmer it <em>raises</em> an error; 3197 1.1 mbalmer that is, it does a long jump. 3198 1.1 mbalmer A <em>protected environment</em> uses <code>setjmp</code> 3199 1.2 lneto to set a recovery point; 3200 1.2 lneto any error jumps to the most recent active recovery point. 3201 1.2 lneto 3202 1.2 lneto 3203 1.2 lneto <p> 3204 1.9 nikita Inside a C function you can raise an error explicitly 3205 1.9 nikita by calling <a href="#lua_error"><code>lua_error</code></a>. 3206 1.7 mbalmer 3207 1.7 mbalmer 3208 1.7 mbalmer <p> 3209 1.7 mbalmer Most functions in the API can raise an error, 3210 1.7 mbalmer for instance due to a memory allocation error. 3211 1.7 mbalmer The documentation for each function indicates whether 3212 1.7 mbalmer it can raise errors. 3213 1.7 mbalmer 3214 1.7 mbalmer 3215 1.7 mbalmer <p> 3216 1.2 lneto If an error happens outside any protected environment, 3217 1.2 lneto Lua calls a <em>panic function</em> (see <a href="#lua_atpanic"><code>lua_atpanic</code></a>) 3218 1.2 lneto and then calls <code>abort</code>, 3219 1.2 lneto thus exiting the host application. 3220 1.2 lneto Your panic function can avoid this exit by 3221 1.2 lneto never returning 3222 1.2 lneto (e.g., doing a long jump to your own recovery point outside Lua). 3223 1.2 lneto 3224 1.2 lneto 3225 1.2 lneto <p> 3226 1.7 mbalmer The panic function, 3227 1.7 mbalmer as its name implies, 3228 1.7 mbalmer is a mechanism of last resort. 3229 1.7 mbalmer Programs should avoid it. 3230 1.7 mbalmer As a general rule, 3231 1.7 mbalmer when a C function is called by Lua with a Lua state, 3232 1.7 mbalmer it can do whatever it wants on that Lua state, 3233 1.7 mbalmer as it should be already protected. 3234 1.7 mbalmer However, 3235 1.7 mbalmer when C code operates on other Lua states 3236 1.9 nikita (e.g., a Lua-state argument to the function, 3237 1.7 mbalmer a Lua state stored in the registry, or 3238 1.7 mbalmer the result of <a href="#lua_newthread"><code>lua_newthread</code></a>), 3239 1.7 mbalmer it should use them only in API calls that cannot raise errors. 3240 1.7 mbalmer 3241 1.7 mbalmer 3242 1.7 mbalmer <p> 3243 1.2 lneto The panic function runs as if it were a message handler (see <a href="#2.3">§2.3</a>); 3244 1.9 nikita in particular, the error object is on the top of the stack. 3245 1.3 lneto However, there is no guarantee about stack space. 3246 1.2 lneto To push anything on the stack, 3247 1.9 nikita the panic function must first check the available space (see <a href="#4.1.1">§4.1.1</a>). 3248 1.9 nikita 3249 1.9 nikita 3250 1.9 nikita 3251 1.9 nikita 3252 1.9 nikita 3253 1.9 nikita <h3>4.4.1 – <a name="4.4.1">Status Codes</a></h3> 3254 1.9 nikita 3255 1.9 nikita <p> 3256 1.9 nikita Several functions that report errors in the API use the following 3257 1.9 nikita status codes to indicate different kinds of errors or other conditions: 3258 1.9 nikita 3259 1.9 nikita <ul> 3260 1.9 nikita 3261 1.9 nikita <li><b><a name="pdf-LUA_OK"><code>LUA_OK</code></a> (0): </b> no errors.</li> 3262 1.9 nikita 3263 1.9 nikita <li><b><a name="pdf-LUA_ERRRUN"><code>LUA_ERRRUN</code></a>: </b> a runtime error.</li> 3264 1.9 nikita 3265 1.9 nikita <li><b><a name="pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>: </b> 3266 1.9 nikita memory allocation error. 3267 1.9 nikita For such errors, Lua does not call the message handler. 3268 1.9 nikita </li> 3269 1.9 nikita 3270 1.9 nikita <li><b><a name="pdf-LUA_ERRERR"><code>LUA_ERRERR</code></a>: </b> error while running the message handler.</li> 3271 1.9 nikita 3272 1.9 nikita <li><b><a name="pdf-LUA_ERRSYNTAX"><code>LUA_ERRSYNTAX</code></a>: </b> syntax error during precompilation.</li> 3273 1.9 nikita 3274 1.9 nikita <li><b><a name="pdf-LUA_YIELD"><code>LUA_YIELD</code></a>: </b> the thread (coroutine) yields.</li> 3275 1.9 nikita 3276 1.9 nikita <li><b><a name="pdf-LUA_ERRFILE"><code>LUA_ERRFILE</code></a>: </b> a file-related error; 3277 1.9 nikita e.g., it cannot open or read the file.</li> 3278 1.9 nikita 3279 1.9 nikita </ul><p> 3280 1.9 nikita These constants are defined in the header file <code>lua.h</code>. 3281 1.9 nikita 3282 1.9 nikita 3283 1.1 mbalmer 3284 1.1 mbalmer 3285 1.2 lneto 3286 1.2 lneto 3287 1.2 lneto 3288 1.9 nikita <h2>4.5 – <a name="4.5">Handling Yields in C</a></h2> 3289 1.2 lneto 3290 1.2 lneto <p> 3291 1.2 lneto Internally, Lua uses the C <code>longjmp</code> facility to yield a coroutine. 3292 1.7 mbalmer Therefore, if a C function <code>foo</code> calls an API function 3293 1.2 lneto and this API function yields 3294 1.2 lneto (directly or indirectly by calling another function that yields), 3295 1.2 lneto Lua cannot return to <code>foo</code> any more, 3296 1.9 nikita because the <code>longjmp</code> removes its frame from the C stack. 3297 1.2 lneto 3298 1.2 lneto 3299 1.2 lneto <p> 3300 1.2 lneto To avoid this kind of problem, 3301 1.2 lneto Lua raises an error whenever it tries to yield across an API call, 3302 1.2 lneto except for three functions: 3303 1.2 lneto <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>. 3304 1.2 lneto All those functions receive a <em>continuation function</em> 3305 1.3 lneto (as a parameter named <code>k</code>) to continue execution after a yield. 3306 1.2 lneto 3307 1.2 lneto 3308 1.2 lneto <p> 3309 1.2 lneto We need to set some terminology to explain continuations. 3310 1.7 mbalmer We have a C function called from Lua which we will call 3311 1.2 lneto the <em>original function</em>. 3312 1.2 lneto This original function then calls one of those three functions in the C API, 3313 1.2 lneto which we will call the <em>callee function</em>, 3314 1.2 lneto that then yields the current thread. 3315 1.9 nikita This can happen when the callee function is <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 3316 1.2 lneto or 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> 3317 1.9 nikita and the function called by them yields. 3318 1.2 lneto 3319 1.2 lneto 3320 1.2 lneto <p> 3321 1.2 lneto Suppose the running thread yields while executing the callee function. 3322 1.2 lneto After the thread resumes, 3323 1.2 lneto it eventually will finish running the callee function. 3324 1.2 lneto However, 3325 1.2 lneto the callee function cannot return to the original function, 3326 1.9 nikita because its frame in the C stack was destroyed by the yield. 3327 1.2 lneto Instead, Lua calls a <em>continuation function</em>, 3328 1.2 lneto which was given as an argument to the callee function. 3329 1.2 lneto As the name implies, 3330 1.2 lneto the continuation function should continue the task 3331 1.2 lneto of the original function. 3332 1.2 lneto 3333 1.2 lneto 3334 1.2 lneto <p> 3335 1.2 lneto As an illustration, consider the following function: 3336 1.2 lneto 3337 1.2 lneto <pre> 3338 1.2 lneto int original_function (lua_State *L) { 3339 1.2 lneto ... /* code 1 */ 3340 1.2 lneto status = lua_pcall(L, n, m, h); /* calls Lua */ 3341 1.2 lneto ... /* code 2 */ 3342 1.2 lneto } 3343 1.2 lneto </pre><p> 3344 1.2 lneto Now we want to allow 3345 1.3 lneto the Lua code being run by <a href="#lua_pcall"><code>lua_pcall</code></a> to yield. 3346 1.2 lneto First, we can rewrite our function like here: 3347 1.2 lneto 3348 1.2 lneto <pre> 3349 1.3 lneto int k (lua_State *L, int status, lua_KContext ctx) { 3350 1.2 lneto ... /* code 2 */ 3351 1.2 lneto } 3352 1.2 lneto 3353 1.2 lneto int original_function (lua_State *L) { 3354 1.2 lneto ... /* code 1 */ 3355 1.2 lneto return k(L, lua_pcall(L, n, m, h), ctx); 3356 1.2 lneto } 3357 1.2 lneto </pre><p> 3358 1.2 lneto In the above code, 3359 1.2 lneto the new function <code>k</code> is a 3360 1.2 lneto <em>continuation function</em> (with type <a href="#lua_KFunction"><code>lua_KFunction</code></a>), 3361 1.2 lneto which should do all the work that the original function 3362 1.2 lneto was doing after calling <a href="#lua_pcall"><code>lua_pcall</code></a>. 3363 1.2 lneto Now, we must inform Lua that it must call <code>k</code> if the Lua code 3364 1.3 lneto being executed by <a href="#lua_pcall"><code>lua_pcall</code></a> gets interrupted in some way 3365 1.2 lneto (errors or yielding), 3366 1.2 lneto so we rewrite the code as here, 3367 1.2 lneto replacing <a href="#lua_pcall"><code>lua_pcall</code></a> by <a href="#lua_pcallk"><code>lua_pcallk</code></a>: 3368 1.2 lneto 3369 1.2 lneto <pre> 3370 1.2 lneto int original_function (lua_State *L) { 3371 1.2 lneto ... /* code 1 */ 3372 1.2 lneto return k(L, lua_pcallk(L, n, m, h, ctx2, k), ctx1); 3373 1.2 lneto } 3374 1.3 lneto </pre><p> 3375 1.3 lneto Note the external, explicit call to the continuation: 3376 1.3 lneto Lua will call the continuation only if needed, that is, 3377 1.3 lneto in case of errors or resuming after a yield. 3378 1.3 lneto If the called function returns normally without ever yielding, 3379 1.3 lneto <a href="#lua_pcallk"><code>lua_pcallk</code></a> (and <a href="#lua_callk"><code>lua_callk</code></a>) will also return normally. 3380 1.3 lneto (Of course, instead of calling the continuation in that case, 3381 1.3 lneto you can do the equivalent work directly inside the original function.) 3382 1.3 lneto 3383 1.2 lneto 3384 1.2 lneto <p> 3385 1.2 lneto Besides the Lua state, 3386 1.2 lneto the continuation function has two other parameters: 3387 1.9 nikita the final status of the call and the context value (<code>ctx</code>) that 3388 1.2 lneto was passed originally to <a href="#lua_pcallk"><code>lua_pcallk</code></a>. 3389 1.9 nikita Lua does not use this context value; 3390 1.2 lneto it only passes this value from the original function to the 3391 1.9 nikita continuation function. 3392 1.2 lneto For <a href="#lua_pcallk"><code>lua_pcallk</code></a>, 3393 1.2 lneto the status is the same value that would be returned by <a href="#lua_pcallk"><code>lua_pcallk</code></a>, 3394 1.3 lneto except that it is <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when being executed after a yield 3395 1.2 lneto (instead of <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>). 3396 1.2 lneto For <a href="#lua_yieldk"><code>lua_yieldk</code></a> and <a href="#lua_callk"><code>lua_callk</code></a>, 3397 1.2 lneto the status is always <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when Lua calls the continuation. 3398 1.2 lneto (For these two functions, 3399 1.2 lneto Lua will not call the continuation in case of errors, 3400 1.2 lneto because they do not handle errors.) 3401 1.3 lneto Similarly, when using <a href="#lua_callk"><code>lua_callk</code></a>, 3402 1.3 lneto you should call the continuation function 3403 1.3 lneto with <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> as the status. 3404 1.3 lneto (For <a href="#lua_yieldk"><code>lua_yieldk</code></a>, there is not much point in calling 3405 1.3 lneto directly the continuation function, 3406 1.3 lneto because <a href="#lua_yieldk"><code>lua_yieldk</code></a> usually does not return.) 3407 1.1 mbalmer 3408 1.1 mbalmer 3409 1.1 mbalmer <p> 3410 1.2 lneto Lua treats the continuation function as if it were the original function. 3411 1.2 lneto The continuation function receives the same Lua stack 3412 1.2 lneto from the original function, 3413 1.2 lneto in the same state it would be if the callee function had returned. 3414 1.2 lneto (For instance, 3415 1.2 lneto after a <a href="#lua_callk"><code>lua_callk</code></a> the function and its arguments are 3416 1.2 lneto removed from the stack and replaced by the results from the call.) 3417 1.2 lneto It also has the same upvalues. 3418 1.2 lneto Whatever it returns is handled by Lua as if it were the return 3419 1.2 lneto of the original function. 3420 1.1 mbalmer 3421 1.1 mbalmer 3422 1.1 mbalmer 3423 1.1 mbalmer 3424 1.1 mbalmer 3425 1.9 nikita <h2>4.6 – <a name="4.6">Functions and Types</a></h2> 3426 1.1 mbalmer 3427 1.1 mbalmer <p> 3428 1.1 mbalmer Here we list all functions and types from the C API in 3429 1.1 mbalmer alphabetical order. 3430 1.1 mbalmer Each function has an indicator like this: 3431 1.1 mbalmer <span class="apii">[-o, +p, <em>x</em>]</span> 3432 1.1 mbalmer 3433 1.1 mbalmer 3434 1.1 mbalmer <p> 3435 1.1 mbalmer The first field, <code>o</code>, 3436 1.1 mbalmer is how many elements the function pops from the stack. 3437 1.1 mbalmer The second field, <code>p</code>, 3438 1.1 mbalmer is how many elements the function pushes onto the stack. 3439 1.1 mbalmer (Any function always pushes its results after popping its arguments.) 3440 1.1 mbalmer A field in the form <code>x|y</code> means the function can push (or pop) 3441 1.1 mbalmer <code>x</code> or <code>y</code> elements, 3442 1.1 mbalmer depending on the situation; 3443 1.1 mbalmer an interrogation mark '<code>?</code>' means that 3444 1.1 mbalmer we cannot know how many elements the function pops/pushes 3445 1.9 nikita by looking only at its arguments. 3446 1.9 nikita (For instance, they may depend on what is in the stack.) 3447 1.1 mbalmer The third field, <code>x</code>, 3448 1.2 lneto tells whether the function may raise errors: 3449 1.2 lneto '<code>-</code>' means the function never raises any error; 3450 1.9 nikita '<code>m</code>' means the function may raise only out-of-memory errors; 3451 1.9 nikita '<code>v</code>' means the function may raise the errors explained in the text; 3452 1.9 nikita '<code>e</code>' means the function can run arbitrary Lua code, 3453 1.9 nikita either directly or through metamethods, 3454 1.9 nikita and therefore may raise any errors. 3455 1.2 lneto 3456 1.2 lneto 3457 1.2 lneto 3458 1.2 lneto <hr><h3><a name="lua_absindex"><code>lua_absindex</code></a></h3><p> 3459 1.2 lneto <span class="apii">[-0, +0, –]</span> 3460 1.2 lneto <pre>int lua_absindex (lua_State *L, int idx);</pre> 3461 1.2 lneto 3462 1.2 lneto <p> 3463 1.4 mbalmer Converts the acceptable index <code>idx</code> 3464 1.4 mbalmer into an equivalent absolute index 3465 1.9 nikita (that is, one that does not depend on the stack size). 3466 1.2 lneto 3467 1.2 lneto 3468 1.1 mbalmer 3469 1.1 mbalmer 3470 1.1 mbalmer 3471 1.1 mbalmer <hr><h3><a name="lua_Alloc"><code>lua_Alloc</code></a></h3> 3472 1.1 mbalmer <pre>typedef void * (*lua_Alloc) (void *ud, 3473 1.1 mbalmer void *ptr, 3474 1.1 mbalmer size_t osize, 3475 1.1 mbalmer size_t nsize);</pre> 3476 1.1 mbalmer 3477 1.1 mbalmer <p> 3478 1.1 mbalmer The type of the memory-allocation function used by Lua states. 3479 1.1 mbalmer The allocator function must provide a 3480 1.1 mbalmer functionality similar to <code>realloc</code>, 3481 1.1 mbalmer but not exactly the same. 3482 1.1 mbalmer Its arguments are 3483 1.1 mbalmer <code>ud</code>, an opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>; 3484 1.1 mbalmer <code>ptr</code>, a pointer to the block being allocated/reallocated/freed; 3485 1.2 lneto <code>osize</code>, the original size of the block or some code about what 3486 1.2 lneto is being allocated; 3487 1.3 lneto and <code>nsize</code>, the new size of the block. 3488 1.2 lneto 3489 1.2 lneto 3490 1.2 lneto <p> 3491 1.2 lneto When <code>ptr</code> is not <code>NULL</code>, 3492 1.2 lneto <code>osize</code> is the size of the block pointed by <code>ptr</code>, 3493 1.2 lneto that is, the size given when it was allocated or reallocated. 3494 1.2 lneto 3495 1.2 lneto 3496 1.2 lneto <p> 3497 1.2 lneto When <code>ptr</code> is <code>NULL</code>, 3498 1.2 lneto <code>osize</code> encodes the kind of object that Lua is allocating. 3499 1.2 lneto <code>osize</code> is any of 3500 1.2 lneto <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>, 3501 1.2 lneto <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) 3502 1.2 lneto Lua is creating a new object of that type. 3503 1.2 lneto When <code>osize</code> is some other value, 3504 1.2 lneto Lua is allocating memory for something else. 3505 1.2 lneto 3506 1.2 lneto 3507 1.2 lneto <p> 3508 1.2 lneto Lua assumes the following behavior from the allocator function: 3509 1.2 lneto 3510 1.2 lneto 3511 1.2 lneto <p> 3512 1.2 lneto When <code>nsize</code> is zero, 3513 1.2 lneto the allocator must behave like <code>free</code> 3514 1.9 nikita and then return <code>NULL</code>. 3515 1.2 lneto 3516 1.2 lneto 3517 1.2 lneto <p> 3518 1.2 lneto When <code>nsize</code> is not zero, 3519 1.2 lneto the allocator must behave like <code>realloc</code>. 3520 1.9 nikita In particular, the allocator returns <code>NULL</code> 3521 1.2 lneto if and only if it cannot fulfill the request. 3522 1.1 mbalmer 3523 1.1 mbalmer 3524 1.1 mbalmer <p> 3525 1.1 mbalmer Here is a simple implementation for the allocator function. 3526 1.1 mbalmer It is used in the auxiliary library by <a href="#luaL_newstate"><code>luaL_newstate</code></a>. 3527 1.1 mbalmer 3528 1.1 mbalmer <pre> 3529 1.1 mbalmer static void *l_alloc (void *ud, void *ptr, size_t osize, 3530 1.1 mbalmer size_t nsize) { 3531 1.1 mbalmer (void)ud; (void)osize; /* not used */ 3532 1.1 mbalmer if (nsize == 0) { 3533 1.1 mbalmer free(ptr); 3534 1.1 mbalmer return NULL; 3535 1.1 mbalmer } 3536 1.1 mbalmer else 3537 1.1 mbalmer return realloc(ptr, nsize); 3538 1.1 mbalmer } 3539 1.1 mbalmer </pre><p> 3540 1.2 lneto Note that Standard C ensures 3541 1.1 mbalmer that <code>free(NULL)</code> has no effect and that 3542 1.3 lneto <code>realloc(NULL,size)</code> is equivalent to <code>malloc(size)</code>. 3543 1.1 mbalmer 3544 1.1 mbalmer 3545 1.1 mbalmer 3546 1.1 mbalmer 3547 1.1 mbalmer 3548 1.2 lneto <hr><h3><a name="lua_arith"><code>lua_arith</code></a></h3><p> 3549 1.2 lneto <span class="apii">[-(2|1), +1, <em>e</em>]</span> 3550 1.2 lneto <pre>void lua_arith (lua_State *L, int op);</pre> 3551 1.1 mbalmer 3552 1.1 mbalmer <p> 3553 1.2 lneto Performs an arithmetic or bitwise operation over the two values 3554 1.2 lneto (or one, in the case of negations) 3555 1.2 lneto at the top of the stack, 3556 1.9 nikita with the value on the top being the second operand, 3557 1.2 lneto pops these values, and pushes the result of the operation. 3558 1.2 lneto The function follows the semantics of the corresponding Lua operator 3559 1.2 lneto (that is, it may call metamethods). 3560 1.1 mbalmer 3561 1.1 mbalmer 3562 1.1 mbalmer <p> 3563 1.2 lneto The value of <code>op</code> must be one of the following constants: 3564 1.2 lneto 3565 1.2 lneto <ul> 3566 1.2 lneto 3567 1.2 lneto <li><b><a name="pdf-LUA_OPADD"><code>LUA_OPADD</code></a>: </b> performs addition (<code>+</code>)</li> 3568 1.2 lneto <li><b><a name="pdf-LUA_OPSUB"><code>LUA_OPSUB</code></a>: </b> performs subtraction (<code>-</code>)</li> 3569 1.2 lneto <li><b><a name="pdf-LUA_OPMUL"><code>LUA_OPMUL</code></a>: </b> performs multiplication (<code>*</code>)</li> 3570 1.2 lneto <li><b><a name="pdf-LUA_OPDIV"><code>LUA_OPDIV</code></a>: </b> performs float division (<code>/</code>)</li> 3571 1.3 lneto <li><b><a name="pdf-LUA_OPIDIV"><code>LUA_OPIDIV</code></a>: </b> performs floor division (<code>//</code>)</li> 3572 1.2 lneto <li><b><a name="pdf-LUA_OPMOD"><code>LUA_OPMOD</code></a>: </b> performs modulo (<code>%</code>)</li> 3573 1.2 lneto <li><b><a name="pdf-LUA_OPPOW"><code>LUA_OPPOW</code></a>: </b> performs exponentiation (<code>^</code>)</li> 3574 1.2 lneto <li><b><a name="pdf-LUA_OPUNM"><code>LUA_OPUNM</code></a>: </b> performs mathematical negation (unary <code>-</code>)</li> 3575 1.6 salazar <li><b><a name="pdf-LUA_OPBNOT"><code>LUA_OPBNOT</code></a>: </b> performs bitwise NOT (<code>~</code>)</li> 3576 1.6 salazar <li><b><a name="pdf-LUA_OPBAND"><code>LUA_OPBAND</code></a>: </b> performs bitwise AND (<code>&</code>)</li> 3577 1.6 salazar <li><b><a name="pdf-LUA_OPBOR"><code>LUA_OPBOR</code></a>: </b> performs bitwise OR (<code>|</code>)</li> 3578 1.6 salazar <li><b><a name="pdf-LUA_OPBXOR"><code>LUA_OPBXOR</code></a>: </b> performs bitwise exclusive OR (<code>~</code>)</li> 3579 1.2 lneto <li><b><a name="pdf-LUA_OPSHL"><code>LUA_OPSHL</code></a>: </b> performs left shift (<code><<</code>)</li> 3580 1.2 lneto <li><b><a name="pdf-LUA_OPSHR"><code>LUA_OPSHR</code></a>: </b> performs right shift (<code>>></code>)</li> 3581 1.2 lneto 3582 1.2 lneto </ul> 3583 1.2 lneto 3584 1.2 lneto 3585 1.2 lneto 3586 1.1 mbalmer 3587 1.2 lneto <hr><h3><a name="lua_atpanic"><code>lua_atpanic</code></a></h3><p> 3588 1.2 lneto <span class="apii">[-0, +0, –]</span> 3589 1.2 lneto <pre>lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);</pre> 3590 1.1 mbalmer 3591 1.1 mbalmer <p> 3592 1.9 nikita Sets a new panic function and returns the old one (see <a href="#4.4">§4.4</a>). 3593 1.1 mbalmer 3594 1.1 mbalmer 3595 1.1 mbalmer 3596 1.1 mbalmer 3597 1.1 mbalmer 3598 1.1 mbalmer <hr><h3><a name="lua_call"><code>lua_call</code></a></h3><p> 3599 1.2 lneto <span class="apii">[-(nargs+1), +nresults, <em>e</em>]</span> 3600 1.1 mbalmer <pre>void lua_call (lua_State *L, int nargs, int nresults);</pre> 3601 1.1 mbalmer 3602 1.1 mbalmer <p> 3603 1.1 mbalmer Calls a function. 3604 1.9 nikita Like regular Lua calls, 3605 1.9 nikita <code>lua_call</code> respects the <code>__call</code> metamethod. 3606 1.9 nikita So, here the word "function" 3607 1.9 nikita means any callable value. 3608 1.1 mbalmer 3609 1.1 mbalmer 3610 1.1 mbalmer <p> 3611 1.9 nikita To do a call you must use the following protocol: 3612 1.1 mbalmer first, the function to be called is pushed onto the stack; 3613 1.9 nikita then, the arguments to the call are pushed 3614 1.1 mbalmer in direct order; 3615 1.1 mbalmer that is, the first argument is pushed first. 3616 1.1 mbalmer Finally you call <a href="#lua_call"><code>lua_call</code></a>; 3617 1.1 mbalmer <code>nargs</code> is the number of arguments that you pushed onto the stack. 3618 1.9 nikita When the function returns, 3619 1.9 nikita all arguments and the function value are popped 3620 1.9 nikita and the call results are pushed onto the stack. 3621 1.1 mbalmer The number of results is adjusted to <code>nresults</code>, 3622 1.1 mbalmer unless <code>nresults</code> is <a name="pdf-LUA_MULTRET"><code>LUA_MULTRET</code></a>. 3623 1.7 mbalmer In this case, all results from the function are pushed; 3624 1.5 lneto Lua takes care that the returned values fit into the stack space, 3625 1.5 lneto but it does not ensure any extra space in the stack. 3626 1.1 mbalmer The function results are pushed onto the stack in direct order 3627 1.1 mbalmer (the first result is pushed first), 3628 1.1 mbalmer so that after the call the last result is on the top of the stack. 3629 1.1 mbalmer 3630 1.1 mbalmer 3631 1.1 mbalmer <p> 3632 1.9 nikita Any error while calling and running the function is propagated upwards 3633 1.1 mbalmer (with a <code>longjmp</code>). 3634 1.1 mbalmer 3635 1.1 mbalmer 3636 1.1 mbalmer <p> 3637 1.1 mbalmer The following example shows how the host program can do the 3638 1.1 mbalmer equivalent to this Lua code: 3639 1.1 mbalmer 3640 1.1 mbalmer <pre> 3641 1.1 mbalmer a = f("how", t.x, 14) 3642 1.1 mbalmer </pre><p> 3643 1.1 mbalmer Here it is in C: 3644 1.1 mbalmer 3645 1.1 mbalmer <pre> 3646 1.2 lneto lua_getglobal(L, "f"); /* function to be called */ 3647 1.3 lneto lua_pushliteral(L, "how"); /* 1st argument */ 3648 1.2 lneto lua_getglobal(L, "t"); /* table to be indexed */ 3649 1.1 mbalmer lua_getfield(L, -1, "x"); /* push result of t.x (2nd arg) */ 3650 1.1 mbalmer lua_remove(L, -2); /* remove 't' from the stack */ 3651 1.1 mbalmer lua_pushinteger(L, 14); /* 3rd argument */ 3652 1.1 mbalmer lua_call(L, 3, 1); /* call 'f' with 3 arguments and 1 result */ 3653 1.2 lneto lua_setglobal(L, "a"); /* set global 'a' */ 3654 1.1 mbalmer </pre><p> 3655 1.3 lneto Note that the code above is <em>balanced</em>: 3656 1.1 mbalmer at its end, the stack is back to its original configuration. 3657 1.1 mbalmer This is considered good programming practice. 3658 1.1 mbalmer 3659 1.1 mbalmer 3660 1.1 mbalmer 3661 1.1 mbalmer 3662 1.1 mbalmer 3663 1.2 lneto <hr><h3><a name="lua_callk"><code>lua_callk</code></a></h3><p> 3664 1.2 lneto <span class="apii">[-(nargs + 1), +nresults, <em>e</em>]</span> 3665 1.3 lneto <pre>void lua_callk (lua_State *L, 3666 1.3 lneto int nargs, 3667 1.3 lneto int nresults, 3668 1.3 lneto lua_KContext ctx, 3669 1.2 lneto lua_KFunction k);</pre> 3670 1.2 lneto 3671 1.2 lneto <p> 3672 1.2 lneto This function behaves exactly like <a href="#lua_call"><code>lua_call</code></a>, 3673 1.9 nikita but allows the called function to yield (see <a href="#4.5">§4.5</a>). 3674 1.2 lneto 3675 1.2 lneto 3676 1.2 lneto 3677 1.2 lneto 3678 1.2 lneto 3679 1.1 mbalmer <hr><h3><a name="lua_CFunction"><code>lua_CFunction</code></a></h3> 3680 1.1 mbalmer <pre>typedef int (*lua_CFunction) (lua_State *L);</pre> 3681 1.1 mbalmer 3682 1.1 mbalmer <p> 3683 1.1 mbalmer Type for C functions. 3684 1.1 mbalmer 3685 1.1 mbalmer 3686 1.1 mbalmer <p> 3687 1.1 mbalmer In order to communicate properly with Lua, 3688 1.1 mbalmer a C function must use the following protocol, 3689 1.1 mbalmer which defines the way parameters and results are passed: 3690 1.1 mbalmer a C function receives its arguments from Lua in its stack 3691 1.1 mbalmer in direct order (the first argument is pushed first). 3692 1.1 mbalmer So, when the function starts, 3693 1.1 mbalmer <code>lua_gettop(L)</code> returns the number of arguments received by the function. 3694 1.1 mbalmer The first argument (if any) is at index 1 3695 1.1 mbalmer and its last argument is at index <code>lua_gettop(L)</code>. 3696 1.1 mbalmer To return values to Lua, a C function just pushes them onto the stack, 3697 1.1 mbalmer in direct order (the first result is pushed first), 3698 1.9 nikita and returns in C the number of results. 3699 1.1 mbalmer Any other value in the stack below the results will be properly 3700 1.1 mbalmer discarded by Lua. 3701 1.1 mbalmer Like a Lua function, a C function called by Lua can also return 3702 1.1 mbalmer many results. 3703 1.1 mbalmer 3704 1.1 mbalmer 3705 1.1 mbalmer <p> 3706 1.1 mbalmer As an example, the following function receives a variable number 3707 1.4 mbalmer of numeric arguments and returns their average and their sum: 3708 1.1 mbalmer 3709 1.1 mbalmer <pre> 3710 1.1 mbalmer static int foo (lua_State *L) { 3711 1.1 mbalmer int n = lua_gettop(L); /* number of arguments */ 3712 1.3 lneto lua_Number sum = 0.0; 3713 1.1 mbalmer int i; 3714 1.1 mbalmer for (i = 1; i <= n; i++) { 3715 1.1 mbalmer if (!lua_isnumber(L, i)) { 3716 1.3 lneto lua_pushliteral(L, "incorrect argument"); 3717 1.1 mbalmer lua_error(L); 3718 1.1 mbalmer } 3719 1.1 mbalmer sum += lua_tonumber(L, i); 3720 1.1 mbalmer } 3721 1.1 mbalmer lua_pushnumber(L, sum/n); /* first result */ 3722 1.1 mbalmer lua_pushnumber(L, sum); /* second result */ 3723 1.1 mbalmer return 2; /* number of results */ 3724 1.1 mbalmer } 3725 1.1 mbalmer </pre> 3726 1.1 mbalmer 3727 1.1 mbalmer 3728 1.1 mbalmer 3729 1.1 mbalmer 3730 1.1 mbalmer <hr><h3><a name="lua_checkstack"><code>lua_checkstack</code></a></h3><p> 3731 1.2 lneto <span class="apii">[-0, +0, –]</span> 3732 1.3 lneto <pre>int lua_checkstack (lua_State *L, int n);</pre> 3733 1.1 mbalmer 3734 1.1 mbalmer <p> 3735 1.9 nikita Ensures that the stack has space for at least <code>n</code> extra elements, 3736 1.9 nikita that is, that you can safely push up to <code>n</code> values into it. 3737 1.2 lneto It returns false if it cannot fulfill the request, 3738 1.3 lneto either because it would cause the stack 3739 1.9 nikita to be greater than a fixed maximum size 3740 1.3 lneto (typically at least several thousand elements) or 3741 1.3 lneto because it cannot allocate memory for the extra space. 3742 1.1 mbalmer This function never shrinks the stack; 3743 1.9 nikita if the stack already has space for the extra elements, 3744 1.1 mbalmer it is left unchanged. 3745 1.1 mbalmer 3746 1.1 mbalmer 3747 1.1 mbalmer 3748 1.1 mbalmer 3749 1.1 mbalmer 3750 1.1 mbalmer <hr><h3><a name="lua_close"><code>lua_close</code></a></h3><p> 3751 1.2 lneto <span class="apii">[-0, +0, –]</span> 3752 1.1 mbalmer <pre>void lua_close (lua_State *L);</pre> 3753 1.1 mbalmer 3754 1.1 mbalmer <p> 3755 1.9 nikita Close all active to-be-closed variables in the main thread, 3756 1.9 nikita release all objects in the given Lua state 3757 1.9 nikita (calling the corresponding garbage-collection metamethods, if any), 3758 1.1 mbalmer and frees all dynamic memory used by this state. 3759 1.9 nikita 3760 1.9 nikita 3761 1.9 nikita <p> 3762 1.9 nikita On several platforms, you may not need to call this function, 3763 1.1 mbalmer because all resources are naturally released when the host program ends. 3764 1.2 lneto On the other hand, long-running programs that create multiple states, 3765 1.2 lneto such as daemons or web servers, 3766 1.3 lneto will probably need to close states as soon as they are not needed. 3767 1.2 lneto 3768 1.1 mbalmer 3769 1.1 mbalmer 3770 1.1 mbalmer 3771 1.1 mbalmer 3772 1.9 nikita <hr><h3><a name="lua_closeslot"><code>lua_closeslot</code></a></h3><p> 3773 1.9 nikita <span class="apii">[-0, +0, <em>e</em>]</span> 3774 1.9 nikita <pre>void lua_closeslot (lua_State *L, int index);</pre> 3775 1.9 nikita 3776 1.9 nikita <p> 3777 1.9 nikita Close the to-be-closed slot at the given index and set its value to <b>nil</b>. 3778 1.9 nikita The index must be the last index previously marked to be closed 3779 1.9 nikita (see <a href="#lua_toclose"><code>lua_toclose</code></a>) that is still active (that is, not closed yet). 3780 1.9 nikita 3781 1.9 nikita 3782 1.9 nikita <p> 3783 1.9 nikita A <code>__close</code> metamethod cannot yield 3784 1.9 nikita when called through this function. 3785 1.9 nikita 3786 1.9 nikita 3787 1.9 nikita <p> 3788 1.9 nikita (Exceptionally, this function was introduced in release 5.4.3. 3789 1.9 nikita It is not present in previous 5.4 releases.) 3790 1.9 nikita 3791 1.9 nikita 3792 1.9 nikita 3793 1.9 nikita 3794 1.9 nikita 3795 1.2 lneto <hr><h3><a name="lua_compare"><code>lua_compare</code></a></h3><p> 3796 1.2 lneto <span class="apii">[-0, +0, <em>e</em>]</span> 3797 1.2 lneto <pre>int lua_compare (lua_State *L, int index1, int index2, int op);</pre> 3798 1.2 lneto 3799 1.2 lneto <p> 3800 1.2 lneto Compares two Lua values. 3801 1.2 lneto Returns 1 if the value at index <code>index1</code> satisfies <code>op</code> 3802 1.2 lneto when compared with the value at index <code>index2</code>, 3803 1.2 lneto following the semantics of the corresponding Lua operator 3804 1.2 lneto (that is, it may call metamethods). 3805 1.2 lneto Otherwise returns 0. 3806 1.3 lneto Also returns 0 if any of the indices is not valid. 3807 1.2 lneto 3808 1.2 lneto 3809 1.2 lneto <p> 3810 1.2 lneto The value of <code>op</code> must be one of the following constants: 3811 1.2 lneto 3812 1.2 lneto <ul> 3813 1.2 lneto 3814 1.2 lneto <li><b><a name="pdf-LUA_OPEQ"><code>LUA_OPEQ</code></a>: </b> compares for equality (<code>==</code>)</li> 3815 1.2 lneto <li><b><a name="pdf-LUA_OPLT"><code>LUA_OPLT</code></a>: </b> compares for less than (<code><</code>)</li> 3816 1.2 lneto <li><b><a name="pdf-LUA_OPLE"><code>LUA_OPLE</code></a>: </b> compares for less or equal (<code><=</code>)</li> 3817 1.2 lneto 3818 1.2 lneto </ul> 3819 1.2 lneto 3820 1.2 lneto 3821 1.2 lneto 3822 1.1 mbalmer 3823 1.1 mbalmer <hr><h3><a name="lua_concat"><code>lua_concat</code></a></h3><p> 3824 1.1 mbalmer <span class="apii">[-n, +1, <em>e</em>]</span> 3825 1.1 mbalmer <pre>void lua_concat (lua_State *L, int n);</pre> 3826 1.1 mbalmer 3827 1.1 mbalmer <p> 3828 1.1 mbalmer Concatenates the <code>n</code> values at the top of the stack, 3829 1.9 nikita pops them, and leaves the result on the top. 3830 1.1 mbalmer If <code>n</code> is 1, the result is the single value on the stack 3831 1.1 mbalmer (that is, the function does nothing); 3832 1.1 mbalmer if <code>n</code> is 0, the result is the empty string. 3833 1.1 mbalmer Concatenation is performed following the usual semantics of Lua 3834 1.2 lneto (see <a href="#3.4.6">§3.4.6</a>). 3835 1.1 mbalmer 3836 1.1 mbalmer 3837 1.1 mbalmer 3838 1.1 mbalmer 3839 1.1 mbalmer 3840 1.2 lneto <hr><h3><a name="lua_copy"><code>lua_copy</code></a></h3><p> 3841 1.2 lneto <span class="apii">[-0, +0, –]</span> 3842 1.2 lneto <pre>void lua_copy (lua_State *L, int fromidx, int toidx);</pre> 3843 1.1 mbalmer 3844 1.1 mbalmer <p> 3845 1.3 lneto Copies the element at index <code>fromidx</code> 3846 1.3 lneto into the valid index <code>toidx</code>, 3847 1.3 lneto replacing the value at that position. 3848 1.3 lneto Values at other positions are not affected. 3849 1.1 mbalmer 3850 1.1 mbalmer 3851 1.1 mbalmer 3852 1.1 mbalmer 3853 1.1 mbalmer 3854 1.1 mbalmer <hr><h3><a name="lua_createtable"><code>lua_createtable</code></a></h3><p> 3855 1.5 lneto <span class="apii">[-0, +1, <em>m</em>]</span> 3856 1.1 mbalmer <pre>void lua_createtable (lua_State *L, int narr, int nrec);</pre> 3857 1.1 mbalmer 3858 1.1 mbalmer <p> 3859 1.1 mbalmer Creates a new empty table and pushes it onto the stack. 3860 1.2 lneto Parameter <code>narr</code> is a hint for how many elements the table 3861 1.2 lneto will have as a sequence; 3862 1.2 lneto parameter <code>nrec</code> is a hint for how many other elements 3863 1.1 mbalmer the table will have. 3864 1.2 lneto Lua may use these hints to preallocate memory for the new table. 3865 1.9 nikita This preallocation may help performance when you know in advance 3866 1.2 lneto how many elements the table will have. 3867 1.1 mbalmer Otherwise you can use the function <a href="#lua_newtable"><code>lua_newtable</code></a>. 3868 1.1 mbalmer 3869 1.1 mbalmer 3870 1.1 mbalmer 3871 1.1 mbalmer 3872 1.1 mbalmer 3873 1.1 mbalmer <hr><h3><a name="lua_dump"><code>lua_dump</code></a></h3><p> 3874 1.5 lneto <span class="apii">[-0, +0, –]</span> 3875 1.2 lneto <pre>int lua_dump (lua_State *L, 3876 1.2 lneto lua_Writer writer, 3877 1.2 lneto void *data, 3878 1.2 lneto int strip);</pre> 3879 1.1 mbalmer 3880 1.1 mbalmer <p> 3881 1.1 mbalmer Dumps a function as a binary chunk. 3882 1.1 mbalmer Receives a Lua function on the top of the stack 3883 1.1 mbalmer and produces a binary chunk that, 3884 1.1 mbalmer if loaded again, 3885 1.1 mbalmer results in a function equivalent to the one dumped. 3886 1.1 mbalmer As it produces parts of the chunk, 3887 1.1 mbalmer <a href="#lua_dump"><code>lua_dump</code></a> calls function <code>writer</code> (see <a href="#lua_Writer"><code>lua_Writer</code></a>) 3888 1.1 mbalmer with the given <code>data</code> 3889 1.1 mbalmer to write them. 3890 1.1 mbalmer 3891 1.1 mbalmer 3892 1.1 mbalmer <p> 3893 1.2 lneto If <code>strip</code> is true, 3894 1.4 mbalmer the binary representation may not include all debug information 3895 1.4 mbalmer about the function, 3896 1.4 mbalmer to save space. 3897 1.2 lneto 3898 1.2 lneto 3899 1.2 lneto <p> 3900 1.1 mbalmer The value returned is the error code returned by the last 3901 1.1 mbalmer call to the writer; 3902 1.1 mbalmer 0 means no errors. 3903 1.1 mbalmer 3904 1.1 mbalmer 3905 1.1 mbalmer <p> 3906 1.1 mbalmer This function does not pop the Lua function from the stack. 3907 1.1 mbalmer 3908 1.1 mbalmer 3909 1.1 mbalmer 3910 1.1 mbalmer 3911 1.1 mbalmer 3912 1.1 mbalmer <hr><h3><a name="lua_error"><code>lua_error</code></a></h3><p> 3913 1.1 mbalmer <span class="apii">[-1, +0, <em>v</em>]</span> 3914 1.1 mbalmer <pre>int lua_error (lua_State *L);</pre> 3915 1.1 mbalmer 3916 1.1 mbalmer <p> 3917 1.9 nikita Raises a Lua error, 3918 1.9 nikita using the value on the top of the stack as the error object. 3919 1.1 mbalmer This function does a long jump, 3920 1.2 lneto and therefore never returns 3921 1.1 mbalmer (see <a href="#luaL_error"><code>luaL_error</code></a>). 3922 1.1 mbalmer 3923 1.1 mbalmer 3924 1.1 mbalmer 3925 1.1 mbalmer 3926 1.1 mbalmer 3927 1.1 mbalmer <hr><h3><a name="lua_gc"><code>lua_gc</code></a></h3><p> 3928 1.9 nikita <span class="apii">[-0, +0, –]</span> 3929 1.9 nikita <pre>int lua_gc (lua_State *L, int what, ...);</pre> 3930 1.1 mbalmer 3931 1.1 mbalmer <p> 3932 1.1 mbalmer Controls the garbage collector. 3933 1.1 mbalmer 3934 1.1 mbalmer 3935 1.1 mbalmer <p> 3936 1.1 mbalmer This function performs several tasks, 3937 1.9 nikita according to the value of the parameter <code>what</code>. 3938 1.9 nikita For options that need extra arguments, 3939 1.9 nikita they are listed after the option. 3940 1.1 mbalmer 3941 1.1 mbalmer <ul> 3942 1.1 mbalmer 3943 1.9 nikita <li><b><code>LUA_GCCOLLECT</code>: </b> 3944 1.9 nikita Performs a full garbage-collection cycle. 3945 1.9 nikita </li> 3946 1.9 nikita 3947 1.2 lneto <li><b><code>LUA_GCSTOP</code>: </b> 3948 1.9 nikita Stops the garbage collector. 3949 1.1 mbalmer </li> 3950 1.1 mbalmer 3951 1.2 lneto <li><b><code>LUA_GCRESTART</code>: </b> 3952 1.9 nikita Restarts the garbage collector. 3953 1.1 mbalmer </li> 3954 1.1 mbalmer 3955 1.2 lneto <li><b><code>LUA_GCCOUNT</code>: </b> 3956 1.9 nikita Returns the current amount of memory (in Kbytes) in use by Lua. 3957 1.1 mbalmer </li> 3958 1.1 mbalmer 3959 1.2 lneto <li><b><code>LUA_GCCOUNTB</code>: </b> 3960 1.9 nikita Returns the remainder of dividing the current amount of bytes of 3961 1.1 mbalmer memory in use by Lua by 1024. 3962 1.1 mbalmer </li> 3963 1.1 mbalmer 3964 1.9 nikita <li><b><code>LUA_GCSTEP</code> <code>(int stepsize)</code>: </b> 3965 1.9 nikita Performs an incremental step of garbage collection, 3966 1.9 nikita corresponding to the allocation of <code>stepsize</code> Kbytes. 3967 1.1 mbalmer </li> 3968 1.1 mbalmer 3969 1.9 nikita <li><b><code>LUA_GCISRUNNING</code>: </b> 3970 1.9 nikita Returns a boolean that tells whether the collector is running 3971 1.9 nikita (i.e., not stopped). 3972 1.1 mbalmer </li> 3973 1.1 mbalmer 3974 1.9 nikita <li><b><code>LUA_GCINC</code> (int pause, int stepmul, stepsize): </b> 3975 1.9 nikita Changes the collector to incremental mode 3976 1.9 nikita with the given parameters (see <a href="#2.5.1">§2.5.1</a>). 3977 1.9 nikita Returns the previous mode (<code>LUA_GCGEN</code> or <code>LUA_GCINC</code>). 3978 1.2 lneto </li> 3979 1.2 lneto 3980 1.9 nikita <li><b><code>LUA_GCGEN</code> (int minormul, int majormul): </b> 3981 1.9 nikita Changes the collector to generational mode 3982 1.9 nikita with the given parameters (see <a href="#2.5.2">§2.5.2</a>). 3983 1.9 nikita Returns the previous mode (<code>LUA_GCGEN</code> or <code>LUA_GCINC</code>). 3984 1.1 mbalmer </li> 3985 1.1 mbalmer 3986 1.9 nikita </ul><p> 3987 1.9 nikita For more details about these options, 3988 1.9 nikita see <a href="#pdf-collectgarbage"><code>collectgarbage</code></a>. 3989 1.9 nikita 3990 1.1 mbalmer 3991 1.2 lneto <p> 3992 1.9 nikita This function should not be called by a finalizer. 3993 1.2 lneto 3994 1.2 lneto 3995 1.1 mbalmer 3996 1.1 mbalmer 3997 1.1 mbalmer 3998 1.1 mbalmer <hr><h3><a name="lua_getallocf"><code>lua_getallocf</code></a></h3><p> 3999 1.2 lneto <span class="apii">[-0, +0, –]</span> 4000 1.1 mbalmer <pre>lua_Alloc lua_getallocf (lua_State *L, void **ud);</pre> 4001 1.1 mbalmer 4002 1.1 mbalmer <p> 4003 1.1 mbalmer Returns the memory-allocation function of a given state. 4004 1.1 mbalmer If <code>ud</code> is not <code>NULL</code>, Lua stores in <code>*ud</code> the 4005 1.3 lneto opaque pointer given when the memory-allocator function was set. 4006 1.1 mbalmer 4007 1.1 mbalmer 4008 1.1 mbalmer 4009 1.1 mbalmer 4010 1.1 mbalmer 4011 1.1 mbalmer <hr><h3><a name="lua_getfield"><code>lua_getfield</code></a></h3><p> 4012 1.1 mbalmer <span class="apii">[-0, +1, <em>e</em>]</span> 4013 1.2 lneto <pre>int lua_getfield (lua_State *L, int index, const char *k);</pre> 4014 1.1 mbalmer 4015 1.1 mbalmer <p> 4016 1.1 mbalmer Pushes onto the stack the value <code>t[k]</code>, 4017 1.2 lneto where <code>t</code> is the value at the given index. 4018 1.1 mbalmer As in Lua, this function may trigger a metamethod 4019 1.2 lneto for the "index" event (see <a href="#2.4">§2.4</a>). 4020 1.2 lneto 4021 1.2 lneto 4022 1.2 lneto <p> 4023 1.2 lneto Returns the type of the pushed value. 4024 1.1 mbalmer 4025 1.1 mbalmer 4026 1.1 mbalmer 4027 1.1 mbalmer 4028 1.1 mbalmer 4029 1.3 lneto <hr><h3><a name="lua_getextraspace"><code>lua_getextraspace</code></a></h3><p> 4030 1.3 lneto <span class="apii">[-0, +0, –]</span> 4031 1.3 lneto <pre>void *lua_getextraspace (lua_State *L);</pre> 4032 1.3 lneto 4033 1.3 lneto <p> 4034 1.3 lneto Returns a pointer to a raw memory area associated with the 4035 1.3 lneto given Lua state. 4036 1.3 lneto The application can use this area for any purpose; 4037 1.3 lneto Lua does not use it for anything. 4038 1.3 lneto 4039 1.3 lneto 4040 1.3 lneto <p> 4041 1.3 lneto Each new thread has this area initialized with a copy 4042 1.3 lneto of the area of the main thread. 4043 1.3 lneto 4044 1.3 lneto 4045 1.3 lneto <p> 4046 1.3 lneto By default, this area has the size of a pointer to void, 4047 1.3 lneto but you can recompile Lua with a different size for this area. 4048 1.3 lneto (See <code>LUA_EXTRASPACE</code> in <code>luaconf.h</code>.) 4049 1.3 lneto 4050 1.3 lneto 4051 1.3 lneto 4052 1.3 lneto 4053 1.3 lneto 4054 1.1 mbalmer <hr><h3><a name="lua_getglobal"><code>lua_getglobal</code></a></h3><p> 4055 1.1 mbalmer <span class="apii">[-0, +1, <em>e</em>]</span> 4056 1.2 lneto <pre>int lua_getglobal (lua_State *L, const char *name);</pre> 4057 1.1 mbalmer 4058 1.1 mbalmer <p> 4059 1.1 mbalmer Pushes onto the stack the value of the global <code>name</code>. 4060 1.2 lneto Returns the type of that value. 4061 1.1 mbalmer 4062 1.1 mbalmer 4063 1.1 mbalmer 4064 1.1 mbalmer 4065 1.1 mbalmer 4066 1.3 lneto <hr><h3><a name="lua_geti"><code>lua_geti</code></a></h3><p> 4067 1.3 lneto <span class="apii">[-0, +1, <em>e</em>]</span> 4068 1.3 lneto <pre>int lua_geti (lua_State *L, int index, lua_Integer i);</pre> 4069 1.3 lneto 4070 1.3 lneto <p> 4071 1.3 lneto Pushes onto the stack the value <code>t[i]</code>, 4072 1.3 lneto where <code>t</code> is the value at the given index. 4073 1.3 lneto As in Lua, this function may trigger a metamethod 4074 1.3 lneto for the "index" event (see <a href="#2.4">§2.4</a>). 4075 1.3 lneto 4076 1.3 lneto 4077 1.3 lneto <p> 4078 1.3 lneto Returns the type of the pushed value. 4079 1.3 lneto 4080 1.3 lneto 4081 1.3 lneto 4082 1.3 lneto 4083 1.3 lneto 4084 1.1 mbalmer <hr><h3><a name="lua_getmetatable"><code>lua_getmetatable</code></a></h3><p> 4085 1.2 lneto <span class="apii">[-0, +(0|1), –]</span> 4086 1.1 mbalmer <pre>int lua_getmetatable (lua_State *L, int index);</pre> 4087 1.1 mbalmer 4088 1.1 mbalmer <p> 4089 1.3 lneto If the value at the given index has a metatable, 4090 1.3 lneto the function pushes that metatable onto the stack and returns 1. 4091 1.3 lneto Otherwise, 4092 1.1 mbalmer the function returns 0 and pushes nothing on the stack. 4093 1.1 mbalmer 4094 1.1 mbalmer 4095 1.1 mbalmer 4096 1.1 mbalmer 4097 1.1 mbalmer 4098 1.1 mbalmer <hr><h3><a name="lua_gettable"><code>lua_gettable</code></a></h3><p> 4099 1.1 mbalmer <span class="apii">[-1, +1, <em>e</em>]</span> 4100 1.2 lneto <pre>int lua_gettable (lua_State *L, int index);</pre> 4101 1.1 mbalmer 4102 1.1 mbalmer <p> 4103 1.1 mbalmer Pushes onto the stack the value <code>t[k]</code>, 4104 1.2 lneto where <code>t</code> is the value at the given index 4105 1.9 nikita and <code>k</code> is the value on the top of the stack. 4106 1.1 mbalmer 4107 1.1 mbalmer 4108 1.1 mbalmer <p> 4109 1.3 lneto This function pops the key from the stack, 4110 1.3 lneto pushing the resulting value in its place. 4111 1.1 mbalmer As in Lua, this function may trigger a metamethod 4112 1.2 lneto for the "index" event (see <a href="#2.4">§2.4</a>). 4113 1.2 lneto 4114 1.2 lneto 4115 1.2 lneto <p> 4116 1.2 lneto Returns the type of the pushed value. 4117 1.1 mbalmer 4118 1.1 mbalmer 4119 1.1 mbalmer 4120 1.1 mbalmer 4121 1.1 mbalmer 4122 1.1 mbalmer <hr><h3><a name="lua_gettop"><code>lua_gettop</code></a></h3><p> 4123 1.2 lneto <span class="apii">[-0, +0, –]</span> 4124 1.1 mbalmer <pre>int lua_gettop (lua_State *L);</pre> 4125 1.1 mbalmer 4126 1.1 mbalmer <p> 4127 1.1 mbalmer Returns the index of the top element in the stack. 4128 1.1 mbalmer Because indices start at 1, 4129 1.3 lneto this result is equal to the number of elements in the stack; 4130 1.3 lneto in particular, 0 means an empty stack. 4131 1.1 mbalmer 4132 1.1 mbalmer 4133 1.1 mbalmer 4134 1.1 mbalmer 4135 1.1 mbalmer 4136 1.9 nikita <hr><h3><a name="lua_getiuservalue"><code>lua_getiuservalue</code></a></h3><p> 4137 1.2 lneto <span class="apii">[-0, +1, –]</span> 4138 1.9 nikita <pre>int lua_getiuservalue (lua_State *L, int index, int n);</pre> 4139 1.2 lneto 4140 1.2 lneto <p> 4141 1.9 nikita Pushes onto the stack the <code>n</code>-th user value associated with the 4142 1.9 nikita full userdata at the given index and 4143 1.9 nikita returns the type of the pushed value. 4144 1.2 lneto 4145 1.2 lneto 4146 1.2 lneto <p> 4147 1.9 nikita If the userdata does not have that value, 4148 1.9 nikita pushes <b>nil</b> and returns <a href="#pdf-LUA_TNONE"><code>LUA_TNONE</code></a>. 4149 1.2 lneto 4150 1.2 lneto 4151 1.2 lneto 4152 1.2 lneto 4153 1.2 lneto 4154 1.1 mbalmer <hr><h3><a name="lua_insert"><code>lua_insert</code></a></h3><p> 4155 1.2 lneto <span class="apii">[-1, +1, –]</span> 4156 1.1 mbalmer <pre>void lua_insert (lua_State *L, int index);</pre> 4157 1.1 mbalmer 4158 1.1 mbalmer <p> 4159 1.1 mbalmer Moves the top element into the given valid index, 4160 1.1 mbalmer shifting up the elements above this index to open space. 4161 1.2 lneto This function cannot be called with a pseudo-index, 4162 1.1 mbalmer because a pseudo-index is not an actual stack position. 4163 1.1 mbalmer 4164 1.1 mbalmer 4165 1.1 mbalmer 4166 1.1 mbalmer 4167 1.1 mbalmer 4168 1.1 mbalmer <hr><h3><a name="lua_Integer"><code>lua_Integer</code></a></h3> 4169 1.2 lneto <pre>typedef ... lua_Integer;</pre> 4170 1.1 mbalmer 4171 1.1 mbalmer <p> 4172 1.2 lneto The type of integers in Lua. 4173 1.1 mbalmer 4174 1.1 mbalmer 4175 1.1 mbalmer <p> 4176 1.3 lneto By default this type is <code>long long</code>, 4177 1.2 lneto (usually a 64-bit two-complement integer), 4178 1.3 lneto but that can be changed to <code>long</code> or <code>int</code> 4179 1.2 lneto (usually a 32-bit two-complement integer). 4180 1.4 mbalmer (See <code>LUA_INT_TYPE</code> in <code>luaconf.h</code>.) 4181 1.2 lneto 4182 1.2 lneto 4183 1.2 lneto <p> 4184 1.2 lneto Lua also defines the constants 4185 1.2 lneto <a name="pdf-LUA_MININTEGER"><code>LUA_MININTEGER</code></a> and <a name="pdf-LUA_MAXINTEGER"><code>LUA_MAXINTEGER</code></a>, 4186 1.2 lneto with the minimum and the maximum values that fit in this type. 4187 1.1 mbalmer 4188 1.1 mbalmer 4189 1.1 mbalmer 4190 1.1 mbalmer 4191 1.1 mbalmer 4192 1.1 mbalmer <hr><h3><a name="lua_isboolean"><code>lua_isboolean</code></a></h3><p> 4193 1.2 lneto <span class="apii">[-0, +0, –]</span> 4194 1.1 mbalmer <pre>int lua_isboolean (lua_State *L, int index);</pre> 4195 1.1 mbalmer 4196 1.1 mbalmer <p> 4197 1.2 lneto Returns 1 if the value at the given index is a boolean, 4198 1.1 mbalmer and 0 otherwise. 4199 1.1 mbalmer 4200 1.1 mbalmer 4201 1.1 mbalmer 4202 1.1 mbalmer 4203 1.1 mbalmer 4204 1.1 mbalmer <hr><h3><a name="lua_iscfunction"><code>lua_iscfunction</code></a></h3><p> 4205 1.2 lneto <span class="apii">[-0, +0, –]</span> 4206 1.1 mbalmer <pre>int lua_iscfunction (lua_State *L, int index);</pre> 4207 1.1 mbalmer 4208 1.1 mbalmer <p> 4209 1.2 lneto Returns 1 if the value at the given index is a C function, 4210 1.1 mbalmer and 0 otherwise. 4211 1.1 mbalmer 4212 1.1 mbalmer 4213 1.1 mbalmer 4214 1.1 mbalmer 4215 1.1 mbalmer 4216 1.1 mbalmer <hr><h3><a name="lua_isfunction"><code>lua_isfunction</code></a></h3><p> 4217 1.2 lneto <span class="apii">[-0, +0, –]</span> 4218 1.1 mbalmer <pre>int lua_isfunction (lua_State *L, int index);</pre> 4219 1.1 mbalmer 4220 1.1 mbalmer <p> 4221 1.2 lneto Returns 1 if the value at the given index is a function 4222 1.1 mbalmer (either C or Lua), and 0 otherwise. 4223 1.1 mbalmer 4224 1.1 mbalmer 4225 1.1 mbalmer 4226 1.1 mbalmer 4227 1.1 mbalmer 4228 1.2 lneto <hr><h3><a name="lua_isinteger"><code>lua_isinteger</code></a></h3><p> 4229 1.2 lneto <span class="apii">[-0, +0, –]</span> 4230 1.2 lneto <pre>int lua_isinteger (lua_State *L, int index);</pre> 4231 1.2 lneto 4232 1.2 lneto <p> 4233 1.2 lneto Returns 1 if the value at the given index is an integer 4234 1.2 lneto (that is, the value is a number and is represented as an integer), 4235 1.2 lneto and 0 otherwise. 4236 1.2 lneto 4237 1.2 lneto 4238 1.2 lneto 4239 1.2 lneto 4240 1.2 lneto 4241 1.1 mbalmer <hr><h3><a name="lua_islightuserdata"><code>lua_islightuserdata</code></a></h3><p> 4242 1.2 lneto <span class="apii">[-0, +0, –]</span> 4243 1.1 mbalmer <pre>int lua_islightuserdata (lua_State *L, int index);</pre> 4244 1.1 mbalmer 4245 1.1 mbalmer <p> 4246 1.2 lneto Returns 1 if the value at the given index is a light userdata, 4247 1.1 mbalmer and 0 otherwise. 4248 1.1 mbalmer 4249 1.1 mbalmer 4250 1.1 mbalmer 4251 1.1 mbalmer 4252 1.1 mbalmer 4253 1.1 mbalmer <hr><h3><a name="lua_isnil"><code>lua_isnil</code></a></h3><p> 4254 1.2 lneto <span class="apii">[-0, +0, –]</span> 4255 1.1 mbalmer <pre>int lua_isnil (lua_State *L, int index);</pre> 4256 1.1 mbalmer 4257 1.1 mbalmer <p> 4258 1.2 lneto Returns 1 if the value at the given index is <b>nil</b>, 4259 1.1 mbalmer and 0 otherwise. 4260 1.1 mbalmer 4261 1.1 mbalmer 4262 1.1 mbalmer 4263 1.1 mbalmer 4264 1.1 mbalmer 4265 1.1 mbalmer <hr><h3><a name="lua_isnone"><code>lua_isnone</code></a></h3><p> 4266 1.2 lneto <span class="apii">[-0, +0, –]</span> 4267 1.1 mbalmer <pre>int lua_isnone (lua_State *L, int index);</pre> 4268 1.1 mbalmer 4269 1.1 mbalmer <p> 4270 1.2 lneto Returns 1 if the given index is not valid, 4271 1.1 mbalmer and 0 otherwise. 4272 1.1 mbalmer 4273 1.1 mbalmer 4274 1.1 mbalmer 4275 1.1 mbalmer 4276 1.1 mbalmer 4277 1.1 mbalmer <hr><h3><a name="lua_isnoneornil"><code>lua_isnoneornil</code></a></h3><p> 4278 1.2 lneto <span class="apii">[-0, +0, –]</span> 4279 1.1 mbalmer <pre>int lua_isnoneornil (lua_State *L, int index);</pre> 4280 1.1 mbalmer 4281 1.1 mbalmer <p> 4282 1.2 lneto Returns 1 if the given index is not valid 4283 1.1 mbalmer or if the value at this index is <b>nil</b>, 4284 1.1 mbalmer and 0 otherwise. 4285 1.1 mbalmer 4286 1.1 mbalmer 4287 1.1 mbalmer 4288 1.1 mbalmer 4289 1.1 mbalmer 4290 1.1 mbalmer <hr><h3><a name="lua_isnumber"><code>lua_isnumber</code></a></h3><p> 4291 1.2 lneto <span class="apii">[-0, +0, –]</span> 4292 1.1 mbalmer <pre>int lua_isnumber (lua_State *L, int index);</pre> 4293 1.1 mbalmer 4294 1.1 mbalmer <p> 4295 1.2 lneto Returns 1 if the value at the given index is a number 4296 1.1 mbalmer or a string convertible to a number, 4297 1.1 mbalmer and 0 otherwise. 4298 1.1 mbalmer 4299 1.1 mbalmer 4300 1.1 mbalmer 4301 1.1 mbalmer 4302 1.1 mbalmer 4303 1.1 mbalmer <hr><h3><a name="lua_isstring"><code>lua_isstring</code></a></h3><p> 4304 1.2 lneto <span class="apii">[-0, +0, –]</span> 4305 1.1 mbalmer <pre>int lua_isstring (lua_State *L, int index);</pre> 4306 1.1 mbalmer 4307 1.1 mbalmer <p> 4308 1.2 lneto Returns 1 if the value at the given index is a string 4309 1.1 mbalmer or a number (which is always convertible to a string), 4310 1.1 mbalmer and 0 otherwise. 4311 1.1 mbalmer 4312 1.1 mbalmer 4313 1.1 mbalmer 4314 1.1 mbalmer 4315 1.1 mbalmer 4316 1.1 mbalmer <hr><h3><a name="lua_istable"><code>lua_istable</code></a></h3><p> 4317 1.2 lneto <span class="apii">[-0, +0, –]</span> 4318 1.1 mbalmer <pre>int lua_istable (lua_State *L, int index);</pre> 4319 1.1 mbalmer 4320 1.1 mbalmer <p> 4321 1.2 lneto Returns 1 if the value at the given index is a table, 4322 1.1 mbalmer and 0 otherwise. 4323 1.1 mbalmer 4324 1.1 mbalmer 4325 1.1 mbalmer 4326 1.1 mbalmer 4327 1.1 mbalmer 4328 1.1 mbalmer <hr><h3><a name="lua_isthread"><code>lua_isthread</code></a></h3><p> 4329 1.2 lneto <span class="apii">[-0, +0, –]</span> 4330 1.1 mbalmer <pre>int lua_isthread (lua_State *L, int index);</pre> 4331 1.1 mbalmer 4332 1.1 mbalmer <p> 4333 1.2 lneto Returns 1 if the value at the given index is a thread, 4334 1.1 mbalmer and 0 otherwise. 4335 1.1 mbalmer 4336 1.1 mbalmer 4337 1.1 mbalmer 4338 1.1 mbalmer 4339 1.1 mbalmer 4340 1.1 mbalmer <hr><h3><a name="lua_isuserdata"><code>lua_isuserdata</code></a></h3><p> 4341 1.2 lneto <span class="apii">[-0, +0, –]</span> 4342 1.1 mbalmer <pre>int lua_isuserdata (lua_State *L, int index);</pre> 4343 1.1 mbalmer 4344 1.1 mbalmer <p> 4345 1.2 lneto Returns 1 if the value at the given index is a userdata 4346 1.1 mbalmer (either full or light), and 0 otherwise. 4347 1.1 mbalmer 4348 1.1 mbalmer 4349 1.1 mbalmer 4350 1.1 mbalmer 4351 1.1 mbalmer 4352 1.2 lneto <hr><h3><a name="lua_isyieldable"><code>lua_isyieldable</code></a></h3><p> 4353 1.2 lneto <span class="apii">[-0, +0, –]</span> 4354 1.2 lneto <pre>int lua_isyieldable (lua_State *L);</pre> 4355 1.2 lneto 4356 1.2 lneto <p> 4357 1.2 lneto Returns 1 if the given coroutine can yield, 4358 1.2 lneto and 0 otherwise. 4359 1.2 lneto 4360 1.2 lneto 4361 1.2 lneto 4362 1.2 lneto 4363 1.2 lneto 4364 1.3 lneto <hr><h3><a name="lua_KContext"><code>lua_KContext</code></a></h3> 4365 1.3 lneto <pre>typedef ... lua_KContext;</pre> 4366 1.3 lneto 4367 1.3 lneto <p> 4368 1.3 lneto The type for continuation-function contexts. 4369 1.4 mbalmer It must be a numeric type. 4370 1.3 lneto This type is defined as <code>intptr_t</code> 4371 1.3 lneto when <code>intptr_t</code> is available, 4372 1.3 lneto so that it can store pointers too. 4373 1.3 lneto Otherwise, it is defined as <code>ptrdiff_t</code>. 4374 1.3 lneto 4375 1.3 lneto 4376 1.3 lneto 4377 1.3 lneto 4378 1.3 lneto 4379 1.2 lneto <hr><h3><a name="lua_KFunction"><code>lua_KFunction</code></a></h3> 4380 1.3 lneto <pre>typedef int (*lua_KFunction) (lua_State *L, int status, lua_KContext ctx);</pre> 4381 1.2 lneto 4382 1.2 lneto <p> 4383 1.9 nikita Type for continuation functions (see <a href="#4.5">§4.5</a>). 4384 1.2 lneto 4385 1.2 lneto 4386 1.2 lneto 4387 1.2 lneto 4388 1.2 lneto 4389 1.2 lneto <hr><h3><a name="lua_len"><code>lua_len</code></a></h3><p> 4390 1.2 lneto <span class="apii">[-0, +1, <em>e</em>]</span> 4391 1.2 lneto <pre>void lua_len (lua_State *L, int index);</pre> 4392 1.1 mbalmer 4393 1.1 mbalmer <p> 4394 1.3 lneto Returns the length of the value at the given index. 4395 1.3 lneto It is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">§3.4.7</a>) and 4396 1.3 lneto may trigger a metamethod for the "length" event (see <a href="#2.4">§2.4</a>). 4397 1.2 lneto The result is pushed on the stack. 4398 1.1 mbalmer 4399 1.1 mbalmer 4400 1.1 mbalmer 4401 1.1 mbalmer 4402 1.1 mbalmer 4403 1.1 mbalmer <hr><h3><a name="lua_load"><code>lua_load</code></a></h3><p> 4404 1.2 lneto <span class="apii">[-0, +1, –]</span> 4405 1.1 mbalmer <pre>int lua_load (lua_State *L, 4406 1.1 mbalmer lua_Reader reader, 4407 1.1 mbalmer void *data, 4408 1.3 lneto const char *chunkname, 4409 1.2 lneto const char *mode);</pre> 4410 1.1 mbalmer 4411 1.1 mbalmer <p> 4412 1.3 lneto Loads a Lua chunk without running it. 4413 1.1 mbalmer If there are no errors, 4414 1.2 lneto <code>lua_load</code> pushes the compiled chunk as a Lua 4415 1.1 mbalmer function on top of the stack. 4416 1.1 mbalmer Otherwise, it pushes an error message. 4417 1.2 lneto 4418 1.2 lneto 4419 1.2 lneto <p> 4420 1.2 lneto The <code>lua_load</code> function uses a user-supplied <code>reader</code> function 4421 1.2 lneto to read the chunk (see <a href="#lua_Reader"><code>lua_Reader</code></a>). 4422 1.2 lneto The <code>data</code> argument is an opaque value passed to the reader function. 4423 1.2 lneto 4424 1.2 lneto 4425 1.2 lneto <p> 4426 1.3 lneto The <code>chunkname</code> argument gives a name to the chunk, 4427 1.9 nikita which is used for error messages and in debug information (see <a href="#4.7">§4.7</a>). 4428 1.1 mbalmer 4429 1.1 mbalmer 4430 1.1 mbalmer <p> 4431 1.2 lneto <code>lua_load</code> automatically detects whether the chunk is text or binary 4432 1.1 mbalmer and loads it accordingly (see program <code>luac</code>). 4433 1.2 lneto The string <code>mode</code> works as in function <a href="#pdf-load"><code>load</code></a>, 4434 1.2 lneto with the addition that 4435 1.2 lneto a <code>NULL</code> value is equivalent to the string "<code>bt</code>". 4436 1.1 mbalmer 4437 1.1 mbalmer 4438 1.1 mbalmer <p> 4439 1.2 lneto <code>lua_load</code> uses the stack internally, 4440 1.2 lneto so the reader function must always leave the stack 4441 1.2 lneto unmodified when returning. 4442 1.1 mbalmer 4443 1.1 mbalmer 4444 1.1 mbalmer <p> 4445 1.9 nikita <code>lua_load</code> can return 4446 1.9 nikita <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>, <a href="#pdf-LUA_ERRSYNTAX"><code>LUA_ERRSYNTAX</code></a>, or <a href="#pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>. 4447 1.9 nikita The function may also return other values corresponding to 4448 1.9 nikita errors raised by the read function (see <a href="#4.4.1">§4.4.1</a>). 4449 1.9 nikita 4450 1.9 nikita 4451 1.9 nikita <p> 4452 1.3 lneto If the resulting function has upvalues, 4453 1.3 lneto its first upvalue is set to the value of the global environment 4454 1.9 nikita stored at index <code>LUA_RIDX_GLOBALS</code> in the registry (see <a href="#4.3">§4.3</a>). 4455 1.2 lneto When loading main chunks, 4456 1.2 lneto this upvalue will be the <code>_ENV</code> variable (see <a href="#2.2">§2.2</a>). 4457 1.3 lneto Other upvalues are initialized with <b>nil</b>. 4458 1.1 mbalmer 4459 1.1 mbalmer 4460 1.1 mbalmer 4461 1.1 mbalmer 4462 1.1 mbalmer 4463 1.1 mbalmer <hr><h3><a name="lua_newstate"><code>lua_newstate</code></a></h3><p> 4464 1.2 lneto <span class="apii">[-0, +0, –]</span> 4465 1.1 mbalmer <pre>lua_State *lua_newstate (lua_Alloc f, void *ud);</pre> 4466 1.1 mbalmer 4467 1.1 mbalmer <p> 4468 1.9 nikita Creates a new independent state and returns its main thread. 4469 1.9 nikita Returns <code>NULL</code> if it cannot create the state 4470 1.1 mbalmer (due to lack of memory). 4471 1.1 mbalmer The argument <code>f</code> is the allocator function; 4472 1.9 nikita Lua will do all memory allocation for this state 4473 1.7 mbalmer through this function (see <a href="#lua_Alloc"><code>lua_Alloc</code></a>). 4474 1.1 mbalmer The second argument, <code>ud</code>, is an opaque pointer that Lua 4475 1.2 lneto passes to the allocator in every call. 4476 1.1 mbalmer 4477 1.1 mbalmer 4478 1.1 mbalmer 4479 1.1 mbalmer 4480 1.1 mbalmer 4481 1.1 mbalmer <hr><h3><a name="lua_newtable"><code>lua_newtable</code></a></h3><p> 4482 1.5 lneto <span class="apii">[-0, +1, <em>m</em>]</span> 4483 1.1 mbalmer <pre>void lua_newtable (lua_State *L);</pre> 4484 1.1 mbalmer 4485 1.1 mbalmer <p> 4486 1.1 mbalmer Creates a new empty table and pushes it onto the stack. 4487 1.1 mbalmer It is equivalent to <code>lua_createtable(L, 0, 0)</code>. 4488 1.1 mbalmer 4489 1.1 mbalmer 4490 1.1 mbalmer 4491 1.1 mbalmer 4492 1.1 mbalmer 4493 1.1 mbalmer <hr><h3><a name="lua_newthread"><code>lua_newthread</code></a></h3><p> 4494 1.5 lneto <span class="apii">[-0, +1, <em>m</em>]</span> 4495 1.1 mbalmer <pre>lua_State *lua_newthread (lua_State *L);</pre> 4496 1.1 mbalmer 4497 1.1 mbalmer <p> 4498 1.1 mbalmer Creates a new thread, pushes it on the stack, 4499 1.1 mbalmer and returns a pointer to a <a href="#lua_State"><code>lua_State</code></a> that represents this new thread. 4500 1.2 lneto The new thread returned by this function shares with the original thread 4501 1.2 lneto its global environment, 4502 1.1 mbalmer but has an independent execution stack. 4503 1.1 mbalmer 4504 1.1 mbalmer 4505 1.1 mbalmer <p> 4506 1.1 mbalmer Threads are subject to garbage collection, 4507 1.1 mbalmer like any Lua object. 4508 1.1 mbalmer 4509 1.1 mbalmer 4510 1.1 mbalmer 4511 1.1 mbalmer 4512 1.1 mbalmer 4513 1.9 nikita <hr><h3><a name="lua_newuserdatauv"><code>lua_newuserdatauv</code></a></h3><p> 4514 1.5 lneto <span class="apii">[-0, +1, <em>m</em>]</span> 4515 1.9 nikita <pre>void *lua_newuserdatauv (lua_State *L, size_t size, int nuvalue);</pre> 4516 1.9 nikita 4517 1.9 nikita <p> 4518 1.9 nikita This function creates and pushes on the stack a new full userdata, 4519 1.9 nikita with <code>nuvalue</code> associated Lua values, called <code>user values</code>, 4520 1.9 nikita plus an associated block of raw memory with <code>size</code> bytes. 4521 1.9 nikita (The user values can be set and read with the functions 4522 1.9 nikita <a href="#lua_setiuservalue"><code>lua_setiuservalue</code></a> and <a href="#lua_getiuservalue"><code>lua_getiuservalue</code></a>.) 4523 1.9 nikita 4524 1.1 mbalmer 4525 1.1 mbalmer <p> 4526 1.9 nikita The function returns the address of the block of memory. 4527 1.9 nikita Lua ensures that this address is valid as long as 4528 1.9 nikita the corresponding userdata is alive (see <a href="#2.5">§2.5</a>). 4529 1.9 nikita Moreover, if the userdata is marked for finalization (see <a href="#2.5.3">§2.5.3</a>), 4530 1.9 nikita its address is valid at least until the call to its finalizer. 4531 1.1 mbalmer 4532 1.1 mbalmer 4533 1.1 mbalmer 4534 1.1 mbalmer 4535 1.1 mbalmer 4536 1.1 mbalmer <hr><h3><a name="lua_next"><code>lua_next</code></a></h3><p> 4537 1.9 nikita <span class="apii">[-1, +(2|0), <em>v</em>]</span> 4538 1.1 mbalmer <pre>int lua_next (lua_State *L, int index);</pre> 4539 1.1 mbalmer 4540 1.1 mbalmer <p> 4541 1.1 mbalmer Pops a key from the stack, 4542 1.9 nikita and pushes a key–value pair from the table at the given index, 4543 1.9 nikita the "next" pair after the given key. 4544 1.1 mbalmer If there are no more elements in the table, 4545 1.9 nikita then <a href="#lua_next"><code>lua_next</code></a> returns 0 and pushes nothing. 4546 1.1 mbalmer 4547 1.1 mbalmer 4548 1.1 mbalmer <p> 4549 1.9 nikita A typical table traversal looks like this: 4550 1.1 mbalmer 4551 1.1 mbalmer <pre> 4552 1.1 mbalmer /* table is in the stack at index 't' */ 4553 1.1 mbalmer lua_pushnil(L); /* first key */ 4554 1.1 mbalmer while (lua_next(L, t) != 0) { 4555 1.1 mbalmer /* uses 'key' (at index -2) and 'value' (at index -1) */ 4556 1.1 mbalmer printf("%s - %s\n", 4557 1.1 mbalmer lua_typename(L, lua_type(L, -2)), 4558 1.1 mbalmer lua_typename(L, lua_type(L, -1))); 4559 1.1 mbalmer /* removes 'value'; keeps 'key' for next iteration */ 4560 1.1 mbalmer lua_pop(L, 1); 4561 1.1 mbalmer } 4562 1.1 mbalmer </pre> 4563 1.1 mbalmer 4564 1.1 mbalmer <p> 4565 1.1 mbalmer While traversing a table, 4566 1.9 nikita avoid calling <a href="#lua_tolstring"><code>lua_tolstring</code></a> directly on a key, 4567 1.1 mbalmer unless you know that the key is actually a string. 4568 1.2 lneto Recall that <a href="#lua_tolstring"><code>lua_tolstring</code></a> may change 4569 1.1 mbalmer the value at the given index; 4570 1.1 mbalmer this confuses the next call to <a href="#lua_next"><code>lua_next</code></a>. 4571 1.1 mbalmer 4572 1.1 mbalmer 4573 1.2 lneto <p> 4574 1.9 nikita This function may raise an error if the given key 4575 1.9 nikita is neither <b>nil</b> nor present in the table. 4576 1.2 lneto See function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying 4577 1.2 lneto the table during its traversal. 4578 1.2 lneto 4579 1.2 lneto 4580 1.1 mbalmer 4581 1.1 mbalmer 4582 1.1 mbalmer 4583 1.1 mbalmer <hr><h3><a name="lua_Number"><code>lua_Number</code></a></h3> 4584 1.4 mbalmer <pre>typedef ... lua_Number;</pre> 4585 1.1 mbalmer 4586 1.1 mbalmer <p> 4587 1.2 lneto The type of floats in Lua. 4588 1.1 mbalmer 4589 1.1 mbalmer 4590 1.1 mbalmer <p> 4591 1.2 lneto By default this type is double, 4592 1.4 mbalmer but that can be changed to a single float or a long double. 4593 1.4 mbalmer (See <code>LUA_FLOAT_TYPE</code> in <code>luaconf.h</code>.) 4594 1.2 lneto 4595 1.2 lneto 4596 1.1 mbalmer 4597 1.1 mbalmer 4598 1.1 mbalmer 4599 1.3 lneto <hr><h3><a name="lua_numbertointeger"><code>lua_numbertointeger</code></a></h3> 4600 1.3 lneto <pre>int lua_numbertointeger (lua_Number n, lua_Integer *p);</pre> 4601 1.1 mbalmer 4602 1.2 lneto <p> 4603 1.9 nikita Tries to convert a Lua float to a Lua integer; 4604 1.9 nikita the float <code>n</code> must have an integral value. 4605 1.2 lneto If that value is within the range of Lua integers, 4606 1.2 lneto it is converted to an integer and assigned to <code>*p</code>. 4607 1.2 lneto The macro results in a boolean indicating whether the 4608 1.2 lneto conversion was successful. 4609 1.2 lneto (Note that this range test can be tricky to do 4610 1.9 nikita correctly without this macro, due to rounding.) 4611 1.1 mbalmer 4612 1.1 mbalmer 4613 1.1 mbalmer <p> 4614 1.2 lneto This macro may evaluate its arguments more than once. 4615 1.1 mbalmer 4616 1.1 mbalmer 4617 1.1 mbalmer 4618 1.1 mbalmer 4619 1.1 mbalmer 4620 1.1 mbalmer <hr><h3><a name="lua_pcall"><code>lua_pcall</code></a></h3><p> 4621 1.2 lneto <span class="apii">[-(nargs + 1), +(nresults|1), –]</span> 4622 1.2 lneto <pre>int lua_pcall (lua_State *L, int nargs, int nresults, int msgh);</pre> 4623 1.1 mbalmer 4624 1.1 mbalmer <p> 4625 1.9 nikita Calls a function (or a callable object) in protected mode. 4626 1.1 mbalmer 4627 1.1 mbalmer 4628 1.1 mbalmer <p> 4629 1.1 mbalmer Both <code>nargs</code> and <code>nresults</code> have the same meaning as 4630 1.1 mbalmer in <a href="#lua_call"><code>lua_call</code></a>. 4631 1.1 mbalmer If there are no errors during the call, 4632 1.1 mbalmer <a href="#lua_pcall"><code>lua_pcall</code></a> behaves exactly like <a href="#lua_call"><code>lua_call</code></a>. 4633 1.1 mbalmer However, if there is any error, 4634 1.1 mbalmer <a href="#lua_pcall"><code>lua_pcall</code></a> catches it, 4635 1.6 salazar pushes a single value on the stack (the error object), 4636 1.1 mbalmer and returns an error code. 4637 1.1 mbalmer Like <a href="#lua_call"><code>lua_call</code></a>, 4638 1.1 mbalmer <a href="#lua_pcall"><code>lua_pcall</code></a> always removes the function 4639 1.1 mbalmer and its arguments from the stack. 4640 1.1 mbalmer 4641 1.1 mbalmer 4642 1.1 mbalmer <p> 4643 1.2 lneto If <code>msgh</code> is 0, 4644 1.6 salazar then the error object returned on the stack 4645 1.6 salazar is exactly the original error object. 4646 1.2 lneto Otherwise, <code>msgh</code> is the stack index of a 4647 1.2 lneto <em>message handler</em>. 4648 1.4 mbalmer (This index cannot be a pseudo-index.) 4649 1.1 mbalmer In case of runtime errors, 4650 1.9 nikita this handler will be called with the error object 4651 1.6 salazar and its return value will be the object 4652 1.2 lneto returned on the stack by <a href="#lua_pcall"><code>lua_pcall</code></a>. 4653 1.1 mbalmer 4654 1.1 mbalmer 4655 1.1 mbalmer <p> 4656 1.2 lneto Typically, the message handler is used to add more debug 4657 1.6 salazar information to the error object, such as a stack traceback. 4658 1.1 mbalmer Such information cannot be gathered after the return of <a href="#lua_pcall"><code>lua_pcall</code></a>, 4659 1.1 mbalmer since by then the stack has unwound. 4660 1.1 mbalmer 4661 1.1 mbalmer 4662 1.1 mbalmer <p> 4663 1.9 nikita The <a href="#lua_pcall"><code>lua_pcall</code></a> function returns one of the following status codes: 4664 1.9 nikita <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>, <a href="#pdf-LUA_ERRRUN"><code>LUA_ERRRUN</code></a>, <a href="#pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>, or <a href="#pdf-LUA_ERRERR"><code>LUA_ERRERR</code></a>. 4665 1.2 lneto 4666 1.1 mbalmer 4667 1.1 mbalmer 4668 1.1 mbalmer 4669 1.1 mbalmer 4670 1.2 lneto <hr><h3><a name="lua_pcallk"><code>lua_pcallk</code></a></h3><p> 4671 1.2 lneto <span class="apii">[-(nargs + 1), +(nresults|1), –]</span> 4672 1.2 lneto <pre>int lua_pcallk (lua_State *L, 4673 1.2 lneto int nargs, 4674 1.2 lneto int nresults, 4675 1.3 lneto int msgh, 4676 1.3 lneto lua_KContext ctx, 4677 1.2 lneto lua_KFunction k);</pre> 4678 1.2 lneto 4679 1.2 lneto <p> 4680 1.2 lneto This function behaves exactly like <a href="#lua_pcall"><code>lua_pcall</code></a>, 4681 1.9 nikita except that it allows the called function to yield (see <a href="#4.5">§4.5</a>). 4682 1.2 lneto 4683 1.2 lneto 4684 1.2 lneto 4685 1.2 lneto 4686 1.2 lneto 4687 1.1 mbalmer <hr><h3><a name="lua_pop"><code>lua_pop</code></a></h3><p> 4688 1.9 nikita <span class="apii">[-n, +0, <em>e</em>]</span> 4689 1.1 mbalmer <pre>void lua_pop (lua_State *L, int n);</pre> 4690 1.1 mbalmer 4691 1.1 mbalmer <p> 4692 1.1 mbalmer Pops <code>n</code> elements from the stack. 4693 1.9 nikita It is implemented as a macro over <a href="#lua_settop"><code>lua_settop</code></a>. 4694 1.1 mbalmer 4695 1.1 mbalmer 4696 1.1 mbalmer 4697 1.1 mbalmer 4698 1.1 mbalmer 4699 1.1 mbalmer <hr><h3><a name="lua_pushboolean"><code>lua_pushboolean</code></a></h3><p> 4700 1.2 lneto <span class="apii">[-0, +1, –]</span> 4701 1.1 mbalmer <pre>void lua_pushboolean (lua_State *L, int b);</pre> 4702 1.1 mbalmer 4703 1.1 mbalmer <p> 4704 1.1 mbalmer Pushes a boolean value with value <code>b</code> onto the stack. 4705 1.1 mbalmer 4706 1.1 mbalmer 4707 1.1 mbalmer 4708 1.1 mbalmer 4709 1.1 mbalmer 4710 1.1 mbalmer <hr><h3><a name="lua_pushcclosure"><code>lua_pushcclosure</code></a></h3><p> 4711 1.5 lneto <span class="apii">[-n, +1, <em>m</em>]</span> 4712 1.1 mbalmer <pre>void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);</pre> 4713 1.1 mbalmer 4714 1.1 mbalmer <p> 4715 1.1 mbalmer Pushes a new C closure onto the stack. 4716 1.9 nikita This function receives a pointer to a C function 4717 1.9 nikita and pushes onto the stack a Lua value of type <code>function</code> that, 4718 1.9 nikita when called, invokes the corresponding C function. 4719 1.9 nikita The parameter <code>n</code> tells how many upvalues this function will have 4720 1.9 nikita (see <a href="#4.2">§4.2</a>). 4721 1.9 nikita 4722 1.9 nikita 4723 1.9 nikita <p> 4724 1.9 nikita Any function to be callable by Lua must 4725 1.9 nikita follow the correct protocol to receive its parameters 4726 1.9 nikita and return its results (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 4727 1.1 mbalmer 4728 1.1 mbalmer 4729 1.1 mbalmer <p> 4730 1.1 mbalmer When a C function is created, 4731 1.1 mbalmer it is possible to associate some values with it, 4732 1.9 nikita the so called upvalues; 4733 1.9 nikita these upvalues are then accessible to the function whenever it is called. 4734 1.9 nikita This association is called a C closure (see <a href="#4.2">§4.2</a>). 4735 1.9 nikita To create a C closure, 4736 1.9 nikita first the initial values for its upvalues must be pushed onto the stack. 4737 1.9 nikita (When there are multiple upvalues, the first value is pushed first.) 4738 1.1 mbalmer Then <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> 4739 1.1 mbalmer is called to create and push the C function onto the stack, 4740 1.2 lneto with the argument <code>n</code> telling how many values will be 4741 1.1 mbalmer associated with the function. 4742 1.1 mbalmer <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> also pops these values from the stack. 4743 1.1 mbalmer 4744 1.1 mbalmer 4745 1.1 mbalmer <p> 4746 1.1 mbalmer The maximum value for <code>n</code> is 255. 4747 1.1 mbalmer 4748 1.1 mbalmer 4749 1.2 lneto <p> 4750 1.2 lneto When <code>n</code> is zero, 4751 1.7 mbalmer this function creates a <em>light C function</em>, 4752 1.2 lneto which is just a pointer to the C function. 4753 1.2 lneto In that case, it never raises a memory error. 4754 1.2 lneto 4755 1.2 lneto 4756 1.1 mbalmer 4757 1.1 mbalmer 4758 1.1 mbalmer 4759 1.1 mbalmer <hr><h3><a name="lua_pushcfunction"><code>lua_pushcfunction</code></a></h3><p> 4760 1.2 lneto <span class="apii">[-0, +1, –]</span> 4761 1.1 mbalmer <pre>void lua_pushcfunction (lua_State *L, lua_CFunction f);</pre> 4762 1.1 mbalmer 4763 1.1 mbalmer <p> 4764 1.1 mbalmer Pushes a C function onto the stack. 4765 1.9 nikita This function is equivalent to <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> with no upvalues. 4766 1.1 mbalmer 4767 1.1 mbalmer 4768 1.1 mbalmer 4769 1.1 mbalmer 4770 1.1 mbalmer 4771 1.1 mbalmer <hr><h3><a name="lua_pushfstring"><code>lua_pushfstring</code></a></h3><p> 4772 1.9 nikita <span class="apii">[-0, +1, <em>v</em>]</span> 4773 1.1 mbalmer <pre>const char *lua_pushfstring (lua_State *L, const char *fmt, ...);</pre> 4774 1.1 mbalmer 4775 1.1 mbalmer <p> 4776 1.1 mbalmer Pushes onto the stack a formatted string 4777 1.9 nikita and returns a pointer to this string (see <a href="#4.1.3">§4.1.3</a>). 4778 1.3 lneto It is similar to the ISO C function <code>sprintf</code>, 4779 1.9 nikita but has two important differences. 4780 1.9 nikita First, 4781 1.9 nikita you do not have to allocate space for the result; 4782 1.1 mbalmer the result is a Lua string and Lua takes care of memory allocation 4783 1.1 mbalmer (and deallocation, through garbage collection). 4784 1.9 nikita Second, 4785 1.9 nikita the conversion specifiers are quite restricted. 4786 1.1 mbalmer There are no flags, widths, or precisions. 4787 1.1 mbalmer The conversion specifiers can only be 4788 1.2 lneto '<code>%%</code>' (inserts the character '<code>%</code>'), 4789 1.1 mbalmer '<code>%s</code>' (inserts a zero-terminated string, with no size restrictions), 4790 1.1 mbalmer '<code>%f</code>' (inserts a <a href="#lua_Number"><code>lua_Number</code></a>), 4791 1.4 mbalmer '<code>%I</code>' (inserts a <a href="#lua_Integer"><code>lua_Integer</code></a>), 4792 1.9 nikita '<code>%p</code>' (inserts a pointer), 4793 1.2 lneto '<code>%d</code>' (inserts an <code>int</code>), 4794 1.2 lneto '<code>%c</code>' (inserts an <code>int</code> as a one-byte character), and 4795 1.3 lneto '<code>%U</code>' (inserts a <code>long int</code> as a UTF-8 byte sequence). 4796 1.1 mbalmer 4797 1.1 mbalmer 4798 1.6 salazar <p> 4799 1.9 nikita This function may raise errors due to memory overflow 4800 1.9 nikita or an invalid conversion specifier. 4801 1.6 salazar 4802 1.6 salazar 4803 1.1 mbalmer 4804 1.1 mbalmer 4805 1.1 mbalmer 4806 1.2 lneto <hr><h3><a name="lua_pushglobaltable"><code>lua_pushglobaltable</code></a></h3><p> 4807 1.2 lneto <span class="apii">[-0, +1, –]</span> 4808 1.2 lneto <pre>void lua_pushglobaltable (lua_State *L);</pre> 4809 1.2 lneto 4810 1.2 lneto <p> 4811 1.2 lneto Pushes the global environment onto the stack. 4812 1.2 lneto 4813 1.2 lneto 4814 1.2 lneto 4815 1.2 lneto 4816 1.2 lneto 4817 1.1 mbalmer <hr><h3><a name="lua_pushinteger"><code>lua_pushinteger</code></a></h3><p> 4818 1.2 lneto <span class="apii">[-0, +1, –]</span> 4819 1.1 mbalmer <pre>void lua_pushinteger (lua_State *L, lua_Integer n);</pre> 4820 1.1 mbalmer 4821 1.1 mbalmer <p> 4822 1.2 lneto Pushes an integer with value <code>n</code> onto the stack. 4823 1.1 mbalmer 4824 1.1 mbalmer 4825 1.1 mbalmer 4826 1.1 mbalmer 4827 1.1 mbalmer 4828 1.1 mbalmer <hr><h3><a name="lua_pushlightuserdata"><code>lua_pushlightuserdata</code></a></h3><p> 4829 1.2 lneto <span class="apii">[-0, +1, –]</span> 4830 1.1 mbalmer <pre>void lua_pushlightuserdata (lua_State *L, void *p);</pre> 4831 1.1 mbalmer 4832 1.1 mbalmer <p> 4833 1.1 mbalmer Pushes a light userdata onto the stack. 4834 1.1 mbalmer 4835 1.1 mbalmer 4836 1.1 mbalmer <p> 4837 1.1 mbalmer Userdata represent C values in Lua. 4838 1.2 lneto A <em>light userdata</em> represents a pointer, a <code>void*</code>. 4839 1.1 mbalmer It is a value (like a number): 4840 1.1 mbalmer you do not create it, it has no individual metatable, 4841 1.1 mbalmer and it is not collected (as it was never created). 4842 1.1 mbalmer A light userdata is equal to "any" 4843 1.1 mbalmer light userdata with the same C address. 4844 1.1 mbalmer 4845 1.1 mbalmer 4846 1.1 mbalmer 4847 1.1 mbalmer 4848 1.1 mbalmer 4849 1.1 mbalmer <hr><h3><a name="lua_pushliteral"><code>lua_pushliteral</code></a></h3><p> 4850 1.5 lneto <span class="apii">[-0, +1, <em>m</em>]</span> 4851 1.2 lneto <pre>const char *lua_pushliteral (lua_State *L, const char *s);</pre> 4852 1.1 mbalmer 4853 1.1 mbalmer <p> 4854 1.4 mbalmer This macro is equivalent to <a href="#lua_pushstring"><code>lua_pushstring</code></a>, 4855 1.4 mbalmer but should be used only when <code>s</code> is a literal string. 4856 1.9 nikita (Lua may optimize this case.) 4857 1.1 mbalmer 4858 1.1 mbalmer 4859 1.1 mbalmer 4860 1.1 mbalmer 4861 1.1 mbalmer 4862 1.1 mbalmer <hr><h3><a name="lua_pushlstring"><code>lua_pushlstring</code></a></h3><p> 4863 1.5 lneto <span class="apii">[-0, +1, <em>m</em>]</span> 4864 1.2 lneto <pre>const char *lua_pushlstring (lua_State *L, const char *s, size_t len);</pre> 4865 1.1 mbalmer 4866 1.1 mbalmer <p> 4867 1.1 mbalmer Pushes the string pointed to by <code>s</code> with size <code>len</code> 4868 1.1 mbalmer onto the stack. 4869 1.9 nikita Lua will make or reuse an internal copy of the given string, 4870 1.1 mbalmer so the memory at <code>s</code> can be freed or reused immediately after 4871 1.1 mbalmer the function returns. 4872 1.2 lneto The string can contain any binary data, 4873 1.2 lneto including embedded zeros. 4874 1.2 lneto 4875 1.2 lneto 4876 1.2 lneto <p> 4877 1.9 nikita Returns a pointer to the internal copy of the string (see <a href="#4.1.3">§4.1.3</a>). 4878 1.1 mbalmer 4879 1.1 mbalmer 4880 1.1 mbalmer 4881 1.1 mbalmer 4882 1.1 mbalmer 4883 1.1 mbalmer <hr><h3><a name="lua_pushnil"><code>lua_pushnil</code></a></h3><p> 4884 1.2 lneto <span class="apii">[-0, +1, –]</span> 4885 1.1 mbalmer <pre>void lua_pushnil (lua_State *L);</pre> 4886 1.1 mbalmer 4887 1.1 mbalmer <p> 4888 1.1 mbalmer Pushes a nil value onto the stack. 4889 1.1 mbalmer 4890 1.1 mbalmer 4891 1.1 mbalmer 4892 1.1 mbalmer 4893 1.1 mbalmer 4894 1.1 mbalmer <hr><h3><a name="lua_pushnumber"><code>lua_pushnumber</code></a></h3><p> 4895 1.2 lneto <span class="apii">[-0, +1, –]</span> 4896 1.1 mbalmer <pre>void lua_pushnumber (lua_State *L, lua_Number n);</pre> 4897 1.1 mbalmer 4898 1.1 mbalmer <p> 4899 1.2 lneto Pushes a float with value <code>n</code> onto the stack. 4900 1.1 mbalmer 4901 1.1 mbalmer 4902 1.1 mbalmer 4903 1.1 mbalmer 4904 1.1 mbalmer 4905 1.1 mbalmer <hr><h3><a name="lua_pushstring"><code>lua_pushstring</code></a></h3><p> 4906 1.5 lneto <span class="apii">[-0, +1, <em>m</em>]</span> 4907 1.2 lneto <pre>const char *lua_pushstring (lua_State *L, const char *s);</pre> 4908 1.1 mbalmer 4909 1.1 mbalmer <p> 4910 1.1 mbalmer Pushes the zero-terminated string pointed to by <code>s</code> 4911 1.1 mbalmer onto the stack. 4912 1.9 nikita Lua will make or reuse an internal copy of the given string, 4913 1.1 mbalmer so the memory at <code>s</code> can be freed or reused immediately after 4914 1.1 mbalmer the function returns. 4915 1.2 lneto 4916 1.2 lneto 4917 1.2 lneto <p> 4918 1.9 nikita Returns a pointer to the internal copy of the string (see <a href="#4.1.3">§4.1.3</a>). 4919 1.2 lneto 4920 1.2 lneto 4921 1.2 lneto <p> 4922 1.2 lneto If <code>s</code> is <code>NULL</code>, pushes <b>nil</b> and returns <code>NULL</code>. 4923 1.1 mbalmer 4924 1.1 mbalmer 4925 1.1 mbalmer 4926 1.1 mbalmer 4927 1.1 mbalmer 4928 1.1 mbalmer <hr><h3><a name="lua_pushthread"><code>lua_pushthread</code></a></h3><p> 4929 1.2 lneto <span class="apii">[-0, +1, –]</span> 4930 1.1 mbalmer <pre>int lua_pushthread (lua_State *L);</pre> 4931 1.1 mbalmer 4932 1.1 mbalmer <p> 4933 1.1 mbalmer Pushes the thread represented by <code>L</code> onto the stack. 4934 1.1 mbalmer Returns 1 if this thread is the main thread of its state. 4935 1.1 mbalmer 4936 1.1 mbalmer 4937 1.1 mbalmer 4938 1.1 mbalmer 4939 1.1 mbalmer 4940 1.1 mbalmer <hr><h3><a name="lua_pushvalue"><code>lua_pushvalue</code></a></h3><p> 4941 1.2 lneto <span class="apii">[-0, +1, –]</span> 4942 1.1 mbalmer <pre>void lua_pushvalue (lua_State *L, int index);</pre> 4943 1.1 mbalmer 4944 1.1 mbalmer <p> 4945 1.2 lneto Pushes a copy of the element at the given index 4946 1.1 mbalmer onto the stack. 4947 1.1 mbalmer 4948 1.1 mbalmer 4949 1.1 mbalmer 4950 1.1 mbalmer 4951 1.1 mbalmer 4952 1.1 mbalmer <hr><h3><a name="lua_pushvfstring"><code>lua_pushvfstring</code></a></h3><p> 4953 1.9 nikita <span class="apii">[-0, +1, <em>v</em>]</span> 4954 1.1 mbalmer <pre>const char *lua_pushvfstring (lua_State *L, 4955 1.1 mbalmer const char *fmt, 4956 1.1 mbalmer va_list argp);</pre> 4957 1.1 mbalmer 4958 1.1 mbalmer <p> 4959 1.1 mbalmer Equivalent to <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>, except that it receives a <code>va_list</code> 4960 1.1 mbalmer instead of a variable number of arguments. 4961 1.1 mbalmer 4962 1.1 mbalmer 4963 1.1 mbalmer 4964 1.1 mbalmer 4965 1.1 mbalmer 4966 1.1 mbalmer <hr><h3><a name="lua_rawequal"><code>lua_rawequal</code></a></h3><p> 4967 1.2 lneto <span class="apii">[-0, +0, –]</span> 4968 1.1 mbalmer <pre>int lua_rawequal (lua_State *L, int index1, int index2);</pre> 4969 1.1 mbalmer 4970 1.1 mbalmer <p> 4971 1.2 lneto Returns 1 if the two values in indices <code>index1</code> and 4972 1.1 mbalmer <code>index2</code> are primitively equal 4973 1.9 nikita (that is, equal without calling the <code>__eq</code> metamethod). 4974 1.1 mbalmer Otherwise returns 0. 4975 1.3 lneto Also returns 0 if any of the indices are not valid. 4976 1.1 mbalmer 4977 1.1 mbalmer 4978 1.1 mbalmer 4979 1.1 mbalmer 4980 1.1 mbalmer 4981 1.1 mbalmer <hr><h3><a name="lua_rawget"><code>lua_rawget</code></a></h3><p> 4982 1.2 lneto <span class="apii">[-1, +1, –]</span> 4983 1.2 lneto <pre>int lua_rawget (lua_State *L, int index);</pre> 4984 1.1 mbalmer 4985 1.1 mbalmer <p> 4986 1.1 mbalmer Similar to <a href="#lua_gettable"><code>lua_gettable</code></a>, but does a raw access 4987 1.1 mbalmer (i.e., without metamethods). 4988 1.1 mbalmer 4989 1.1 mbalmer 4990 1.1 mbalmer 4991 1.1 mbalmer 4992 1.1 mbalmer 4993 1.2 lneto <hr><h3><a name="lua_rawgeti"><code>lua_rawgeti</code></a></h3><p> 4994 1.2 lneto <span class="apii">[-0, +1, –]</span> 4995 1.2 lneto <pre>int lua_rawgeti (lua_State *L, int index, lua_Integer n);</pre> 4996 1.2 lneto 4997 1.2 lneto <p> 4998 1.2 lneto Pushes onto the stack the value <code>t[n]</code>, 4999 1.2 lneto where <code>t</code> is the table at the given index. 5000 1.6 salazar The access is raw, 5001 1.9 nikita that is, it does not use the <code>__index</code> metavalue. 5002 1.2 lneto 5003 1.2 lneto 5004 1.2 lneto <p> 5005 1.2 lneto Returns the type of the pushed value. 5006 1.2 lneto 5007 1.2 lneto 5008 1.2 lneto 5009 1.2 lneto 5010 1.2 lneto 5011 1.2 lneto <hr><h3><a name="lua_rawgetp"><code>lua_rawgetp</code></a></h3><p> 5012 1.2 lneto <span class="apii">[-0, +1, –]</span> 5013 1.2 lneto <pre>int lua_rawgetp (lua_State *L, int index, const void *p);</pre> 5014 1.2 lneto 5015 1.2 lneto <p> 5016 1.2 lneto Pushes onto the stack the value <code>t[k]</code>, 5017 1.2 lneto where <code>t</code> is the table at the given index and 5018 1.2 lneto <code>k</code> is the pointer <code>p</code> represented as a light userdata. 5019 1.2 lneto The access is raw; 5020 1.9 nikita that is, it does not use the <code>__index</code> metavalue. 5021 1.2 lneto 5022 1.2 lneto 5023 1.2 lneto <p> 5024 1.2 lneto Returns the type of the pushed value. 5025 1.2 lneto 5026 1.2 lneto 5027 1.2 lneto 5028 1.2 lneto 5029 1.2 lneto 5030 1.2 lneto <hr><h3><a name="lua_rawlen"><code>lua_rawlen</code></a></h3><p> 5031 1.2 lneto <span class="apii">[-0, +0, –]</span> 5032 1.9 nikita <pre>lua_Unsigned lua_rawlen (lua_State *L, int index);</pre> 5033 1.2 lneto 5034 1.2 lneto <p> 5035 1.2 lneto Returns the raw "length" of the value at the given index: 5036 1.2 lneto for strings, this is the string length; 5037 1.2 lneto for tables, this is the result of the length operator ('<code>#</code>') 5038 1.2 lneto with no metamethods; 5039 1.2 lneto for userdata, this is the size of the block of memory allocated 5040 1.9 nikita for the userdata. 5041 1.9 nikita For other values, this call returns 0. 5042 1.1 mbalmer 5043 1.1 mbalmer 5044 1.1 mbalmer 5045 1.1 mbalmer 5046 1.1 mbalmer 5047 1.1 mbalmer <hr><h3><a name="lua_rawset"><code>lua_rawset</code></a></h3><p> 5048 1.5 lneto <span class="apii">[-2, +0, <em>m</em>]</span> 5049 1.1 mbalmer <pre>void lua_rawset (lua_State *L, int index);</pre> 5050 1.1 mbalmer 5051 1.1 mbalmer <p> 5052 1.1 mbalmer Similar to <a href="#lua_settable"><code>lua_settable</code></a>, but does a raw assignment 5053 1.1 mbalmer (i.e., without metamethods). 5054 1.1 mbalmer 5055 1.1 mbalmer 5056 1.1 mbalmer 5057 1.1 mbalmer 5058 1.1 mbalmer 5059 1.1 mbalmer <hr><h3><a name="lua_rawseti"><code>lua_rawseti</code></a></h3><p> 5060 1.5 lneto <span class="apii">[-1, +0, <em>m</em>]</span> 5061 1.3 lneto <pre>void lua_rawseti (lua_State *L, int index, lua_Integer i);</pre> 5062 1.1 mbalmer 5063 1.1 mbalmer <p> 5064 1.3 lneto Does the equivalent of <code>t[i] = v</code>, 5065 1.2 lneto where <code>t</code> is the table at the given index 5066 1.9 nikita and <code>v</code> is the value on the top of the stack. 5067 1.2 lneto 5068 1.2 lneto 5069 1.2 lneto <p> 5070 1.2 lneto This function pops the value from the stack. 5071 1.6 salazar The assignment is raw, 5072 1.9 nikita that is, it does not use the <code>__newindex</code> metavalue. 5073 1.2 lneto 5074 1.2 lneto 5075 1.2 lneto 5076 1.2 lneto 5077 1.2 lneto 5078 1.2 lneto <hr><h3><a name="lua_rawsetp"><code>lua_rawsetp</code></a></h3><p> 5079 1.5 lneto <span class="apii">[-1, +0, <em>m</em>]</span> 5080 1.2 lneto <pre>void lua_rawsetp (lua_State *L, int index, const void *p);</pre> 5081 1.2 lneto 5082 1.2 lneto <p> 5083 1.4 mbalmer Does the equivalent of <code>t[p] = v</code>, 5084 1.2 lneto where <code>t</code> is the table at the given index, 5085 1.4 mbalmer <code>p</code> is encoded as a light userdata, 5086 1.9 nikita and <code>v</code> is the value on the top of the stack. 5087 1.1 mbalmer 5088 1.1 mbalmer 5089 1.1 mbalmer <p> 5090 1.1 mbalmer This function pops the value from the stack. 5091 1.6 salazar The assignment is raw, 5092 1.9 nikita that is, it does not use the <code>__newindex</code> metavalue. 5093 1.1 mbalmer 5094 1.1 mbalmer 5095 1.1 mbalmer 5096 1.1 mbalmer 5097 1.1 mbalmer 5098 1.1 mbalmer <hr><h3><a name="lua_Reader"><code>lua_Reader</code></a></h3> 5099 1.1 mbalmer <pre>typedef const char * (*lua_Reader) (lua_State *L, 5100 1.1 mbalmer void *data, 5101 1.1 mbalmer size_t *size);</pre> 5102 1.1 mbalmer 5103 1.1 mbalmer <p> 5104 1.1 mbalmer The reader function used by <a href="#lua_load"><code>lua_load</code></a>. 5105 1.9 nikita Every time <a href="#lua_load"><code>lua_load</code></a> needs another piece of the chunk, 5106 1.9 nikita it calls the reader, 5107 1.1 mbalmer passing along its <code>data</code> parameter. 5108 1.1 mbalmer The reader must return a pointer to a block of memory 5109 1.1 mbalmer with a new piece of the chunk 5110 1.1 mbalmer and set <code>size</code> to the block size. 5111 1.1 mbalmer The block must exist until the reader function is called again. 5112 1.1 mbalmer To signal the end of the chunk, 5113 1.1 mbalmer the reader must return <code>NULL</code> or set <code>size</code> to zero. 5114 1.1 mbalmer The reader function may return pieces of any size greater than zero. 5115 1.1 mbalmer 5116 1.1 mbalmer 5117 1.1 mbalmer 5118 1.1 mbalmer 5119 1.1 mbalmer 5120 1.1 mbalmer <hr><h3><a name="lua_register"><code>lua_register</code></a></h3><p> 5121 1.1 mbalmer <span class="apii">[-0, +0, <em>e</em>]</span> 5122 1.2 lneto <pre>void lua_register (lua_State *L, const char *name, lua_CFunction f);</pre> 5123 1.1 mbalmer 5124 1.1 mbalmer <p> 5125 1.7 mbalmer Sets the C function <code>f</code> as the new value of global <code>name</code>. 5126 1.1 mbalmer It is defined as a macro: 5127 1.1 mbalmer 5128 1.1 mbalmer <pre> 5129 1.1 mbalmer #define lua_register(L,n,f) \ 5130 1.1 mbalmer (lua_pushcfunction(L, f), lua_setglobal(L, n)) 5131 1.1 mbalmer </pre> 5132 1.1 mbalmer 5133 1.1 mbalmer 5134 1.1 mbalmer 5135 1.1 mbalmer 5136 1.1 mbalmer <hr><h3><a name="lua_remove"><code>lua_remove</code></a></h3><p> 5137 1.2 lneto <span class="apii">[-1, +0, –]</span> 5138 1.1 mbalmer <pre>void lua_remove (lua_State *L, int index);</pre> 5139 1.1 mbalmer 5140 1.1 mbalmer <p> 5141 1.1 mbalmer Removes the element at the given valid index, 5142 1.1 mbalmer shifting down the elements above this index to fill the gap. 5143 1.2 lneto This function cannot be called with a pseudo-index, 5144 1.1 mbalmer because a pseudo-index is not an actual stack position. 5145 1.1 mbalmer 5146 1.1 mbalmer 5147 1.1 mbalmer 5148 1.1 mbalmer 5149 1.1 mbalmer 5150 1.1 mbalmer <hr><h3><a name="lua_replace"><code>lua_replace</code></a></h3><p> 5151 1.2 lneto <span class="apii">[-1, +0, –]</span> 5152 1.1 mbalmer <pre>void lua_replace (lua_State *L, int index);</pre> 5153 1.1 mbalmer 5154 1.1 mbalmer <p> 5155 1.2 lneto Moves the top element into the given valid index 5156 1.1 mbalmer without shifting any element 5157 1.4 mbalmer (therefore replacing the value at that given index), 5158 1.2 lneto and then pops the top element. 5159 1.1 mbalmer 5160 1.1 mbalmer 5161 1.1 mbalmer 5162 1.1 mbalmer 5163 1.1 mbalmer 5164 1.9 nikita <hr><h3><a name="lua_resetthread"><code>lua_resetthread</code></a></h3><p> 5165 1.9 nikita <span class="apii">[-0, +?, –]</span> 5166 1.9 nikita <pre>int lua_resetthread (lua_State *L);</pre> 5167 1.9 nikita 5168 1.9 nikita <p> 5169 1.9 nikita Resets a thread, cleaning its call stack and closing all pending 5170 1.9 nikita to-be-closed variables. 5171 1.9 nikita Returns a status code: 5172 1.9 nikita <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> for no errors in the thread 5173 1.9 nikita (either the original error that stopped the thread or 5174 1.9 nikita errors in closing methods), 5175 1.9 nikita or an error status otherwise. 5176 1.9 nikita In case of error, 5177 1.9 nikita leaves the error object on the top of the stack. 5178 1.9 nikita 5179 1.9 nikita 5180 1.9 nikita 5181 1.9 nikita 5182 1.9 nikita 5183 1.1 mbalmer <hr><h3><a name="lua_resume"><code>lua_resume</code></a></h3><p> 5184 1.2 lneto <span class="apii">[-?, +?, –]</span> 5185 1.9 nikita <pre>int lua_resume (lua_State *L, lua_State *from, int nargs, 5186 1.9 nikita int *nresults);</pre> 5187 1.1 mbalmer 5188 1.1 mbalmer <p> 5189 1.4 mbalmer Starts and resumes a coroutine in the given thread <code>L</code>. 5190 1.1 mbalmer 5191 1.1 mbalmer 5192 1.1 mbalmer <p> 5193 1.2 lneto To start a coroutine, 5194 1.9 nikita you push the main function plus any arguments 5195 1.9 nikita onto the empty stack of the thread. 5196 1.1 mbalmer then you call <a href="#lua_resume"><code>lua_resume</code></a>, 5197 1.2 lneto with <code>nargs</code> being the number of arguments. 5198 1.1 mbalmer This call returns when the coroutine suspends or finishes its execution. 5199 1.9 nikita When it returns, 5200 1.9 nikita <code>*nresults</code> is updated and 5201 1.9 nikita the top of the stack contains 5202 1.9 nikita the <code>*nresults</code> values passed to <a href="#lua_yield"><code>lua_yield</code></a> 5203 1.9 nikita or returned by the body function. 5204 1.1 mbalmer <a href="#lua_resume"><code>lua_resume</code></a> returns 5205 1.1 mbalmer <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the coroutine yields, 5206 1.2 lneto <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> if the coroutine finishes its execution 5207 1.1 mbalmer without errors, 5208 1.9 nikita or an error code in case of errors (see <a href="#4.4.1">§4.4.1</a>). 5209 1.1 mbalmer In case of errors, 5210 1.9 nikita the error object is on the top of the stack. 5211 1.2 lneto 5212 1.2 lneto 5213 1.2 lneto <p> 5214 1.2 lneto To resume a coroutine, 5215 1.9 nikita you remove the <code>*nresults</code> yielded values from its stack, 5216 1.9 nikita push the values to be passed as results from <code>yield</code>, 5217 1.1 mbalmer and then call <a href="#lua_resume"><code>lua_resume</code></a>. 5218 1.1 mbalmer 5219 1.1 mbalmer 5220 1.2 lneto <p> 5221 1.2 lneto The parameter <code>from</code> represents the coroutine that is resuming <code>L</code>. 5222 1.2 lneto If there is no such coroutine, 5223 1.2 lneto this parameter can be <code>NULL</code>. 5224 1.2 lneto 5225 1.2 lneto 5226 1.1 mbalmer 5227 1.1 mbalmer 5228 1.1 mbalmer 5229 1.2 lneto <hr><h3><a name="lua_rotate"><code>lua_rotate</code></a></h3><p> 5230 1.2 lneto <span class="apii">[-0, +0, –]</span> 5231 1.2 lneto <pre>void lua_rotate (lua_State *L, int idx, int n);</pre> 5232 1.1 mbalmer 5233 1.1 mbalmer <p> 5234 1.4 mbalmer Rotates the stack elements between the valid index <code>idx</code> 5235 1.4 mbalmer and the top of the stack. 5236 1.4 mbalmer The elements are rotated <code>n</code> positions in the direction of the top, 5237 1.4 mbalmer for a positive <code>n</code>, 5238 1.2 lneto or <code>-n</code> positions in the direction of the bottom, 5239 1.2 lneto for a negative <code>n</code>. 5240 1.2 lneto The absolute value of <code>n</code> must not be greater than the size 5241 1.2 lneto of the slice being rotated. 5242 1.4 mbalmer This function cannot be called with a pseudo-index, 5243 1.4 mbalmer because a pseudo-index is not an actual stack position. 5244 1.1 mbalmer 5245 1.1 mbalmer 5246 1.1 mbalmer 5247 1.1 mbalmer 5248 1.1 mbalmer 5249 1.2 lneto <hr><h3><a name="lua_setallocf"><code>lua_setallocf</code></a></h3><p> 5250 1.2 lneto <span class="apii">[-0, +0, –]</span> 5251 1.2 lneto <pre>void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);</pre> 5252 1.1 mbalmer 5253 1.1 mbalmer <p> 5254 1.2 lneto Changes the allocator function of a given state to <code>f</code> 5255 1.2 lneto with user data <code>ud</code>. 5256 1.1 mbalmer 5257 1.1 mbalmer 5258 1.1 mbalmer 5259 1.1 mbalmer 5260 1.1 mbalmer 5261 1.1 mbalmer <hr><h3><a name="lua_setfield"><code>lua_setfield</code></a></h3><p> 5262 1.1 mbalmer <span class="apii">[-1, +0, <em>e</em>]</span> 5263 1.1 mbalmer <pre>void lua_setfield (lua_State *L, int index, const char *k);</pre> 5264 1.1 mbalmer 5265 1.1 mbalmer <p> 5266 1.1 mbalmer Does the equivalent to <code>t[k] = v</code>, 5267 1.2 lneto where <code>t</code> is the value at the given index 5268 1.9 nikita and <code>v</code> is the value on the top of the stack. 5269 1.1 mbalmer 5270 1.1 mbalmer 5271 1.1 mbalmer <p> 5272 1.1 mbalmer This function pops the value from the stack. 5273 1.1 mbalmer As in Lua, this function may trigger a metamethod 5274 1.2 lneto for the "newindex" event (see <a href="#2.4">§2.4</a>). 5275 1.1 mbalmer 5276 1.1 mbalmer 5277 1.1 mbalmer 5278 1.1 mbalmer 5279 1.1 mbalmer 5280 1.1 mbalmer <hr><h3><a name="lua_setglobal"><code>lua_setglobal</code></a></h3><p> 5281 1.1 mbalmer <span class="apii">[-1, +0, <em>e</em>]</span> 5282 1.1 mbalmer <pre>void lua_setglobal (lua_State *L, const char *name);</pre> 5283 1.1 mbalmer 5284 1.1 mbalmer <p> 5285 1.1 mbalmer Pops a value from the stack and 5286 1.1 mbalmer sets it as the new value of global <code>name</code>. 5287 1.1 mbalmer 5288 1.1 mbalmer 5289 1.1 mbalmer 5290 1.1 mbalmer 5291 1.1 mbalmer 5292 1.3 lneto <hr><h3><a name="lua_seti"><code>lua_seti</code></a></h3><p> 5293 1.3 lneto <span class="apii">[-1, +0, <em>e</em>]</span> 5294 1.3 lneto <pre>void lua_seti (lua_State *L, int index, lua_Integer n);</pre> 5295 1.3 lneto 5296 1.3 lneto <p> 5297 1.3 lneto Does the equivalent to <code>t[n] = v</code>, 5298 1.3 lneto where <code>t</code> is the value at the given index 5299 1.9 nikita and <code>v</code> is the value on the top of the stack. 5300 1.3 lneto 5301 1.3 lneto 5302 1.3 lneto <p> 5303 1.3 lneto This function pops the value from the stack. 5304 1.3 lneto As in Lua, this function may trigger a metamethod 5305 1.3 lneto for the "newindex" event (see <a href="#2.4">§2.4</a>). 5306 1.3 lneto 5307 1.3 lneto 5308 1.3 lneto 5309 1.3 lneto 5310 1.3 lneto 5311 1.9 nikita <hr><h3><a name="lua_setiuservalue"><code>lua_setiuservalue</code></a></h3><p> 5312 1.9 nikita <span class="apii">[-1, +0, –]</span> 5313 1.9 nikita <pre>int lua_setiuservalue (lua_State *L, int index, int n);</pre> 5314 1.9 nikita 5315 1.9 nikita <p> 5316 1.9 nikita Pops a value from the stack and sets it as 5317 1.9 nikita the new <code>n</code>-th user value associated to the 5318 1.9 nikita full userdata at the given index. 5319 1.9 nikita Returns 0 if the userdata does not have that value. 5320 1.9 nikita 5321 1.9 nikita 5322 1.9 nikita 5323 1.9 nikita 5324 1.9 nikita 5325 1.1 mbalmer <hr><h3><a name="lua_setmetatable"><code>lua_setmetatable</code></a></h3><p> 5326 1.2 lneto <span class="apii">[-1, +0, –]</span> 5327 1.9 nikita <pre>int lua_setmetatable (lua_State *L, int index);</pre> 5328 1.9 nikita 5329 1.9 nikita <p> 5330 1.9 nikita Pops a table or <b>nil</b> from the stack and 5331 1.9 nikita sets that value as the new metatable for the value at the given index. 5332 1.9 nikita (<b>nil</b> means no metatable.) 5333 1.9 nikita 5334 1.1 mbalmer 5335 1.1 mbalmer <p> 5336 1.9 nikita (For historical reasons, this function returns an <code>int</code>, 5337 1.9 nikita which now is always 1.) 5338 1.1 mbalmer 5339 1.1 mbalmer 5340 1.1 mbalmer 5341 1.1 mbalmer 5342 1.1 mbalmer 5343 1.1 mbalmer <hr><h3><a name="lua_settable"><code>lua_settable</code></a></h3><p> 5344 1.1 mbalmer <span class="apii">[-2, +0, <em>e</em>]</span> 5345 1.1 mbalmer <pre>void lua_settable (lua_State *L, int index);</pre> 5346 1.1 mbalmer 5347 1.1 mbalmer <p> 5348 1.1 mbalmer Does the equivalent to <code>t[k] = v</code>, 5349 1.2 lneto where <code>t</code> is the value at the given index, 5350 1.9 nikita <code>v</code> is the value on the top of the stack, 5351 1.1 mbalmer and <code>k</code> is the value just below the top. 5352 1.1 mbalmer 5353 1.1 mbalmer 5354 1.1 mbalmer <p> 5355 1.1 mbalmer This function pops both the key and the value from the stack. 5356 1.1 mbalmer As in Lua, this function may trigger a metamethod 5357 1.2 lneto for the "newindex" event (see <a href="#2.4">§2.4</a>). 5358 1.1 mbalmer 5359 1.1 mbalmer 5360 1.1 mbalmer 5361 1.1 mbalmer 5362 1.1 mbalmer 5363 1.1 mbalmer <hr><h3><a name="lua_settop"><code>lua_settop</code></a></h3><p> 5364 1.9 nikita <span class="apii">[-?, +?, <em>e</em>]</span> 5365 1.1 mbalmer <pre>void lua_settop (lua_State *L, int index);</pre> 5366 1.1 mbalmer 5367 1.1 mbalmer <p> 5368 1.2 lneto Accepts any index, or 0, 5369 1.1 mbalmer and sets the stack top to this index. 5370 1.9 nikita If the new top is greater than the old one, 5371 1.1 mbalmer then the new elements are filled with <b>nil</b>. 5372 1.1 mbalmer If <code>index</code> is 0, then all stack elements are removed. 5373 1.1 mbalmer 5374 1.1 mbalmer 5375 1.9 nikita <p> 5376 1.9 nikita This function can run arbitrary code when removing an index 5377 1.9 nikita marked as to-be-closed from the stack. 5378 1.9 nikita 5379 1.1 mbalmer 5380 1.1 mbalmer 5381 1.1 mbalmer 5382 1.9 nikita 5383 1.9 nikita <hr><h3><a name="lua_setwarnf"><code>lua_setwarnf</code></a></h3><p> 5384 1.9 nikita <span class="apii">[-0, +0, –]</span> 5385 1.9 nikita <pre>void lua_setwarnf (lua_State *L, lua_WarnFunction f, void *ud);</pre> 5386 1.2 lneto 5387 1.2 lneto <p> 5388 1.9 nikita Sets the warning function to be used by Lua to emit warnings 5389 1.9 nikita (see <a href="#lua_WarnFunction"><code>lua_WarnFunction</code></a>). 5390 1.9 nikita The <code>ud</code> parameter sets the value <code>ud</code> passed to 5391 1.9 nikita the warning function. 5392 1.2 lneto 5393 1.2 lneto 5394 1.2 lneto 5395 1.2 lneto 5396 1.2 lneto 5397 1.1 mbalmer <hr><h3><a name="lua_State"><code>lua_State</code></a></h3> 5398 1.1 mbalmer <pre>typedef struct lua_State lua_State;</pre> 5399 1.1 mbalmer 5400 1.1 mbalmer <p> 5401 1.2 lneto An opaque structure that points to a thread and indirectly 5402 1.2 lneto (through the thread) to the whole state of a Lua interpreter. 5403 1.1 mbalmer The Lua library is fully reentrant: 5404 1.1 mbalmer it has no global variables. 5405 1.2 lneto All information about a state is accessible through this structure. 5406 1.1 mbalmer 5407 1.1 mbalmer 5408 1.1 mbalmer <p> 5409 1.2 lneto A pointer to this structure must be passed as the first argument to 5410 1.1 mbalmer every function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>, 5411 1.1 mbalmer which creates a Lua state from scratch. 5412 1.1 mbalmer 5413 1.1 mbalmer 5414 1.1 mbalmer 5415 1.1 mbalmer 5416 1.1 mbalmer 5417 1.1 mbalmer <hr><h3><a name="lua_status"><code>lua_status</code></a></h3><p> 5418 1.2 lneto <span class="apii">[-0, +0, –]</span> 5419 1.1 mbalmer <pre>int lua_status (lua_State *L);</pre> 5420 1.1 mbalmer 5421 1.1 mbalmer <p> 5422 1.1 mbalmer Returns the status of the thread <code>L</code>. 5423 1.1 mbalmer 5424 1.1 mbalmer 5425 1.1 mbalmer <p> 5426 1.9 nikita The status can be <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> for a normal thread, 5427 1.2 lneto an error code if the thread finished the execution 5428 1.2 lneto of a <a href="#lua_resume"><code>lua_resume</code></a> with an error, 5429 1.9 nikita or <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the thread is suspended. 5430 1.1 mbalmer 5431 1.1 mbalmer 5432 1.2 lneto <p> 5433 1.9 nikita You can call functions only in threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>. 5434 1.2 lneto You can resume threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> 5435 1.2 lneto (to start a new coroutine) or <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> 5436 1.2 lneto (to resume a coroutine). 5437 1.2 lneto 5438 1.2 lneto 5439 1.2 lneto 5440 1.2 lneto 5441 1.2 lneto 5442 1.3 lneto <hr><h3><a name="lua_stringtonumber"><code>lua_stringtonumber</code></a></h3><p> 5443 1.2 lneto <span class="apii">[-0, +1, –]</span> 5444 1.3 lneto <pre>size_t lua_stringtonumber (lua_State *L, const char *s);</pre> 5445 1.2 lneto 5446 1.2 lneto <p> 5447 1.2 lneto Converts the zero-terminated string <code>s</code> to a number, 5448 1.2 lneto pushes that number into the stack, 5449 1.3 lneto and returns the total size of the string, 5450 1.3 lneto that is, its length plus one. 5451 1.2 lneto The conversion can result in an integer or a float, 5452 1.2 lneto according to the lexical conventions of Lua (see <a href="#3.1">§3.1</a>). 5453 1.9 nikita The string may have leading and trailing whitespaces and a sign. 5454 1.2 lneto If the string is not a valid numeral, 5455 1.2 lneto returns 0 and pushes nothing. 5456 1.3 lneto (Note that the result can be used as a boolean, 5457 1.3 lneto true if the conversion succeeds.) 5458 1.2 lneto 5459 1.2 lneto 5460 1.1 mbalmer 5461 1.1 mbalmer 5462 1.1 mbalmer 5463 1.1 mbalmer <hr><h3><a name="lua_toboolean"><code>lua_toboolean</code></a></h3><p> 5464 1.2 lneto <span class="apii">[-0, +0, –]</span> 5465 1.1 mbalmer <pre>int lua_toboolean (lua_State *L, int index);</pre> 5466 1.1 mbalmer 5467 1.1 mbalmer <p> 5468 1.2 lneto Converts the Lua value at the given index to a C boolean 5469 1.1 mbalmer value (0 or 1). 5470 1.1 mbalmer Like all tests in Lua, 5471 1.2 lneto <a href="#lua_toboolean"><code>lua_toboolean</code></a> returns true for any Lua value 5472 1.1 mbalmer different from <b>false</b> and <b>nil</b>; 5473 1.2 lneto otherwise it returns false. 5474 1.1 mbalmer (If you want to accept only actual boolean values, 5475 1.1 mbalmer use <a href="#lua_isboolean"><code>lua_isboolean</code></a> to test the value's type.) 5476 1.1 mbalmer 5477 1.1 mbalmer 5478 1.1 mbalmer 5479 1.1 mbalmer 5480 1.1 mbalmer 5481 1.1 mbalmer <hr><h3><a name="lua_tocfunction"><code>lua_tocfunction</code></a></h3><p> 5482 1.2 lneto <span class="apii">[-0, +0, –]</span> 5483 1.1 mbalmer <pre>lua_CFunction lua_tocfunction (lua_State *L, int index);</pre> 5484 1.1 mbalmer 5485 1.1 mbalmer <p> 5486 1.2 lneto Converts a value at the given index to a C function. 5487 1.1 mbalmer That value must be a C function; 5488 1.1 mbalmer otherwise, returns <code>NULL</code>. 5489 1.1 mbalmer 5490 1.1 mbalmer 5491 1.1 mbalmer 5492 1.1 mbalmer 5493 1.1 mbalmer 5494 1.9 nikita <hr><h3><a name="lua_toclose"><code>lua_toclose</code></a></h3><p> 5495 1.9 nikita <span class="apii">[-0, +0, <em>m</em>]</span> 5496 1.9 nikita <pre>void lua_toclose (lua_State *L, int index);</pre> 5497 1.9 nikita 5498 1.9 nikita <p> 5499 1.9 nikita Marks the given index in the stack as a 5500 1.9 nikita to-be-closed slot (see <a href="#3.3.8">§3.3.8</a>). 5501 1.9 nikita Like a to-be-closed variable in Lua, 5502 1.9 nikita the value at that slot in the stack will be closed 5503 1.9 nikita when it goes out of scope. 5504 1.9 nikita Here, in the context of a C function, 5505 1.9 nikita to go out of scope means that the running function returns to Lua, 5506 1.9 nikita or there is an error, 5507 1.9 nikita or the slot is removed from the stack through 5508 1.9 nikita <a href="#lua_settop"><code>lua_settop</code></a> or <a href="#lua_pop"><code>lua_pop</code></a>, 5509 1.9 nikita or there is a call to <a href="#lua_closeslot"><code>lua_closeslot</code></a>. 5510 1.9 nikita A slot marked as to-be-closed should not be removed from the stack 5511 1.9 nikita by any other function in the API except <a href="#lua_settop"><code>lua_settop</code></a> or <a href="#lua_pop"><code>lua_pop</code></a>, 5512 1.9 nikita unless previously deactivated by <a href="#lua_closeslot"><code>lua_closeslot</code></a>. 5513 1.9 nikita 5514 1.9 nikita 5515 1.9 nikita <p> 5516 1.9 nikita This function should not be called for an index 5517 1.9 nikita that is equal to or below an active to-be-closed slot. 5518 1.9 nikita 5519 1.9 nikita 5520 1.9 nikita <p> 5521 1.9 nikita Note that, both in case of errors and of a regular return, 5522 1.9 nikita by the time the <code>__close</code> metamethod runs, 5523 1.9 nikita the C stack was already unwound, 5524 1.9 nikita so that any automatic C variable declared in the calling function 5525 1.9 nikita (e.g., a buffer) will be out of scope. 5526 1.9 nikita 5527 1.9 nikita 5528 1.9 nikita 5529 1.9 nikita 5530 1.9 nikita 5531 1.1 mbalmer <hr><h3><a name="lua_tointeger"><code>lua_tointeger</code></a></h3><p> 5532 1.2 lneto <span class="apii">[-0, +0, –]</span> 5533 1.1 mbalmer <pre>lua_Integer lua_tointeger (lua_State *L, int index);</pre> 5534 1.1 mbalmer 5535 1.1 mbalmer <p> 5536 1.2 lneto Equivalent to <a href="#lua_tointegerx"><code>lua_tointegerx</code></a> with <code>isnum</code> equal to <code>NULL</code>. 5537 1.2 lneto 5538 1.2 lneto 5539 1.2 lneto 5540 1.2 lneto 5541 1.2 lneto 5542 1.2 lneto <hr><h3><a name="lua_tointegerx"><code>lua_tointegerx</code></a></h3><p> 5543 1.2 lneto <span class="apii">[-0, +0, –]</span> 5544 1.2 lneto <pre>lua_Integer lua_tointegerx (lua_State *L, int index, int *isnum);</pre> 5545 1.2 lneto 5546 1.2 lneto <p> 5547 1.2 lneto Converts the Lua value at the given index 5548 1.1 mbalmer to the signed integral type <a href="#lua_Integer"><code>lua_Integer</code></a>. 5549 1.2 lneto The Lua value must be an integer, 5550 1.2 lneto or a number or string convertible to an integer (see <a href="#3.4.3">§3.4.3</a>); 5551 1.2 lneto otherwise, <code>lua_tointegerx</code> returns 0. 5552 1.1 mbalmer 5553 1.1 mbalmer 5554 1.1 mbalmer <p> 5555 1.2 lneto If <code>isnum</code> is not <code>NULL</code>, 5556 1.2 lneto its referent is assigned a boolean value that 5557 1.2 lneto indicates whether the operation succeeded. 5558 1.1 mbalmer 5559 1.1 mbalmer 5560 1.1 mbalmer 5561 1.1 mbalmer 5562 1.1 mbalmer 5563 1.1 mbalmer <hr><h3><a name="lua_tolstring"><code>lua_tolstring</code></a></h3><p> 5564 1.5 lneto <span class="apii">[-0, +0, <em>m</em>]</span> 5565 1.1 mbalmer <pre>const char *lua_tolstring (lua_State *L, int index, size_t *len);</pre> 5566 1.1 mbalmer 5567 1.1 mbalmer <p> 5568 1.2 lneto Converts the Lua value at the given index to a C string. 5569 1.1 mbalmer If <code>len</code> is not <code>NULL</code>, 5570 1.5 lneto it sets <code>*len</code> with the string length. 5571 1.1 mbalmer The Lua value must be a string or a number; 5572 1.1 mbalmer otherwise, the function returns <code>NULL</code>. 5573 1.1 mbalmer If the value is a number, 5574 1.2 lneto then <code>lua_tolstring</code> also 5575 1.1 mbalmer <em>changes the actual value in the stack to a string</em>. 5576 1.1 mbalmer (This change confuses <a href="#lua_next"><code>lua_next</code></a> 5577 1.2 lneto when <code>lua_tolstring</code> is applied to keys during a table traversal.) 5578 1.1 mbalmer 5579 1.1 mbalmer 5580 1.1 mbalmer <p> 5581 1.5 lneto <code>lua_tolstring</code> returns a pointer 5582 1.9 nikita to a string inside the Lua state (see <a href="#4.1.3">§4.1.3</a>). 5583 1.1 mbalmer This string always has a zero ('<code>\0</code>') 5584 1.1 mbalmer after its last character (as in C), 5585 1.1 mbalmer but can contain other zeros in its body. 5586 1.3 lneto 5587 1.3 lneto 5588 1.1 mbalmer 5589 1.1 mbalmer 5590 1.1 mbalmer 5591 1.1 mbalmer <hr><h3><a name="lua_tonumber"><code>lua_tonumber</code></a></h3><p> 5592 1.2 lneto <span class="apii">[-0, +0, –]</span> 5593 1.1 mbalmer <pre>lua_Number lua_tonumber (lua_State *L, int index);</pre> 5594 1.1 mbalmer 5595 1.1 mbalmer <p> 5596 1.2 lneto Equivalent to <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> with <code>isnum</code> equal to <code>NULL</code>. 5597 1.2 lneto 5598 1.2 lneto 5599 1.2 lneto 5600 1.2 lneto 5601 1.2 lneto 5602 1.2 lneto <hr><h3><a name="lua_tonumberx"><code>lua_tonumberx</code></a></h3><p> 5603 1.2 lneto <span class="apii">[-0, +0, –]</span> 5604 1.2 lneto <pre>lua_Number lua_tonumberx (lua_State *L, int index, int *isnum);</pre> 5605 1.2 lneto 5606 1.2 lneto <p> 5607 1.2 lneto Converts the Lua value at the given index 5608 1.1 mbalmer to the C type <a href="#lua_Number"><code>lua_Number</code></a> (see <a href="#lua_Number"><code>lua_Number</code></a>). 5609 1.1 mbalmer The Lua value must be a number or a string convertible to a number 5610 1.2 lneto (see <a href="#3.4.3">§3.4.3</a>); 5611 1.2 lneto otherwise, <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> returns 0. 5612 1.2 lneto 5613 1.2 lneto 5614 1.2 lneto <p> 5615 1.2 lneto If <code>isnum</code> is not <code>NULL</code>, 5616 1.2 lneto its referent is assigned a boolean value that 5617 1.2 lneto indicates whether the operation succeeded. 5618 1.1 mbalmer 5619 1.1 mbalmer 5620 1.1 mbalmer 5621 1.1 mbalmer 5622 1.1 mbalmer 5623 1.1 mbalmer <hr><h3><a name="lua_topointer"><code>lua_topointer</code></a></h3><p> 5624 1.2 lneto <span class="apii">[-0, +0, –]</span> 5625 1.1 mbalmer <pre>const void *lua_topointer (lua_State *L, int index);</pre> 5626 1.1 mbalmer 5627 1.1 mbalmer <p> 5628 1.2 lneto Converts the value at the given index to a generic 5629 1.1 mbalmer C pointer (<code>void*</code>). 5630 1.9 nikita The value can be a userdata, a table, a thread, a string, or a function; 5631 1.2 lneto otherwise, <code>lua_topointer</code> returns <code>NULL</code>. 5632 1.1 mbalmer Different objects will give different pointers. 5633 1.1 mbalmer There is no way to convert the pointer back to its original value. 5634 1.1 mbalmer 5635 1.1 mbalmer 5636 1.1 mbalmer <p> 5637 1.4 mbalmer Typically this function is used only for hashing and debug information. 5638 1.1 mbalmer 5639 1.1 mbalmer 5640 1.1 mbalmer 5641 1.1 mbalmer 5642 1.1 mbalmer 5643 1.1 mbalmer <hr><h3><a name="lua_tostring"><code>lua_tostring</code></a></h3><p> 5644 1.5 lneto <span class="apii">[-0, +0, <em>m</em>]</span> 5645 1.1 mbalmer <pre>const char *lua_tostring (lua_State *L, int index);</pre> 5646 1.1 mbalmer 5647 1.1 mbalmer <p> 5648 1.1 mbalmer Equivalent to <a href="#lua_tolstring"><code>lua_tolstring</code></a> with <code>len</code> equal to <code>NULL</code>. 5649 1.1 mbalmer 5650 1.1 mbalmer 5651 1.1 mbalmer 5652 1.1 mbalmer 5653 1.1 mbalmer 5654 1.1 mbalmer <hr><h3><a name="lua_tothread"><code>lua_tothread</code></a></h3><p> 5655 1.2 lneto <span class="apii">[-0, +0, –]</span> 5656 1.1 mbalmer <pre>lua_State *lua_tothread (lua_State *L, int index);</pre> 5657 1.1 mbalmer 5658 1.1 mbalmer <p> 5659 1.2 lneto Converts the value at the given index to a Lua thread 5660 1.1 mbalmer (represented as <code>lua_State*</code>). 5661 1.1 mbalmer This value must be a thread; 5662 1.1 mbalmer otherwise, the function returns <code>NULL</code>. 5663 1.1 mbalmer 5664 1.1 mbalmer 5665 1.1 mbalmer 5666 1.1 mbalmer 5667 1.1 mbalmer 5668 1.1 mbalmer <hr><h3><a name="lua_touserdata"><code>lua_touserdata</code></a></h3><p> 5669 1.2 lneto <span class="apii">[-0, +0, –]</span> 5670 1.1 mbalmer <pre>void *lua_touserdata (lua_State *L, int index);</pre> 5671 1.1 mbalmer 5672 1.1 mbalmer <p> 5673 1.2 lneto If the value at the given index is a full userdata, 5674 1.9 nikita returns its memory-block address. 5675 1.1 mbalmer If the value is a light userdata, 5676 1.9 nikita returns its value (a pointer). 5677 1.1 mbalmer Otherwise, returns <code>NULL</code>. 5678 1.1 mbalmer 5679 1.1 mbalmer 5680 1.1 mbalmer 5681 1.1 mbalmer 5682 1.1 mbalmer 5683 1.1 mbalmer <hr><h3><a name="lua_type"><code>lua_type</code></a></h3><p> 5684 1.2 lneto <span class="apii">[-0, +0, –]</span> 5685 1.1 mbalmer <pre>int lua_type (lua_State *L, int index);</pre> 5686 1.1 mbalmer 5687 1.1 mbalmer <p> 5688 1.2 lneto Returns the type of the value in the given valid index, 5689 1.9 nikita or <code>LUA_TNONE</code> for a non-valid but acceptable index. 5690 1.1 mbalmer The types returned by <a href="#lua_type"><code>lua_type</code></a> are coded by the following constants 5691 1.1 mbalmer defined in <code>lua.h</code>: 5692 1.9 nikita <a name="pdf-LUA_TNIL"><code>LUA_TNIL</code></a>, 5693 1.2 lneto <a name="pdf-LUA_TNUMBER"><code>LUA_TNUMBER</code></a>, 5694 1.2 lneto <a name="pdf-LUA_TBOOLEAN"><code>LUA_TBOOLEAN</code></a>, 5695 1.2 lneto <a name="pdf-LUA_TSTRING"><code>LUA_TSTRING</code></a>, 5696 1.2 lneto <a name="pdf-LUA_TTABLE"><code>LUA_TTABLE</code></a>, 5697 1.2 lneto <a name="pdf-LUA_TFUNCTION"><code>LUA_TFUNCTION</code></a>, 5698 1.2 lneto <a name="pdf-LUA_TUSERDATA"><code>LUA_TUSERDATA</code></a>, 5699 1.2 lneto <a name="pdf-LUA_TTHREAD"><code>LUA_TTHREAD</code></a>, 5700 1.1 mbalmer and 5701 1.2 lneto <a name="pdf-LUA_TLIGHTUSERDATA"><code>LUA_TLIGHTUSERDATA</code></a>. 5702 1.1 mbalmer 5703 1.1 mbalmer 5704 1.1 mbalmer 5705 1.1 mbalmer 5706 1.1 mbalmer 5707 1.1 mbalmer <hr><h3><a name="lua_typename"><code>lua_typename</code></a></h3><p> 5708 1.2 lneto <span class="apii">[-0, +0, –]</span> 5709 1.2 lneto <pre>const char *lua_typename (lua_State *L, int tp);</pre> 5710 1.1 mbalmer 5711 1.1 mbalmer <p> 5712 1.1 mbalmer Returns the name of the type encoded by the value <code>tp</code>, 5713 1.1 mbalmer which must be one the values returned by <a href="#lua_type"><code>lua_type</code></a>. 5714 1.1 mbalmer 5715 1.1 mbalmer 5716 1.1 mbalmer 5717 1.1 mbalmer 5718 1.1 mbalmer 5719 1.2 lneto <hr><h3><a name="lua_Unsigned"><code>lua_Unsigned</code></a></h3> 5720 1.2 lneto <pre>typedef ... lua_Unsigned;</pre> 5721 1.2 lneto 5722 1.2 lneto <p> 5723 1.2 lneto The unsigned version of <a href="#lua_Integer"><code>lua_Integer</code></a>. 5724 1.2 lneto 5725 1.2 lneto 5726 1.2 lneto 5727 1.2 lneto 5728 1.2 lneto 5729 1.2 lneto <hr><h3><a name="lua_upvalueindex"><code>lua_upvalueindex</code></a></h3><p> 5730 1.2 lneto <span class="apii">[-0, +0, –]</span> 5731 1.2 lneto <pre>int lua_upvalueindex (int i);</pre> 5732 1.2 lneto 5733 1.2 lneto <p> 5734 1.2 lneto Returns the pseudo-index that represents the <code>i</code>-th upvalue of 5735 1.9 nikita the running function (see <a href="#4.2">§4.2</a>). 5736 1.9 nikita <code>i</code> must be in the range <em>[1,256]</em>. 5737 1.2 lneto 5738 1.2 lneto 5739 1.2 lneto 5740 1.2 lneto 5741 1.2 lneto 5742 1.2 lneto <hr><h3><a name="lua_version"><code>lua_version</code></a></h3><p> 5743 1.6 salazar <span class="apii">[-0, +0, –]</span> 5744 1.9 nikita <pre>lua_Number lua_version (lua_State *L);</pre> 5745 1.9 nikita 5746 1.9 nikita <p> 5747 1.9 nikita Returns the version number of this core. 5748 1.9 nikita 5749 1.9 nikita 5750 1.9 nikita 5751 1.9 nikita 5752 1.9 nikita 5753 1.9 nikita <hr><h3><a name="lua_WarnFunction"><code>lua_WarnFunction</code></a></h3> 5754 1.9 nikita <pre>typedef void (*lua_WarnFunction) (void *ud, const char *msg, int tocont);</pre> 5755 1.9 nikita 5756 1.9 nikita <p> 5757 1.9 nikita The type of warning functions, called by Lua to emit warnings. 5758 1.9 nikita The first parameter is an opaque pointer 5759 1.9 nikita set by <a href="#lua_setwarnf"><code>lua_setwarnf</code></a>. 5760 1.9 nikita The second parameter is the warning message. 5761 1.9 nikita The third parameter is a boolean that 5762 1.9 nikita indicates whether the message is 5763 1.9 nikita to be continued by the message in the next call. 5764 1.9 nikita 5765 1.9 nikita 5766 1.9 nikita <p> 5767 1.9 nikita See <a href="#pdf-warn"><code>warn</code></a> for more details about warnings. 5768 1.9 nikita 5769 1.9 nikita 5770 1.9 nikita 5771 1.9 nikita 5772 1.9 nikita 5773 1.9 nikita <hr><h3><a name="lua_warning"><code>lua_warning</code></a></h3><p> 5774 1.9 nikita <span class="apii">[-0, +0, –]</span> 5775 1.9 nikita <pre>void lua_warning (lua_State *L, const char *msg, int tocont);</pre> 5776 1.9 nikita 5777 1.9 nikita <p> 5778 1.9 nikita Emits a warning with the given message. 5779 1.9 nikita A message in a call with <code>tocont</code> true should be 5780 1.9 nikita continued in another call to this function. 5781 1.9 nikita 5782 1.2 lneto 5783 1.2 lneto <p> 5784 1.9 nikita See <a href="#pdf-warn"><code>warn</code></a> for more details about warnings. 5785 1.2 lneto 5786 1.2 lneto 5787 1.2 lneto 5788 1.2 lneto 5789 1.2 lneto 5790 1.1 mbalmer <hr><h3><a name="lua_Writer"><code>lua_Writer</code></a></h3> 5791 1.1 mbalmer <pre>typedef int (*lua_Writer) (lua_State *L, 5792 1.1 mbalmer const void* p, 5793 1.1 mbalmer size_t sz, 5794 1.1 mbalmer void* ud);</pre> 5795 1.1 mbalmer 5796 1.1 mbalmer <p> 5797 1.1 mbalmer The type of the writer function used by <a href="#lua_dump"><code>lua_dump</code></a>. 5798 1.9 nikita Every time <a href="#lua_dump"><code>lua_dump</code></a> produces another piece of chunk, 5799 1.9 nikita it calls the writer, 5800 1.1 mbalmer passing along the buffer to be written (<code>p</code>), 5801 1.1 mbalmer its size (<code>sz</code>), 5802 1.9 nikita and the <code>ud</code> parameter supplied to <a href="#lua_dump"><code>lua_dump</code></a>. 5803 1.1 mbalmer 5804 1.1 mbalmer 5805 1.1 mbalmer <p> 5806 1.1 mbalmer The writer returns an error code: 5807 1.1 mbalmer 0 means no errors; 5808 1.1 mbalmer any other value means an error and stops <a href="#lua_dump"><code>lua_dump</code></a> from 5809 1.1 mbalmer calling the writer again. 5810 1.1 mbalmer 5811 1.1 mbalmer 5812 1.1 mbalmer 5813 1.1 mbalmer 5814 1.1 mbalmer 5815 1.1 mbalmer <hr><h3><a name="lua_xmove"><code>lua_xmove</code></a></h3><p> 5816 1.2 lneto <span class="apii">[-?, +?, –]</span> 5817 1.1 mbalmer <pre>void lua_xmove (lua_State *from, lua_State *to, int n);</pre> 5818 1.1 mbalmer 5819 1.1 mbalmer <p> 5820 1.2 lneto Exchange values between different threads of the same state. 5821 1.1 mbalmer 5822 1.1 mbalmer 5823 1.1 mbalmer <p> 5824 1.1 mbalmer This function pops <code>n</code> values from the stack <code>from</code>, 5825 1.1 mbalmer and pushes them onto the stack <code>to</code>. 5826 1.1 mbalmer 5827 1.1 mbalmer 5828 1.1 mbalmer 5829 1.1 mbalmer 5830 1.1 mbalmer 5831 1.1 mbalmer <hr><h3><a name="lua_yield"><code>lua_yield</code></a></h3><p> 5832 1.9 nikita <span class="apii">[-?, +?, <em>v</em>]</span> 5833 1.2 lneto <pre>int lua_yield (lua_State *L, int nresults);</pre> 5834 1.2 lneto 5835 1.2 lneto <p> 5836 1.2 lneto This function is equivalent to <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 5837 1.9 nikita but it has no continuation (see <a href="#4.5">§4.5</a>). 5838 1.2 lneto Therefore, when the thread resumes, 5839 1.3 lneto it continues the function that called 5840 1.2 lneto the function calling <code>lua_yield</code>. 5841 1.9 nikita To avoid surprises, 5842 1.9 nikita this function should be called only in a tail call. 5843 1.2 lneto 5844 1.2 lneto 5845 1.2 lneto 5846 1.2 lneto 5847 1.2 lneto 5848 1.2 lneto <hr><h3><a name="lua_yieldk"><code>lua_yieldk</code></a></h3><p> 5849 1.9 nikita <span class="apii">[-?, +?, <em>v</em>]</span> 5850 1.3 lneto <pre>int lua_yieldk (lua_State *L, 5851 1.3 lneto int nresults, 5852 1.3 lneto lua_KContext ctx, 5853 1.3 lneto lua_KFunction k);</pre> 5854 1.1 mbalmer 5855 1.1 mbalmer <p> 5856 1.3 lneto Yields a coroutine (thread). 5857 1.1 mbalmer 5858 1.1 mbalmer 5859 1.1 mbalmer <p> 5860 1.3 lneto When a C function calls <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 5861 1.1 mbalmer the running coroutine suspends its execution, 5862 1.1 mbalmer and the call to <a href="#lua_resume"><code>lua_resume</code></a> that started this coroutine returns. 5863 1.1 mbalmer The parameter <code>nresults</code> is the number of values from the stack 5864 1.2 lneto that will be passed as results to <a href="#lua_resume"><code>lua_resume</code></a>. 5865 1.2 lneto 5866 1.2 lneto 5867 1.2 lneto <p> 5868 1.2 lneto When the coroutine is resumed again, 5869 1.2 lneto Lua calls the given continuation function <code>k</code> to continue 5870 1.9 nikita the execution of the C function that yielded (see <a href="#4.5">§4.5</a>). 5871 1.2 lneto This continuation function receives the same stack 5872 1.2 lneto from the previous function, 5873 1.2 lneto with the <code>n</code> results removed and 5874 1.2 lneto replaced by the arguments passed to <a href="#lua_resume"><code>lua_resume</code></a>. 5875 1.2 lneto Moreover, 5876 1.2 lneto the continuation function receives the value <code>ctx</code> 5877 1.2 lneto that was passed to <a href="#lua_yieldk"><code>lua_yieldk</code></a>. 5878 1.1 mbalmer 5879 1.1 mbalmer 5880 1.3 lneto <p> 5881 1.3 lneto Usually, this function does not return; 5882 1.3 lneto when the coroutine eventually resumes, 5883 1.3 lneto it continues executing the continuation function. 5884 1.3 lneto However, there is one special case, 5885 1.3 lneto which is when this function is called 5886 1.9 nikita from inside a line or a count hook (see <a href="#4.7">§4.7</a>). 5887 1.3 lneto In that case, <code>lua_yieldk</code> should be called with no continuation 5888 1.6 salazar (probably in the form of <a href="#lua_yield"><code>lua_yield</code></a>) and no results, 5889 1.3 lneto and the hook should return immediately after the call. 5890 1.3 lneto Lua will yield and, 5891 1.3 lneto when the coroutine resumes again, 5892 1.3 lneto it will continue the normal execution 5893 1.3 lneto of the (Lua) function that triggered the hook. 5894 1.3 lneto 5895 1.3 lneto 5896 1.3 lneto <p> 5897 1.3 lneto This function can raise an error if it is called from a thread 5898 1.9 nikita with a pending C call with no continuation function 5899 1.9 nikita (what is called a <em>C-call boundary</em>), 5900 1.3 lneto or it is called from a thread that is not running inside a resume 5901 1.9 nikita (typically the main thread). 5902 1.3 lneto 5903 1.3 lneto 5904 1.1 mbalmer 5905 1.1 mbalmer 5906 1.1 mbalmer 5907 1.1 mbalmer 5908 1.1 mbalmer 5909 1.9 nikita <h2>4.7 – <a name="4.7">The Debug Interface</a></h2> 5910 1.1 mbalmer 5911 1.1 mbalmer <p> 5912 1.1 mbalmer Lua has no built-in debugging facilities. 5913 1.1 mbalmer Instead, it offers a special interface 5914 1.1 mbalmer by means of functions and <em>hooks</em>. 5915 1.1 mbalmer This interface allows the construction of different 5916 1.1 mbalmer kinds of debuggers, profilers, and other tools 5917 1.1 mbalmer that need "inside information" from the interpreter. 5918 1.1 mbalmer 5919 1.1 mbalmer 5920 1.1 mbalmer 5921 1.1 mbalmer <hr><h3><a name="lua_Debug"><code>lua_Debug</code></a></h3> 5922 1.1 mbalmer <pre>typedef struct lua_Debug { 5923 1.1 mbalmer int event; 5924 1.1 mbalmer const char *name; /* (n) */ 5925 1.1 mbalmer const char *namewhat; /* (n) */ 5926 1.1 mbalmer const char *what; /* (S) */ 5927 1.1 mbalmer const char *source; /* (S) */ 5928 1.9 nikita size_t srclen; /* (S) */ 5929 1.1 mbalmer int currentline; /* (l) */ 5930 1.1 mbalmer int linedefined; /* (S) */ 5931 1.1 mbalmer int lastlinedefined; /* (S) */ 5932 1.2 lneto unsigned char nups; /* (u) number of upvalues */ 5933 1.2 lneto unsigned char nparams; /* (u) number of parameters */ 5934 1.2 lneto char isvararg; /* (u) */ 5935 1.2 lneto char istailcall; /* (t) */ 5936 1.9 nikita unsigned short ftransfer; /* (r) index of first value transferred */ 5937 1.9 nikita unsigned short ntransfer; /* (r) number of transferred values */ 5938 1.1 mbalmer char short_src[LUA_IDSIZE]; /* (S) */ 5939 1.1 mbalmer /* private part */ 5940 1.1 mbalmer <em>other fields</em> 5941 1.1 mbalmer } lua_Debug;</pre> 5942 1.1 mbalmer 5943 1.1 mbalmer <p> 5944 1.1 mbalmer A structure used to carry different pieces of 5945 1.2 lneto information about a function or an activation record. 5946 1.1 mbalmer <a href="#lua_getstack"><code>lua_getstack</code></a> fills only the private part 5947 1.1 mbalmer of this structure, for later use. 5948 1.1 mbalmer To fill the other fields of <a href="#lua_Debug"><code>lua_Debug</code></a> with useful information, 5949 1.9 nikita you must call <a href="#lua_getinfo"><code>lua_getinfo</code></a> with an appropriate parameter. 5950 1.9 nikita (Specifically, to get a field, 5951 1.9 nikita you must add the letter between parentheses in the field's comment 5952 1.9 nikita to the parameter <code>what</code> of <a href="#lua_getinfo"><code>lua_getinfo</code></a>.) 5953 1.1 mbalmer 5954 1.1 mbalmer 5955 1.1 mbalmer <p> 5956 1.1 mbalmer The fields of <a href="#lua_Debug"><code>lua_Debug</code></a> have the following meaning: 5957 1.1 mbalmer 5958 1.1 mbalmer <ul> 5959 1.1 mbalmer 5960 1.2 lneto <li><b><code>source</code>: </b> 5961 1.9 nikita the source of the chunk that created the function. 5962 1.2 lneto If <code>source</code> starts with a '<code>@</code>', 5963 1.2 lneto it means that the function was defined in a file where 5964 1.2 lneto the file name follows the '<code>@</code>'. 5965 1.2 lneto If <code>source</code> starts with a '<code>=</code>', 5966 1.9 nikita the remainder of its contents describes the source in a user-dependent manner. 5967 1.2 lneto Otherwise, 5968 1.2 lneto the function was defined in a string where 5969 1.2 lneto <code>source</code> is that string. 5970 1.1 mbalmer </li> 5971 1.1 mbalmer 5972 1.9 nikita <li><b><code>srclen</code>: </b> 5973 1.9 nikita The length of the string <code>source</code>. 5974 1.9 nikita </li> 5975 1.9 nikita 5976 1.2 lneto <li><b><code>short_src</code>: </b> 5977 1.1 mbalmer a "printable" version of <code>source</code>, to be used in error messages. 5978 1.1 mbalmer </li> 5979 1.1 mbalmer 5980 1.2 lneto <li><b><code>linedefined</code>: </b> 5981 1.1 mbalmer the line number where the definition of the function starts. 5982 1.1 mbalmer </li> 5983 1.1 mbalmer 5984 1.2 lneto <li><b><code>lastlinedefined</code>: </b> 5985 1.1 mbalmer the line number where the definition of the function ends. 5986 1.1 mbalmer </li> 5987 1.1 mbalmer 5988 1.2 lneto <li><b><code>what</code>: </b> 5989 1.1 mbalmer the string <code>"Lua"</code> if the function is a Lua function, 5990 1.1 mbalmer <code>"C"</code> if it is a C function, 5991 1.2 lneto <code>"main"</code> if it is the main part of a chunk. 5992 1.1 mbalmer </li> 5993 1.1 mbalmer 5994 1.2 lneto <li><b><code>currentline</code>: </b> 5995 1.1 mbalmer the current line where the given function is executing. 5996 1.1 mbalmer When no line information is available, 5997 1.1 mbalmer <code>currentline</code> is set to -1. 5998 1.1 mbalmer </li> 5999 1.1 mbalmer 6000 1.2 lneto <li><b><code>name</code>: </b> 6001 1.1 mbalmer a reasonable name for the given function. 6002 1.1 mbalmer Because functions in Lua are first-class values, 6003 1.1 mbalmer they do not have a fixed name: 6004 1.1 mbalmer some functions can be the value of multiple global variables, 6005 1.1 mbalmer while others can be stored only in a table field. 6006 1.1 mbalmer The <code>lua_getinfo</code> function checks how the function was 6007 1.1 mbalmer called to find a suitable name. 6008 1.1 mbalmer If it cannot find a name, 6009 1.1 mbalmer then <code>name</code> is set to <code>NULL</code>. 6010 1.1 mbalmer </li> 6011 1.1 mbalmer 6012 1.2 lneto <li><b><code>namewhat</code>: </b> 6013 1.1 mbalmer explains the <code>name</code> field. 6014 1.1 mbalmer The value of <code>namewhat</code> can be 6015 1.1 mbalmer <code>"global"</code>, <code>"local"</code>, <code>"method"</code>, 6016 1.1 mbalmer <code>"field"</code>, <code>"upvalue"</code>, or <code>""</code> (the empty string), 6017 1.1 mbalmer according to how the function was called. 6018 1.1 mbalmer (Lua uses the empty string when no other option seems to apply.) 6019 1.1 mbalmer </li> 6020 1.1 mbalmer 6021 1.2 lneto <li><b><code>istailcall</code>: </b> 6022 1.2 lneto true if this function invocation was called by a tail call. 6023 1.2 lneto In this case, the caller of this level is not in the stack. 6024 1.2 lneto </li> 6025 1.2 lneto 6026 1.2 lneto <li><b><code>nups</code>: </b> 6027 1.1 mbalmer the number of upvalues of the function. 6028 1.1 mbalmer </li> 6029 1.1 mbalmer 6030 1.2 lneto <li><b><code>nparams</code>: </b> 6031 1.9 nikita the number of parameters of the function 6032 1.2 lneto (always 0 for C functions). 6033 1.2 lneto </li> 6034 1.2 lneto 6035 1.2 lneto <li><b><code>isvararg</code>: </b> 6036 1.2 lneto true if the function is a vararg function 6037 1.2 lneto (always true for C functions). 6038 1.2 lneto </li> 6039 1.2 lneto 6040 1.9 nikita <li><b><code>ftransfer</code>: </b> 6041 1.9 nikita the index in the stack of the first value being "transferred", 6042 1.9 nikita that is, parameters in a call or return values in a return. 6043 1.9 nikita (The other values are in consecutive indices.) 6044 1.9 nikita Using this index, you can access and modify these values 6045 1.9 nikita through <a href="#lua_getlocal"><code>lua_getlocal</code></a> and <a href="#lua_setlocal"><code>lua_setlocal</code></a>. 6046 1.9 nikita This field is only meaningful during a 6047 1.9 nikita call hook, denoting the first parameter, 6048 1.9 nikita or a return hook, denoting the first value being returned. 6049 1.9 nikita (For call hooks, this value is always 1.) 6050 1.9 nikita </li> 6051 1.9 nikita 6052 1.9 nikita <li><b><code>ntransfer</code>: </b> 6053 1.9 nikita The number of values being transferred (see previous item). 6054 1.9 nikita (For calls of Lua functions, 6055 1.9 nikita this value is always equal to <code>nparams</code>.) 6056 1.9 nikita </li> 6057 1.9 nikita 6058 1.1 mbalmer </ul> 6059 1.1 mbalmer 6060 1.1 mbalmer 6061 1.1 mbalmer 6062 1.1 mbalmer 6063 1.1 mbalmer <hr><h3><a name="lua_gethook"><code>lua_gethook</code></a></h3><p> 6064 1.2 lneto <span class="apii">[-0, +0, –]</span> 6065 1.1 mbalmer <pre>lua_Hook lua_gethook (lua_State *L);</pre> 6066 1.1 mbalmer 6067 1.1 mbalmer <p> 6068 1.1 mbalmer Returns the current hook function. 6069 1.1 mbalmer 6070 1.1 mbalmer 6071 1.1 mbalmer 6072 1.1 mbalmer 6073 1.1 mbalmer 6074 1.1 mbalmer <hr><h3><a name="lua_gethookcount"><code>lua_gethookcount</code></a></h3><p> 6075 1.2 lneto <span class="apii">[-0, +0, –]</span> 6076 1.1 mbalmer <pre>int lua_gethookcount (lua_State *L);</pre> 6077 1.1 mbalmer 6078 1.1 mbalmer <p> 6079 1.1 mbalmer Returns the current hook count. 6080 1.1 mbalmer 6081 1.1 mbalmer 6082 1.1 mbalmer 6083 1.1 mbalmer 6084 1.1 mbalmer 6085 1.1 mbalmer <hr><h3><a name="lua_gethookmask"><code>lua_gethookmask</code></a></h3><p> 6086 1.2 lneto <span class="apii">[-0, +0, –]</span> 6087 1.1 mbalmer <pre>int lua_gethookmask (lua_State *L);</pre> 6088 1.1 mbalmer 6089 1.1 mbalmer <p> 6090 1.1 mbalmer Returns the current hook mask. 6091 1.1 mbalmer 6092 1.1 mbalmer 6093 1.1 mbalmer 6094 1.1 mbalmer 6095 1.1 mbalmer 6096 1.1 mbalmer <hr><h3><a name="lua_getinfo"><code>lua_getinfo</code></a></h3><p> 6097 1.9 nikita <span class="apii">[-(0|1), +(0|1|2), <em>m</em>]</span> 6098 1.1 mbalmer <pre>int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar);</pre> 6099 1.1 mbalmer 6100 1.1 mbalmer <p> 6101 1.2 lneto Gets information about a specific function or function invocation. 6102 1.1 mbalmer 6103 1.1 mbalmer 6104 1.1 mbalmer <p> 6105 1.1 mbalmer To get information about a function invocation, 6106 1.1 mbalmer the parameter <code>ar</code> must be a valid activation record that was 6107 1.1 mbalmer filled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or 6108 1.1 mbalmer given as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>). 6109 1.1 mbalmer 6110 1.1 mbalmer 6111 1.1 mbalmer <p> 6112 1.8 alnsn To get information about a function, you push it onto the stack 6113 1.1 mbalmer and start the <code>what</code> string with the character '<code>></code>'. 6114 1.1 mbalmer (In that case, 6115 1.2 lneto <code>lua_getinfo</code> pops the function from the top of the stack.) 6116 1.1 mbalmer For instance, to know in which line a function <code>f</code> was defined, 6117 1.1 mbalmer you can write the following code: 6118 1.1 mbalmer 6119 1.1 mbalmer <pre> 6120 1.1 mbalmer lua_Debug ar; 6121 1.2 lneto lua_getglobal(L, "f"); /* get global 'f' */ 6122 1.1 mbalmer lua_getinfo(L, ">S", &ar); 6123 1.1 mbalmer printf("%d\n", ar.linedefined); 6124 1.1 mbalmer </pre> 6125 1.1 mbalmer 6126 1.1 mbalmer <p> 6127 1.1 mbalmer Each character in the string <code>what</code> 6128 1.1 mbalmer selects some fields of the structure <code>ar</code> to be filled or 6129 1.9 nikita a value to be pushed on the stack. 6130 1.9 nikita (These characters are also documented in the declaration of 6131 1.9 nikita the structure <a href="#lua_Debug"><code>lua_Debug</code></a>, 6132 1.9 nikita between parentheses in the comments following each field.) 6133 1.1 mbalmer 6134 1.1 mbalmer <ul> 6135 1.1 mbalmer 6136 1.9 nikita <li><b>'<code>f</code>': </b> 6137 1.9 nikita pushes onto the stack the function that is 6138 1.9 nikita running at the given level; 6139 1.9 nikita </li> 6140 1.9 nikita 6141 1.9 nikita <li><b>'<code>l</code>': </b> fills in the field <code>currentline</code>; 6142 1.9 nikita </li> 6143 1.9 nikita 6144 1.9 nikita <li><b>'<code>n</code>': </b> fills in the fields <code>name</code> and <code>namewhat</code>; 6145 1.9 nikita </li> 6146 1.9 nikita 6147 1.9 nikita <li><b>'<code>r</code>': </b> fills in the fields <code>ftransfer</code> and <code>ntransfer</code>; 6148 1.1 mbalmer </li> 6149 1.1 mbalmer 6150 1.2 lneto <li><b>'<code>S</code>': </b> 6151 1.1 mbalmer fills in the fields <code>source</code>, <code>short_src</code>, 6152 1.1 mbalmer <code>linedefined</code>, <code>lastlinedefined</code>, and <code>what</code>; 6153 1.1 mbalmer </li> 6154 1.1 mbalmer 6155 1.2 lneto <li><b>'<code>t</code>': </b> fills in the field <code>istailcall</code>; 6156 1.1 mbalmer </li> 6157 1.1 mbalmer 6158 1.2 lneto <li><b>'<code>u</code>': </b> fills in the fields 6159 1.2 lneto <code>nups</code>, <code>nparams</code>, and <code>isvararg</code>; 6160 1.1 mbalmer </li> 6161 1.1 mbalmer 6162 1.2 lneto <li><b>'<code>L</code>': </b> 6163 1.9 nikita pushes onto the stack a table whose indices are 6164 1.9 nikita the lines on the function with some associated code, 6165 1.9 nikita that is, the lines where you can put a break point. 6166 1.9 nikita (Lines with no code include empty lines and comments.) 6167 1.2 lneto If this option is given together with option '<code>f</code>', 6168 1.2 lneto its table is pushed after the function. 6169 1.9 nikita This is the only option that can raise a memory error. 6170 1.1 mbalmer </li> 6171 1.1 mbalmer 6172 1.1 mbalmer </ul> 6173 1.1 mbalmer 6174 1.1 mbalmer <p> 6175 1.9 nikita This function returns 0 to signal an invalid option in <code>what</code>; 6176 1.9 nikita even then the valid options are handled correctly. 6177 1.1 mbalmer 6178 1.1 mbalmer 6179 1.1 mbalmer 6180 1.1 mbalmer 6181 1.1 mbalmer 6182 1.1 mbalmer <hr><h3><a name="lua_getlocal"><code>lua_getlocal</code></a></h3><p> 6183 1.2 lneto <span class="apii">[-0, +(0|1), –]</span> 6184 1.3 lneto <pre>const char *lua_getlocal (lua_State *L, const lua_Debug *ar, int n);</pre> 6185 1.1 mbalmer 6186 1.1 mbalmer <p> 6187 1.9 nikita Gets information about a local variable or a temporary value 6188 1.9 nikita of a given activation record or a given function. 6189 1.2 lneto 6190 1.2 lneto 6191 1.2 lneto <p> 6192 1.2 lneto In the first case, 6193 1.2 lneto the parameter <code>ar</code> must be a valid activation record that was 6194 1.1 mbalmer filled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or 6195 1.1 mbalmer given as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>). 6196 1.2 lneto The index <code>n</code> selects which local variable to inspect; 6197 1.2 lneto see <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for details about variable indices 6198 1.2 lneto and names. 6199 1.2 lneto 6200 1.2 lneto 6201 1.2 lneto <p> 6202 1.1 mbalmer <a href="#lua_getlocal"><code>lua_getlocal</code></a> pushes the variable's value onto the stack 6203 1.1 mbalmer and returns its name. 6204 1.1 mbalmer 6205 1.1 mbalmer 6206 1.1 mbalmer <p> 6207 1.2 lneto In the second case, <code>ar</code> must be <code>NULL</code> and the function 6208 1.9 nikita to be inspected must be on the top of the stack. 6209 1.2 lneto In this case, only parameters of Lua functions are visible 6210 1.2 lneto (as there is no information about what variables are active) 6211 1.2 lneto and no values are pushed onto the stack. 6212 1.1 mbalmer 6213 1.1 mbalmer 6214 1.1 mbalmer <p> 6215 1.1 mbalmer Returns <code>NULL</code> (and pushes nothing) 6216 1.1 mbalmer when the index is greater than 6217 1.1 mbalmer the number of active local variables. 6218 1.1 mbalmer 6219 1.1 mbalmer 6220 1.1 mbalmer 6221 1.1 mbalmer 6222 1.1 mbalmer 6223 1.1 mbalmer <hr><h3><a name="lua_getstack"><code>lua_getstack</code></a></h3><p> 6224 1.2 lneto <span class="apii">[-0, +0, –]</span> 6225 1.1 mbalmer <pre>int lua_getstack (lua_State *L, int level, lua_Debug *ar);</pre> 6226 1.1 mbalmer 6227 1.1 mbalmer <p> 6228 1.2 lneto Gets information about the interpreter runtime stack. 6229 1.1 mbalmer 6230 1.1 mbalmer 6231 1.1 mbalmer <p> 6232 1.1 mbalmer This function fills parts of a <a href="#lua_Debug"><code>lua_Debug</code></a> structure with 6233 1.1 mbalmer an identification of the <em>activation record</em> 6234 1.1 mbalmer of the function executing at a given level. 6235 1.1 mbalmer Level 0 is the current running function, 6236 1.2 lneto whereas level <em>n+1</em> is the function that has called level <em>n</em> 6237 1.9 nikita (except for tail calls, which do not count in the stack). 6238 1.9 nikita When called with a level greater than the stack depth, 6239 1.9 nikita <a href="#lua_getstack"><code>lua_getstack</code></a> returns 0; 6240 1.9 nikita otherwise it returns 1. 6241 1.1 mbalmer 6242 1.1 mbalmer 6243 1.1 mbalmer 6244 1.1 mbalmer 6245 1.1 mbalmer 6246 1.1 mbalmer <hr><h3><a name="lua_getupvalue"><code>lua_getupvalue</code></a></h3><p> 6247 1.2 lneto <span class="apii">[-0, +(0|1), –]</span> 6248 1.1 mbalmer <pre>const char *lua_getupvalue (lua_State *L, int funcindex, int n);</pre> 6249 1.1 mbalmer 6250 1.1 mbalmer <p> 6251 1.4 mbalmer Gets information about the <code>n</code>-th upvalue 6252 1.4 mbalmer of the closure at index <code>funcindex</code>. 6253 1.4 mbalmer It pushes the upvalue's value onto the stack 6254 1.4 mbalmer and returns its name. 6255 1.4 mbalmer Returns <code>NULL</code> (and pushes nothing) 6256 1.4 mbalmer when the index <code>n</code> is greater than the number of upvalues. 6257 1.4 mbalmer 6258 1.4 mbalmer 6259 1.4 mbalmer <p> 6260 1.9 nikita See <a href="#pdf-debug.getupvalue"><code>debug.getupvalue</code></a> for more information about upvalues. 6261 1.1 mbalmer 6262 1.1 mbalmer 6263 1.1 mbalmer 6264 1.1 mbalmer 6265 1.1 mbalmer 6266 1.1 mbalmer <hr><h3><a name="lua_Hook"><code>lua_Hook</code></a></h3> 6267 1.1 mbalmer <pre>typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar);</pre> 6268 1.1 mbalmer 6269 1.1 mbalmer <p> 6270 1.1 mbalmer Type for debugging hook functions. 6271 1.1 mbalmer 6272 1.1 mbalmer 6273 1.1 mbalmer <p> 6274 1.1 mbalmer Whenever a hook is called, its <code>ar</code> argument has its field 6275 1.1 mbalmer <code>event</code> set to the specific event that triggered the hook. 6276 1.1 mbalmer Lua identifies these events with the following constants: 6277 1.1 mbalmer <a name="pdf-LUA_HOOKCALL"><code>LUA_HOOKCALL</code></a>, <a name="pdf-LUA_HOOKRET"><code>LUA_HOOKRET</code></a>, 6278 1.2 lneto <a name="pdf-LUA_HOOKTAILCALL"><code>LUA_HOOKTAILCALL</code></a>, <a name="pdf-LUA_HOOKLINE"><code>LUA_HOOKLINE</code></a>, 6279 1.1 mbalmer and <a name="pdf-LUA_HOOKCOUNT"><code>LUA_HOOKCOUNT</code></a>. 6280 1.1 mbalmer Moreover, for line events, the field <code>currentline</code> is also set. 6281 1.1 mbalmer To get the value of any other field in <code>ar</code>, 6282 1.1 mbalmer the hook must call <a href="#lua_getinfo"><code>lua_getinfo</code></a>. 6283 1.2 lneto 6284 1.2 lneto 6285 1.2 lneto <p> 6286 1.2 lneto For call events, <code>event</code> can be <code>LUA_HOOKCALL</code>, 6287 1.2 lneto the normal value, or <code>LUA_HOOKTAILCALL</code>, for a tail call; 6288 1.2 lneto in this case, there will be no corresponding return event. 6289 1.1 mbalmer 6290 1.1 mbalmer 6291 1.1 mbalmer <p> 6292 1.1 mbalmer While Lua is running a hook, it disables other calls to hooks. 6293 1.1 mbalmer Therefore, if a hook calls back Lua to execute a function or a chunk, 6294 1.1 mbalmer this execution occurs without any calls to hooks. 6295 1.1 mbalmer 6296 1.1 mbalmer 6297 1.2 lneto <p> 6298 1.2 lneto Hook functions cannot have continuations, 6299 1.2 lneto that is, they cannot call <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 6300 1.2 lneto <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>. 6301 1.2 lneto 6302 1.2 lneto 6303 1.2 lneto <p> 6304 1.2 lneto Hook functions can yield under the following conditions: 6305 1.4 mbalmer Only count and line events can yield; 6306 1.4 mbalmer to yield, a hook function must finish its execution 6307 1.4 mbalmer calling <a href="#lua_yield"><code>lua_yield</code></a> with <code>nresults</code> equal to zero 6308 1.4 mbalmer (that is, with no values). 6309 1.2 lneto 6310 1.2 lneto 6311 1.1 mbalmer 6312 1.1 mbalmer 6313 1.1 mbalmer 6314 1.1 mbalmer <hr><h3><a name="lua_sethook"><code>lua_sethook</code></a></h3><p> 6315 1.2 lneto <span class="apii">[-0, +0, –]</span> 6316 1.2 lneto <pre>void lua_sethook (lua_State *L, lua_Hook f, int mask, int count);</pre> 6317 1.1 mbalmer 6318 1.1 mbalmer <p> 6319 1.1 mbalmer Sets the debugging hook function. 6320 1.1 mbalmer 6321 1.1 mbalmer 6322 1.1 mbalmer <p> 6323 1.1 mbalmer Argument <code>f</code> is the hook function. 6324 1.1 mbalmer <code>mask</code> specifies on which events the hook will be called: 6325 1.6 salazar it is formed by a bitwise OR of the constants 6326 1.1 mbalmer <a name="pdf-LUA_MASKCALL"><code>LUA_MASKCALL</code></a>, 6327 1.1 mbalmer <a name="pdf-LUA_MASKRET"><code>LUA_MASKRET</code></a>, 6328 1.1 mbalmer <a name="pdf-LUA_MASKLINE"><code>LUA_MASKLINE</code></a>, 6329 1.1 mbalmer and <a name="pdf-LUA_MASKCOUNT"><code>LUA_MASKCOUNT</code></a>. 6330 1.1 mbalmer The <code>count</code> argument is only meaningful when the mask 6331 1.1 mbalmer includes <code>LUA_MASKCOUNT</code>. 6332 1.1 mbalmer For each event, the hook is called as explained below: 6333 1.1 mbalmer 6334 1.1 mbalmer <ul> 6335 1.1 mbalmer 6336 1.2 lneto <li><b>The call hook: </b> is called when the interpreter calls a function. 6337 1.9 nikita The hook is called just after Lua enters the new function. 6338 1.1 mbalmer </li> 6339 1.1 mbalmer 6340 1.2 lneto <li><b>The return hook: </b> is called when the interpreter returns from a function. 6341 1.1 mbalmer The hook is called just before Lua leaves the function. 6342 1.1 mbalmer </li> 6343 1.1 mbalmer 6344 1.2 lneto <li><b>The line hook: </b> is called when the interpreter is about to 6345 1.1 mbalmer start the execution of a new line of code, 6346 1.1 mbalmer or when it jumps back in the code (even to the same line). 6347 1.9 nikita This event only happens while Lua is executing a Lua function. 6348 1.1 mbalmer </li> 6349 1.1 mbalmer 6350 1.2 lneto <li><b>The count hook: </b> is called after the interpreter executes every 6351 1.1 mbalmer <code>count</code> instructions. 6352 1.9 nikita This event only happens while Lua is executing a Lua function. 6353 1.1 mbalmer </li> 6354 1.1 mbalmer 6355 1.1 mbalmer </ul> 6356 1.1 mbalmer 6357 1.1 mbalmer <p> 6358 1.9 nikita Hooks are disabled by setting <code>mask</code> to zero. 6359 1.1 mbalmer 6360 1.1 mbalmer 6361 1.1 mbalmer 6362 1.1 mbalmer 6363 1.1 mbalmer 6364 1.1 mbalmer <hr><h3><a name="lua_setlocal"><code>lua_setlocal</code></a></h3><p> 6365 1.2 lneto <span class="apii">[-(0|1), +0, –]</span> 6366 1.3 lneto <pre>const char *lua_setlocal (lua_State *L, const lua_Debug *ar, int n);</pre> 6367 1.1 mbalmer 6368 1.1 mbalmer <p> 6369 1.1 mbalmer Sets the value of a local variable of a given activation record. 6370 1.9 nikita It assigns the value on the top of the stack 6371 1.1 mbalmer to the variable and returns its name. 6372 1.1 mbalmer It also pops the value from the stack. 6373 1.1 mbalmer 6374 1.1 mbalmer 6375 1.1 mbalmer <p> 6376 1.1 mbalmer Returns <code>NULL</code> (and pops nothing) 6377 1.1 mbalmer when the index is greater than 6378 1.1 mbalmer the number of active local variables. 6379 1.1 mbalmer 6380 1.1 mbalmer 6381 1.4 mbalmer <p> 6382 1.9 nikita Parameters <code>ar</code> and <code>n</code> are as in the function <a href="#lua_getlocal"><code>lua_getlocal</code></a>. 6383 1.4 mbalmer 6384 1.4 mbalmer 6385 1.1 mbalmer 6386 1.1 mbalmer 6387 1.1 mbalmer 6388 1.1 mbalmer <hr><h3><a name="lua_setupvalue"><code>lua_setupvalue</code></a></h3><p> 6389 1.2 lneto <span class="apii">[-(0|1), +0, –]</span> 6390 1.1 mbalmer <pre>const char *lua_setupvalue (lua_State *L, int funcindex, int n);</pre> 6391 1.1 mbalmer 6392 1.1 mbalmer <p> 6393 1.1 mbalmer Sets the value of a closure's upvalue. 6394 1.9 nikita It assigns the value on the top of the stack 6395 1.1 mbalmer to the upvalue and returns its name. 6396 1.1 mbalmer It also pops the value from the stack. 6397 1.1 mbalmer 6398 1.1 mbalmer 6399 1.1 mbalmer <p> 6400 1.1 mbalmer Returns <code>NULL</code> (and pops nothing) 6401 1.4 mbalmer when the index <code>n</code> is greater than the number of upvalues. 6402 1.4 mbalmer 6403 1.4 mbalmer 6404 1.4 mbalmer <p> 6405 1.9 nikita Parameters <code>funcindex</code> and <code>n</code> are as in 6406 1.9 nikita the function <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>. 6407 1.1 mbalmer 6408 1.1 mbalmer 6409 1.1 mbalmer 6410 1.1 mbalmer 6411 1.1 mbalmer 6412 1.2 lneto <hr><h3><a name="lua_upvalueid"><code>lua_upvalueid</code></a></h3><p> 6413 1.2 lneto <span class="apii">[-0, +0, –]</span> 6414 1.2 lneto <pre>void *lua_upvalueid (lua_State *L, int funcindex, int n);</pre> 6415 1.2 lneto 6416 1.2 lneto <p> 6417 1.3 lneto Returns a unique identifier for the upvalue numbered <code>n</code> 6418 1.2 lneto from the closure at index <code>funcindex</code>. 6419 1.2 lneto 6420 1.2 lneto 6421 1.2 lneto <p> 6422 1.2 lneto These unique identifiers allow a program to check whether different 6423 1.2 lneto closures share upvalues. 6424 1.2 lneto Lua closures that share an upvalue 6425 1.2 lneto (that is, that access a same external local variable) 6426 1.2 lneto will return identical ids for those upvalue indices. 6427 1.2 lneto 6428 1.2 lneto 6429 1.4 mbalmer <p> 6430 1.9 nikita Parameters <code>funcindex</code> and <code>n</code> are as in 6431 1.9 nikita the function <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>, 6432 1.4 mbalmer but <code>n</code> cannot be greater than the number of upvalues. 6433 1.4 mbalmer 6434 1.4 mbalmer 6435 1.2 lneto 6436 1.2 lneto 6437 1.2 lneto 6438 1.2 lneto <hr><h3><a name="lua_upvaluejoin"><code>lua_upvaluejoin</code></a></h3><p> 6439 1.2 lneto <span class="apii">[-0, +0, –]</span> 6440 1.2 lneto <pre>void lua_upvaluejoin (lua_State *L, int funcindex1, int n1, 6441 1.2 lneto int funcindex2, int n2);</pre> 6442 1.2 lneto 6443 1.2 lneto <p> 6444 1.2 lneto Make the <code>n1</code>-th upvalue of the Lua closure at index <code>funcindex1</code> 6445 1.2 lneto refer to the <code>n2</code>-th upvalue of the Lua closure at index <code>funcindex2</code>. 6446 1.2 lneto 6447 1.2 lneto 6448 1.2 lneto 6449 1.2 lneto 6450 1.2 lneto 6451 1.1 mbalmer 6452 1.1 mbalmer 6453 1.2 lneto <h1>5 – <a name="5">The Auxiliary Library</a></h1> 6454 1.1 mbalmer 6455 1.9 nikita 6456 1.9 nikita 6457 1.1 mbalmer <p> 6458 1.1 mbalmer 6459 1.1 mbalmer The <em>auxiliary library</em> provides several convenient functions 6460 1.1 mbalmer to interface C with Lua. 6461 1.2 lneto While the basic API provides the primitive functions for all 6462 1.1 mbalmer interactions between C and Lua, 6463 1.1 mbalmer the auxiliary library provides higher-level functions for some 6464 1.1 mbalmer common tasks. 6465 1.1 mbalmer 6466 1.1 mbalmer 6467 1.1 mbalmer <p> 6468 1.2 lneto All functions and types from the auxiliary library 6469 1.1 mbalmer are defined in header file <code>lauxlib.h</code> and 6470 1.1 mbalmer have a prefix <code>luaL_</code>. 6471 1.1 mbalmer 6472 1.1 mbalmer 6473 1.1 mbalmer <p> 6474 1.1 mbalmer All functions in the auxiliary library are built on 6475 1.1 mbalmer top of the basic API, 6476 1.2 lneto and so they provide nothing that cannot be done with that API. 6477 1.2 lneto Nevertheless, the use of the auxiliary library ensures 6478 1.2 lneto more consistency to your code. 6479 1.2 lneto 6480 1.2 lneto 6481 1.2 lneto <p> 6482 1.2 lneto Several functions in the auxiliary library use internally some 6483 1.2 lneto extra stack slots. 6484 1.2 lneto When a function in the auxiliary library uses less than five slots, 6485 1.2 lneto it does not check the stack size; 6486 1.2 lneto it simply assumes that there are enough slots. 6487 1.1 mbalmer 6488 1.1 mbalmer 6489 1.1 mbalmer <p> 6490 1.1 mbalmer Several functions in the auxiliary library are used to 6491 1.1 mbalmer check C function arguments. 6492 1.1 mbalmer Because the error message is formatted for arguments 6493 1.1 mbalmer (e.g., "<code>bad argument #1</code>"), 6494 1.1 mbalmer you should not use these functions for other stack values. 6495 1.1 mbalmer 6496 1.1 mbalmer 6497 1.2 lneto <p> 6498 1.2 lneto Functions called <code>luaL_check*</code> 6499 1.2 lneto always raise an error if the check is not satisfied. 6500 1.2 lneto 6501 1.2 lneto 6502 1.1 mbalmer 6503 1.9 nikita 6504 1.9 nikita 6505 1.2 lneto <h2>5.1 – <a name="5.1">Functions and Types</a></h2> 6506 1.1 mbalmer 6507 1.1 mbalmer <p> 6508 1.1 mbalmer Here we list all functions and types from the auxiliary library 6509 1.1 mbalmer in alphabetical order. 6510 1.1 mbalmer 6511 1.1 mbalmer 6512 1.1 mbalmer 6513 1.1 mbalmer <hr><h3><a name="luaL_addchar"><code>luaL_addchar</code></a></h3><p> 6514 1.5 lneto <span class="apii">[-?, +?, <em>m</em>]</span> 6515 1.1 mbalmer <pre>void luaL_addchar (luaL_Buffer *B, char c);</pre> 6516 1.1 mbalmer 6517 1.1 mbalmer <p> 6518 1.2 lneto Adds the byte <code>c</code> to the buffer <code>B</code> 6519 1.1 mbalmer (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6520 1.1 mbalmer 6521 1.1 mbalmer 6522 1.1 mbalmer 6523 1.1 mbalmer 6524 1.1 mbalmer 6525 1.9 nikita <hr><h3><a name="luaL_addgsub"><code>luaL_addgsub</code></a></h3><p> 6526 1.9 nikita <span class="apii">[-?, +?, <em>m</em>]</span> 6527 1.9 nikita <pre>const void luaL_addgsub (luaL_Buffer *B, const char *s, 6528 1.9 nikita const char *p, const char *r);</pre> 6529 1.9 nikita 6530 1.9 nikita <p> 6531 1.9 nikita Adds a copy of the string <code>s</code> to the buffer <code>B</code> (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>), 6532 1.9 nikita replacing any occurrence of the string <code>p</code> 6533 1.9 nikita with the string <code>r</code>. 6534 1.9 nikita 6535 1.9 nikita 6536 1.9 nikita 6537 1.9 nikita 6538 1.9 nikita 6539 1.1 mbalmer <hr><h3><a name="luaL_addlstring"><code>luaL_addlstring</code></a></h3><p> 6540 1.5 lneto <span class="apii">[-?, +?, <em>m</em>]</span> 6541 1.1 mbalmer <pre>void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l);</pre> 6542 1.1 mbalmer 6543 1.1 mbalmer <p> 6544 1.1 mbalmer Adds the string pointed to by <code>s</code> with length <code>l</code> to 6545 1.1 mbalmer the buffer <code>B</code> 6546 1.1 mbalmer (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6547 1.2 lneto The string can contain embedded zeros. 6548 1.1 mbalmer 6549 1.1 mbalmer 6550 1.1 mbalmer 6551 1.1 mbalmer 6552 1.1 mbalmer 6553 1.1 mbalmer <hr><h3><a name="luaL_addsize"><code>luaL_addsize</code></a></h3><p> 6554 1.5 lneto <span class="apii">[-?, +?, –]</span> 6555 1.1 mbalmer <pre>void luaL_addsize (luaL_Buffer *B, size_t n);</pre> 6556 1.1 mbalmer 6557 1.1 mbalmer <p> 6558 1.9 nikita Adds to the buffer <code>B</code> 6559 1.1 mbalmer a string of length <code>n</code> previously copied to the 6560 1.1 mbalmer buffer area (see <a href="#luaL_prepbuffer"><code>luaL_prepbuffer</code></a>). 6561 1.1 mbalmer 6562 1.1 mbalmer 6563 1.1 mbalmer 6564 1.1 mbalmer 6565 1.1 mbalmer 6566 1.1 mbalmer <hr><h3><a name="luaL_addstring"><code>luaL_addstring</code></a></h3><p> 6567 1.5 lneto <span class="apii">[-?, +?, <em>m</em>]</span> 6568 1.1 mbalmer <pre>void luaL_addstring (luaL_Buffer *B, const char *s);</pre> 6569 1.1 mbalmer 6570 1.1 mbalmer <p> 6571 1.1 mbalmer Adds the zero-terminated string pointed to by <code>s</code> 6572 1.1 mbalmer to the buffer <code>B</code> 6573 1.1 mbalmer (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6574 1.1 mbalmer 6575 1.1 mbalmer 6576 1.1 mbalmer 6577 1.1 mbalmer 6578 1.1 mbalmer 6579 1.1 mbalmer <hr><h3><a name="luaL_addvalue"><code>luaL_addvalue</code></a></h3><p> 6580 1.9 nikita <span class="apii">[-?, +?, <em>m</em>]</span> 6581 1.1 mbalmer <pre>void luaL_addvalue (luaL_Buffer *B);</pre> 6582 1.1 mbalmer 6583 1.1 mbalmer <p> 6584 1.9 nikita Adds the value on the top of the stack 6585 1.1 mbalmer to the buffer <code>B</code> 6586 1.1 mbalmer (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6587 1.1 mbalmer Pops the value. 6588 1.1 mbalmer 6589 1.1 mbalmer 6590 1.1 mbalmer <p> 6591 1.1 mbalmer This is the only function on string buffers that can (and must) 6592 1.1 mbalmer be called with an extra element on the stack, 6593 1.1 mbalmer which is the value to be added to the buffer. 6594 1.1 mbalmer 6595 1.1 mbalmer 6596 1.1 mbalmer 6597 1.1 mbalmer 6598 1.1 mbalmer 6599 1.1 mbalmer <hr><h3><a name="luaL_argcheck"><code>luaL_argcheck</code></a></h3><p> 6600 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 6601 1.1 mbalmer <pre>void luaL_argcheck (lua_State *L, 6602 1.1 mbalmer int cond, 6603 1.2 lneto int arg, 6604 1.1 mbalmer const char *extramsg);</pre> 6605 1.1 mbalmer 6606 1.1 mbalmer <p> 6607 1.1 mbalmer Checks whether <code>cond</code> is true. 6608 1.2 lneto If it is not, raises an error with a standard message (see <a href="#luaL_argerror"><code>luaL_argerror</code></a>). 6609 1.1 mbalmer 6610 1.1 mbalmer 6611 1.1 mbalmer 6612 1.1 mbalmer 6613 1.1 mbalmer 6614 1.1 mbalmer <hr><h3><a name="luaL_argerror"><code>luaL_argerror</code></a></h3><p> 6615 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 6616 1.2 lneto <pre>int luaL_argerror (lua_State *L, int arg, const char *extramsg);</pre> 6617 1.1 mbalmer 6618 1.1 mbalmer <p> 6619 1.2 lneto Raises an error reporting a problem with argument <code>arg</code> 6620 1.7 mbalmer of the C function that called it, 6621 1.2 lneto using a standard message 6622 1.2 lneto that includes <code>extramsg</code> as a comment: 6623 1.1 mbalmer 6624 1.1 mbalmer <pre> 6625 1.2 lneto bad argument #<em>arg</em> to '<em>funcname</em>' (<em>extramsg</em>) 6626 1.2 lneto </pre><p> 6627 1.2 lneto This function never returns. 6628 1.1 mbalmer 6629 1.1 mbalmer 6630 1.1 mbalmer 6631 1.1 mbalmer 6632 1.1 mbalmer 6633 1.9 nikita <hr><h3><a name="luaL_argexpected"><code>luaL_argexpected</code></a></h3><p> 6634 1.9 nikita <span class="apii">[-0, +0, <em>v</em>]</span> 6635 1.9 nikita <pre>void luaL_argexpected (lua_State *L, 6636 1.9 nikita int cond, 6637 1.9 nikita int arg, 6638 1.9 nikita const char *tname);</pre> 6639 1.9 nikita 6640 1.9 nikita <p> 6641 1.9 nikita Checks whether <code>cond</code> is true. 6642 1.9 nikita If it is not, raises an error about the type of the argument <code>arg</code> 6643 1.9 nikita with a standard message (see <a href="#luaL_typeerror"><code>luaL_typeerror</code></a>). 6644 1.9 nikita 6645 1.9 nikita 6646 1.9 nikita 6647 1.9 nikita 6648 1.9 nikita 6649 1.1 mbalmer <hr><h3><a name="luaL_Buffer"><code>luaL_Buffer</code></a></h3> 6650 1.1 mbalmer <pre>typedef struct luaL_Buffer luaL_Buffer;</pre> 6651 1.1 mbalmer 6652 1.1 mbalmer <p> 6653 1.1 mbalmer Type for a <em>string buffer</em>. 6654 1.1 mbalmer 6655 1.1 mbalmer 6656 1.1 mbalmer <p> 6657 1.1 mbalmer A string buffer allows C code to build Lua strings piecemeal. 6658 1.1 mbalmer Its pattern of use is as follows: 6659 1.1 mbalmer 6660 1.1 mbalmer <ul> 6661 1.1 mbalmer 6662 1.2 lneto <li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li> 6663 1.1 mbalmer 6664 1.2 lneto <li>Then initialize it with a call <code>luaL_buffinit(L, &b)</code>.</li> 6665 1.1 mbalmer 6666 1.1 mbalmer <li> 6667 1.2 lneto Then add string pieces to the buffer calling any of 6668 1.1 mbalmer the <code>luaL_add*</code> functions. 6669 1.1 mbalmer </li> 6670 1.1 mbalmer 6671 1.1 mbalmer <li> 6672 1.2 lneto Finish by calling <code>luaL_pushresult(&b)</code>. 6673 1.1 mbalmer This call leaves the final string on the top of the stack. 6674 1.1 mbalmer </li> 6675 1.1 mbalmer 6676 1.1 mbalmer </ul> 6677 1.1 mbalmer 6678 1.1 mbalmer <p> 6679 1.9 nikita If you know beforehand the maximum size of the resulting string, 6680 1.2 lneto you can use the buffer like this: 6681 1.2 lneto 6682 1.2 lneto <ul> 6683 1.2 lneto 6684 1.2 lneto <li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li> 6685 1.2 lneto 6686 1.2 lneto <li>Then initialize it and preallocate a space of 6687 1.2 lneto size <code>sz</code> with a call <code>luaL_buffinitsize(L, &b, sz)</code>.</li> 6688 1.2 lneto 6689 1.9 nikita <li>Then produce the string into that space.</li> 6690 1.2 lneto 6691 1.2 lneto <li> 6692 1.2 lneto Finish by calling <code>luaL_pushresultsize(&b, sz)</code>, 6693 1.2 lneto where <code>sz</code> is the total size of the resulting string 6694 1.9 nikita copied into that space (which may be less than or 6695 1.9 nikita equal to the preallocated size). 6696 1.2 lneto </li> 6697 1.2 lneto 6698 1.2 lneto </ul> 6699 1.2 lneto 6700 1.2 lneto <p> 6701 1.1 mbalmer During its normal operation, 6702 1.1 mbalmer a string buffer uses a variable number of stack slots. 6703 1.1 mbalmer So, while using a buffer, you cannot assume that you know where 6704 1.1 mbalmer the top of the stack is. 6705 1.1 mbalmer You can use the stack between successive calls to buffer operations 6706 1.1 mbalmer as long as that use is balanced; 6707 1.1 mbalmer that is, 6708 1.1 mbalmer when you call a buffer operation, 6709 1.1 mbalmer the stack is at the same level 6710 1.1 mbalmer it was immediately after the previous buffer operation. 6711 1.1 mbalmer (The only exception to this rule is <a href="#luaL_addvalue"><code>luaL_addvalue</code></a>.) 6712 1.9 nikita After calling <a href="#luaL_pushresult"><code>luaL_pushresult</code></a>, 6713 1.9 nikita the stack is back to its level when the buffer was initialized, 6714 1.1 mbalmer plus the final string on its top. 6715 1.1 mbalmer 6716 1.1 mbalmer 6717 1.1 mbalmer 6718 1.1 mbalmer 6719 1.1 mbalmer 6720 1.9 nikita <hr><h3><a name="luaL_buffaddr"><code>luaL_buffaddr</code></a></h3><p> 6721 1.9 nikita <span class="apii">[-0, +0, –]</span> 6722 1.9 nikita <pre>char *luaL_buffaddr (luaL_Buffer *B);</pre> 6723 1.9 nikita 6724 1.9 nikita <p> 6725 1.9 nikita Returns the address of the current content of buffer <code>B</code> 6726 1.9 nikita (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6727 1.9 nikita Note that any addition to the buffer may invalidate this address. 6728 1.9 nikita 6729 1.9 nikita 6730 1.9 nikita 6731 1.9 nikita 6732 1.9 nikita 6733 1.1 mbalmer <hr><h3><a name="luaL_buffinit"><code>luaL_buffinit</code></a></h3><p> 6734 1.9 nikita <span class="apii">[-0, +?, –]</span> 6735 1.1 mbalmer <pre>void luaL_buffinit (lua_State *L, luaL_Buffer *B);</pre> 6736 1.1 mbalmer 6737 1.1 mbalmer <p> 6738 1.9 nikita Initializes a buffer <code>B</code> 6739 1.9 nikita (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6740 1.1 mbalmer This function does not allocate any space; 6741 1.9 nikita the buffer must be declared as a variable. 6742 1.9 nikita 6743 1.9 nikita 6744 1.9 nikita 6745 1.9 nikita 6746 1.9 nikita 6747 1.9 nikita <hr><h3><a name="luaL_bufflen"><code>luaL_bufflen</code></a></h3><p> 6748 1.9 nikita <span class="apii">[-0, +0, –]</span> 6749 1.9 nikita <pre>size_t luaL_bufflen (luaL_Buffer *B);</pre> 6750 1.9 nikita 6751 1.9 nikita <p> 6752 1.9 nikita Returns the length of the current content of buffer <code>B</code> 6753 1.1 mbalmer (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6754 1.1 mbalmer 6755 1.1 mbalmer 6756 1.1 mbalmer 6757 1.1 mbalmer 6758 1.1 mbalmer 6759 1.2 lneto <hr><h3><a name="luaL_buffinitsize"><code>luaL_buffinitsize</code></a></h3><p> 6760 1.5 lneto <span class="apii">[-?, +?, <em>m</em>]</span> 6761 1.2 lneto <pre>char *luaL_buffinitsize (lua_State *L, luaL_Buffer *B, size_t sz);</pre> 6762 1.2 lneto 6763 1.2 lneto <p> 6764 1.2 lneto Equivalent to the sequence 6765 1.2 lneto <a href="#luaL_buffinit"><code>luaL_buffinit</code></a>, <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a>. 6766 1.2 lneto 6767 1.2 lneto 6768 1.2 lneto 6769 1.2 lneto 6770 1.2 lneto 6771 1.9 nikita <hr><h3><a name="luaL_buffsub"><code>luaL_buffsub</code></a></h3><p> 6772 1.9 nikita <span class="apii">[-?, +?, –]</span> 6773 1.9 nikita <pre>void luaL_buffsub (luaL_Buffer *B, int n);</pre> 6774 1.9 nikita 6775 1.9 nikita <p> 6776 1.9 nikita Removes <code>n</code> bytes from the the buffer <code>B</code> 6777 1.9 nikita (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6778 1.9 nikita The buffer must have at least that many bytes. 6779 1.9 nikita 6780 1.9 nikita 6781 1.9 nikita 6782 1.9 nikita 6783 1.9 nikita 6784 1.1 mbalmer <hr><h3><a name="luaL_callmeta"><code>luaL_callmeta</code></a></h3><p> 6785 1.1 mbalmer <span class="apii">[-0, +(0|1), <em>e</em>]</span> 6786 1.1 mbalmer <pre>int luaL_callmeta (lua_State *L, int obj, const char *e);</pre> 6787 1.1 mbalmer 6788 1.1 mbalmer <p> 6789 1.1 mbalmer Calls a metamethod. 6790 1.1 mbalmer 6791 1.1 mbalmer 6792 1.1 mbalmer <p> 6793 1.1 mbalmer If the object at index <code>obj</code> has a metatable and this 6794 1.1 mbalmer metatable has a field <code>e</code>, 6795 1.2 lneto this function calls this field passing the object as its only argument. 6796 1.2 lneto In this case this function returns true and pushes onto the 6797 1.1 mbalmer stack the value returned by the call. 6798 1.1 mbalmer If there is no metatable or no metamethod, 6799 1.9 nikita this function returns false without pushing any value on the stack. 6800 1.1 mbalmer 6801 1.1 mbalmer 6802 1.1 mbalmer 6803 1.1 mbalmer 6804 1.1 mbalmer 6805 1.1 mbalmer <hr><h3><a name="luaL_checkany"><code>luaL_checkany</code></a></h3><p> 6806 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 6807 1.2 lneto <pre>void luaL_checkany (lua_State *L, int arg);</pre> 6808 1.1 mbalmer 6809 1.1 mbalmer <p> 6810 1.1 mbalmer Checks whether the function has an argument 6811 1.2 lneto of any type (including <b>nil</b>) at position <code>arg</code>. 6812 1.1 mbalmer 6813 1.1 mbalmer 6814 1.1 mbalmer 6815 1.1 mbalmer 6816 1.1 mbalmer 6817 1.1 mbalmer <hr><h3><a name="luaL_checkinteger"><code>luaL_checkinteger</code></a></h3><p> 6818 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 6819 1.2 lneto <pre>lua_Integer luaL_checkinteger (lua_State *L, int arg);</pre> 6820 1.1 mbalmer 6821 1.1 mbalmer <p> 6822 1.2 lneto Checks whether the function argument <code>arg</code> is an integer 6823 1.2 lneto (or can be converted to an integer) 6824 1.9 nikita and returns this integer. 6825 1.1 mbalmer 6826 1.1 mbalmer 6827 1.1 mbalmer 6828 1.1 mbalmer 6829 1.1 mbalmer 6830 1.1 mbalmer <hr><h3><a name="luaL_checklstring"><code>luaL_checklstring</code></a></h3><p> 6831 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 6832 1.2 lneto <pre>const char *luaL_checklstring (lua_State *L, int arg, size_t *l);</pre> 6833 1.1 mbalmer 6834 1.1 mbalmer <p> 6835 1.2 lneto Checks whether the function argument <code>arg</code> is a string 6836 1.1 mbalmer and returns this string; 6837 1.9 nikita if <code>l</code> is not <code>NULL</code> fills its referent 6838 1.1 mbalmer with the string's length. 6839 1.1 mbalmer 6840 1.1 mbalmer 6841 1.1 mbalmer <p> 6842 1.1 mbalmer This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, 6843 1.1 mbalmer so all conversions and caveats of that function apply here. 6844 1.1 mbalmer 6845 1.1 mbalmer 6846 1.1 mbalmer 6847 1.1 mbalmer 6848 1.1 mbalmer 6849 1.1 mbalmer <hr><h3><a name="luaL_checknumber"><code>luaL_checknumber</code></a></h3><p> 6850 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 6851 1.2 lneto <pre>lua_Number luaL_checknumber (lua_State *L, int arg);</pre> 6852 1.1 mbalmer 6853 1.1 mbalmer <p> 6854 1.2 lneto Checks whether the function argument <code>arg</code> is a number 6855 1.9 nikita and returns this number converted to a <code>lua_Number</code>. 6856 1.1 mbalmer 6857 1.1 mbalmer 6858 1.1 mbalmer 6859 1.1 mbalmer 6860 1.1 mbalmer 6861 1.1 mbalmer <hr><h3><a name="luaL_checkoption"><code>luaL_checkoption</code></a></h3><p> 6862 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 6863 1.1 mbalmer <pre>int luaL_checkoption (lua_State *L, 6864 1.2 lneto int arg, 6865 1.1 mbalmer const char *def, 6866 1.1 mbalmer const char *const lst[]);</pre> 6867 1.1 mbalmer 6868 1.1 mbalmer <p> 6869 1.2 lneto Checks whether the function argument <code>arg</code> is a string and 6870 1.1 mbalmer searches for this string in the array <code>lst</code> 6871 1.1 mbalmer (which must be NULL-terminated). 6872 1.1 mbalmer Returns the index in the array where the string was found. 6873 1.1 mbalmer Raises an error if the argument is not a string or 6874 1.1 mbalmer if the string cannot be found. 6875 1.1 mbalmer 6876 1.1 mbalmer 6877 1.1 mbalmer <p> 6878 1.1 mbalmer If <code>def</code> is not <code>NULL</code>, 6879 1.1 mbalmer the function uses <code>def</code> as a default value when 6880 1.2 lneto there is no argument <code>arg</code> or when this argument is <b>nil</b>. 6881 1.1 mbalmer 6882 1.1 mbalmer 6883 1.1 mbalmer <p> 6884 1.1 mbalmer This is a useful function for mapping strings to C enums. 6885 1.1 mbalmer (The usual convention in Lua libraries is 6886 1.1 mbalmer to use strings instead of numbers to select options.) 6887 1.1 mbalmer 6888 1.1 mbalmer 6889 1.1 mbalmer 6890 1.1 mbalmer 6891 1.1 mbalmer 6892 1.1 mbalmer <hr><h3><a name="luaL_checkstack"><code>luaL_checkstack</code></a></h3><p> 6893 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 6894 1.1 mbalmer <pre>void luaL_checkstack (lua_State *L, int sz, const char *msg);</pre> 6895 1.1 mbalmer 6896 1.1 mbalmer <p> 6897 1.1 mbalmer Grows the stack size to <code>top + sz</code> elements, 6898 1.1 mbalmer raising an error if the stack cannot grow to that size. 6899 1.2 lneto <code>msg</code> is an additional text to go into the error message 6900 1.2 lneto (or <code>NULL</code> for no additional text). 6901 1.1 mbalmer 6902 1.1 mbalmer 6903 1.1 mbalmer 6904 1.1 mbalmer 6905 1.1 mbalmer 6906 1.1 mbalmer <hr><h3><a name="luaL_checkstring"><code>luaL_checkstring</code></a></h3><p> 6907 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 6908 1.2 lneto <pre>const char *luaL_checkstring (lua_State *L, int arg);</pre> 6909 1.1 mbalmer 6910 1.1 mbalmer <p> 6911 1.2 lneto Checks whether the function argument <code>arg</code> is a string 6912 1.1 mbalmer and returns this string. 6913 1.1 mbalmer 6914 1.1 mbalmer 6915 1.1 mbalmer <p> 6916 1.1 mbalmer This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, 6917 1.1 mbalmer so all conversions and caveats of that function apply here. 6918 1.1 mbalmer 6919 1.1 mbalmer 6920 1.1 mbalmer 6921 1.1 mbalmer 6922 1.1 mbalmer 6923 1.1 mbalmer <hr><h3><a name="luaL_checktype"><code>luaL_checktype</code></a></h3><p> 6924 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 6925 1.2 lneto <pre>void luaL_checktype (lua_State *L, int arg, int t);</pre> 6926 1.1 mbalmer 6927 1.1 mbalmer <p> 6928 1.2 lneto Checks whether the function argument <code>arg</code> has type <code>t</code>. 6929 1.1 mbalmer See <a href="#lua_type"><code>lua_type</code></a> for the encoding of types for <code>t</code>. 6930 1.1 mbalmer 6931 1.1 mbalmer 6932 1.1 mbalmer 6933 1.1 mbalmer 6934 1.1 mbalmer 6935 1.1 mbalmer <hr><h3><a name="luaL_checkudata"><code>luaL_checkudata</code></a></h3><p> 6936 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 6937 1.2 lneto <pre>void *luaL_checkudata (lua_State *L, int arg, const char *tname);</pre> 6938 1.2 lneto 6939 1.2 lneto <p> 6940 1.2 lneto Checks whether the function argument <code>arg</code> is a userdata 6941 1.2 lneto of the type <code>tname</code> (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>) and 6942 1.9 nikita returns the userdata's memory-block address (see <a href="#lua_touserdata"><code>lua_touserdata</code></a>). 6943 1.2 lneto 6944 1.2 lneto 6945 1.2 lneto 6946 1.2 lneto 6947 1.2 lneto 6948 1.2 lneto <hr><h3><a name="luaL_checkversion"><code>luaL_checkversion</code></a></h3><p> 6949 1.6 salazar <span class="apii">[-0, +0, <em>v</em>]</span> 6950 1.2 lneto <pre>void luaL_checkversion (lua_State *L);</pre> 6951 1.1 mbalmer 6952 1.1 mbalmer <p> 6953 1.9 nikita Checks whether the code making the call and the Lua library being called 6954 1.9 nikita are using the same version of Lua and the same numeric types. 6955 1.1 mbalmer 6956 1.1 mbalmer 6957 1.1 mbalmer 6958 1.1 mbalmer 6959 1.1 mbalmer 6960 1.1 mbalmer <hr><h3><a name="luaL_dofile"><code>luaL_dofile</code></a></h3><p> 6961 1.9 nikita <span class="apii">[-0, +?, <em>m</em>]</span> 6962 1.1 mbalmer <pre>int luaL_dofile (lua_State *L, const char *filename);</pre> 6963 1.1 mbalmer 6964 1.1 mbalmer <p> 6965 1.1 mbalmer Loads and runs the given file. 6966 1.1 mbalmer It is defined as the following macro: 6967 1.1 mbalmer 6968 1.1 mbalmer <pre> 6969 1.1 mbalmer (luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0)) 6970 1.1 mbalmer </pre><p> 6971 1.9 nikita It returns <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> if there are no errors, 6972 1.9 nikita or an error code in case of errors (see <a href="#4.4.1">§4.4.1</a>). 6973 1.1 mbalmer 6974 1.1 mbalmer 6975 1.1 mbalmer 6976 1.1 mbalmer 6977 1.1 mbalmer 6978 1.1 mbalmer <hr><h3><a name="luaL_dostring"><code>luaL_dostring</code></a></h3><p> 6979 1.2 lneto <span class="apii">[-0, +?, –]</span> 6980 1.1 mbalmer <pre>int luaL_dostring (lua_State *L, const char *str);</pre> 6981 1.1 mbalmer 6982 1.1 mbalmer <p> 6983 1.1 mbalmer Loads and runs the given string. 6984 1.1 mbalmer It is defined as the following macro: 6985 1.1 mbalmer 6986 1.1 mbalmer <pre> 6987 1.1 mbalmer (luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0)) 6988 1.1 mbalmer </pre><p> 6989 1.9 nikita It returns <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> if there are no errors, 6990 1.9 nikita or an error code in case of errors (see <a href="#4.4.1">§4.4.1</a>). 6991 1.1 mbalmer 6992 1.1 mbalmer 6993 1.1 mbalmer 6994 1.1 mbalmer 6995 1.1 mbalmer 6996 1.1 mbalmer <hr><h3><a name="luaL_error"><code>luaL_error</code></a></h3><p> 6997 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 6998 1.1 mbalmer <pre>int luaL_error (lua_State *L, const char *fmt, ...);</pre> 6999 1.1 mbalmer 7000 1.1 mbalmer <p> 7001 1.1 mbalmer Raises an error. 7002 1.2 lneto The error message format is given by <code>fmt</code> 7003 1.2 lneto plus any extra arguments, 7004 1.2 lneto following the same rules of <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>. 7005 1.2 lneto It also adds at the beginning of the message the file name and 7006 1.2 lneto the line number where the error occurred, 7007 1.2 lneto if this information is available. 7008 1.2 lneto 7009 1.2 lneto 7010 1.2 lneto <p> 7011 1.2 lneto This function never returns, 7012 1.2 lneto but it is an idiom to use it in C functions 7013 1.2 lneto as <code>return luaL_error(<em>args</em>)</code>. 7014 1.2 lneto 7015 1.2 lneto 7016 1.2 lneto 7017 1.2 lneto 7018 1.2 lneto 7019 1.2 lneto <hr><h3><a name="luaL_execresult"><code>luaL_execresult</code></a></h3><p> 7020 1.5 lneto <span class="apii">[-0, +3, <em>m</em>]</span> 7021 1.2 lneto <pre>int luaL_execresult (lua_State *L, int stat);</pre> 7022 1.2 lneto 7023 1.2 lneto <p> 7024 1.2 lneto This function produces the return values for 7025 1.2 lneto process-related functions in the standard library 7026 1.2 lneto (<a href="#pdf-os.execute"><code>os.execute</code></a> and <a href="#pdf-io.close"><code>io.close</code></a>). 7027 1.2 lneto 7028 1.2 lneto 7029 1.2 lneto 7030 1.2 lneto 7031 1.1 mbalmer 7032 1.2 lneto <hr><h3><a name="luaL_fileresult"><code>luaL_fileresult</code></a></h3><p> 7033 1.5 lneto <span class="apii">[-0, +(1|3), <em>m</em>]</span> 7034 1.2 lneto <pre>int luaL_fileresult (lua_State *L, int stat, const char *fname);</pre> 7035 1.1 mbalmer 7036 1.1 mbalmer <p> 7037 1.2 lneto This function produces the return values for 7038 1.2 lneto file-related functions in the standard library 7039 1.2 lneto (<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.). 7040 1.1 mbalmer 7041 1.1 mbalmer 7042 1.1 mbalmer 7043 1.1 mbalmer 7044 1.1 mbalmer 7045 1.1 mbalmer <hr><h3><a name="luaL_getmetafield"><code>luaL_getmetafield</code></a></h3><p> 7046 1.5 lneto <span class="apii">[-0, +(0|1), <em>m</em>]</span> 7047 1.1 mbalmer <pre>int luaL_getmetafield (lua_State *L, int obj, const char *e);</pre> 7048 1.1 mbalmer 7049 1.1 mbalmer <p> 7050 1.1 mbalmer Pushes onto the stack the field <code>e</code> from the metatable 7051 1.8 alnsn of the object at index <code>obj</code> and returns the type of the pushed value. 7052 1.1 mbalmer If the object does not have a metatable, 7053 1.1 mbalmer or if the metatable does not have this field, 7054 1.3 lneto pushes nothing and returns <code>LUA_TNIL</code>. 7055 1.1 mbalmer 7056 1.1 mbalmer 7057 1.1 mbalmer 7058 1.1 mbalmer 7059 1.1 mbalmer 7060 1.1 mbalmer <hr><h3><a name="luaL_getmetatable"><code>luaL_getmetatable</code></a></h3><p> 7061 1.5 lneto <span class="apii">[-0, +1, <em>m</em>]</span> 7062 1.3 lneto <pre>int luaL_getmetatable (lua_State *L, const char *tname);</pre> 7063 1.1 mbalmer 7064 1.1 mbalmer <p> 7065 1.9 nikita Pushes onto the stack the metatable associated with the name <code>tname</code> 7066 1.9 nikita in the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>), 7067 1.9 nikita or <b>nil</b> if there is no metatable associated with that name. 7068 1.4 mbalmer Returns the type of the pushed value. 7069 1.1 mbalmer 7070 1.1 mbalmer 7071 1.1 mbalmer 7072 1.1 mbalmer 7073 1.1 mbalmer 7074 1.2 lneto <hr><h3><a name="luaL_getsubtable"><code>luaL_getsubtable</code></a></h3><p> 7075 1.2 lneto <span class="apii">[-0, +1, <em>e</em>]</span> 7076 1.2 lneto <pre>int luaL_getsubtable (lua_State *L, int idx, const char *fname);</pre> 7077 1.2 lneto 7078 1.2 lneto <p> 7079 1.2 lneto Ensures that the value <code>t[fname]</code>, 7080 1.2 lneto where <code>t</code> is the value at index <code>idx</code>, 7081 1.2 lneto is a table, 7082 1.2 lneto and pushes that table onto the stack. 7083 1.2 lneto Returns true if it finds a previous table there 7084 1.2 lneto and false if it creates a new table. 7085 1.2 lneto 7086 1.2 lneto 7087 1.2 lneto 7088 1.2 lneto 7089 1.2 lneto 7090 1.1 mbalmer <hr><h3><a name="luaL_gsub"><code>luaL_gsub</code></a></h3><p> 7091 1.5 lneto <span class="apii">[-0, +1, <em>m</em>]</span> 7092 1.1 mbalmer <pre>const char *luaL_gsub (lua_State *L, 7093 1.1 mbalmer const char *s, 7094 1.1 mbalmer const char *p, 7095 1.1 mbalmer const char *r);</pre> 7096 1.1 mbalmer 7097 1.1 mbalmer <p> 7098 1.9 nikita Creates a copy of string <code>s</code>, 7099 1.9 nikita replacing any occurrence of the string <code>p</code> 7100 1.1 mbalmer with the string <code>r</code>. 7101 1.1 mbalmer Pushes the resulting string on the stack and returns it. 7102 1.1 mbalmer 7103 1.1 mbalmer 7104 1.1 mbalmer 7105 1.1 mbalmer 7106 1.1 mbalmer 7107 1.2 lneto <hr><h3><a name="luaL_len"><code>luaL_len</code></a></h3><p> 7108 1.2 lneto <span class="apii">[-0, +0, <em>e</em>]</span> 7109 1.2 lneto <pre>lua_Integer luaL_len (lua_State *L, int index);</pre> 7110 1.2 lneto 7111 1.2 lneto <p> 7112 1.2 lneto Returns the "length" of the value at the given index 7113 1.2 lneto as a number; 7114 1.2 lneto it is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">§3.4.7</a>). 7115 1.2 lneto Raises an error if the result of the operation is not an integer. 7116 1.9 nikita (This case can only happen through metamethods.) 7117 1.2 lneto 7118 1.2 lneto 7119 1.2 lneto 7120 1.2 lneto 7121 1.2 lneto 7122 1.1 mbalmer <hr><h3><a name="luaL_loadbuffer"><code>luaL_loadbuffer</code></a></h3><p> 7123 1.2 lneto <span class="apii">[-0, +1, –]</span> 7124 1.1 mbalmer <pre>int luaL_loadbuffer (lua_State *L, 7125 1.1 mbalmer const char *buff, 7126 1.1 mbalmer size_t sz, 7127 1.1 mbalmer const char *name);</pre> 7128 1.1 mbalmer 7129 1.1 mbalmer <p> 7130 1.2 lneto Equivalent to <a href="#luaL_loadbufferx"><code>luaL_loadbufferx</code></a> with <code>mode</code> equal to <code>NULL</code>. 7131 1.2 lneto 7132 1.2 lneto 7133 1.2 lneto 7134 1.2 lneto 7135 1.2 lneto 7136 1.2 lneto <hr><h3><a name="luaL_loadbufferx"><code>luaL_loadbufferx</code></a></h3><p> 7137 1.2 lneto <span class="apii">[-0, +1, –]</span> 7138 1.2 lneto <pre>int luaL_loadbufferx (lua_State *L, 7139 1.2 lneto const char *buff, 7140 1.2 lneto size_t sz, 7141 1.2 lneto const char *name, 7142 1.2 lneto const char *mode);</pre> 7143 1.2 lneto 7144 1.2 lneto <p> 7145 1.1 mbalmer Loads a buffer as a Lua chunk. 7146 1.1 mbalmer This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the 7147 1.1 mbalmer buffer pointed to by <code>buff</code> with size <code>sz</code>. 7148 1.1 mbalmer 7149 1.1 mbalmer 7150 1.1 mbalmer <p> 7151 1.1 mbalmer This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>. 7152 1.1 mbalmer <code>name</code> is the chunk name, 7153 1.1 mbalmer used for debug information and error messages. 7154 1.9 nikita The string <code>mode</code> works as in the function <a href="#lua_load"><code>lua_load</code></a>. 7155 1.1 mbalmer 7156 1.1 mbalmer 7157 1.1 mbalmer 7158 1.1 mbalmer 7159 1.1 mbalmer 7160 1.1 mbalmer <hr><h3><a name="luaL_loadfile"><code>luaL_loadfile</code></a></h3><p> 7161 1.6 salazar <span class="apii">[-0, +1, <em>m</em>]</span> 7162 1.1 mbalmer <pre>int luaL_loadfile (lua_State *L, const char *filename);</pre> 7163 1.1 mbalmer 7164 1.1 mbalmer <p> 7165 1.2 lneto Equivalent to <a href="#luaL_loadfilex"><code>luaL_loadfilex</code></a> with <code>mode</code> equal to <code>NULL</code>. 7166 1.2 lneto 7167 1.2 lneto 7168 1.2 lneto 7169 1.2 lneto 7170 1.2 lneto 7171 1.2 lneto <hr><h3><a name="luaL_loadfilex"><code>luaL_loadfilex</code></a></h3><p> 7172 1.6 salazar <span class="apii">[-0, +1, <em>m</em>]</span> 7173 1.2 lneto <pre>int luaL_loadfilex (lua_State *L, const char *filename, 7174 1.2 lneto const char *mode);</pre> 7175 1.2 lneto 7176 1.2 lneto <p> 7177 1.1 mbalmer Loads a file as a Lua chunk. 7178 1.1 mbalmer This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the file 7179 1.1 mbalmer named <code>filename</code>. 7180 1.1 mbalmer If <code>filename</code> is <code>NULL</code>, 7181 1.1 mbalmer then it loads from the standard input. 7182 1.1 mbalmer The first line in the file is ignored if it starts with a <code>#</code>. 7183 1.1 mbalmer 7184 1.1 mbalmer 7185 1.1 mbalmer <p> 7186 1.9 nikita The string <code>mode</code> works as in the function <a href="#lua_load"><code>lua_load</code></a>. 7187 1.2 lneto 7188 1.2 lneto 7189 1.2 lneto <p> 7190 1.9 nikita This function returns the same results as <a href="#lua_load"><code>lua_load</code></a> 7191 1.9 nikita or <a href="#pdf-LUA_ERRFILE"><code>LUA_ERRFILE</code></a> for file-related errors. 7192 1.1 mbalmer 7193 1.1 mbalmer 7194 1.1 mbalmer <p> 7195 1.1 mbalmer As <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk; 7196 1.1 mbalmer it does not run it. 7197 1.1 mbalmer 7198 1.1 mbalmer 7199 1.1 mbalmer 7200 1.1 mbalmer 7201 1.1 mbalmer 7202 1.1 mbalmer <hr><h3><a name="luaL_loadstring"><code>luaL_loadstring</code></a></h3><p> 7203 1.2 lneto <span class="apii">[-0, +1, –]</span> 7204 1.1 mbalmer <pre>int luaL_loadstring (lua_State *L, const char *s);</pre> 7205 1.1 mbalmer 7206 1.1 mbalmer <p> 7207 1.1 mbalmer Loads a string as a Lua chunk. 7208 1.1 mbalmer This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in 7209 1.1 mbalmer the zero-terminated string <code>s</code>. 7210 1.1 mbalmer 7211 1.1 mbalmer 7212 1.1 mbalmer <p> 7213 1.1 mbalmer This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>. 7214 1.1 mbalmer 7215 1.1 mbalmer 7216 1.1 mbalmer <p> 7217 1.1 mbalmer Also as <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk; 7218 1.1 mbalmer it does not run it. 7219 1.1 mbalmer 7220 1.1 mbalmer 7221 1.1 mbalmer 7222 1.1 mbalmer 7223 1.1 mbalmer 7224 1.2 lneto <hr><h3><a name="luaL_newlib"><code>luaL_newlib</code></a></h3><p> 7225 1.5 lneto <span class="apii">[-0, +1, <em>m</em>]</span> 7226 1.3 lneto <pre>void luaL_newlib (lua_State *L, const luaL_Reg l[]);</pre> 7227 1.2 lneto 7228 1.2 lneto <p> 7229 1.2 lneto Creates a new table and registers there 7230 1.9 nikita the functions in the list <code>l</code>. 7231 1.3 lneto 7232 1.3 lneto 7233 1.3 lneto <p> 7234 1.2 lneto It is implemented as the following macro: 7235 1.2 lneto 7236 1.2 lneto <pre> 7237 1.2 lneto (luaL_newlibtable(L,l), luaL_setfuncs(L,l,0)) 7238 1.3 lneto </pre><p> 7239 1.3 lneto The array <code>l</code> must be the actual array, 7240 1.3 lneto not a pointer to it. 7241 1.3 lneto 7242 1.2 lneto 7243 1.2 lneto 7244 1.2 lneto 7245 1.2 lneto 7246 1.2 lneto <hr><h3><a name="luaL_newlibtable"><code>luaL_newlibtable</code></a></h3><p> 7247 1.5 lneto <span class="apii">[-0, +1, <em>m</em>]</span> 7248 1.2 lneto <pre>void luaL_newlibtable (lua_State *L, const luaL_Reg l[]);</pre> 7249 1.2 lneto 7250 1.2 lneto <p> 7251 1.2 lneto Creates a new table with a size optimized 7252 1.2 lneto to store all entries in the array <code>l</code> 7253 1.2 lneto (but does not actually store them). 7254 1.2 lneto It is intended to be used in conjunction with <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a> 7255 1.2 lneto (see <a href="#luaL_newlib"><code>luaL_newlib</code></a>). 7256 1.2 lneto 7257 1.2 lneto 7258 1.2 lneto <p> 7259 1.2 lneto It is implemented as a macro. 7260 1.2 lneto The array <code>l</code> must be the actual array, 7261 1.2 lneto not a pointer to it. 7262 1.2 lneto 7263 1.2 lneto 7264 1.2 lneto 7265 1.2 lneto 7266 1.2 lneto 7267 1.1 mbalmer <hr><h3><a name="luaL_newmetatable"><code>luaL_newmetatable</code></a></h3><p> 7268 1.5 lneto <span class="apii">[-0, +1, <em>m</em>]</span> 7269 1.1 mbalmer <pre>int luaL_newmetatable (lua_State *L, const char *tname);</pre> 7270 1.1 mbalmer 7271 1.1 mbalmer <p> 7272 1.1 mbalmer If the registry already has the key <code>tname</code>, 7273 1.1 mbalmer returns 0. 7274 1.1 mbalmer Otherwise, 7275 1.1 mbalmer creates a new table to be used as a metatable for userdata, 7276 1.2 lneto adds to this new table the pair <code>__name = tname</code>, 7277 1.2 lneto adds to the registry the pair <code>[tname] = new table</code>, 7278 1.1 mbalmer and returns 1. 7279 1.1 mbalmer 7280 1.1 mbalmer 7281 1.1 mbalmer <p> 7282 1.9 nikita In both cases, 7283 1.9 nikita the function pushes onto the stack the final value associated 7284 1.1 mbalmer with <code>tname</code> in the registry. 7285 1.1 mbalmer 7286 1.1 mbalmer 7287 1.1 mbalmer 7288 1.1 mbalmer 7289 1.1 mbalmer 7290 1.1 mbalmer <hr><h3><a name="luaL_newstate"><code>luaL_newstate</code></a></h3><p> 7291 1.2 lneto <span class="apii">[-0, +0, –]</span> 7292 1.1 mbalmer <pre>lua_State *luaL_newstate (void);</pre> 7293 1.1 mbalmer 7294 1.1 mbalmer <p> 7295 1.1 mbalmer Creates a new Lua state. 7296 1.1 mbalmer It calls <a href="#lua_newstate"><code>lua_newstate</code></a> with an 7297 1.9 nikita allocator based on the standard C allocation functions 7298 1.9 nikita and then sets a warning function and a panic function (see <a href="#4.4">§4.4</a>) 7299 1.9 nikita that print messages to the standard error output. 7300 1.1 mbalmer 7301 1.1 mbalmer 7302 1.1 mbalmer <p> 7303 1.1 mbalmer Returns the new state, 7304 1.1 mbalmer or <code>NULL</code> if there is a memory allocation error. 7305 1.1 mbalmer 7306 1.1 mbalmer 7307 1.1 mbalmer 7308 1.1 mbalmer 7309 1.1 mbalmer 7310 1.1 mbalmer <hr><h3><a name="luaL_openlibs"><code>luaL_openlibs</code></a></h3><p> 7311 1.2 lneto <span class="apii">[-0, +0, <em>e</em>]</span> 7312 1.1 mbalmer <pre>void luaL_openlibs (lua_State *L);</pre> 7313 1.1 mbalmer 7314 1.1 mbalmer <p> 7315 1.1 mbalmer Opens all standard Lua libraries into the given state. 7316 1.1 mbalmer 7317 1.1 mbalmer 7318 1.1 mbalmer 7319 1.1 mbalmer 7320 1.1 mbalmer 7321 1.6 salazar <hr><h3><a name="luaL_opt"><code>luaL_opt</code></a></h3><p> 7322 1.9 nikita <span class="apii">[-0, +0, –]</span> 7323 1.6 salazar <pre>T luaL_opt (L, func, arg, dflt);</pre> 7324 1.6 salazar 7325 1.6 salazar <p> 7326 1.6 salazar This macro is defined as follows: 7327 1.6 salazar 7328 1.6 salazar <pre> 7329 1.6 salazar (lua_isnoneornil(L,(arg)) ? (dflt) : func(L,(arg))) 7330 1.6 salazar </pre><p> 7331 1.6 salazar In words, if the argument <code>arg</code> is nil or absent, 7332 1.6 salazar the macro results in the default <code>dflt</code>. 7333 1.6 salazar Otherwise, it results in the result of calling <code>func</code> 7334 1.6 salazar with the state <code>L</code> and the argument index <code>arg</code> as 7335 1.8 alnsn arguments. 7336 1.6 salazar Note that it evaluates the expression <code>dflt</code> only if needed. 7337 1.6 salazar 7338 1.6 salazar 7339 1.6 salazar 7340 1.6 salazar 7341 1.6 salazar 7342 1.1 mbalmer <hr><h3><a name="luaL_optinteger"><code>luaL_optinteger</code></a></h3><p> 7343 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 7344 1.1 mbalmer <pre>lua_Integer luaL_optinteger (lua_State *L, 7345 1.2 lneto int arg, 7346 1.1 mbalmer lua_Integer d);</pre> 7347 1.1 mbalmer 7348 1.1 mbalmer <p> 7349 1.2 lneto If the function argument <code>arg</code> is an integer 7350 1.9 nikita (or it is convertible to an integer), 7351 1.2 lneto returns this integer. 7352 1.1 mbalmer If this argument is absent or is <b>nil</b>, 7353 1.1 mbalmer returns <code>d</code>. 7354 1.1 mbalmer Otherwise, raises an error. 7355 1.1 mbalmer 7356 1.1 mbalmer 7357 1.1 mbalmer 7358 1.1 mbalmer 7359 1.1 mbalmer 7360 1.1 mbalmer <hr><h3><a name="luaL_optlstring"><code>luaL_optlstring</code></a></h3><p> 7361 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 7362 1.1 mbalmer <pre>const char *luaL_optlstring (lua_State *L, 7363 1.2 lneto int arg, 7364 1.1 mbalmer const char *d, 7365 1.1 mbalmer size_t *l);</pre> 7366 1.1 mbalmer 7367 1.1 mbalmer <p> 7368 1.2 lneto If the function argument <code>arg</code> is a string, 7369 1.1 mbalmer returns this string. 7370 1.1 mbalmer If this argument is absent or is <b>nil</b>, 7371 1.1 mbalmer returns <code>d</code>. 7372 1.1 mbalmer Otherwise, raises an error. 7373 1.1 mbalmer 7374 1.1 mbalmer 7375 1.1 mbalmer <p> 7376 1.1 mbalmer If <code>l</code> is not <code>NULL</code>, 7377 1.9 nikita fills its referent with the result's length. 7378 1.5 lneto If the result is <code>NULL</code> 7379 1.5 lneto (only possible when returning <code>d</code> and <code>d == NULL</code>), 7380 1.5 lneto its length is considered zero. 7381 1.1 mbalmer 7382 1.1 mbalmer 7383 1.7 mbalmer <p> 7384 1.7 mbalmer This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, 7385 1.7 mbalmer so all conversions and caveats of that function apply here. 7386 1.7 mbalmer 7387 1.7 mbalmer 7388 1.1 mbalmer 7389 1.1 mbalmer 7390 1.1 mbalmer 7391 1.1 mbalmer <hr><h3><a name="luaL_optnumber"><code>luaL_optnumber</code></a></h3><p> 7392 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 7393 1.2 lneto <pre>lua_Number luaL_optnumber (lua_State *L, int arg, lua_Number d);</pre> 7394 1.1 mbalmer 7395 1.1 mbalmer <p> 7396 1.2 lneto If the function argument <code>arg</code> is a number, 7397 1.9 nikita returns this number as a <code>lua_Number</code>. 7398 1.1 mbalmer If this argument is absent or is <b>nil</b>, 7399 1.1 mbalmer returns <code>d</code>. 7400 1.1 mbalmer Otherwise, raises an error. 7401 1.1 mbalmer 7402 1.1 mbalmer 7403 1.1 mbalmer 7404 1.1 mbalmer 7405 1.1 mbalmer 7406 1.1 mbalmer <hr><h3><a name="luaL_optstring"><code>luaL_optstring</code></a></h3><p> 7407 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 7408 1.1 mbalmer <pre>const char *luaL_optstring (lua_State *L, 7409 1.2 lneto int arg, 7410 1.1 mbalmer const char *d);</pre> 7411 1.1 mbalmer 7412 1.1 mbalmer <p> 7413 1.2 lneto If the function argument <code>arg</code> is a string, 7414 1.1 mbalmer returns this string. 7415 1.1 mbalmer If this argument is absent or is <b>nil</b>, 7416 1.1 mbalmer returns <code>d</code>. 7417 1.1 mbalmer Otherwise, raises an error. 7418 1.1 mbalmer 7419 1.1 mbalmer 7420 1.1 mbalmer 7421 1.1 mbalmer 7422 1.1 mbalmer 7423 1.1 mbalmer <hr><h3><a name="luaL_prepbuffer"><code>luaL_prepbuffer</code></a></h3><p> 7424 1.5 lneto <span class="apii">[-?, +?, <em>m</em>]</span> 7425 1.1 mbalmer <pre>char *luaL_prepbuffer (luaL_Buffer *B);</pre> 7426 1.1 mbalmer 7427 1.1 mbalmer <p> 7428 1.2 lneto Equivalent to <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a> 7429 1.2 lneto with the predefined size <a name="pdf-LUAL_BUFFERSIZE"><code>LUAL_BUFFERSIZE</code></a>. 7430 1.2 lneto 7431 1.2 lneto 7432 1.2 lneto 7433 1.2 lneto 7434 1.2 lneto 7435 1.2 lneto <hr><h3><a name="luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a></h3><p> 7436 1.5 lneto <span class="apii">[-?, +?, <em>m</em>]</span> 7437 1.2 lneto <pre>char *luaL_prepbuffsize (luaL_Buffer *B, size_t sz);</pre> 7438 1.2 lneto 7439 1.2 lneto <p> 7440 1.2 lneto Returns an address to a space of size <code>sz</code> 7441 1.1 mbalmer where you can copy a string to be added to buffer <code>B</code> 7442 1.1 mbalmer (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 7443 1.1 mbalmer After copying the string into this space you must call 7444 1.2 lneto <a href="#luaL_addsize"><code>luaL_addsize</code></a> with the size of the string to actually add 7445 1.1 mbalmer it to the buffer. 7446 1.1 mbalmer 7447 1.1 mbalmer 7448 1.1 mbalmer 7449 1.1 mbalmer 7450 1.1 mbalmer 7451 1.9 nikita <hr><h3><a name="luaL_pushfail"><code>luaL_pushfail</code></a></h3><p> 7452 1.9 nikita <span class="apii">[-0, +1, –]</span> 7453 1.9 nikita <pre>void luaL_pushfail (lua_State *L);</pre> 7454 1.9 nikita 7455 1.9 nikita <p> 7456 1.9 nikita Pushes the <b>fail</b> value onto the stack (see <a href="#6">§6</a>). 7457 1.9 nikita 7458 1.9 nikita 7459 1.9 nikita 7460 1.9 nikita 7461 1.9 nikita 7462 1.1 mbalmer <hr><h3><a name="luaL_pushresult"><code>luaL_pushresult</code></a></h3><p> 7463 1.5 lneto <span class="apii">[-?, +1, <em>m</em>]</span> 7464 1.1 mbalmer <pre>void luaL_pushresult (luaL_Buffer *B);</pre> 7465 1.1 mbalmer 7466 1.1 mbalmer <p> 7467 1.1 mbalmer Finishes the use of buffer <code>B</code> leaving the final string on 7468 1.1 mbalmer the top of the stack. 7469 1.1 mbalmer 7470 1.1 mbalmer 7471 1.1 mbalmer 7472 1.1 mbalmer 7473 1.1 mbalmer 7474 1.2 lneto <hr><h3><a name="luaL_pushresultsize"><code>luaL_pushresultsize</code></a></h3><p> 7475 1.5 lneto <span class="apii">[-?, +1, <em>m</em>]</span> 7476 1.2 lneto <pre>void luaL_pushresultsize (luaL_Buffer *B, size_t sz);</pre> 7477 1.2 lneto 7478 1.2 lneto <p> 7479 1.2 lneto Equivalent to the sequence <a href="#luaL_addsize"><code>luaL_addsize</code></a>, <a href="#luaL_pushresult"><code>luaL_pushresult</code></a>. 7480 1.2 lneto 7481 1.2 lneto 7482 1.2 lneto 7483 1.2 lneto 7484 1.2 lneto 7485 1.1 mbalmer <hr><h3><a name="luaL_ref"><code>luaL_ref</code></a></h3><p> 7486 1.5 lneto <span class="apii">[-1, +0, <em>m</em>]</span> 7487 1.1 mbalmer <pre>int luaL_ref (lua_State *L, int t);</pre> 7488 1.1 mbalmer 7489 1.1 mbalmer <p> 7490 1.1 mbalmer Creates and returns a <em>reference</em>, 7491 1.1 mbalmer in the table at index <code>t</code>, 7492 1.9 nikita for the object on the top of the stack (and pops the object). 7493 1.1 mbalmer 7494 1.1 mbalmer 7495 1.1 mbalmer <p> 7496 1.1 mbalmer A reference is a unique integer key. 7497 1.9 nikita As long as you do not manually add integer keys into the table <code>t</code>, 7498 1.1 mbalmer <a href="#luaL_ref"><code>luaL_ref</code></a> ensures the uniqueness of the key it returns. 7499 1.9 nikita You can retrieve an object referred by the reference <code>r</code> 7500 1.1 mbalmer by calling <code>lua_rawgeti(L, t, r)</code>. 7501 1.9 nikita The function <a href="#luaL_unref"><code>luaL_unref</code></a> frees a reference. 7502 1.1 mbalmer 7503 1.1 mbalmer 7504 1.1 mbalmer <p> 7505 1.9 nikita If the object on the top of the stack is <b>nil</b>, 7506 1.1 mbalmer <a href="#luaL_ref"><code>luaL_ref</code></a> returns the constant <a name="pdf-LUA_REFNIL"><code>LUA_REFNIL</code></a>. 7507 1.1 mbalmer The constant <a name="pdf-LUA_NOREF"><code>LUA_NOREF</code></a> is guaranteed to be different 7508 1.1 mbalmer from any reference returned by <a href="#luaL_ref"><code>luaL_ref</code></a>. 7509 1.1 mbalmer 7510 1.1 mbalmer 7511 1.1 mbalmer 7512 1.1 mbalmer 7513 1.1 mbalmer 7514 1.1 mbalmer <hr><h3><a name="luaL_Reg"><code>luaL_Reg</code></a></h3> 7515 1.1 mbalmer <pre>typedef struct luaL_Reg { 7516 1.1 mbalmer const char *name; 7517 1.1 mbalmer lua_CFunction func; 7518 1.1 mbalmer } luaL_Reg;</pre> 7519 1.1 mbalmer 7520 1.1 mbalmer <p> 7521 1.1 mbalmer Type for arrays of functions to be registered by 7522 1.2 lneto <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a>. 7523 1.1 mbalmer <code>name</code> is the function name and <code>func</code> is a pointer to 7524 1.1 mbalmer the function. 7525 1.3 lneto Any array of <a href="#luaL_Reg"><code>luaL_Reg</code></a> must end with a sentinel entry 7526 1.1 mbalmer in which both <code>name</code> and <code>func</code> are <code>NULL</code>. 7527 1.1 mbalmer 7528 1.1 mbalmer 7529 1.1 mbalmer 7530 1.1 mbalmer 7531 1.1 mbalmer 7532 1.2 lneto <hr><h3><a name="luaL_requiref"><code>luaL_requiref</code></a></h3><p> 7533 1.2 lneto <span class="apii">[-0, +1, <em>e</em>]</span> 7534 1.2 lneto <pre>void luaL_requiref (lua_State *L, const char *modname, 7535 1.2 lneto lua_CFunction openf, int glb);</pre> 7536 1.2 lneto 7537 1.2 lneto <p> 7538 1.9 nikita If <code>package.loaded[modname]</code> is not true, 7539 1.9 nikita calls the function <code>openf</code> with the string <code>modname</code> as an argument 7540 1.9 nikita and sets the call result to <code>package.loaded[modname]</code>, 7541 1.2 lneto as if that function has been called through <a href="#pdf-require"><code>require</code></a>. 7542 1.2 lneto 7543 1.2 lneto 7544 1.2 lneto <p> 7545 1.2 lneto If <code>glb</code> is true, 7546 1.9 nikita also stores the module into the global <code>modname</code>. 7547 1.2 lneto 7548 1.2 lneto 7549 1.2 lneto <p> 7550 1.3 lneto Leaves a copy of the module on the stack. 7551 1.2 lneto 7552 1.2 lneto 7553 1.2 lneto 7554 1.2 lneto 7555 1.2 lneto 7556 1.2 lneto <hr><h3><a name="luaL_setfuncs"><code>luaL_setfuncs</code></a></h3><p> 7557 1.5 lneto <span class="apii">[-nup, +0, <em>m</em>]</span> 7558 1.2 lneto <pre>void luaL_setfuncs (lua_State *L, const luaL_Reg *l, int nup);</pre> 7559 1.2 lneto 7560 1.2 lneto <p> 7561 1.2 lneto Registers all functions in the array <code>l</code> 7562 1.2 lneto (see <a href="#luaL_Reg"><code>luaL_Reg</code></a>) into the table on the top of the stack 7563 1.2 lneto (below optional upvalues, see next). 7564 1.2 lneto 7565 1.1 mbalmer 7566 1.1 mbalmer <p> 7567 1.2 lneto When <code>nup</code> is not zero, 7568 1.9 nikita all functions are created with <code>nup</code> upvalues, 7569 1.9 nikita initialized with copies of the <code>nup</code> values 7570 1.9 nikita previously pushed on the stack 7571 1.2 lneto on top of the library table. 7572 1.2 lneto These values are popped from the stack after the registration. 7573 1.1 mbalmer 7574 1.1 mbalmer 7575 1.9 nikita <p> 7576 1.9 nikita A function with a <code>NULL</code> value represents a placeholder, 7577 1.9 nikita which is filled with <b>false</b>. 7578 1.9 nikita 7579 1.9 nikita 7580 1.2 lneto 7581 1.2 lneto 7582 1.2 lneto 7583 1.2 lneto <hr><h3><a name="luaL_setmetatable"><code>luaL_setmetatable</code></a></h3><p> 7584 1.2 lneto <span class="apii">[-0, +0, –]</span> 7585 1.2 lneto <pre>void luaL_setmetatable (lua_State *L, const char *tname);</pre> 7586 1.2 lneto 7587 1.2 lneto <p> 7588 1.9 nikita Sets the metatable of the object on the top of the stack 7589 1.2 lneto as the metatable associated with name <code>tname</code> 7590 1.2 lneto in the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). 7591 1.2 lneto 7592 1.2 lneto 7593 1.2 lneto 7594 1.2 lneto 7595 1.2 lneto 7596 1.2 lneto <hr><h3><a name="luaL_Stream"><code>luaL_Stream</code></a></h3> 7597 1.2 lneto <pre>typedef struct luaL_Stream { 7598 1.2 lneto FILE *f; 7599 1.2 lneto lua_CFunction closef; 7600 1.2 lneto } luaL_Stream;</pre> 7601 1.2 lneto 7602 1.1 mbalmer <p> 7603 1.9 nikita The standard representation for file handles 7604 1.9 nikita used by the standard I/O library. 7605 1.1 mbalmer 7606 1.1 mbalmer 7607 1.1 mbalmer <p> 7608 1.2 lneto A file handle is implemented as a full userdata, 7609 1.3 lneto with a metatable called <code>LUA_FILEHANDLE</code> 7610 1.3 lneto (where <code>LUA_FILEHANDLE</code> is a macro with the actual metatable's name). 7611 1.2 lneto The metatable is created by the I/O library 7612 1.2 lneto (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). 7613 1.2 lneto 7614 1.2 lneto 7615 1.2 lneto <p> 7616 1.2 lneto This userdata must start with the structure <code>luaL_Stream</code>; 7617 1.2 lneto it can contain other data after this initial structure. 7618 1.9 nikita The field <code>f</code> points to the corresponding C stream 7619 1.2 lneto (or it can be <code>NULL</code> to indicate an incompletely created handle). 7620 1.9 nikita The field <code>closef</code> points to a Lua function 7621 1.2 lneto that will be called to close the stream 7622 1.2 lneto when the handle is closed or collected; 7623 1.2 lneto this function receives the file handle as its sole argument and 7624 1.9 nikita must return either a true value, in case of success, 7625 1.9 nikita or a false value plus an error message, in case of error. 7626 1.2 lneto Once Lua calls this field, 7627 1.5 lneto it changes the field value to <code>NULL</code> 7628 1.3 lneto to signal that the handle is closed. 7629 1.2 lneto 7630 1.1 mbalmer 7631 1.1 mbalmer 7632 1.2 lneto 7633 1.2 lneto 7634 1.2 lneto <hr><h3><a name="luaL_testudata"><code>luaL_testudata</code></a></h3><p> 7635 1.5 lneto <span class="apii">[-0, +0, <em>m</em>]</span> 7636 1.2 lneto <pre>void *luaL_testudata (lua_State *L, int arg, const char *tname);</pre> 7637 1.2 lneto 7638 1.1 mbalmer <p> 7639 1.2 lneto This function works like <a href="#luaL_checkudata"><code>luaL_checkudata</code></a>, 7640 1.2 lneto except that, when the test fails, 7641 1.2 lneto it returns <code>NULL</code> instead of raising an error. 7642 1.1 mbalmer 7643 1.1 mbalmer 7644 1.1 mbalmer 7645 1.1 mbalmer 7646 1.1 mbalmer 7647 1.2 lneto <hr><h3><a name="luaL_tolstring"><code>luaL_tolstring</code></a></h3><p> 7648 1.2 lneto <span class="apii">[-0, +1, <em>e</em>]</span> 7649 1.2 lneto <pre>const char *luaL_tolstring (lua_State *L, int idx, size_t *len);</pre> 7650 1.2 lneto 7651 1.2 lneto <p> 7652 1.2 lneto Converts any Lua value at the given index to a C string 7653 1.2 lneto in a reasonable format. 7654 1.2 lneto The resulting string is pushed onto the stack and also 7655 1.9 nikita returned by the function (see <a href="#4.1.3">§4.1.3</a>). 7656 1.2 lneto If <code>len</code> is not <code>NULL</code>, 7657 1.2 lneto the function also sets <code>*len</code> with the string length. 7658 1.2 lneto 7659 1.1 mbalmer 7660 1.1 mbalmer <p> 7661 1.6 salazar If the value has a metatable with a <code>__tostring</code> field, 7662 1.2 lneto then <code>luaL_tolstring</code> calls the corresponding metamethod 7663 1.2 lneto with the value as argument, 7664 1.2 lneto and uses the result of the call as its result. 7665 1.1 mbalmer 7666 1.1 mbalmer 7667 1.1 mbalmer 7668 1.1 mbalmer 7669 1.1 mbalmer 7670 1.2 lneto <hr><h3><a name="luaL_traceback"><code>luaL_traceback</code></a></h3><p> 7671 1.5 lneto <span class="apii">[-0, +1, <em>m</em>]</span> 7672 1.2 lneto <pre>void luaL_traceback (lua_State *L, lua_State *L1, const char *msg, 7673 1.2 lneto int level);</pre> 7674 1.1 mbalmer 7675 1.1 mbalmer <p> 7676 1.2 lneto Creates and pushes a traceback of the stack <code>L1</code>. 7677 1.9 nikita If <code>msg</code> is not <code>NULL</code>, it is appended 7678 1.2 lneto at the beginning of the traceback. 7679 1.2 lneto The <code>level</code> parameter tells at which level 7680 1.2 lneto to start the traceback. 7681 1.1 mbalmer 7682 1.2 lneto 7683 1.2 lneto 7684 1.2 lneto 7685 1.2 lneto 7686 1.9 nikita <hr><h3><a name="luaL_typeerror"><code>luaL_typeerror</code></a></h3><p> 7687 1.9 nikita <span class="apii">[-0, +0, <em>v</em>]</span> 7688 1.9 nikita <pre>const char *luaL_typeerror (lua_State *L, 7689 1.9 nikita int arg, 7690 1.9 nikita const char *tname);</pre> 7691 1.9 nikita 7692 1.9 nikita <p> 7693 1.9 nikita Raises a type error for the argument <code>arg</code> 7694 1.9 nikita of the C function that called it, 7695 1.9 nikita using a standard message; 7696 1.9 nikita <code>tname</code> is a "name" for the expected type. 7697 1.9 nikita This function never returns. 7698 1.9 nikita 7699 1.9 nikita 7700 1.9 nikita 7701 1.9 nikita 7702 1.9 nikita 7703 1.2 lneto <hr><h3><a name="luaL_typename"><code>luaL_typename</code></a></h3><p> 7704 1.2 lneto <span class="apii">[-0, +0, –]</span> 7705 1.2 lneto <pre>const char *luaL_typename (lua_State *L, int index);</pre> 7706 1.2 lneto 7707 1.2 lneto <p> 7708 1.2 lneto Returns the name of the type of the value at the given index. 7709 1.1 mbalmer 7710 1.1 mbalmer 7711 1.1 mbalmer 7712 1.1 mbalmer 7713 1.1 mbalmer 7714 1.1 mbalmer <hr><h3><a name="luaL_unref"><code>luaL_unref</code></a></h3><p> 7715 1.2 lneto <span class="apii">[-0, +0, –]</span> 7716 1.1 mbalmer <pre>void luaL_unref (lua_State *L, int t, int ref);</pre> 7717 1.1 mbalmer 7718 1.1 mbalmer <p> 7719 1.9 nikita Releases the reference <code>ref</code> from the table at index <code>t</code> 7720 1.1 mbalmer (see <a href="#luaL_ref"><code>luaL_ref</code></a>). 7721 1.1 mbalmer The entry is removed from the table, 7722 1.1 mbalmer so that the referred object can be collected. 7723 1.1 mbalmer The reference <code>ref</code> is also freed to be used again. 7724 1.1 mbalmer 7725 1.1 mbalmer 7726 1.1 mbalmer <p> 7727 1.1 mbalmer If <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>, 7728 1.1 mbalmer <a href="#luaL_unref"><code>luaL_unref</code></a> does nothing. 7729 1.1 mbalmer 7730 1.1 mbalmer 7731 1.1 mbalmer 7732 1.1 mbalmer 7733 1.1 mbalmer 7734 1.1 mbalmer <hr><h3><a name="luaL_where"><code>luaL_where</code></a></h3><p> 7735 1.5 lneto <span class="apii">[-0, +1, <em>m</em>]</span> 7736 1.1 mbalmer <pre>void luaL_where (lua_State *L, int lvl);</pre> 7737 1.1 mbalmer 7738 1.1 mbalmer <p> 7739 1.1 mbalmer Pushes onto the stack a string identifying the current position 7740 1.1 mbalmer of the control at level <code>lvl</code> in the call stack. 7741 1.1 mbalmer Typically this string has the following format: 7742 1.1 mbalmer 7743 1.1 mbalmer <pre> 7744 1.1 mbalmer <em>chunkname</em>:<em>currentline</em>: 7745 1.1 mbalmer </pre><p> 7746 1.1 mbalmer Level 0 is the running function, 7747 1.1 mbalmer level 1 is the function that called the running function, 7748 1.1 mbalmer etc. 7749 1.1 mbalmer 7750 1.1 mbalmer 7751 1.1 mbalmer <p> 7752 1.1 mbalmer This function is used to build a prefix for error messages. 7753 1.1 mbalmer 7754 1.1 mbalmer 7755 1.1 mbalmer 7756 1.1 mbalmer 7757 1.1 mbalmer 7758 1.1 mbalmer 7759 1.1 mbalmer 7760 1.9 nikita <h1>6 – <a name="6">The Standard Libraries</a></h1> 7761 1.9 nikita 7762 1.9 nikita 7763 1.1 mbalmer 7764 1.1 mbalmer <p> 7765 1.1 mbalmer The standard Lua libraries provide useful functions 7766 1.9 nikita that are implemented in C through the C API. 7767 1.1 mbalmer Some of these functions provide essential services to the language 7768 1.1 mbalmer (e.g., <a href="#pdf-type"><code>type</code></a> and <a href="#pdf-getmetatable"><code>getmetatable</code></a>); 7769 1.9 nikita others provide access to outside services (e.g., I/O); 7770 1.1 mbalmer and others could be implemented in Lua itself, 7771 1.9 nikita but that for different reasons 7772 1.1 mbalmer deserve an implementation in C (e.g., <a href="#pdf-table.sort"><code>table.sort</code></a>). 7773 1.1 mbalmer 7774 1.1 mbalmer 7775 1.1 mbalmer <p> 7776 1.1 mbalmer All libraries are implemented through the official C API 7777 1.1 mbalmer and are provided as separate C modules. 7778 1.9 nikita Unless otherwise noted, 7779 1.9 nikita these library functions do not adjust its number of arguments 7780 1.9 nikita to its expected parameters. 7781 1.9 nikita For instance, a function documented as <code>foo(arg)</code> 7782 1.9 nikita should not be called without an argument. 7783 1.9 nikita 7784 1.9 nikita 7785 1.9 nikita <p> 7786 1.9 nikita The notation <b>fail</b> means a false value representing 7787 1.9 nikita some kind of failure. 7788 1.9 nikita (Currently, <b>fail</b> is equal to <b>nil</b>, 7789 1.9 nikita but that may change in future versions. 7790 1.9 nikita The recommendation is to always test the success of these functions 7791 1.9 nikita with <code>(not status)</code>, instead of <code>(status == nil)</code>.) 7792 1.9 nikita 7793 1.9 nikita 7794 1.9 nikita <p> 7795 1.1 mbalmer Currently, Lua has the following standard libraries: 7796 1.1 mbalmer 7797 1.1 mbalmer <ul> 7798 1.1 mbalmer 7799 1.2 lneto <li>basic library (<a href="#6.1">§6.1</a>);</li> 7800 1.1 mbalmer 7801 1.2 lneto <li>coroutine library (<a href="#6.2">§6.2</a>);</li> 7802 1.1 mbalmer 7803 1.2 lneto <li>package library (<a href="#6.3">§6.3</a>);</li> 7804 1.1 mbalmer 7805 1.2 lneto <li>string manipulation (<a href="#6.4">§6.4</a>);</li> 7806 1.1 mbalmer 7807 1.2 lneto <li>basic UTF-8 support (<a href="#6.5">§6.5</a>);</li> 7808 1.1 mbalmer 7809 1.2 lneto <li>table manipulation (<a href="#6.6">§6.6</a>);</li> 7810 1.1 mbalmer 7811 1.2 lneto <li>mathematical functions (<a href="#6.7">§6.7</a>) (sin, log, etc.);</li> 7812 1.1 mbalmer 7813 1.2 lneto <li>input and output (<a href="#6.8">§6.8</a>);</li> 7814 1.2 lneto 7815 1.2 lneto <li>operating system facilities (<a href="#6.9">§6.9</a>);</li> 7816 1.2 lneto 7817 1.2 lneto <li>debug facilities (<a href="#6.10">§6.10</a>).</li> 7818 1.1 mbalmer 7819 1.1 mbalmer </ul><p> 7820 1.2 lneto Except for the basic and the package libraries, 7821 1.1 mbalmer each library provides all its functions as fields of a global table 7822 1.1 mbalmer or as methods of its objects. 7823 1.1 mbalmer 7824 1.1 mbalmer 7825 1.1 mbalmer <p> 7826 1.1 mbalmer To have access to these libraries, 7827 1.1 mbalmer the C host program should call the <a href="#luaL_openlibs"><code>luaL_openlibs</code></a> function, 7828 1.1 mbalmer which opens all standard libraries. 7829 1.1 mbalmer Alternatively, 7830 1.2 lneto the host program can open them individually by using 7831 1.2 lneto <a href="#luaL_requiref"><code>luaL_requiref</code></a> to call 7832 1.1 mbalmer <a name="pdf-luaopen_base"><code>luaopen_base</code></a> (for the basic library), 7833 1.1 mbalmer <a name="pdf-luaopen_package"><code>luaopen_package</code></a> (for the package library), 7834 1.2 lneto <a name="pdf-luaopen_coroutine"><code>luaopen_coroutine</code></a> (for the coroutine library), 7835 1.1 mbalmer <a name="pdf-luaopen_string"><code>luaopen_string</code></a> (for the string library), 7836 1.9 nikita <a name="pdf-luaopen_utf8"><code>luaopen_utf8</code></a> (for the UTF-8 library), 7837 1.1 mbalmer <a name="pdf-luaopen_table"><code>luaopen_table</code></a> (for the table library), 7838 1.1 mbalmer <a name="pdf-luaopen_math"><code>luaopen_math</code></a> (for the mathematical library), 7839 1.1 mbalmer <a name="pdf-luaopen_io"><code>luaopen_io</code></a> (for the I/O library), 7840 1.3 lneto <a name="pdf-luaopen_os"><code>luaopen_os</code></a> (for the operating system library), 7841 1.1 mbalmer and <a name="pdf-luaopen_debug"><code>luaopen_debug</code></a> (for the debug library). 7842 1.2 lneto These functions are declared in <a name="pdf-lualib.h"><code>lualib.h</code></a>. 7843 1.1 mbalmer 7844 1.1 mbalmer 7845 1.1 mbalmer 7846 1.9 nikita 7847 1.9 nikita 7848 1.2 lneto <h2>6.1 – <a name="6.1">Basic Functions</a></h2> 7849 1.1 mbalmer 7850 1.1 mbalmer <p> 7851 1.2 lneto The basic library provides core functions to Lua. 7852 1.1 mbalmer If you do not include this library in your application, 7853 1.2 lneto you should check carefully whether you need to provide 7854 1.1 mbalmer implementations for some of its facilities. 7855 1.1 mbalmer 7856 1.1 mbalmer 7857 1.1 mbalmer <p> 7858 1.1 mbalmer <hr><h3><a name="pdf-assert"><code>assert (v [, message])</code></a></h3> 7859 1.2 lneto 7860 1.2 lneto 7861 1.2 lneto <p> 7862 1.9 nikita Raises an error if 7863 1.1 mbalmer the value of its argument <code>v</code> is false (i.e., <b>nil</b> or <b>false</b>); 7864 1.1 mbalmer otherwise, returns all its arguments. 7865 1.2 lneto In case of error, 7866 1.2 lneto <code>message</code> is the error object; 7867 1.2 lneto when absent, it defaults to "<code>assertion failed!</code>" 7868 1.1 mbalmer 7869 1.1 mbalmer 7870 1.1 mbalmer 7871 1.1 mbalmer 7872 1.1 mbalmer <p> 7873 1.2 lneto <hr><h3><a name="pdf-collectgarbage"><code>collectgarbage ([opt [, arg]])</code></a></h3> 7874 1.1 mbalmer 7875 1.1 mbalmer 7876 1.1 mbalmer <p> 7877 1.1 mbalmer This function is a generic interface to the garbage collector. 7878 1.1 mbalmer It performs different functions according to its first argument, <code>opt</code>: 7879 1.1 mbalmer 7880 1.1 mbalmer <ul> 7881 1.1 mbalmer 7882 1.2 lneto <li><b>"<code>collect</code>": </b> 7883 1.9 nikita Performs a full garbage-collection cycle. 7884 1.2 lneto This is the default option. 7885 1.1 mbalmer </li> 7886 1.1 mbalmer 7887 1.2 lneto <li><b>"<code>stop</code>": </b> 7888 1.9 nikita Stops automatic execution of the garbage collector. 7889 1.2 lneto The collector will run only when explicitly invoked, 7890 1.2 lneto until a call to restart it. 7891 1.1 mbalmer </li> 7892 1.1 mbalmer 7893 1.2 lneto <li><b>"<code>restart</code>": </b> 7894 1.9 nikita Restarts automatic execution of the garbage collector. 7895 1.1 mbalmer </li> 7896 1.1 mbalmer 7897 1.2 lneto <li><b>"<code>count</code>": </b> 7898 1.9 nikita Returns the total memory in use by Lua in Kbytes. 7899 1.2 lneto The value has a fractional part, 7900 1.2 lneto so that it multiplied by 1024 7901 1.9 nikita gives the exact number of bytes in use by Lua. 7902 1.1 mbalmer </li> 7903 1.1 mbalmer 7904 1.2 lneto <li><b>"<code>step</code>": </b> 7905 1.9 nikita Performs a garbage-collection step. 7906 1.2 lneto The step "size" is controlled by <code>arg</code>. 7907 1.2 lneto With a zero value, 7908 1.2 lneto the collector will perform one basic (indivisible) step. 7909 1.2 lneto For non-zero values, 7910 1.2 lneto the collector will perform as if that amount of memory 7911 1.9 nikita (in Kbytes) had been allocated by Lua. 7912 1.1 mbalmer Returns <b>true</b> if the step finished a collection cycle. 7913 1.1 mbalmer </li> 7914 1.1 mbalmer 7915 1.9 nikita <li><b>"<code>isrunning</code>": </b> 7916 1.9 nikita Returns a boolean that tells whether the collector is running 7917 1.9 nikita (i.e., not stopped). 7918 1.1 mbalmer </li> 7919 1.1 mbalmer 7920 1.9 nikita <li><b>"<code>incremental</code>": </b> 7921 1.9 nikita Change the collector mode to incremental. 7922 1.9 nikita This option can be followed by three numbers: 7923 1.9 nikita the garbage-collector pause, 7924 1.9 nikita the step multiplier, 7925 1.9 nikita and the step size (see <a href="#2.5.1">§2.5.1</a>). 7926 1.9 nikita A zero means to not change that value. 7927 1.1 mbalmer </li> 7928 1.1 mbalmer 7929 1.9 nikita <li><b>"<code>generational</code>": </b> 7930 1.9 nikita Change the collector mode to generational. 7931 1.9 nikita This option can be followed by two numbers: 7932 1.9 nikita the garbage-collector minor multiplier 7933 1.9 nikita and the major multiplier (see <a href="#2.5.2">§2.5.2</a>). 7934 1.9 nikita A zero means to not change that value. 7935 1.2 lneto </li> 7936 1.2 lneto 7937 1.9 nikita </ul><p> 7938 1.9 nikita See <a href="#2.5">§2.5</a> for more details about garbage collection 7939 1.9 nikita and some of these options. 7940 1.9 nikita 7941 1.9 nikita 7942 1.9 nikita <p> 7943 1.9 nikita This function should not be called by a finalizer. 7944 1.9 nikita 7945 1.1 mbalmer 7946 1.1 mbalmer 7947 1.1 mbalmer 7948 1.1 mbalmer <p> 7949 1.2 lneto <hr><h3><a name="pdf-dofile"><code>dofile ([filename])</code></a></h3> 7950 1.9 nikita Opens the named file and executes its content as a Lua chunk. 7951 1.1 mbalmer When called without arguments, 7952 1.9 nikita <code>dofile</code> executes the content of the standard input (<code>stdin</code>). 7953 1.1 mbalmer Returns all values returned by the chunk. 7954 1.1 mbalmer In case of errors, <code>dofile</code> propagates the error 7955 1.9 nikita to its caller. 7956 1.9 nikita (That is, <code>dofile</code> does not run in protected mode.) 7957 1.1 mbalmer 7958 1.1 mbalmer 7959 1.1 mbalmer 7960 1.1 mbalmer 7961 1.1 mbalmer <p> 7962 1.1 mbalmer <hr><h3><a name="pdf-error"><code>error (message [, level])</code></a></h3> 7963 1.9 nikita Raises an error (see <a href="#2.3">§2.3</a>) with <code>message</code> as the error object. 7964 1.9 nikita This function never returns. 7965 1.1 mbalmer 7966 1.1 mbalmer 7967 1.1 mbalmer <p> 7968 1.1 mbalmer Usually, <code>error</code> adds some information about the error position 7969 1.2 lneto at the beginning of the message, if the message is a string. 7970 1.1 mbalmer The <code>level</code> argument specifies how to get the error position. 7971 1.1 mbalmer With level 1 (the default), the error position is where the 7972 1.1 mbalmer <code>error</code> function was called. 7973 1.1 mbalmer Level 2 points the error to where the function 7974 1.1 mbalmer that called <code>error</code> was called; and so on. 7975 1.1 mbalmer Passing a level 0 avoids the addition of error position information 7976 1.1 mbalmer to the message. 7977 1.1 mbalmer 7978 1.1 mbalmer 7979 1.1 mbalmer 7980 1.1 mbalmer 7981 1.1 mbalmer <p> 7982 1.1 mbalmer <hr><h3><a name="pdf-_G"><code>_G</code></a></h3> 7983 1.1 mbalmer A global variable (not a function) that 7984 1.2 lneto holds the global environment (see <a href="#2.2">§2.2</a>). 7985 1.1 mbalmer Lua itself does not use this variable; 7986 1.1 mbalmer changing its value does not affect any environment, 7987 1.2 lneto nor vice versa. 7988 1.1 mbalmer 7989 1.1 mbalmer 7990 1.1 mbalmer 7991 1.1 mbalmer 7992 1.1 mbalmer <p> 7993 1.1 mbalmer <hr><h3><a name="pdf-getmetatable"><code>getmetatable (object)</code></a></h3> 7994 1.1 mbalmer 7995 1.1 mbalmer 7996 1.1 mbalmer <p> 7997 1.1 mbalmer If <code>object</code> does not have a metatable, returns <b>nil</b>. 7998 1.1 mbalmer Otherwise, 7999 1.6 salazar if the object's metatable has a <code>__metatable</code> field, 8000 1.1 mbalmer returns the associated value. 8001 1.1 mbalmer Otherwise, returns the metatable of the given object. 8002 1.1 mbalmer 8003 1.1 mbalmer 8004 1.1 mbalmer 8005 1.1 mbalmer 8006 1.1 mbalmer <p> 8007 1.1 mbalmer <hr><h3><a name="pdf-ipairs"><code>ipairs (t)</code></a></h3> 8008 1.1 mbalmer 8009 1.1 mbalmer 8010 1.1 mbalmer <p> 8011 1.3 lneto Returns three values (an iterator function, the table <code>t</code>, and 0) 8012 1.1 mbalmer so that the construction 8013 1.1 mbalmer 8014 1.1 mbalmer <pre> 8015 1.1 mbalmer for i,v in ipairs(t) do <em>body</em> end 8016 1.1 mbalmer </pre><p> 8017 1.3 lneto will iterate over the key–value pairs 8018 1.3 lneto (<code>1,t[1]</code>), (<code>2,t[2]</code>), ..., 8019 1.9 nikita up to the first absent index. 8020 1.1 mbalmer 8021 1.1 mbalmer 8022 1.1 mbalmer 8023 1.1 mbalmer 8024 1.1 mbalmer <p> 8025 1.3 lneto <hr><h3><a name="pdf-load"><code>load (chunk [, chunkname [, mode [, env]]])</code></a></h3> 8026 1.1 mbalmer 8027 1.1 mbalmer 8028 1.1 mbalmer <p> 8029 1.2 lneto Loads a chunk. 8030 1.2 lneto 8031 1.2 lneto 8032 1.2 lneto <p> 8033 1.3 lneto If <code>chunk</code> is a string, the chunk is this string. 8034 1.3 lneto If <code>chunk</code> is a function, 8035 1.2 lneto <code>load</code> calls it repeatedly to get the chunk pieces. 8036 1.3 lneto Each call to <code>chunk</code> must return a string that concatenates 8037 1.1 mbalmer with previous results. 8038 1.1 mbalmer A return of an empty string, <b>nil</b>, or no value signals the end of the chunk. 8039 1.1 mbalmer 8040 1.1 mbalmer 8041 1.1 mbalmer <p> 8042 1.2 lneto If there are no syntactic errors, 8043 1.9 nikita <code>load</code> returns the compiled chunk as a function; 8044 1.9 nikita otherwise, it returns <b>fail</b> plus the error message. 8045 1.1 mbalmer 8046 1.1 mbalmer 8047 1.1 mbalmer <p> 8048 1.9 nikita When you load a main chunk, 8049 1.2 lneto the resulting function will always have exactly one upvalue, 8050 1.2 lneto the <code>_ENV</code> variable (see <a href="#2.2">§2.2</a>). 8051 1.3 lneto However, 8052 1.3 lneto when you load a binary chunk created from a function (see <a href="#pdf-string.dump"><code>string.dump</code></a>), 8053 1.9 nikita the resulting function can have an arbitrary number of upvalues, 8054 1.9 nikita and there is no guarantee that its first upvalue will be 8055 1.9 nikita the <code>_ENV</code> variable. 8056 1.9 nikita (A non-main function may not even have an <code>_ENV</code> upvalue.) 8057 1.9 nikita 8058 1.9 nikita 8059 1.9 nikita <p> 8060 1.9 nikita Regardless, if the resulting function has any upvalues, 8061 1.9 nikita its first upvalue is set to the value of <code>env</code>, 8062 1.9 nikita if that parameter is given, 8063 1.9 nikita or to the value of the global environment. 8064 1.9 nikita Other upvalues are initialized with <b>nil</b>. 8065 1.3 lneto All upvalues are fresh, that is, 8066 1.3 lneto they are not shared with any other function. 8067 1.1 mbalmer 8068 1.1 mbalmer 8069 1.2 lneto <p> 8070 1.3 lneto <code>chunkname</code> is used as the name of the chunk for error messages 8071 1.9 nikita and debug information (see <a href="#4.7">§4.7</a>). 8072 1.2 lneto When absent, 8073 1.3 lneto it defaults to <code>chunk</code>, if <code>chunk</code> is a string, 8074 1.2 lneto or to "<code>=(load)</code>" otherwise. 8075 1.1 mbalmer 8076 1.1 mbalmer 8077 1.1 mbalmer <p> 8078 1.2 lneto The string <code>mode</code> controls whether the chunk can be text or binary 8079 1.2 lneto (that is, a precompiled chunk). 8080 1.2 lneto It may be the string "<code>b</code>" (only binary chunks), 8081 1.2 lneto "<code>t</code>" (only text chunks), 8082 1.2 lneto or "<code>bt</code>" (both binary and text). 8083 1.2 lneto The default is "<code>bt</code>". 8084 1.1 mbalmer 8085 1.1 mbalmer 8086 1.1 mbalmer <p> 8087 1.9 nikita It is safe to load malformed binary chunks; 8088 1.9 nikita <code>load</code> signals an appropriate error. 8089 1.9 nikita However, 8090 1.9 nikita Lua does not check the consistency of the code inside binary chunks; 8091 1.9 nikita running maliciously crafted bytecode can crash the interpreter. 8092 1.1 mbalmer 8093 1.1 mbalmer 8094 1.1 mbalmer 8095 1.1 mbalmer 8096 1.1 mbalmer <p> 8097 1.2 lneto <hr><h3><a name="pdf-loadfile"><code>loadfile ([filename [, mode [, env]]])</code></a></h3> 8098 1.1 mbalmer 8099 1.1 mbalmer 8100 1.1 mbalmer <p> 8101 1.1 mbalmer Similar to <a href="#pdf-load"><code>load</code></a>, 8102 1.2 lneto but gets the chunk from file <code>filename</code> 8103 1.2 lneto or from the standard input, 8104 1.2 lneto if no file name is given. 8105 1.1 mbalmer 8106 1.1 mbalmer 8107 1.1 mbalmer 8108 1.1 mbalmer 8109 1.1 mbalmer <p> 8110 1.1 mbalmer <hr><h3><a name="pdf-next"><code>next (table [, index])</code></a></h3> 8111 1.1 mbalmer 8112 1.1 mbalmer 8113 1.1 mbalmer <p> 8114 1.1 mbalmer Allows a program to traverse all fields of a table. 8115 1.1 mbalmer Its first argument is a table and its second argument 8116 1.1 mbalmer is an index in this table. 8117 1.9 nikita A call to <code>next</code> returns the next index of the table 8118 1.1 mbalmer and its associated value. 8119 1.1 mbalmer When called with <b>nil</b> as its second argument, 8120 1.1 mbalmer <code>next</code> returns an initial index 8121 1.1 mbalmer and its associated value. 8122 1.1 mbalmer When called with the last index, 8123 1.1 mbalmer or with <b>nil</b> in an empty table, 8124 1.1 mbalmer <code>next</code> returns <b>nil</b>. 8125 1.1 mbalmer If the second argument is absent, then it is interpreted as <b>nil</b>. 8126 1.1 mbalmer In particular, 8127 1.1 mbalmer you can use <code>next(t)</code> to check whether a table is empty. 8128 1.1 mbalmer 8129 1.1 mbalmer 8130 1.1 mbalmer <p> 8131 1.1 mbalmer The order in which the indices are enumerated is not specified, 8132 1.1 mbalmer <em>even for numeric indices</em>. 8133 1.4 mbalmer (To traverse a table in numerical order, 8134 1.2 lneto use a numerical <b>for</b>.) 8135 1.1 mbalmer 8136 1.1 mbalmer 8137 1.1 mbalmer <p> 8138 1.9 nikita You should not assign any value to a non-existent field in a table 8139 1.9 nikita during its traversal. 8140 1.1 mbalmer You may however modify existing fields. 8141 1.9 nikita In particular, you may set existing fields to nil. 8142 1.1 mbalmer 8143 1.1 mbalmer 8144 1.1 mbalmer 8145 1.1 mbalmer 8146 1.1 mbalmer <p> 8147 1.1 mbalmer <hr><h3><a name="pdf-pairs"><code>pairs (t)</code></a></h3> 8148 1.1 mbalmer 8149 1.1 mbalmer 8150 1.1 mbalmer <p> 8151 1.2 lneto If <code>t</code> has a metamethod <code>__pairs</code>, 8152 1.2 lneto calls it with <code>t</code> as argument and returns the first three 8153 1.2 lneto results from the call. 8154 1.2 lneto 8155 1.2 lneto 8156 1.2 lneto <p> 8157 1.2 lneto Otherwise, 8158 1.2 lneto returns three values: the <a href="#pdf-next"><code>next</code></a> function, the table <code>t</code>, and <b>nil</b>, 8159 1.1 mbalmer so that the construction 8160 1.1 mbalmer 8161 1.1 mbalmer <pre> 8162 1.1 mbalmer for k,v in pairs(t) do <em>body</em> end 8163 1.1 mbalmer </pre><p> 8164 1.1 mbalmer will iterate over all key–value pairs of table <code>t</code>. 8165 1.1 mbalmer 8166 1.1 mbalmer 8167 1.1 mbalmer <p> 8168 1.1 mbalmer See function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying 8169 1.1 mbalmer the table during its traversal. 8170 1.1 mbalmer 8171 1.1 mbalmer 8172 1.1 mbalmer 8173 1.1 mbalmer 8174 1.1 mbalmer <p> 8175 1.2 lneto <hr><h3><a name="pdf-pcall"><code>pcall (f [, arg1, ···])</code></a></h3> 8176 1.1 mbalmer 8177 1.1 mbalmer 8178 1.1 mbalmer <p> 8179 1.9 nikita Calls the function <code>f</code> with 8180 1.1 mbalmer the given arguments in <em>protected mode</em>. 8181 1.1 mbalmer This means that any error inside <code>f</code> is not propagated; 8182 1.1 mbalmer instead, <code>pcall</code> catches the error 8183 1.1 mbalmer and returns a status code. 8184 1.1 mbalmer Its first result is the status code (a boolean), 8185 1.9 nikita which is <b>true</b> if the call succeeds without errors. 8186 1.1 mbalmer In such case, <code>pcall</code> also returns all results from the call, 8187 1.1 mbalmer after this first result. 8188 1.9 nikita In case of any error, <code>pcall</code> returns <b>false</b> plus the error object. 8189 1.9 nikita Note that errors caught by <code>pcall</code> do not call a message handler. 8190 1.1 mbalmer 8191 1.1 mbalmer 8192 1.1 mbalmer 8193 1.1 mbalmer 8194 1.1 mbalmer <p> 8195 1.1 mbalmer <hr><h3><a name="pdf-print"><code>print (···)</code></a></h3> 8196 1.2 lneto Receives any number of arguments 8197 1.1 mbalmer and prints their values to <code>stdout</code>, 8198 1.9 nikita converting each argument to a string 8199 1.9 nikita following the same rules of <a href="#pdf-tostring"><code>tostring</code></a>. 8200 1.9 nikita 8201 1.9 nikita 8202 1.9 nikita <p> 8203 1.9 nikita The function <code>print</code> is not intended for formatted output, 8204 1.1 mbalmer but only as a quick way to show a value, 8205 1.2 lneto for instance for debugging. 8206 1.2 lneto For complete control over the output, 8207 1.2 lneto use <a href="#pdf-string.format"><code>string.format</code></a> and <a href="#pdf-io.write"><code>io.write</code></a>. 8208 1.1 mbalmer 8209 1.1 mbalmer 8210 1.1 mbalmer 8211 1.1 mbalmer 8212 1.1 mbalmer <p> 8213 1.1 mbalmer <hr><h3><a name="pdf-rawequal"><code>rawequal (v1, v2)</code></a></h3> 8214 1.1 mbalmer Checks whether <code>v1</code> is equal to <code>v2</code>, 8215 1.6 salazar without invoking the <code>__eq</code> metamethod. 8216 1.1 mbalmer Returns a boolean. 8217 1.1 mbalmer 8218 1.1 mbalmer 8219 1.1 mbalmer 8220 1.1 mbalmer 8221 1.1 mbalmer <p> 8222 1.1 mbalmer <hr><h3><a name="pdf-rawget"><code>rawget (table, index)</code></a></h3> 8223 1.1 mbalmer Gets the real value of <code>table[index]</code>, 8224 1.9 nikita without using the <code>__index</code> metavalue. 8225 1.1 mbalmer <code>table</code> must be a table; 8226 1.1 mbalmer <code>index</code> may be any value. 8227 1.1 mbalmer 8228 1.1 mbalmer 8229 1.1 mbalmer 8230 1.1 mbalmer 8231 1.1 mbalmer <p> 8232 1.2 lneto <hr><h3><a name="pdf-rawlen"><code>rawlen (v)</code></a></h3> 8233 1.2 lneto Returns the length of the object <code>v</code>, 8234 1.2 lneto which must be a table or a string, 8235 1.6 salazar without invoking the <code>__len</code> metamethod. 8236 1.2 lneto Returns an integer. 8237 1.2 lneto 8238 1.2 lneto 8239 1.2 lneto 8240 1.2 lneto 8241 1.2 lneto <p> 8242 1.1 mbalmer <hr><h3><a name="pdf-rawset"><code>rawset (table, index, value)</code></a></h3> 8243 1.1 mbalmer Sets the real value of <code>table[index]</code> to <code>value</code>, 8244 1.9 nikita without using the <code>__newindex</code> metavalue. 8245 1.1 mbalmer <code>table</code> must be a table, 8246 1.2 lneto <code>index</code> any value different from <b>nil</b> and NaN, 8247 1.1 mbalmer and <code>value</code> any Lua value. 8248 1.1 mbalmer 8249 1.1 mbalmer 8250 1.1 mbalmer <p> 8251 1.1 mbalmer This function returns <code>table</code>. 8252 1.1 mbalmer 8253 1.1 mbalmer 8254 1.1 mbalmer 8255 1.1 mbalmer 8256 1.1 mbalmer <p> 8257 1.1 mbalmer <hr><h3><a name="pdf-select"><code>select (index, ···)</code></a></h3> 8258 1.1 mbalmer 8259 1.1 mbalmer 8260 1.1 mbalmer <p> 8261 1.1 mbalmer If <code>index</code> is a number, 8262 1.2 lneto returns all arguments after argument number <code>index</code>; 8263 1.2 lneto a negative number indexes from the end (-1 is the last argument). 8264 1.1 mbalmer Otherwise, <code>index</code> must be the string <code>"#"</code>, 8265 1.1 mbalmer and <code>select</code> returns the total number of extra arguments it received. 8266 1.1 mbalmer 8267 1.1 mbalmer 8268 1.1 mbalmer 8269 1.1 mbalmer 8270 1.1 mbalmer <p> 8271 1.1 mbalmer <hr><h3><a name="pdf-setmetatable"><code>setmetatable (table, metatable)</code></a></h3> 8272 1.1 mbalmer 8273 1.1 mbalmer 8274 1.1 mbalmer <p> 8275 1.1 mbalmer Sets the metatable for the given table. 8276 1.1 mbalmer If <code>metatable</code> is <b>nil</b>, 8277 1.1 mbalmer removes the metatable of the given table. 8278 1.6 salazar If the original metatable has a <code>__metatable</code> field, 8279 1.1 mbalmer raises an error. 8280 1.1 mbalmer 8281 1.1 mbalmer 8282 1.1 mbalmer <p> 8283 1.1 mbalmer This function returns <code>table</code>. 8284 1.1 mbalmer 8285 1.1 mbalmer 8286 1.9 nikita <p> 8287 1.9 nikita To change the metatable of other types from Lua code, 8288 1.9 nikita you must use the debug library (<a href="#6.10">§6.10</a>). 8289 1.9 nikita 8290 1.9 nikita 8291 1.1 mbalmer 8292 1.1 mbalmer 8293 1.1 mbalmer <p> 8294 1.1 mbalmer <hr><h3><a name="pdf-tonumber"><code>tonumber (e [, base])</code></a></h3> 8295 1.2 lneto 8296 1.2 lneto 8297 1.2 lneto <p> 8298 1.2 lneto When called with no <code>base</code>, 8299 1.2 lneto <code>tonumber</code> tries to convert its argument to a number. 8300 1.2 lneto If the argument is already a number or 8301 1.2 lneto a string convertible to a number, 8302 1.2 lneto then <code>tonumber</code> returns this number; 8303 1.9 nikita otherwise, it returns <b>fail</b>. 8304 1.1 mbalmer 8305 1.1 mbalmer 8306 1.1 mbalmer <p> 8307 1.2 lneto The conversion of strings can result in integers or floats, 8308 1.2 lneto according to the lexical conventions of Lua (see <a href="#3.1">§3.1</a>). 8309 1.9 nikita The string may have leading and trailing spaces and a sign. 8310 1.2 lneto 8311 1.2 lneto 8312 1.2 lneto <p> 8313 1.2 lneto When called with <code>base</code>, 8314 1.2 lneto then <code>e</code> must be a string to be interpreted as 8315 1.2 lneto an integer numeral in that base. 8316 1.1 mbalmer The base may be any integer between 2 and 36, inclusive. 8317 1.1 mbalmer In bases above 10, the letter '<code>A</code>' (in either upper or lower case) 8318 1.1 mbalmer represents 10, '<code>B</code>' represents 11, and so forth, 8319 1.1 mbalmer with '<code>Z</code>' representing 35. 8320 1.2 lneto If the string <code>e</code> is not a valid numeral in the given base, 8321 1.9 nikita the function returns <b>fail</b>. 8322 1.1 mbalmer 8323 1.1 mbalmer 8324 1.1 mbalmer 8325 1.1 mbalmer 8326 1.1 mbalmer <p> 8327 1.2 lneto <hr><h3><a name="pdf-tostring"><code>tostring (v)</code></a></h3> 8328 1.9 nikita 8329 1.9 nikita 8330 1.9 nikita <p> 8331 1.2 lneto Receives a value of any type and 8332 1.2 lneto converts it to a string in a human-readable format. 8333 1.1 mbalmer 8334 1.1 mbalmer 8335 1.1 mbalmer <p> 8336 1.6 salazar If the metatable of <code>v</code> has a <code>__tostring</code> field, 8337 1.1 mbalmer then <code>tostring</code> calls the corresponding value 8338 1.2 lneto with <code>v</code> as argument, 8339 1.1 mbalmer and uses the result of the call as its result. 8340 1.9 nikita Otherwise, if the metatable of <code>v</code> has a <code>__name</code> field 8341 1.9 nikita with a string value, 8342 1.9 nikita <code>tostring</code> may use that string in its final result. 8343 1.9 nikita 8344 1.9 nikita 8345 1.9 nikita <p> 8346 1.9 nikita For complete control of how numbers are converted, 8347 1.9 nikita use <a href="#pdf-string.format"><code>string.format</code></a>. 8348 1.1 mbalmer 8349 1.1 mbalmer 8350 1.1 mbalmer 8351 1.1 mbalmer 8352 1.1 mbalmer <p> 8353 1.1 mbalmer <hr><h3><a name="pdf-type"><code>type (v)</code></a></h3> 8354 1.9 nikita 8355 1.9 nikita 8356 1.9 nikita <p> 8357 1.1 mbalmer Returns the type of its only argument, coded as a string. 8358 1.1 mbalmer The possible results of this function are 8359 1.1 mbalmer "<code>nil</code>" (a string, not the value <b>nil</b>), 8360 1.1 mbalmer "<code>number</code>", 8361 1.1 mbalmer "<code>string</code>", 8362 1.1 mbalmer "<code>boolean</code>", 8363 1.1 mbalmer "<code>table</code>", 8364 1.1 mbalmer "<code>function</code>", 8365 1.1 mbalmer "<code>thread</code>", 8366 1.1 mbalmer and "<code>userdata</code>". 8367 1.1 mbalmer 8368 1.1 mbalmer 8369 1.1 mbalmer 8370 1.1 mbalmer 8371 1.1 mbalmer <p> 8372 1.1 mbalmer <hr><h3><a name="pdf-_VERSION"><code>_VERSION</code></a></h3> 8373 1.5 lneto 8374 1.5 lneto 8375 1.5 lneto <p> 8376 1.1 mbalmer A global variable (not a function) that 8377 1.5 lneto holds a string containing the running Lua version. 8378 1.9 nikita The current value of this variable is "<code>Lua 5.4</code>". 8379 1.9 nikita 8380 1.9 nikita 8381 1.9 nikita 8382 1.9 nikita 8383 1.9 nikita <p> 8384 1.9 nikita <hr><h3><a name="pdf-warn"><code>warn (msg1, ···)</code></a></h3> 8385 1.9 nikita 8386 1.9 nikita 8387 1.9 nikita <p> 8388 1.9 nikita Emits a warning with a message composed by the concatenation 8389 1.9 nikita of all its arguments (which should be strings). 8390 1.9 nikita 8391 1.9 nikita 8392 1.9 nikita <p> 8393 1.9 nikita By convention, 8394 1.9 nikita a one-piece message starting with '<code>@</code>' 8395 1.9 nikita is intended to be a <em>control message</em>, 8396 1.9 nikita which is a message to the warning system itself. 8397 1.9 nikita In particular, the standard warning function in Lua 8398 1.9 nikita recognizes the control messages "<code>@off</code>", 8399 1.9 nikita to stop the emission of warnings, 8400 1.9 nikita and "<code>@on</code>", to (re)start the emission; 8401 1.9 nikita it ignores unknown control messages. 8402 1.1 mbalmer 8403 1.1 mbalmer 8404 1.1 mbalmer 8405 1.1 mbalmer 8406 1.1 mbalmer <p> 8407 1.2 lneto <hr><h3><a name="pdf-xpcall"><code>xpcall (f, msgh [, arg1, ···])</code></a></h3> 8408 1.1 mbalmer 8409 1.1 mbalmer 8410 1.1 mbalmer <p> 8411 1.1 mbalmer This function is similar to <a href="#pdf-pcall"><code>pcall</code></a>, 8412 1.2 lneto except that it sets a new message handler <code>msgh</code>. 8413 1.1 mbalmer 8414 1.1 mbalmer 8415 1.1 mbalmer 8416 1.1 mbalmer 8417 1.1 mbalmer 8418 1.1 mbalmer 8419 1.1 mbalmer 8420 1.2 lneto <h2>6.2 – <a name="6.2">Coroutine Manipulation</a></h2> 8421 1.1 mbalmer 8422 1.1 mbalmer <p> 8423 1.4 mbalmer This library comprises the operations to manipulate coroutines, 8424 1.4 mbalmer which come inside the table <a name="pdf-coroutine"><code>coroutine</code></a>. 8425 1.2 lneto See <a href="#2.6">§2.6</a> for a general description of coroutines. 8426 1.1 mbalmer 8427 1.1 mbalmer 8428 1.1 mbalmer <p> 8429 1.9 nikita <hr><h3><a name="pdf-coroutine.close"><code>coroutine.close (co)</code></a></h3> 8430 1.9 nikita 8431 1.9 nikita 8432 1.9 nikita <p> 8433 1.9 nikita Closes coroutine <code>co</code>, 8434 1.9 nikita that is, 8435 1.9 nikita closes all its pending to-be-closed variables 8436 1.9 nikita and puts the coroutine in a dead state. 8437 1.9 nikita The given coroutine must be dead or suspended. 8438 1.9 nikita In case of error 8439 1.9 nikita (either the original error that stopped the coroutine or 8440 1.9 nikita errors in closing methods), 8441 1.9 nikita returns <b>false</b> plus the error object; 8442 1.9 nikita otherwise returns <b>true</b>. 8443 1.9 nikita 8444 1.9 nikita 8445 1.9 nikita 8446 1.9 nikita 8447 1.9 nikita <p> 8448 1.1 mbalmer <hr><h3><a name="pdf-coroutine.create"><code>coroutine.create (f)</code></a></h3> 8449 1.1 mbalmer 8450 1.1 mbalmer 8451 1.1 mbalmer <p> 8452 1.1 mbalmer Creates a new coroutine, with body <code>f</code>. 8453 1.4 mbalmer <code>f</code> must be a function. 8454 1.2 lneto Returns this new coroutine, 8455 1.2 lneto an object with type <code>"thread"</code>. 8456 1.2 lneto 8457 1.2 lneto 8458 1.2 lneto 8459 1.2 lneto 8460 1.2 lneto <p> 8461 1.9 nikita <hr><h3><a name="pdf-coroutine.isyieldable"><code>coroutine.isyieldable ([co])</code></a></h3> 8462 1.2 lneto 8463 1.2 lneto 8464 1.2 lneto <p> 8465 1.9 nikita Returns <b>true</b> when the coroutine <code>co</code> can yield. 8466 1.9 nikita The default for <code>co</code> is the running coroutine. 8467 1.2 lneto 8468 1.2 lneto 8469 1.2 lneto <p> 8470 1.9 nikita A coroutine is yieldable if it is not the main thread and 8471 1.7 mbalmer it is not inside a non-yieldable C function. 8472 1.1 mbalmer 8473 1.1 mbalmer 8474 1.1 mbalmer 8475 1.1 mbalmer 8476 1.1 mbalmer <p> 8477 1.1 mbalmer <hr><h3><a name="pdf-coroutine.resume"><code>coroutine.resume (co [, val1, ···])</code></a></h3> 8478 1.1 mbalmer 8479 1.1 mbalmer 8480 1.1 mbalmer <p> 8481 1.1 mbalmer Starts or continues the execution of coroutine <code>co</code>. 8482 1.1 mbalmer The first time you resume a coroutine, 8483 1.1 mbalmer it starts running its body. 8484 1.2 lneto The values <code>val1</code>, ... are passed 8485 1.1 mbalmer as the arguments to the body function. 8486 1.1 mbalmer If the coroutine has yielded, 8487 1.1 mbalmer <code>resume</code> restarts it; 8488 1.2 lneto the values <code>val1</code>, ... are passed 8489 1.1 mbalmer as the results from the yield. 8490 1.1 mbalmer 8491 1.1 mbalmer 8492 1.1 mbalmer <p> 8493 1.1 mbalmer If the coroutine runs without any errors, 8494 1.1 mbalmer <code>resume</code> returns <b>true</b> plus any values passed to <code>yield</code> 8495 1.2 lneto (when the coroutine yields) or any values returned by the body function 8496 1.2 lneto (when the coroutine terminates). 8497 1.1 mbalmer If there is any error, 8498 1.1 mbalmer <code>resume</code> returns <b>false</b> plus the error message. 8499 1.1 mbalmer 8500 1.1 mbalmer 8501 1.1 mbalmer 8502 1.1 mbalmer 8503 1.1 mbalmer <p> 8504 1.1 mbalmer <hr><h3><a name="pdf-coroutine.running"><code>coroutine.running ()</code></a></h3> 8505 1.1 mbalmer 8506 1.1 mbalmer 8507 1.1 mbalmer <p> 8508 1.2 lneto Returns the running coroutine plus a boolean, 8509 1.9 nikita <b>true</b> when the running coroutine is the main one. 8510 1.1 mbalmer 8511 1.1 mbalmer 8512 1.1 mbalmer 8513 1.1 mbalmer 8514 1.1 mbalmer <p> 8515 1.1 mbalmer <hr><h3><a name="pdf-coroutine.status"><code>coroutine.status (co)</code></a></h3> 8516 1.1 mbalmer 8517 1.1 mbalmer 8518 1.1 mbalmer <p> 8519 1.9 nikita Returns the status of the coroutine <code>co</code>, as a string: 8520 1.1 mbalmer <code>"running"</code>, 8521 1.9 nikita if the coroutine is running 8522 1.9 nikita (that is, it is the one that called <code>status</code>); 8523 1.1 mbalmer <code>"suspended"</code>, if the coroutine is suspended in a call to <code>yield</code>, 8524 1.1 mbalmer or if it has not started running yet; 8525 1.1 mbalmer <code>"normal"</code> if the coroutine is active but not running 8526 1.1 mbalmer (that is, it has resumed another coroutine); 8527 1.1 mbalmer and <code>"dead"</code> if the coroutine has finished its body function, 8528 1.1 mbalmer or if it has stopped with an error. 8529 1.1 mbalmer 8530 1.1 mbalmer 8531 1.1 mbalmer 8532 1.1 mbalmer 8533 1.1 mbalmer <p> 8534 1.1 mbalmer <hr><h3><a name="pdf-coroutine.wrap"><code>coroutine.wrap (f)</code></a></h3> 8535 1.1 mbalmer 8536 1.1 mbalmer 8537 1.1 mbalmer <p> 8538 1.9 nikita Creates a new coroutine, with body <code>f</code>; 8539 1.4 mbalmer <code>f</code> must be a function. 8540 1.1 mbalmer Returns a function that resumes the coroutine each time it is called. 8541 1.9 nikita Any arguments passed to this function behave as the 8542 1.1 mbalmer extra arguments to <code>resume</code>. 8543 1.9 nikita The function returns the same values returned by <code>resume</code>, 8544 1.1 mbalmer except the first boolean. 8545 1.9 nikita In case of error, 8546 1.9 nikita the function closes the coroutine and propagates the error. 8547 1.1 mbalmer 8548 1.1 mbalmer 8549 1.1 mbalmer 8550 1.1 mbalmer 8551 1.1 mbalmer <p> 8552 1.1 mbalmer <hr><h3><a name="pdf-coroutine.yield"><code>coroutine.yield (···)</code></a></h3> 8553 1.1 mbalmer 8554 1.1 mbalmer 8555 1.1 mbalmer <p> 8556 1.1 mbalmer Suspends the execution of the calling coroutine. 8557 1.1 mbalmer Any arguments to <code>yield</code> are passed as extra results to <code>resume</code>. 8558 1.1 mbalmer 8559 1.1 mbalmer 8560 1.1 mbalmer 8561 1.1 mbalmer 8562 1.1 mbalmer 8563 1.1 mbalmer 8564 1.1 mbalmer 8565 1.2 lneto <h2>6.3 – <a name="6.3">Modules</a></h2> 8566 1.1 mbalmer 8567 1.1 mbalmer <p> 8568 1.1 mbalmer The package library provides basic 8569 1.2 lneto facilities for loading modules in Lua. 8570 1.2 lneto It exports one function directly in the global environment: 8571 1.2 lneto <a href="#pdf-require"><code>require</code></a>. 8572 1.9 nikita Everything else is exported in the table <a name="pdf-package"><code>package</code></a>. 8573 1.1 mbalmer 8574 1.1 mbalmer 8575 1.1 mbalmer <p> 8576 1.1 mbalmer <hr><h3><a name="pdf-require"><code>require (modname)</code></a></h3> 8577 1.1 mbalmer 8578 1.1 mbalmer 8579 1.1 mbalmer <p> 8580 1.1 mbalmer Loads the given module. 8581 1.1 mbalmer The function starts by looking into the <a href="#pdf-package.loaded"><code>package.loaded</code></a> table 8582 1.1 mbalmer to determine whether <code>modname</code> is already loaded. 8583 1.1 mbalmer If it is, then <code>require</code> returns the value stored 8584 1.1 mbalmer at <code>package.loaded[modname]</code>. 8585 1.9 nikita (The absence of a second result in this case 8586 1.9 nikita signals that this call did not have to load the module.) 8587 1.1 mbalmer Otherwise, it tries to find a <em>loader</em> for the module. 8588 1.1 mbalmer 8589 1.1 mbalmer 8590 1.1 mbalmer <p> 8591 1.1 mbalmer To find a loader, 8592 1.9 nikita <code>require</code> is guided by the table <a href="#pdf-package.searchers"><code>package.searchers</code></a>. 8593 1.9 nikita Each item in this table is a search function, 8594 1.9 nikita that searches for the module in a particular way. 8595 1.9 nikita By changing this table, 8596 1.1 mbalmer we can change how <code>require</code> looks for a module. 8597 1.1 mbalmer The following explanation is based on the default configuration 8598 1.2 lneto for <a href="#pdf-package.searchers"><code>package.searchers</code></a>. 8599 1.1 mbalmer 8600 1.1 mbalmer 8601 1.1 mbalmer <p> 8602 1.1 mbalmer First <code>require</code> queries <code>package.preload[modname]</code>. 8603 1.1 mbalmer If it has a value, 8604 1.2 lneto this value (which must be a function) is the loader. 8605 1.1 mbalmer Otherwise <code>require</code> searches for a Lua loader using the 8606 1.1 mbalmer path stored in <a href="#pdf-package.path"><code>package.path</code></a>. 8607 1.1 mbalmer If that also fails, it searches for a C loader using the 8608 1.1 mbalmer path stored in <a href="#pdf-package.cpath"><code>package.cpath</code></a>. 8609 1.1 mbalmer If that also fails, 8610 1.2 lneto it tries an <em>all-in-one</em> loader (see <a href="#pdf-package.searchers"><code>package.searchers</code></a>). 8611 1.1 mbalmer 8612 1.1 mbalmer 8613 1.1 mbalmer <p> 8614 1.1 mbalmer Once a loader is found, 8615 1.2 lneto <code>require</code> calls the loader with two arguments: 8616 1.9 nikita <code>modname</code> and an extra value, 8617 1.9 nikita a <em>loader data</em>, 8618 1.9 nikita also returned by the searcher. 8619 1.9 nikita The loader data can be any value useful to the module; 8620 1.9 nikita for the default searchers, 8621 1.9 nikita it indicates where the loader was found. 8622 1.9 nikita (For instance, if the loader came from a file, 8623 1.9 nikita this extra value is the file path.) 8624 1.2 lneto If the loader returns any non-nil value, 8625 1.1 mbalmer <code>require</code> assigns the returned value to <code>package.loaded[modname]</code>. 8626 1.2 lneto If the loader does not return a non-nil value and 8627 1.1 mbalmer has not assigned any value to <code>package.loaded[modname]</code>, 8628 1.1 mbalmer then <code>require</code> assigns <b>true</b> to this entry. 8629 1.1 mbalmer In any case, <code>require</code> returns the 8630 1.1 mbalmer final value of <code>package.loaded[modname]</code>. 8631 1.9 nikita Besides that value, <code>require</code> also returns as a second result 8632 1.9 nikita the loader data returned by the searcher, 8633 1.9 nikita which indicates how <code>require</code> found the module. 8634 1.1 mbalmer 8635 1.1 mbalmer 8636 1.1 mbalmer <p> 8637 1.1 mbalmer If there is any error loading or running the module, 8638 1.1 mbalmer or if it cannot find any loader for the module, 8639 1.2 lneto then <code>require</code> raises an error. 8640 1.2 lneto 8641 1.2 lneto 8642 1.2 lneto 8643 1.2 lneto 8644 1.2 lneto <p> 8645 1.2 lneto <hr><h3><a name="pdf-package.config"><code>package.config</code></a></h3> 8646 1.2 lneto 8647 1.2 lneto 8648 1.2 lneto <p> 8649 1.2 lneto A string describing some compile-time configurations for packages. 8650 1.2 lneto This string is a sequence of lines: 8651 1.2 lneto 8652 1.2 lneto <ul> 8653 1.2 lneto 8654 1.2 lneto <li>The first line is the directory separator string. 8655 1.2 lneto Default is '<code>\</code>' for Windows and '<code>/</code>' for all other systems.</li> 8656 1.1 mbalmer 8657 1.2 lneto <li>The second line is the character that separates templates in a path. 8658 1.2 lneto Default is '<code>;</code>'.</li> 8659 1.2 lneto 8660 1.2 lneto <li>The third line is the string that marks the 8661 1.2 lneto substitution points in a template. 8662 1.2 lneto Default is '<code>?</code>'.</li> 8663 1.2 lneto 8664 1.2 lneto <li>The fourth line is a string that, in a path in Windows, 8665 1.2 lneto is replaced by the executable's directory. 8666 1.2 lneto Default is '<code>!</code>'.</li> 8667 1.2 lneto 8668 1.3 lneto <li>The fifth line is a mark to ignore all text after it 8669 1.2 lneto when building the <code>luaopen_</code> function name. 8670 1.2 lneto Default is '<code>-</code>'.</li> 8671 1.2 lneto 8672 1.2 lneto </ul> 8673 1.1 mbalmer 8674 1.1 mbalmer 8675 1.1 mbalmer 8676 1.1 mbalmer <p> 8677 1.1 mbalmer <hr><h3><a name="pdf-package.cpath"><code>package.cpath</code></a></h3> 8678 1.1 mbalmer 8679 1.1 mbalmer 8680 1.1 mbalmer <p> 8681 1.9 nikita A string with the path used by <a href="#pdf-require"><code>require</code></a> 8682 1.9 nikita to search for a C loader. 8683 1.1 mbalmer 8684 1.1 mbalmer 8685 1.1 mbalmer <p> 8686 1.1 mbalmer Lua initializes the C path <a href="#pdf-package.cpath"><code>package.cpath</code></a> in the same way 8687 1.1 mbalmer it initializes the Lua path <a href="#pdf-package.path"><code>package.path</code></a>, 8688 1.9 nikita using the environment variable <a name="pdf-LUA_CPATH_5_4"><code>LUA_CPATH_5_4</code></a>, 8689 1.7 mbalmer or the environment variable <a name="pdf-LUA_CPATH"><code>LUA_CPATH</code></a>, 8690 1.1 mbalmer or a default path defined in <code>luaconf.h</code>. 8691 1.1 mbalmer 8692 1.1 mbalmer 8693 1.1 mbalmer 8694 1.1 mbalmer 8695 1.1 mbalmer <p> 8696 1.1 mbalmer <hr><h3><a name="pdf-package.loaded"><code>package.loaded</code></a></h3> 8697 1.1 mbalmer 8698 1.1 mbalmer 8699 1.1 mbalmer <p> 8700 1.1 mbalmer A table used by <a href="#pdf-require"><code>require</code></a> to control which 8701 1.1 mbalmer modules are already loaded. 8702 1.1 mbalmer When you require a module <code>modname</code> and 8703 1.1 mbalmer <code>package.loaded[modname]</code> is not false, 8704 1.1 mbalmer <a href="#pdf-require"><code>require</code></a> simply returns the value stored there. 8705 1.1 mbalmer 8706 1.1 mbalmer 8707 1.2 lneto <p> 8708 1.2 lneto This variable is only a reference to the real table; 8709 1.2 lneto assignments to this variable do not change the 8710 1.2 lneto table used by <a href="#pdf-require"><code>require</code></a>. 8711 1.2 lneto 8712 1.2 lneto 8713 1.2 lneto 8714 1.2 lneto 8715 1.2 lneto <p> 8716 1.2 lneto <hr><h3><a name="pdf-package.loadlib"><code>package.loadlib (libname, funcname)</code></a></h3> 8717 1.2 lneto 8718 1.2 lneto 8719 1.2 lneto <p> 8720 1.2 lneto Dynamically links the host program with the C library <code>libname</code>. 8721 1.2 lneto 8722 1.2 lneto 8723 1.2 lneto <p> 8724 1.2 lneto If <code>funcname</code> is "<code>*</code>", 8725 1.2 lneto then it only links with the library, 8726 1.2 lneto making the symbols exported by the library 8727 1.2 lneto available to other dynamically linked libraries. 8728 1.2 lneto Otherwise, 8729 1.2 lneto it looks for a function <code>funcname</code> inside the library 8730 1.2 lneto and returns this function as a C function. 8731 1.2 lneto So, <code>funcname</code> must follow the <a href="#lua_CFunction"><code>lua_CFunction</code></a> prototype 8732 1.2 lneto (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 8733 1.2 lneto 8734 1.2 lneto 8735 1.2 lneto <p> 8736 1.2 lneto This is a low-level function. 8737 1.2 lneto It completely bypasses the package and module system. 8738 1.2 lneto Unlike <a href="#pdf-require"><code>require</code></a>, 8739 1.2 lneto it does not perform any path searching and 8740 1.2 lneto does not automatically adds extensions. 8741 1.2 lneto <code>libname</code> must be the complete file name of the C library, 8742 1.2 lneto including if necessary a path and an extension. 8743 1.2 lneto <code>funcname</code> must be the exact name exported by the C library 8744 1.2 lneto (which may depend on the C compiler and linker used). 8745 1.2 lneto 8746 1.2 lneto 8747 1.2 lneto <p> 8748 1.2 lneto This function is not supported by Standard C. 8749 1.2 lneto As such, it is only available on some platforms 8750 1.2 lneto (Windows, Linux, Mac OS X, Solaris, BSD, 8751 1.2 lneto plus other Unix systems that support the <code>dlfcn</code> standard). 8752 1.2 lneto 8753 1.2 lneto 8754 1.9 nikita <p> 8755 1.9 nikita This function is inherently insecure, 8756 1.9 nikita as it allows Lua to call any function in any readable dynamic 8757 1.9 nikita library in the system. 8758 1.9 nikita (Lua calls any function assuming the function 8759 1.9 nikita has a proper prototype and respects a proper protocol 8760 1.9 nikita (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 8761 1.9 nikita Therefore, 8762 1.9 nikita calling an arbitrary function in an arbitrary dynamic library 8763 1.9 nikita more often than not results in an access violation.) 8764 1.9 nikita 8765 1.9 nikita 8766 1.2 lneto 8767 1.2 lneto 8768 1.2 lneto <p> 8769 1.2 lneto <hr><h3><a name="pdf-package.path"><code>package.path</code></a></h3> 8770 1.2 lneto 8771 1.2 lneto 8772 1.2 lneto <p> 8773 1.9 nikita A string with the path used by <a href="#pdf-require"><code>require</code></a> 8774 1.9 nikita to search for a Lua loader. 8775 1.2 lneto 8776 1.2 lneto 8777 1.2 lneto <p> 8778 1.2 lneto At start-up, Lua initializes this variable with 8779 1.9 nikita the value of the environment variable <a name="pdf-LUA_PATH_5_4"><code>LUA_PATH_5_4</code></a> or 8780 1.2 lneto the environment variable <a name="pdf-LUA_PATH"><code>LUA_PATH</code></a> or 8781 1.2 lneto with a default path defined in <code>luaconf.h</code>, 8782 1.2 lneto if those environment variables are not defined. 8783 1.9 nikita A "<code>;;</code>" in the value of the environment variable 8784 1.2 lneto is replaced by the default path. 8785 1.2 lneto 8786 1.2 lneto 8787 1.2 lneto 8788 1.2 lneto 8789 1.2 lneto <p> 8790 1.2 lneto <hr><h3><a name="pdf-package.preload"><code>package.preload</code></a></h3> 8791 1.2 lneto 8792 1.2 lneto 8793 1.2 lneto <p> 8794 1.2 lneto A table to store loaders for specific modules 8795 1.2 lneto (see <a href="#pdf-require"><code>require</code></a>). 8796 1.2 lneto 8797 1.2 lneto 8798 1.2 lneto <p> 8799 1.2 lneto This variable is only a reference to the real table; 8800 1.2 lneto assignments to this variable do not change the 8801 1.2 lneto table used by <a href="#pdf-require"><code>require</code></a>. 8802 1.2 lneto 8803 1.2 lneto 8804 1.1 mbalmer 8805 1.1 mbalmer 8806 1.1 mbalmer <p> 8807 1.2 lneto <hr><h3><a name="pdf-package.searchers"><code>package.searchers</code></a></h3> 8808 1.1 mbalmer 8809 1.1 mbalmer 8810 1.1 mbalmer <p> 8811 1.9 nikita A table used by <a href="#pdf-require"><code>require</code></a> to control how to find modules. 8812 1.1 mbalmer 8813 1.1 mbalmer 8814 1.1 mbalmer <p> 8815 1.1 mbalmer Each entry in this table is a <em>searcher function</em>. 8816 1.1 mbalmer When looking for a module, 8817 1.1 mbalmer <a href="#pdf-require"><code>require</code></a> calls each of these searchers in ascending order, 8818 1.1 mbalmer with the module name (the argument given to <a href="#pdf-require"><code>require</code></a>) as its 8819 1.9 nikita sole argument. 8820 1.9 nikita If the searcher finds the module, 8821 1.9 nikita it returns another function, the module <em>loader</em>, 8822 1.9 nikita plus an extra value, a <em>loader data</em>, 8823 1.9 nikita that will be passed to that loader and 8824 1.9 nikita returned as a second result by <a href="#pdf-require"><code>require</code></a>. 8825 1.9 nikita If it cannot find the module, 8826 1.9 nikita it returns a string explaining why 8827 1.1 mbalmer (or <b>nil</b> if it has nothing to say). 8828 1.2 lneto 8829 1.2 lneto 8830 1.2 lneto <p> 8831 1.2 lneto Lua initializes this table with four searcher functions. 8832 1.1 mbalmer 8833 1.1 mbalmer 8834 1.1 mbalmer <p> 8835 1.1 mbalmer The first searcher simply looks for a loader in the 8836 1.1 mbalmer <a href="#pdf-package.preload"><code>package.preload</code></a> table. 8837 1.1 mbalmer 8838 1.1 mbalmer 8839 1.1 mbalmer <p> 8840 1.1 mbalmer The second searcher looks for a loader as a Lua library, 8841 1.1 mbalmer using the path stored at <a href="#pdf-package.path"><code>package.path</code></a>. 8842 1.2 lneto The search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. 8843 1.1 mbalmer 8844 1.1 mbalmer 8845 1.1 mbalmer <p> 8846 1.1 mbalmer The third searcher looks for a loader as a C library, 8847 1.1 mbalmer using the path given by the variable <a href="#pdf-package.cpath"><code>package.cpath</code></a>. 8848 1.2 lneto Again, 8849 1.2 lneto the search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. 8850 1.1 mbalmer For instance, 8851 1.1 mbalmer if the C path is the string 8852 1.1 mbalmer 8853 1.1 mbalmer <pre> 8854 1.1 mbalmer "./?.so;./?.dll;/usr/local/?/init.so" 8855 1.1 mbalmer </pre><p> 8856 1.1 mbalmer the searcher for module <code>foo</code> 8857 1.1 mbalmer will try to open the files <code>./foo.so</code>, <code>./foo.dll</code>, 8858 1.1 mbalmer and <code>/usr/local/foo/init.so</code>, in that order. 8859 1.1 mbalmer Once it finds a C library, 8860 1.1 mbalmer this searcher first uses a dynamic link facility to link the 8861 1.1 mbalmer application with the library. 8862 1.1 mbalmer Then it tries to find a C function inside the library to 8863 1.1 mbalmer be used as the loader. 8864 1.1 mbalmer The name of this C function is the string "<code>luaopen_</code>" 8865 1.1 mbalmer concatenated with a copy of the module name where each dot 8866 1.1 mbalmer is replaced by an underscore. 8867 1.1 mbalmer Moreover, if the module name has a hyphen, 8868 1.3 lneto its suffix after (and including) the first hyphen is removed. 8869 1.3 lneto For instance, if the module name is <code>a.b.c-v2.1</code>, 8870 1.3 lneto the function name will be <code>luaopen_a_b_c</code>. 8871 1.1 mbalmer 8872 1.1 mbalmer 8873 1.1 mbalmer <p> 8874 1.1 mbalmer The fourth searcher tries an <em>all-in-one loader</em>. 8875 1.1 mbalmer It searches the C path for a library for 8876 1.1 mbalmer the root name of the given module. 8877 1.1 mbalmer For instance, when requiring <code>a.b.c</code>, 8878 1.1 mbalmer it will search for a C library for <code>a</code>. 8879 1.1 mbalmer If found, it looks into it for an open function for 8880 1.1 mbalmer the submodule; 8881 1.1 mbalmer in our example, that would be <code>luaopen_a_b_c</code>. 8882 1.1 mbalmer With this facility, a package can pack several C submodules 8883 1.1 mbalmer into one single library, 8884 1.1 mbalmer with each submodule keeping its original open function. 8885 1.1 mbalmer 8886 1.1 mbalmer 8887 1.1 mbalmer <p> 8888 1.2 lneto All searchers except the first one (preload) return as the extra value 8889 1.9 nikita the file path where the module was found, 8890 1.2 lneto as returned by <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. 8891 1.9 nikita The first searcher always returns the string "<code>:preload:</code>". 8892 1.9 nikita 8893 1.9 nikita 8894 1.9 nikita <p> 8895 1.9 nikita Searchers should raise no errors and have no side effects in Lua. 8896 1.9 nikita (They may have side effects in C, 8897 1.9 nikita for instance by linking the application with a library.) 8898 1.1 mbalmer 8899 1.1 mbalmer 8900 1.1 mbalmer 8901 1.1 mbalmer 8902 1.1 mbalmer <p> 8903 1.2 lneto <hr><h3><a name="pdf-package.searchpath"><code>package.searchpath (name, path [, sep [, rep]])</code></a></h3> 8904 1.1 mbalmer 8905 1.1 mbalmer 8906 1.1 mbalmer <p> 8907 1.2 lneto Searches for the given <code>name</code> in the given <code>path</code>. 8908 1.1 mbalmer 8909 1.1 mbalmer 8910 1.1 mbalmer <p> 8911 1.2 lneto A path is a string containing a sequence of 8912 1.2 lneto <em>templates</em> separated by semicolons. 8913 1.2 lneto For each template, 8914 1.2 lneto the function replaces each interrogation mark (if any) 8915 1.2 lneto in the template with a copy of <code>name</code> 8916 1.2 lneto wherein all occurrences of <code>sep</code> 8917 1.2 lneto (a dot, by default) 8918 1.2 lneto were replaced by <code>rep</code> 8919 1.2 lneto (the system's directory separator, by default), 8920 1.2 lneto and then tries to open the resulting file name. 8921 1.1 mbalmer 8922 1.1 mbalmer 8923 1.1 mbalmer <p> 8924 1.2 lneto For instance, if the path is the string 8925 1.1 mbalmer 8926 1.2 lneto <pre> 8927 1.2 lneto "./?.lua;./?.lc;/usr/local/?/init.lua" 8928 1.2 lneto </pre><p> 8929 1.2 lneto the search for the name <code>foo.a</code> 8930 1.2 lneto will try to open the files 8931 1.2 lneto <code>./foo/a.lua</code>, <code>./foo/a.lc</code>, and 8932 1.2 lneto <code>/usr/local/foo/a/init.lua</code>, in that order. 8933 1.1 mbalmer 8934 1.1 mbalmer 8935 1.1 mbalmer <p> 8936 1.2 lneto Returns the resulting name of the first file that it can 8937 1.2 lneto open in read mode (after closing the file), 8938 1.9 nikita or <b>fail</b> plus an error message if none succeeds. 8939 1.2 lneto (This error message lists all file names it tried to open.) 8940 1.1 mbalmer 8941 1.1 mbalmer 8942 1.1 mbalmer 8943 1.1 mbalmer 8944 1.1 mbalmer 8945 1.1 mbalmer 8946 1.1 mbalmer 8947 1.2 lneto <h2>6.4 – <a name="6.4">String Manipulation</a></h2> 8948 1.1 mbalmer 8949 1.9 nikita 8950 1.9 nikita 8951 1.1 mbalmer <p> 8952 1.1 mbalmer This library provides generic functions for string manipulation, 8953 1.1 mbalmer such as finding and extracting substrings, and pattern matching. 8954 1.1 mbalmer When indexing a string in Lua, the first character is at position 1 8955 1.1 mbalmer (not at 0, as in C). 8956 1.1 mbalmer Indices are allowed to be negative and are interpreted as indexing backwards, 8957 1.1 mbalmer from the end of the string. 8958 1.1 mbalmer Thus, the last character is at position -1, and so on. 8959 1.1 mbalmer 8960 1.1 mbalmer 8961 1.1 mbalmer <p> 8962 1.1 mbalmer The string library provides all its functions inside the table 8963 1.1 mbalmer <a name="pdf-string"><code>string</code></a>. 8964 1.1 mbalmer It also sets a metatable for strings 8965 1.1 mbalmer where the <code>__index</code> field points to the <code>string</code> table. 8966 1.1 mbalmer Therefore, you can use the string functions in object-oriented style. 8967 1.2 lneto For instance, <code>string.byte(s,i)</code> 8968 1.1 mbalmer can be written as <code>s:byte(i)</code>. 8969 1.1 mbalmer 8970 1.1 mbalmer 8971 1.1 mbalmer <p> 8972 1.1 mbalmer The string library assumes one-byte character encodings. 8973 1.1 mbalmer 8974 1.1 mbalmer 8975 1.1 mbalmer <p> 8976 1.1 mbalmer <hr><h3><a name="pdf-string.byte"><code>string.byte (s [, i [, j]])</code></a></h3> 8977 1.4 mbalmer Returns the internal numeric codes of the characters <code>s[i]</code>, 8978 1.2 lneto <code>s[i+1]</code>, ..., <code>s[j]</code>. 8979 1.1 mbalmer The default value for <code>i</code> is 1; 8980 1.1 mbalmer the default value for <code>j</code> is <code>i</code>. 8981 1.2 lneto These indices are corrected 8982 1.2 lneto following the same rules of function <a href="#pdf-string.sub"><code>string.sub</code></a>. 8983 1.1 mbalmer 8984 1.1 mbalmer 8985 1.1 mbalmer <p> 8986 1.4 mbalmer Numeric codes are not necessarily portable across platforms. 8987 1.1 mbalmer 8988 1.1 mbalmer 8989 1.1 mbalmer 8990 1.1 mbalmer 8991 1.1 mbalmer <p> 8992 1.1 mbalmer <hr><h3><a name="pdf-string.char"><code>string.char (···)</code></a></h3> 8993 1.1 mbalmer Receives zero or more integers. 8994 1.1 mbalmer Returns a string with length equal to the number of arguments, 8995 1.4 mbalmer in which each character has the internal numeric code equal 8996 1.1 mbalmer to its corresponding argument. 8997 1.1 mbalmer 8998 1.1 mbalmer 8999 1.1 mbalmer <p> 9000 1.4 mbalmer Numeric codes are not necessarily portable across platforms. 9001 1.2 lneto 9002 1.2 lneto 9003 1.2 lneto 9004 1.2 lneto 9005 1.2 lneto <p> 9006 1.2 lneto <hr><h3><a name="pdf-string.dump"><code>string.dump (function [, strip])</code></a></h3> 9007 1.1 mbalmer 9008 1.1 mbalmer 9009 1.2 lneto <p> 9010 1.2 lneto Returns a string containing a binary representation 9011 1.2 lneto (a <em>binary chunk</em>) 9012 1.2 lneto of the given function, 9013 1.2 lneto so that a later <a href="#pdf-load"><code>load</code></a> on this string returns 9014 1.2 lneto a copy of the function (but with new upvalues). 9015 1.2 lneto If <code>strip</code> is a true value, 9016 1.4 mbalmer the binary representation may not include all debug information 9017 1.4 mbalmer about the function, 9018 1.4 mbalmer to save space. 9019 1.2 lneto 9020 1.2 lneto 9021 1.2 lneto <p> 9022 1.3 lneto Functions with upvalues have only their number of upvalues saved. 9023 1.3 lneto When (re)loaded, 9024 1.9 nikita those upvalues receive fresh instances. 9025 1.9 nikita (See the <a href="#pdf-load"><code>load</code></a> function for details about 9026 1.9 nikita how these upvalues are initialized. 9027 1.9 nikita You can use the debug library to serialize 9028 1.3 lneto and reload the upvalues of a function 9029 1.3 lneto in a way adequate to your needs.) 9030 1.1 mbalmer 9031 1.1 mbalmer 9032 1.1 mbalmer 9033 1.1 mbalmer 9034 1.1 mbalmer <p> 9035 1.1 mbalmer <hr><h3><a name="pdf-string.find"><code>string.find (s, pattern [, init [, plain]])</code></a></h3> 9036 1.2 lneto 9037 1.2 lneto 9038 1.2 lneto <p> 9039 1.1 mbalmer Looks for the first match of 9040 1.3 lneto <code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) in the string <code>s</code>. 9041 1.1 mbalmer If it finds a match, then <code>find</code> returns the indices of <code>s</code> 9042 1.1 mbalmer where this occurrence starts and ends; 9043 1.9 nikita otherwise, it returns <b>fail</b>. 9044 1.4 mbalmer A third, optional numeric argument <code>init</code> specifies 9045 1.1 mbalmer where to start the search; 9046 1.1 mbalmer its default value is 1 and can be negative. 9047 1.9 nikita A <b>true</b> as a fourth, optional argument <code>plain</code> 9048 1.1 mbalmer turns off the pattern matching facilities, 9049 1.1 mbalmer so the function does a plain "find substring" operation, 9050 1.2 lneto with no characters in <code>pattern</code> being considered magic. 9051 1.1 mbalmer 9052 1.1 mbalmer 9053 1.1 mbalmer <p> 9054 1.1 mbalmer If the pattern has captures, 9055 1.1 mbalmer then in a successful match 9056 1.1 mbalmer the captured values are also returned, 9057 1.1 mbalmer after the two indices. 9058 1.1 mbalmer 9059 1.1 mbalmer 9060 1.1 mbalmer 9061 1.1 mbalmer 9062 1.1 mbalmer <p> 9063 1.1 mbalmer <hr><h3><a name="pdf-string.format"><code>string.format (formatstring, ···)</code></a></h3> 9064 1.2 lneto 9065 1.2 lneto 9066 1.2 lneto <p> 9067 1.1 mbalmer Returns a formatted version of its variable number of arguments 9068 1.9 nikita following the description given in its first argument, 9069 1.9 nikita which must be a string. 9070 1.3 lneto The format string follows the same rules as the ISO C function <code>sprintf</code>. 9071 1.9 nikita The only differences are that the conversion specifiers and modifiers 9072 1.9 nikita <code>F</code>, <code>n</code>, <code>*</code>, <code>h</code>, <code>L</code>, and <code>l</code> are not supported 9073 1.9 nikita and that there is an extra specifier, <code>q</code>. 9074 1.9 nikita Both width and precision, when present, 9075 1.9 nikita are limited to two digits. 9076 1.6 salazar 9077 1.6 salazar 9078 1.6 salazar <p> 9079 1.9 nikita The specifier <code>q</code> formats booleans, nil, numbers, and strings 9080 1.9 nikita in a way that the result is a valid constant in Lua source code. 9081 1.9 nikita Booleans and nil are written in the obvious way 9082 1.9 nikita (<code>true</code>, <code>false</code>, <code>nil</code>). 9083 1.9 nikita Floats are written in hexadecimal, 9084 1.9 nikita to preserve full precision. 9085 1.9 nikita A string is written between double quotes, 9086 1.2 lneto using escape sequences when necessary to ensure that 9087 1.2 lneto it can safely be read back by the Lua interpreter. 9088 1.1 mbalmer For instance, the call 9089 1.1 mbalmer 9090 1.1 mbalmer <pre> 9091 1.1 mbalmer string.format('%q', 'a string with "quotes" and \n new line') 9092 1.1 mbalmer </pre><p> 9093 1.2 lneto may produce the string: 9094 1.1 mbalmer 9095 1.1 mbalmer <pre> 9096 1.1 mbalmer "a string with \"quotes\" and \ 9097 1.1 mbalmer new line" 9098 1.9 nikita </pre><p> 9099 1.9 nikita This specifier does not support modifiers (flags, width, precision). 9100 1.9 nikita 9101 1.1 mbalmer 9102 1.1 mbalmer <p> 9103 1.9 nikita The conversion specifiers 9104 1.4 mbalmer <code>A</code>, <code>a</code>, <code>E</code>, <code>e</code>, <code>f</code>, 9105 1.2 lneto <code>G</code>, and <code>g</code> all expect a number as argument. 9106 1.9 nikita The specifiers <code>c</code>, <code>d</code>, 9107 1.2 lneto <code>i</code>, <code>o</code>, <code>u</code>, <code>X</code>, and <code>x</code> 9108 1.2 lneto expect an integer. 9109 1.6 salazar When Lua is compiled with a C89 compiler, 9110 1.9 nikita the specifiers <code>A</code> and <code>a</code> (hexadecimal floats) 9111 1.9 nikita do not support modifiers. 9112 1.6 salazar 9113 1.6 salazar 9114 1.6 salazar <p> 9115 1.9 nikita The specifier <code>s</code> expects a string; 9116 1.4 mbalmer if its argument is not a string, 9117 1.2 lneto it is converted to one following the same rules of <a href="#pdf-tostring"><code>tostring</code></a>. 9118 1.9 nikita If the specifier has any modifier, 9119 1.9 nikita the corresponding string argument should not contain embedded zeros. 9120 1.9 nikita 9121 1.9 nikita 9122 1.9 nikita <p> 9123 1.9 nikita The specifier <code>p</code> formats the pointer 9124 1.9 nikita returned by <a href="#lua_topointer"><code>lua_topointer</code></a>. 9125 1.9 nikita That gives a unique string identifier for tables, userdata, 9126 1.9 nikita threads, strings, and functions. 9127 1.9 nikita For other values (numbers, nil, booleans), 9128 1.9 nikita this specifier results in a string representing 9129 1.9 nikita the pointer <code>NULL</code>. 9130 1.1 mbalmer 9131 1.1 mbalmer 9132 1.1 mbalmer 9133 1.1 mbalmer 9134 1.1 mbalmer <p> 9135 1.9 nikita <hr><h3><a name="pdf-string.gmatch"><code>string.gmatch (s, pattern [, init])</code></a></h3> 9136 1.1 mbalmer Returns an iterator function that, 9137 1.1 mbalmer each time it is called, 9138 1.3 lneto returns the next captures from <code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) 9139 1.3 lneto over the string <code>s</code>. 9140 1.1 mbalmer If <code>pattern</code> specifies no captures, 9141 1.1 mbalmer then the whole match is produced in each call. 9142 1.9 nikita A third, optional numeric argument <code>init</code> specifies 9143 1.9 nikita where to start the search; 9144 1.9 nikita its default value is 1 and can be negative. 9145 1.1 mbalmer 9146 1.1 mbalmer 9147 1.1 mbalmer <p> 9148 1.1 mbalmer As an example, the following loop 9149 1.2 lneto will iterate over all the words from string <code>s</code>, 9150 1.2 lneto printing one per line: 9151 1.1 mbalmer 9152 1.1 mbalmer <pre> 9153 1.1 mbalmer s = "hello world from Lua" 9154 1.1 mbalmer for w in string.gmatch(s, "%a+") do 9155 1.1 mbalmer print(w) 9156 1.1 mbalmer end 9157 1.1 mbalmer </pre><p> 9158 1.1 mbalmer The next example collects all pairs <code>key=value</code> from the 9159 1.1 mbalmer given string into a table: 9160 1.1 mbalmer 9161 1.1 mbalmer <pre> 9162 1.1 mbalmer t = {} 9163 1.1 mbalmer s = "from=world, to=Lua" 9164 1.1 mbalmer for k, v in string.gmatch(s, "(%w+)=(%w+)") do 9165 1.1 mbalmer t[k] = v 9166 1.1 mbalmer end 9167 1.1 mbalmer </pre> 9168 1.1 mbalmer 9169 1.1 mbalmer <p> 9170 1.2 lneto For this function, a caret '<code>^</code>' at the start of a pattern does not 9171 1.1 mbalmer work as an anchor, as this would prevent the iteration. 9172 1.1 mbalmer 9173 1.1 mbalmer 9174 1.1 mbalmer 9175 1.1 mbalmer 9176 1.1 mbalmer <p> 9177 1.1 mbalmer <hr><h3><a name="pdf-string.gsub"><code>string.gsub (s, pattern, repl [, n])</code></a></h3> 9178 1.1 mbalmer Returns a copy of <code>s</code> 9179 1.1 mbalmer in which all (or the first <code>n</code>, if given) 9180 1.3 lneto occurrences of the <code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) have been 9181 1.1 mbalmer replaced by a replacement string specified by <code>repl</code>, 9182 1.1 mbalmer which can be a string, a table, or a function. 9183 1.1 mbalmer <code>gsub</code> also returns, as its second value, 9184 1.1 mbalmer the total number of matches that occurred. 9185 1.2 lneto The name <code>gsub</code> comes from <em>Global SUBstitution</em>. 9186 1.1 mbalmer 9187 1.1 mbalmer 9188 1.1 mbalmer <p> 9189 1.1 mbalmer If <code>repl</code> is a string, then its value is used for replacement. 9190 1.1 mbalmer The character <code>%</code> works as an escape character: 9191 1.2 lneto any sequence in <code>repl</code> of the form <code>%<em>d</em></code>, 9192 1.2 lneto with <em>d</em> between 1 and 9, 9193 1.9 nikita stands for the value of the <em>d</em>-th captured substring; 9194 1.9 nikita the sequence <code>%0</code> stands for the whole match; 9195 1.9 nikita the sequence <code>%%</code> stands for a single <code>%</code>. 9196 1.1 mbalmer 9197 1.1 mbalmer 9198 1.1 mbalmer <p> 9199 1.1 mbalmer If <code>repl</code> is a table, then the table is queried for every match, 9200 1.2 lneto using the first capture as the key. 9201 1.1 mbalmer 9202 1.1 mbalmer 9203 1.1 mbalmer <p> 9204 1.1 mbalmer If <code>repl</code> is a function, then this function is called every time a 9205 1.1 mbalmer match occurs, with all captured substrings passed as arguments, 9206 1.2 lneto in order. 9207 1.2 lneto 9208 1.2 lneto 9209 1.2 lneto <p> 9210 1.2 lneto In any case, 9211 1.1 mbalmer if the pattern specifies no captures, 9212 1.2 lneto then it behaves as if the whole pattern was inside a capture. 9213 1.1 mbalmer 9214 1.1 mbalmer 9215 1.1 mbalmer <p> 9216 1.1 mbalmer If the value returned by the table query or by the function call 9217 1.1 mbalmer is a string or a number, 9218 1.1 mbalmer then it is used as the replacement string; 9219 1.1 mbalmer otherwise, if it is <b>false</b> or <b>nil</b>, 9220 1.1 mbalmer then there is no replacement 9221 1.1 mbalmer (that is, the original match is kept in the string). 9222 1.1 mbalmer 9223 1.1 mbalmer 9224 1.1 mbalmer <p> 9225 1.1 mbalmer Here are some examples: 9226 1.1 mbalmer 9227 1.1 mbalmer <pre> 9228 1.1 mbalmer x = string.gsub("hello world", "(%w+)", "%1 %1") 9229 1.1 mbalmer --> x="hello hello world world" 9230 1.1 mbalmer 9231 1.1 mbalmer x = string.gsub("hello world", "%w+", "%0 %0", 1) 9232 1.1 mbalmer --> x="hello hello world" 9233 1.1 mbalmer 9234 1.1 mbalmer x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1") 9235 1.1 mbalmer --> x="world hello Lua from" 9236 1.1 mbalmer 9237 1.1 mbalmer x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv) 9238 1.1 mbalmer --> x="home = /home/roberto, user = roberto" 9239 1.1 mbalmer 9240 1.1 mbalmer x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s) 9241 1.2 lneto return load(s)() 9242 1.1 mbalmer end) 9243 1.1 mbalmer --> x="4+5 = 9" 9244 1.1 mbalmer 9245 1.9 nikita local t = {name="lua", version="5.4"} 9246 1.1 mbalmer x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t) 9247 1.9 nikita --> x="lua-5.4.tar.gz" 9248 1.1 mbalmer </pre> 9249 1.1 mbalmer 9250 1.1 mbalmer 9251 1.1 mbalmer 9252 1.1 mbalmer <p> 9253 1.1 mbalmer <hr><h3><a name="pdf-string.len"><code>string.len (s)</code></a></h3> 9254 1.9 nikita 9255 1.9 nikita 9256 1.9 nikita <p> 9257 1.1 mbalmer Receives a string and returns its length. 9258 1.1 mbalmer The empty string <code>""</code> has length 0. 9259 1.1 mbalmer Embedded zeros are counted, 9260 1.1 mbalmer so <code>"a\000bc\000"</code> has length 5. 9261 1.1 mbalmer 9262 1.1 mbalmer 9263 1.1 mbalmer 9264 1.1 mbalmer 9265 1.1 mbalmer <p> 9266 1.1 mbalmer <hr><h3><a name="pdf-string.lower"><code>string.lower (s)</code></a></h3> 9267 1.9 nikita 9268 1.9 nikita 9269 1.9 nikita <p> 9270 1.1 mbalmer Receives a string and returns a copy of this string with all 9271 1.1 mbalmer uppercase letters changed to lowercase. 9272 1.1 mbalmer All other characters are left unchanged. 9273 1.1 mbalmer The definition of what an uppercase letter is depends on the current locale. 9274 1.1 mbalmer 9275 1.1 mbalmer 9276 1.1 mbalmer 9277 1.1 mbalmer 9278 1.1 mbalmer <p> 9279 1.1 mbalmer <hr><h3><a name="pdf-string.match"><code>string.match (s, pattern [, init])</code></a></h3> 9280 1.9 nikita 9281 1.9 nikita 9282 1.9 nikita <p> 9283 1.1 mbalmer Looks for the first <em>match</em> of 9284 1.9 nikita the <code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) in the string <code>s</code>. 9285 1.1 mbalmer If it finds one, then <code>match</code> returns 9286 1.1 mbalmer the captures from the pattern; 9287 1.9 nikita otherwise it returns <b>fail</b>. 9288 1.1 mbalmer If <code>pattern</code> specifies no captures, 9289 1.1 mbalmer then the whole match is returned. 9290 1.4 mbalmer A third, optional numeric argument <code>init</code> specifies 9291 1.1 mbalmer where to start the search; 9292 1.1 mbalmer its default value is 1 and can be negative. 9293 1.1 mbalmer 9294 1.1 mbalmer 9295 1.1 mbalmer 9296 1.1 mbalmer 9297 1.1 mbalmer <p> 9298 1.3 lneto <hr><h3><a name="pdf-string.pack"><code>string.pack (fmt, v1, v2, ···)</code></a></h3> 9299 1.3 lneto 9300 1.3 lneto 9301 1.3 lneto <p> 9302 1.3 lneto Returns a binary string containing the values <code>v1</code>, <code>v2</code>, etc. 9303 1.9 nikita serialized in binary form (packed) 9304 1.7 mbalmer according to the format string <code>fmt</code> (see <a href="#6.4.2">§6.4.2</a>). 9305 1.3 lneto 9306 1.3 lneto 9307 1.3 lneto 9308 1.3 lneto 9309 1.3 lneto <p> 9310 1.3 lneto <hr><h3><a name="pdf-string.packsize"><code>string.packsize (fmt)</code></a></h3> 9311 1.3 lneto 9312 1.3 lneto 9313 1.3 lneto <p> 9314 1.3 lneto Returns the size of a string resulting from <a href="#pdf-string.pack"><code>string.pack</code></a> 9315 1.3 lneto with the given format. 9316 1.3 lneto The format string cannot have the variable-length options 9317 1.3 lneto '<code>s</code>' or '<code>z</code>' (see <a href="#6.4.2">§6.4.2</a>). 9318 1.3 lneto 9319 1.3 lneto 9320 1.3 lneto 9321 1.3 lneto 9322 1.3 lneto <p> 9323 1.2 lneto <hr><h3><a name="pdf-string.rep"><code>string.rep (s, n [, sep])</code></a></h3> 9324 1.9 nikita 9325 1.9 nikita 9326 1.9 nikita <p> 9327 1.1 mbalmer Returns a string that is the concatenation of <code>n</code> copies of 9328 1.2 lneto the string <code>s</code> separated by the string <code>sep</code>. 9329 1.2 lneto The default value for <code>sep</code> is the empty string 9330 1.2 lneto (that is, no separator). 9331 1.3 lneto Returns the empty string if <code>n</code> is not positive. 9332 1.1 mbalmer 9333 1.1 mbalmer 9334 1.5 lneto <p> 9335 1.5 lneto (Note that it is very easy to exhaust the memory of your machine 9336 1.5 lneto with a single call to this function.) 9337 1.5 lneto 9338 1.5 lneto 9339 1.1 mbalmer 9340 1.1 mbalmer 9341 1.1 mbalmer <p> 9342 1.1 mbalmer <hr><h3><a name="pdf-string.reverse"><code>string.reverse (s)</code></a></h3> 9343 1.9 nikita 9344 1.9 nikita 9345 1.9 nikita <p> 9346 1.1 mbalmer Returns a string that is the string <code>s</code> reversed. 9347 1.1 mbalmer 9348 1.1 mbalmer 9349 1.1 mbalmer 9350 1.1 mbalmer 9351 1.1 mbalmer <p> 9352 1.1 mbalmer <hr><h3><a name="pdf-string.sub"><code>string.sub (s, i [, j])</code></a></h3> 9353 1.9 nikita 9354 1.9 nikita 9355 1.9 nikita <p> 9356 1.1 mbalmer Returns the substring of <code>s</code> that 9357 1.1 mbalmer starts at <code>i</code> and continues until <code>j</code>; 9358 1.1 mbalmer <code>i</code> and <code>j</code> can be negative. 9359 1.1 mbalmer If <code>j</code> is absent, then it is assumed to be equal to -1 9360 1.1 mbalmer (which is the same as the string length). 9361 1.1 mbalmer In particular, 9362 1.1 mbalmer the call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code> 9363 1.1 mbalmer with length <code>j</code>, 9364 1.7 mbalmer and <code>string.sub(s, -i)</code> (for a positive <code>i</code>) 9365 1.7 mbalmer returns a suffix of <code>s</code> 9366 1.1 mbalmer with length <code>i</code>. 9367 1.1 mbalmer 9368 1.1 mbalmer 9369 1.2 lneto <p> 9370 1.2 lneto If, after the translation of negative indices, 9371 1.2 lneto <code>i</code> is less than 1, 9372 1.2 lneto it is corrected to 1. 9373 1.2 lneto If <code>j</code> is greater than the string length, 9374 1.2 lneto it is corrected to that length. 9375 1.2 lneto If, after these corrections, 9376 1.2 lneto <code>i</code> is greater than <code>j</code>, 9377 1.2 lneto the function returns the empty string. 9378 1.2 lneto 9379 1.2 lneto 9380 1.2 lneto 9381 1.2 lneto 9382 1.2 lneto <p> 9383 1.3 lneto <hr><h3><a name="pdf-string.unpack"><code>string.unpack (fmt, s [, pos])</code></a></h3> 9384 1.2 lneto 9385 1.2 lneto 9386 1.2 lneto <p> 9387 1.3 lneto Returns the values packed in string <code>s</code> (see <a href="#pdf-string.pack"><code>string.pack</code></a>) 9388 1.3 lneto according to the format string <code>fmt</code> (see <a href="#6.4.2">§6.4.2</a>). 9389 1.3 lneto An optional <code>pos</code> marks where 9390 1.3 lneto to start reading in <code>s</code> (default is 1). 9391 1.3 lneto After the read values, 9392 1.3 lneto this function also returns the index of the first unread byte in <code>s</code>. 9393 1.2 lneto 9394 1.2 lneto 9395 1.1 mbalmer 9396 1.1 mbalmer 9397 1.1 mbalmer <p> 9398 1.1 mbalmer <hr><h3><a name="pdf-string.upper"><code>string.upper (s)</code></a></h3> 9399 1.9 nikita 9400 1.9 nikita 9401 1.9 nikita <p> 9402 1.1 mbalmer Receives a string and returns a copy of this string with all 9403 1.1 mbalmer lowercase letters changed to uppercase. 9404 1.1 mbalmer All other characters are left unchanged. 9405 1.1 mbalmer The definition of what a lowercase letter is depends on the current locale. 9406 1.1 mbalmer 9407 1.1 mbalmer 9408 1.1 mbalmer 9409 1.3 lneto 9410 1.3 lneto 9411 1.9 nikita 9412 1.9 nikita 9413 1.2 lneto <h3>6.4.1 – <a name="6.4.1">Patterns</a></h3> 9414 1.1 mbalmer 9415 1.9 nikita 9416 1.9 nikita 9417 1.3 lneto <p> 9418 1.3 lneto Patterns in Lua are described by regular strings, 9419 1.3 lneto which are interpreted as patterns by the pattern-matching functions 9420 1.3 lneto <a href="#pdf-string.find"><code>string.find</code></a>, 9421 1.3 lneto <a href="#pdf-string.gmatch"><code>string.gmatch</code></a>, 9422 1.3 lneto <a href="#pdf-string.gsub"><code>string.gsub</code></a>, 9423 1.3 lneto and <a href="#pdf-string.match"><code>string.match</code></a>. 9424 1.3 lneto This section describes the syntax and the meaning 9425 1.3 lneto (that is, what they match) of these strings. 9426 1.3 lneto 9427 1.3 lneto 9428 1.1 mbalmer 9429 1.9 nikita 9430 1.9 nikita 9431 1.1 mbalmer <h4>Character Class:</h4><p> 9432 1.1 mbalmer A <em>character class</em> is used to represent a set of characters. 9433 1.1 mbalmer The following combinations are allowed in describing a character class: 9434 1.1 mbalmer 9435 1.1 mbalmer <ul> 9436 1.1 mbalmer 9437 1.2 lneto <li><b><em>x</em>: </b> 9438 1.1 mbalmer (where <em>x</em> is not one of the <em>magic characters</em> 9439 1.1 mbalmer <code>^$()%.[]*+-?</code>) 9440 1.1 mbalmer represents the character <em>x</em> itself. 9441 1.1 mbalmer </li> 9442 1.1 mbalmer 9443 1.2 lneto <li><b><code>.</code>: </b> (a dot) represents all characters.</li> 9444 1.1 mbalmer 9445 1.2 lneto <li><b><code>%a</code>: </b> represents all letters.</li> 9446 1.1 mbalmer 9447 1.2 lneto <li><b><code>%c</code>: </b> represents all control characters.</li> 9448 1.1 mbalmer 9449 1.2 lneto <li><b><code>%d</code>: </b> represents all digits.</li> 9450 1.1 mbalmer 9451 1.2 lneto <li><b><code>%g</code>: </b> represents all printable characters except space.</li> 9452 1.1 mbalmer 9453 1.2 lneto <li><b><code>%l</code>: </b> represents all lowercase letters.</li> 9454 1.1 mbalmer 9455 1.2 lneto <li><b><code>%p</code>: </b> represents all punctuation characters.</li> 9456 1.1 mbalmer 9457 1.2 lneto <li><b><code>%s</code>: </b> represents all space characters.</li> 9458 1.1 mbalmer 9459 1.2 lneto <li><b><code>%u</code>: </b> represents all uppercase letters.</li> 9460 1.1 mbalmer 9461 1.2 lneto <li><b><code>%w</code>: </b> represents all alphanumeric characters.</li> 9462 1.1 mbalmer 9463 1.2 lneto <li><b><code>%x</code>: </b> represents all hexadecimal digits.</li> 9464 1.1 mbalmer 9465 1.2 lneto <li><b><code>%<em>x</em></code>: </b> (where <em>x</em> is any non-alphanumeric character) 9466 1.1 mbalmer represents the character <em>x</em>. 9467 1.1 mbalmer This is the standard way to escape the magic characters. 9468 1.3 lneto Any non-alphanumeric character 9469 1.4 mbalmer (including all punctuation characters, even the non-magical) 9470 1.9 nikita can be preceded by a '<code>%</code>' to represent itself in a pattern. 9471 1.1 mbalmer </li> 9472 1.1 mbalmer 9473 1.2 lneto <li><b><code>[<em>set</em>]</code>: </b> 9474 1.1 mbalmer represents the class which is the union of all 9475 1.1 mbalmer characters in <em>set</em>. 9476 1.1 mbalmer A range of characters can be specified by 9477 1.2 lneto separating the end characters of the range, 9478 1.2 lneto in ascending order, with a '<code>-</code>'. 9479 1.1 mbalmer All classes <code>%</code><em>x</em> described above can also be used as 9480 1.1 mbalmer components in <em>set</em>. 9481 1.1 mbalmer All other characters in <em>set</em> represent themselves. 9482 1.1 mbalmer For example, <code>[%w_]</code> (or <code>[_%w]</code>) 9483 1.1 mbalmer represents all alphanumeric characters plus the underscore, 9484 1.1 mbalmer <code>[0-7]</code> represents the octal digits, 9485 1.1 mbalmer and <code>[0-7%l%-]</code> represents the octal digits plus 9486 1.1 mbalmer the lowercase letters plus the '<code>-</code>' character. 9487 1.1 mbalmer 9488 1.1 mbalmer 9489 1.1 mbalmer <p> 9490 1.6 salazar You can put a closing square bracket in a set 9491 1.6 salazar by positioning it as the first character in the set. 9492 1.8 alnsn You can put a hyphen in a set 9493 1.6 salazar by positioning it as the first or the last character in the set. 9494 1.6 salazar (You can also use an escape for both cases.) 9495 1.6 salazar 9496 1.6 salazar 9497 1.6 salazar <p> 9498 1.1 mbalmer The interaction between ranges and classes is not defined. 9499 1.1 mbalmer Therefore, patterns like <code>[%a-z]</code> or <code>[a-%%]</code> 9500 1.1 mbalmer have no meaning. 9501 1.1 mbalmer </li> 9502 1.1 mbalmer 9503 1.2 lneto <li><b><code>[^<em>set</em>]</code>: </b> 9504 1.1 mbalmer represents the complement of <em>set</em>, 9505 1.1 mbalmer where <em>set</em> is interpreted as above. 9506 1.1 mbalmer </li> 9507 1.1 mbalmer 9508 1.1 mbalmer </ul><p> 9509 1.1 mbalmer For all classes represented by single letters (<code>%a</code>, <code>%c</code>, etc.), 9510 1.1 mbalmer the corresponding uppercase letter represents the complement of the class. 9511 1.1 mbalmer For instance, <code>%S</code> represents all non-space characters. 9512 1.1 mbalmer 9513 1.1 mbalmer 9514 1.1 mbalmer <p> 9515 1.1 mbalmer The definitions of letter, space, and other character groups 9516 1.1 mbalmer depend on the current locale. 9517 1.1 mbalmer In particular, the class <code>[a-z]</code> may not be equivalent to <code>%l</code>. 9518 1.1 mbalmer 9519 1.1 mbalmer 9520 1.1 mbalmer 9521 1.1 mbalmer 9522 1.1 mbalmer 9523 1.1 mbalmer <h4>Pattern Item:</h4><p> 9524 1.1 mbalmer A <em>pattern item</em> can be 9525 1.1 mbalmer 9526 1.1 mbalmer <ul> 9527 1.1 mbalmer 9528 1.1 mbalmer <li> 9529 1.1 mbalmer a single character class, 9530 1.1 mbalmer which matches any single character in the class; 9531 1.1 mbalmer </li> 9532 1.1 mbalmer 9533 1.1 mbalmer <li> 9534 1.1 mbalmer a single character class followed by '<code>*</code>', 9535 1.9 nikita which matches sequences of zero or more characters in the class. 9536 1.1 mbalmer These repetition items will always match the longest possible sequence; 9537 1.1 mbalmer </li> 9538 1.1 mbalmer 9539 1.1 mbalmer <li> 9540 1.1 mbalmer a single character class followed by '<code>+</code>', 9541 1.9 nikita which matches sequences of one or more characters in the class. 9542 1.1 mbalmer These repetition items will always match the longest possible sequence; 9543 1.1 mbalmer </li> 9544 1.1 mbalmer 9545 1.1 mbalmer <li> 9546 1.1 mbalmer a single character class followed by '<code>-</code>', 9547 1.9 nikita which also matches sequences of zero or more characters in the class. 9548 1.1 mbalmer Unlike '<code>*</code>', 9549 1.2 lneto these repetition items will always match the shortest possible sequence; 9550 1.1 mbalmer </li> 9551 1.1 mbalmer 9552 1.1 mbalmer <li> 9553 1.1 mbalmer a single character class followed by '<code>?</code>', 9554 1.3 lneto which matches zero or one occurrence of a character in the class. 9555 1.3 lneto It always matches one occurrence if possible; 9556 1.1 mbalmer </li> 9557 1.1 mbalmer 9558 1.1 mbalmer <li> 9559 1.1 mbalmer <code>%<em>n</em></code>, for <em>n</em> between 1 and 9; 9560 1.1 mbalmer such item matches a substring equal to the <em>n</em>-th captured string 9561 1.1 mbalmer (see below); 9562 1.1 mbalmer </li> 9563 1.1 mbalmer 9564 1.1 mbalmer <li> 9565 1.1 mbalmer <code>%b<em>xy</em></code>, where <em>x</em> and <em>y</em> are two distinct characters; 9566 1.1 mbalmer such item matches strings that start with <em>x</em>, end with <em>y</em>, 9567 1.1 mbalmer and where the <em>x</em> and <em>y</em> are <em>balanced</em>. 9568 1.1 mbalmer This means that, if one reads the string from left to right, 9569 1.1 mbalmer counting <em>+1</em> for an <em>x</em> and <em>-1</em> for a <em>y</em>, 9570 1.1 mbalmer the ending <em>y</em> is the first <em>y</em> where the count reaches 0. 9571 1.1 mbalmer For instance, the item <code>%b()</code> matches expressions with 9572 1.1 mbalmer balanced parentheses. 9573 1.1 mbalmer </li> 9574 1.1 mbalmer 9575 1.2 lneto <li> 9576 1.2 lneto <code>%f[<em>set</em>]</code>, a <em>frontier pattern</em>; 9577 1.2 lneto such item matches an empty string at any position such that 9578 1.2 lneto the next character belongs to <em>set</em> 9579 1.2 lneto and the previous character does not belong to <em>set</em>. 9580 1.2 lneto The set <em>set</em> is interpreted as previously described. 9581 1.2 lneto The beginning and the end of the subject are handled as if 9582 1.2 lneto they were the character '<code>\0</code>'. 9583 1.2 lneto </li> 9584 1.2 lneto 9585 1.1 mbalmer </ul> 9586 1.1 mbalmer 9587 1.1 mbalmer 9588 1.1 mbalmer 9589 1.1 mbalmer 9590 1.1 mbalmer <h4>Pattern:</h4><p> 9591 1.1 mbalmer A <em>pattern</em> is a sequence of pattern items. 9592 1.2 lneto A caret '<code>^</code>' at the beginning of a pattern anchors the match at the 9593 1.1 mbalmer beginning of the subject string. 9594 1.1 mbalmer A '<code>$</code>' at the end of a pattern anchors the match at the 9595 1.1 mbalmer end of the subject string. 9596 1.1 mbalmer At other positions, 9597 1.1 mbalmer '<code>^</code>' and '<code>$</code>' have no special meaning and represent themselves. 9598 1.1 mbalmer 9599 1.1 mbalmer 9600 1.1 mbalmer 9601 1.1 mbalmer 9602 1.1 mbalmer 9603 1.1 mbalmer <h4>Captures:</h4><p> 9604 1.1 mbalmer A pattern can contain sub-patterns enclosed in parentheses; 9605 1.1 mbalmer they describe <em>captures</em>. 9606 1.1 mbalmer When a match succeeds, the substrings of the subject string 9607 1.1 mbalmer that match captures are stored (<em>captured</em>) for future use. 9608 1.1 mbalmer Captures are numbered according to their left parentheses. 9609 1.1 mbalmer For instance, in the pattern <code>"(a*(.)%w(%s*))"</code>, 9610 1.1 mbalmer the part of the string matching <code>"a*(.)%w(%s*)"</code> is 9611 1.9 nikita stored as the first capture, and therefore has number 1; 9612 1.1 mbalmer the character matching "<code>.</code>" is captured with number 2, 9613 1.1 mbalmer and the part matching "<code>%s*</code>" has number 3. 9614 1.1 mbalmer 9615 1.1 mbalmer 9616 1.1 mbalmer <p> 9617 1.9 nikita As a special case, the capture <code>()</code> captures 9618 1.1 mbalmer the current string position (a number). 9619 1.1 mbalmer For instance, if we apply the pattern <code>"()aa()"</code> on the 9620 1.1 mbalmer string <code>"flaaap"</code>, there will be two captures: 3 and 5. 9621 1.1 mbalmer 9622 1.1 mbalmer 9623 1.2 lneto 9624 1.2 lneto 9625 1.2 lneto 9626 1.9 nikita <h4>Multiple matches:</h4><p> 9627 1.9 nikita The function <a href="#pdf-string.gsub"><code>string.gsub</code></a> and the iterator <a href="#pdf-string.gmatch"><code>string.gmatch</code></a> 9628 1.9 nikita match multiple occurrences of the given pattern in the subject. 9629 1.9 nikita For these functions, 9630 1.9 nikita a new match is considered valid only 9631 1.9 nikita if it ends at least one byte after the end of the previous match. 9632 1.9 nikita In other words, the pattern machine never accepts the 9633 1.9 nikita empty string as a match immediately after another match. 9634 1.9 nikita As an example, 9635 1.9 nikita consider the results of the following code: 9636 1.9 nikita 9637 1.9 nikita <pre> 9638 1.9 nikita > string.gsub("abc", "()a*()", print); 9639 1.9 nikita --> 1 2 9640 1.9 nikita --> 3 3 9641 1.9 nikita --> 4 4 9642 1.9 nikita </pre><p> 9643 1.9 nikita The second and third results come from Lua matching an empty 9644 1.9 nikita string after '<code>b</code>' and another one after '<code>c</code>'. 9645 1.9 nikita Lua does not match an empty string after '<code>a</code>', 9646 1.9 nikita because it would end at the same position of the previous match. 9647 1.9 nikita 9648 1.9 nikita 9649 1.9 nikita 9650 1.9 nikita 9651 1.9 nikita 9652 1.2 lneto 9653 1.2 lneto 9654 1.3 lneto <h3>6.4.2 – <a name="6.4.2">Format Strings for Pack and Unpack</a></h3> 9655 1.3 lneto 9656 1.3 lneto <p> 9657 1.3 lneto The first argument to <a href="#pdf-string.pack"><code>string.pack</code></a>, 9658 1.3 lneto <a href="#pdf-string.packsize"><code>string.packsize</code></a>, and <a href="#pdf-string.unpack"><code>string.unpack</code></a> 9659 1.3 lneto is a format string, 9660 1.3 lneto which describes the layout of the structure being created or read. 9661 1.3 lneto 9662 1.3 lneto 9663 1.3 lneto <p> 9664 1.3 lneto A format string is a sequence of conversion options. 9665 1.3 lneto The conversion options are as follows: 9666 1.3 lneto 9667 1.3 lneto <ul> 9668 1.3 lneto <li><b><code><</code>: </b>sets little endian</li> 9669 1.3 lneto <li><b><code>></code>: </b>sets big endian</li> 9670 1.3 lneto <li><b><code>=</code>: </b>sets native endian</li> 9671 1.3 lneto <li><b><code>![<em>n</em>]</code>: </b>sets maximum alignment to <code>n</code> 9672 1.3 lneto (default is native alignment)</li> 9673 1.3 lneto <li><b><code>b</code>: </b>a signed byte (<code>char</code>)</li> 9674 1.3 lneto <li><b><code>B</code>: </b>an unsigned byte (<code>char</code>)</li> 9675 1.3 lneto <li><b><code>h</code>: </b>a signed <code>short</code> (native size)</li> 9676 1.3 lneto <li><b><code>H</code>: </b>an unsigned <code>short</code> (native size)</li> 9677 1.3 lneto <li><b><code>l</code>: </b>a signed <code>long</code> (native size)</li> 9678 1.3 lneto <li><b><code>L</code>: </b>an unsigned <code>long</code> (native size)</li> 9679 1.3 lneto <li><b><code>j</code>: </b>a <code>lua_Integer</code></li> 9680 1.3 lneto <li><b><code>J</code>: </b>a <code>lua_Unsigned</code></li> 9681 1.3 lneto <li><b><code>T</code>: </b>a <code>size_t</code> (native size)</li> 9682 1.3 lneto <li><b><code>i[<em>n</em>]</code>: </b>a signed <code>int</code> with <code>n</code> bytes 9683 1.3 lneto (default is native size)</li> 9684 1.3 lneto <li><b><code>I[<em>n</em>]</code>: </b>an unsigned <code>int</code> with <code>n</code> bytes 9685 1.3 lneto (default is native size)</li> 9686 1.3 lneto <li><b><code>f</code>: </b>a <code>float</code> (native size)</li> 9687 1.3 lneto <li><b><code>d</code>: </b>a <code>double</code> (native size)</li> 9688 1.3 lneto <li><b><code>n</code>: </b>a <code>lua_Number</code></li> 9689 1.3 lneto <li><b><code>c<em>n</em></code>: </b>a fixed-sized string with <code>n</code> bytes</li> 9690 1.3 lneto <li><b><code>z</code>: </b>a zero-terminated string</li> 9691 1.3 lneto <li><b><code>s[<em>n</em>]</code>: </b>a string preceded by its length 9692 1.3 lneto coded as an unsigned integer with <code>n</code> bytes 9693 1.3 lneto (default is a <code>size_t</code>)</li> 9694 1.3 lneto <li><b><code>x</code>: </b>one byte of padding</li> 9695 1.3 lneto <li><b><code>X<em>op</em></code>: </b>an empty item that aligns 9696 1.3 lneto according to option <code>op</code> 9697 1.3 lneto (which is otherwise ignored)</li> 9698 1.9 nikita <li><b>'<code> </code>': </b>(space) ignored</li> 9699 1.3 lneto </ul><p> 9700 1.3 lneto (A "<code>[<em>n</em>]</code>" means an optional integral numeral.) 9701 1.3 lneto Except for padding, spaces, and configurations 9702 1.3 lneto (options "<code>xX <=>!</code>"), 9703 1.9 nikita each option corresponds to an argument in <a href="#pdf-string.pack"><code>string.pack</code></a> 9704 1.9 nikita or a result in <a href="#pdf-string.unpack"><code>string.unpack</code></a>. 9705 1.3 lneto 9706 1.3 lneto 9707 1.3 lneto <p> 9708 1.3 lneto For 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>", 9709 1.3 lneto <code>n</code> can be any integer between 1 and 16. 9710 1.3 lneto All integral options check overflows; 9711 1.3 lneto <a href="#pdf-string.pack"><code>string.pack</code></a> checks whether the given value fits in the given size; 9712 1.3 lneto <a href="#pdf-string.unpack"><code>string.unpack</code></a> checks whether the read value fits in a Lua integer. 9713 1.9 nikita For the unsigned options, 9714 1.9 nikita Lua integers are treated as unsigned values too. 9715 1.3 lneto 9716 1.3 lneto 9717 1.3 lneto <p> 9718 1.3 lneto Any format string starts as if prefixed by "<code>!1=</code>", 9719 1.3 lneto that is, 9720 1.3 lneto with maximum alignment of 1 (no alignment) 9721 1.3 lneto and native endianness. 9722 1.3 lneto 9723 1.3 lneto 9724 1.3 lneto <p> 9725 1.9 nikita Native endianness assumes that the whole system is 9726 1.9 nikita either big or little endian. 9727 1.9 nikita The packing functions will not emulate correctly the behavior 9728 1.9 nikita of mixed-endian formats. 9729 1.9 nikita 9730 1.9 nikita 9731 1.9 nikita <p> 9732 1.3 lneto Alignment works as follows: 9733 1.3 lneto For each option, 9734 1.3 lneto the format gets extra padding until the data starts 9735 1.3 lneto at an offset that is a multiple of the minimum between the 9736 1.3 lneto option size and the maximum alignment; 9737 1.3 lneto this minimum must be a power of 2. 9738 1.3 lneto Options "<code>c</code>" and "<code>z</code>" are not aligned; 9739 1.3 lneto option "<code>s</code>" follows the alignment of its starting integer. 9740 1.3 lneto 9741 1.3 lneto 9742 1.3 lneto <p> 9743 1.3 lneto All padding is filled with zeros by <a href="#pdf-string.pack"><code>string.pack</code></a> 9744 1.9 nikita and ignored by <a href="#pdf-string.unpack"><code>string.unpack</code></a>. 9745 1.3 lneto 9746 1.3 lneto 9747 1.3 lneto 9748 1.2 lneto 9749 1.2 lneto 9750 1.2 lneto 9751 1.2 lneto 9752 1.2 lneto <h2>6.5 – <a name="6.5">UTF-8 Support</a></h2> 9753 1.2 lneto 9754 1.2 lneto <p> 9755 1.2 lneto This library provides basic support for UTF-8 encoding. 9756 1.2 lneto It provides all its functions inside the table <a name="pdf-utf8"><code>utf8</code></a>. 9757 1.2 lneto This library does not provide any support for Unicode other 9758 1.2 lneto than the handling of the encoding. 9759 1.2 lneto Any operation that needs the meaning of a character, 9760 1.2 lneto such as character classification, is outside its scope. 9761 1.2 lneto 9762 1.2 lneto 9763 1.2 lneto <p> 9764 1.2 lneto Unless stated otherwise, 9765 1.2 lneto all functions that expect a byte position as a parameter 9766 1.2 lneto assume that the given position is either the start of a byte sequence 9767 1.2 lneto or one plus the length of the subject string. 9768 1.2 lneto As in the string library, 9769 1.2 lneto negative indices count from the end of the string. 9770 1.2 lneto 9771 1.2 lneto 9772 1.2 lneto <p> 9773 1.9 nikita Functions that create byte sequences 9774 1.9 nikita accept all values up to <code>0x7FFFFFFF</code>, 9775 1.9 nikita as defined in the original UTF-8 specification; 9776 1.9 nikita that implies byte sequences of up to six bytes. 9777 1.9 nikita 9778 1.9 nikita 9779 1.9 nikita <p> 9780 1.9 nikita Functions that interpret byte sequences only accept 9781 1.9 nikita valid sequences (well formed and not overlong). 9782 1.9 nikita By default, they only accept byte sequences 9783 1.9 nikita that result in valid Unicode code points, 9784 1.9 nikita rejecting values greater than <code>10FFFF</code> and surrogates. 9785 1.9 nikita A boolean argument <code>lax</code>, when available, 9786 1.9 nikita lifts these checks, 9787 1.9 nikita so that all values up to <code>0x7FFFFFFF</code> are accepted. 9788 1.9 nikita (Not well formed and overlong sequences are still rejected.) 9789 1.9 nikita 9790 1.9 nikita 9791 1.9 nikita <p> 9792 1.2 lneto <hr><h3><a name="pdf-utf8.char"><code>utf8.char (···)</code></a></h3> 9793 1.9 nikita 9794 1.9 nikita 9795 1.9 nikita <p> 9796 1.2 lneto Receives zero or more integers, 9797 1.2 lneto converts each one to its corresponding UTF-8 byte sequence 9798 1.2 lneto and returns a string with the concatenation of all these sequences. 9799 1.2 lneto 9800 1.2 lneto 9801 1.2 lneto 9802 1.2 lneto 9803 1.2 lneto <p> 9804 1.3 lneto <hr><h3><a name="pdf-utf8.charpattern"><code>utf8.charpattern</code></a></h3> 9805 1.9 nikita 9806 1.9 nikita 9807 1.9 nikita <p> 9808 1.9 nikita The pattern (a string, not a function) "<code>[\0-\x7F\xC2-\xFD][\x80-\xBF]*</code>" 9809 1.2 lneto (see <a href="#6.4.1">§6.4.1</a>), 9810 1.2 lneto which matches exactly one UTF-8 byte sequence, 9811 1.2 lneto assuming that the subject is a valid UTF-8 string. 9812 1.2 lneto 9813 1.2 lneto 9814 1.2 lneto 9815 1.2 lneto 9816 1.2 lneto <p> 9817 1.9 nikita <hr><h3><a name="pdf-utf8.codes"><code>utf8.codes (s [, lax])</code></a></h3> 9818 1.2 lneto 9819 1.2 lneto 9820 1.2 lneto <p> 9821 1.2 lneto Returns values so that the construction 9822 1.2 lneto 9823 1.2 lneto <pre> 9824 1.2 lneto for p, c in utf8.codes(s) do <em>body</em> end 9825 1.2 lneto </pre><p> 9826 1.9 nikita will iterate over all UTF-8 characters in string <code>s</code>, 9827 1.2 lneto with <code>p</code> being the position (in bytes) and <code>c</code> the code point 9828 1.2 lneto of each character. 9829 1.2 lneto It raises an error if it meets any invalid byte sequence. 9830 1.2 lneto 9831 1.2 lneto 9832 1.2 lneto 9833 1.2 lneto 9834 1.2 lneto <p> 9835 1.9 nikita <hr><h3><a name="pdf-utf8.codepoint"><code>utf8.codepoint (s [, i [, j [, lax]]])</code></a></h3> 9836 1.9 nikita 9837 1.9 nikita 9838 1.9 nikita <p> 9839 1.9 nikita Returns the code points (as integers) from all characters in <code>s</code> 9840 1.2 lneto that start between byte position <code>i</code> and <code>j</code> (both included). 9841 1.2 lneto The default for <code>i</code> is 1 and for <code>j</code> is <code>i</code>. 9842 1.2 lneto It raises an error if it meets any invalid byte sequence. 9843 1.2 lneto 9844 1.2 lneto 9845 1.2 lneto 9846 1.2 lneto 9847 1.2 lneto <p> 9848 1.9 nikita <hr><h3><a name="pdf-utf8.len"><code>utf8.len (s [, i [, j [, lax]]])</code></a></h3> 9849 1.9 nikita 9850 1.9 nikita 9851 1.9 nikita <p> 9852 1.2 lneto Returns the number of UTF-8 characters in string <code>s</code> 9853 1.3 lneto that start between positions <code>i</code> and <code>j</code> (both inclusive). 9854 1.2 lneto The default for <code>i</code> is 1 and for <code>j</code> is -1. 9855 1.2 lneto If it finds any invalid byte sequence, 9856 1.9 nikita returns <b>fail</b> plus the position of the first invalid byte. 9857 1.2 lneto 9858 1.2 lneto 9859 1.2 lneto 9860 1.2 lneto 9861 1.2 lneto <p> 9862 1.2 lneto <hr><h3><a name="pdf-utf8.offset"><code>utf8.offset (s, n [, i])</code></a></h3> 9863 1.9 nikita 9864 1.9 nikita 9865 1.9 nikita <p> 9866 1.2 lneto Returns the position (in bytes) where the encoding of the 9867 1.2 lneto <code>n</code>-th character of <code>s</code> 9868 1.2 lneto (counting from position <code>i</code>) starts. 9869 1.2 lneto A negative <code>n</code> gets characters before position <code>i</code>. 9870 1.2 lneto The default for <code>i</code> is 1 when <code>n</code> is non-negative 9871 1.2 lneto and <code>#s + 1</code> otherwise, 9872 1.2 lneto so that <code>utf8.offset(s, -n)</code> gets the offset of the 9873 1.2 lneto <code>n</code>-th character from the end of the string. 9874 1.3 lneto If the specified character is neither in the subject 9875 1.3 lneto nor right after its end, 9876 1.9 nikita the function returns <b>fail</b>. 9877 1.2 lneto 9878 1.2 lneto 9879 1.2 lneto <p> 9880 1.2 lneto As a special case, 9881 1.2 lneto when <code>n</code> is 0 the function returns the start of the encoding 9882 1.2 lneto of the character that contains the <code>i</code>-th byte of <code>s</code>. 9883 1.2 lneto 9884 1.2 lneto 9885 1.1 mbalmer <p> 9886 1.2 lneto This function assumes that <code>s</code> is a valid UTF-8 string. 9887 1.1 mbalmer 9888 1.1 mbalmer 9889 1.1 mbalmer 9890 1.1 mbalmer 9891 1.1 mbalmer 9892 1.1 mbalmer 9893 1.1 mbalmer 9894 1.2 lneto <h2>6.6 – <a name="6.6">Table Manipulation</a></h2> 9895 1.2 lneto 9896 1.2 lneto <p> 9897 1.2 lneto This library provides generic functions for table manipulation. 9898 1.2 lneto It provides all its functions inside the table <a name="pdf-table"><code>table</code></a>. 9899 1.1 mbalmer 9900 1.1 mbalmer 9901 1.2 lneto <p> 9902 1.2 lneto Remember that, whenever an operation needs the length of a table, 9903 1.7 mbalmer all caveats about the length operator apply (see <a href="#3.4.7">§3.4.7</a>). 9904 1.2 lneto All functions ignore non-numeric keys 9905 1.3 lneto in the tables given as arguments. 9906 1.1 mbalmer 9907 1.1 mbalmer 9908 1.1 mbalmer <p> 9909 1.2 lneto <hr><h3><a name="pdf-table.concat"><code>table.concat (list [, sep [, i [, j]]])</code></a></h3> 9910 1.1 mbalmer 9911 1.1 mbalmer 9912 1.1 mbalmer <p> 9913 1.2 lneto Given a list where all elements are strings or numbers, 9914 1.2 lneto returns the string <code>list[i]..sep..list[i+1] ··· sep..list[j]</code>. 9915 1.1 mbalmer The default value for <code>sep</code> is the empty string, 9916 1.1 mbalmer the default for <code>i</code> is 1, 9917 1.2 lneto and the default for <code>j</code> is <code>#list</code>. 9918 1.1 mbalmer If <code>i</code> is greater than <code>j</code>, returns the empty string. 9919 1.1 mbalmer 9920 1.1 mbalmer 9921 1.1 mbalmer 9922 1.1 mbalmer 9923 1.1 mbalmer <p> 9924 1.2 lneto <hr><h3><a name="pdf-table.insert"><code>table.insert (list, [pos,] value)</code></a></h3> 9925 1.1 mbalmer 9926 1.1 mbalmer 9927 1.1 mbalmer <p> 9928 1.2 lneto Inserts element <code>value</code> at position <code>pos</code> in <code>list</code>, 9929 1.2 lneto shifting up the elements 9930 1.2 lneto <code>list[pos], list[pos+1], ···, list[#list]</code>. 9931 1.2 lneto The default value for <code>pos</code> is <code>#list+1</code>, 9932 1.1 mbalmer so that a call <code>table.insert(t,x)</code> inserts <code>x</code> at the end 9933 1.9 nikita of the list <code>t</code>. 9934 1.1 mbalmer 9935 1.1 mbalmer 9936 1.1 mbalmer 9937 1.1 mbalmer 9938 1.1 mbalmer <p> 9939 1.3 lneto <hr><h3><a name="pdf-table.move"><code>table.move (a1, f, e, t [,a2])</code></a></h3> 9940 1.3 lneto 9941 1.3 lneto 9942 1.3 lneto <p> 9943 1.9 nikita Moves elements from the table <code>a1</code> to the table <code>a2</code>, 9944 1.6 salazar performing the equivalent to the following 9945 1.3 lneto multiple assignment: 9946 1.3 lneto <code>a2[t],··· = a1[f],···,a1[e]</code>. 9947 1.3 lneto The default for <code>a2</code> is <code>a1</code>. 9948 1.3 lneto The destination range can overlap with the source range. 9949 1.4 mbalmer The number of elements to be moved must fit in a Lua integer. 9950 1.3 lneto 9951 1.3 lneto 9952 1.6 salazar <p> 9953 1.6 salazar Returns the destination table <code>a2</code>. 9954 1.6 salazar 9955 1.6 salazar 9956 1.3 lneto 9957 1.3 lneto 9958 1.3 lneto <p> 9959 1.2 lneto <hr><h3><a name="pdf-table.pack"><code>table.pack (···)</code></a></h3> 9960 1.1 mbalmer 9961 1.1 mbalmer 9962 1.1 mbalmer <p> 9963 1.8 alnsn Returns a new table with all arguments stored into keys 1, 2, etc. 9964 1.8 alnsn and with a field "<code>n</code>" with the total number of arguments. 9965 1.9 nikita Note that the resulting table may not be a sequence, 9966 1.9 nikita if some arguments are <b>nil</b>. 9967 1.1 mbalmer 9968 1.1 mbalmer 9969 1.1 mbalmer 9970 1.1 mbalmer 9971 1.1 mbalmer <p> 9972 1.2 lneto <hr><h3><a name="pdf-table.remove"><code>table.remove (list [, pos])</code></a></h3> 9973 1.1 mbalmer 9974 1.1 mbalmer 9975 1.1 mbalmer <p> 9976 1.2 lneto Removes from <code>list</code> the element at position <code>pos</code>, 9977 1.2 lneto returning the value of the removed element. 9978 1.2 lneto When <code>pos</code> is an integer between 1 and <code>#list</code>, 9979 1.2 lneto it shifts down the elements 9980 1.2 lneto <code>list[pos+1], list[pos+2], ···, list[#list]</code> 9981 1.2 lneto and erases element <code>list[#list]</code>; 9982 1.2 lneto The index <code>pos</code> can also be 0 when <code>#list</code> is 0, 9983 1.9 nikita or <code>#list + 1</code>. 9984 1.2 lneto 9985 1.2 lneto 9986 1.2 lneto <p> 9987 1.2 lneto The default value for <code>pos</code> is <code>#list</code>, 9988 1.2 lneto so that a call <code>table.remove(l)</code> removes the last element 9989 1.9 nikita of the list <code>l</code>. 9990 1.2 lneto 9991 1.1 mbalmer 9992 1.1 mbalmer 9993 1.1 mbalmer 9994 1.2 lneto <p> 9995 1.2 lneto <hr><h3><a name="pdf-table.sort"><code>table.sort (list [, comp])</code></a></h3> 9996 1.2 lneto 9997 1.1 mbalmer 9998 1.1 mbalmer <p> 9999 1.9 nikita Sorts the list elements in a given order, <em>in-place</em>, 10000 1.2 lneto from <code>list[1]</code> to <code>list[#list]</code>. 10001 1.1 mbalmer If <code>comp</code> is given, 10002 1.2 lneto then it must be a function that receives two list elements 10003 1.2 lneto and returns true when the first element must come 10004 1.9 nikita before the second in the final order, 10005 1.9 nikita so that, after the sort, 10006 1.9 nikita <code>i <= j</code> implies <code>not comp(list[j],list[i])</code>. 10007 1.1 mbalmer If <code>comp</code> is not given, 10008 1.1 mbalmer then the standard Lua operator <code><</code> is used instead. 10009 1.1 mbalmer 10010 1.1 mbalmer 10011 1.1 mbalmer <p> 10012 1.9 nikita The <code>comp</code> function must define a consistent order; 10013 1.9 nikita more formally, the function must define a strict weak order. 10014 1.9 nikita (A weak order is similar to a total order, 10015 1.9 nikita but it can equate different elements for comparison purposes.) 10016 1.5 lneto 10017 1.5 lneto 10018 1.5 lneto <p> 10019 1.7 mbalmer The sort algorithm is not stable: 10020 1.9 nikita Different elements considered equal by the given order 10021 1.1 mbalmer may have their relative positions changed by the sort. 10022 1.1 mbalmer 10023 1.1 mbalmer 10024 1.1 mbalmer 10025 1.1 mbalmer 10026 1.2 lneto <p> 10027 1.2 lneto <hr><h3><a name="pdf-table.unpack"><code>table.unpack (list [, i [, j]])</code></a></h3> 10028 1.2 lneto 10029 1.2 lneto 10030 1.2 lneto <p> 10031 1.2 lneto Returns the elements from the given list. 10032 1.2 lneto This function is equivalent to 10033 1.2 lneto 10034 1.2 lneto <pre> 10035 1.2 lneto return list[i], list[i+1], ···, list[j] 10036 1.2 lneto </pre><p> 10037 1.2 lneto By default, <code>i</code> is 1 and <code>j</code> is <code>#list</code>. 10038 1.2 lneto 10039 1.2 lneto 10040 1.2 lneto 10041 1.1 mbalmer 10042 1.1 mbalmer 10043 1.1 mbalmer 10044 1.2 lneto 10045 1.2 lneto <h2>6.7 – <a name="6.7">Mathematical Functions</a></h2> 10046 1.1 mbalmer 10047 1.1 mbalmer <p> 10048 1.2 lneto This library provides basic mathematical functions. 10049 1.2 lneto It provides all its functions and constants inside the table <a name="pdf-math"><code>math</code></a>. 10050 1.2 lneto Functions with the annotation "<code>integer/float</code>" give 10051 1.2 lneto integer results for integer arguments 10052 1.9 nikita and float results for non-integer arguments. 10053 1.9 nikita The rounding functions 10054 1.9 nikita <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> 10055 1.2 lneto return an integer when the result fits in the range of an integer, 10056 1.3 lneto or a float otherwise. 10057 1.1 mbalmer 10058 1.1 mbalmer 10059 1.1 mbalmer <p> 10060 1.1 mbalmer <hr><h3><a name="pdf-math.abs"><code>math.abs (x)</code></a></h3> 10061 1.1 mbalmer 10062 1.1 mbalmer 10063 1.1 mbalmer <p> 10064 1.9 nikita Returns the maximum value between <code>x</code> and <code>-x</code>. (integer/float) 10065 1.1 mbalmer 10066 1.1 mbalmer 10067 1.1 mbalmer 10068 1.1 mbalmer 10069 1.1 mbalmer <p> 10070 1.1 mbalmer <hr><h3><a name="pdf-math.acos"><code>math.acos (x)</code></a></h3> 10071 1.1 mbalmer 10072 1.1 mbalmer 10073 1.1 mbalmer <p> 10074 1.1 mbalmer Returns the arc cosine of <code>x</code> (in radians). 10075 1.1 mbalmer 10076 1.1 mbalmer 10077 1.1 mbalmer 10078 1.1 mbalmer 10079 1.1 mbalmer <p> 10080 1.1 mbalmer <hr><h3><a name="pdf-math.asin"><code>math.asin (x)</code></a></h3> 10081 1.1 mbalmer 10082 1.1 mbalmer 10083 1.1 mbalmer <p> 10084 1.1 mbalmer Returns the arc sine of <code>x</code> (in radians). 10085 1.1 mbalmer 10086 1.1 mbalmer 10087 1.1 mbalmer 10088 1.1 mbalmer 10089 1.1 mbalmer <p> 10090 1.2 lneto <hr><h3><a name="pdf-math.atan"><code>math.atan (y [, x])</code></a></h3> 10091 1.1 mbalmer 10092 1.1 mbalmer 10093 1.1 mbalmer <p> 10094 1.1 mbalmer 10095 1.1 mbalmer Returns the arc tangent of <code>y/x</code> (in radians), 10096 1.8 alnsn but uses the signs of both arguments to find the 10097 1.1 mbalmer quadrant of the result. 10098 1.9 nikita It also handles correctly the case of <code>x</code> being zero. 10099 1.1 mbalmer 10100 1.1 mbalmer 10101 1.2 lneto <p> 10102 1.2 lneto The default value for <code>x</code> is 1, 10103 1.2 lneto so that the call <code>math.atan(y)</code> 10104 1.2 lneto returns the arc tangent of <code>y</code>. 10105 1.2 lneto 10106 1.2 lneto 10107 1.1 mbalmer 10108 1.1 mbalmer 10109 1.1 mbalmer <p> 10110 1.1 mbalmer <hr><h3><a name="pdf-math.ceil"><code>math.ceil (x)</code></a></h3> 10111 1.1 mbalmer 10112 1.1 mbalmer 10113 1.1 mbalmer <p> 10114 1.9 nikita Returns the smallest integral value greater than or equal to <code>x</code>. 10115 1.1 mbalmer 10116 1.1 mbalmer 10117 1.1 mbalmer 10118 1.1 mbalmer 10119 1.1 mbalmer <p> 10120 1.1 mbalmer <hr><h3><a name="pdf-math.cos"><code>math.cos (x)</code></a></h3> 10121 1.1 mbalmer 10122 1.1 mbalmer 10123 1.1 mbalmer <p> 10124 1.1 mbalmer Returns the cosine of <code>x</code> (assumed to be in radians). 10125 1.1 mbalmer 10126 1.1 mbalmer 10127 1.1 mbalmer 10128 1.1 mbalmer 10129 1.1 mbalmer <p> 10130 1.1 mbalmer <hr><h3><a name="pdf-math.deg"><code>math.deg (x)</code></a></h3> 10131 1.1 mbalmer 10132 1.1 mbalmer 10133 1.1 mbalmer <p> 10134 1.2 lneto Converts the angle <code>x</code> from radians to degrees. 10135 1.1 mbalmer 10136 1.1 mbalmer 10137 1.1 mbalmer 10138 1.1 mbalmer 10139 1.1 mbalmer <p> 10140 1.3 lneto <hr><h3><a name="pdf-math.exp"><code>math.exp (x)</code></a></h3> 10141 1.3 lneto 10142 1.3 lneto 10143 1.3 lneto <p> 10144 1.3 lneto Returns the value <em>e<sup>x</sup></em> 10145 1.3 lneto (where <code>e</code> is the base of natural logarithms). 10146 1.3 lneto 10147 1.3 lneto 10148 1.3 lneto 10149 1.3 lneto 10150 1.3 lneto <p> 10151 1.1 mbalmer <hr><h3><a name="pdf-math.floor"><code>math.floor (x)</code></a></h3> 10152 1.1 mbalmer 10153 1.1 mbalmer 10154 1.1 mbalmer <p> 10155 1.9 nikita Returns the largest integral value less than or equal to <code>x</code>. 10156 1.1 mbalmer 10157 1.1 mbalmer 10158 1.1 mbalmer 10159 1.1 mbalmer 10160 1.1 mbalmer <p> 10161 1.1 mbalmer <hr><h3><a name="pdf-math.fmod"><code>math.fmod (x, y)</code></a></h3> 10162 1.1 mbalmer 10163 1.1 mbalmer 10164 1.1 mbalmer <p> 10165 1.1 mbalmer Returns the remainder of the division of <code>x</code> by <code>y</code> 10166 1.2 lneto that rounds the quotient towards zero. (integer/float) 10167 1.1 mbalmer 10168 1.1 mbalmer 10169 1.1 mbalmer 10170 1.1 mbalmer 10171 1.1 mbalmer <p> 10172 1.2 lneto <hr><h3><a name="pdf-math.huge"><code>math.huge</code></a></h3> 10173 1.1 mbalmer 10174 1.1 mbalmer 10175 1.1 mbalmer <p> 10176 1.2 lneto The float value <code>HUGE_VAL</code>, 10177 1.9 nikita a value greater than any other numeric value. 10178 1.1 mbalmer 10179 1.1 mbalmer 10180 1.1 mbalmer 10181 1.1 mbalmer 10182 1.1 mbalmer <p> 10183 1.2 lneto <hr><h3><a name="pdf-math.log"><code>math.log (x [, base])</code></a></h3> 10184 1.1 mbalmer 10185 1.1 mbalmer 10186 1.1 mbalmer <p> 10187 1.2 lneto Returns the logarithm of <code>x</code> in the given base. 10188 1.2 lneto The default for <code>base</code> is <em>e</em> 10189 1.2 lneto (so that the function returns the natural logarithm of <code>x</code>). 10190 1.1 mbalmer 10191 1.1 mbalmer 10192 1.1 mbalmer 10193 1.1 mbalmer 10194 1.1 mbalmer <p> 10195 1.2 lneto <hr><h3><a name="pdf-math.max"><code>math.max (x, ···)</code></a></h3> 10196 1.1 mbalmer 10197 1.1 mbalmer 10198 1.1 mbalmer <p> 10199 1.2 lneto Returns the argument with the maximum value, 10200 1.9 nikita according to the Lua operator <code><</code>. 10201 1.1 mbalmer 10202 1.1 mbalmer 10203 1.1 mbalmer 10204 1.1 mbalmer 10205 1.1 mbalmer <p> 10206 1.2 lneto <hr><h3><a name="pdf-math.maxinteger"><code>math.maxinteger</code></a></h3> 10207 1.2 lneto An integer with the maximum value for an integer. 10208 1.1 mbalmer 10209 1.1 mbalmer 10210 1.1 mbalmer 10211 1.1 mbalmer 10212 1.1 mbalmer <p> 10213 1.2 lneto <hr><h3><a name="pdf-math.min"><code>math.min (x, ···)</code></a></h3> 10214 1.1 mbalmer 10215 1.1 mbalmer 10216 1.1 mbalmer <p> 10217 1.2 lneto Returns the argument with the minimum value, 10218 1.9 nikita according to the Lua operator <code><</code>. 10219 1.1 mbalmer 10220 1.1 mbalmer 10221 1.1 mbalmer 10222 1.1 mbalmer 10223 1.1 mbalmer <p> 10224 1.2 lneto <hr><h3><a name="pdf-math.mininteger"><code>math.mininteger</code></a></h3> 10225 1.2 lneto An integer with the minimum value for an integer. 10226 1.1 mbalmer 10227 1.1 mbalmer 10228 1.1 mbalmer 10229 1.1 mbalmer 10230 1.1 mbalmer <p> 10231 1.1 mbalmer <hr><h3><a name="pdf-math.modf"><code>math.modf (x)</code></a></h3> 10232 1.1 mbalmer 10233 1.1 mbalmer 10234 1.1 mbalmer <p> 10235 1.2 lneto Returns the integral part of <code>x</code> and the fractional part of <code>x</code>. 10236 1.2 lneto Its second result is always a float. 10237 1.1 mbalmer 10238 1.1 mbalmer 10239 1.1 mbalmer 10240 1.1 mbalmer 10241 1.1 mbalmer <p> 10242 1.1 mbalmer <hr><h3><a name="pdf-math.pi"><code>math.pi</code></a></h3> 10243 1.1 mbalmer 10244 1.1 mbalmer 10245 1.1 mbalmer <p> 10246 1.2 lneto The value of <em>π</em>. 10247 1.1 mbalmer 10248 1.1 mbalmer 10249 1.1 mbalmer 10250 1.1 mbalmer 10251 1.1 mbalmer <p> 10252 1.1 mbalmer <hr><h3><a name="pdf-math.rad"><code>math.rad (x)</code></a></h3> 10253 1.1 mbalmer 10254 1.1 mbalmer 10255 1.1 mbalmer <p> 10256 1.2 lneto Converts the angle <code>x</code> from degrees to radians. 10257 1.1 mbalmer 10258 1.1 mbalmer 10259 1.1 mbalmer 10260 1.1 mbalmer 10261 1.1 mbalmer <p> 10262 1.1 mbalmer <hr><h3><a name="pdf-math.random"><code>math.random ([m [, n]])</code></a></h3> 10263 1.1 mbalmer 10264 1.1 mbalmer 10265 1.1 mbalmer <p> 10266 1.2 lneto When called without arguments, 10267 1.2 lneto returns a pseudo-random float with uniform distribution 10268 1.2 lneto in the range <em>[0,1)</em>. 10269 1.2 lneto When called with two integers <code>m</code> and <code>n</code>, 10270 1.2 lneto <code>math.random</code> returns a pseudo-random integer 10271 1.2 lneto with uniform distribution in the range <em>[m, n]</em>. 10272 1.9 nikita The call <code>math.random(n)</code>, for a positive <code>n</code>, 10273 1.9 nikita is equivalent to <code>math.random(1,n)</code>. 10274 1.9 nikita The call <code>math.random(0)</code> produces an integer with 10275 1.9 nikita all bits (pseudo)random. 10276 1.9 nikita 10277 1.9 nikita 10278 1.9 nikita <p> 10279 1.9 nikita This function uses the <code>xoshiro256**</code> algorithm to produce 10280 1.9 nikita pseudo-random 64-bit integers, 10281 1.9 nikita which are the results of calls with argument 0. 10282 1.9 nikita Other results (ranges and floats) 10283 1.9 nikita are unbiased extracted from these integers. 10284 1.1 mbalmer 10285 1.1 mbalmer 10286 1.1 mbalmer <p> 10287 1.9 nikita Lua initializes its pseudo-random generator with the equivalent of 10288 1.9 nikita a call to <a href="#pdf-math.randomseed"><code>math.randomseed</code></a> with no arguments, 10289 1.9 nikita so that <code>math.random</code> should generate 10290 1.9 nikita different sequences of results each time the program runs. 10291 1.1 mbalmer 10292 1.1 mbalmer 10293 1.1 mbalmer 10294 1.1 mbalmer 10295 1.1 mbalmer <p> 10296 1.9 nikita <hr><h3><a name="pdf-math.randomseed"><code>math.randomseed ([x [, y]])</code></a></h3> 10297 1.1 mbalmer 10298 1.1 mbalmer 10299 1.1 mbalmer <p> 10300 1.9 nikita When called with at least one argument, 10301 1.9 nikita the integer parameters <code>x</code> and <code>y</code> are 10302 1.9 nikita joined into a 128-bit <em>seed</em> that 10303 1.9 nikita is used to reinitialize the pseudo-random generator; 10304 1.1 mbalmer equal seeds produce equal sequences of numbers. 10305 1.9 nikita The default for <code>y</code> is zero. 10306 1.9 nikita 10307 1.9 nikita 10308 1.9 nikita <p> 10309 1.9 nikita When called with no arguments, 10310 1.9 nikita Lua generates a seed with 10311 1.9 nikita a weak attempt for randomness. 10312 1.9 nikita 10313 1.9 nikita 10314 1.9 nikita <p> 10315 1.9 nikita This function returns the two seed components 10316 1.9 nikita that were effectively used, 10317 1.9 nikita so that setting them again repeats the sequence. 10318 1.9 nikita 10319 1.9 nikita 10320 1.9 nikita <p> 10321 1.9 nikita To ensure a required level of randomness to the initial state 10322 1.9 nikita (or contrarily, to have a deterministic sequence, 10323 1.9 nikita for instance when debugging a program), 10324 1.9 nikita you should call <a href="#pdf-math.randomseed"><code>math.randomseed</code></a> with explicit arguments. 10325 1.1 mbalmer 10326 1.1 mbalmer 10327 1.1 mbalmer 10328 1.1 mbalmer 10329 1.1 mbalmer <p> 10330 1.1 mbalmer <hr><h3><a name="pdf-math.sin"><code>math.sin (x)</code></a></h3> 10331 1.1 mbalmer 10332 1.1 mbalmer 10333 1.1 mbalmer <p> 10334 1.1 mbalmer Returns the sine of <code>x</code> (assumed to be in radians). 10335 1.1 mbalmer 10336 1.1 mbalmer 10337 1.1 mbalmer 10338 1.1 mbalmer 10339 1.1 mbalmer <p> 10340 1.1 mbalmer <hr><h3><a name="pdf-math.sqrt"><code>math.sqrt (x)</code></a></h3> 10341 1.1 mbalmer 10342 1.1 mbalmer 10343 1.1 mbalmer <p> 10344 1.1 mbalmer Returns the square root of <code>x</code>. 10345 1.1 mbalmer (You can also use the expression <code>x^0.5</code> to compute this value.) 10346 1.1 mbalmer 10347 1.1 mbalmer 10348 1.1 mbalmer 10349 1.1 mbalmer 10350 1.1 mbalmer <p> 10351 1.1 mbalmer <hr><h3><a name="pdf-math.tan"><code>math.tan (x)</code></a></h3> 10352 1.1 mbalmer 10353 1.1 mbalmer 10354 1.1 mbalmer <p> 10355 1.1 mbalmer Returns the tangent of <code>x</code> (assumed to be in radians). 10356 1.1 mbalmer 10357 1.1 mbalmer 10358 1.1 mbalmer 10359 1.1 mbalmer 10360 1.1 mbalmer <p> 10361 1.3 lneto <hr><h3><a name="pdf-math.tointeger"><code>math.tointeger (x)</code></a></h3> 10362 1.3 lneto 10363 1.3 lneto 10364 1.3 lneto <p> 10365 1.3 lneto If the value <code>x</code> is convertible to an integer, 10366 1.3 lneto returns that integer. 10367 1.9 nikita Otherwise, returns <b>fail</b>. 10368 1.3 lneto 10369 1.3 lneto 10370 1.3 lneto 10371 1.3 lneto 10372 1.3 lneto <p> 10373 1.2 lneto <hr><h3><a name="pdf-math.type"><code>math.type (x)</code></a></h3> 10374 1.1 mbalmer 10375 1.1 mbalmer 10376 1.1 mbalmer <p> 10377 1.2 lneto Returns "<code>integer</code>" if <code>x</code> is an integer, 10378 1.2 lneto "<code>float</code>" if it is a float, 10379 1.9 nikita or <b>fail</b> if <code>x</code> is not a number. 10380 1.1 mbalmer 10381 1.1 mbalmer 10382 1.1 mbalmer 10383 1.1 mbalmer 10384 1.3 lneto <p> 10385 1.3 lneto <hr><h3><a name="pdf-math.ult"><code>math.ult (m, n)</code></a></h3> 10386 1.3 lneto 10387 1.3 lneto 10388 1.3 lneto <p> 10389 1.3 lneto Returns a boolean, 10390 1.9 nikita <b>true</b> if and only if integer <code>m</code> is below integer <code>n</code> when 10391 1.3 lneto they are compared as unsigned integers. 10392 1.3 lneto 10393 1.3 lneto 10394 1.3 lneto 10395 1.3 lneto 10396 1.1 mbalmer 10397 1.1 mbalmer 10398 1.1 mbalmer 10399 1.2 lneto <h2>6.8 – <a name="6.8">Input and Output Facilities</a></h2> 10400 1.1 mbalmer 10401 1.1 mbalmer <p> 10402 1.1 mbalmer The I/O library provides two different styles for file manipulation. 10403 1.2 lneto The first one uses implicit file handles; 10404 1.1 mbalmer that is, there are operations to set a default input file and a 10405 1.1 mbalmer default output file, 10406 1.9 nikita and all input/output operations are done over these default files. 10407 1.2 lneto The second style uses explicit file handles. 10408 1.1 mbalmer 10409 1.1 mbalmer 10410 1.1 mbalmer <p> 10411 1.2 lneto When using implicit file handles, 10412 1.1 mbalmer all operations are supplied by table <a name="pdf-io"><code>io</code></a>. 10413 1.2 lneto When using explicit file handles, 10414 1.2 lneto the operation <a href="#pdf-io.open"><code>io.open</code></a> returns a file handle 10415 1.2 lneto and then all operations are supplied as methods of the file handle. 10416 1.1 mbalmer 10417 1.1 mbalmer 10418 1.1 mbalmer <p> 10419 1.9 nikita The metatable for file handles provides metamethods 10420 1.9 nikita for <code>__gc</code> and <code>__close</code> that try 10421 1.9 nikita to close the file when called. 10422 1.9 nikita 10423 1.9 nikita 10424 1.9 nikita <p> 10425 1.1 mbalmer The table <code>io</code> also provides 10426 1.2 lneto three predefined file handles with their usual meanings from C: 10427 1.1 mbalmer <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>. 10428 1.1 mbalmer The I/O library never closes these files. 10429 1.1 mbalmer 10430 1.1 mbalmer 10431 1.1 mbalmer <p> 10432 1.1 mbalmer Unless otherwise stated, 10433 1.9 nikita all I/O functions return <b>fail</b> on failure, 10434 1.9 nikita plus an error message as a second result and 10435 1.9 nikita a system-dependent error code as a third result, 10436 1.9 nikita and some non-false value on success. 10437 1.9 nikita On non-POSIX systems, 10438 1.2 lneto the computation of the error message and error code 10439 1.2 lneto in case of errors 10440 1.2 lneto may be not thread safe, 10441 1.2 lneto because they rely on the global C variable <code>errno</code>. 10442 1.1 mbalmer 10443 1.1 mbalmer 10444 1.1 mbalmer <p> 10445 1.1 mbalmer <hr><h3><a name="pdf-io.close"><code>io.close ([file])</code></a></h3> 10446 1.1 mbalmer 10447 1.1 mbalmer 10448 1.1 mbalmer <p> 10449 1.1 mbalmer Equivalent to <code>file:close()</code>. 10450 1.1 mbalmer Without a <code>file</code>, closes the default output file. 10451 1.1 mbalmer 10452 1.1 mbalmer 10453 1.1 mbalmer 10454 1.1 mbalmer 10455 1.1 mbalmer <p> 10456 1.1 mbalmer <hr><h3><a name="pdf-io.flush"><code>io.flush ()</code></a></h3> 10457 1.1 mbalmer 10458 1.1 mbalmer 10459 1.1 mbalmer <p> 10460 1.2 lneto Equivalent to <code>io.output():flush()</code>. 10461 1.1 mbalmer 10462 1.1 mbalmer 10463 1.1 mbalmer 10464 1.1 mbalmer 10465 1.1 mbalmer <p> 10466 1.1 mbalmer <hr><h3><a name="pdf-io.input"><code>io.input ([file])</code></a></h3> 10467 1.1 mbalmer 10468 1.1 mbalmer 10469 1.1 mbalmer <p> 10470 1.1 mbalmer When called with a file name, it opens the named file (in text mode), 10471 1.1 mbalmer and sets its handle as the default input file. 10472 1.1 mbalmer When called with a file handle, 10473 1.1 mbalmer it simply sets this file handle as the default input file. 10474 1.8 alnsn When called without arguments, 10475 1.1 mbalmer it returns the current default input file. 10476 1.1 mbalmer 10477 1.1 mbalmer 10478 1.1 mbalmer <p> 10479 1.1 mbalmer In case of errors this function raises the error, 10480 1.1 mbalmer instead of returning an error code. 10481 1.1 mbalmer 10482 1.1 mbalmer 10483 1.1 mbalmer 10484 1.1 mbalmer 10485 1.1 mbalmer <p> 10486 1.5 lneto <hr><h3><a name="pdf-io.lines"><code>io.lines ([filename, ···])</code></a></h3> 10487 1.1 mbalmer 10488 1.1 mbalmer 10489 1.1 mbalmer <p> 10490 1.1 mbalmer Opens the given file name in read mode 10491 1.2 lneto and returns an iterator function that 10492 1.2 lneto works like <code>file:lines(···)</code> over the opened file. 10493 1.9 nikita When the iterator function fails to read any value, 10494 1.9 nikita it automatically closes the file. 10495 1.9 nikita Besides the iterator function, 10496 1.9 nikita <code>io.lines</code> returns three other values: 10497 1.9 nikita two <b>nil</b> values as placeholders, 10498 1.9 nikita plus the created file handle. 10499 1.9 nikita Therefore, when used in a generic <b>for</b> loop, 10500 1.9 nikita the file is closed also if the loop is interrupted by an 10501 1.9 nikita error or a <b>break</b>. 10502 1.1 mbalmer 10503 1.1 mbalmer 10504 1.1 mbalmer <p> 10505 1.1 mbalmer The call <code>io.lines()</code> (with no file name) is equivalent 10506 1.9 nikita to <code>io.input():lines("l")</code>; 10507 1.1 mbalmer that is, it iterates over the lines of the default input file. 10508 1.8 alnsn In this case, the iterator does not close the file when the loop ends. 10509 1.1 mbalmer 10510 1.1 mbalmer 10511 1.2 lneto <p> 10512 1.9 nikita In case of errors opening the file, 10513 1.9 nikita this function raises the error, 10514 1.2 lneto instead of returning an error code. 10515 1.2 lneto 10516 1.2 lneto 10517 1.1 mbalmer 10518 1.1 mbalmer 10519 1.1 mbalmer <p> 10520 1.1 mbalmer <hr><h3><a name="pdf-io.open"><code>io.open (filename [, mode])</code></a></h3> 10521 1.1 mbalmer 10522 1.1 mbalmer 10523 1.1 mbalmer <p> 10524 1.1 mbalmer This function opens a file, 10525 1.1 mbalmer in the mode specified in the string <code>mode</code>. 10526 1.6 salazar In case of success, 10527 1.6 salazar it returns a new file handle. 10528 1.1 mbalmer 10529 1.1 mbalmer 10530 1.1 mbalmer <p> 10531 1.1 mbalmer The <code>mode</code> string can be any of the following: 10532 1.1 mbalmer 10533 1.1 mbalmer <ul> 10534 1.2 lneto <li><b>"<code>r</code>": </b> read mode (the default);</li> 10535 1.2 lneto <li><b>"<code>w</code>": </b> write mode;</li> 10536 1.2 lneto <li><b>"<code>a</code>": </b> append mode;</li> 10537 1.2 lneto <li><b>"<code>r+</code>": </b> update mode, all previous data is preserved;</li> 10538 1.2 lneto <li><b>"<code>w+</code>": </b> update mode, all previous data is erased;</li> 10539 1.2 lneto <li><b>"<code>a+</code>": </b> append update mode, previous data is preserved, 10540 1.1 mbalmer writing is only allowed at the end of file.</li> 10541 1.1 mbalmer </ul><p> 10542 1.1 mbalmer The <code>mode</code> string can also have a '<code>b</code>' at the end, 10543 1.1 mbalmer which is needed in some systems to open the file in binary mode. 10544 1.1 mbalmer 10545 1.1 mbalmer 10546 1.1 mbalmer 10547 1.1 mbalmer 10548 1.1 mbalmer <p> 10549 1.1 mbalmer <hr><h3><a name="pdf-io.output"><code>io.output ([file])</code></a></h3> 10550 1.1 mbalmer 10551 1.1 mbalmer 10552 1.1 mbalmer <p> 10553 1.1 mbalmer Similar to <a href="#pdf-io.input"><code>io.input</code></a>, but operates over the default output file. 10554 1.1 mbalmer 10555 1.1 mbalmer 10556 1.1 mbalmer 10557 1.1 mbalmer 10558 1.1 mbalmer <p> 10559 1.1 mbalmer <hr><h3><a name="pdf-io.popen"><code>io.popen (prog [, mode])</code></a></h3> 10560 1.1 mbalmer 10561 1.1 mbalmer 10562 1.1 mbalmer <p> 10563 1.2 lneto This function is system dependent and is not available 10564 1.2 lneto on all platforms. 10565 1.2 lneto 10566 1.2 lneto 10567 1.2 lneto <p> 10568 1.9 nikita Starts the program <code>prog</code> in a separated process and returns 10569 1.1 mbalmer a file handle that you can use to read data from this program 10570 1.1 mbalmer (if <code>mode</code> is <code>"r"</code>, the default) 10571 1.1 mbalmer or to write data to this program 10572 1.1 mbalmer (if <code>mode</code> is <code>"w"</code>). 10573 1.1 mbalmer 10574 1.1 mbalmer 10575 1.1 mbalmer 10576 1.1 mbalmer 10577 1.1 mbalmer <p> 10578 1.1 mbalmer <hr><h3><a name="pdf-io.read"><code>io.read (···)</code></a></h3> 10579 1.1 mbalmer 10580 1.1 mbalmer 10581 1.1 mbalmer <p> 10582 1.2 lneto Equivalent to <code>io.input():read(···)</code>. 10583 1.1 mbalmer 10584 1.1 mbalmer 10585 1.1 mbalmer 10586 1.1 mbalmer 10587 1.1 mbalmer <p> 10588 1.1 mbalmer <hr><h3><a name="pdf-io.tmpfile"><code>io.tmpfile ()</code></a></h3> 10589 1.1 mbalmer 10590 1.1 mbalmer 10591 1.1 mbalmer <p> 10592 1.6 salazar In case of success, 10593 1.6 salazar returns a handle for a temporary file. 10594 1.1 mbalmer This file is opened in update mode 10595 1.1 mbalmer and it is automatically removed when the program ends. 10596 1.1 mbalmer 10597 1.1 mbalmer 10598 1.1 mbalmer 10599 1.1 mbalmer 10600 1.1 mbalmer <p> 10601 1.1 mbalmer <hr><h3><a name="pdf-io.type"><code>io.type (obj)</code></a></h3> 10602 1.1 mbalmer 10603 1.1 mbalmer 10604 1.1 mbalmer <p> 10605 1.1 mbalmer Checks whether <code>obj</code> is a valid file handle. 10606 1.1 mbalmer Returns the string <code>"file"</code> if <code>obj</code> is an open file handle, 10607 1.1 mbalmer <code>"closed file"</code> if <code>obj</code> is a closed file handle, 10608 1.9 nikita or <b>fail</b> if <code>obj</code> is not a file handle. 10609 1.1 mbalmer 10610 1.1 mbalmer 10611 1.1 mbalmer 10612 1.1 mbalmer 10613 1.1 mbalmer <p> 10614 1.1 mbalmer <hr><h3><a name="pdf-io.write"><code>io.write (···)</code></a></h3> 10615 1.1 mbalmer 10616 1.1 mbalmer 10617 1.1 mbalmer <p> 10618 1.2 lneto Equivalent to <code>io.output():write(···)</code>. 10619 1.1 mbalmer 10620 1.1 mbalmer 10621 1.1 mbalmer 10622 1.1 mbalmer 10623 1.1 mbalmer <p> 10624 1.1 mbalmer <hr><h3><a name="pdf-file:close"><code>file:close ()</code></a></h3> 10625 1.1 mbalmer 10626 1.1 mbalmer 10627 1.1 mbalmer <p> 10628 1.1 mbalmer Closes <code>file</code>. 10629 1.1 mbalmer Note that files are automatically closed when 10630 1.1 mbalmer their handles are garbage collected, 10631 1.1 mbalmer but that takes an unpredictable amount of time to happen. 10632 1.1 mbalmer 10633 1.1 mbalmer 10634 1.2 lneto <p> 10635 1.2 lneto When closing a file handle created with <a href="#pdf-io.popen"><code>io.popen</code></a>, 10636 1.2 lneto <a href="#pdf-file:close"><code>file:close</code></a> returns the same values 10637 1.2 lneto returned by <a href="#pdf-os.execute"><code>os.execute</code></a>. 10638 1.2 lneto 10639 1.2 lneto 10640 1.1 mbalmer 10641 1.1 mbalmer 10642 1.1 mbalmer <p> 10643 1.1 mbalmer <hr><h3><a name="pdf-file:flush"><code>file:flush ()</code></a></h3> 10644 1.1 mbalmer 10645 1.1 mbalmer 10646 1.1 mbalmer <p> 10647 1.1 mbalmer Saves any written data to <code>file</code>. 10648 1.1 mbalmer 10649 1.1 mbalmer 10650 1.1 mbalmer 10651 1.1 mbalmer 10652 1.1 mbalmer <p> 10653 1.2 lneto <hr><h3><a name="pdf-file:lines"><code>file:lines (···)</code></a></h3> 10654 1.1 mbalmer 10655 1.1 mbalmer 10656 1.1 mbalmer <p> 10657 1.1 mbalmer Returns an iterator function that, 10658 1.1 mbalmer each time it is called, 10659 1.2 lneto reads the file according to the given formats. 10660 1.2 lneto When no format is given, 10661 1.2 lneto uses "<code>l</code>" as a default. 10662 1.2 lneto As an example, the construction 10663 1.1 mbalmer 10664 1.1 mbalmer <pre> 10665 1.2 lneto for c in file:lines(1) do <em>body</em> end 10666 1.2 lneto </pre><p> 10667 1.2 lneto will iterate over all characters of the file, 10668 1.2 lneto starting at the current position. 10669 1.2 lneto Unlike <a href="#pdf-io.lines"><code>io.lines</code></a>, this function does not close the file 10670 1.2 lneto when the loop ends. 10671 1.2 lneto 10672 1.2 lneto 10673 1.1 mbalmer 10674 1.1 mbalmer 10675 1.1 mbalmer <p> 10676 1.1 mbalmer <hr><h3><a name="pdf-file:read"><code>file:read (···)</code></a></h3> 10677 1.1 mbalmer 10678 1.1 mbalmer 10679 1.1 mbalmer <p> 10680 1.1 mbalmer Reads the file <code>file</code>, 10681 1.1 mbalmer according to the given formats, which specify what to read. 10682 1.1 mbalmer For each format, 10683 1.2 lneto the function returns a string or a number with the characters read, 10684 1.9 nikita or <b>fail</b> if it cannot read data with the specified format. 10685 1.3 lneto (In this latter case, 10686 1.3 lneto the function does not read subsequent formats.) 10687 1.9 nikita When called without arguments, 10688 1.2 lneto it uses a default format that reads the next line 10689 1.1 mbalmer (see below). 10690 1.1 mbalmer 10691 1.1 mbalmer 10692 1.1 mbalmer <p> 10693 1.1 mbalmer The available formats are 10694 1.1 mbalmer 10695 1.1 mbalmer <ul> 10696 1.1 mbalmer 10697 1.2 lneto <li><b>"<code>n</code>": </b> 10698 1.2 lneto reads a numeral and returns it as a float or an integer, 10699 1.2 lneto following the lexical conventions of Lua. 10700 1.9 nikita (The numeral may have leading whitespaces and a sign.) 10701 1.2 lneto This format always reads the longest input sequence that 10702 1.4 mbalmer is a valid prefix for a numeral; 10703 1.4 mbalmer if that prefix does not form a valid numeral 10704 1.9 nikita (e.g., an empty string, "<code>0x</code>", or "<code>3.4e-</code>") 10705 1.9 nikita or it is too long (more than 200 characters), 10706 1.9 nikita it is discarded and the format returns <b>fail</b>. 10707 1.2 lneto </li> 10708 1.2 lneto 10709 1.2 lneto <li><b>"<code>a</code>": </b> 10710 1.1 mbalmer reads the whole file, starting at the current position. 10711 1.9 nikita On end of file, it returns the empty string; 10712 1.9 nikita this format never fails. 10713 1.1 mbalmer </li> 10714 1.1 mbalmer 10715 1.2 lneto <li><b>"<code>l</code>": </b> 10716 1.2 lneto reads the next line skipping the end of line, 10717 1.9 nikita returning <b>fail</b> on end of file. 10718 1.1 mbalmer This is the default format. 10719 1.1 mbalmer </li> 10720 1.1 mbalmer 10721 1.2 lneto <li><b>"<code>L</code>": </b> 10722 1.2 lneto reads the next line keeping the end-of-line character (if present), 10723 1.9 nikita returning <b>fail</b> on end of file. 10724 1.2 lneto </li> 10725 1.2 lneto 10726 1.2 lneto <li><b><em>number</em>: </b> 10727 1.2 lneto reads a string with up to this number of bytes, 10728 1.9 nikita returning <b>fail</b> on end of file. 10729 1.2 lneto If <code>number</code> is zero, 10730 1.1 mbalmer it reads nothing and returns an empty string, 10731 1.9 nikita or <b>fail</b> on end of file. 10732 1.1 mbalmer </li> 10733 1.1 mbalmer 10734 1.2 lneto </ul><p> 10735 1.2 lneto The formats "<code>l</code>" and "<code>L</code>" should be used only for text files. 10736 1.2 lneto 10737 1.1 mbalmer 10738 1.1 mbalmer 10739 1.1 mbalmer 10740 1.1 mbalmer <p> 10741 1.2 lneto <hr><h3><a name="pdf-file:seek"><code>file:seek ([whence [, offset]])</code></a></h3> 10742 1.1 mbalmer 10743 1.1 mbalmer 10744 1.1 mbalmer <p> 10745 1.1 mbalmer Sets and gets the file position, 10746 1.1 mbalmer measured from the beginning of the file, 10747 1.1 mbalmer to the position given by <code>offset</code> plus a base 10748 1.1 mbalmer specified by the string <code>whence</code>, as follows: 10749 1.1 mbalmer 10750 1.1 mbalmer <ul> 10751 1.2 lneto <li><b>"<code>set</code>": </b> base is position 0 (beginning of the file);</li> 10752 1.2 lneto <li><b>"<code>cur</code>": </b> base is current position;</li> 10753 1.2 lneto <li><b>"<code>end</code>": </b> base is end of file;</li> 10754 1.1 mbalmer </ul><p> 10755 1.2 lneto In case of success, <code>seek</code> returns the final file position, 10756 1.1 mbalmer measured in bytes from the beginning of the file. 10757 1.9 nikita If <code>seek</code> fails, it returns <b>fail</b>, 10758 1.1 mbalmer plus a string describing the error. 10759 1.1 mbalmer 10760 1.1 mbalmer 10761 1.1 mbalmer <p> 10762 1.1 mbalmer The default value for <code>whence</code> is <code>"cur"</code>, 10763 1.1 mbalmer and for <code>offset</code> is 0. 10764 1.1 mbalmer Therefore, the call <code>file:seek()</code> returns the current 10765 1.1 mbalmer file position, without changing it; 10766 1.1 mbalmer the call <code>file:seek("set")</code> sets the position to the 10767 1.1 mbalmer beginning of the file (and returns 0); 10768 1.1 mbalmer and the call <code>file:seek("end")</code> sets the position to the 10769 1.1 mbalmer end of the file, and returns its size. 10770 1.1 mbalmer 10771 1.1 mbalmer 10772 1.1 mbalmer 10773 1.1 mbalmer 10774 1.1 mbalmer <p> 10775 1.1 mbalmer <hr><h3><a name="pdf-file:setvbuf"><code>file:setvbuf (mode [, size])</code></a></h3> 10776 1.1 mbalmer 10777 1.1 mbalmer 10778 1.1 mbalmer <p> 10779 1.9 nikita Sets the buffering mode for a file. 10780 1.1 mbalmer There are three available modes: 10781 1.1 mbalmer 10782 1.1 mbalmer <ul> 10783 1.9 nikita <li><b>"<code>no</code>": </b> no buffering.</li> 10784 1.9 nikita <li><b>"<code>full</code>": </b> full buffering.</li> 10785 1.9 nikita <li><b>"<code>line</code>": </b> line buffering.</li> 10786 1.9 nikita </ul> 10787 1.1 mbalmer 10788 1.9 nikita <p> 10789 1.9 nikita For the last two cases, 10790 1.9 nikita <code>size</code> is a hint for the size of the buffer, in bytes. 10791 1.9 nikita The default is an appropriate size. 10792 1.1 mbalmer 10793 1.1 mbalmer 10794 1.9 nikita <p> 10795 1.9 nikita The specific behavior of each mode is non portable; 10796 1.9 nikita check the underlying ISO C function <code>setvbuf</code> in your platform for 10797 1.9 nikita more details. 10798 1.1 mbalmer 10799 1.1 mbalmer 10800 1.1 mbalmer 10801 1.1 mbalmer 10802 1.1 mbalmer <p> 10803 1.1 mbalmer <hr><h3><a name="pdf-file:write"><code>file:write (···)</code></a></h3> 10804 1.1 mbalmer 10805 1.1 mbalmer 10806 1.1 mbalmer <p> 10807 1.2 lneto Writes the value of each of its arguments to <code>file</code>. 10808 1.1 mbalmer The arguments must be strings or numbers. 10809 1.2 lneto 10810 1.2 lneto 10811 1.2 lneto <p> 10812 1.2 lneto In case of success, this function returns <code>file</code>. 10813 1.1 mbalmer 10814 1.1 mbalmer 10815 1.1 mbalmer 10816 1.1 mbalmer 10817 1.1 mbalmer 10818 1.1 mbalmer 10819 1.1 mbalmer 10820 1.2 lneto <h2>6.9 – <a name="6.9">Operating System Facilities</a></h2> 10821 1.1 mbalmer 10822 1.1 mbalmer <p> 10823 1.1 mbalmer This library is implemented through table <a name="pdf-os"><code>os</code></a>. 10824 1.1 mbalmer 10825 1.1 mbalmer 10826 1.1 mbalmer <p> 10827 1.1 mbalmer <hr><h3><a name="pdf-os.clock"><code>os.clock ()</code></a></h3> 10828 1.1 mbalmer 10829 1.1 mbalmer 10830 1.1 mbalmer <p> 10831 1.1 mbalmer Returns an approximation of the amount in seconds of CPU time 10832 1.9 nikita used by the program, 10833 1.9 nikita as returned by the underlying ISO C function <code>clock</code>. 10834 1.1 mbalmer 10835 1.1 mbalmer 10836 1.1 mbalmer 10837 1.1 mbalmer 10838 1.1 mbalmer <p> 10839 1.1 mbalmer <hr><h3><a name="pdf-os.date"><code>os.date ([format [, time]])</code></a></h3> 10840 1.1 mbalmer 10841 1.1 mbalmer 10842 1.1 mbalmer <p> 10843 1.1 mbalmer Returns a string or a table containing date and time, 10844 1.1 mbalmer formatted according to the given string <code>format</code>. 10845 1.1 mbalmer 10846 1.1 mbalmer 10847 1.1 mbalmer <p> 10848 1.1 mbalmer If the <code>time</code> argument is present, 10849 1.1 mbalmer this is the time to be formatted 10850 1.1 mbalmer (see the <a href="#pdf-os.time"><code>os.time</code></a> function for a description of this value). 10851 1.1 mbalmer Otherwise, <code>date</code> formats the current time. 10852 1.1 mbalmer 10853 1.1 mbalmer 10854 1.1 mbalmer <p> 10855 1.1 mbalmer If <code>format</code> starts with '<code>!</code>', 10856 1.1 mbalmer then the date is formatted in Coordinated Universal Time. 10857 1.1 mbalmer After this optional character, 10858 1.1 mbalmer if <code>format</code> is the string "<code>*t</code>", 10859 1.1 mbalmer then <code>date</code> returns a table with the following fields: 10860 1.5 lneto <code>year</code>, <code>month</code> (1–12), <code>day</code> (1–31), 10861 1.9 nikita <code>hour</code> (0–23), <code>min</code> (0–59), 10862 1.9 nikita <code>sec</code> (0–61, due to leap seconds), 10863 1.6 salazar <code>wday</code> (weekday, 1–7, Sunday is 1), 10864 1.6 salazar <code>yday</code> (day of the year, 1–366), 10865 1.1 mbalmer and <code>isdst</code> (daylight saving flag, a boolean). 10866 1.2 lneto This last field may be absent 10867 1.2 lneto if the information is not available. 10868 1.1 mbalmer 10869 1.1 mbalmer 10870 1.1 mbalmer <p> 10871 1.1 mbalmer If <code>format</code> is not "<code>*t</code>", 10872 1.1 mbalmer then <code>date</code> returns the date as a string, 10873 1.3 lneto formatted according to the same rules as the ISO C function <code>strftime</code>. 10874 1.1 mbalmer 10875 1.1 mbalmer 10876 1.1 mbalmer <p> 10877 1.9 nikita If <code>format</code> is absent, it defaults to "<code>%c</code>", 10878 1.9 nikita which gives a human-readable date and time representation 10879 1.9 nikita using the current locale. 10880 1.1 mbalmer 10881 1.1 mbalmer 10882 1.2 lneto <p> 10883 1.9 nikita On non-POSIX systems, 10884 1.2 lneto this function may be not thread safe 10885 1.2 lneto because of its reliance on C function <code>gmtime</code> and C function <code>localtime</code>. 10886 1.2 lneto 10887 1.2 lneto 10888 1.1 mbalmer 10889 1.1 mbalmer 10890 1.1 mbalmer <p> 10891 1.1 mbalmer <hr><h3><a name="pdf-os.difftime"><code>os.difftime (t2, t1)</code></a></h3> 10892 1.1 mbalmer 10893 1.1 mbalmer 10894 1.1 mbalmer <p> 10895 1.3 lneto Returns the difference, in seconds, 10896 1.3 lneto from time <code>t1</code> to time <code>t2</code> 10897 1.3 lneto (where the times are values returned by <a href="#pdf-os.time"><code>os.time</code></a>). 10898 1.1 mbalmer In POSIX, Windows, and some other systems, 10899 1.1 mbalmer this value is exactly <code>t2</code><em>-</em><code>t1</code>. 10900 1.1 mbalmer 10901 1.1 mbalmer 10902 1.1 mbalmer 10903 1.1 mbalmer 10904 1.1 mbalmer <p> 10905 1.1 mbalmer <hr><h3><a name="pdf-os.execute"><code>os.execute ([command])</code></a></h3> 10906 1.1 mbalmer 10907 1.1 mbalmer 10908 1.1 mbalmer <p> 10909 1.3 lneto This function is equivalent to the ISO C function <code>system</code>. 10910 1.1 mbalmer It passes <code>command</code> to be executed by an operating system shell. 10911 1.2 lneto Its first result is <b>true</b> 10912 1.2 lneto if the command terminated successfully, 10913 1.9 nikita or <b>fail</b> otherwise. 10914 1.2 lneto After this first result 10915 1.2 lneto the function returns a string plus a number, 10916 1.2 lneto as follows: 10917 1.2 lneto 10918 1.2 lneto <ul> 10919 1.2 lneto 10920 1.2 lneto <li><b>"<code>exit</code>": </b> 10921 1.2 lneto the command terminated normally; 10922 1.2 lneto the following number is the exit status of the command. 10923 1.2 lneto </li> 10924 1.2 lneto 10925 1.2 lneto <li><b>"<code>signal</code>": </b> 10926 1.2 lneto the command was terminated by a signal; 10927 1.2 lneto the following number is the signal that terminated the command. 10928 1.2 lneto </li> 10929 1.2 lneto 10930 1.2 lneto </ul> 10931 1.2 lneto 10932 1.2 lneto <p> 10933 1.2 lneto When called without a <code>command</code>, 10934 1.2 lneto <code>os.execute</code> returns a boolean that is true if a shell is available. 10935 1.2 lneto 10936 1.1 mbalmer 10937 1.1 mbalmer 10938 1.1 mbalmer 10939 1.2 lneto <p> 10940 1.2 lneto <hr><h3><a name="pdf-os.exit"><code>os.exit ([code [, close]])</code></a></h3> 10941 1.2 lneto 10942 1.1 mbalmer 10943 1.1 mbalmer <p> 10944 1.3 lneto Calls the ISO C function <code>exit</code> to terminate the host program. 10945 1.2 lneto If <code>code</code> is <b>true</b>, 10946 1.2 lneto the returned status is <code>EXIT_SUCCESS</code>; 10947 1.2 lneto if <code>code</code> is <b>false</b>, 10948 1.2 lneto the returned status is <code>EXIT_FAILURE</code>; 10949 1.2 lneto if <code>code</code> is a number, 10950 1.2 lneto the returned status is this number. 10951 1.2 lneto The default value for <code>code</code> is <b>true</b>. 10952 1.1 mbalmer 10953 1.1 mbalmer 10954 1.1 mbalmer <p> 10955 1.2 lneto If the optional second argument <code>close</code> is true, 10956 1.2 lneto closes the Lua state before exiting. 10957 1.1 mbalmer 10958 1.1 mbalmer 10959 1.1 mbalmer 10960 1.1 mbalmer 10961 1.1 mbalmer <p> 10962 1.1 mbalmer <hr><h3><a name="pdf-os.getenv"><code>os.getenv (varname)</code></a></h3> 10963 1.1 mbalmer 10964 1.1 mbalmer 10965 1.1 mbalmer <p> 10966 1.9 nikita Returns the value of the process environment variable <code>varname</code> 10967 1.9 nikita or <b>fail</b> if the variable is not defined. 10968 1.1 mbalmer 10969 1.1 mbalmer 10970 1.1 mbalmer 10971 1.1 mbalmer 10972 1.1 mbalmer <p> 10973 1.1 mbalmer <hr><h3><a name="pdf-os.remove"><code>os.remove (filename)</code></a></h3> 10974 1.1 mbalmer 10975 1.1 mbalmer 10976 1.1 mbalmer <p> 10977 1.2 lneto Deletes the file (or empty directory, on POSIX systems) 10978 1.2 lneto with the given name. 10979 1.9 nikita If this function fails, it returns <b>fail</b> 10980 1.2 lneto plus a string describing the error and the error code. 10981 1.7 mbalmer Otherwise, it returns true. 10982 1.1 mbalmer 10983 1.1 mbalmer 10984 1.1 mbalmer 10985 1.1 mbalmer 10986 1.1 mbalmer <p> 10987 1.1 mbalmer <hr><h3><a name="pdf-os.rename"><code>os.rename (oldname, newname)</code></a></h3> 10988 1.1 mbalmer 10989 1.1 mbalmer 10990 1.1 mbalmer <p> 10991 1.7 mbalmer Renames the file or directory named <code>oldname</code> to <code>newname</code>. 10992 1.9 nikita If this function fails, it returns <b>fail</b>, 10993 1.2 lneto plus a string describing the error and the error code. 10994 1.7 mbalmer Otherwise, it returns true. 10995 1.1 mbalmer 10996 1.1 mbalmer 10997 1.1 mbalmer 10998 1.1 mbalmer 10999 1.1 mbalmer <p> 11000 1.1 mbalmer <hr><h3><a name="pdf-os.setlocale"><code>os.setlocale (locale [, category])</code></a></h3> 11001 1.1 mbalmer 11002 1.1 mbalmer 11003 1.1 mbalmer <p> 11004 1.1 mbalmer Sets the current locale of the program. 11005 1.2 lneto <code>locale</code> is a system-dependent string specifying a locale; 11006 1.1 mbalmer <code>category</code> is an optional string describing which category to change: 11007 1.1 mbalmer <code>"all"</code>, <code>"collate"</code>, <code>"ctype"</code>, 11008 1.1 mbalmer <code>"monetary"</code>, <code>"numeric"</code>, or <code>"time"</code>; 11009 1.1 mbalmer the default category is <code>"all"</code>. 11010 1.1 mbalmer The function returns the name of the new locale, 11011 1.9 nikita or <b>fail</b> if the request cannot be honored. 11012 1.1 mbalmer 11013 1.1 mbalmer 11014 1.1 mbalmer <p> 11015 1.1 mbalmer If <code>locale</code> is the empty string, 11016 1.1 mbalmer the current locale is set to an implementation-defined native locale. 11017 1.1 mbalmer If <code>locale</code> is the string "<code>C</code>", 11018 1.1 mbalmer the current locale is set to the standard C locale. 11019 1.1 mbalmer 11020 1.1 mbalmer 11021 1.1 mbalmer <p> 11022 1.1 mbalmer When called with <b>nil</b> as the first argument, 11023 1.1 mbalmer this function only returns the name of the current locale 11024 1.1 mbalmer for the given category. 11025 1.1 mbalmer 11026 1.1 mbalmer 11027 1.2 lneto <p> 11028 1.2 lneto This function may be not thread safe 11029 1.2 lneto because of its reliance on C function <code>setlocale</code>. 11030 1.2 lneto 11031 1.2 lneto 11032 1.1 mbalmer 11033 1.1 mbalmer 11034 1.1 mbalmer <p> 11035 1.1 mbalmer <hr><h3><a name="pdf-os.time"><code>os.time ([table])</code></a></h3> 11036 1.1 mbalmer 11037 1.1 mbalmer 11038 1.1 mbalmer <p> 11039 1.1 mbalmer Returns the current time when called without arguments, 11040 1.4 mbalmer or a time representing the local date and time specified by the given table. 11041 1.1 mbalmer This table must have fields <code>year</code>, <code>month</code>, and <code>day</code>, 11042 1.2 lneto and may have fields 11043 1.2 lneto <code>hour</code> (default is 12), 11044 1.2 lneto <code>min</code> (default is 0), 11045 1.2 lneto <code>sec</code> (default is 0), 11046 1.2 lneto and <code>isdst</code> (default is <b>nil</b>). 11047 1.4 mbalmer Other fields are ignored. 11048 1.2 lneto For a description of these fields, see the <a href="#pdf-os.date"><code>os.date</code></a> function. 11049 1.1 mbalmer 11050 1.1 mbalmer 11051 1.1 mbalmer <p> 11052 1.9 nikita When the function is called, 11053 1.9 nikita the values in these fields do not need to be inside their valid ranges. 11054 1.4 mbalmer For instance, if <code>sec</code> is -10, 11055 1.9 nikita it means 10 seconds before the time specified by the other fields; 11056 1.4 mbalmer if <code>hour</code> is 1000, 11057 1.9 nikita it means 1000 hours after the time specified by the other fields. 11058 1.4 mbalmer 11059 1.4 mbalmer 11060 1.4 mbalmer <p> 11061 1.1 mbalmer The returned value is a number, whose meaning depends on your system. 11062 1.2 lneto In POSIX, Windows, and some other systems, 11063 1.2 lneto this number counts the number 11064 1.1 mbalmer of seconds since some given start time (the "epoch"). 11065 1.1 mbalmer In other systems, the meaning is not specified, 11066 1.1 mbalmer and the number returned by <code>time</code> can be used only as an argument to 11067 1.2 lneto <a href="#pdf-os.date"><code>os.date</code></a> and <a href="#pdf-os.difftime"><code>os.difftime</code></a>. 11068 1.1 mbalmer 11069 1.1 mbalmer 11070 1.9 nikita <p> 11071 1.9 nikita When called with a table, 11072 1.9 nikita <code>os.time</code> also normalizes all the fields 11073 1.9 nikita documented in the <a href="#pdf-os.date"><code>os.date</code></a> function, 11074 1.9 nikita so that they represent the same time as before the call 11075 1.9 nikita but with values inside their valid ranges. 11076 1.9 nikita 11077 1.9 nikita 11078 1.1 mbalmer 11079 1.1 mbalmer 11080 1.1 mbalmer <p> 11081 1.1 mbalmer <hr><h3><a name="pdf-os.tmpname"><code>os.tmpname ()</code></a></h3> 11082 1.1 mbalmer 11083 1.1 mbalmer 11084 1.1 mbalmer <p> 11085 1.1 mbalmer Returns a string with a file name that can 11086 1.1 mbalmer be used for a temporary file. 11087 1.1 mbalmer The file must be explicitly opened before its use 11088 1.1 mbalmer and explicitly removed when no longer needed. 11089 1.1 mbalmer 11090 1.1 mbalmer 11091 1.1 mbalmer <p> 11092 1.8 alnsn In POSIX systems, 11093 1.1 mbalmer this function also creates a file with that name, 11094 1.1 mbalmer to avoid security risks. 11095 1.1 mbalmer (Someone else might create the file with wrong permissions 11096 1.1 mbalmer in the time between getting the name and creating the file.) 11097 1.1 mbalmer You still have to open the file to use it 11098 1.1 mbalmer and to remove it (even if you do not use it). 11099 1.1 mbalmer 11100 1.1 mbalmer 11101 1.1 mbalmer <p> 11102 1.1 mbalmer When possible, 11103 1.1 mbalmer you may prefer to use <a href="#pdf-io.tmpfile"><code>io.tmpfile</code></a>, 11104 1.1 mbalmer which automatically removes the file when the program ends. 11105 1.1 mbalmer 11106 1.1 mbalmer 11107 1.1 mbalmer 11108 1.1 mbalmer 11109 1.1 mbalmer 11110 1.1 mbalmer 11111 1.1 mbalmer 11112 1.2 lneto <h2>6.10 – <a name="6.10">The Debug Library</a></h2> 11113 1.1 mbalmer 11114 1.1 mbalmer <p> 11115 1.1 mbalmer This library provides 11116 1.9 nikita the functionality of the debug interface (<a href="#4.7">§4.7</a>) to Lua programs. 11117 1.1 mbalmer You should exert care when using this library. 11118 1.2 lneto Several of its functions 11119 1.2 lneto violate basic assumptions about Lua code 11120 1.1 mbalmer (e.g., that variables local to a function 11121 1.2 lneto cannot be accessed from outside; 11122 1.2 lneto that userdata metatables cannot be changed by Lua code; 11123 1.2 lneto that Lua programs do not crash) 11124 1.1 mbalmer and therefore can compromise otherwise secure code. 11125 1.2 lneto Moreover, some functions in this library may be slow. 11126 1.1 mbalmer 11127 1.1 mbalmer 11128 1.1 mbalmer <p> 11129 1.1 mbalmer All functions in this library are provided 11130 1.1 mbalmer inside the <a name="pdf-debug"><code>debug</code></a> table. 11131 1.1 mbalmer All functions that operate over a thread 11132 1.1 mbalmer have an optional first argument which is the 11133 1.1 mbalmer thread to operate over. 11134 1.1 mbalmer The default is always the current thread. 11135 1.1 mbalmer 11136 1.1 mbalmer 11137 1.1 mbalmer <p> 11138 1.1 mbalmer <hr><h3><a name="pdf-debug.debug"><code>debug.debug ()</code></a></h3> 11139 1.1 mbalmer 11140 1.1 mbalmer 11141 1.1 mbalmer <p> 11142 1.1 mbalmer Enters an interactive mode with the user, 11143 1.1 mbalmer running each string that the user enters. 11144 1.1 mbalmer Using simple commands and other debug facilities, 11145 1.1 mbalmer the user can inspect global and local variables, 11146 1.1 mbalmer change their values, evaluate expressions, and so on. 11147 1.1 mbalmer A line containing only the word <code>cont</code> finishes this function, 11148 1.1 mbalmer so that the caller continues its execution. 11149 1.1 mbalmer 11150 1.1 mbalmer 11151 1.1 mbalmer <p> 11152 1.1 mbalmer Note that commands for <code>debug.debug</code> are not lexically nested 11153 1.2 lneto within any function and so have no direct access to local variables. 11154 1.1 mbalmer 11155 1.1 mbalmer 11156 1.1 mbalmer 11157 1.1 mbalmer 11158 1.1 mbalmer <p> 11159 1.1 mbalmer <hr><h3><a name="pdf-debug.gethook"><code>debug.gethook ([thread])</code></a></h3> 11160 1.1 mbalmer 11161 1.1 mbalmer 11162 1.1 mbalmer <p> 11163 1.1 mbalmer Returns the current hook settings of the thread, as three values: 11164 1.1 mbalmer the current hook function, the current hook mask, 11165 1.9 nikita and the current hook count, 11166 1.9 nikita as set by the <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> function. 11167 1.9 nikita 11168 1.9 nikita 11169 1.9 nikita <p> 11170 1.9 nikita Returns <b>fail</b> if there is no active hook. 11171 1.1 mbalmer 11172 1.1 mbalmer 11173 1.1 mbalmer 11174 1.1 mbalmer 11175 1.1 mbalmer <p> 11176 1.2 lneto <hr><h3><a name="pdf-debug.getinfo"><code>debug.getinfo ([thread,] f [, what])</code></a></h3> 11177 1.1 mbalmer 11178 1.1 mbalmer 11179 1.1 mbalmer <p> 11180 1.1 mbalmer Returns a table with information about a function. 11181 1.2 lneto You can give the function directly 11182 1.2 lneto or you can give a number as the value of <code>f</code>, 11183 1.2 lneto which means the function running at level <code>f</code> of the call stack 11184 1.1 mbalmer of the given thread: 11185 1.1 mbalmer level 0 is the current function (<code>getinfo</code> itself); 11186 1.2 lneto level 1 is the function that called <code>getinfo</code> 11187 1.9 nikita (except for tail calls, which do not count in the stack); 11188 1.1 mbalmer and so on. 11189 1.9 nikita If <code>f</code> is a number greater than the number of active functions, 11190 1.9 nikita then <code>getinfo</code> returns <b>fail</b>. 11191 1.1 mbalmer 11192 1.1 mbalmer 11193 1.1 mbalmer <p> 11194 1.1 mbalmer The returned table can contain all the fields returned by <a href="#lua_getinfo"><code>lua_getinfo</code></a>, 11195 1.1 mbalmer with the string <code>what</code> describing which fields to fill in. 11196 1.1 mbalmer The default for <code>what</code> is to get all information available, 11197 1.1 mbalmer except the table of valid lines. 11198 1.1 mbalmer If present, 11199 1.1 mbalmer the option '<code>f</code>' 11200 1.1 mbalmer adds a field named <code>func</code> with the function itself. 11201 1.1 mbalmer If present, 11202 1.1 mbalmer the option '<code>L</code>' 11203 1.1 mbalmer adds a field named <code>activelines</code> with the table of 11204 1.1 mbalmer valid lines. 11205 1.1 mbalmer 11206 1.1 mbalmer 11207 1.1 mbalmer <p> 11208 1.1 mbalmer For instance, the expression <code>debug.getinfo(1,"n").name</code> returns 11209 1.4 mbalmer a name for the current function, 11210 1.1 mbalmer if a reasonable name can be found, 11211 1.1 mbalmer and the expression <code>debug.getinfo(print)</code> 11212 1.1 mbalmer returns a table with all available information 11213 1.1 mbalmer about the <a href="#pdf-print"><code>print</code></a> function. 11214 1.1 mbalmer 11215 1.1 mbalmer 11216 1.1 mbalmer 11217 1.1 mbalmer 11218 1.1 mbalmer <p> 11219 1.2 lneto <hr><h3><a name="pdf-debug.getlocal"><code>debug.getlocal ([thread,] f, local)</code></a></h3> 11220 1.1 mbalmer 11221 1.1 mbalmer 11222 1.1 mbalmer <p> 11223 1.1 mbalmer This function returns the name and the value of the local variable 11224 1.2 lneto with index <code>local</code> of the function at level <code>f</code> of the stack. 11225 1.2 lneto This function accesses not only explicit local variables, 11226 1.9 nikita but also parameters and temporary values. 11227 1.2 lneto 11228 1.2 lneto 11229 1.2 lneto <p> 11230 1.2 lneto The first parameter or local variable has index 1, and so on, 11231 1.3 lneto following the order that they are declared in the code, 11232 1.3 lneto counting only the variables that are active 11233 1.3 lneto in the current scope of the function. 11234 1.9 nikita Compile-time constants may not appear in this listing, 11235 1.9 nikita if they were optimized away by the compiler. 11236 1.8 alnsn Negative indices refer to vararg arguments; 11237 1.8 alnsn -1 is the first vararg argument. 11238 1.9 nikita The function returns <b>fail</b> 11239 1.9 nikita if there is no variable with the given index, 11240 1.2 lneto and raises an error when called with a level out of range. 11241 1.1 mbalmer (You can call <a href="#pdf-debug.getinfo"><code>debug.getinfo</code></a> to check whether the level is valid.) 11242 1.1 mbalmer 11243 1.1 mbalmer 11244 1.1 mbalmer <p> 11245 1.2 lneto Variable names starting with '<code>(</code>' (open parenthesis) 11246 1.2 lneto represent variables with no known names 11247 1.3 lneto (internal variables such as loop control variables, 11248 1.2 lneto and variables from chunks saved without debug information). 11249 1.2 lneto 11250 1.2 lneto 11251 1.2 lneto <p> 11252 1.2 lneto The parameter <code>f</code> may also be a function. 11253 1.2 lneto In that case, <code>getlocal</code> returns only the name of function parameters. 11254 1.1 mbalmer 11255 1.1 mbalmer 11256 1.1 mbalmer 11257 1.1 mbalmer 11258 1.1 mbalmer <p> 11259 1.2 lneto <hr><h3><a name="pdf-debug.getmetatable"><code>debug.getmetatable (value)</code></a></h3> 11260 1.1 mbalmer 11261 1.1 mbalmer 11262 1.1 mbalmer <p> 11263 1.2 lneto Returns the metatable of the given <code>value</code> 11264 1.1 mbalmer or <b>nil</b> if it does not have a metatable. 11265 1.1 mbalmer 11266 1.1 mbalmer 11267 1.1 mbalmer 11268 1.1 mbalmer 11269 1.1 mbalmer <p> 11270 1.1 mbalmer <hr><h3><a name="pdf-debug.getregistry"><code>debug.getregistry ()</code></a></h3> 11271 1.1 mbalmer 11272 1.1 mbalmer 11273 1.1 mbalmer <p> 11274 1.9 nikita Returns the registry table (see <a href="#4.3">§4.3</a>). 11275 1.1 mbalmer 11276 1.1 mbalmer 11277 1.1 mbalmer 11278 1.1 mbalmer 11279 1.1 mbalmer <p> 11280 1.2 lneto <hr><h3><a name="pdf-debug.getupvalue"><code>debug.getupvalue (f, up)</code></a></h3> 11281 1.1 mbalmer 11282 1.1 mbalmer 11283 1.1 mbalmer <p> 11284 1.1 mbalmer This function returns the name and the value of the upvalue 11285 1.2 lneto with index <code>up</code> of the function <code>f</code>. 11286 1.9 nikita The function returns <b>fail</b> 11287 1.9 nikita if there is no upvalue with the given index. 11288 1.1 mbalmer 11289 1.1 mbalmer 11290 1.2 lneto <p> 11291 1.9 nikita (For Lua functions, 11292 1.9 nikita upvalues are the external local variables that the function uses, 11293 1.9 nikita and that are consequently included in its closure.) 11294 1.9 nikita 11295 1.9 nikita 11296 1.9 nikita <p> 11297 1.9 nikita For C functions, this function uses the empty string <code>""</code> 11298 1.9 nikita as a name for all upvalues. 11299 1.9 nikita 11300 1.9 nikita 11301 1.9 nikita <p> 11302 1.9 nikita Variable name '<code>?</code>' (interrogation mark) 11303 1.9 nikita represents variables with no known names 11304 1.2 lneto (variables from chunks saved without debug information). 11305 1.2 lneto 11306 1.2 lneto 11307 1.1 mbalmer 11308 1.1 mbalmer 11309 1.1 mbalmer <p> 11310 1.9 nikita <hr><h3><a name="pdf-debug.getuservalue"><code>debug.getuservalue (u, n)</code></a></h3> 11311 1.1 mbalmer 11312 1.1 mbalmer 11313 1.1 mbalmer <p> 11314 1.9 nikita Returns the <code>n</code>-th user value associated 11315 1.9 nikita to the userdata <code>u</code> plus a boolean, 11316 1.9 nikita <b>false</b> if the userdata does not have that value. 11317 1.1 mbalmer 11318 1.1 mbalmer 11319 1.1 mbalmer 11320 1.1 mbalmer 11321 1.1 mbalmer <p> 11322 1.1 mbalmer <hr><h3><a name="pdf-debug.sethook"><code>debug.sethook ([thread,] hook, mask [, count])</code></a></h3> 11323 1.1 mbalmer 11324 1.1 mbalmer 11325 1.1 mbalmer <p> 11326 1.9 nikita Sets the given function as the debug hook. 11327 1.1 mbalmer The string <code>mask</code> and the number <code>count</code> describe 11328 1.1 mbalmer when the hook will be called. 11329 1.2 lneto The string mask may have any combination of the following characters, 11330 1.1 mbalmer with the given meaning: 11331 1.1 mbalmer 11332 1.1 mbalmer <ul> 11333 1.2 lneto <li><b>'<code>c</code>': </b> the hook is called every time Lua calls a function;</li> 11334 1.2 lneto <li><b>'<code>r</code>': </b> the hook is called every time Lua returns from a function;</li> 11335 1.2 lneto <li><b>'<code>l</code>': </b> the hook is called every time Lua enters a new line of code.</li> 11336 1.1 mbalmer </ul><p> 11337 1.2 lneto Moreover, 11338 1.2 lneto with a <code>count</code> different from zero, 11339 1.2 lneto the hook is called also after every <code>count</code> instructions. 11340 1.1 mbalmer 11341 1.1 mbalmer 11342 1.1 mbalmer <p> 11343 1.1 mbalmer When called without arguments, 11344 1.1 mbalmer <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> turns off the hook. 11345 1.1 mbalmer 11346 1.1 mbalmer 11347 1.1 mbalmer <p> 11348 1.9 nikita When the hook is called, its first parameter is a string 11349 1.1 mbalmer describing the event that has triggered its call: 11350 1.9 nikita <code>"call"</code>, <code>"tail call"</code>, <code>"return"</code>, 11351 1.1 mbalmer <code>"line"</code>, and <code>"count"</code>. 11352 1.1 mbalmer For line events, 11353 1.1 mbalmer the hook also gets the new line number as its second parameter. 11354 1.1 mbalmer Inside a hook, 11355 1.1 mbalmer you can call <code>getinfo</code> with level 2 to get more information about 11356 1.9 nikita the running function. 11357 1.9 nikita (Level 0 is the <code>getinfo</code> function, 11358 1.9 nikita and level 1 is the hook function.) 11359 1.1 mbalmer 11360 1.1 mbalmer 11361 1.1 mbalmer 11362 1.1 mbalmer 11363 1.1 mbalmer <p> 11364 1.1 mbalmer <hr><h3><a name="pdf-debug.setlocal"><code>debug.setlocal ([thread,] level, local, value)</code></a></h3> 11365 1.1 mbalmer 11366 1.1 mbalmer 11367 1.1 mbalmer <p> 11368 1.1 mbalmer This function assigns the value <code>value</code> to the local variable 11369 1.1 mbalmer with index <code>local</code> of the function at level <code>level</code> of the stack. 11370 1.9 nikita The function returns <b>fail</b> if there is no local 11371 1.1 mbalmer variable with the given index, 11372 1.1 mbalmer and raises an error when called with a <code>level</code> out of range. 11373 1.1 mbalmer (You can call <code>getinfo</code> to check whether the level is valid.) 11374 1.1 mbalmer Otherwise, it returns the name of the local variable. 11375 1.1 mbalmer 11376 1.1 mbalmer 11377 1.2 lneto <p> 11378 1.2 lneto See <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for more information about 11379 1.2 lneto variable indices and names. 11380 1.2 lneto 11381 1.2 lneto 11382 1.1 mbalmer 11383 1.1 mbalmer 11384 1.1 mbalmer <p> 11385 1.2 lneto <hr><h3><a name="pdf-debug.setmetatable"><code>debug.setmetatable (value, table)</code></a></h3> 11386 1.1 mbalmer 11387 1.1 mbalmer 11388 1.1 mbalmer <p> 11389 1.2 lneto Sets the metatable for the given <code>value</code> to the given <code>table</code> 11390 1.1 mbalmer (which can be <b>nil</b>). 11391 1.2 lneto Returns <code>value</code>. 11392 1.1 mbalmer 11393 1.1 mbalmer 11394 1.1 mbalmer 11395 1.1 mbalmer 11396 1.1 mbalmer <p> 11397 1.2 lneto <hr><h3><a name="pdf-debug.setupvalue"><code>debug.setupvalue (f, up, value)</code></a></h3> 11398 1.1 mbalmer 11399 1.1 mbalmer 11400 1.1 mbalmer <p> 11401 1.1 mbalmer This function assigns the value <code>value</code> to the upvalue 11402 1.2 lneto with index <code>up</code> of the function <code>f</code>. 11403 1.9 nikita The function returns <b>fail</b> if there is no upvalue 11404 1.1 mbalmer with the given index. 11405 1.1 mbalmer Otherwise, it returns the name of the upvalue. 11406 1.1 mbalmer 11407 1.1 mbalmer 11408 1.9 nikita <p> 11409 1.9 nikita See <a href="#pdf-debug.getupvalue"><code>debug.getupvalue</code></a> for more information about upvalues. 11410 1.9 nikita 11411 1.9 nikita 11412 1.1 mbalmer 11413 1.1 mbalmer 11414 1.1 mbalmer <p> 11415 1.9 nikita <hr><h3><a name="pdf-debug.setuservalue"><code>debug.setuservalue (udata, value, n)</code></a></h3> 11416 1.2 lneto 11417 1.2 lneto 11418 1.2 lneto <p> 11419 1.2 lneto Sets the given <code>value</code> as 11420 1.9 nikita the <code>n</code>-th user value associated to the given <code>udata</code>. 11421 1.2 lneto <code>udata</code> must be a full userdata. 11422 1.2 lneto 11423 1.2 lneto 11424 1.2 lneto <p> 11425 1.9 nikita Returns <code>udata</code>, 11426 1.9 nikita or <b>fail</b> if the userdata does not have that value. 11427 1.2 lneto 11428 1.2 lneto 11429 1.2 lneto 11430 1.2 lneto 11431 1.2 lneto <p> 11432 1.2 lneto <hr><h3><a name="pdf-debug.traceback"><code>debug.traceback ([thread,] [message [, level]])</code></a></h3> 11433 1.1 mbalmer 11434 1.1 mbalmer 11435 1.1 mbalmer <p> 11436 1.2 lneto If <code>message</code> is present but is neither a string nor <b>nil</b>, 11437 1.2 lneto this function returns <code>message</code> without further processing. 11438 1.2 lneto Otherwise, 11439 1.2 lneto it returns a string with a traceback of the call stack. 11440 1.3 lneto The optional <code>message</code> string is appended 11441 1.1 mbalmer at the beginning of the traceback. 11442 1.1 mbalmer An optional <code>level</code> number tells at which level 11443 1.1 mbalmer to start the traceback 11444 1.1 mbalmer (default is 1, the function calling <code>traceback</code>). 11445 1.1 mbalmer 11446 1.1 mbalmer 11447 1.1 mbalmer 11448 1.1 mbalmer 11449 1.2 lneto <p> 11450 1.2 lneto <hr><h3><a name="pdf-debug.upvalueid"><code>debug.upvalueid (f, n)</code></a></h3> 11451 1.2 lneto 11452 1.2 lneto 11453 1.2 lneto <p> 11454 1.3 lneto Returns a unique identifier (as a light userdata) 11455 1.2 lneto for the upvalue numbered <code>n</code> 11456 1.2 lneto from the given function. 11457 1.2 lneto 11458 1.2 lneto 11459 1.2 lneto <p> 11460 1.2 lneto These unique identifiers allow a program to check whether different 11461 1.2 lneto closures share upvalues. 11462 1.2 lneto Lua closures that share an upvalue 11463 1.2 lneto (that is, that access a same external local variable) 11464 1.2 lneto will return identical ids for those upvalue indices. 11465 1.2 lneto 11466 1.2 lneto 11467 1.2 lneto 11468 1.2 lneto 11469 1.2 lneto <p> 11470 1.2 lneto <hr><h3><a name="pdf-debug.upvaluejoin"><code>debug.upvaluejoin (f1, n1, f2, n2)</code></a></h3> 11471 1.2 lneto 11472 1.2 lneto 11473 1.2 lneto <p> 11474 1.2 lneto Make the <code>n1</code>-th upvalue of the Lua closure <code>f1</code> 11475 1.2 lneto refer to the <code>n2</code>-th upvalue of the Lua closure <code>f2</code>. 11476 1.2 lneto 11477 1.2 lneto 11478 1.2 lneto 11479 1.2 lneto 11480 1.1 mbalmer 11481 1.1 mbalmer 11482 1.1 mbalmer 11483 1.2 lneto <h1>7 – <a name="7">Lua Standalone</a></h1> 11484 1.1 mbalmer 11485 1.1 mbalmer <p> 11486 1.1 mbalmer Although Lua has been designed as an extension language, 11487 1.1 mbalmer to be embedded in a host C program, 11488 1.2 lneto it is also frequently used as a standalone language. 11489 1.2 lneto An interpreter for Lua as a standalone language, 11490 1.1 mbalmer called simply <code>lua</code>, 11491 1.1 mbalmer is provided with the standard distribution. 11492 1.2 lneto The standalone interpreter includes 11493 1.9 nikita all standard libraries. 11494 1.1 mbalmer Its usage is: 11495 1.1 mbalmer 11496 1.1 mbalmer <pre> 11497 1.1 mbalmer lua [options] [script [args]] 11498 1.1 mbalmer </pre><p> 11499 1.1 mbalmer The options are: 11500 1.1 mbalmer 11501 1.1 mbalmer <ul> 11502 1.9 nikita <li><b><code>-e <em>stat</em></code>: </b> execute string <em>stat</em>;</li> 11503 1.9 nikita <li><b><code>-i</code>: </b> enter interactive mode after running <em>script</em>;</li> 11504 1.9 nikita <li><b><code>-l <em>mod</em></code>: </b> "require" <em>mod</em> and assign the 11505 1.9 nikita result to global <em>mod</em>;</li> 11506 1.9 nikita <li><b><code>-v</code>: </b> print version information;</li> 11507 1.9 nikita <li><b><code>-E</code>: </b> ignore environment variables;</li> 11508 1.9 nikita <li><b><code>-W</code>: </b> turn warnings on;</li> 11509 1.9 nikita <li><b><code>--</code>: </b> stop handling options;</li> 11510 1.9 nikita <li><b><code>-</code>: </b> execute <code>stdin</code> as a file and stop handling options.</li> 11511 1.1 mbalmer </ul><p> 11512 1.3 lneto After handling its options, <code>lua</code> runs the given <em>script</em>. 11513 1.1 mbalmer When called without arguments, 11514 1.1 mbalmer <code>lua</code> behaves as <code>lua -v -i</code> 11515 1.1 mbalmer when the standard input (<code>stdin</code>) is a terminal, 11516 1.1 mbalmer and as <code>lua -</code> otherwise. 11517 1.1 mbalmer 11518 1.1 mbalmer 11519 1.1 mbalmer <p> 11520 1.9 nikita When called without the option <code>-E</code>, 11521 1.9 nikita the interpreter checks for an environment variable <a name="pdf-LUA_INIT_5_4"><code>LUA_INIT_5_4</code></a> 11522 1.3 lneto (or <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a> if the versioned name is not defined) 11523 1.2 lneto before running any argument. 11524 1.2 lneto If the variable content has the format <code>@<em>filename</em></code>, 11525 1.1 mbalmer then <code>lua</code> executes the file. 11526 1.1 mbalmer Otherwise, <code>lua</code> executes the string itself. 11527 1.1 mbalmer 11528 1.1 mbalmer 11529 1.1 mbalmer <p> 11530 1.9 nikita When called with the option <code>-E</code>, 11531 1.9 nikita Lua does not consult any environment variables. 11532 1.9 nikita In particular, 11533 1.9 nikita the values of <a href="#pdf-package.path"><code>package.path</code></a> and <a href="#pdf-package.cpath"><code>package.cpath</code></a> 11534 1.9 nikita are set with the default paths defined in <code>luaconf.h</code>. 11535 1.2 lneto 11536 1.2 lneto 11537 1.2 lneto <p> 11538 1.9 nikita The options <code>-e</code>, <code>-l</code>, and <code>-W</code> are handled in 11539 1.9 nikita the order they appear. 11540 1.1 mbalmer For instance, an invocation like 11541 1.1 mbalmer 11542 1.1 mbalmer <pre> 11543 1.9 nikita $ lua -e 'a=1' -llib1 script.lua 11544 1.1 mbalmer </pre><p> 11545 1.9 nikita will first set <code>a</code> to 1, then require the library <code>lib1</code>, 11546 1.1 mbalmer and finally run the file <code>script.lua</code> with no arguments. 11547 1.1 mbalmer (Here <code>$</code> is the shell prompt. Your prompt may be different.) 11548 1.1 mbalmer 11549 1.1 mbalmer 11550 1.1 mbalmer <p> 11551 1.2 lneto Before running any code, 11552 1.2 lneto <code>lua</code> collects all command-line arguments 11553 1.1 mbalmer in a global table called <code>arg</code>. 11554 1.2 lneto The script name goes to index 0, 11555 1.1 mbalmer the first argument after the script name goes to index 1, 11556 1.1 mbalmer and so on. 11557 1.1 mbalmer Any arguments before the script name 11558 1.2 lneto (that is, the interpreter name plus its options) 11559 1.1 mbalmer go to negative indices. 11560 1.1 mbalmer For instance, in the call 11561 1.1 mbalmer 11562 1.1 mbalmer <pre> 11563 1.1 mbalmer $ lua -la b.lua t1 t2 11564 1.1 mbalmer </pre><p> 11565 1.2 lneto the table is like this: 11566 1.1 mbalmer 11567 1.1 mbalmer <pre> 11568 1.1 mbalmer arg = { [-2] = "lua", [-1] = "-la", 11569 1.1 mbalmer [0] = "b.lua", 11570 1.1 mbalmer [1] = "t1", [2] = "t2" } 11571 1.1 mbalmer </pre><p> 11572 1.2 lneto If there is no script in the call, 11573 1.2 lneto the interpreter name goes to index 0, 11574 1.2 lneto followed by the other arguments. 11575 1.2 lneto For instance, the call 11576 1.2 lneto 11577 1.2 lneto <pre> 11578 1.2 lneto $ lua -e "print(arg[1])" 11579 1.2 lneto </pre><p> 11580 1.2 lneto will print "<code>-e</code>". 11581 1.3 lneto If there is a script, 11582 1.8 alnsn the script is called with arguments 11583 1.3 lneto <code>arg[1]</code>, ···, <code>arg[#arg]</code>. 11584 1.9 nikita Like all chunks in Lua, 11585 1.9 nikita the script is compiled as a vararg function. 11586 1.1 mbalmer 11587 1.1 mbalmer 11588 1.1 mbalmer <p> 11589 1.1 mbalmer In interactive mode, 11590 1.2 lneto Lua repeatedly prompts and waits for a line. 11591 1.2 lneto After reading a line, 11592 1.2 lneto Lua first try to interpret the line as an expression. 11593 1.2 lneto If it succeeds, it prints its value. 11594 1.2 lneto Otherwise, it interprets the line as a statement. 11595 1.2 lneto If you write an incomplete statement, 11596 1.1 mbalmer the interpreter waits for its completion 11597 1.1 mbalmer by issuing a different prompt. 11598 1.1 mbalmer 11599 1.1 mbalmer 11600 1.1 mbalmer <p> 11601 1.6 salazar If the global variable <a name="pdf-_PROMPT"><code>_PROMPT</code></a> contains a string, 11602 1.6 salazar then its value is used as the prompt. 11603 1.6 salazar Similarly, if the global variable <a name="pdf-_PROMPT2"><code>_PROMPT2</code></a> contains a string, 11604 1.6 salazar its value is used as the secondary prompt 11605 1.6 salazar (issued during incomplete statements). 11606 1.6 salazar 11607 1.6 salazar 11608 1.6 salazar <p> 11609 1.2 lneto In case of unprotected errors in the script, 11610 1.2 lneto the interpreter reports the error to the standard error stream. 11611 1.7 mbalmer If the error object is not a string but 11612 1.3 lneto has a metamethod <code>__tostring</code>, 11613 1.2 lneto the interpreter calls this metamethod to produce the final message. 11614 1.3 lneto Otherwise, the interpreter converts the error object to a string 11615 1.3 lneto and adds a stack traceback to it. 11616 1.9 nikita When warnings are on, 11617 1.9 nikita they are simply printed in the standard error output. 11618 1.2 lneto 11619 1.2 lneto 11620 1.2 lneto <p> 11621 1.2 lneto When finishing normally, 11622 1.2 lneto the interpreter closes its main Lua state 11623 1.2 lneto (see <a href="#lua_close"><code>lua_close</code></a>). 11624 1.2 lneto The script can avoid this step by 11625 1.2 lneto calling <a href="#pdf-os.exit"><code>os.exit</code></a> to terminate. 11626 1.1 mbalmer 11627 1.1 mbalmer 11628 1.1 mbalmer <p> 11629 1.1 mbalmer To allow the use of Lua as a 11630 1.1 mbalmer script interpreter in Unix systems, 11631 1.9 nikita Lua skips the first line of a file chunk if it starts with <code>#</code>. 11632 1.1 mbalmer Therefore, Lua scripts can be made into executable programs 11633 1.1 mbalmer by using <code>chmod +x</code> and the <code>#!</code> form, 11634 1.1 mbalmer as in 11635 1.1 mbalmer 11636 1.1 mbalmer <pre> 11637 1.1 mbalmer #!/usr/local/bin/lua 11638 1.1 mbalmer </pre><p> 11639 1.9 nikita Of course, 11640 1.1 mbalmer the location of the Lua interpreter may be different in your machine. 11641 1.1 mbalmer If <code>lua</code> is in your <code>PATH</code>, 11642 1.2 lneto then 11643 1.1 mbalmer 11644 1.1 mbalmer <pre> 11645 1.1 mbalmer #!/usr/bin/env lua 11646 1.1 mbalmer </pre><p> 11647 1.9 nikita is a more portable solution. 11648 1.1 mbalmer 11649 1.1 mbalmer 11650 1.1 mbalmer 11651 1.2 lneto <h1>8 – <a name="8">Incompatibilities with the Previous Version</a></h1> 11652 1.1 mbalmer 11653 1.9 nikita 11654 1.9 nikita 11655 1.1 mbalmer <p> 11656 1.1 mbalmer Here we list the incompatibilities that you may find when moving a program 11657 1.9 nikita from Lua 5.3 to Lua 5.4. 11658 1.9 nikita 11659 1.9 nikita 11660 1.9 nikita <p> 11661 1.2 lneto You can avoid some incompatibilities by compiling Lua with 11662 1.1 mbalmer appropriate options (see file <code>luaconf.h</code>). 11663 1.1 mbalmer However, 11664 1.2 lneto all these compatibility options will be removed in the future. 11665 1.9 nikita More often than not, 11666 1.9 nikita compatibility issues arise when these compatibility options 11667 1.9 nikita are removed. 11668 1.9 nikita So, whenever you have the chance, 11669 1.9 nikita you should try to test your code with a version of Lua compiled 11670 1.9 nikita with all compatibility options turned off. 11671 1.9 nikita That will ease transitions to newer versions of Lua. 11672 1.1 mbalmer 11673 1.1 mbalmer 11674 1.2 lneto <p> 11675 1.2 lneto Lua versions can always change the C API in ways that 11676 1.2 lneto do not imply source-code changes in a program, 11677 1.2 lneto such as the numeric values for constants 11678 1.2 lneto or the implementation of functions as macros. 11679 1.2 lneto Therefore, 11680 1.9 nikita you should never assume that binaries are compatible between 11681 1.2 lneto different Lua versions. 11682 1.2 lneto Always recompile clients of the Lua API when 11683 1.2 lneto using a new version. 11684 1.1 mbalmer 11685 1.1 mbalmer 11686 1.2 lneto <p> 11687 1.2 lneto Similarly, Lua versions can always change the internal representation 11688 1.2 lneto of precompiled chunks; 11689 1.3 lneto precompiled chunks are not compatible between different Lua versions. 11690 1.1 mbalmer 11691 1.1 mbalmer 11692 1.2 lneto <p> 11693 1.2 lneto The standard paths in the official distribution may 11694 1.2 lneto change between versions. 11695 1.1 mbalmer 11696 1.1 mbalmer 11697 1.1 mbalmer 11698 1.9 nikita 11699 1.9 nikita 11700 1.9 nikita <h2>8.1 – <a name="8.1">Incompatibilities in the Language</a></h2> 11701 1.1 mbalmer <ul> 11702 1.1 mbalmer 11703 1.1 mbalmer <li> 11704 1.9 nikita The coercion of strings to numbers in 11705 1.9 nikita arithmetic and bitwise operations 11706 1.9 nikita has been removed from the core language. 11707 1.9 nikita The string library does a similar job 11708 1.9 nikita for arithmetic (but not for bitwise) operations 11709 1.9 nikita using the string metamethods. 11710 1.9 nikita However, unlike in previous versions, 11711 1.9 nikita the new implementation preserves the implicit type of the numeral 11712 1.9 nikita in the string. 11713 1.9 nikita For instance, the result of <code>"1" + "2"</code> now is an integer, 11714 1.9 nikita not a float. 11715 1.9 nikita </li> 11716 1.2 lneto 11717 1.9 nikita <li> 11718 1.9 nikita Literal decimal integer constants that overflow are read as floats, 11719 1.9 nikita instead of wrapping around. 11720 1.9 nikita You can use hexadecimal notation for such constants if you 11721 1.9 nikita want the old behavior 11722 1.9 nikita (reading them as integers with wrap around). 11723 1.9 nikita </li> 11724 1.1 mbalmer 11725 1.9 nikita <li> 11726 1.9 nikita The use of the <code>__lt</code> metamethod to emulate <code>__le</code> 11727 1.9 nikita has been removed. 11728 1.9 nikita When needed, this metamethod must be explicitly defined. 11729 1.1 mbalmer </li> 11730 1.1 mbalmer 11731 1.1 mbalmer <li> 11732 1.9 nikita The semantics of the numerical <b>for</b> loop 11733 1.9 nikita over integers changed in some details. 11734 1.9 nikita In particular, the control variable never wraps around. 11735 1.9 nikita </li> 11736 1.1 mbalmer 11737 1.9 nikita <li> 11738 1.9 nikita A label for a <b>goto</b> cannot be declared where a label with the same 11739 1.9 nikita name is visible, even if this other label is declared in an enclosing 11740 1.9 nikita block. 11741 1.1 mbalmer </li> 11742 1.1 mbalmer 11743 1.1 mbalmer <li> 11744 1.9 nikita When finalizing an object, 11745 1.9 nikita Lua does not ignore <code>__gc</code> metamethods that are not functions. 11746 1.9 nikita Any value will be called, if present. 11747 1.9 nikita (Non-callable values will generate a warning, 11748 1.9 nikita like any other error when calling a finalizer.) 11749 1.1 mbalmer </li> 11750 1.1 mbalmer 11751 1.1 mbalmer </ul> 11752 1.1 mbalmer 11753 1.1 mbalmer 11754 1.1 mbalmer 11755 1.1 mbalmer 11756 1.9 nikita <h2>8.2 – <a name="8.2">Incompatibilities in the Libraries</a></h2> 11757 1.1 mbalmer <ul> 11758 1.1 mbalmer 11759 1.1 mbalmer <li> 11760 1.9 nikita The function <a href="#pdf-print"><code>print</code></a> does not call <a href="#pdf-tostring"><code>tostring</code></a> 11761 1.9 nikita to format its arguments; 11762 1.9 nikita instead, it has this functionality hardwired. 11763 1.9 nikita You should use <code>__tostring</code> to modify how values are printed. 11764 1.3 lneto </li> 11765 1.3 lneto 11766 1.3 lneto <li> 11767 1.9 nikita The pseudo-random number generator used by the function <a href="#pdf-math.random"><code>math.random</code></a> 11768 1.9 nikita now starts with a somewhat random seed. 11769 1.9 nikita Moreover, it uses a different algorithm. 11770 1.3 lneto </li> 11771 1.3 lneto 11772 1.3 lneto <li> 11773 1.9 nikita By default, the decoding functions in the <a href="#pdf-utf8"><code>utf8</code></a> library 11774 1.9 nikita do not accept surrogates as valid code points. 11775 1.9 nikita An extra parameter in these functions makes them more permissive. 11776 1.1 mbalmer </li> 11777 1.1 mbalmer 11778 1.1 mbalmer <li> 11779 1.9 nikita The options "<code>setpause</code>" and "<code>setstepmul</code>" 11780 1.9 nikita of the function <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> are deprecated. 11781 1.9 nikita You should use the new option "<code>incremental</code>" to set them. 11782 1.1 mbalmer </li> 11783 1.1 mbalmer 11784 1.1 mbalmer <li> 11785 1.9 nikita The function <a href="#pdf-io.lines"><code>io.lines</code></a> now returns four values, 11786 1.9 nikita instead of just one. 11787 1.9 nikita That can be a problem when it is used as the sole 11788 1.9 nikita argument to another function that has optional parameters, 11789 1.9 nikita such as in <code>load(io.lines(filename, "L"))</code>. 11790 1.9 nikita To fix that issue, 11791 1.9 nikita you can wrap the call into parentheses, 11792 1.9 nikita to adjust its number of results to one. 11793 1.3 lneto </li> 11794 1.3 lneto 11795 1.9 nikita </ul> 11796 1.9 nikita 11797 1.1 mbalmer 11798 1.4 mbalmer 11799 1.2 lneto 11800 1.9 nikita <h2>8.3 – <a name="8.3">Incompatibilities in the API</a></h2> 11801 1.2 lneto 11802 1.2 lneto 11803 1.9 nikita <ul> 11804 1.2 lneto 11805 1.9 nikita <li> 11806 1.9 nikita Full userdata now has an arbitrary number of associated user values. 11807 1.9 nikita Therefore, the functions <code>lua_newuserdata</code>, 11808 1.9 nikita <code>lua_setuservalue</code>, and <code>lua_getuservalue</code> were 11809 1.9 nikita replaced by <a href="#lua_newuserdatauv"><code>lua_newuserdatauv</code></a>, 11810 1.9 nikita <a href="#lua_setiuservalue"><code>lua_setiuservalue</code></a>, and <a href="#lua_getiuservalue"><code>lua_getiuservalue</code></a>, 11811 1.9 nikita which have an extra argument. 11812 1.2 lneto 11813 1.2 lneto 11814 1.9 nikita <p> 11815 1.9 nikita For compatibility, the old names still work as macros assuming 11816 1.9 nikita one single user value. 11817 1.9 nikita Note, however, that userdata with zero user values 11818 1.9 nikita are more efficient memory-wise. 11819 1.9 nikita </li> 11820 1.2 lneto 11821 1.1 mbalmer <li> 11822 1.9 nikita The function <a href="#lua_resume"><code>lua_resume</code></a> has an extra parameter. 11823 1.9 nikita This out parameter returns the number of values on 11824 1.9 nikita the top of the stack that were yielded or returned by the coroutine. 11825 1.9 nikita (In previous versions, 11826 1.9 nikita those values were the entire stack.) 11827 1.1 mbalmer </li> 11828 1.1 mbalmer 11829 1.1 mbalmer <li> 11830 1.9 nikita The function <a href="#lua_version"><code>lua_version</code></a> returns the version number, 11831 1.9 nikita instead of an address of the version number. 11832 1.9 nikita The Lua core should work correctly with libraries using their 11833 1.9 nikita own static copies of the same core, 11834 1.9 nikita so there is no need to check whether they are using the same 11835 1.9 nikita address space. 11836 1.1 mbalmer </li> 11837 1.1 mbalmer 11838 1.3 lneto <li> 11839 1.9 nikita The constant <code>LUA_ERRGCMM</code> was removed. 11840 1.9 nikita Errors in finalizers are never propagated; 11841 1.9 nikita instead, they generate a warning. 11842 1.3 lneto </li> 11843 1.3 lneto 11844 1.3 lneto <li> 11845 1.9 nikita The options <code>LUA_GCSETPAUSE</code> and <code>LUA_GCSETSTEPMUL</code> 11846 1.9 nikita of the function <a href="#lua_gc"><code>lua_gc</code></a> are deprecated. 11847 1.9 nikita You should use the new option <code>LUA_GCINC</code> to set them. 11848 1.3 lneto </li> 11849 1.3 lneto 11850 1.1 mbalmer </ul> 11851 1.1 mbalmer 11852 1.1 mbalmer 11853 1.1 mbalmer 11854 1.1 mbalmer 11855 1.2 lneto <h1>9 – <a name="9">The Complete Syntax of Lua</a></h1> 11856 1.1 mbalmer 11857 1.1 mbalmer <p> 11858 1.1 mbalmer Here is the complete syntax of Lua in extended BNF. 11859 1.3 lneto As usual in extended BNF, 11860 1.3 lneto {A} means 0 or more As, 11861 1.3 lneto and [A] means an optional A. 11862 1.3 lneto (For operator precedences, see <a href="#3.4.8">§3.4.8</a>; 11863 1.3 lneto for a description of the terminals 11864 1.3 lneto Name, Numeral, 11865 1.3 lneto and LiteralString, see <a href="#3.1">§3.1</a>.) 11866 1.1 mbalmer 11867 1.1 mbalmer 11868 1.1 mbalmer 11869 1.1 mbalmer 11870 1.1 mbalmer <pre> 11871 1.1 mbalmer 11872 1.2 lneto chunk ::= block 11873 1.1 mbalmer 11874 1.2 lneto block ::= {stat} [retstat] 11875 1.1 mbalmer 11876 1.2 lneto stat ::= ‘<b>;</b>’ | 11877 1.2 lneto varlist ‘<b>=</b>’ explist | 11878 1.1 mbalmer functioncall | 11879 1.2 lneto label | 11880 1.2 lneto <b>break</b> | 11881 1.2 lneto <b>goto</b> Name | 11882 1.1 mbalmer <b>do</b> block <b>end</b> | 11883 1.1 mbalmer <b>while</b> exp <b>do</b> block <b>end</b> | 11884 1.1 mbalmer <b>repeat</b> block <b>until</b> exp | 11885 1.1 mbalmer <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> | 11886 1.2 lneto <b>for</b> Name ‘<b>=</b>’ exp ‘<b>,</b>’ exp [‘<b>,</b>’ exp] <b>do</b> block <b>end</b> | 11887 1.1 mbalmer <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> | 11888 1.1 mbalmer <b>function</b> funcname funcbody | 11889 1.1 mbalmer <b>local</b> <b>function</b> Name funcbody | 11890 1.9 nikita <b>local</b> attnamelist [‘<b>=</b>’ explist] 11891 1.9 nikita 11892 1.9 nikita attnamelist ::= Name attrib {‘<b>,</b>’ Name attrib} 11893 1.9 nikita 11894 1.9 nikita attrib ::= [‘<b><</b>’ Name ‘<b>></b>’] 11895 1.1 mbalmer 11896 1.2 lneto retstat ::= <b>return</b> [explist] [‘<b>;</b>’] 11897 1.1 mbalmer 11898 1.2 lneto label ::= ‘<b>::</b>’ Name ‘<b>::</b>’ 11899 1.1 mbalmer 11900 1.2 lneto funcname ::= Name {‘<b>.</b>’ Name} [‘<b>:</b>’ Name] 11901 1.1 mbalmer 11902 1.2 lneto varlist ::= var {‘<b>,</b>’ var} 11903 1.1 mbalmer 11904 1.2 lneto var ::= Name | prefixexp ‘<b>[</b>’ exp ‘<b>]</b>’ | prefixexp ‘<b>.</b>’ Name 11905 1.1 mbalmer 11906 1.2 lneto namelist ::= Name {‘<b>,</b>’ Name} 11907 1.1 mbalmer 11908 1.2 lneto explist ::= exp {‘<b>,</b>’ exp} 11909 1.2 lneto 11910 1.3 lneto exp ::= <b>nil</b> | <b>false</b> | <b>true</b> | Numeral | LiteralString | ‘<b>...</b>’ | functiondef | 11911 1.1 mbalmer prefixexp | tableconstructor | exp binop exp | unop exp 11912 1.1 mbalmer 11913 1.2 lneto prefixexp ::= var | functioncall | ‘<b>(</b>’ exp ‘<b>)</b>’ 11914 1.1 mbalmer 11915 1.2 lneto functioncall ::= prefixexp args | prefixexp ‘<b>:</b>’ Name args 11916 1.1 mbalmer 11917 1.3 lneto args ::= ‘<b>(</b>’ [explist] ‘<b>)</b>’ | tableconstructor | LiteralString 11918 1.1 mbalmer 11919 1.2 lneto functiondef ::= <b>function</b> funcbody 11920 1.1 mbalmer 11921 1.2 lneto funcbody ::= ‘<b>(</b>’ [parlist] ‘<b>)</b>’ block <b>end</b> 11922 1.1 mbalmer 11923 1.2 lneto parlist ::= namelist [‘<b>,</b>’ ‘<b>...</b>’] | ‘<b>...</b>’ 11924 1.1 mbalmer 11925 1.2 lneto tableconstructor ::= ‘<b>{</b>’ [fieldlist] ‘<b>}</b>’ 11926 1.1 mbalmer 11927 1.1 mbalmer fieldlist ::= field {fieldsep field} [fieldsep] 11928 1.1 mbalmer 11929 1.2 lneto field ::= ‘<b>[</b>’ exp ‘<b>]</b>’ ‘<b>=</b>’ exp | Name ‘<b>=</b>’ exp | exp 11930 1.1 mbalmer 11931 1.2 lneto fieldsep ::= ‘<b>,</b>’ | ‘<b>;</b>’ 11932 1.1 mbalmer 11933 1.2 lneto binop ::= ‘<b>+</b>’ | ‘<b>-</b>’ | ‘<b>*</b>’ | ‘<b>/</b>’ | ‘<b>//</b>’ | ‘<b>^</b>’ | ‘<b>%</b>’ | 11934 1.2 lneto ‘<b>&</b>’ | ‘<b>~</b>’ | ‘<b>|</b>’ | ‘<b>>></b>’ | ‘<b><<</b>’ | ‘<b>..</b>’ | 11935 1.2 lneto ‘<b><</b>’ | ‘<b><=</b>’ | ‘<b>></b>’ | ‘<b>>=</b>’ | ‘<b>==</b>’ | ‘<b>~=</b>’ | 11936 1.1 mbalmer <b>and</b> | <b>or</b> 11937 1.1 mbalmer 11938 1.2 lneto unop ::= ‘<b>-</b>’ | <b>not</b> | ‘<b>#</b>’ | ‘<b>~</b>’ 11939 1.1 mbalmer 11940 1.1 mbalmer </pre> 11941 1.1 mbalmer 11942 1.1 mbalmer <p> 11943 1.1 mbalmer 11944 1.1 mbalmer 11945 1.1 mbalmer 11946 1.1 mbalmer 11947 1.1 mbalmer 11948 1.1 mbalmer 11949 1.1 mbalmer 11950 1.4 mbalmer <P CLASS="footer"> 11951 1.1 mbalmer Last update: 11952 1.9 nikita Thu Jan 13 11:33:16 UTC 2022 11953 1.4 mbalmer </P> 11954 1.1 mbalmer <!-- 11955 1.9 nikita Last change: revised for Lua 5.4.4 11956 1.1 mbalmer --> 11957 1.1 mbalmer 11958 1.1 mbalmer </body></html> 11959 1.1 mbalmer 11960
Indexes created Mon Apr 27 00:23:16 UTC 2026