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.10 nikita Copyright © 2020–2023 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.10 nikita 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.10 nikita marked by a letter '<code>p</code>' or '<code>P</code>' and written in decimal. 1383 1.10 nikita (For instance, <code>0x1.fp10</code> denotes 1984, 1384 1.10 nikita which is <em>0x1f / 16</em> multiplied by <em>2<sup>10</sup></em>.) 1385 1.9 nikita 1386 1.9 nikita 1387 1.9 nikita <p> 1388 1.7 mbalmer A numeric constant with a radix point or an exponent 1389 1.2 lneto denotes a float; 1390 1.6 salazar otherwise, 1391 1.9 nikita if its value fits in an integer or it is a hexadecimal constant, 1392 1.9 nikita it denotes an integer; 1393 1.9 nikita otherwise (that is, a decimal integer numeral that overflows), 1394 1.9 nikita it denotes a float. 1395 1.9 nikita Hexadecimal numerals with neither a radix point nor an exponent 1396 1.9 nikita always denote an integer value; 1397 1.9 nikita if the value overflows, it <em>wraps around</em> 1398 1.9 nikita to fit into a valid integer. 1399 1.9 nikita 1400 1.9 nikita 1401 1.9 nikita <p> 1402 1.2 lneto Examples of valid integer constants are 1403 1.1 mbalmer 1404 1.1 mbalmer <pre> 1405 1.2 lneto 3 345 0xff 0xBEBADA 1406 1.1 mbalmer </pre><p> 1407 1.2 lneto Examples of valid float constants are 1408 1.1 mbalmer 1409 1.1 mbalmer <pre> 1410 1.2 lneto 3.0 3.1416 314.16e-2 0.31416E1 34e1 1411 1.2 lneto 0x0.1E 0xA23p-4 0X1.921FB54442D18P+1 1412 1.1 mbalmer </pre> 1413 1.1 mbalmer 1414 1.1 mbalmer <p> 1415 1.2 lneto A <em>comment</em> starts with a double hyphen (<code>--</code>) 1416 1.2 lneto anywhere outside a string. 1417 1.2 lneto If the text immediately after <code>--</code> is not an opening long bracket, 1418 1.2 lneto the comment is a <em>short comment</em>, 1419 1.2 lneto which runs until the end of the line. 1420 1.2 lneto Otherwise, it is a <em>long comment</em>, 1421 1.2 lneto which runs until the corresponding closing long bracket. 1422 1.2 lneto 1423 1.1 mbalmer 1424 1.1 mbalmer 1425 1.1 mbalmer 1426 1.1 mbalmer 1427 1.2 lneto <h2>3.2 – <a name="3.2">Variables</a></h2> 1428 1.1 mbalmer 1429 1.2 lneto <p> 1430 1.2 lneto Variables are places that store values. 1431 1.2 lneto There are three kinds of variables in Lua: 1432 1.2 lneto global variables, local variables, and table fields. 1433 1.1 mbalmer 1434 1.1 mbalmer 1435 1.2 lneto <p> 1436 1.2 lneto A single name can denote a global variable or a local variable 1437 1.2 lneto (or a function's formal parameter, 1438 1.2 lneto which is a particular kind of local variable): 1439 1.1 mbalmer 1440 1.1 mbalmer <pre> 1441 1.2 lneto var ::= Name 1442 1.1 mbalmer </pre><p> 1443 1.9 nikita Name denotes identifiers (see <a href="#3.1">§3.1</a>). 1444 1.1 mbalmer 1445 1.1 mbalmer 1446 1.1 mbalmer <p> 1447 1.2 lneto Any variable name is assumed to be global unless explicitly declared 1448 1.2 lneto as a local (see <a href="#3.3.7">§3.3.7</a>). 1449 1.2 lneto Local variables are <em>lexically scoped</em>: 1450 1.2 lneto local variables can be freely accessed by functions 1451 1.2 lneto defined inside their scope (see <a href="#3.5">§3.5</a>). 1452 1.2 lneto 1453 1.1 mbalmer 1454 1.2 lneto <p> 1455 1.2 lneto Before the first assignment to a variable, its value is <b>nil</b>. 1456 1.1 mbalmer 1457 1.1 mbalmer 1458 1.1 mbalmer <p> 1459 1.2 lneto Square brackets are used to index a table: 1460 1.1 mbalmer 1461 1.1 mbalmer <pre> 1462 1.2 lneto var ::= prefixexp ‘<b>[</b>’ exp ‘<b>]</b>’ 1463 1.1 mbalmer </pre><p> 1464 1.8 alnsn The meaning of accesses to table fields can be changed via metatables 1465 1.8 alnsn (see <a href="#2.4">§2.4</a>). 1466 1.1 mbalmer 1467 1.1 mbalmer 1468 1.1 mbalmer <p> 1469 1.2 lneto The syntax <code>var.Name</code> is just syntactic sugar for 1470 1.2 lneto <code>var["Name"]</code>: 1471 1.1 mbalmer 1472 1.1 mbalmer <pre> 1473 1.2 lneto var ::= prefixexp ‘<b>.</b>’ Name 1474 1.2 lneto </pre> 1475 1.1 mbalmer 1476 1.1 mbalmer <p> 1477 1.2 lneto An access to a global variable <code>x</code> 1478 1.2 lneto is equivalent to <code>_ENV.x</code>. 1479 1.2 lneto Due to the way that chunks are compiled, 1480 1.9 nikita the variable <code>_ENV</code> itself is never global (see <a href="#2.2">§2.2</a>). 1481 1.1 mbalmer 1482 1.1 mbalmer 1483 1.1 mbalmer 1484 1.1 mbalmer 1485 1.1 mbalmer 1486 1.2 lneto <h2>3.3 – <a name="3.3">Statements</a></h2> 1487 1.1 mbalmer 1488 1.9 nikita 1489 1.9 nikita 1490 1.1 mbalmer <p> 1491 1.2 lneto Lua supports an almost conventional set of statements, 1492 1.9 nikita similar to those in other conventional languages. 1493 1.2 lneto This set includes 1494 1.9 nikita blocks, assignments, control structures, function calls, 1495 1.2 lneto and variable declarations. 1496 1.2 lneto 1497 1.2 lneto 1498 1.1 mbalmer 1499 1.9 nikita 1500 1.9 nikita 1501 1.2 lneto <h3>3.3.1 – <a name="3.3.1">Blocks</a></h3> 1502 1.1 mbalmer 1503 1.1 mbalmer <p> 1504 1.2 lneto A block is a list of statements, 1505 1.2 lneto which are executed sequentially: 1506 1.1 mbalmer 1507 1.1 mbalmer <pre> 1508 1.2 lneto block ::= {stat} 1509 1.1 mbalmer </pre><p> 1510 1.2 lneto Lua has <em>empty statements</em> 1511 1.2 lneto that allow you to separate statements with semicolons, 1512 1.2 lneto start a block with a semicolon 1513 1.2 lneto or write two semicolons in sequence: 1514 1.1 mbalmer 1515 1.1 mbalmer <pre> 1516 1.2 lneto stat ::= ‘<b>;</b>’ 1517 1.2 lneto </pre> 1518 1.2 lneto 1519 1.2 lneto <p> 1520 1.9 nikita Both function calls and assignments 1521 1.2 lneto can start with an open parenthesis. 1522 1.2 lneto This possibility leads to an ambiguity in Lua's grammar. 1523 1.2 lneto Consider the following fragment: 1524 1.1 mbalmer 1525 1.1 mbalmer <pre> 1526 1.2 lneto a = b + c 1527 1.2 lneto (print or io.write)('done') 1528 1.1 mbalmer </pre><p> 1529 1.9 nikita The grammar could see this fragment in two ways: 1530 1.1 mbalmer 1531 1.1 mbalmer <pre> 1532 1.2 lneto a = b + c(print or io.write)('done') 1533 1.2 lneto 1534 1.2 lneto a = b + c; (print or io.write)('done') 1535 1.1 mbalmer </pre><p> 1536 1.2 lneto The current parser always sees such constructions 1537 1.2 lneto in the first way, 1538 1.2 lneto interpreting the open parenthesis 1539 1.2 lneto as the start of the arguments to a call. 1540 1.2 lneto To avoid this ambiguity, 1541 1.2 lneto it is a good practice to always precede with a semicolon 1542 1.2 lneto statements that start with a parenthesis: 1543 1.1 mbalmer 1544 1.1 mbalmer <pre> 1545 1.2 lneto ;(print or io.write)('done') 1546 1.2 lneto </pre> 1547 1.2 lneto 1548 1.2 lneto <p> 1549 1.2 lneto A block can be explicitly delimited to produce a single statement: 1550 1.1 mbalmer 1551 1.1 mbalmer <pre> 1552 1.2 lneto stat ::= <b>do</b> block <b>end</b> 1553 1.1 mbalmer </pre><p> 1554 1.2 lneto Explicit blocks are useful 1555 1.2 lneto to control the scope of variable declarations. 1556 1.2 lneto Explicit blocks are also sometimes used to 1557 1.2 lneto add a <b>return</b> statement in the middle 1558 1.2 lneto of another block (see <a href="#3.3.4">§3.3.4</a>). 1559 1.2 lneto 1560 1.2 lneto 1561 1.2 lneto 1562 1.2 lneto 1563 1.2 lneto 1564 1.2 lneto <h3>3.3.2 – <a name="3.3.2">Chunks</a></h3> 1565 1.2 lneto 1566 1.2 lneto <p> 1567 1.2 lneto The unit of compilation of Lua is called a <em>chunk</em>. 1568 1.2 lneto Syntactically, 1569 1.2 lneto a chunk is simply a block: 1570 1.1 mbalmer 1571 1.1 mbalmer <pre> 1572 1.2 lneto chunk ::= block 1573 1.2 lneto </pre> 1574 1.1 mbalmer 1575 1.2 lneto <p> 1576 1.2 lneto Lua handles a chunk as the body of an anonymous function 1577 1.2 lneto with a variable number of arguments 1578 1.2 lneto (see <a href="#3.4.11">§3.4.11</a>). 1579 1.2 lneto As such, chunks can define local variables, 1580 1.2 lneto receive arguments, and return values. 1581 1.2 lneto Moreover, such anonymous function is compiled as in the 1582 1.2 lneto scope of an external local variable called <code>_ENV</code> (see <a href="#2.2">§2.2</a>). 1583 1.9 nikita The resulting function always has <code>_ENV</code> as its only external variable, 1584 1.2 lneto even if it does not use that variable. 1585 1.1 mbalmer 1586 1.1 mbalmer 1587 1.1 mbalmer <p> 1588 1.2 lneto A chunk can be stored in a file or in a string inside the host program. 1589 1.2 lneto To execute a chunk, 1590 1.3 lneto Lua first <em>loads</em> it, 1591 1.3 lneto precompiling the chunk's code into instructions for a virtual machine, 1592 1.3 lneto and then Lua executes the compiled code 1593 1.2 lneto with an interpreter for the virtual machine. 1594 1.1 mbalmer 1595 1.1 mbalmer 1596 1.1 mbalmer <p> 1597 1.2 lneto Chunks can also be precompiled into binary form; 1598 1.9 nikita see the program <code>luac</code> and the function <a href="#pdf-string.dump"><code>string.dump</code></a> for details. 1599 1.2 lneto Programs in source and compiled forms are interchangeable; 1600 1.2 lneto Lua automatically detects the file type and acts accordingly (see <a href="#pdf-load"><code>load</code></a>). 1601 1.2 lneto 1602 1.2 lneto 1603 1.2 lneto 1604 1.1 mbalmer 1605 1.1 mbalmer 1606 1.2 lneto <h3>3.3.3 – <a name="3.3.3">Assignment</a></h3> 1607 1.1 mbalmer 1608 1.1 mbalmer <p> 1609 1.2 lneto Lua allows multiple assignments. 1610 1.2 lneto Therefore, the syntax for assignment 1611 1.2 lneto defines a list of variables on the left side 1612 1.2 lneto and a list of expressions on the right side. 1613 1.2 lneto The elements in both lists are separated by commas: 1614 1.1 mbalmer 1615 1.1 mbalmer <pre> 1616 1.2 lneto stat ::= varlist ‘<b>=</b>’ explist 1617 1.2 lneto varlist ::= var {‘<b>,</b>’ var} 1618 1.2 lneto explist ::= exp {‘<b>,</b>’ exp} 1619 1.1 mbalmer </pre><p> 1620 1.2 lneto Expressions are discussed in <a href="#3.4">§3.4</a>. 1621 1.1 mbalmer 1622 1.1 mbalmer 1623 1.1 mbalmer <p> 1624 1.2 lneto Before the assignment, 1625 1.2 lneto the list of values is <em>adjusted</em> to the length of 1626 1.10 nikita the list of variables (see <a href="#3.4.12">§3.4.12</a>). 1627 1.1 mbalmer 1628 1.1 mbalmer 1629 1.1 mbalmer <p> 1630 1.9 nikita If a variable is both assigned and read 1631 1.9 nikita inside a multiple assignment, 1632 1.10 nikita Lua ensures that all reads get the value of the variable 1633 1.9 nikita before the assignment. 1634 1.2 lneto Thus the code 1635 1.1 mbalmer 1636 1.1 mbalmer <pre> 1637 1.2 lneto i = 3 1638 1.2 lneto i, a[i] = i+1, 20 1639 1.1 mbalmer </pre><p> 1640 1.2 lneto sets <code>a[3]</code> to 20, without affecting <code>a[4]</code> 1641 1.2 lneto because the <code>i</code> in <code>a[i]</code> is evaluated (to 3) 1642 1.2 lneto before it is assigned 4. 1643 1.2 lneto Similarly, the line 1644 1.1 mbalmer 1645 1.1 mbalmer <pre> 1646 1.2 lneto x, y = y, x 1647 1.2 lneto </pre><p> 1648 1.2 lneto exchanges the values of <code>x</code> and <code>y</code>, 1649 1.2 lneto and 1650 1.1 mbalmer 1651 1.2 lneto <pre> 1652 1.2 lneto x, y, z = y, z, x 1653 1.2 lneto </pre><p> 1654 1.2 lneto cyclically permutes the values of <code>x</code>, <code>y</code>, and <code>z</code>. 1655 1.1 mbalmer 1656 1.1 mbalmer 1657 1.2 lneto <p> 1658 1.9 nikita Note that this guarantee covers only accesses 1659 1.9 nikita syntactically inside the assignment statement. 1660 1.9 nikita If a function or a metamethod called during the assignment 1661 1.9 nikita changes the value of a variable, 1662 1.9 nikita Lua gives no guarantees about the order of that access. 1663 1.9 nikita 1664 1.9 nikita 1665 1.9 nikita <p> 1666 1.8 alnsn An assignment to a global name <code>x = val</code> 1667 1.8 alnsn is equivalent to the assignment 1668 1.8 alnsn <code>_ENV.x = val</code> (see <a href="#2.2">§2.2</a>). 1669 1.1 mbalmer 1670 1.1 mbalmer 1671 1.2 lneto <p> 1672 1.8 alnsn The meaning of assignments to table fields and 1673 1.8 alnsn global variables (which are actually table fields, too) 1674 1.8 alnsn can be changed via metatables (see <a href="#2.4">§2.4</a>). 1675 1.1 mbalmer 1676 1.1 mbalmer 1677 1.1 mbalmer 1678 1.1 mbalmer 1679 1.1 mbalmer 1680 1.2 lneto <h3>3.3.4 – <a name="3.3.4">Control Structures</a></h3><p> 1681 1.2 lneto The control structures 1682 1.2 lneto <b>if</b>, <b>while</b>, and <b>repeat</b> have the usual meaning and 1683 1.2 lneto familiar syntax: 1684 1.1 mbalmer 1685 1.1 mbalmer 1686 1.1 mbalmer 1687 1.1 mbalmer 1688 1.1 mbalmer <pre> 1689 1.2 lneto stat ::= <b>while</b> exp <b>do</b> block <b>end</b> 1690 1.2 lneto stat ::= <b>repeat</b> block <b>until</b> exp 1691 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> 1692 1.1 mbalmer </pre><p> 1693 1.2 lneto Lua also has a <b>for</b> statement, in two flavors (see <a href="#3.3.5">§3.3.5</a>). 1694 1.1 mbalmer 1695 1.1 mbalmer 1696 1.2 lneto <p> 1697 1.2 lneto The condition expression of a 1698 1.2 lneto control structure can return any value. 1699 1.9 nikita Both <b>false</b> and <b>nil</b> test false. 1700 1.9 nikita All values different from <b>nil</b> and <b>false</b> test true. 1701 1.9 nikita In particular, the number 0 and the empty string also test true. 1702 1.1 mbalmer 1703 1.1 mbalmer 1704 1.1 mbalmer <p> 1705 1.2 lneto In the <b>repeat</b>–<b>until</b> loop, 1706 1.2 lneto the inner block does not end at the <b>until</b> keyword, 1707 1.2 lneto but only after the condition. 1708 1.2 lneto So, the condition can refer to local variables 1709 1.2 lneto declared inside the loop block. 1710 1.1 mbalmer 1711 1.1 mbalmer 1712 1.1 mbalmer <p> 1713 1.2 lneto The <b>goto</b> statement transfers the program control to a label. 1714 1.2 lneto For syntactical reasons, 1715 1.2 lneto labels in Lua are considered statements too: 1716 1.1 mbalmer 1717 1.1 mbalmer 1718 1.1 mbalmer 1719 1.2 lneto <pre> 1720 1.2 lneto stat ::= <b>goto</b> Name 1721 1.2 lneto stat ::= label 1722 1.2 lneto label ::= ‘<b>::</b>’ Name ‘<b>::</b>’ 1723 1.2 lneto </pre> 1724 1.1 mbalmer 1725 1.1 mbalmer <p> 1726 1.2 lneto A label is visible in the entire block where it is defined, 1727 1.9 nikita except inside nested functions. 1728 1.2 lneto A goto may jump to any visible label as long as it does not 1729 1.2 lneto enter into the scope of a local variable. 1730 1.9 nikita A label should not be declared 1731 1.9 nikita where a label with the same name is visible, 1732 1.9 nikita even if this other label has been declared in an enclosing block. 1733 1.1 mbalmer 1734 1.1 mbalmer 1735 1.1 mbalmer <p> 1736 1.2 lneto The <b>break</b> statement terminates the execution of a 1737 1.2 lneto <b>while</b>, <b>repeat</b>, or <b>for</b> loop, 1738 1.2 lneto skipping to the next statement after the loop: 1739 1.1 mbalmer 1740 1.1 mbalmer 1741 1.2 lneto <pre> 1742 1.2 lneto stat ::= <b>break</b> 1743 1.2 lneto </pre><p> 1744 1.2 lneto A <b>break</b> ends the innermost enclosing loop. 1745 1.1 mbalmer 1746 1.1 mbalmer 1747 1.1 mbalmer <p> 1748 1.2 lneto The <b>return</b> statement is used to return values 1749 1.3 lneto from a function or a chunk 1750 1.9 nikita (which is handled as an anonymous function). 1751 1.1 mbalmer 1752 1.2 lneto Functions can return more than one value, 1753 1.2 lneto so the syntax for the <b>return</b> statement is 1754 1.1 mbalmer 1755 1.2 lneto <pre> 1756 1.2 lneto stat ::= <b>return</b> [explist] [‘<b>;</b>’] 1757 1.2 lneto </pre> 1758 1.1 mbalmer 1759 1.1 mbalmer <p> 1760 1.2 lneto The <b>return</b> statement can only be written 1761 1.2 lneto as the last statement of a block. 1762 1.9 nikita If it is necessary to <b>return</b> in the middle of a block, 1763 1.2 lneto then an explicit inner block can be used, 1764 1.2 lneto as in the idiom <code>do return end</code>, 1765 1.2 lneto because now <b>return</b> is the last statement in its (inner) block. 1766 1.1 mbalmer 1767 1.1 mbalmer 1768 1.1 mbalmer 1769 1.1 mbalmer 1770 1.1 mbalmer 1771 1.2 lneto <h3>3.3.5 – <a name="3.3.5">For Statement</a></h3> 1772 1.1 mbalmer 1773 1.2 lneto <p> 1774 1.1 mbalmer 1775 1.2 lneto The <b>for</b> statement has two forms: 1776 1.4 mbalmer one numerical and one generic. 1777 1.1 mbalmer 1778 1.1 mbalmer 1779 1.9 nikita 1780 1.9 nikita <h4>The numerical <b>for</b> loop</h4> 1781 1.9 nikita 1782 1.2 lneto <p> 1783 1.4 mbalmer The numerical <b>for</b> loop repeats a block of code while a 1784 1.9 nikita control variable goes through an arithmetic progression. 1785 1.2 lneto It has the following syntax: 1786 1.1 mbalmer 1787 1.2 lneto <pre> 1788 1.2 lneto stat ::= <b>for</b> Name ‘<b>=</b>’ exp ‘<b>,</b>’ exp [‘<b>,</b>’ exp] <b>do</b> block <b>end</b> 1789 1.2 lneto </pre><p> 1790 1.9 nikita The given identifier (Name) defines the control variable, 1791 1.9 nikita which is a new variable local to the loop body (<em>block</em>). 1792 1.1 mbalmer 1793 1.1 mbalmer 1794 1.9 nikita <p> 1795 1.9 nikita The loop starts by evaluating once the three control expressions. 1796 1.9 nikita Their values are called respectively 1797 1.9 nikita the <em>initial value</em>, the <em>limit</em>, and the <em>step</em>. 1798 1.9 nikita If the step is absent, it defaults to 1. 1799 1.9 nikita 1800 1.2 lneto 1801 1.2 lneto <p> 1802 1.9 nikita If both the initial value and the step are integers, 1803 1.9 nikita the loop is done with integers; 1804 1.9 nikita note that the limit may not be an integer. 1805 1.9 nikita Otherwise, the three values are converted to 1806 1.9 nikita floats and the loop is done with floats. 1807 1.9 nikita Beware of floating-point accuracy in this case. 1808 1.1 mbalmer 1809 1.1 mbalmer 1810 1.9 nikita <p> 1811 1.9 nikita After that initialization, 1812 1.9 nikita the loop body is repeated with the value of the control variable 1813 1.9 nikita going through an arithmetic progression, 1814 1.9 nikita starting at the initial value, 1815 1.9 nikita with a common difference given by the step. 1816 1.9 nikita A negative step makes a decreasing sequence; 1817 1.9 nikita a step equal to zero raises an error. 1818 1.9 nikita The loop continues while the value is less than 1819 1.9 nikita or equal to the limit 1820 1.9 nikita (greater than or equal to for a negative step). 1821 1.9 nikita If the initial value is already greater than the limit 1822 1.9 nikita (or less than, if the step is negative), 1823 1.9 nikita the body is not executed. 1824 1.1 mbalmer 1825 1.1 mbalmer 1826 1.9 nikita <p> 1827 1.9 nikita For integer loops, 1828 1.9 nikita the control variable never wraps around; 1829 1.9 nikita instead, the loop ends in case of an overflow. 1830 1.1 mbalmer 1831 1.1 mbalmer 1832 1.9 nikita <p> 1833 1.9 nikita You should not change the value of the control variable 1834 1.9 nikita during the loop. 1835 1.2 lneto If you need its value after the loop, 1836 1.2 lneto assign it to another variable before exiting the loop. 1837 1.1 mbalmer 1838 1.9 nikita 1839 1.9 nikita 1840 1.9 nikita 1841 1.9 nikita 1842 1.9 nikita <h4>The generic <b>for</b> loop</h4> 1843 1.1 mbalmer 1844 1.2 lneto <p> 1845 1.2 lneto The generic <b>for</b> statement works over functions, 1846 1.2 lneto called <em>iterators</em>. 1847 1.2 lneto On each iteration, the iterator function is called to produce a new value, 1848 1.2 lneto stopping when this new value is <b>nil</b>. 1849 1.2 lneto The generic <b>for</b> loop has the following syntax: 1850 1.1 mbalmer 1851 1.2 lneto <pre> 1852 1.2 lneto stat ::= <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> 1853 1.2 lneto namelist ::= Name {‘<b>,</b>’ Name} 1854 1.2 lneto </pre><p> 1855 1.2 lneto A <b>for</b> statement like 1856 1.1 mbalmer 1857 1.2 lneto <pre> 1858 1.9 nikita for <em>var_1</em>, ···, <em>var_n</em> in <em>explist</em> do <em>body</em> end 1859 1.2 lneto </pre><p> 1860 1.9 nikita works as follows. 1861 1.9 nikita 1862 1.1 mbalmer 1863 1.9 nikita <p> 1864 1.9 nikita The names <em>var_i</em> declare loop variables local to the loop body. 1865 1.9 nikita The first of these variables is the <em>control variable</em>. 1866 1.2 lneto 1867 1.2 lneto 1868 1.9 nikita <p> 1869 1.9 nikita The loop starts by evaluating <em>explist</em> 1870 1.9 nikita to produce four values: 1871 1.9 nikita an <em>iterator function</em>, 1872 1.2 lneto a <em>state</em>, 1873 1.9 nikita an initial value for the control variable, 1874 1.9 nikita and a <em>closing value</em>. 1875 1.9 nikita 1876 1.9 nikita 1877 1.9 nikita <p> 1878 1.9 nikita Then, at each iteration, 1879 1.9 nikita Lua calls the iterator function with two arguments: 1880 1.9 nikita the state and the control variable. 1881 1.9 nikita The results from this call are then assigned to the loop variables, 1882 1.9 nikita following the rules of multiple assignments (see <a href="#3.3.3">§3.3.3</a>). 1883 1.9 nikita If the control variable becomes <b>nil</b>, 1884 1.9 nikita the loop terminates. 1885 1.9 nikita Otherwise, the body is executed and the loop goes 1886 1.9 nikita to the next iteration. 1887 1.9 nikita 1888 1.9 nikita 1889 1.9 nikita <p> 1890 1.9 nikita The closing value behaves like a 1891 1.9 nikita to-be-closed variable (see <a href="#3.3.8">§3.3.8</a>), 1892 1.9 nikita which can be used to release resources when the loop ends. 1893 1.9 nikita Otherwise, it does not interfere with the loop. 1894 1.9 nikita 1895 1.1 mbalmer 1896 1.9 nikita <p> 1897 1.9 nikita You should not change the value of the control variable 1898 1.9 nikita during the loop. 1899 1.1 mbalmer 1900 1.1 mbalmer 1901 1.1 mbalmer 1902 1.2 lneto 1903 1.2 lneto 1904 1.1 mbalmer 1905 1.1 mbalmer 1906 1.2 lneto <h3>3.3.6 – <a name="3.3.6">Function Calls as Statements</a></h3><p> 1907 1.2 lneto To allow possible side-effects, 1908 1.2 lneto function calls can be executed as statements: 1909 1.2 lneto 1910 1.1 mbalmer <pre> 1911 1.2 lneto stat ::= functioncall 1912 1.1 mbalmer </pre><p> 1913 1.2 lneto In this case, all returned values are thrown away. 1914 1.2 lneto Function calls are explained in <a href="#3.4.10">§3.4.10</a>. 1915 1.2 lneto 1916 1.2 lneto 1917 1.2 lneto 1918 1.1 mbalmer 1919 1.1 mbalmer 1920 1.2 lneto <h3>3.3.7 – <a name="3.3.7">Local Declarations</a></h3><p> 1921 1.2 lneto Local variables can be declared anywhere inside a block. 1922 1.9 nikita The declaration can include an initialization: 1923 1.1 mbalmer 1924 1.1 mbalmer <pre> 1925 1.9 nikita stat ::= <b>local</b> attnamelist [‘<b>=</b>’ explist] 1926 1.9 nikita attnamelist ::= Name attrib {‘<b>,</b>’ Name attrib} 1927 1.1 mbalmer </pre><p> 1928 1.2 lneto If present, an initial assignment has the same semantics 1929 1.2 lneto of a multiple assignment (see <a href="#3.3.3">§3.3.3</a>). 1930 1.2 lneto Otherwise, all variables are initialized with <b>nil</b>. 1931 1.2 lneto 1932 1.2 lneto 1933 1.2 lneto <p> 1934 1.9 nikita Each variable name may be postfixed by an attribute 1935 1.9 nikita (a name between angle brackets): 1936 1.9 nikita 1937 1.9 nikita <pre> 1938 1.9 nikita attrib ::= [‘<b><</b>’ Name ‘<b>></b>’] 1939 1.9 nikita </pre><p> 1940 1.9 nikita There are two possible attributes: 1941 1.9 nikita <code>const</code>, which declares a constant variable, 1942 1.9 nikita that is, a variable that cannot be assigned to 1943 1.9 nikita after its initialization; 1944 1.9 nikita and <code>close</code>, which declares a to-be-closed variable (see <a href="#3.3.8">§3.3.8</a>). 1945 1.9 nikita A list of variables can contain at most one to-be-closed variable. 1946 1.9 nikita 1947 1.9 nikita 1948 1.9 nikita <p> 1949 1.2 lneto A chunk is also a block (see <a href="#3.3.2">§3.3.2</a>), 1950 1.2 lneto and so local variables can be declared in a chunk outside any explicit block. 1951 1.1 mbalmer 1952 1.1 mbalmer 1953 1.2 lneto <p> 1954 1.2 lneto The visibility rules for local variables are explained in <a href="#3.5">§3.5</a>. 1955 1.2 lneto 1956 1.1 mbalmer 1957 1.1 mbalmer 1958 1.1 mbalmer 1959 1.1 mbalmer 1960 1.9 nikita <h3>3.3.8 – <a name="3.3.8">To-be-closed Variables</a></h3> 1961 1.9 nikita 1962 1.9 nikita <p> 1963 1.9 nikita A to-be-closed variable behaves like a constant local variable, 1964 1.9 nikita except that its value is <em>closed</em> whenever the variable 1965 1.9 nikita goes out of scope, including normal block termination, 1966 1.9 nikita exiting its block by <b>break</b>/<b>goto</b>/<b>return</b>, 1967 1.9 nikita or exiting by an error. 1968 1.9 nikita 1969 1.9 nikita 1970 1.9 nikita <p> 1971 1.9 nikita Here, to <em>close</em> a value means 1972 1.9 nikita to call its <code>__close</code> metamethod. 1973 1.9 nikita When calling the metamethod, 1974 1.9 nikita the value itself is passed as the first argument 1975 1.9 nikita and the error object that caused the exit (if any) 1976 1.9 nikita is passed as a second argument; 1977 1.9 nikita if there was no error, the second argument is <b>nil</b>. 1978 1.9 nikita 1979 1.9 nikita 1980 1.9 nikita <p> 1981 1.9 nikita The value assigned to a to-be-closed variable 1982 1.9 nikita must have a <code>__close</code> metamethod 1983 1.9 nikita or be a false value. 1984 1.9 nikita (<b>nil</b> and <b>false</b> are ignored as to-be-closed values.) 1985 1.9 nikita 1986 1.9 nikita 1987 1.9 nikita <p> 1988 1.9 nikita If several to-be-closed variables go out of scope at the same event, 1989 1.9 nikita they are closed in the reverse order that they were declared. 1990 1.9 nikita 1991 1.9 nikita 1992 1.9 nikita <p> 1993 1.9 nikita If there is any error while running a closing method, 1994 1.9 nikita that error is handled like an error in the regular code 1995 1.9 nikita where the variable was defined. 1996 1.9 nikita After an error, 1997 1.9 nikita the other pending closing methods will still be called. 1998 1.9 nikita 1999 1.9 nikita 2000 1.9 nikita <p> 2001 1.9 nikita If a coroutine yields and is never resumed again, 2002 1.9 nikita some variables may never go out of scope, 2003 1.9 nikita and therefore they will never be closed. 2004 1.9 nikita (These variables are the ones created inside the coroutine 2005 1.9 nikita and in scope at the point where the coroutine yielded.) 2006 1.9 nikita Similarly, if a coroutine ends with an error, 2007 1.9 nikita it does not unwind its stack, 2008 1.9 nikita so it does not close any variable. 2009 1.9 nikita In both cases, 2010 1.9 nikita you can either use finalizers 2011 1.9 nikita or call <a href="#pdf-coroutine.close"><code>coroutine.close</code></a> to close the variables. 2012 1.9 nikita However, if the coroutine was created 2013 1.9 nikita through <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a>, 2014 1.9 nikita then its corresponding function will close the coroutine 2015 1.9 nikita in case of errors. 2016 1.9 nikita 2017 1.9 nikita 2018 1.9 nikita 2019 1.9 nikita 2020 1.9 nikita 2021 1.1 mbalmer 2022 1.1 mbalmer 2023 1.2 lneto <h2>3.4 – <a name="3.4">Expressions</a></h2> 2024 1.1 mbalmer 2025 1.9 nikita 2026 1.9 nikita 2027 1.2 lneto <p> 2028 1.2 lneto The basic expressions in Lua are the following: 2029 1.1 mbalmer 2030 1.1 mbalmer <pre> 2031 1.2 lneto exp ::= prefixexp 2032 1.2 lneto exp ::= <b>nil</b> | <b>false</b> | <b>true</b> 2033 1.3 lneto exp ::= Numeral 2034 1.3 lneto exp ::= LiteralString 2035 1.2 lneto exp ::= functiondef 2036 1.2 lneto exp ::= tableconstructor 2037 1.2 lneto exp ::= ‘<b>...</b>’ 2038 1.2 lneto exp ::= exp binop exp 2039 1.2 lneto exp ::= unop exp 2040 1.2 lneto prefixexp ::= var | functioncall | ‘<b>(</b>’ exp ‘<b>)</b>’ 2041 1.2 lneto </pre> 2042 1.2 lneto 2043 1.2 lneto <p> 2044 1.3 lneto Numerals and literal strings are explained in <a href="#3.1">§3.1</a>; 2045 1.2 lneto variables are explained in <a href="#3.2">§3.2</a>; 2046 1.2 lneto function definitions are explained in <a href="#3.4.11">§3.4.11</a>; 2047 1.2 lneto function calls are explained in <a href="#3.4.10">§3.4.10</a>; 2048 1.2 lneto table constructors are explained in <a href="#3.4.9">§3.4.9</a>. 2049 1.2 lneto Vararg expressions, 2050 1.2 lneto denoted by three dots ('<code>...</code>'), can only be used when 2051 1.10 nikita directly inside a variadic function; 2052 1.2 lneto they are explained in <a href="#3.4.11">§3.4.11</a>. 2053 1.2 lneto 2054 1.1 mbalmer 2055 1.2 lneto <p> 2056 1.2 lneto Binary operators comprise arithmetic operators (see <a href="#3.4.1">§3.4.1</a>), 2057 1.2 lneto bitwise operators (see <a href="#3.4.2">§3.4.2</a>), 2058 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>), 2059 1.2 lneto and the concatenation operator (see <a href="#3.4.6">§3.4.6</a>). 2060 1.2 lneto Unary operators comprise the unary minus (see <a href="#3.4.1">§3.4.1</a>), 2061 1.6 salazar the unary bitwise NOT (see <a href="#3.4.2">§3.4.2</a>), 2062 1.3 lneto the unary logical <b>not</b> (see <a href="#3.4.5">§3.4.5</a>), 2063 1.2 lneto and the unary <em>length operator</em> (see <a href="#3.4.7">§3.4.7</a>). 2064 1.1 mbalmer 2065 1.1 mbalmer 2066 1.1 mbalmer 2067 1.9 nikita 2068 1.9 nikita 2069 1.2 lneto <h3>3.4.1 – <a name="3.4.1">Arithmetic Operators</a></h3><p> 2070 1.2 lneto Lua supports the following arithmetic operators: 2071 1.1 mbalmer 2072 1.3 lneto <ul> 2073 1.3 lneto <li><b><code>+</code>: </b>addition</li> 2074 1.3 lneto <li><b><code>-</code>: </b>subtraction</li> 2075 1.3 lneto <li><b><code>*</code>: </b>multiplication</li> 2076 1.3 lneto <li><b><code>/</code>: </b>float division</li> 2077 1.3 lneto <li><b><code>//</code>: </b>floor division</li> 2078 1.3 lneto <li><b><code>%</code>: </b>modulo</li> 2079 1.3 lneto <li><b><code>^</code>: </b>exponentiation</li> 2080 1.3 lneto <li><b><code>-</code>: </b>unary minus</li> 2081 1.3 lneto </ul> 2082 1.1 mbalmer 2083 1.2 lneto <p> 2084 1.3 lneto With the exception of exponentiation and float division, 2085 1.2 lneto the arithmetic operators work as follows: 2086 1.2 lneto If both operands are integers, 2087 1.2 lneto the operation is performed over integers and the result is an integer. 2088 1.9 nikita Otherwise, if both operands are numbers, 2089 1.2 lneto then they are converted to floats, 2090 1.9 nikita the operation is performed following the machine's rules 2091 1.2 lneto for floating-point arithmetic 2092 1.2 lneto (usually the IEEE 754 standard), 2093 1.2 lneto and the result is a float. 2094 1.9 nikita (The string library coerces strings to numbers in 2095 1.9 nikita arithmetic operations; see <a href="#3.4.3">§3.4.3</a> for details.) 2096 1.1 mbalmer 2097 1.1 mbalmer 2098 1.1 mbalmer <p> 2099 1.3 lneto Exponentiation and float division (<code>/</code>) 2100 1.2 lneto always convert their operands to floats 2101 1.2 lneto and the result is always a float. 2102 1.3 lneto Exponentiation uses the ISO C function <code>pow</code>, 2103 1.2 lneto so that it works for non-integer exponents too. 2104 1.1 mbalmer 2105 1.1 mbalmer 2106 1.1 mbalmer <p> 2107 1.7 mbalmer Floor division (<code>//</code>) is a division 2108 1.4 mbalmer that rounds the quotient towards minus infinity, 2109 1.9 nikita resulting in the floor of the division of its operands. 2110 1.1 mbalmer 2111 1.1 mbalmer 2112 1.1 mbalmer <p> 2113 1.2 lneto Modulo is defined as the remainder of a division 2114 1.4 mbalmer that rounds the quotient towards minus infinity (floor division). 2115 1.1 mbalmer 2116 1.1 mbalmer 2117 1.1 mbalmer <p> 2118 1.2 lneto In case of overflows in integer arithmetic, 2119 1.9 nikita all operations <em>wrap around</em>. 2120 1.2 lneto 2121 1.2 lneto 2122 1.2 lneto 2123 1.2 lneto <h3>3.4.2 – <a name="3.4.2">Bitwise Operators</a></h3><p> 2124 1.2 lneto Lua supports the following bitwise operators: 2125 1.1 mbalmer 2126 1.3 lneto <ul> 2127 1.6 salazar <li><b><code>&</code>: </b>bitwise AND</li> 2128 1.6 salazar <li><b><code>|</code>: </b>bitwise OR</li> 2129 1.6 salazar <li><b><code>~</code>: </b>bitwise exclusive OR</li> 2130 1.3 lneto <li><b><code>>></code>: </b>right shift</li> 2131 1.3 lneto <li><b><code><<</code>: </b>left shift</li> 2132 1.6 salazar <li><b><code>~</code>: </b>unary bitwise NOT</li> 2133 1.3 lneto </ul> 2134 1.1 mbalmer 2135 1.1 mbalmer <p> 2136 1.2 lneto All bitwise operations convert its operands to integers 2137 1.2 lneto (see <a href="#3.4.3">§3.4.3</a>), 2138 1.2 lneto operate on all bits of those integers, 2139 1.2 lneto and result in an integer. 2140 1.1 mbalmer 2141 1.1 mbalmer 2142 1.1 mbalmer <p> 2143 1.2 lneto Both right and left shifts fill the vacant bits with zeros. 2144 1.2 lneto Negative displacements shift to the other direction; 2145 1.2 lneto displacements with absolute values equal to or higher than 2146 1.2 lneto the number of bits in an integer 2147 1.3 lneto result in zero (as all bits are shifted out). 2148 1.2 lneto 2149 1.2 lneto 2150 1.2 lneto 2151 1.2 lneto 2152 1.2 lneto 2153 1.2 lneto <h3>3.4.3 – <a name="3.4.3">Coercions and Conversions</a></h3><p> 2154 1.2 lneto Lua provides some automatic conversions between some 2155 1.2 lneto types and representations at run time. 2156 1.3 lneto Bitwise operators always convert float operands to integers. 2157 1.3 lneto Exponentiation and float division 2158 1.3 lneto always convert integer operands to floats. 2159 1.3 lneto All other arithmetic operations applied to mixed numbers 2160 1.9 nikita (integers and floats) convert the integer operand to a float. 2161 1.2 lneto The C API also converts both integers to floats and 2162 1.2 lneto floats to integers, as needed. 2163 1.2 lneto Moreover, string concatenation accepts numbers as arguments, 2164 1.7 mbalmer besides strings. 2165 1.1 mbalmer 2166 1.1 mbalmer 2167 1.1 mbalmer <p> 2168 1.2 lneto In a conversion from integer to float, 2169 1.2 lneto if the integer value has an exact representation as a float, 2170 1.2 lneto that is the result. 2171 1.2 lneto Otherwise, 2172 1.3 lneto the conversion gets the nearest higher or 2173 1.3 lneto the nearest lower representable value. 2174 1.2 lneto This kind of conversion never fails. 2175 1.1 mbalmer 2176 1.1 mbalmer 2177 1.2 lneto <p> 2178 1.2 lneto The conversion from float to integer 2179 1.3 lneto checks whether the float has an exact representation as an integer 2180 1.3 lneto (that is, the float has an integral value and 2181 1.3 lneto it is in the range of integer representation). 2182 1.3 lneto If it does, that representation is the result. 2183 1.2 lneto Otherwise, the conversion fails. 2184 1.1 mbalmer 2185 1.1 mbalmer 2186 1.1 mbalmer <p> 2187 1.9 nikita Several places in Lua coerce strings to numbers when necessary. 2188 1.9 nikita In particular, 2189 1.9 nikita the string library sets metamethods that try to coerce 2190 1.9 nikita strings to numbers in all arithmetic operations. 2191 1.9 nikita If the conversion fails, 2192 1.9 nikita the library calls the metamethod of the other operand 2193 1.9 nikita (if present) or it raises an error. 2194 1.9 nikita Note that bitwise operators do not do this coercion. 2195 1.9 nikita 2196 1.9 nikita 2197 1.9 nikita <p> 2198 1.10 nikita It is always a good practice not to rely on the 2199 1.10 nikita implicit coercions from strings to numbers, 2200 1.10 nikita as they are not always applied; 2201 1.9 nikita in particular, <code>"1"==1</code> is false and <code>"1"<1</code> raises an error 2202 1.9 nikita (see <a href="#3.4.4">§3.4.4</a>). 2203 1.9 nikita These coercions exist mainly for compatibility and may be removed 2204 1.9 nikita in future versions of the language. 2205 1.1 mbalmer 2206 1.1 mbalmer 2207 1.1 mbalmer <p> 2208 1.9 nikita A string is converted to an integer or a float 2209 1.9 nikita following its syntax and the rules of the Lua lexer. 2210 1.9 nikita The string may have also leading and trailing whitespaces and a sign. 2211 1.7 mbalmer All conversions from strings to numbers 2212 1.6 salazar accept both a dot and the current locale mark 2213 1.6 salazar as the radix character. 2214 1.6 salazar (The Lua lexer, however, accepts only a dot.) 2215 1.9 nikita If the string is not a valid numeral, 2216 1.9 nikita the conversion fails. 2217 1.9 nikita If necessary, the result of this first step is then converted 2218 1.9 nikita to a specific number subtype following the previous rules 2219 1.9 nikita for conversions between floats and integers. 2220 1.6 salazar 2221 1.6 salazar 2222 1.6 salazar <p> 2223 1.3 lneto The conversion from numbers to strings uses a 2224 1.3 lneto non-specified human-readable format. 2225 1.9 nikita To convert numbers to strings in any specific way, 2226 1.9 nikita use the function <a href="#pdf-string.format"><code>string.format</code></a>. 2227 1.2 lneto 2228 1.2 lneto 2229 1.2 lneto 2230 1.2 lneto 2231 1.2 lneto 2232 1.2 lneto <h3>3.4.4 – <a name="3.4.4">Relational Operators</a></h3><p> 2233 1.2 lneto Lua supports the following relational operators: 2234 1.3 lneto 2235 1.3 lneto <ul> 2236 1.3 lneto <li><b><code>==</code>: </b>equality</li> 2237 1.3 lneto <li><b><code>~=</code>: </b>inequality</li> 2238 1.3 lneto <li><b><code><</code>: </b>less than</li> 2239 1.3 lneto <li><b><code>></code>: </b>greater than</li> 2240 1.3 lneto <li><b><code><=</code>: </b>less or equal</li> 2241 1.3 lneto <li><b><code>>=</code>: </b>greater or equal</li> 2242 1.3 lneto </ul><p> 2243 1.2 lneto These operators always result in <b>false</b> or <b>true</b>. 2244 1.1 mbalmer 2245 1.1 mbalmer 2246 1.1 mbalmer <p> 2247 1.2 lneto Equality (<code>==</code>) first compares the type of its operands. 2248 1.2 lneto If the types are different, then the result is <b>false</b>. 2249 1.2 lneto Otherwise, the values of the operands are compared. 2250 1.9 nikita Strings are equal if they have the same byte content. 2251 1.4 mbalmer Numbers are equal if they denote the same mathematical value. 2252 1.1 mbalmer 2253 1.1 mbalmer 2254 1.1 mbalmer <p> 2255 1.2 lneto Tables, userdata, and threads 2256 1.2 lneto are compared by reference: 2257 1.2 lneto two objects are considered equal only if they are the same object. 2258 1.2 lneto Every time you create a new object 2259 1.9 nikita (a table, a userdata, or a thread), 2260 1.2 lneto this new object is different from any previously existing object. 2261 1.9 nikita A function is always equal to itself. 2262 1.9 nikita Functions with any detectable difference 2263 1.2 lneto (different behavior, different definition) are always different. 2264 1.9 nikita Functions created at different times but with no detectable differences 2265 1.8 alnsn may be classified as equal or not 2266 1.8 alnsn (depending on internal caching details). 2267 1.1 mbalmer 2268 1.1 mbalmer 2269 1.1 mbalmer <p> 2270 1.2 lneto You can change the way that Lua compares tables and userdata 2271 1.9 nikita by using the <code>__eq</code> metamethod (see <a href="#2.4">§2.4</a>). 2272 1.1 mbalmer 2273 1.1 mbalmer 2274 1.2 lneto <p> 2275 1.3 lneto Equality comparisons do not convert strings to numbers 2276 1.2 lneto or vice versa. 2277 1.2 lneto Thus, <code>"0"==0</code> evaluates to <b>false</b>, 2278 1.2 lneto and <code>t[0]</code> and <code>t["0"]</code> denote different 2279 1.2 lneto entries in a table. 2280 1.1 mbalmer 2281 1.1 mbalmer 2282 1.1 mbalmer <p> 2283 1.2 lneto The operator <code>~=</code> is exactly the negation of equality (<code>==</code>). 2284 1.1 mbalmer 2285 1.1 mbalmer 2286 1.2 lneto <p> 2287 1.2 lneto The order operators work as follows. 2288 1.2 lneto If both arguments are numbers, 2289 1.9 nikita then they are compared according to their mathematical values, 2290 1.9 nikita regardless of their subtypes. 2291 1.2 lneto Otherwise, if both arguments are strings, 2292 1.2 lneto then their values are compared according to the current locale. 2293 1.9 nikita Otherwise, Lua tries to call the <code>__lt</code> or the <code>__le</code> 2294 1.2 lneto metamethod (see <a href="#2.4">§2.4</a>). 2295 1.2 lneto A comparison <code>a > b</code> is translated to <code>b < a</code> 2296 1.2 lneto and <code>a >= b</code> is translated to <code>b <= a</code>. 2297 1.2 lneto 2298 1.2 lneto 2299 1.4 mbalmer <p> 2300 1.4 mbalmer Following the IEEE 754 standard, 2301 1.9 nikita the special value NaN is considered neither less than, 2302 1.9 nikita nor equal to, nor greater than any value, including itself. 2303 1.4 mbalmer 2304 1.4 mbalmer 2305 1.2 lneto 2306 1.2 lneto 2307 1.2 lneto 2308 1.2 lneto <h3>3.4.5 – <a name="3.4.5">Logical Operators</a></h3><p> 2309 1.2 lneto The logical operators in Lua are 2310 1.2 lneto <b>and</b>, <b>or</b>, and <b>not</b>. 2311 1.2 lneto Like the control structures (see <a href="#3.3.4">§3.3.4</a>), 2312 1.2 lneto all logical operators consider both <b>false</b> and <b>nil</b> as false 2313 1.2 lneto and anything else as true. 2314 1.2 lneto 2315 1.2 lneto 2316 1.2 lneto <p> 2317 1.2 lneto The negation operator <b>not</b> always returns <b>false</b> or <b>true</b>. 2318 1.2 lneto The conjunction operator <b>and</b> returns its first argument 2319 1.2 lneto if this value is <b>false</b> or <b>nil</b>; 2320 1.2 lneto otherwise, <b>and</b> returns its second argument. 2321 1.2 lneto The disjunction operator <b>or</b> returns its first argument 2322 1.2 lneto if this value is different from <b>nil</b> and <b>false</b>; 2323 1.2 lneto otherwise, <b>or</b> returns its second argument. 2324 1.2 lneto Both <b>and</b> and <b>or</b> use short-circuit evaluation; 2325 1.2 lneto that is, 2326 1.2 lneto the second operand is evaluated only if necessary. 2327 1.2 lneto Here are some examples: 2328 1.2 lneto 2329 1.2 lneto <pre> 2330 1.2 lneto 10 or 20 --> 10 2331 1.2 lneto 10 or error() --> 10 2332 1.2 lneto nil or "a" --> "a" 2333 1.2 lneto nil and 10 --> nil 2334 1.2 lneto false and error() --> false 2335 1.2 lneto false and nil --> false 2336 1.2 lneto false or nil --> nil 2337 1.2 lneto 10 and 20 --> 20 2338 1.9 nikita </pre> 2339 1.2 lneto 2340 1.2 lneto 2341 1.2 lneto 2342 1.2 lneto 2343 1.2 lneto <h3>3.4.6 – <a name="3.4.6">Concatenation</a></h3><p> 2344 1.2 lneto The string concatenation operator in Lua is 2345 1.2 lneto denoted by two dots ('<code>..</code>'). 2346 1.9 nikita If both operands are strings or numbers, 2347 1.9 nikita then the numbers are converted to strings 2348 1.9 nikita in a non-specified format (see <a href="#3.4.3">§3.4.3</a>). 2349 1.2 lneto Otherwise, the <code>__concat</code> metamethod is called (see <a href="#2.4">§2.4</a>). 2350 1.2 lneto 2351 1.2 lneto 2352 1.2 lneto 2353 1.2 lneto 2354 1.2 lneto 2355 1.2 lneto <h3>3.4.7 – <a name="3.4.7">The Length Operator</a></h3> 2356 1.2 lneto 2357 1.2 lneto <p> 2358 1.2 lneto The length operator is denoted by the unary prefix operator <code>#</code>. 2359 1.7 mbalmer 2360 1.7 mbalmer 2361 1.7 mbalmer <p> 2362 1.9 nikita The length of a string is its number of bytes. 2363 1.9 nikita (That is the usual meaning of string length when each 2364 1.9 nikita character is one byte.) 2365 1.2 lneto 2366 1.2 lneto 2367 1.2 lneto <p> 2368 1.7 mbalmer The length operator applied on a table 2369 1.7 mbalmer returns a border in that table. 2370 1.9 nikita A <em>border</em> in a table <code>t</code> is any non-negative integer 2371 1.7 mbalmer that satisfies the following condition: 2372 1.7 mbalmer 2373 1.7 mbalmer <pre> 2374 1.9 nikita (border == 0 or t[border] ~= nil) and 2375 1.9 nikita (t[border + 1] == nil or border == math.maxinteger) 2376 1.7 mbalmer </pre><p> 2377 1.7 mbalmer In words, 2378 1.9 nikita a border is any positive integer index present in the table 2379 1.9 nikita that is followed by an absent index, 2380 1.9 nikita plus two limit cases: 2381 1.9 nikita zero, when index 1 is absent; 2382 1.9 nikita and the maximum value for an integer, when that index is present. 2383 1.9 nikita Note that keys that are not positive integers 2384 1.9 nikita do not interfere with borders. 2385 1.7 mbalmer 2386 1.7 mbalmer 2387 1.7 mbalmer <p> 2388 1.7 mbalmer A table with exactly one border is called a <em>sequence</em>. 2389 1.7 mbalmer For instance, the table <code>{10, 20, 30, 40, 50}</code> is a sequence, 2390 1.7 mbalmer as it has only one border (5). 2391 1.7 mbalmer The table <code>{10, 20, 30, nil, 50}</code> has two borders (3 and 5), 2392 1.7 mbalmer and therefore it is not a sequence. 2393 1.9 nikita (The <b>nil</b> at index 4 is called a <em>hole</em>.) 2394 1.7 mbalmer The table <code>{nil, 20, 30, nil, nil, 60, nil}</code> 2395 1.7 mbalmer has three borders (0, 3, and 6), 2396 1.7 mbalmer so it is not a sequence, too. 2397 1.7 mbalmer The table <code>{}</code> is a sequence with border 0. 2398 1.7 mbalmer 2399 1.7 mbalmer 2400 1.7 mbalmer <p> 2401 1.7 mbalmer When <code>t</code> is a sequence, 2402 1.7 mbalmer <code>#t</code> returns its only border, 2403 1.7 mbalmer which corresponds to the intuitive notion of the length of the sequence. 2404 1.7 mbalmer When <code>t</code> is not a sequence, 2405 1.7 mbalmer <code>#t</code> can return any of its borders. 2406 1.7 mbalmer (The exact one depends on details of 2407 1.7 mbalmer the internal representation of the table, 2408 1.7 mbalmer which in turn can depend on how the table was populated and 2409 1.7 mbalmer the memory addresses of its non-numeric keys.) 2410 1.2 lneto 2411 1.2 lneto 2412 1.2 lneto <p> 2413 1.7 mbalmer The computation of the length of a table 2414 1.7 mbalmer has a guaranteed worst time of <em>O(log n)</em>, 2415 1.9 nikita where <em>n</em> is the largest integer key in the table. 2416 1.7 mbalmer 2417 1.2 lneto 2418 1.7 mbalmer <p> 2419 1.7 mbalmer A program can modify the behavior of the length operator for 2420 1.7 mbalmer any value but strings through the <code>__len</code> metamethod (see <a href="#2.4">§2.4</a>). 2421 1.2 lneto 2422 1.2 lneto 2423 1.2 lneto 2424 1.2 lneto 2425 1.2 lneto 2426 1.2 lneto <h3>3.4.8 – <a name="3.4.8">Precedence</a></h3><p> 2427 1.2 lneto Operator precedence in Lua follows the table below, 2428 1.2 lneto from lower to higher priority: 2429 1.2 lneto 2430 1.2 lneto <pre> 2431 1.2 lneto or 2432 1.2 lneto and 2433 1.2 lneto < > <= >= ~= == 2434 1.2 lneto | 2435 1.2 lneto ~ 2436 1.2 lneto & 2437 1.2 lneto << >> 2438 1.2 lneto .. 2439 1.2 lneto + - 2440 1.2 lneto * / // % 2441 1.2 lneto unary operators (not # - ~) 2442 1.2 lneto ^ 2443 1.2 lneto </pre><p> 2444 1.2 lneto As usual, 2445 1.2 lneto you can use parentheses to change the precedences of an expression. 2446 1.2 lneto The concatenation ('<code>..</code>') and exponentiation ('<code>^</code>') 2447 1.2 lneto operators are right associative. 2448 1.2 lneto All other binary operators are left associative. 2449 1.2 lneto 2450 1.2 lneto 2451 1.2 lneto 2452 1.2 lneto 2453 1.2 lneto 2454 1.2 lneto <h3>3.4.9 – <a name="3.4.9">Table Constructors</a></h3><p> 2455 1.2 lneto Table constructors are expressions that create tables. 2456 1.2 lneto Every time a constructor is evaluated, a new table is created. 2457 1.2 lneto A constructor can be used to create an empty table 2458 1.2 lneto or to create a table and initialize some of its fields. 2459 1.2 lneto The general syntax for constructors is 2460 1.2 lneto 2461 1.2 lneto <pre> 2462 1.2 lneto tableconstructor ::= ‘<b>{</b>’ [fieldlist] ‘<b>}</b>’ 2463 1.2 lneto fieldlist ::= field {fieldsep field} [fieldsep] 2464 1.2 lneto field ::= ‘<b>[</b>’ exp ‘<b>]</b>’ ‘<b>=</b>’ exp | Name ‘<b>=</b>’ exp | exp 2465 1.2 lneto fieldsep ::= ‘<b>,</b>’ | ‘<b>;</b>’ 2466 1.2 lneto </pre> 2467 1.2 lneto 2468 1.2 lneto <p> 2469 1.2 lneto Each field of the form <code>[exp1] = exp2</code> adds to the new table an entry 2470 1.2 lneto with key <code>exp1</code> and value <code>exp2</code>. 2471 1.2 lneto A field of the form <code>name = exp</code> is equivalent to 2472 1.2 lneto <code>["name"] = exp</code>. 2473 1.9 nikita Fields of the form <code>exp</code> are equivalent to 2474 1.3 lneto <code>[i] = exp</code>, where <code>i</code> are consecutive integers 2475 1.9 nikita starting with 1; 2476 1.9 nikita fields in the other formats do not affect this counting. 2477 1.2 lneto For example, 2478 1.2 lneto 2479 1.2 lneto <pre> 2480 1.2 lneto a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 } 2481 1.2 lneto </pre><p> 2482 1.2 lneto is equivalent to 2483 1.2 lneto 2484 1.2 lneto <pre> 2485 1.2 lneto do 2486 1.2 lneto local t = {} 2487 1.2 lneto t[f(1)] = g 2488 1.2 lneto t[1] = "x" -- 1st exp 2489 1.2 lneto t[2] = "y" -- 2nd exp 2490 1.2 lneto t.x = 1 -- t["x"] = 1 2491 1.2 lneto t[3] = f(x) -- 3rd exp 2492 1.2 lneto t[30] = 23 2493 1.2 lneto t[4] = 45 -- 4th exp 2494 1.2 lneto a = t 2495 1.2 lneto end 2496 1.2 lneto </pre> 2497 1.2 lneto 2498 1.2 lneto <p> 2499 1.3 lneto The order of the assignments in a constructor is undefined. 2500 1.3 lneto (This order would be relevant only when there are repeated keys.) 2501 1.3 lneto 2502 1.3 lneto 2503 1.3 lneto <p> 2504 1.2 lneto If the last field in the list has the form <code>exp</code> 2505 1.10 nikita and the expression is a multires expression, 2506 1.2 lneto then all values returned by this expression enter the list consecutively 2507 1.10 nikita (see <a href="#3.4.12">§3.4.12</a>). 2508 1.2 lneto 2509 1.2 lneto 2510 1.2 lneto <p> 2511 1.2 lneto The field list can have an optional trailing separator, 2512 1.2 lneto as a convenience for machine-generated code. 2513 1.2 lneto 2514 1.2 lneto 2515 1.2 lneto 2516 1.2 lneto 2517 1.2 lneto 2518 1.2 lneto <h3>3.4.10 – <a name="3.4.10">Function Calls</a></h3><p> 2519 1.2 lneto A function call in Lua has the following syntax: 2520 1.2 lneto 2521 1.2 lneto <pre> 2522 1.2 lneto functioncall ::= prefixexp args 2523 1.2 lneto </pre><p> 2524 1.2 lneto In a function call, 2525 1.2 lneto first prefixexp and args are evaluated. 2526 1.2 lneto If the value of prefixexp has type <em>function</em>, 2527 1.2 lneto then this function is called 2528 1.2 lneto with the given arguments. 2529 1.9 nikita Otherwise, if present, 2530 1.9 nikita the prefixexp <code>__call</code> metamethod is called: 2531 1.9 nikita its first argument is the value of prefixexp, 2532 1.2 lneto followed by the original call arguments 2533 1.2 lneto (see <a href="#2.4">§2.4</a>). 2534 1.2 lneto 2535 1.2 lneto 2536 1.2 lneto <p> 2537 1.2 lneto The form 2538 1.2 lneto 2539 1.2 lneto <pre> 2540 1.2 lneto functioncall ::= prefixexp ‘<b>:</b>’ Name args 2541 1.2 lneto </pre><p> 2542 1.9 nikita can be used to emulate methods. 2543 1.2 lneto A call <code>v:name(<em>args</em>)</code> 2544 1.2 lneto is syntactic sugar for <code>v.name(v,<em>args</em>)</code>, 2545 1.2 lneto except that <code>v</code> is evaluated only once. 2546 1.2 lneto 2547 1.2 lneto 2548 1.2 lneto <p> 2549 1.2 lneto Arguments have the following syntax: 2550 1.2 lneto 2551 1.2 lneto <pre> 2552 1.2 lneto args ::= ‘<b>(</b>’ [explist] ‘<b>)</b>’ 2553 1.2 lneto args ::= tableconstructor 2554 1.3 lneto args ::= LiteralString 2555 1.2 lneto </pre><p> 2556 1.2 lneto All argument expressions are evaluated before the call. 2557 1.2 lneto A call of the form <code>f{<em>fields</em>}</code> is 2558 1.2 lneto syntactic sugar for <code>f({<em>fields</em>})</code>; 2559 1.2 lneto that is, the argument list is a single new table. 2560 1.2 lneto A call of the form <code>f'<em>string</em>'</code> 2561 1.2 lneto (or <code>f"<em>string</em>"</code> or <code>f[[<em>string</em>]]</code>) 2562 1.2 lneto is syntactic sugar for <code>f('<em>string</em>')</code>; 2563 1.2 lneto that is, the argument list is a single literal string. 2564 1.2 lneto 2565 1.2 lneto 2566 1.2 lneto <p> 2567 1.9 nikita A call of the form <code>return <em>functioncall</em></code> not in the 2568 1.9 nikita scope of a to-be-closed variable is called a <em>tail call</em>. 2569 1.2 lneto Lua implements <em>proper tail calls</em> 2570 1.2 lneto (or <em>proper tail recursion</em>): 2571 1.10 nikita In a tail call, 2572 1.2 lneto the called function reuses the stack entry of the calling function. 2573 1.2 lneto Therefore, there is no limit on the number of nested tail calls that 2574 1.2 lneto a program can execute. 2575 1.2 lneto However, a tail call erases any debug information about the 2576 1.2 lneto calling function. 2577 1.2 lneto Note that a tail call only happens with a particular syntax, 2578 1.9 nikita where the <b>return</b> has one single function call as argument, 2579 1.9 nikita and it is outside the scope of any to-be-closed variable. 2580 1.9 nikita This syntax makes the calling function return exactly 2581 1.9 nikita the returns of the called function, 2582 1.9 nikita without any intervening action. 2583 1.2 lneto So, none of the following examples are tail calls: 2584 1.2 lneto 2585 1.2 lneto <pre> 2586 1.2 lneto return (f(x)) -- results adjusted to 1 2587 1.9 nikita return 2 * f(x) -- result multiplied by 2 2588 1.2 lneto return x, f(x) -- additional results 2589 1.2 lneto f(x); return -- results discarded 2590 1.2 lneto return x or f(x) -- results adjusted to 1 2591 1.2 lneto </pre> 2592 1.2 lneto 2593 1.2 lneto 2594 1.2 lneto 2595 1.2 lneto 2596 1.2 lneto <h3>3.4.11 – <a name="3.4.11">Function Definitions</a></h3> 2597 1.2 lneto 2598 1.2 lneto <p> 2599 1.2 lneto The syntax for function definition is 2600 1.2 lneto 2601 1.2 lneto <pre> 2602 1.2 lneto functiondef ::= <b>function</b> funcbody 2603 1.2 lneto funcbody ::= ‘<b>(</b>’ [parlist] ‘<b>)</b>’ block <b>end</b> 2604 1.2 lneto </pre> 2605 1.2 lneto 2606 1.2 lneto <p> 2607 1.2 lneto The following syntactic sugar simplifies function definitions: 2608 1.2 lneto 2609 1.2 lneto <pre> 2610 1.2 lneto stat ::= <b>function</b> funcname funcbody 2611 1.2 lneto stat ::= <b>local</b> <b>function</b> Name funcbody 2612 1.2 lneto funcname ::= Name {‘<b>.</b>’ Name} [‘<b>:</b>’ Name] 2613 1.2 lneto </pre><p> 2614 1.2 lneto The statement 2615 1.2 lneto 2616 1.2 lneto <pre> 2617 1.2 lneto function f () <em>body</em> end 2618 1.2 lneto </pre><p> 2619 1.2 lneto translates to 2620 1.2 lneto 2621 1.2 lneto <pre> 2622 1.2 lneto f = function () <em>body</em> end 2623 1.2 lneto </pre><p> 2624 1.2 lneto The statement 2625 1.2 lneto 2626 1.2 lneto <pre> 2627 1.2 lneto function t.a.b.c.f () <em>body</em> end 2628 1.2 lneto </pre><p> 2629 1.2 lneto translates to 2630 1.2 lneto 2631 1.2 lneto <pre> 2632 1.2 lneto t.a.b.c.f = function () <em>body</em> end 2633 1.2 lneto </pre><p> 2634 1.2 lneto The statement 2635 1.2 lneto 2636 1.2 lneto <pre> 2637 1.2 lneto local function f () <em>body</em> end 2638 1.2 lneto </pre><p> 2639 1.2 lneto translates to 2640 1.2 lneto 2641 1.2 lneto <pre> 2642 1.2 lneto local f; f = function () <em>body</em> end 2643 1.2 lneto </pre><p> 2644 1.2 lneto not to 2645 1.2 lneto 2646 1.2 lneto <pre> 2647 1.2 lneto local f = function () <em>body</em> end 2648 1.2 lneto </pre><p> 2649 1.2 lneto (This only makes a difference when the body of the function 2650 1.2 lneto contains references to <code>f</code>.) 2651 1.2 lneto 2652 1.2 lneto 2653 1.2 lneto <p> 2654 1.2 lneto A function definition is an executable expression, 2655 1.2 lneto whose value has type <em>function</em>. 2656 1.2 lneto When Lua precompiles a chunk, 2657 1.9 nikita all its function bodies are precompiled too, 2658 1.9 nikita but they are not created yet. 2659 1.2 lneto Then, whenever Lua executes the function definition, 2660 1.2 lneto the function is <em>instantiated</em> (or <em>closed</em>). 2661 1.9 nikita This function instance, or <em>closure</em>, 2662 1.2 lneto is the final value of the expression. 2663 1.2 lneto 2664 1.2 lneto 2665 1.2 lneto <p> 2666 1.2 lneto Parameters act as local variables that are 2667 1.2 lneto initialized with the argument values: 2668 1.2 lneto 2669 1.2 lneto <pre> 2670 1.2 lneto parlist ::= namelist [‘<b>,</b>’ ‘<b>...</b>’] | ‘<b>...</b>’ 2671 1.2 lneto </pre><p> 2672 1.9 nikita When a Lua function is called, 2673 1.9 nikita it adjusts its list of arguments to 2674 1.10 nikita the length of its list of parameters (see <a href="#3.4.12">§3.4.12</a>), 2675 1.10 nikita unless the function is a <em>variadic function</em>, 2676 1.2 lneto which is indicated by three dots ('<code>...</code>') 2677 1.2 lneto at the end of its parameter list. 2678 1.10 nikita A variadic function does not adjust its argument list; 2679 1.2 lneto instead, it collects all extra arguments and supplies them 2680 1.2 lneto to the function through a <em>vararg expression</em>, 2681 1.2 lneto which is also written as three dots. 2682 1.2 lneto The value of this expression is a list of all actual extra arguments, 2683 1.10 nikita similar to a function with multiple results (see <a href="#3.4.12">§3.4.12</a>). 2684 1.2 lneto 2685 1.2 lneto 2686 1.2 lneto <p> 2687 1.2 lneto As an example, consider the following definitions: 2688 1.2 lneto 2689 1.2 lneto <pre> 2690 1.2 lneto function f(a, b) end 2691 1.2 lneto function g(a, b, ...) end 2692 1.2 lneto function r() return 1,2,3 end 2693 1.2 lneto </pre><p> 2694 1.2 lneto Then, we have the following mapping from arguments to parameters and 2695 1.2 lneto to the vararg expression: 2696 1.1 mbalmer 2697 1.1 mbalmer <pre> 2698 1.9 nikita CALL PARAMETERS 2699 1.2 lneto 2700 1.2 lneto f(3) a=3, b=nil 2701 1.2 lneto f(3, 4) a=3, b=4 2702 1.2 lneto f(3, 4, 5) a=3, b=4 2703 1.2 lneto f(r(), 10) a=1, b=10 2704 1.2 lneto f(r()) a=1, b=2 2705 1.2 lneto 2706 1.2 lneto g(3) a=3, b=nil, ... --> (nothing) 2707 1.2 lneto g(3, 4) a=3, b=4, ... --> (nothing) 2708 1.2 lneto g(3, 4, 5, 8) a=3, b=4, ... --> 5 8 2709 1.2 lneto g(5, r()) a=5, b=1, ... --> 2 3 2710 1.1 mbalmer </pre> 2711 1.1 mbalmer 2712 1.1 mbalmer <p> 2713 1.2 lneto Results are returned using the <b>return</b> statement (see <a href="#3.3.4">§3.3.4</a>). 2714 1.2 lneto If control reaches the end of a function 2715 1.2 lneto without encountering a <b>return</b> statement, 2716 1.2 lneto then the function returns with no results. 2717 1.1 mbalmer 2718 1.1 mbalmer 2719 1.1 mbalmer <p> 2720 1.1 mbalmer 2721 1.2 lneto There is a system-dependent limit on the number of values 2722 1.2 lneto that a function may return. 2723 1.9 nikita This limit is guaranteed to be greater than 1000. 2724 1.1 mbalmer 2725 1.1 mbalmer 2726 1.1 mbalmer <p> 2727 1.2 lneto The <em>colon</em> syntax 2728 1.9 nikita is used to emulate <em>methods</em>, 2729 1.9 nikita adding an implicit extra parameter <code>self</code> to the function. 2730 1.2 lneto Thus, the statement 2731 1.1 mbalmer 2732 1.2 lneto <pre> 2733 1.2 lneto function t.a.b.c:f (<em>params</em>) <em>body</em> end 2734 1.2 lneto </pre><p> 2735 1.2 lneto is syntactic sugar for 2736 1.1 mbalmer 2737 1.2 lneto <pre> 2738 1.2 lneto t.a.b.c.f = function (self, <em>params</em>) <em>body</em> end 2739 1.2 lneto </pre> 2740 1.1 mbalmer 2741 1.1 mbalmer 2742 1.1 mbalmer 2743 1.1 mbalmer 2744 1.10 nikita <h3>3.4.12 – <a name="3.4.12">Lists of expressions, multiple results, 2745 1.10 nikita and adjustment</a></h3> 2746 1.10 nikita 2747 1.10 nikita <p> 2748 1.10 nikita Both function calls and vararg expressions can result in multiple values. 2749 1.10 nikita These expressions are called <em>multires expressions</em>. 2750 1.10 nikita 2751 1.10 nikita 2752 1.10 nikita <p> 2753 1.10 nikita When a multires expression is used as the last element 2754 1.10 nikita of a list of expressions, 2755 1.10 nikita all results from the expression are added to the 2756 1.10 nikita list of values produced by the list of expressions. 2757 1.10 nikita Note that a single expression 2758 1.10 nikita in a place that expects a list of expressions 2759 1.10 nikita is the last expression in that (singleton) list. 2760 1.10 nikita 2761 1.10 nikita 2762 1.10 nikita <p> 2763 1.10 nikita These are the places where Lua expects a list of expressions: 2764 1.10 nikita 2765 1.10 nikita <ul> 2766 1.10 nikita 2767 1.10 nikita <li>A <b>return</b> statement, 2768 1.10 nikita for instance <code>return e1, e2, e3</code> (see <a href="#3.3.4">§3.3.4</a>).</li> 2769 1.10 nikita 2770 1.10 nikita <li>A table constructor, 2771 1.10 nikita for instance <code>{e1, e2, e3}</code> (see <a href="#3.4.9">§3.4.9</a>).</li> 2772 1.10 nikita 2773 1.10 nikita <li>The arguments of a function call, 2774 1.10 nikita for instance <code>foo(e1, e2, e3)</code> (see <a href="#3.4.10">§3.4.10</a>).</li> 2775 1.10 nikita 2776 1.10 nikita <li>A multiple assignment, 2777 1.10 nikita for instance <code>a , b, c = e1, e2, e3</code> (see <a href="#3.3.3">§3.3.3</a>).</li> 2778 1.10 nikita 2779 1.10 nikita <li>A local declaration, 2780 1.10 nikita for instance <code>local a , b, c = e1, e2, e3</code> (see <a href="#3.3.7">§3.3.7</a>).</li> 2781 1.10 nikita 2782 1.10 nikita <li>The initial values in a generic <b>for</b> loop, 2783 1.10 nikita for instance <code>for k in e1, e2, e3 do ... end</code> (see <a href="#3.3.5">§3.3.5</a>).</li> 2784 1.10 nikita 2785 1.10 nikita </ul><p> 2786 1.10 nikita In the last four cases, 2787 1.10 nikita the list of values from the list of expressions 2788 1.10 nikita must be <em>adjusted</em> to a specific length: 2789 1.10 nikita the number of parameters in a call to a non-variadic function 2790 1.10 nikita (see <a href="#3.4.11">§3.4.11</a>), 2791 1.10 nikita the number of variables in a multiple assignment or 2792 1.10 nikita a local declaration, 2793 1.10 nikita and exactly four values for a generic <b>for</b> loop. 2794 1.10 nikita The <em>adjustment</em> follows these rules: 2795 1.10 nikita If there are more values than needed, 2796 1.10 nikita the extra values are thrown away; 2797 1.10 nikita if there are fewer values than needed, 2798 1.10 nikita the list is extended with <b>nil</b>'s. 2799 1.10 nikita When the list of expressions ends with a multires expression, 2800 1.10 nikita all results from that expression enter the list of values 2801 1.10 nikita before the adjustment. 2802 1.10 nikita 2803 1.10 nikita 2804 1.10 nikita <p> 2805 1.10 nikita When a multires expression is used 2806 1.10 nikita in a list of expressions without being the last element, 2807 1.10 nikita or in a place where the syntax expects a single expression, 2808 1.10 nikita Lua adjusts the result list of that expression to one element. 2809 1.10 nikita As a particular case, 2810 1.10 nikita the syntax expects a single expression inside a parenthesized expression; 2811 1.10 nikita therefore, adding parentheses around a multires expression 2812 1.10 nikita forces it to produce exactly one result. 2813 1.10 nikita 2814 1.10 nikita 2815 1.10 nikita <p> 2816 1.10 nikita We seldom need to use a vararg expression in a place 2817 1.10 nikita where the syntax expects a single expression. 2818 1.10 nikita (Usually it is simpler to add a regular parameter before 2819 1.10 nikita the variadic part and use that parameter.) 2820 1.10 nikita When there is such a need, 2821 1.10 nikita we recommend assigning the vararg expression 2822 1.10 nikita to a single variable and using that variable 2823 1.10 nikita in its place. 2824 1.10 nikita 2825 1.10 nikita 2826 1.10 nikita <p> 2827 1.10 nikita Here are some examples of uses of mutlres expressions. 2828 1.10 nikita In all cases, when the construction needs 2829 1.10 nikita "the n-th result" and there is no such result, 2830 1.10 nikita it uses a <b>nil</b>. 2831 1.10 nikita 2832 1.10 nikita <pre> 2833 1.10 nikita print(x, f()) -- prints x and all results from f(). 2834 1.10 nikita print(x, (f())) -- prints x and the first result from f(). 2835 1.10 nikita print(f(), x) -- prints the first result from f() and x. 2836 1.10 nikita print(1 + f()) -- prints 1 added to the first result from f(). 2837 1.10 nikita local x = ... -- x gets the first vararg argument. 2838 1.10 nikita x,y = ... -- x gets the first vararg argument, 2839 1.10 nikita -- y gets the second vararg argument. 2840 1.10 nikita x,y,z = w, f() -- x gets w, y gets the first result from f(), 2841 1.10 nikita -- z gets the second result from f(). 2842 1.10 nikita x,y,z = f() -- x gets the first result from f(), 2843 1.10 nikita -- y gets the second result from f(), 2844 1.10 nikita -- z gets the third result from f(). 2845 1.10 nikita x,y,z = f(), g() -- x gets the first result from f(), 2846 1.10 nikita -- y gets the first result from g(), 2847 1.10 nikita -- z gets the second result from g(). 2848 1.10 nikita x,y,z = (f()) -- x gets the first result from f(), y and z get nil. 2849 1.10 nikita return f() -- returns all results from f(). 2850 1.10 nikita return x, ... -- returns x and all received vararg arguments. 2851 1.10 nikita return x,y,f() -- returns x, y, and all results from f(). 2852 1.10 nikita {f()} -- creates a list with all results from f(). 2853 1.10 nikita {...} -- creates a list with all vararg arguments. 2854 1.10 nikita {f(), 5} -- creates a list with the first result from f() and 5. 2855 1.10 nikita </pre> 2856 1.10 nikita 2857 1.10 nikita 2858 1.10 nikita 2859 1.10 nikita 2860 1.1 mbalmer 2861 1.1 mbalmer 2862 1.2 lneto <h2>3.5 – <a name="3.5">Visibility Rules</a></h2> 2863 1.1 mbalmer 2864 1.1 mbalmer <p> 2865 1.1 mbalmer 2866 1.2 lneto Lua is a lexically scoped language. 2867 1.2 lneto The scope of a local variable begins at the first statement after 2868 1.2 lneto its declaration and lasts until the last non-void statement 2869 1.2 lneto of the innermost block that includes the declaration. 2870 1.10 nikita (<em>Void statements</em> are labels and empty statements.) 2871 1.2 lneto Consider the following example: 2872 1.1 mbalmer 2873 1.2 lneto <pre> 2874 1.2 lneto x = 10 -- global variable 2875 1.2 lneto do -- new block 2876 1.2 lneto local x = x -- new 'x', with value 10 2877 1.2 lneto print(x) --> 10 2878 1.2 lneto x = x+1 2879 1.2 lneto do -- another block 2880 1.2 lneto local x = x+1 -- another 'x' 2881 1.2 lneto print(x) --> 12 2882 1.2 lneto end 2883 1.2 lneto print(x) --> 11 2884 1.2 lneto end 2885 1.2 lneto print(x) --> 10 (the global one) 2886 1.2 lneto </pre> 2887 1.1 mbalmer 2888 1.1 mbalmer <p> 2889 1.2 lneto Notice that, in a declaration like <code>local x = x</code>, 2890 1.2 lneto the new <code>x</code> being declared is not in scope yet, 2891 1.2 lneto and so the second <code>x</code> refers to the outside variable. 2892 1.1 mbalmer 2893 1.1 mbalmer 2894 1.1 mbalmer <p> 2895 1.2 lneto Because of the lexical scoping rules, 2896 1.2 lneto local variables can be freely accessed by functions 2897 1.2 lneto defined inside their scope. 2898 1.9 nikita A local variable used by an inner function is called an <em>upvalue</em> 2899 1.9 nikita (or <em>external local variable</em>, or simply <em>external variable</em>) 2900 1.2 lneto inside the inner function. 2901 1.1 mbalmer 2902 1.1 mbalmer 2903 1.1 mbalmer <p> 2904 1.2 lneto Notice that each execution of a <b>local</b> statement 2905 1.2 lneto defines new local variables. 2906 1.2 lneto Consider the following example: 2907 1.1 mbalmer 2908 1.1 mbalmer <pre> 2909 1.2 lneto a = {} 2910 1.2 lneto local x = 20 2911 1.9 nikita for i = 1, 10 do 2912 1.2 lneto local y = 0 2913 1.9 nikita a[i] = function () y = y + 1; return x + y end 2914 1.1 mbalmer end 2915 1.1 mbalmer </pre><p> 2916 1.2 lneto The loop creates ten closures 2917 1.2 lneto (that is, ten instances of the anonymous function). 2918 1.2 lneto Each of these closures uses a different <code>y</code> variable, 2919 1.2 lneto while all of them share the same <code>x</code>. 2920 1.1 mbalmer 2921 1.1 mbalmer 2922 1.1 mbalmer 2923 1.1 mbalmer 2924 1.1 mbalmer 2925 1.2 lneto <h1>4 – <a name="4">The Application Program Interface</a></h1> 2926 1.1 mbalmer 2927 1.9 nikita 2928 1.9 nikita 2929 1.1 mbalmer <p> 2930 1.1 mbalmer 2931 1.1 mbalmer This section describes the C API for Lua, that is, 2932 1.1 mbalmer the set of C functions available to the host program to communicate 2933 1.1 mbalmer with Lua. 2934 1.1 mbalmer All API functions and related types and constants 2935 1.1 mbalmer are declared in the header file <a name="pdf-lua.h"><code>lua.h</code></a>. 2936 1.1 mbalmer 2937 1.1 mbalmer 2938 1.1 mbalmer <p> 2939 1.1 mbalmer Even when we use the term "function", 2940 1.1 mbalmer any facility in the API may be provided as a macro instead. 2941 1.2 lneto Except where stated otherwise, 2942 1.2 lneto all such macros use each of their arguments exactly once 2943 1.1 mbalmer (except for the first argument, which is always a Lua state), 2944 1.1 mbalmer and so do not generate any hidden side-effects. 2945 1.1 mbalmer 2946 1.1 mbalmer 2947 1.1 mbalmer <p> 2948 1.1 mbalmer As in most C libraries, 2949 1.9 nikita the Lua API functions do not check their arguments 2950 1.9 nikita for validity or consistency. 2951 1.1 mbalmer However, you can change this behavior by compiling Lua 2952 1.2 lneto with the macro <a name="pdf-LUA_USE_APICHECK"><code>LUA_USE_APICHECK</code></a> defined. 2953 1.1 mbalmer 2954 1.1 mbalmer 2955 1.7 mbalmer <p> 2956 1.7 mbalmer The Lua library is fully reentrant: 2957 1.7 mbalmer it has no global variables. 2958 1.7 mbalmer It keeps all information it needs in a dynamic structure, 2959 1.7 mbalmer called the <em>Lua state</em>. 2960 1.7 mbalmer 2961 1.7 mbalmer 2962 1.7 mbalmer <p> 2963 1.7 mbalmer Each Lua state has one or more threads, 2964 1.7 mbalmer which correspond to independent, cooperative lines of execution. 2965 1.7 mbalmer The type <a href="#lua_State"><code>lua_State</code></a> (despite its name) refers to a thread. 2966 1.7 mbalmer (Indirectly, through the thread, it also refers to the 2967 1.7 mbalmer Lua state associated to the thread.) 2968 1.7 mbalmer 2969 1.7 mbalmer 2970 1.7 mbalmer <p> 2971 1.7 mbalmer A pointer to a thread must be passed as the first argument to 2972 1.7 mbalmer every function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>, 2973 1.7 mbalmer which creates a Lua state from scratch and returns a pointer 2974 1.7 mbalmer to the <em>main thread</em> in the new state. 2975 1.7 mbalmer 2976 1.7 mbalmer 2977 1.1 mbalmer 2978 1.9 nikita 2979 1.9 nikita 2980 1.2 lneto <h2>4.1 – <a name="4.1">The Stack</a></h2> 2981 1.1 mbalmer 2982 1.9 nikita 2983 1.9 nikita 2984 1.1 mbalmer <p> 2985 1.1 mbalmer Lua uses a <em>virtual stack</em> to pass values to and from C. 2986 1.1 mbalmer Each element in this stack represents a Lua value 2987 1.1 mbalmer (<b>nil</b>, number, string, etc.). 2988 1.7 mbalmer Functions in the API can access this stack through the 2989 1.7 mbalmer Lua state parameter that they receive. 2990 1.1 mbalmer 2991 1.1 mbalmer 2992 1.1 mbalmer <p> 2993 1.1 mbalmer Whenever Lua calls C, the called function gets a new stack, 2994 1.1 mbalmer which is independent of previous stacks and of stacks of 2995 1.1 mbalmer C functions that are still active. 2996 1.1 mbalmer This stack initially contains any arguments to the C function 2997 1.7 mbalmer and it is where the C function can store temporary 2998 1.7 mbalmer Lua values and must push its results 2999 1.1 mbalmer to be returned to the caller (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 3000 1.1 mbalmer 3001 1.1 mbalmer 3002 1.1 mbalmer <p> 3003 1.1 mbalmer For convenience, 3004 1.1 mbalmer most query operations in the API do not follow a strict stack discipline. 3005 1.1 mbalmer Instead, they can refer to any element in the stack 3006 1.1 mbalmer by using an <em>index</em>: 3007 1.9 nikita A positive index represents an absolute stack position, 3008 1.9 nikita starting at 1 as the bottom of the stack; 3009 1.2 lneto a negative index represents an offset relative to the top of the stack. 3010 1.1 mbalmer More specifically, if the stack has <em>n</em> elements, 3011 1.1 mbalmer then index 1 represents the first element 3012 1.1 mbalmer (that is, the element that was pushed onto the stack first) 3013 1.1 mbalmer and 3014 1.1 mbalmer index <em>n</em> represents the last element; 3015 1.1 mbalmer index -1 also represents the last element 3016 1.1 mbalmer (that is, the element at the top) 3017 1.1 mbalmer and index <em>-n</em> represents the first element. 3018 1.1 mbalmer 3019 1.1 mbalmer 3020 1.1 mbalmer 3021 1.1 mbalmer 3022 1.1 mbalmer 3023 1.9 nikita <h3>4.1.1 – <a name="4.1.1">Stack Size</a></h3> 3024 1.1 mbalmer 3025 1.1 mbalmer <p> 3026 1.2 lneto When you interact with the Lua API, 3027 1.1 mbalmer you are responsible for ensuring consistency. 3028 1.1 mbalmer In particular, 3029 1.1 mbalmer <em>you are responsible for controlling stack overflow</em>. 3030 1.9 nikita When you call any API function, 3031 1.9 nikita you must ensure the stack has enough room to accommodate the results. 3032 1.9 nikita 3033 1.9 nikita 3034 1.9 nikita <p> 3035 1.9 nikita There is one exception to the above rule: 3036 1.9 nikita When you call a Lua function 3037 1.9 nikita without a fixed number of results (see <a href="#lua_call"><code>lua_call</code></a>), 3038 1.9 nikita Lua ensures that the stack has enough space for all results. 3039 1.9 nikita However, it does not ensure any extra space. 3040 1.9 nikita So, before pushing anything on the stack after such a call 3041 1.9 nikita you should use <a href="#lua_checkstack"><code>lua_checkstack</code></a>. 3042 1.1 mbalmer 3043 1.1 mbalmer 3044 1.1 mbalmer <p> 3045 1.1 mbalmer Whenever Lua calls C, 3046 1.3 lneto it ensures that the stack has space for 3047 1.9 nikita at least <a name="pdf-LUA_MINSTACK"><code>LUA_MINSTACK</code></a> extra elements; 3048 1.9 nikita that is, you can safely push up to <code>LUA_MINSTACK</code> values into it. 3049 1.1 mbalmer <code>LUA_MINSTACK</code> is defined as 20, 3050 1.1 mbalmer so that usually you do not have to worry about stack space 3051 1.1 mbalmer unless your code has loops pushing elements onto the stack. 3052 1.9 nikita Whenever necessary, 3053 1.9 nikita you can use the function <a href="#lua_checkstack"><code>lua_checkstack</code></a> 3054 1.9 nikita to ensure that the stack has enough space for pushing new elements. 3055 1.2 lneto 3056 1.2 lneto 3057 1.2 lneto 3058 1.2 lneto 3059 1.1 mbalmer 3060 1.9 nikita <h3>4.1.2 – <a name="4.1.2">Valid and Acceptable Indices</a></h3> 3061 1.1 mbalmer 3062 1.2 lneto <p> 3063 1.2 lneto Any function in the API that receives stack indices 3064 1.2 lneto works only with <em>valid indices</em> or <em>acceptable indices</em>. 3065 1.1 mbalmer 3066 1.1 mbalmer 3067 1.2 lneto <p> 3068 1.2 lneto A <em>valid index</em> is an index that refers to a 3069 1.4 mbalmer position that stores a modifiable Lua value. 3070 1.4 mbalmer It comprises stack indices between 1 and the stack top 3071 1.4 mbalmer (<code>1 ≤ abs(index) ≤ top</code>) 3072 1.4 mbalmer 3073 1.4 mbalmer plus <em>pseudo-indices</em>, 3074 1.4 mbalmer which represent some positions that are accessible to C code 3075 1.4 mbalmer but that are not in the stack. 3076 1.9 nikita Pseudo-indices are used to access the registry (see <a href="#4.3">§4.3</a>) 3077 1.9 nikita and the upvalues of a C function (see <a href="#4.2">§4.2</a>). 3078 1.2 lneto 3079 1.2 lneto 3080 1.2 lneto <p> 3081 1.4 mbalmer Functions that do not need a specific mutable position, 3082 1.4 mbalmer but only a value (e.g., query functions), 3083 1.2 lneto can be called with acceptable indices. 3084 1.2 lneto An <em>acceptable index</em> can be any valid index, 3085 1.2 lneto but it also can be any positive index after the stack top 3086 1.2 lneto within the space allocated for the stack, 3087 1.2 lneto that is, indices up to the stack size. 3088 1.2 lneto (Note that 0 is never an acceptable index.) 3089 1.9 nikita Indices to upvalues (see <a href="#4.2">§4.2</a>) greater than the real number 3090 1.9 nikita of upvalues in the current C function are also acceptable (but invalid). 3091 1.2 lneto Except when noted otherwise, 3092 1.2 lneto functions in the API work with acceptable indices. 3093 1.1 mbalmer 3094 1.1 mbalmer 3095 1.1 mbalmer <p> 3096 1.2 lneto Acceptable indices serve to avoid extra tests 3097 1.2 lneto against the stack top when querying the stack. 3098 1.2 lneto For instance, a C function can query its third argument 3099 1.9 nikita without the need to check whether there is a third argument, 3100 1.2 lneto that is, without the need to check whether 3 is a valid index. 3101 1.1 mbalmer 3102 1.1 mbalmer 3103 1.1 mbalmer <p> 3104 1.2 lneto For functions that can be called with acceptable indices, 3105 1.2 lneto any non-valid index is treated as if it 3106 1.2 lneto contains a value of a virtual type <a name="pdf-LUA_TNONE"><code>LUA_TNONE</code></a>, 3107 1.2 lneto which behaves like a nil value. 3108 1.1 mbalmer 3109 1.1 mbalmer 3110 1.1 mbalmer 3111 1.1 mbalmer 3112 1.1 mbalmer 3113 1.9 nikita <h3>4.1.3 – <a name="4.1.3">Pointers to strings</a></h3> 3114 1.9 nikita 3115 1.9 nikita <p> 3116 1.9 nikita Several functions in the API return pointers (<code>const char*</code>) 3117 1.9 nikita to Lua strings in the stack. 3118 1.9 nikita (See <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>, <a href="#lua_pushlstring"><code>lua_pushlstring</code></a>, 3119 1.9 nikita <a href="#lua_pushstring"><code>lua_pushstring</code></a>, and <a href="#lua_tolstring"><code>lua_tolstring</code></a>. 3120 1.9 nikita See also <a href="#luaL_checklstring"><code>luaL_checklstring</code></a>, <a href="#luaL_checkstring"><code>luaL_checkstring</code></a>, 3121 1.9 nikita and <a href="#luaL_tolstring"><code>luaL_tolstring</code></a> in the auxiliary library.) 3122 1.9 nikita 3123 1.9 nikita 3124 1.9 nikita <p> 3125 1.9 nikita In general, 3126 1.9 nikita Lua's garbage collection can free or move internal memory 3127 1.9 nikita and then invalidate pointers to internal strings. 3128 1.9 nikita To allow a safe use of these pointers, 3129 1.10 nikita the API guarantees that any pointer to a string in a stack index 3130 1.9 nikita is valid while the string value at that index is not removed from the stack. 3131 1.9 nikita (It can be moved to another index, though.) 3132 1.9 nikita When the index is a pseudo-index (referring to an upvalue), 3133 1.9 nikita the pointer is valid while the corresponding call is active and 3134 1.9 nikita the corresponding upvalue is not modified. 3135 1.9 nikita 3136 1.9 nikita 3137 1.9 nikita <p> 3138 1.9 nikita Some functions in the debug interface 3139 1.9 nikita also return pointers to strings, 3140 1.9 nikita namely <a href="#lua_getlocal"><code>lua_getlocal</code></a>, <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>, 3141 1.9 nikita <a href="#lua_setlocal"><code>lua_setlocal</code></a>, and <a href="#lua_setupvalue"><code>lua_setupvalue</code></a>. 3142 1.9 nikita For these functions, the pointer is guaranteed to 3143 1.9 nikita be valid while the caller function is active and 3144 1.9 nikita the given closure (if one was given) is in the stack. 3145 1.9 nikita 3146 1.9 nikita 3147 1.9 nikita <p> 3148 1.9 nikita Except for these guarantees, 3149 1.9 nikita the garbage collector is free to invalidate 3150 1.9 nikita any pointer to internal strings. 3151 1.9 nikita 3152 1.9 nikita 3153 1.9 nikita 3154 1.9 nikita 3155 1.9 nikita 3156 1.9 nikita 3157 1.9 nikita 3158 1.9 nikita <h2>4.2 – <a name="4.2">C Closures</a></h2> 3159 1.1 mbalmer 3160 1.1 mbalmer <p> 3161 1.1 mbalmer When a C function is created, 3162 1.1 mbalmer it is possible to associate some values with it, 3163 1.2 lneto thus creating a <em>C closure</em> 3164 1.2 lneto (see <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>); 3165 1.1 mbalmer these values are called <em>upvalues</em> and are 3166 1.2 lneto accessible to the function whenever it is called. 3167 1.1 mbalmer 3168 1.1 mbalmer 3169 1.1 mbalmer <p> 3170 1.1 mbalmer Whenever a C function is called, 3171 1.1 mbalmer its upvalues are located at specific pseudo-indices. 3172 1.1 mbalmer These pseudo-indices are produced by the macro 3173 1.2 lneto <a href="#lua_upvalueindex"><code>lua_upvalueindex</code></a>. 3174 1.4 mbalmer The first upvalue associated with a function is at index 3175 1.1 mbalmer <code>lua_upvalueindex(1)</code>, and so on. 3176 1.1 mbalmer Any access to <code>lua_upvalueindex(<em>n</em>)</code>, 3177 1.1 mbalmer where <em>n</em> is greater than the number of upvalues of the 3178 1.5 lneto current function 3179 1.5 lneto (but not greater than 256, 3180 1.5 lneto which is one plus the maximum number of upvalues in a closure), 3181 1.2 lneto produces an acceptable but invalid index. 3182 1.1 mbalmer 3183 1.1 mbalmer 3184 1.9 nikita <p> 3185 1.9 nikita A C closure can also change the values 3186 1.9 nikita of its corresponding upvalues. 3187 1.9 nikita 3188 1.1 mbalmer 3189 1.1 mbalmer 3190 1.1 mbalmer 3191 1.9 nikita 3192 1.9 nikita <h2>4.3 – <a name="4.3">Registry</a></h2> 3193 1.1 mbalmer 3194 1.1 mbalmer <p> 3195 1.1 mbalmer Lua provides a <em>registry</em>, 3196 1.2 lneto a predefined table that can be used by any C code to 3197 1.2 lneto store whatever Lua values it needs to store. 3198 1.9 nikita The registry table is always accessible at pseudo-index 3199 1.4 mbalmer <a name="pdf-LUA_REGISTRYINDEX"><code>LUA_REGISTRYINDEX</code></a>. 3200 1.1 mbalmer Any C library can store data into this table, 3201 1.2 lneto but it must take care to choose keys 3202 1.2 lneto that are different from those used 3203 1.1 mbalmer by other libraries, to avoid collisions. 3204 1.2 lneto Typically, you should use as key a string containing your library name, 3205 1.2 lneto or a light userdata with the address of a C object in your code, 3206 1.2 lneto or any Lua object created by your code. 3207 1.3 lneto As with variable names, 3208 1.2 lneto string keys starting with an underscore followed by 3209 1.2 lneto uppercase letters are reserved for Lua. 3210 1.1 mbalmer 3211 1.1 mbalmer 3212 1.1 mbalmer <p> 3213 1.3 lneto The integer keys in the registry are used 3214 1.3 lneto by the reference mechanism (see <a href="#luaL_ref"><code>luaL_ref</code></a>) 3215 1.2 lneto and by some predefined values. 3216 1.9 nikita Therefore, integer keys in the registry 3217 1.9 nikita must not be used for other purposes. 3218 1.2 lneto 3219 1.1 mbalmer 3220 1.2 lneto <p> 3221 1.2 lneto When you create a new Lua state, 3222 1.2 lneto its registry comes with some predefined values. 3223 1.2 lneto These predefined values are indexed with integer keys 3224 1.2 lneto defined as constants in <code>lua.h</code>. 3225 1.2 lneto The following constants are defined: 3226 1.2 lneto 3227 1.2 lneto <ul> 3228 1.2 lneto <li><b><a name="pdf-LUA_RIDX_MAINTHREAD"><code>LUA_RIDX_MAINTHREAD</code></a>: </b> At this index the registry has 3229 1.2 lneto the main thread of the state. 3230 1.2 lneto (The main thread is the one created together with the state.) 3231 1.2 lneto </li> 3232 1.1 mbalmer 3233 1.2 lneto <li><b><a name="pdf-LUA_RIDX_GLOBALS"><code>LUA_RIDX_GLOBALS</code></a>: </b> At this index the registry has 3234 1.2 lneto the global environment. 3235 1.2 lneto </li> 3236 1.2 lneto </ul> 3237 1.1 mbalmer 3238 1.1 mbalmer 3239 1.1 mbalmer 3240 1.2 lneto 3241 1.9 nikita <h2>4.4 – <a name="4.4">Error Handling in C</a></h2> 3242 1.9 nikita 3243 1.9 nikita 3244 1.1 mbalmer 3245 1.1 mbalmer <p> 3246 1.1 mbalmer Internally, Lua uses the C <code>longjmp</code> facility to handle errors. 3247 1.3 lneto (Lua will use exceptions if you compile it as C++; 3248 1.3 lneto search for <code>LUAI_THROW</code> in the source code for details.) 3249 1.9 nikita When Lua faces any error, 3250 1.9 nikita such as a memory allocation error or a type error, 3251 1.1 mbalmer it <em>raises</em> an error; 3252 1.1 mbalmer that is, it does a long jump. 3253 1.1 mbalmer A <em>protected environment</em> uses <code>setjmp</code> 3254 1.2 lneto to set a recovery point; 3255 1.2 lneto any error jumps to the most recent active recovery point. 3256 1.2 lneto 3257 1.2 lneto 3258 1.2 lneto <p> 3259 1.9 nikita Inside a C function you can raise an error explicitly 3260 1.9 nikita by calling <a href="#lua_error"><code>lua_error</code></a>. 3261 1.7 mbalmer 3262 1.7 mbalmer 3263 1.7 mbalmer <p> 3264 1.7 mbalmer Most functions in the API can raise an error, 3265 1.7 mbalmer for instance due to a memory allocation error. 3266 1.7 mbalmer The documentation for each function indicates whether 3267 1.7 mbalmer it can raise errors. 3268 1.7 mbalmer 3269 1.7 mbalmer 3270 1.7 mbalmer <p> 3271 1.2 lneto If an error happens outside any protected environment, 3272 1.2 lneto Lua calls a <em>panic function</em> (see <a href="#lua_atpanic"><code>lua_atpanic</code></a>) 3273 1.2 lneto and then calls <code>abort</code>, 3274 1.2 lneto thus exiting the host application. 3275 1.2 lneto Your panic function can avoid this exit by 3276 1.2 lneto never returning 3277 1.2 lneto (e.g., doing a long jump to your own recovery point outside Lua). 3278 1.2 lneto 3279 1.2 lneto 3280 1.2 lneto <p> 3281 1.7 mbalmer The panic function, 3282 1.7 mbalmer as its name implies, 3283 1.7 mbalmer is a mechanism of last resort. 3284 1.7 mbalmer Programs should avoid it. 3285 1.7 mbalmer As a general rule, 3286 1.7 mbalmer when a C function is called by Lua with a Lua state, 3287 1.7 mbalmer it can do whatever it wants on that Lua state, 3288 1.7 mbalmer as it should be already protected. 3289 1.7 mbalmer However, 3290 1.7 mbalmer when C code operates on other Lua states 3291 1.9 nikita (e.g., a Lua-state argument to the function, 3292 1.7 mbalmer a Lua state stored in the registry, or 3293 1.7 mbalmer the result of <a href="#lua_newthread"><code>lua_newthread</code></a>), 3294 1.7 mbalmer it should use them only in API calls that cannot raise errors. 3295 1.7 mbalmer 3296 1.7 mbalmer 3297 1.7 mbalmer <p> 3298 1.2 lneto The panic function runs as if it were a message handler (see <a href="#2.3">§2.3</a>); 3299 1.9 nikita in particular, the error object is on the top of the stack. 3300 1.3 lneto However, there is no guarantee about stack space. 3301 1.2 lneto To push anything on the stack, 3302 1.9 nikita the panic function must first check the available space (see <a href="#4.1.1">§4.1.1</a>). 3303 1.9 nikita 3304 1.9 nikita 3305 1.9 nikita 3306 1.9 nikita 3307 1.9 nikita 3308 1.9 nikita <h3>4.4.1 – <a name="4.4.1">Status Codes</a></h3> 3309 1.9 nikita 3310 1.9 nikita <p> 3311 1.9 nikita Several functions that report errors in the API use the following 3312 1.9 nikita status codes to indicate different kinds of errors or other conditions: 3313 1.9 nikita 3314 1.9 nikita <ul> 3315 1.9 nikita 3316 1.9 nikita <li><b><a name="pdf-LUA_OK"><code>LUA_OK</code></a> (0): </b> no errors.</li> 3317 1.9 nikita 3318 1.9 nikita <li><b><a name="pdf-LUA_ERRRUN"><code>LUA_ERRRUN</code></a>: </b> a runtime error.</li> 3319 1.9 nikita 3320 1.9 nikita <li><b><a name="pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>: </b> 3321 1.9 nikita memory allocation error. 3322 1.9 nikita For such errors, Lua does not call the message handler. 3323 1.9 nikita </li> 3324 1.9 nikita 3325 1.9 nikita <li><b><a name="pdf-LUA_ERRERR"><code>LUA_ERRERR</code></a>: </b> error while running the message handler.</li> 3326 1.9 nikita 3327 1.9 nikita <li><b><a name="pdf-LUA_ERRSYNTAX"><code>LUA_ERRSYNTAX</code></a>: </b> syntax error during precompilation.</li> 3328 1.9 nikita 3329 1.9 nikita <li><b><a name="pdf-LUA_YIELD"><code>LUA_YIELD</code></a>: </b> the thread (coroutine) yields.</li> 3330 1.9 nikita 3331 1.9 nikita <li><b><a name="pdf-LUA_ERRFILE"><code>LUA_ERRFILE</code></a>: </b> a file-related error; 3332 1.9 nikita e.g., it cannot open or read the file.</li> 3333 1.9 nikita 3334 1.9 nikita </ul><p> 3335 1.9 nikita These constants are defined in the header file <code>lua.h</code>. 3336 1.9 nikita 3337 1.9 nikita 3338 1.1 mbalmer 3339 1.1 mbalmer 3340 1.2 lneto 3341 1.2 lneto 3342 1.2 lneto 3343 1.9 nikita <h2>4.5 – <a name="4.5">Handling Yields in C</a></h2> 3344 1.2 lneto 3345 1.2 lneto <p> 3346 1.2 lneto Internally, Lua uses the C <code>longjmp</code> facility to yield a coroutine. 3347 1.7 mbalmer Therefore, if a C function <code>foo</code> calls an API function 3348 1.2 lneto and this API function yields 3349 1.2 lneto (directly or indirectly by calling another function that yields), 3350 1.2 lneto Lua cannot return to <code>foo</code> any more, 3351 1.9 nikita because the <code>longjmp</code> removes its frame from the C stack. 3352 1.2 lneto 3353 1.2 lneto 3354 1.2 lneto <p> 3355 1.2 lneto To avoid this kind of problem, 3356 1.2 lneto Lua raises an error whenever it tries to yield across an API call, 3357 1.2 lneto except for three functions: 3358 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>. 3359 1.2 lneto All those functions receive a <em>continuation function</em> 3360 1.3 lneto (as a parameter named <code>k</code>) to continue execution after a yield. 3361 1.2 lneto 3362 1.2 lneto 3363 1.2 lneto <p> 3364 1.2 lneto We need to set some terminology to explain continuations. 3365 1.7 mbalmer We have a C function called from Lua which we will call 3366 1.2 lneto the <em>original function</em>. 3367 1.2 lneto This original function then calls one of those three functions in the C API, 3368 1.2 lneto which we will call the <em>callee function</em>, 3369 1.2 lneto that then yields the current thread. 3370 1.9 nikita This can happen when the callee function is <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 3371 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> 3372 1.9 nikita and the function called by them yields. 3373 1.2 lneto 3374 1.2 lneto 3375 1.2 lneto <p> 3376 1.2 lneto Suppose the running thread yields while executing the callee function. 3377 1.2 lneto After the thread resumes, 3378 1.2 lneto it eventually will finish running the callee function. 3379 1.2 lneto However, 3380 1.2 lneto the callee function cannot return to the original function, 3381 1.9 nikita because its frame in the C stack was destroyed by the yield. 3382 1.2 lneto Instead, Lua calls a <em>continuation function</em>, 3383 1.2 lneto which was given as an argument to the callee function. 3384 1.2 lneto As the name implies, 3385 1.2 lneto the continuation function should continue the task 3386 1.2 lneto of the original function. 3387 1.2 lneto 3388 1.2 lneto 3389 1.2 lneto <p> 3390 1.2 lneto As an illustration, consider the following function: 3391 1.2 lneto 3392 1.2 lneto <pre> 3393 1.2 lneto int original_function (lua_State *L) { 3394 1.2 lneto ... /* code 1 */ 3395 1.2 lneto status = lua_pcall(L, n, m, h); /* calls Lua */ 3396 1.2 lneto ... /* code 2 */ 3397 1.2 lneto } 3398 1.2 lneto </pre><p> 3399 1.2 lneto Now we want to allow 3400 1.3 lneto the Lua code being run by <a href="#lua_pcall"><code>lua_pcall</code></a> to yield. 3401 1.2 lneto First, we can rewrite our function like here: 3402 1.2 lneto 3403 1.2 lneto <pre> 3404 1.3 lneto int k (lua_State *L, int status, lua_KContext ctx) { 3405 1.2 lneto ... /* code 2 */ 3406 1.2 lneto } 3407 1.2 lneto 3408 1.2 lneto int original_function (lua_State *L) { 3409 1.2 lneto ... /* code 1 */ 3410 1.2 lneto return k(L, lua_pcall(L, n, m, h), ctx); 3411 1.2 lneto } 3412 1.2 lneto </pre><p> 3413 1.2 lneto In the above code, 3414 1.2 lneto the new function <code>k</code> is a 3415 1.2 lneto <em>continuation function</em> (with type <a href="#lua_KFunction"><code>lua_KFunction</code></a>), 3416 1.2 lneto which should do all the work that the original function 3417 1.2 lneto was doing after calling <a href="#lua_pcall"><code>lua_pcall</code></a>. 3418 1.2 lneto Now, we must inform Lua that it must call <code>k</code> if the Lua code 3419 1.3 lneto being executed by <a href="#lua_pcall"><code>lua_pcall</code></a> gets interrupted in some way 3420 1.2 lneto (errors or yielding), 3421 1.2 lneto so we rewrite the code as here, 3422 1.2 lneto replacing <a href="#lua_pcall"><code>lua_pcall</code></a> by <a href="#lua_pcallk"><code>lua_pcallk</code></a>: 3423 1.2 lneto 3424 1.2 lneto <pre> 3425 1.2 lneto int original_function (lua_State *L) { 3426 1.2 lneto ... /* code 1 */ 3427 1.2 lneto return k(L, lua_pcallk(L, n, m, h, ctx2, k), ctx1); 3428 1.2 lneto } 3429 1.3 lneto </pre><p> 3430 1.3 lneto Note the external, explicit call to the continuation: 3431 1.3 lneto Lua will call the continuation only if needed, that is, 3432 1.3 lneto in case of errors or resuming after a yield. 3433 1.3 lneto If the called function returns normally without ever yielding, 3434 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. 3435 1.3 lneto (Of course, instead of calling the continuation in that case, 3436 1.3 lneto you can do the equivalent work directly inside the original function.) 3437 1.3 lneto 3438 1.2 lneto 3439 1.2 lneto <p> 3440 1.2 lneto Besides the Lua state, 3441 1.2 lneto the continuation function has two other parameters: 3442 1.9 nikita the final status of the call and the context value (<code>ctx</code>) that 3443 1.2 lneto was passed originally to <a href="#lua_pcallk"><code>lua_pcallk</code></a>. 3444 1.9 nikita Lua does not use this context value; 3445 1.2 lneto it only passes this value from the original function to the 3446 1.9 nikita continuation function. 3447 1.2 lneto For <a href="#lua_pcallk"><code>lua_pcallk</code></a>, 3448 1.2 lneto the status is the same value that would be returned by <a href="#lua_pcallk"><code>lua_pcallk</code></a>, 3449 1.3 lneto except that it is <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when being executed after a yield 3450 1.2 lneto (instead of <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>). 3451 1.2 lneto For <a href="#lua_yieldk"><code>lua_yieldk</code></a> and <a href="#lua_callk"><code>lua_callk</code></a>, 3452 1.2 lneto the status is always <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when Lua calls the continuation. 3453 1.2 lneto (For these two functions, 3454 1.2 lneto Lua will not call the continuation in case of errors, 3455 1.2 lneto because they do not handle errors.) 3456 1.3 lneto Similarly, when using <a href="#lua_callk"><code>lua_callk</code></a>, 3457 1.3 lneto you should call the continuation function 3458 1.3 lneto with <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> as the status. 3459 1.3 lneto (For <a href="#lua_yieldk"><code>lua_yieldk</code></a>, there is not much point in calling 3460 1.3 lneto directly the continuation function, 3461 1.3 lneto because <a href="#lua_yieldk"><code>lua_yieldk</code></a> usually does not return.) 3462 1.1 mbalmer 3463 1.1 mbalmer 3464 1.1 mbalmer <p> 3465 1.2 lneto Lua treats the continuation function as if it were the original function. 3466 1.2 lneto The continuation function receives the same Lua stack 3467 1.2 lneto from the original function, 3468 1.2 lneto in the same state it would be if the callee function had returned. 3469 1.2 lneto (For instance, 3470 1.2 lneto after a <a href="#lua_callk"><code>lua_callk</code></a> the function and its arguments are 3471 1.2 lneto removed from the stack and replaced by the results from the call.) 3472 1.2 lneto It also has the same upvalues. 3473 1.2 lneto Whatever it returns is handled by Lua as if it were the return 3474 1.2 lneto of the original function. 3475 1.1 mbalmer 3476 1.1 mbalmer 3477 1.1 mbalmer 3478 1.1 mbalmer 3479 1.1 mbalmer 3480 1.9 nikita <h2>4.6 – <a name="4.6">Functions and Types</a></h2> 3481 1.1 mbalmer 3482 1.1 mbalmer <p> 3483 1.1 mbalmer Here we list all functions and types from the C API in 3484 1.1 mbalmer alphabetical order. 3485 1.1 mbalmer Each function has an indicator like this: 3486 1.1 mbalmer <span class="apii">[-o, +p, <em>x</em>]</span> 3487 1.1 mbalmer 3488 1.1 mbalmer 3489 1.1 mbalmer <p> 3490 1.1 mbalmer The first field, <code>o</code>, 3491 1.1 mbalmer is how many elements the function pops from the stack. 3492 1.1 mbalmer The second field, <code>p</code>, 3493 1.1 mbalmer is how many elements the function pushes onto the stack. 3494 1.1 mbalmer (Any function always pushes its results after popping its arguments.) 3495 1.1 mbalmer A field in the form <code>x|y</code> means the function can push (or pop) 3496 1.1 mbalmer <code>x</code> or <code>y</code> elements, 3497 1.1 mbalmer depending on the situation; 3498 1.1 mbalmer an interrogation mark '<code>?</code>' means that 3499 1.1 mbalmer we cannot know how many elements the function pops/pushes 3500 1.9 nikita by looking only at its arguments. 3501 1.9 nikita (For instance, they may depend on what is in the stack.) 3502 1.1 mbalmer The third field, <code>x</code>, 3503 1.2 lneto tells whether the function may raise errors: 3504 1.2 lneto '<code>-</code>' means the function never raises any error; 3505 1.9 nikita '<code>m</code>' means the function may raise only out-of-memory errors; 3506 1.9 nikita '<code>v</code>' means the function may raise the errors explained in the text; 3507 1.9 nikita '<code>e</code>' means the function can run arbitrary Lua code, 3508 1.9 nikita either directly or through metamethods, 3509 1.9 nikita and therefore may raise any errors. 3510 1.2 lneto 3511 1.2 lneto 3512 1.2 lneto 3513 1.2 lneto <hr><h3><a name="lua_absindex"><code>lua_absindex</code></a></h3><p> 3514 1.2 lneto <span class="apii">[-0, +0, –]</span> 3515 1.2 lneto <pre>int lua_absindex (lua_State *L, int idx);</pre> 3516 1.2 lneto 3517 1.2 lneto <p> 3518 1.4 mbalmer Converts the acceptable index <code>idx</code> 3519 1.4 mbalmer into an equivalent absolute index 3520 1.9 nikita (that is, one that does not depend on the stack size). 3521 1.2 lneto 3522 1.2 lneto 3523 1.1 mbalmer 3524 1.1 mbalmer 3525 1.1 mbalmer 3526 1.1 mbalmer <hr><h3><a name="lua_Alloc"><code>lua_Alloc</code></a></h3> 3527 1.1 mbalmer <pre>typedef void * (*lua_Alloc) (void *ud, 3528 1.1 mbalmer void *ptr, 3529 1.1 mbalmer size_t osize, 3530 1.1 mbalmer size_t nsize);</pre> 3531 1.1 mbalmer 3532 1.1 mbalmer <p> 3533 1.1 mbalmer The type of the memory-allocation function used by Lua states. 3534 1.1 mbalmer The allocator function must provide a 3535 1.1 mbalmer functionality similar to <code>realloc</code>, 3536 1.1 mbalmer but not exactly the same. 3537 1.1 mbalmer Its arguments are 3538 1.1 mbalmer <code>ud</code>, an opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>; 3539 1.1 mbalmer <code>ptr</code>, a pointer to the block being allocated/reallocated/freed; 3540 1.2 lneto <code>osize</code>, the original size of the block or some code about what 3541 1.2 lneto is being allocated; 3542 1.3 lneto and <code>nsize</code>, the new size of the block. 3543 1.2 lneto 3544 1.2 lneto 3545 1.2 lneto <p> 3546 1.2 lneto When <code>ptr</code> is not <code>NULL</code>, 3547 1.2 lneto <code>osize</code> is the size of the block pointed by <code>ptr</code>, 3548 1.2 lneto that is, the size given when it was allocated or reallocated. 3549 1.2 lneto 3550 1.2 lneto 3551 1.2 lneto <p> 3552 1.2 lneto When <code>ptr</code> is <code>NULL</code>, 3553 1.2 lneto <code>osize</code> encodes the kind of object that Lua is allocating. 3554 1.2 lneto <code>osize</code> is any of 3555 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>, 3556 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) 3557 1.2 lneto Lua is creating a new object of that type. 3558 1.2 lneto When <code>osize</code> is some other value, 3559 1.2 lneto Lua is allocating memory for something else. 3560 1.2 lneto 3561 1.2 lneto 3562 1.2 lneto <p> 3563 1.2 lneto Lua assumes the following behavior from the allocator function: 3564 1.2 lneto 3565 1.2 lneto 3566 1.2 lneto <p> 3567 1.2 lneto When <code>nsize</code> is zero, 3568 1.2 lneto the allocator must behave like <code>free</code> 3569 1.9 nikita and then return <code>NULL</code>. 3570 1.2 lneto 3571 1.2 lneto 3572 1.2 lneto <p> 3573 1.2 lneto When <code>nsize</code> is not zero, 3574 1.2 lneto the allocator must behave like <code>realloc</code>. 3575 1.9 nikita In particular, the allocator returns <code>NULL</code> 3576 1.2 lneto if and only if it cannot fulfill the request. 3577 1.1 mbalmer 3578 1.1 mbalmer 3579 1.1 mbalmer <p> 3580 1.1 mbalmer Here is a simple implementation for the allocator function. 3581 1.1 mbalmer It is used in the auxiliary library by <a href="#luaL_newstate"><code>luaL_newstate</code></a>. 3582 1.1 mbalmer 3583 1.1 mbalmer <pre> 3584 1.1 mbalmer static void *l_alloc (void *ud, void *ptr, size_t osize, 3585 1.1 mbalmer size_t nsize) { 3586 1.1 mbalmer (void)ud; (void)osize; /* not used */ 3587 1.1 mbalmer if (nsize == 0) { 3588 1.1 mbalmer free(ptr); 3589 1.1 mbalmer return NULL; 3590 1.1 mbalmer } 3591 1.1 mbalmer else 3592 1.1 mbalmer return realloc(ptr, nsize); 3593 1.1 mbalmer } 3594 1.1 mbalmer </pre><p> 3595 1.10 nikita Note that ISO C ensures 3596 1.1 mbalmer that <code>free(NULL)</code> has no effect and that 3597 1.3 lneto <code>realloc(NULL,size)</code> is equivalent to <code>malloc(size)</code>. 3598 1.1 mbalmer 3599 1.1 mbalmer 3600 1.1 mbalmer 3601 1.1 mbalmer 3602 1.1 mbalmer 3603 1.2 lneto <hr><h3><a name="lua_arith"><code>lua_arith</code></a></h3><p> 3604 1.2 lneto <span class="apii">[-(2|1), +1, <em>e</em>]</span> 3605 1.2 lneto <pre>void lua_arith (lua_State *L, int op);</pre> 3606 1.1 mbalmer 3607 1.1 mbalmer <p> 3608 1.2 lneto Performs an arithmetic or bitwise operation over the two values 3609 1.2 lneto (or one, in the case of negations) 3610 1.2 lneto at the top of the stack, 3611 1.9 nikita with the value on the top being the second operand, 3612 1.2 lneto pops these values, and pushes the result of the operation. 3613 1.2 lneto The function follows the semantics of the corresponding Lua operator 3614 1.2 lneto (that is, it may call metamethods). 3615 1.1 mbalmer 3616 1.1 mbalmer 3617 1.1 mbalmer <p> 3618 1.2 lneto The value of <code>op</code> must be one of the following constants: 3619 1.2 lneto 3620 1.2 lneto <ul> 3621 1.2 lneto 3622 1.2 lneto <li><b><a name="pdf-LUA_OPADD"><code>LUA_OPADD</code></a>: </b> performs addition (<code>+</code>)</li> 3623 1.2 lneto <li><b><a name="pdf-LUA_OPSUB"><code>LUA_OPSUB</code></a>: </b> performs subtraction (<code>-</code>)</li> 3624 1.2 lneto <li><b><a name="pdf-LUA_OPMUL"><code>LUA_OPMUL</code></a>: </b> performs multiplication (<code>*</code>)</li> 3625 1.2 lneto <li><b><a name="pdf-LUA_OPDIV"><code>LUA_OPDIV</code></a>: </b> performs float division (<code>/</code>)</li> 3626 1.3 lneto <li><b><a name="pdf-LUA_OPIDIV"><code>LUA_OPIDIV</code></a>: </b> performs floor division (<code>//</code>)</li> 3627 1.2 lneto <li><b><a name="pdf-LUA_OPMOD"><code>LUA_OPMOD</code></a>: </b> performs modulo (<code>%</code>)</li> 3628 1.2 lneto <li><b><a name="pdf-LUA_OPPOW"><code>LUA_OPPOW</code></a>: </b> performs exponentiation (<code>^</code>)</li> 3629 1.2 lneto <li><b><a name="pdf-LUA_OPUNM"><code>LUA_OPUNM</code></a>: </b> performs mathematical negation (unary <code>-</code>)</li> 3630 1.6 salazar <li><b><a name="pdf-LUA_OPBNOT"><code>LUA_OPBNOT</code></a>: </b> performs bitwise NOT (<code>~</code>)</li> 3631 1.6 salazar <li><b><a name="pdf-LUA_OPBAND"><code>LUA_OPBAND</code></a>: </b> performs bitwise AND (<code>&</code>)</li> 3632 1.6 salazar <li><b><a name="pdf-LUA_OPBOR"><code>LUA_OPBOR</code></a>: </b> performs bitwise OR (<code>|</code>)</li> 3633 1.6 salazar <li><b><a name="pdf-LUA_OPBXOR"><code>LUA_OPBXOR</code></a>: </b> performs bitwise exclusive OR (<code>~</code>)</li> 3634 1.2 lneto <li><b><a name="pdf-LUA_OPSHL"><code>LUA_OPSHL</code></a>: </b> performs left shift (<code><<</code>)</li> 3635 1.2 lneto <li><b><a name="pdf-LUA_OPSHR"><code>LUA_OPSHR</code></a>: </b> performs right shift (<code>>></code>)</li> 3636 1.2 lneto 3637 1.2 lneto </ul> 3638 1.2 lneto 3639 1.2 lneto 3640 1.2 lneto 3641 1.1 mbalmer 3642 1.2 lneto <hr><h3><a name="lua_atpanic"><code>lua_atpanic</code></a></h3><p> 3643 1.2 lneto <span class="apii">[-0, +0, –]</span> 3644 1.2 lneto <pre>lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);</pre> 3645 1.1 mbalmer 3646 1.1 mbalmer <p> 3647 1.9 nikita Sets a new panic function and returns the old one (see <a href="#4.4">§4.4</a>). 3648 1.1 mbalmer 3649 1.1 mbalmer 3650 1.1 mbalmer 3651 1.1 mbalmer 3652 1.1 mbalmer 3653 1.1 mbalmer <hr><h3><a name="lua_call"><code>lua_call</code></a></h3><p> 3654 1.2 lneto <span class="apii">[-(nargs+1), +nresults, <em>e</em>]</span> 3655 1.1 mbalmer <pre>void lua_call (lua_State *L, int nargs, int nresults);</pre> 3656 1.1 mbalmer 3657 1.1 mbalmer <p> 3658 1.1 mbalmer Calls a function. 3659 1.9 nikita Like regular Lua calls, 3660 1.9 nikita <code>lua_call</code> respects the <code>__call</code> metamethod. 3661 1.9 nikita So, here the word "function" 3662 1.9 nikita means any callable value. 3663 1.1 mbalmer 3664 1.1 mbalmer 3665 1.1 mbalmer <p> 3666 1.9 nikita To do a call you must use the following protocol: 3667 1.1 mbalmer first, the function to be called is pushed onto the stack; 3668 1.9 nikita then, the arguments to the call are pushed 3669 1.1 mbalmer in direct order; 3670 1.1 mbalmer that is, the first argument is pushed first. 3671 1.1 mbalmer Finally you call <a href="#lua_call"><code>lua_call</code></a>; 3672 1.1 mbalmer <code>nargs</code> is the number of arguments that you pushed onto the stack. 3673 1.9 nikita When the function returns, 3674 1.9 nikita all arguments and the function value are popped 3675 1.9 nikita and the call results are pushed onto the stack. 3676 1.1 mbalmer The number of results is adjusted to <code>nresults</code>, 3677 1.1 mbalmer unless <code>nresults</code> is <a name="pdf-LUA_MULTRET"><code>LUA_MULTRET</code></a>. 3678 1.7 mbalmer In this case, all results from the function are pushed; 3679 1.5 lneto Lua takes care that the returned values fit into the stack space, 3680 1.5 lneto but it does not ensure any extra space in the stack. 3681 1.1 mbalmer The function results are pushed onto the stack in direct order 3682 1.1 mbalmer (the first result is pushed first), 3683 1.1 mbalmer so that after the call the last result is on the top of the stack. 3684 1.1 mbalmer 3685 1.1 mbalmer 3686 1.1 mbalmer <p> 3687 1.9 nikita Any error while calling and running the function is propagated upwards 3688 1.1 mbalmer (with a <code>longjmp</code>). 3689 1.1 mbalmer 3690 1.1 mbalmer 3691 1.1 mbalmer <p> 3692 1.1 mbalmer The following example shows how the host program can do the 3693 1.1 mbalmer equivalent to this Lua code: 3694 1.1 mbalmer 3695 1.1 mbalmer <pre> 3696 1.1 mbalmer a = f("how", t.x, 14) 3697 1.1 mbalmer </pre><p> 3698 1.1 mbalmer Here it is in C: 3699 1.1 mbalmer 3700 1.1 mbalmer <pre> 3701 1.2 lneto lua_getglobal(L, "f"); /* function to be called */ 3702 1.3 lneto lua_pushliteral(L, "how"); /* 1st argument */ 3703 1.2 lneto lua_getglobal(L, "t"); /* table to be indexed */ 3704 1.1 mbalmer lua_getfield(L, -1, "x"); /* push result of t.x (2nd arg) */ 3705 1.1 mbalmer lua_remove(L, -2); /* remove 't' from the stack */ 3706 1.1 mbalmer lua_pushinteger(L, 14); /* 3rd argument */ 3707 1.1 mbalmer lua_call(L, 3, 1); /* call 'f' with 3 arguments and 1 result */ 3708 1.2 lneto lua_setglobal(L, "a"); /* set global 'a' */ 3709 1.1 mbalmer </pre><p> 3710 1.3 lneto Note that the code above is <em>balanced</em>: 3711 1.1 mbalmer at its end, the stack is back to its original configuration. 3712 1.1 mbalmer This is considered good programming practice. 3713 1.1 mbalmer 3714 1.1 mbalmer 3715 1.1 mbalmer 3716 1.1 mbalmer 3717 1.1 mbalmer 3718 1.2 lneto <hr><h3><a name="lua_callk"><code>lua_callk</code></a></h3><p> 3719 1.2 lneto <span class="apii">[-(nargs + 1), +nresults, <em>e</em>]</span> 3720 1.3 lneto <pre>void lua_callk (lua_State *L, 3721 1.3 lneto int nargs, 3722 1.3 lneto int nresults, 3723 1.3 lneto lua_KContext ctx, 3724 1.2 lneto lua_KFunction k);</pre> 3725 1.2 lneto 3726 1.2 lneto <p> 3727 1.2 lneto This function behaves exactly like <a href="#lua_call"><code>lua_call</code></a>, 3728 1.9 nikita but allows the called function to yield (see <a href="#4.5">§4.5</a>). 3729 1.2 lneto 3730 1.2 lneto 3731 1.2 lneto 3732 1.2 lneto 3733 1.2 lneto 3734 1.1 mbalmer <hr><h3><a name="lua_CFunction"><code>lua_CFunction</code></a></h3> 3735 1.1 mbalmer <pre>typedef int (*lua_CFunction) (lua_State *L);</pre> 3736 1.1 mbalmer 3737 1.1 mbalmer <p> 3738 1.1 mbalmer Type for C functions. 3739 1.1 mbalmer 3740 1.1 mbalmer 3741 1.1 mbalmer <p> 3742 1.1 mbalmer In order to communicate properly with Lua, 3743 1.1 mbalmer a C function must use the following protocol, 3744 1.1 mbalmer which defines the way parameters and results are passed: 3745 1.1 mbalmer a C function receives its arguments from Lua in its stack 3746 1.1 mbalmer in direct order (the first argument is pushed first). 3747 1.1 mbalmer So, when the function starts, 3748 1.1 mbalmer <code>lua_gettop(L)</code> returns the number of arguments received by the function. 3749 1.1 mbalmer The first argument (if any) is at index 1 3750 1.1 mbalmer and its last argument is at index <code>lua_gettop(L)</code>. 3751 1.1 mbalmer To return values to Lua, a C function just pushes them onto the stack, 3752 1.1 mbalmer in direct order (the first result is pushed first), 3753 1.9 nikita and returns in C the number of results. 3754 1.1 mbalmer Any other value in the stack below the results will be properly 3755 1.1 mbalmer discarded by Lua. 3756 1.1 mbalmer Like a Lua function, a C function called by Lua can also return 3757 1.1 mbalmer many results. 3758 1.1 mbalmer 3759 1.1 mbalmer 3760 1.1 mbalmer <p> 3761 1.1 mbalmer As an example, the following function receives a variable number 3762 1.4 mbalmer of numeric arguments and returns their average and their sum: 3763 1.1 mbalmer 3764 1.1 mbalmer <pre> 3765 1.1 mbalmer static int foo (lua_State *L) { 3766 1.1 mbalmer int n = lua_gettop(L); /* number of arguments */ 3767 1.3 lneto lua_Number sum = 0.0; 3768 1.1 mbalmer int i; 3769 1.1 mbalmer for (i = 1; i <= n; i++) { 3770 1.1 mbalmer if (!lua_isnumber(L, i)) { 3771 1.3 lneto lua_pushliteral(L, "incorrect argument"); 3772 1.1 mbalmer lua_error(L); 3773 1.1 mbalmer } 3774 1.1 mbalmer sum += lua_tonumber(L, i); 3775 1.1 mbalmer } 3776 1.1 mbalmer lua_pushnumber(L, sum/n); /* first result */ 3777 1.1 mbalmer lua_pushnumber(L, sum); /* second result */ 3778 1.1 mbalmer return 2; /* number of results */ 3779 1.1 mbalmer } 3780 1.1 mbalmer </pre> 3781 1.1 mbalmer 3782 1.1 mbalmer 3783 1.1 mbalmer 3784 1.1 mbalmer 3785 1.1 mbalmer <hr><h3><a name="lua_checkstack"><code>lua_checkstack</code></a></h3><p> 3786 1.2 lneto <span class="apii">[-0, +0, –]</span> 3787 1.3 lneto <pre>int lua_checkstack (lua_State *L, int n);</pre> 3788 1.1 mbalmer 3789 1.1 mbalmer <p> 3790 1.9 nikita Ensures that the stack has space for at least <code>n</code> extra elements, 3791 1.9 nikita that is, that you can safely push up to <code>n</code> values into it. 3792 1.2 lneto It returns false if it cannot fulfill the request, 3793 1.3 lneto either because it would cause the stack 3794 1.9 nikita to be greater than a fixed maximum size 3795 1.3 lneto (typically at least several thousand elements) or 3796 1.3 lneto because it cannot allocate memory for the extra space. 3797 1.1 mbalmer This function never shrinks the stack; 3798 1.9 nikita if the stack already has space for the extra elements, 3799 1.1 mbalmer it is left unchanged. 3800 1.1 mbalmer 3801 1.1 mbalmer 3802 1.1 mbalmer 3803 1.1 mbalmer 3804 1.1 mbalmer 3805 1.1 mbalmer <hr><h3><a name="lua_close"><code>lua_close</code></a></h3><p> 3806 1.2 lneto <span class="apii">[-0, +0, –]</span> 3807 1.1 mbalmer <pre>void lua_close (lua_State *L);</pre> 3808 1.1 mbalmer 3809 1.1 mbalmer <p> 3810 1.9 nikita Close all active to-be-closed variables in the main thread, 3811 1.9 nikita release all objects in the given Lua state 3812 1.9 nikita (calling the corresponding garbage-collection metamethods, if any), 3813 1.1 mbalmer and frees all dynamic memory used by this state. 3814 1.9 nikita 3815 1.9 nikita 3816 1.9 nikita <p> 3817 1.9 nikita On several platforms, you may not need to call this function, 3818 1.1 mbalmer because all resources are naturally released when the host program ends. 3819 1.2 lneto On the other hand, long-running programs that create multiple states, 3820 1.2 lneto such as daemons or web servers, 3821 1.3 lneto will probably need to close states as soon as they are not needed. 3822 1.2 lneto 3823 1.1 mbalmer 3824 1.1 mbalmer 3825 1.1 mbalmer 3826 1.1 mbalmer 3827 1.9 nikita <hr><h3><a name="lua_closeslot"><code>lua_closeslot</code></a></h3><p> 3828 1.9 nikita <span class="apii">[-0, +0, <em>e</em>]</span> 3829 1.9 nikita <pre>void lua_closeslot (lua_State *L, int index);</pre> 3830 1.9 nikita 3831 1.9 nikita <p> 3832 1.9 nikita Close the to-be-closed slot at the given index and set its value to <b>nil</b>. 3833 1.9 nikita The index must be the last index previously marked to be closed 3834 1.9 nikita (see <a href="#lua_toclose"><code>lua_toclose</code></a>) that is still active (that is, not closed yet). 3835 1.9 nikita 3836 1.9 nikita 3837 1.9 nikita <p> 3838 1.9 nikita A <code>__close</code> metamethod cannot yield 3839 1.9 nikita when called through this function. 3840 1.9 nikita 3841 1.9 nikita 3842 1.9 nikita <p> 3843 1.10 nikita (This function was introduced in release 5.4.3.) 3844 1.10 nikita 3845 1.10 nikita 3846 1.10 nikita 3847 1.10 nikita 3848 1.10 nikita 3849 1.10 nikita <hr><h3><a name="lua_closethread"><code>lua_closethread</code></a></h3><p> 3850 1.10 nikita <span class="apii">[-0, +?, –]</span> 3851 1.10 nikita <pre>int lua_closethread (lua_State *L, lua_State *from);</pre> 3852 1.10 nikita 3853 1.10 nikita <p> 3854 1.10 nikita Resets a thread, cleaning its call stack and closing all pending 3855 1.10 nikita to-be-closed variables. 3856 1.10 nikita Returns a status code: 3857 1.10 nikita <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> for no errors in the thread 3858 1.10 nikita (either the original error that stopped the thread or 3859 1.10 nikita errors in closing methods), 3860 1.10 nikita or an error status otherwise. 3861 1.10 nikita In case of error, 3862 1.10 nikita leaves the error object on the top of the stack. 3863 1.10 nikita 3864 1.10 nikita 3865 1.10 nikita <p> 3866 1.10 nikita The parameter <code>from</code> represents the coroutine that is resetting <code>L</code>. 3867 1.10 nikita If there is no such coroutine, 3868 1.10 nikita this parameter can be <code>NULL</code>. 3869 1.10 nikita 3870 1.10 nikita 3871 1.10 nikita <p> 3872 1.10 nikita (This function was introduced in release 5.4.6.) 3873 1.9 nikita 3874 1.9 nikita 3875 1.9 nikita 3876 1.9 nikita 3877 1.9 nikita 3878 1.2 lneto <hr><h3><a name="lua_compare"><code>lua_compare</code></a></h3><p> 3879 1.2 lneto <span class="apii">[-0, +0, <em>e</em>]</span> 3880 1.2 lneto <pre>int lua_compare (lua_State *L, int index1, int index2, int op);</pre> 3881 1.2 lneto 3882 1.2 lneto <p> 3883 1.2 lneto Compares two Lua values. 3884 1.2 lneto Returns 1 if the value at index <code>index1</code> satisfies <code>op</code> 3885 1.2 lneto when compared with the value at index <code>index2</code>, 3886 1.2 lneto following the semantics of the corresponding Lua operator 3887 1.2 lneto (that is, it may call metamethods). 3888 1.2 lneto Otherwise returns 0. 3889 1.3 lneto Also returns 0 if any of the indices is not valid. 3890 1.2 lneto 3891 1.2 lneto 3892 1.2 lneto <p> 3893 1.2 lneto The value of <code>op</code> must be one of the following constants: 3894 1.2 lneto 3895 1.2 lneto <ul> 3896 1.2 lneto 3897 1.2 lneto <li><b><a name="pdf-LUA_OPEQ"><code>LUA_OPEQ</code></a>: </b> compares for equality (<code>==</code>)</li> 3898 1.2 lneto <li><b><a name="pdf-LUA_OPLT"><code>LUA_OPLT</code></a>: </b> compares for less than (<code><</code>)</li> 3899 1.2 lneto <li><b><a name="pdf-LUA_OPLE"><code>LUA_OPLE</code></a>: </b> compares for less or equal (<code><=</code>)</li> 3900 1.2 lneto 3901 1.2 lneto </ul> 3902 1.2 lneto 3903 1.2 lneto 3904 1.2 lneto 3905 1.1 mbalmer 3906 1.1 mbalmer <hr><h3><a name="lua_concat"><code>lua_concat</code></a></h3><p> 3907 1.1 mbalmer <span class="apii">[-n, +1, <em>e</em>]</span> 3908 1.1 mbalmer <pre>void lua_concat (lua_State *L, int n);</pre> 3909 1.1 mbalmer 3910 1.1 mbalmer <p> 3911 1.1 mbalmer Concatenates the <code>n</code> values at the top of the stack, 3912 1.9 nikita pops them, and leaves the result on the top. 3913 1.1 mbalmer If <code>n</code> is 1, the result is the single value on the stack 3914 1.1 mbalmer (that is, the function does nothing); 3915 1.1 mbalmer if <code>n</code> is 0, the result is the empty string. 3916 1.1 mbalmer Concatenation is performed following the usual semantics of Lua 3917 1.2 lneto (see <a href="#3.4.6">§3.4.6</a>). 3918 1.1 mbalmer 3919 1.1 mbalmer 3920 1.1 mbalmer 3921 1.1 mbalmer 3922 1.1 mbalmer 3923 1.2 lneto <hr><h3><a name="lua_copy"><code>lua_copy</code></a></h3><p> 3924 1.2 lneto <span class="apii">[-0, +0, –]</span> 3925 1.2 lneto <pre>void lua_copy (lua_State *L, int fromidx, int toidx);</pre> 3926 1.1 mbalmer 3927 1.1 mbalmer <p> 3928 1.3 lneto Copies the element at index <code>fromidx</code> 3929 1.3 lneto into the valid index <code>toidx</code>, 3930 1.3 lneto replacing the value at that position. 3931 1.3 lneto Values at other positions are not affected. 3932 1.1 mbalmer 3933 1.1 mbalmer 3934 1.1 mbalmer 3935 1.1 mbalmer 3936 1.1 mbalmer 3937 1.1 mbalmer <hr><h3><a name="lua_createtable"><code>lua_createtable</code></a></h3><p> 3938 1.5 lneto <span class="apii">[-0, +1, <em>m</em>]</span> 3939 1.1 mbalmer <pre>void lua_createtable (lua_State *L, int narr, int nrec);</pre> 3940 1.1 mbalmer 3941 1.1 mbalmer <p> 3942 1.1 mbalmer Creates a new empty table and pushes it onto the stack. 3943 1.2 lneto Parameter <code>narr</code> is a hint for how many elements the table 3944 1.2 lneto will have as a sequence; 3945 1.2 lneto parameter <code>nrec</code> is a hint for how many other elements 3946 1.1 mbalmer the table will have. 3947 1.2 lneto Lua may use these hints to preallocate memory for the new table. 3948 1.9 nikita This preallocation may help performance when you know in advance 3949 1.2 lneto how many elements the table will have. 3950 1.1 mbalmer Otherwise you can use the function <a href="#lua_newtable"><code>lua_newtable</code></a>. 3951 1.1 mbalmer 3952 1.1 mbalmer 3953 1.1 mbalmer 3954 1.1 mbalmer 3955 1.1 mbalmer 3956 1.1 mbalmer <hr><h3><a name="lua_dump"><code>lua_dump</code></a></h3><p> 3957 1.5 lneto <span class="apii">[-0, +0, –]</span> 3958 1.2 lneto <pre>int lua_dump (lua_State *L, 3959 1.2 lneto lua_Writer writer, 3960 1.2 lneto void *data, 3961 1.2 lneto int strip);</pre> 3962 1.1 mbalmer 3963 1.1 mbalmer <p> 3964 1.1 mbalmer Dumps a function as a binary chunk. 3965 1.1 mbalmer Receives a Lua function on the top of the stack 3966 1.1 mbalmer and produces a binary chunk that, 3967 1.1 mbalmer if loaded again, 3968 1.1 mbalmer results in a function equivalent to the one dumped. 3969 1.1 mbalmer As it produces parts of the chunk, 3970 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>) 3971 1.1 mbalmer with the given <code>data</code> 3972 1.1 mbalmer to write them. 3973 1.1 mbalmer 3974 1.1 mbalmer 3975 1.1 mbalmer <p> 3976 1.2 lneto If <code>strip</code> is true, 3977 1.4 mbalmer the binary representation may not include all debug information 3978 1.4 mbalmer about the function, 3979 1.4 mbalmer to save space. 3980 1.2 lneto 3981 1.2 lneto 3982 1.2 lneto <p> 3983 1.1 mbalmer The value returned is the error code returned by the last 3984 1.1 mbalmer call to the writer; 3985 1.1 mbalmer 0 means no errors. 3986 1.1 mbalmer 3987 1.1 mbalmer 3988 1.1 mbalmer <p> 3989 1.1 mbalmer This function does not pop the Lua function from the stack. 3990 1.1 mbalmer 3991 1.1 mbalmer 3992 1.1 mbalmer 3993 1.1 mbalmer 3994 1.1 mbalmer 3995 1.1 mbalmer <hr><h3><a name="lua_error"><code>lua_error</code></a></h3><p> 3996 1.1 mbalmer <span class="apii">[-1, +0, <em>v</em>]</span> 3997 1.1 mbalmer <pre>int lua_error (lua_State *L);</pre> 3998 1.1 mbalmer 3999 1.1 mbalmer <p> 4000 1.9 nikita Raises a Lua error, 4001 1.9 nikita using the value on the top of the stack as the error object. 4002 1.1 mbalmer This function does a long jump, 4003 1.2 lneto and therefore never returns 4004 1.1 mbalmer (see <a href="#luaL_error"><code>luaL_error</code></a>). 4005 1.1 mbalmer 4006 1.1 mbalmer 4007 1.1 mbalmer 4008 1.1 mbalmer 4009 1.1 mbalmer 4010 1.1 mbalmer <hr><h3><a name="lua_gc"><code>lua_gc</code></a></h3><p> 4011 1.9 nikita <span class="apii">[-0, +0, –]</span> 4012 1.9 nikita <pre>int lua_gc (lua_State *L, int what, ...);</pre> 4013 1.1 mbalmer 4014 1.1 mbalmer <p> 4015 1.1 mbalmer Controls the garbage collector. 4016 1.1 mbalmer 4017 1.1 mbalmer 4018 1.1 mbalmer <p> 4019 1.1 mbalmer This function performs several tasks, 4020 1.9 nikita according to the value of the parameter <code>what</code>. 4021 1.9 nikita For options that need extra arguments, 4022 1.9 nikita they are listed after the option. 4023 1.1 mbalmer 4024 1.1 mbalmer <ul> 4025 1.1 mbalmer 4026 1.9 nikita <li><b><code>LUA_GCCOLLECT</code>: </b> 4027 1.9 nikita Performs a full garbage-collection cycle. 4028 1.9 nikita </li> 4029 1.9 nikita 4030 1.2 lneto <li><b><code>LUA_GCSTOP</code>: </b> 4031 1.9 nikita Stops the garbage collector. 4032 1.1 mbalmer </li> 4033 1.1 mbalmer 4034 1.2 lneto <li><b><code>LUA_GCRESTART</code>: </b> 4035 1.9 nikita Restarts the garbage collector. 4036 1.1 mbalmer </li> 4037 1.1 mbalmer 4038 1.2 lneto <li><b><code>LUA_GCCOUNT</code>: </b> 4039 1.9 nikita Returns the current amount of memory (in Kbytes) in use by Lua. 4040 1.1 mbalmer </li> 4041 1.1 mbalmer 4042 1.2 lneto <li><b><code>LUA_GCCOUNTB</code>: </b> 4043 1.9 nikita Returns the remainder of dividing the current amount of bytes of 4044 1.1 mbalmer memory in use by Lua by 1024. 4045 1.1 mbalmer </li> 4046 1.1 mbalmer 4047 1.9 nikita <li><b><code>LUA_GCSTEP</code> <code>(int stepsize)</code>: </b> 4048 1.9 nikita Performs an incremental step of garbage collection, 4049 1.9 nikita corresponding to the allocation of <code>stepsize</code> Kbytes. 4050 1.1 mbalmer </li> 4051 1.1 mbalmer 4052 1.9 nikita <li><b><code>LUA_GCISRUNNING</code>: </b> 4053 1.9 nikita Returns a boolean that tells whether the collector is running 4054 1.9 nikita (i.e., not stopped). 4055 1.1 mbalmer </li> 4056 1.1 mbalmer 4057 1.9 nikita <li><b><code>LUA_GCINC</code> (int pause, int stepmul, stepsize): </b> 4058 1.9 nikita Changes the collector to incremental mode 4059 1.9 nikita with the given parameters (see <a href="#2.5.1">§2.5.1</a>). 4060 1.9 nikita Returns the previous mode (<code>LUA_GCGEN</code> or <code>LUA_GCINC</code>). 4061 1.2 lneto </li> 4062 1.2 lneto 4063 1.9 nikita <li><b><code>LUA_GCGEN</code> (int minormul, int majormul): </b> 4064 1.9 nikita Changes the collector to generational mode 4065 1.9 nikita with the given parameters (see <a href="#2.5.2">§2.5.2</a>). 4066 1.9 nikita Returns the previous mode (<code>LUA_GCGEN</code> or <code>LUA_GCINC</code>). 4067 1.1 mbalmer </li> 4068 1.1 mbalmer 4069 1.9 nikita </ul><p> 4070 1.9 nikita For more details about these options, 4071 1.9 nikita see <a href="#pdf-collectgarbage"><code>collectgarbage</code></a>. 4072 1.9 nikita 4073 1.1 mbalmer 4074 1.2 lneto <p> 4075 1.9 nikita This function should not be called by a finalizer. 4076 1.2 lneto 4077 1.2 lneto 4078 1.1 mbalmer 4079 1.1 mbalmer 4080 1.1 mbalmer 4081 1.1 mbalmer <hr><h3><a name="lua_getallocf"><code>lua_getallocf</code></a></h3><p> 4082 1.2 lneto <span class="apii">[-0, +0, –]</span> 4083 1.1 mbalmer <pre>lua_Alloc lua_getallocf (lua_State *L, void **ud);</pre> 4084 1.1 mbalmer 4085 1.1 mbalmer <p> 4086 1.1 mbalmer Returns the memory-allocation function of a given state. 4087 1.1 mbalmer If <code>ud</code> is not <code>NULL</code>, Lua stores in <code>*ud</code> the 4088 1.3 lneto opaque pointer given when the memory-allocator function was set. 4089 1.1 mbalmer 4090 1.1 mbalmer 4091 1.1 mbalmer 4092 1.1 mbalmer 4093 1.1 mbalmer 4094 1.1 mbalmer <hr><h3><a name="lua_getfield"><code>lua_getfield</code></a></h3><p> 4095 1.1 mbalmer <span class="apii">[-0, +1, <em>e</em>]</span> 4096 1.2 lneto <pre>int lua_getfield (lua_State *L, int index, const char *k);</pre> 4097 1.1 mbalmer 4098 1.1 mbalmer <p> 4099 1.1 mbalmer Pushes onto the stack the value <code>t[k]</code>, 4100 1.2 lneto where <code>t</code> is the value at the given index. 4101 1.1 mbalmer As in Lua, this function may trigger a metamethod 4102 1.2 lneto for the "index" event (see <a href="#2.4">§2.4</a>). 4103 1.2 lneto 4104 1.2 lneto 4105 1.2 lneto <p> 4106 1.2 lneto Returns the type of the pushed value. 4107 1.1 mbalmer 4108 1.1 mbalmer 4109 1.1 mbalmer 4110 1.1 mbalmer 4111 1.1 mbalmer 4112 1.3 lneto <hr><h3><a name="lua_getextraspace"><code>lua_getextraspace</code></a></h3><p> 4113 1.3 lneto <span class="apii">[-0, +0, –]</span> 4114 1.3 lneto <pre>void *lua_getextraspace (lua_State *L);</pre> 4115 1.3 lneto 4116 1.3 lneto <p> 4117 1.3 lneto Returns a pointer to a raw memory area associated with the 4118 1.3 lneto given Lua state. 4119 1.3 lneto The application can use this area for any purpose; 4120 1.3 lneto Lua does not use it for anything. 4121 1.3 lneto 4122 1.3 lneto 4123 1.3 lneto <p> 4124 1.3 lneto Each new thread has this area initialized with a copy 4125 1.3 lneto of the area of the main thread. 4126 1.3 lneto 4127 1.3 lneto 4128 1.3 lneto <p> 4129 1.3 lneto By default, this area has the size of a pointer to void, 4130 1.3 lneto but you can recompile Lua with a different size for this area. 4131 1.3 lneto (See <code>LUA_EXTRASPACE</code> in <code>luaconf.h</code>.) 4132 1.3 lneto 4133 1.3 lneto 4134 1.3 lneto 4135 1.3 lneto 4136 1.3 lneto 4137 1.1 mbalmer <hr><h3><a name="lua_getglobal"><code>lua_getglobal</code></a></h3><p> 4138 1.1 mbalmer <span class="apii">[-0, +1, <em>e</em>]</span> 4139 1.2 lneto <pre>int lua_getglobal (lua_State *L, const char *name);</pre> 4140 1.1 mbalmer 4141 1.1 mbalmer <p> 4142 1.1 mbalmer Pushes onto the stack the value of the global <code>name</code>. 4143 1.2 lneto Returns the type of that value. 4144 1.1 mbalmer 4145 1.1 mbalmer 4146 1.1 mbalmer 4147 1.1 mbalmer 4148 1.1 mbalmer 4149 1.3 lneto <hr><h3><a name="lua_geti"><code>lua_geti</code></a></h3><p> 4150 1.3 lneto <span class="apii">[-0, +1, <em>e</em>]</span> 4151 1.3 lneto <pre>int lua_geti (lua_State *L, int index, lua_Integer i);</pre> 4152 1.3 lneto 4153 1.3 lneto <p> 4154 1.3 lneto Pushes onto the stack the value <code>t[i]</code>, 4155 1.3 lneto where <code>t</code> is the value at the given index. 4156 1.3 lneto As in Lua, this function may trigger a metamethod 4157 1.3 lneto for the "index" event (see <a href="#2.4">§2.4</a>). 4158 1.3 lneto 4159 1.3 lneto 4160 1.3 lneto <p> 4161 1.3 lneto Returns the type of the pushed value. 4162 1.3 lneto 4163 1.3 lneto 4164 1.3 lneto 4165 1.3 lneto 4166 1.3 lneto 4167 1.1 mbalmer <hr><h3><a name="lua_getmetatable"><code>lua_getmetatable</code></a></h3><p> 4168 1.2 lneto <span class="apii">[-0, +(0|1), –]</span> 4169 1.1 mbalmer <pre>int lua_getmetatable (lua_State *L, int index);</pre> 4170 1.1 mbalmer 4171 1.1 mbalmer <p> 4172 1.3 lneto If the value at the given index has a metatable, 4173 1.3 lneto the function pushes that metatable onto the stack and returns 1. 4174 1.3 lneto Otherwise, 4175 1.1 mbalmer the function returns 0 and pushes nothing on the stack. 4176 1.1 mbalmer 4177 1.1 mbalmer 4178 1.1 mbalmer 4179 1.1 mbalmer 4180 1.1 mbalmer 4181 1.1 mbalmer <hr><h3><a name="lua_gettable"><code>lua_gettable</code></a></h3><p> 4182 1.1 mbalmer <span class="apii">[-1, +1, <em>e</em>]</span> 4183 1.2 lneto <pre>int lua_gettable (lua_State *L, int index);</pre> 4184 1.1 mbalmer 4185 1.1 mbalmer <p> 4186 1.1 mbalmer Pushes onto the stack the value <code>t[k]</code>, 4187 1.2 lneto where <code>t</code> is the value at the given index 4188 1.9 nikita and <code>k</code> is the value on the top of the stack. 4189 1.1 mbalmer 4190 1.1 mbalmer 4191 1.1 mbalmer <p> 4192 1.3 lneto This function pops the key from the stack, 4193 1.3 lneto pushing the resulting value in its place. 4194 1.1 mbalmer As in Lua, this function may trigger a metamethod 4195 1.2 lneto for the "index" event (see <a href="#2.4">§2.4</a>). 4196 1.2 lneto 4197 1.2 lneto 4198 1.2 lneto <p> 4199 1.2 lneto Returns the type of the pushed value. 4200 1.1 mbalmer 4201 1.1 mbalmer 4202 1.1 mbalmer 4203 1.1 mbalmer 4204 1.1 mbalmer 4205 1.1 mbalmer <hr><h3><a name="lua_gettop"><code>lua_gettop</code></a></h3><p> 4206 1.2 lneto <span class="apii">[-0, +0, –]</span> 4207 1.1 mbalmer <pre>int lua_gettop (lua_State *L);</pre> 4208 1.1 mbalmer 4209 1.1 mbalmer <p> 4210 1.1 mbalmer Returns the index of the top element in the stack. 4211 1.1 mbalmer Because indices start at 1, 4212 1.3 lneto this result is equal to the number of elements in the stack; 4213 1.3 lneto in particular, 0 means an empty stack. 4214 1.1 mbalmer 4215 1.1 mbalmer 4216 1.1 mbalmer 4217 1.1 mbalmer 4218 1.1 mbalmer 4219 1.9 nikita <hr><h3><a name="lua_getiuservalue"><code>lua_getiuservalue</code></a></h3><p> 4220 1.2 lneto <span class="apii">[-0, +1, –]</span> 4221 1.9 nikita <pre>int lua_getiuservalue (lua_State *L, int index, int n);</pre> 4222 1.2 lneto 4223 1.2 lneto <p> 4224 1.9 nikita Pushes onto the stack the <code>n</code>-th user value associated with the 4225 1.9 nikita full userdata at the given index and 4226 1.9 nikita returns the type of the pushed value. 4227 1.2 lneto 4228 1.2 lneto 4229 1.2 lneto <p> 4230 1.9 nikita If the userdata does not have that value, 4231 1.9 nikita pushes <b>nil</b> and returns <a href="#pdf-LUA_TNONE"><code>LUA_TNONE</code></a>. 4232 1.2 lneto 4233 1.2 lneto 4234 1.2 lneto 4235 1.2 lneto 4236 1.2 lneto 4237 1.1 mbalmer <hr><h3><a name="lua_insert"><code>lua_insert</code></a></h3><p> 4238 1.2 lneto <span class="apii">[-1, +1, –]</span> 4239 1.1 mbalmer <pre>void lua_insert (lua_State *L, int index);</pre> 4240 1.1 mbalmer 4241 1.1 mbalmer <p> 4242 1.1 mbalmer Moves the top element into the given valid index, 4243 1.1 mbalmer shifting up the elements above this index to open space. 4244 1.2 lneto This function cannot be called with a pseudo-index, 4245 1.1 mbalmer because a pseudo-index is not an actual stack position. 4246 1.1 mbalmer 4247 1.1 mbalmer 4248 1.1 mbalmer 4249 1.1 mbalmer 4250 1.1 mbalmer 4251 1.1 mbalmer <hr><h3><a name="lua_Integer"><code>lua_Integer</code></a></h3> 4252 1.2 lneto <pre>typedef ... lua_Integer;</pre> 4253 1.1 mbalmer 4254 1.1 mbalmer <p> 4255 1.2 lneto The type of integers in Lua. 4256 1.1 mbalmer 4257 1.1 mbalmer 4258 1.1 mbalmer <p> 4259 1.3 lneto By default this type is <code>long long</code>, 4260 1.2 lneto (usually a 64-bit two-complement integer), 4261 1.3 lneto but that can be changed to <code>long</code> or <code>int</code> 4262 1.2 lneto (usually a 32-bit two-complement integer). 4263 1.4 mbalmer (See <code>LUA_INT_TYPE</code> in <code>luaconf.h</code>.) 4264 1.2 lneto 4265 1.2 lneto 4266 1.2 lneto <p> 4267 1.2 lneto Lua also defines the constants 4268 1.2 lneto <a name="pdf-LUA_MININTEGER"><code>LUA_MININTEGER</code></a> and <a name="pdf-LUA_MAXINTEGER"><code>LUA_MAXINTEGER</code></a>, 4269 1.2 lneto with the minimum and the maximum values that fit in this type. 4270 1.1 mbalmer 4271 1.1 mbalmer 4272 1.1 mbalmer 4273 1.1 mbalmer 4274 1.1 mbalmer 4275 1.1 mbalmer <hr><h3><a name="lua_isboolean"><code>lua_isboolean</code></a></h3><p> 4276 1.2 lneto <span class="apii">[-0, +0, –]</span> 4277 1.1 mbalmer <pre>int lua_isboolean (lua_State *L, int index);</pre> 4278 1.1 mbalmer 4279 1.1 mbalmer <p> 4280 1.2 lneto Returns 1 if the value at the given index is a boolean, 4281 1.1 mbalmer and 0 otherwise. 4282 1.1 mbalmer 4283 1.1 mbalmer 4284 1.1 mbalmer 4285 1.1 mbalmer 4286 1.1 mbalmer 4287 1.1 mbalmer <hr><h3><a name="lua_iscfunction"><code>lua_iscfunction</code></a></h3><p> 4288 1.2 lneto <span class="apii">[-0, +0, –]</span> 4289 1.1 mbalmer <pre>int lua_iscfunction (lua_State *L, int index);</pre> 4290 1.1 mbalmer 4291 1.1 mbalmer <p> 4292 1.2 lneto Returns 1 if the value at the given index is a C function, 4293 1.1 mbalmer and 0 otherwise. 4294 1.1 mbalmer 4295 1.1 mbalmer 4296 1.1 mbalmer 4297 1.1 mbalmer 4298 1.1 mbalmer 4299 1.1 mbalmer <hr><h3><a name="lua_isfunction"><code>lua_isfunction</code></a></h3><p> 4300 1.2 lneto <span class="apii">[-0, +0, –]</span> 4301 1.1 mbalmer <pre>int lua_isfunction (lua_State *L, int index);</pre> 4302 1.1 mbalmer 4303 1.1 mbalmer <p> 4304 1.2 lneto Returns 1 if the value at the given index is a function 4305 1.1 mbalmer (either C or Lua), and 0 otherwise. 4306 1.1 mbalmer 4307 1.1 mbalmer 4308 1.1 mbalmer 4309 1.1 mbalmer 4310 1.1 mbalmer 4311 1.2 lneto <hr><h3><a name="lua_isinteger"><code>lua_isinteger</code></a></h3><p> 4312 1.2 lneto <span class="apii">[-0, +0, –]</span> 4313 1.2 lneto <pre>int lua_isinteger (lua_State *L, int index);</pre> 4314 1.2 lneto 4315 1.2 lneto <p> 4316 1.2 lneto Returns 1 if the value at the given index is an integer 4317 1.2 lneto (that is, the value is a number and is represented as an integer), 4318 1.2 lneto and 0 otherwise. 4319 1.2 lneto 4320 1.2 lneto 4321 1.2 lneto 4322 1.2 lneto 4323 1.2 lneto 4324 1.1 mbalmer <hr><h3><a name="lua_islightuserdata"><code>lua_islightuserdata</code></a></h3><p> 4325 1.2 lneto <span class="apii">[-0, +0, –]</span> 4326 1.1 mbalmer <pre>int lua_islightuserdata (lua_State *L, int index);</pre> 4327 1.1 mbalmer 4328 1.1 mbalmer <p> 4329 1.2 lneto Returns 1 if the value at the given index is a light userdata, 4330 1.1 mbalmer and 0 otherwise. 4331 1.1 mbalmer 4332 1.1 mbalmer 4333 1.1 mbalmer 4334 1.1 mbalmer 4335 1.1 mbalmer 4336 1.1 mbalmer <hr><h3><a name="lua_isnil"><code>lua_isnil</code></a></h3><p> 4337 1.2 lneto <span class="apii">[-0, +0, –]</span> 4338 1.1 mbalmer <pre>int lua_isnil (lua_State *L, int index);</pre> 4339 1.1 mbalmer 4340 1.1 mbalmer <p> 4341 1.2 lneto Returns 1 if the value at the given index is <b>nil</b>, 4342 1.1 mbalmer and 0 otherwise. 4343 1.1 mbalmer 4344 1.1 mbalmer 4345 1.1 mbalmer 4346 1.1 mbalmer 4347 1.1 mbalmer 4348 1.1 mbalmer <hr><h3><a name="lua_isnone"><code>lua_isnone</code></a></h3><p> 4349 1.2 lneto <span class="apii">[-0, +0, –]</span> 4350 1.1 mbalmer <pre>int lua_isnone (lua_State *L, int index);</pre> 4351 1.1 mbalmer 4352 1.1 mbalmer <p> 4353 1.2 lneto Returns 1 if the given index is not valid, 4354 1.1 mbalmer and 0 otherwise. 4355 1.1 mbalmer 4356 1.1 mbalmer 4357 1.1 mbalmer 4358 1.1 mbalmer 4359 1.1 mbalmer 4360 1.1 mbalmer <hr><h3><a name="lua_isnoneornil"><code>lua_isnoneornil</code></a></h3><p> 4361 1.2 lneto <span class="apii">[-0, +0, –]</span> 4362 1.1 mbalmer <pre>int lua_isnoneornil (lua_State *L, int index);</pre> 4363 1.1 mbalmer 4364 1.1 mbalmer <p> 4365 1.2 lneto Returns 1 if the given index is not valid 4366 1.1 mbalmer or if the value at this index is <b>nil</b>, 4367 1.1 mbalmer and 0 otherwise. 4368 1.1 mbalmer 4369 1.1 mbalmer 4370 1.1 mbalmer 4371 1.1 mbalmer 4372 1.1 mbalmer 4373 1.1 mbalmer <hr><h3><a name="lua_isnumber"><code>lua_isnumber</code></a></h3><p> 4374 1.2 lneto <span class="apii">[-0, +0, –]</span> 4375 1.1 mbalmer <pre>int lua_isnumber (lua_State *L, int index);</pre> 4376 1.1 mbalmer 4377 1.1 mbalmer <p> 4378 1.2 lneto Returns 1 if the value at the given index is a number 4379 1.1 mbalmer or a string convertible to a number, 4380 1.1 mbalmer and 0 otherwise. 4381 1.1 mbalmer 4382 1.1 mbalmer 4383 1.1 mbalmer 4384 1.1 mbalmer 4385 1.1 mbalmer 4386 1.1 mbalmer <hr><h3><a name="lua_isstring"><code>lua_isstring</code></a></h3><p> 4387 1.2 lneto <span class="apii">[-0, +0, –]</span> 4388 1.1 mbalmer <pre>int lua_isstring (lua_State *L, int index);</pre> 4389 1.1 mbalmer 4390 1.1 mbalmer <p> 4391 1.2 lneto Returns 1 if the value at the given index is a string 4392 1.1 mbalmer or a number (which is always convertible to a string), 4393 1.1 mbalmer and 0 otherwise. 4394 1.1 mbalmer 4395 1.1 mbalmer 4396 1.1 mbalmer 4397 1.1 mbalmer 4398 1.1 mbalmer 4399 1.1 mbalmer <hr><h3><a name="lua_istable"><code>lua_istable</code></a></h3><p> 4400 1.2 lneto <span class="apii">[-0, +0, –]</span> 4401 1.1 mbalmer <pre>int lua_istable (lua_State *L, int index);</pre> 4402 1.1 mbalmer 4403 1.1 mbalmer <p> 4404 1.2 lneto Returns 1 if the value at the given index is a table, 4405 1.1 mbalmer and 0 otherwise. 4406 1.1 mbalmer 4407 1.1 mbalmer 4408 1.1 mbalmer 4409 1.1 mbalmer 4410 1.1 mbalmer 4411 1.1 mbalmer <hr><h3><a name="lua_isthread"><code>lua_isthread</code></a></h3><p> 4412 1.2 lneto <span class="apii">[-0, +0, –]</span> 4413 1.1 mbalmer <pre>int lua_isthread (lua_State *L, int index);</pre> 4414 1.1 mbalmer 4415 1.1 mbalmer <p> 4416 1.2 lneto Returns 1 if the value at the given index is a thread, 4417 1.1 mbalmer and 0 otherwise. 4418 1.1 mbalmer 4419 1.1 mbalmer 4420 1.1 mbalmer 4421 1.1 mbalmer 4422 1.1 mbalmer 4423 1.1 mbalmer <hr><h3><a name="lua_isuserdata"><code>lua_isuserdata</code></a></h3><p> 4424 1.2 lneto <span class="apii">[-0, +0, –]</span> 4425 1.1 mbalmer <pre>int lua_isuserdata (lua_State *L, int index);</pre> 4426 1.1 mbalmer 4427 1.1 mbalmer <p> 4428 1.2 lneto Returns 1 if the value at the given index is a userdata 4429 1.1 mbalmer (either full or light), and 0 otherwise. 4430 1.1 mbalmer 4431 1.1 mbalmer 4432 1.1 mbalmer 4433 1.1 mbalmer 4434 1.1 mbalmer 4435 1.2 lneto <hr><h3><a name="lua_isyieldable"><code>lua_isyieldable</code></a></h3><p> 4436 1.2 lneto <span class="apii">[-0, +0, –]</span> 4437 1.2 lneto <pre>int lua_isyieldable (lua_State *L);</pre> 4438 1.2 lneto 4439 1.2 lneto <p> 4440 1.2 lneto Returns 1 if the given coroutine can yield, 4441 1.2 lneto and 0 otherwise. 4442 1.2 lneto 4443 1.2 lneto 4444 1.2 lneto 4445 1.2 lneto 4446 1.2 lneto 4447 1.3 lneto <hr><h3><a name="lua_KContext"><code>lua_KContext</code></a></h3> 4448 1.3 lneto <pre>typedef ... lua_KContext;</pre> 4449 1.3 lneto 4450 1.3 lneto <p> 4451 1.3 lneto The type for continuation-function contexts. 4452 1.4 mbalmer It must be a numeric type. 4453 1.3 lneto This type is defined as <code>intptr_t</code> 4454 1.3 lneto when <code>intptr_t</code> is available, 4455 1.3 lneto so that it can store pointers too. 4456 1.3 lneto Otherwise, it is defined as <code>ptrdiff_t</code>. 4457 1.3 lneto 4458 1.3 lneto 4459 1.3 lneto 4460 1.3 lneto 4461 1.3 lneto 4462 1.2 lneto <hr><h3><a name="lua_KFunction"><code>lua_KFunction</code></a></h3> 4463 1.3 lneto <pre>typedef int (*lua_KFunction) (lua_State *L, int status, lua_KContext ctx);</pre> 4464 1.2 lneto 4465 1.2 lneto <p> 4466 1.9 nikita Type for continuation functions (see <a href="#4.5">§4.5</a>). 4467 1.2 lneto 4468 1.2 lneto 4469 1.2 lneto 4470 1.2 lneto 4471 1.2 lneto 4472 1.2 lneto <hr><h3><a name="lua_len"><code>lua_len</code></a></h3><p> 4473 1.2 lneto <span class="apii">[-0, +1, <em>e</em>]</span> 4474 1.2 lneto <pre>void lua_len (lua_State *L, int index);</pre> 4475 1.1 mbalmer 4476 1.1 mbalmer <p> 4477 1.3 lneto Returns the length of the value at the given index. 4478 1.3 lneto It is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">§3.4.7</a>) and 4479 1.3 lneto may trigger a metamethod for the "length" event (see <a href="#2.4">§2.4</a>). 4480 1.2 lneto The result is pushed on the stack. 4481 1.1 mbalmer 4482 1.1 mbalmer 4483 1.1 mbalmer 4484 1.1 mbalmer 4485 1.1 mbalmer 4486 1.1 mbalmer <hr><h3><a name="lua_load"><code>lua_load</code></a></h3><p> 4487 1.2 lneto <span class="apii">[-0, +1, –]</span> 4488 1.1 mbalmer <pre>int lua_load (lua_State *L, 4489 1.1 mbalmer lua_Reader reader, 4490 1.1 mbalmer void *data, 4491 1.3 lneto const char *chunkname, 4492 1.2 lneto const char *mode);</pre> 4493 1.1 mbalmer 4494 1.1 mbalmer <p> 4495 1.3 lneto Loads a Lua chunk without running it. 4496 1.1 mbalmer If there are no errors, 4497 1.2 lneto <code>lua_load</code> pushes the compiled chunk as a Lua 4498 1.1 mbalmer function on top of the stack. 4499 1.1 mbalmer Otherwise, it pushes an error message. 4500 1.2 lneto 4501 1.2 lneto 4502 1.2 lneto <p> 4503 1.2 lneto The <code>lua_load</code> function uses a user-supplied <code>reader</code> function 4504 1.2 lneto to read the chunk (see <a href="#lua_Reader"><code>lua_Reader</code></a>). 4505 1.2 lneto The <code>data</code> argument is an opaque value passed to the reader function. 4506 1.2 lneto 4507 1.2 lneto 4508 1.2 lneto <p> 4509 1.3 lneto The <code>chunkname</code> argument gives a name to the chunk, 4510 1.9 nikita which is used for error messages and in debug information (see <a href="#4.7">§4.7</a>). 4511 1.1 mbalmer 4512 1.1 mbalmer 4513 1.1 mbalmer <p> 4514 1.2 lneto <code>lua_load</code> automatically detects whether the chunk is text or binary 4515 1.1 mbalmer and loads it accordingly (see program <code>luac</code>). 4516 1.2 lneto The string <code>mode</code> works as in function <a href="#pdf-load"><code>load</code></a>, 4517 1.2 lneto with the addition that 4518 1.2 lneto a <code>NULL</code> value is equivalent to the string "<code>bt</code>". 4519 1.1 mbalmer 4520 1.1 mbalmer 4521 1.1 mbalmer <p> 4522 1.2 lneto <code>lua_load</code> uses the stack internally, 4523 1.2 lneto so the reader function must always leave the stack 4524 1.2 lneto unmodified when returning. 4525 1.1 mbalmer 4526 1.1 mbalmer 4527 1.1 mbalmer <p> 4528 1.9 nikita <code>lua_load</code> can return 4529 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>. 4530 1.9 nikita The function may also return other values corresponding to 4531 1.9 nikita errors raised by the read function (see <a href="#4.4.1">§4.4.1</a>). 4532 1.9 nikita 4533 1.9 nikita 4534 1.9 nikita <p> 4535 1.3 lneto If the resulting function has upvalues, 4536 1.3 lneto its first upvalue is set to the value of the global environment 4537 1.9 nikita stored at index <code>LUA_RIDX_GLOBALS</code> in the registry (see <a href="#4.3">§4.3</a>). 4538 1.2 lneto When loading main chunks, 4539 1.2 lneto this upvalue will be the <code>_ENV</code> variable (see <a href="#2.2">§2.2</a>). 4540 1.3 lneto Other upvalues are initialized with <b>nil</b>. 4541 1.1 mbalmer 4542 1.1 mbalmer 4543 1.1 mbalmer 4544 1.1 mbalmer 4545 1.1 mbalmer 4546 1.1 mbalmer <hr><h3><a name="lua_newstate"><code>lua_newstate</code></a></h3><p> 4547 1.2 lneto <span class="apii">[-0, +0, –]</span> 4548 1.1 mbalmer <pre>lua_State *lua_newstate (lua_Alloc f, void *ud);</pre> 4549 1.1 mbalmer 4550 1.1 mbalmer <p> 4551 1.9 nikita Creates a new independent state and returns its main thread. 4552 1.9 nikita Returns <code>NULL</code> if it cannot create the state 4553 1.1 mbalmer (due to lack of memory). 4554 1.1 mbalmer The argument <code>f</code> is the allocator function; 4555 1.9 nikita Lua will do all memory allocation for this state 4556 1.7 mbalmer through this function (see <a href="#lua_Alloc"><code>lua_Alloc</code></a>). 4557 1.1 mbalmer The second argument, <code>ud</code>, is an opaque pointer that Lua 4558 1.2 lneto passes to the allocator in every call. 4559 1.1 mbalmer 4560 1.1 mbalmer 4561 1.1 mbalmer 4562 1.1 mbalmer 4563 1.1 mbalmer 4564 1.1 mbalmer <hr><h3><a name="lua_newtable"><code>lua_newtable</code></a></h3><p> 4565 1.5 lneto <span class="apii">[-0, +1, <em>m</em>]</span> 4566 1.1 mbalmer <pre>void lua_newtable (lua_State *L);</pre> 4567 1.1 mbalmer 4568 1.1 mbalmer <p> 4569 1.1 mbalmer Creates a new empty table and pushes it onto the stack. 4570 1.1 mbalmer It is equivalent to <code>lua_createtable(L, 0, 0)</code>. 4571 1.1 mbalmer 4572 1.1 mbalmer 4573 1.1 mbalmer 4574 1.1 mbalmer 4575 1.1 mbalmer 4576 1.1 mbalmer <hr><h3><a name="lua_newthread"><code>lua_newthread</code></a></h3><p> 4577 1.5 lneto <span class="apii">[-0, +1, <em>m</em>]</span> 4578 1.1 mbalmer <pre>lua_State *lua_newthread (lua_State *L);</pre> 4579 1.1 mbalmer 4580 1.1 mbalmer <p> 4581 1.1 mbalmer Creates a new thread, pushes it on the stack, 4582 1.1 mbalmer and returns a pointer to a <a href="#lua_State"><code>lua_State</code></a> that represents this new thread. 4583 1.2 lneto The new thread returned by this function shares with the original thread 4584 1.2 lneto its global environment, 4585 1.1 mbalmer but has an independent execution stack. 4586 1.1 mbalmer 4587 1.1 mbalmer 4588 1.1 mbalmer <p> 4589 1.1 mbalmer Threads are subject to garbage collection, 4590 1.1 mbalmer like any Lua object. 4591 1.1 mbalmer 4592 1.1 mbalmer 4593 1.1 mbalmer 4594 1.1 mbalmer 4595 1.1 mbalmer 4596 1.9 nikita <hr><h3><a name="lua_newuserdatauv"><code>lua_newuserdatauv</code></a></h3><p> 4597 1.5 lneto <span class="apii">[-0, +1, <em>m</em>]</span> 4598 1.9 nikita <pre>void *lua_newuserdatauv (lua_State *L, size_t size, int nuvalue);</pre> 4599 1.9 nikita 4600 1.9 nikita <p> 4601 1.9 nikita This function creates and pushes on the stack a new full userdata, 4602 1.9 nikita with <code>nuvalue</code> associated Lua values, called <code>user values</code>, 4603 1.9 nikita plus an associated block of raw memory with <code>size</code> bytes. 4604 1.9 nikita (The user values can be set and read with the functions 4605 1.9 nikita <a href="#lua_setiuservalue"><code>lua_setiuservalue</code></a> and <a href="#lua_getiuservalue"><code>lua_getiuservalue</code></a>.) 4606 1.9 nikita 4607 1.1 mbalmer 4608 1.1 mbalmer <p> 4609 1.9 nikita The function returns the address of the block of memory. 4610 1.9 nikita Lua ensures that this address is valid as long as 4611 1.9 nikita the corresponding userdata is alive (see <a href="#2.5">§2.5</a>). 4612 1.9 nikita Moreover, if the userdata is marked for finalization (see <a href="#2.5.3">§2.5.3</a>), 4613 1.9 nikita its address is valid at least until the call to its finalizer. 4614 1.1 mbalmer 4615 1.1 mbalmer 4616 1.1 mbalmer 4617 1.1 mbalmer 4618 1.1 mbalmer 4619 1.1 mbalmer <hr><h3><a name="lua_next"><code>lua_next</code></a></h3><p> 4620 1.9 nikita <span class="apii">[-1, +(2|0), <em>v</em>]</span> 4621 1.1 mbalmer <pre>int lua_next (lua_State *L, int index);</pre> 4622 1.1 mbalmer 4623 1.1 mbalmer <p> 4624 1.1 mbalmer Pops a key from the stack, 4625 1.9 nikita and pushes a key–value pair from the table at the given index, 4626 1.9 nikita the "next" pair after the given key. 4627 1.1 mbalmer If there are no more elements in the table, 4628 1.10 nikita then <a href="#lua_next"><code>lua_next</code></a> returns 0 and pushes nothing. 4629 1.1 mbalmer 4630 1.1 mbalmer 4631 1.1 mbalmer <p> 4632 1.9 nikita A typical table traversal looks like this: 4633 1.1 mbalmer 4634 1.1 mbalmer <pre> 4635 1.1 mbalmer /* table is in the stack at index 't' */ 4636 1.1 mbalmer lua_pushnil(L); /* first key */ 4637 1.1 mbalmer while (lua_next(L, t) != 0) { 4638 1.1 mbalmer /* uses 'key' (at index -2) and 'value' (at index -1) */ 4639 1.1 mbalmer printf("%s - %s\n", 4640 1.1 mbalmer lua_typename(L, lua_type(L, -2)), 4641 1.1 mbalmer lua_typename(L, lua_type(L, -1))); 4642 1.1 mbalmer /* removes 'value'; keeps 'key' for next iteration */ 4643 1.1 mbalmer lua_pop(L, 1); 4644 1.1 mbalmer } 4645 1.1 mbalmer </pre> 4646 1.1 mbalmer 4647 1.1 mbalmer <p> 4648 1.1 mbalmer While traversing a table, 4649 1.9 nikita avoid calling <a href="#lua_tolstring"><code>lua_tolstring</code></a> directly on a key, 4650 1.1 mbalmer unless you know that the key is actually a string. 4651 1.2 lneto Recall that <a href="#lua_tolstring"><code>lua_tolstring</code></a> may change 4652 1.1 mbalmer the value at the given index; 4653 1.1 mbalmer this confuses the next call to <a href="#lua_next"><code>lua_next</code></a>. 4654 1.1 mbalmer 4655 1.1 mbalmer 4656 1.2 lneto <p> 4657 1.9 nikita This function may raise an error if the given key 4658 1.9 nikita is neither <b>nil</b> nor present in the table. 4659 1.2 lneto See function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying 4660 1.2 lneto the table during its traversal. 4661 1.2 lneto 4662 1.2 lneto 4663 1.1 mbalmer 4664 1.1 mbalmer 4665 1.1 mbalmer 4666 1.1 mbalmer <hr><h3><a name="lua_Number"><code>lua_Number</code></a></h3> 4667 1.4 mbalmer <pre>typedef ... lua_Number;</pre> 4668 1.1 mbalmer 4669 1.1 mbalmer <p> 4670 1.2 lneto The type of floats in Lua. 4671 1.1 mbalmer 4672 1.1 mbalmer 4673 1.1 mbalmer <p> 4674 1.2 lneto By default this type is double, 4675 1.4 mbalmer but that can be changed to a single float or a long double. 4676 1.4 mbalmer (See <code>LUA_FLOAT_TYPE</code> in <code>luaconf.h</code>.) 4677 1.2 lneto 4678 1.2 lneto 4679 1.1 mbalmer 4680 1.1 mbalmer 4681 1.1 mbalmer 4682 1.3 lneto <hr><h3><a name="lua_numbertointeger"><code>lua_numbertointeger</code></a></h3> 4683 1.3 lneto <pre>int lua_numbertointeger (lua_Number n, lua_Integer *p);</pre> 4684 1.1 mbalmer 4685 1.2 lneto <p> 4686 1.9 nikita Tries to convert a Lua float to a Lua integer; 4687 1.9 nikita the float <code>n</code> must have an integral value. 4688 1.2 lneto If that value is within the range of Lua integers, 4689 1.2 lneto it is converted to an integer and assigned to <code>*p</code>. 4690 1.2 lneto The macro results in a boolean indicating whether the 4691 1.2 lneto conversion was successful. 4692 1.2 lneto (Note that this range test can be tricky to do 4693 1.9 nikita correctly without this macro, due to rounding.) 4694 1.1 mbalmer 4695 1.1 mbalmer 4696 1.1 mbalmer <p> 4697 1.2 lneto This macro may evaluate its arguments more than once. 4698 1.1 mbalmer 4699 1.1 mbalmer 4700 1.1 mbalmer 4701 1.1 mbalmer 4702 1.1 mbalmer 4703 1.1 mbalmer <hr><h3><a name="lua_pcall"><code>lua_pcall</code></a></h3><p> 4704 1.2 lneto <span class="apii">[-(nargs + 1), +(nresults|1), –]</span> 4705 1.2 lneto <pre>int lua_pcall (lua_State *L, int nargs, int nresults, int msgh);</pre> 4706 1.1 mbalmer 4707 1.1 mbalmer <p> 4708 1.9 nikita Calls a function (or a callable object) in protected mode. 4709 1.1 mbalmer 4710 1.1 mbalmer 4711 1.1 mbalmer <p> 4712 1.1 mbalmer Both <code>nargs</code> and <code>nresults</code> have the same meaning as 4713 1.1 mbalmer in <a href="#lua_call"><code>lua_call</code></a>. 4714 1.1 mbalmer If there are no errors during the call, 4715 1.1 mbalmer <a href="#lua_pcall"><code>lua_pcall</code></a> behaves exactly like <a href="#lua_call"><code>lua_call</code></a>. 4716 1.1 mbalmer However, if there is any error, 4717 1.1 mbalmer <a href="#lua_pcall"><code>lua_pcall</code></a> catches it, 4718 1.6 salazar pushes a single value on the stack (the error object), 4719 1.1 mbalmer and returns an error code. 4720 1.1 mbalmer Like <a href="#lua_call"><code>lua_call</code></a>, 4721 1.1 mbalmer <a href="#lua_pcall"><code>lua_pcall</code></a> always removes the function 4722 1.1 mbalmer and its arguments from the stack. 4723 1.1 mbalmer 4724 1.1 mbalmer 4725 1.1 mbalmer <p> 4726 1.2 lneto If <code>msgh</code> is 0, 4727 1.6 salazar then the error object returned on the stack 4728 1.6 salazar is exactly the original error object. 4729 1.2 lneto Otherwise, <code>msgh</code> is the stack index of a 4730 1.2 lneto <em>message handler</em>. 4731 1.4 mbalmer (This index cannot be a pseudo-index.) 4732 1.1 mbalmer In case of runtime errors, 4733 1.9 nikita this handler will be called with the error object 4734 1.6 salazar and its return value will be the object 4735 1.2 lneto returned on the stack by <a href="#lua_pcall"><code>lua_pcall</code></a>. 4736 1.1 mbalmer 4737 1.1 mbalmer 4738 1.1 mbalmer <p> 4739 1.2 lneto Typically, the message handler is used to add more debug 4740 1.6 salazar information to the error object, such as a stack traceback. 4741 1.1 mbalmer Such information cannot be gathered after the return of <a href="#lua_pcall"><code>lua_pcall</code></a>, 4742 1.1 mbalmer since by then the stack has unwound. 4743 1.1 mbalmer 4744 1.1 mbalmer 4745 1.1 mbalmer <p> 4746 1.9 nikita The <a href="#lua_pcall"><code>lua_pcall</code></a> function returns one of the following status codes: 4747 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>. 4748 1.2 lneto 4749 1.1 mbalmer 4750 1.1 mbalmer 4751 1.1 mbalmer 4752 1.1 mbalmer 4753 1.2 lneto <hr><h3><a name="lua_pcallk"><code>lua_pcallk</code></a></h3><p> 4754 1.2 lneto <span class="apii">[-(nargs + 1), +(nresults|1), –]</span> 4755 1.2 lneto <pre>int lua_pcallk (lua_State *L, 4756 1.2 lneto int nargs, 4757 1.2 lneto int nresults, 4758 1.3 lneto int msgh, 4759 1.3 lneto lua_KContext ctx, 4760 1.2 lneto lua_KFunction k);</pre> 4761 1.2 lneto 4762 1.2 lneto <p> 4763 1.2 lneto This function behaves exactly like <a href="#lua_pcall"><code>lua_pcall</code></a>, 4764 1.9 nikita except that it allows the called function to yield (see <a href="#4.5">§4.5</a>). 4765 1.2 lneto 4766 1.2 lneto 4767 1.2 lneto 4768 1.2 lneto 4769 1.2 lneto 4770 1.1 mbalmer <hr><h3><a name="lua_pop"><code>lua_pop</code></a></h3><p> 4771 1.9 nikita <span class="apii">[-n, +0, <em>e</em>]</span> 4772 1.1 mbalmer <pre>void lua_pop (lua_State *L, int n);</pre> 4773 1.1 mbalmer 4774 1.1 mbalmer <p> 4775 1.1 mbalmer Pops <code>n</code> elements from the stack. 4776 1.9 nikita It is implemented as a macro over <a href="#lua_settop"><code>lua_settop</code></a>. 4777 1.1 mbalmer 4778 1.1 mbalmer 4779 1.1 mbalmer 4780 1.1 mbalmer 4781 1.1 mbalmer 4782 1.1 mbalmer <hr><h3><a name="lua_pushboolean"><code>lua_pushboolean</code></a></h3><p> 4783 1.2 lneto <span class="apii">[-0, +1, –]</span> 4784 1.1 mbalmer <pre>void lua_pushboolean (lua_State *L, int b);</pre> 4785 1.1 mbalmer 4786 1.1 mbalmer <p> 4787 1.1 mbalmer Pushes a boolean value with value <code>b</code> onto the stack. 4788 1.1 mbalmer 4789 1.1 mbalmer 4790 1.1 mbalmer 4791 1.1 mbalmer 4792 1.1 mbalmer 4793 1.1 mbalmer <hr><h3><a name="lua_pushcclosure"><code>lua_pushcclosure</code></a></h3><p> 4794 1.5 lneto <span class="apii">[-n, +1, <em>m</em>]</span> 4795 1.1 mbalmer <pre>void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);</pre> 4796 1.1 mbalmer 4797 1.1 mbalmer <p> 4798 1.1 mbalmer Pushes a new C closure onto the stack. 4799 1.9 nikita This function receives a pointer to a C function 4800 1.9 nikita and pushes onto the stack a Lua value of type <code>function</code> that, 4801 1.9 nikita when called, invokes the corresponding C function. 4802 1.9 nikita The parameter <code>n</code> tells how many upvalues this function will have 4803 1.9 nikita (see <a href="#4.2">§4.2</a>). 4804 1.9 nikita 4805 1.9 nikita 4806 1.9 nikita <p> 4807 1.9 nikita Any function to be callable by Lua must 4808 1.9 nikita follow the correct protocol to receive its parameters 4809 1.9 nikita and return its results (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 4810 1.1 mbalmer 4811 1.1 mbalmer 4812 1.1 mbalmer <p> 4813 1.1 mbalmer When a C function is created, 4814 1.1 mbalmer it is possible to associate some values with it, 4815 1.9 nikita the so called upvalues; 4816 1.9 nikita these upvalues are then accessible to the function whenever it is called. 4817 1.9 nikita This association is called a C closure (see <a href="#4.2">§4.2</a>). 4818 1.9 nikita To create a C closure, 4819 1.9 nikita first the initial values for its upvalues must be pushed onto the stack. 4820 1.9 nikita (When there are multiple upvalues, the first value is pushed first.) 4821 1.1 mbalmer Then <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> 4822 1.1 mbalmer is called to create and push the C function onto the stack, 4823 1.2 lneto with the argument <code>n</code> telling how many values will be 4824 1.1 mbalmer associated with the function. 4825 1.1 mbalmer <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> also pops these values from the stack. 4826 1.1 mbalmer 4827 1.1 mbalmer 4828 1.1 mbalmer <p> 4829 1.1 mbalmer The maximum value for <code>n</code> is 255. 4830 1.1 mbalmer 4831 1.1 mbalmer 4832 1.2 lneto <p> 4833 1.2 lneto When <code>n</code> is zero, 4834 1.7 mbalmer this function creates a <em>light C function</em>, 4835 1.2 lneto which is just a pointer to the C function. 4836 1.2 lneto In that case, it never raises a memory error. 4837 1.2 lneto 4838 1.2 lneto 4839 1.1 mbalmer 4840 1.1 mbalmer 4841 1.1 mbalmer 4842 1.1 mbalmer <hr><h3><a name="lua_pushcfunction"><code>lua_pushcfunction</code></a></h3><p> 4843 1.2 lneto <span class="apii">[-0, +1, –]</span> 4844 1.1 mbalmer <pre>void lua_pushcfunction (lua_State *L, lua_CFunction f);</pre> 4845 1.1 mbalmer 4846 1.1 mbalmer <p> 4847 1.1 mbalmer Pushes a C function onto the stack. 4848 1.9 nikita This function is equivalent to <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> with no upvalues. 4849 1.1 mbalmer 4850 1.1 mbalmer 4851 1.1 mbalmer 4852 1.1 mbalmer 4853 1.1 mbalmer 4854 1.1 mbalmer <hr><h3><a name="lua_pushfstring"><code>lua_pushfstring</code></a></h3><p> 4855 1.9 nikita <span class="apii">[-0, +1, <em>v</em>]</span> 4856 1.1 mbalmer <pre>const char *lua_pushfstring (lua_State *L, const char *fmt, ...);</pre> 4857 1.1 mbalmer 4858 1.1 mbalmer <p> 4859 1.1 mbalmer Pushes onto the stack a formatted string 4860 1.9 nikita and returns a pointer to this string (see <a href="#4.1.3">§4.1.3</a>). 4861 1.3 lneto It is similar to the ISO C function <code>sprintf</code>, 4862 1.9 nikita but has two important differences. 4863 1.9 nikita First, 4864 1.9 nikita you do not have to allocate space for the result; 4865 1.1 mbalmer the result is a Lua string and Lua takes care of memory allocation 4866 1.1 mbalmer (and deallocation, through garbage collection). 4867 1.9 nikita Second, 4868 1.9 nikita the conversion specifiers are quite restricted. 4869 1.1 mbalmer There are no flags, widths, or precisions. 4870 1.1 mbalmer The conversion specifiers can only be 4871 1.2 lneto '<code>%%</code>' (inserts the character '<code>%</code>'), 4872 1.1 mbalmer '<code>%s</code>' (inserts a zero-terminated string, with no size restrictions), 4873 1.1 mbalmer '<code>%f</code>' (inserts a <a href="#lua_Number"><code>lua_Number</code></a>), 4874 1.4 mbalmer '<code>%I</code>' (inserts a <a href="#lua_Integer"><code>lua_Integer</code></a>), 4875 1.9 nikita '<code>%p</code>' (inserts a pointer), 4876 1.2 lneto '<code>%d</code>' (inserts an <code>int</code>), 4877 1.2 lneto '<code>%c</code>' (inserts an <code>int</code> as a one-byte character), and 4878 1.3 lneto '<code>%U</code>' (inserts a <code>long int</code> as a UTF-8 byte sequence). 4879 1.1 mbalmer 4880 1.1 mbalmer 4881 1.6 salazar <p> 4882 1.9 nikita This function may raise errors due to memory overflow 4883 1.9 nikita or an invalid conversion specifier. 4884 1.6 salazar 4885 1.6 salazar 4886 1.1 mbalmer 4887 1.1 mbalmer 4888 1.1 mbalmer 4889 1.2 lneto <hr><h3><a name="lua_pushglobaltable"><code>lua_pushglobaltable</code></a></h3><p> 4890 1.2 lneto <span class="apii">[-0, +1, –]</span> 4891 1.2 lneto <pre>void lua_pushglobaltable (lua_State *L);</pre> 4892 1.2 lneto 4893 1.2 lneto <p> 4894 1.2 lneto Pushes the global environment onto the stack. 4895 1.2 lneto 4896 1.2 lneto 4897 1.2 lneto 4898 1.2 lneto 4899 1.2 lneto 4900 1.1 mbalmer <hr><h3><a name="lua_pushinteger"><code>lua_pushinteger</code></a></h3><p> 4901 1.2 lneto <span class="apii">[-0, +1, –]</span> 4902 1.1 mbalmer <pre>void lua_pushinteger (lua_State *L, lua_Integer n);</pre> 4903 1.1 mbalmer 4904 1.1 mbalmer <p> 4905 1.2 lneto Pushes an integer with value <code>n</code> onto the stack. 4906 1.1 mbalmer 4907 1.1 mbalmer 4908 1.1 mbalmer 4909 1.1 mbalmer 4910 1.1 mbalmer 4911 1.1 mbalmer <hr><h3><a name="lua_pushlightuserdata"><code>lua_pushlightuserdata</code></a></h3><p> 4912 1.2 lneto <span class="apii">[-0, +1, –]</span> 4913 1.1 mbalmer <pre>void lua_pushlightuserdata (lua_State *L, void *p);</pre> 4914 1.1 mbalmer 4915 1.1 mbalmer <p> 4916 1.1 mbalmer Pushes a light userdata onto the stack. 4917 1.1 mbalmer 4918 1.1 mbalmer 4919 1.1 mbalmer <p> 4920 1.1 mbalmer Userdata represent C values in Lua. 4921 1.2 lneto A <em>light userdata</em> represents a pointer, a <code>void*</code>. 4922 1.1 mbalmer It is a value (like a number): 4923 1.1 mbalmer you do not create it, it has no individual metatable, 4924 1.1 mbalmer and it is not collected (as it was never created). 4925 1.1 mbalmer A light userdata is equal to "any" 4926 1.1 mbalmer light userdata with the same C address. 4927 1.1 mbalmer 4928 1.1 mbalmer 4929 1.1 mbalmer 4930 1.1 mbalmer 4931 1.1 mbalmer 4932 1.1 mbalmer <hr><h3><a name="lua_pushliteral"><code>lua_pushliteral</code></a></h3><p> 4933 1.5 lneto <span class="apii">[-0, +1, <em>m</em>]</span> 4934 1.2 lneto <pre>const char *lua_pushliteral (lua_State *L, const char *s);</pre> 4935 1.1 mbalmer 4936 1.1 mbalmer <p> 4937 1.4 mbalmer This macro is equivalent to <a href="#lua_pushstring"><code>lua_pushstring</code></a>, 4938 1.4 mbalmer but should be used only when <code>s</code> is a literal string. 4939 1.9 nikita (Lua may optimize this case.) 4940 1.1 mbalmer 4941 1.1 mbalmer 4942 1.1 mbalmer 4943 1.1 mbalmer 4944 1.1 mbalmer 4945 1.1 mbalmer <hr><h3><a name="lua_pushlstring"><code>lua_pushlstring</code></a></h3><p> 4946 1.5 lneto <span class="apii">[-0, +1, <em>m</em>]</span> 4947 1.2 lneto <pre>const char *lua_pushlstring (lua_State *L, const char *s, size_t len);</pre> 4948 1.1 mbalmer 4949 1.1 mbalmer <p> 4950 1.1 mbalmer Pushes the string pointed to by <code>s</code> with size <code>len</code> 4951 1.1 mbalmer onto the stack. 4952 1.9 nikita Lua will make or reuse an internal copy of the given string, 4953 1.1 mbalmer so the memory at <code>s</code> can be freed or reused immediately after 4954 1.1 mbalmer the function returns. 4955 1.2 lneto The string can contain any binary data, 4956 1.2 lneto including embedded zeros. 4957 1.2 lneto 4958 1.2 lneto 4959 1.2 lneto <p> 4960 1.9 nikita Returns a pointer to the internal copy of the string (see <a href="#4.1.3">§4.1.3</a>). 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_pushnil"><code>lua_pushnil</code></a></h3><p> 4967 1.2 lneto <span class="apii">[-0, +1, –]</span> 4968 1.1 mbalmer <pre>void lua_pushnil (lua_State *L);</pre> 4969 1.1 mbalmer 4970 1.1 mbalmer <p> 4971 1.1 mbalmer Pushes a nil value onto the stack. 4972 1.1 mbalmer 4973 1.1 mbalmer 4974 1.1 mbalmer 4975 1.1 mbalmer 4976 1.1 mbalmer 4977 1.1 mbalmer <hr><h3><a name="lua_pushnumber"><code>lua_pushnumber</code></a></h3><p> 4978 1.2 lneto <span class="apii">[-0, +1, –]</span> 4979 1.1 mbalmer <pre>void lua_pushnumber (lua_State *L, lua_Number n);</pre> 4980 1.1 mbalmer 4981 1.1 mbalmer <p> 4982 1.2 lneto Pushes a float with value <code>n</code> onto the stack. 4983 1.1 mbalmer 4984 1.1 mbalmer 4985 1.1 mbalmer 4986 1.1 mbalmer 4987 1.1 mbalmer 4988 1.1 mbalmer <hr><h3><a name="lua_pushstring"><code>lua_pushstring</code></a></h3><p> 4989 1.5 lneto <span class="apii">[-0, +1, <em>m</em>]</span> 4990 1.2 lneto <pre>const char *lua_pushstring (lua_State *L, const char *s);</pre> 4991 1.1 mbalmer 4992 1.1 mbalmer <p> 4993 1.1 mbalmer Pushes the zero-terminated string pointed to by <code>s</code> 4994 1.1 mbalmer onto the stack. 4995 1.9 nikita Lua will make or reuse an internal copy of the given string, 4996 1.1 mbalmer so the memory at <code>s</code> can be freed or reused immediately after 4997 1.1 mbalmer the function returns. 4998 1.2 lneto 4999 1.2 lneto 5000 1.2 lneto <p> 5001 1.9 nikita Returns a pointer to the internal copy of the string (see <a href="#4.1.3">§4.1.3</a>). 5002 1.2 lneto 5003 1.2 lneto 5004 1.2 lneto <p> 5005 1.2 lneto If <code>s</code> is <code>NULL</code>, pushes <b>nil</b> and returns <code>NULL</code>. 5006 1.1 mbalmer 5007 1.1 mbalmer 5008 1.1 mbalmer 5009 1.1 mbalmer 5010 1.1 mbalmer 5011 1.1 mbalmer <hr><h3><a name="lua_pushthread"><code>lua_pushthread</code></a></h3><p> 5012 1.2 lneto <span class="apii">[-0, +1, –]</span> 5013 1.1 mbalmer <pre>int lua_pushthread (lua_State *L);</pre> 5014 1.1 mbalmer 5015 1.1 mbalmer <p> 5016 1.1 mbalmer Pushes the thread represented by <code>L</code> onto the stack. 5017 1.1 mbalmer Returns 1 if this thread is the main thread of its state. 5018 1.1 mbalmer 5019 1.1 mbalmer 5020 1.1 mbalmer 5021 1.1 mbalmer 5022 1.1 mbalmer 5023 1.1 mbalmer <hr><h3><a name="lua_pushvalue"><code>lua_pushvalue</code></a></h3><p> 5024 1.2 lneto <span class="apii">[-0, +1, –]</span> 5025 1.1 mbalmer <pre>void lua_pushvalue (lua_State *L, int index);</pre> 5026 1.1 mbalmer 5027 1.1 mbalmer <p> 5028 1.2 lneto Pushes a copy of the element at the given index 5029 1.1 mbalmer onto the stack. 5030 1.1 mbalmer 5031 1.1 mbalmer 5032 1.1 mbalmer 5033 1.1 mbalmer 5034 1.1 mbalmer 5035 1.1 mbalmer <hr><h3><a name="lua_pushvfstring"><code>lua_pushvfstring</code></a></h3><p> 5036 1.9 nikita <span class="apii">[-0, +1, <em>v</em>]</span> 5037 1.1 mbalmer <pre>const char *lua_pushvfstring (lua_State *L, 5038 1.1 mbalmer const char *fmt, 5039 1.1 mbalmer va_list argp);</pre> 5040 1.1 mbalmer 5041 1.1 mbalmer <p> 5042 1.1 mbalmer Equivalent to <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>, except that it receives a <code>va_list</code> 5043 1.1 mbalmer instead of a variable number of arguments. 5044 1.1 mbalmer 5045 1.1 mbalmer 5046 1.1 mbalmer 5047 1.1 mbalmer 5048 1.1 mbalmer 5049 1.1 mbalmer <hr><h3><a name="lua_rawequal"><code>lua_rawequal</code></a></h3><p> 5050 1.2 lneto <span class="apii">[-0, +0, –]</span> 5051 1.1 mbalmer <pre>int lua_rawequal (lua_State *L, int index1, int index2);</pre> 5052 1.1 mbalmer 5053 1.1 mbalmer <p> 5054 1.2 lneto Returns 1 if the two values in indices <code>index1</code> and 5055 1.1 mbalmer <code>index2</code> are primitively equal 5056 1.9 nikita (that is, equal without calling the <code>__eq</code> metamethod). 5057 1.1 mbalmer Otherwise returns 0. 5058 1.3 lneto Also returns 0 if any of the indices are not valid. 5059 1.1 mbalmer 5060 1.1 mbalmer 5061 1.1 mbalmer 5062 1.1 mbalmer 5063 1.1 mbalmer 5064 1.1 mbalmer <hr><h3><a name="lua_rawget"><code>lua_rawget</code></a></h3><p> 5065 1.2 lneto <span class="apii">[-1, +1, –]</span> 5066 1.2 lneto <pre>int lua_rawget (lua_State *L, int index);</pre> 5067 1.1 mbalmer 5068 1.1 mbalmer <p> 5069 1.1 mbalmer Similar to <a href="#lua_gettable"><code>lua_gettable</code></a>, but does a raw access 5070 1.1 mbalmer (i.e., without metamethods). 5071 1.10 nikita The value at <code>index</code> must be a table. 5072 1.1 mbalmer 5073 1.1 mbalmer 5074 1.1 mbalmer 5075 1.1 mbalmer 5076 1.1 mbalmer 5077 1.2 lneto <hr><h3><a name="lua_rawgeti"><code>lua_rawgeti</code></a></h3><p> 5078 1.2 lneto <span class="apii">[-0, +1, –]</span> 5079 1.2 lneto <pre>int lua_rawgeti (lua_State *L, int index, lua_Integer n);</pre> 5080 1.2 lneto 5081 1.2 lneto <p> 5082 1.2 lneto Pushes onto the stack the value <code>t[n]</code>, 5083 1.2 lneto where <code>t</code> is the table at the given index. 5084 1.6 salazar The access is raw, 5085 1.9 nikita that is, it does not use the <code>__index</code> metavalue. 5086 1.2 lneto 5087 1.2 lneto 5088 1.2 lneto <p> 5089 1.2 lneto Returns the type of the pushed value. 5090 1.2 lneto 5091 1.2 lneto 5092 1.2 lneto 5093 1.2 lneto 5094 1.2 lneto 5095 1.2 lneto <hr><h3><a name="lua_rawgetp"><code>lua_rawgetp</code></a></h3><p> 5096 1.2 lneto <span class="apii">[-0, +1, –]</span> 5097 1.2 lneto <pre>int lua_rawgetp (lua_State *L, int index, const void *p);</pre> 5098 1.2 lneto 5099 1.2 lneto <p> 5100 1.2 lneto Pushes onto the stack the value <code>t[k]</code>, 5101 1.2 lneto where <code>t</code> is the table at the given index and 5102 1.2 lneto <code>k</code> is the pointer <code>p</code> represented as a light userdata. 5103 1.2 lneto The access is raw; 5104 1.9 nikita that is, it does not use the <code>__index</code> metavalue. 5105 1.2 lneto 5106 1.2 lneto 5107 1.2 lneto <p> 5108 1.2 lneto Returns the type of the pushed value. 5109 1.2 lneto 5110 1.2 lneto 5111 1.2 lneto 5112 1.2 lneto 5113 1.2 lneto 5114 1.2 lneto <hr><h3><a name="lua_rawlen"><code>lua_rawlen</code></a></h3><p> 5115 1.2 lneto <span class="apii">[-0, +0, –]</span> 5116 1.9 nikita <pre>lua_Unsigned lua_rawlen (lua_State *L, int index);</pre> 5117 1.2 lneto 5118 1.2 lneto <p> 5119 1.2 lneto Returns the raw "length" of the value at the given index: 5120 1.2 lneto for strings, this is the string length; 5121 1.2 lneto for tables, this is the result of the length operator ('<code>#</code>') 5122 1.2 lneto with no metamethods; 5123 1.2 lneto for userdata, this is the size of the block of memory allocated 5124 1.9 nikita for the userdata. 5125 1.9 nikita For other values, this call returns 0. 5126 1.1 mbalmer 5127 1.1 mbalmer 5128 1.1 mbalmer 5129 1.1 mbalmer 5130 1.1 mbalmer 5131 1.1 mbalmer <hr><h3><a name="lua_rawset"><code>lua_rawset</code></a></h3><p> 5132 1.5 lneto <span class="apii">[-2, +0, <em>m</em>]</span> 5133 1.1 mbalmer <pre>void lua_rawset (lua_State *L, int index);</pre> 5134 1.1 mbalmer 5135 1.1 mbalmer <p> 5136 1.1 mbalmer Similar to <a href="#lua_settable"><code>lua_settable</code></a>, but does a raw assignment 5137 1.1 mbalmer (i.e., without metamethods). 5138 1.10 nikita The value at <code>index</code> must be a table. 5139 1.1 mbalmer 5140 1.1 mbalmer 5141 1.1 mbalmer 5142 1.1 mbalmer 5143 1.1 mbalmer 5144 1.1 mbalmer <hr><h3><a name="lua_rawseti"><code>lua_rawseti</code></a></h3><p> 5145 1.5 lneto <span class="apii">[-1, +0, <em>m</em>]</span> 5146 1.3 lneto <pre>void lua_rawseti (lua_State *L, int index, lua_Integer i);</pre> 5147 1.1 mbalmer 5148 1.1 mbalmer <p> 5149 1.3 lneto Does the equivalent of <code>t[i] = v</code>, 5150 1.2 lneto where <code>t</code> is the table at the given index 5151 1.9 nikita and <code>v</code> is the value on the top of the stack. 5152 1.2 lneto 5153 1.2 lneto 5154 1.2 lneto <p> 5155 1.2 lneto This function pops the value from the stack. 5156 1.6 salazar The assignment is raw, 5157 1.9 nikita that is, it does not use the <code>__newindex</code> metavalue. 5158 1.2 lneto 5159 1.2 lneto 5160 1.2 lneto 5161 1.2 lneto 5162 1.2 lneto 5163 1.2 lneto <hr><h3><a name="lua_rawsetp"><code>lua_rawsetp</code></a></h3><p> 5164 1.5 lneto <span class="apii">[-1, +0, <em>m</em>]</span> 5165 1.2 lneto <pre>void lua_rawsetp (lua_State *L, int index, const void *p);</pre> 5166 1.2 lneto 5167 1.2 lneto <p> 5168 1.4 mbalmer Does the equivalent of <code>t[p] = v</code>, 5169 1.2 lneto where <code>t</code> is the table at the given index, 5170 1.4 mbalmer <code>p</code> is encoded as a light userdata, 5171 1.9 nikita and <code>v</code> is the value on the top of the stack. 5172 1.1 mbalmer 5173 1.1 mbalmer 5174 1.1 mbalmer <p> 5175 1.1 mbalmer This function pops the value from the stack. 5176 1.6 salazar The assignment is raw, 5177 1.9 nikita that is, it does not use the <code>__newindex</code> metavalue. 5178 1.1 mbalmer 5179 1.1 mbalmer 5180 1.1 mbalmer 5181 1.1 mbalmer 5182 1.1 mbalmer 5183 1.1 mbalmer <hr><h3><a name="lua_Reader"><code>lua_Reader</code></a></h3> 5184 1.1 mbalmer <pre>typedef const char * (*lua_Reader) (lua_State *L, 5185 1.1 mbalmer void *data, 5186 1.1 mbalmer size_t *size);</pre> 5187 1.1 mbalmer 5188 1.1 mbalmer <p> 5189 1.1 mbalmer The reader function used by <a href="#lua_load"><code>lua_load</code></a>. 5190 1.9 nikita Every time <a href="#lua_load"><code>lua_load</code></a> needs another piece of the chunk, 5191 1.9 nikita it calls the reader, 5192 1.1 mbalmer passing along its <code>data</code> parameter. 5193 1.1 mbalmer The reader must return a pointer to a block of memory 5194 1.1 mbalmer with a new piece of the chunk 5195 1.1 mbalmer and set <code>size</code> to the block size. 5196 1.1 mbalmer The block must exist until the reader function is called again. 5197 1.1 mbalmer To signal the end of the chunk, 5198 1.1 mbalmer the reader must return <code>NULL</code> or set <code>size</code> to zero. 5199 1.1 mbalmer The reader function may return pieces of any size greater than zero. 5200 1.1 mbalmer 5201 1.1 mbalmer 5202 1.1 mbalmer 5203 1.1 mbalmer 5204 1.1 mbalmer 5205 1.1 mbalmer <hr><h3><a name="lua_register"><code>lua_register</code></a></h3><p> 5206 1.1 mbalmer <span class="apii">[-0, +0, <em>e</em>]</span> 5207 1.2 lneto <pre>void lua_register (lua_State *L, const char *name, lua_CFunction f);</pre> 5208 1.1 mbalmer 5209 1.1 mbalmer <p> 5210 1.7 mbalmer Sets the C function <code>f</code> as the new value of global <code>name</code>. 5211 1.1 mbalmer It is defined as a macro: 5212 1.1 mbalmer 5213 1.1 mbalmer <pre> 5214 1.1 mbalmer #define lua_register(L,n,f) \ 5215 1.1 mbalmer (lua_pushcfunction(L, f), lua_setglobal(L, n)) 5216 1.1 mbalmer </pre> 5217 1.1 mbalmer 5218 1.1 mbalmer 5219 1.1 mbalmer 5220 1.1 mbalmer 5221 1.1 mbalmer <hr><h3><a name="lua_remove"><code>lua_remove</code></a></h3><p> 5222 1.2 lneto <span class="apii">[-1, +0, –]</span> 5223 1.1 mbalmer <pre>void lua_remove (lua_State *L, int index);</pre> 5224 1.1 mbalmer 5225 1.1 mbalmer <p> 5226 1.1 mbalmer Removes the element at the given valid index, 5227 1.1 mbalmer shifting down the elements above this index to fill the gap. 5228 1.2 lneto This function cannot be called with a pseudo-index, 5229 1.1 mbalmer because a pseudo-index is not an actual stack position. 5230 1.1 mbalmer 5231 1.1 mbalmer 5232 1.1 mbalmer 5233 1.1 mbalmer 5234 1.1 mbalmer 5235 1.1 mbalmer <hr><h3><a name="lua_replace"><code>lua_replace</code></a></h3><p> 5236 1.2 lneto <span class="apii">[-1, +0, –]</span> 5237 1.1 mbalmer <pre>void lua_replace (lua_State *L, int index);</pre> 5238 1.1 mbalmer 5239 1.1 mbalmer <p> 5240 1.2 lneto Moves the top element into the given valid index 5241 1.1 mbalmer without shifting any element 5242 1.4 mbalmer (therefore replacing the value at that given index), 5243 1.2 lneto and then pops the top element. 5244 1.1 mbalmer 5245 1.1 mbalmer 5246 1.1 mbalmer 5247 1.1 mbalmer 5248 1.1 mbalmer 5249 1.9 nikita <hr><h3><a name="lua_resetthread"><code>lua_resetthread</code></a></h3><p> 5250 1.9 nikita <span class="apii">[-0, +?, –]</span> 5251 1.9 nikita <pre>int lua_resetthread (lua_State *L);</pre> 5252 1.9 nikita 5253 1.9 nikita <p> 5254 1.10 nikita This function is deprecated; 5255 1.10 nikita it is equivalent to <a href="#lua_closethread"><code>lua_closethread</code></a> with 5256 1.10 nikita <code>from</code> being <code>NULL</code>. 5257 1.9 nikita 5258 1.9 nikita 5259 1.9 nikita 5260 1.9 nikita 5261 1.9 nikita 5262 1.1 mbalmer <hr><h3><a name="lua_resume"><code>lua_resume</code></a></h3><p> 5263 1.2 lneto <span class="apii">[-?, +?, –]</span> 5264 1.9 nikita <pre>int lua_resume (lua_State *L, lua_State *from, int nargs, 5265 1.9 nikita int *nresults);</pre> 5266 1.1 mbalmer 5267 1.1 mbalmer <p> 5268 1.4 mbalmer Starts and resumes a coroutine in the given thread <code>L</code>. 5269 1.1 mbalmer 5270 1.1 mbalmer 5271 1.1 mbalmer <p> 5272 1.2 lneto To start a coroutine, 5273 1.9 nikita you push the main function plus any arguments 5274 1.9 nikita onto the empty stack of the thread. 5275 1.1 mbalmer then you call <a href="#lua_resume"><code>lua_resume</code></a>, 5276 1.2 lneto with <code>nargs</code> being the number of arguments. 5277 1.1 mbalmer This call returns when the coroutine suspends or finishes its execution. 5278 1.9 nikita When it returns, 5279 1.9 nikita <code>*nresults</code> is updated and 5280 1.9 nikita the top of the stack contains 5281 1.9 nikita the <code>*nresults</code> values passed to <a href="#lua_yield"><code>lua_yield</code></a> 5282 1.9 nikita or returned by the body function. 5283 1.1 mbalmer <a href="#lua_resume"><code>lua_resume</code></a> returns 5284 1.1 mbalmer <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the coroutine yields, 5285 1.2 lneto <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> if the coroutine finishes its execution 5286 1.1 mbalmer without errors, 5287 1.9 nikita or an error code in case of errors (see <a href="#4.4.1">§4.4.1</a>). 5288 1.1 mbalmer In case of errors, 5289 1.9 nikita the error object is on the top of the stack. 5290 1.2 lneto 5291 1.2 lneto 5292 1.2 lneto <p> 5293 1.2 lneto To resume a coroutine, 5294 1.9 nikita you remove the <code>*nresults</code> yielded values from its stack, 5295 1.9 nikita push the values to be passed as results from <code>yield</code>, 5296 1.1 mbalmer and then call <a href="#lua_resume"><code>lua_resume</code></a>. 5297 1.1 mbalmer 5298 1.1 mbalmer 5299 1.2 lneto <p> 5300 1.2 lneto The parameter <code>from</code> represents the coroutine that is resuming <code>L</code>. 5301 1.2 lneto If there is no such coroutine, 5302 1.2 lneto this parameter can be <code>NULL</code>. 5303 1.2 lneto 5304 1.2 lneto 5305 1.1 mbalmer 5306 1.1 mbalmer 5307 1.1 mbalmer 5308 1.2 lneto <hr><h3><a name="lua_rotate"><code>lua_rotate</code></a></h3><p> 5309 1.2 lneto <span class="apii">[-0, +0, –]</span> 5310 1.2 lneto <pre>void lua_rotate (lua_State *L, int idx, int n);</pre> 5311 1.1 mbalmer 5312 1.1 mbalmer <p> 5313 1.4 mbalmer Rotates the stack elements between the valid index <code>idx</code> 5314 1.4 mbalmer and the top of the stack. 5315 1.4 mbalmer The elements are rotated <code>n</code> positions in the direction of the top, 5316 1.4 mbalmer for a positive <code>n</code>, 5317 1.2 lneto or <code>-n</code> positions in the direction of the bottom, 5318 1.2 lneto for a negative <code>n</code>. 5319 1.2 lneto The absolute value of <code>n</code> must not be greater than the size 5320 1.2 lneto of the slice being rotated. 5321 1.4 mbalmer This function cannot be called with a pseudo-index, 5322 1.4 mbalmer because a pseudo-index is not an actual stack position. 5323 1.1 mbalmer 5324 1.1 mbalmer 5325 1.1 mbalmer 5326 1.1 mbalmer 5327 1.1 mbalmer 5328 1.2 lneto <hr><h3><a name="lua_setallocf"><code>lua_setallocf</code></a></h3><p> 5329 1.2 lneto <span class="apii">[-0, +0, –]</span> 5330 1.2 lneto <pre>void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);</pre> 5331 1.1 mbalmer 5332 1.1 mbalmer <p> 5333 1.2 lneto Changes the allocator function of a given state to <code>f</code> 5334 1.2 lneto with user data <code>ud</code>. 5335 1.1 mbalmer 5336 1.1 mbalmer 5337 1.1 mbalmer 5338 1.1 mbalmer 5339 1.1 mbalmer 5340 1.1 mbalmer <hr><h3><a name="lua_setfield"><code>lua_setfield</code></a></h3><p> 5341 1.1 mbalmer <span class="apii">[-1, +0, <em>e</em>]</span> 5342 1.1 mbalmer <pre>void lua_setfield (lua_State *L, int index, const char *k);</pre> 5343 1.1 mbalmer 5344 1.1 mbalmer <p> 5345 1.1 mbalmer Does the equivalent to <code>t[k] = v</code>, 5346 1.2 lneto where <code>t</code> is the value at the given index 5347 1.9 nikita and <code>v</code> is the value on the top of the stack. 5348 1.1 mbalmer 5349 1.1 mbalmer 5350 1.1 mbalmer <p> 5351 1.1 mbalmer This function pops the value from the stack. 5352 1.1 mbalmer As in Lua, this function may trigger a metamethod 5353 1.2 lneto for the "newindex" event (see <a href="#2.4">§2.4</a>). 5354 1.1 mbalmer 5355 1.1 mbalmer 5356 1.1 mbalmer 5357 1.1 mbalmer 5358 1.1 mbalmer 5359 1.1 mbalmer <hr><h3><a name="lua_setglobal"><code>lua_setglobal</code></a></h3><p> 5360 1.1 mbalmer <span class="apii">[-1, +0, <em>e</em>]</span> 5361 1.1 mbalmer <pre>void lua_setglobal (lua_State *L, const char *name);</pre> 5362 1.1 mbalmer 5363 1.1 mbalmer <p> 5364 1.1 mbalmer Pops a value from the stack and 5365 1.1 mbalmer sets it as the new value of global <code>name</code>. 5366 1.1 mbalmer 5367 1.1 mbalmer 5368 1.1 mbalmer 5369 1.1 mbalmer 5370 1.1 mbalmer 5371 1.3 lneto <hr><h3><a name="lua_seti"><code>lua_seti</code></a></h3><p> 5372 1.3 lneto <span class="apii">[-1, +0, <em>e</em>]</span> 5373 1.3 lneto <pre>void lua_seti (lua_State *L, int index, lua_Integer n);</pre> 5374 1.3 lneto 5375 1.3 lneto <p> 5376 1.3 lneto Does the equivalent to <code>t[n] = v</code>, 5377 1.3 lneto where <code>t</code> is the value at the given index 5378 1.9 nikita and <code>v</code> is the value on the top of the stack. 5379 1.3 lneto 5380 1.3 lneto 5381 1.3 lneto <p> 5382 1.3 lneto This function pops the value from the stack. 5383 1.3 lneto As in Lua, this function may trigger a metamethod 5384 1.3 lneto for the "newindex" event (see <a href="#2.4">§2.4</a>). 5385 1.3 lneto 5386 1.3 lneto 5387 1.3 lneto 5388 1.3 lneto 5389 1.3 lneto 5390 1.9 nikita <hr><h3><a name="lua_setiuservalue"><code>lua_setiuservalue</code></a></h3><p> 5391 1.9 nikita <span class="apii">[-1, +0, –]</span> 5392 1.9 nikita <pre>int lua_setiuservalue (lua_State *L, int index, int n);</pre> 5393 1.9 nikita 5394 1.9 nikita <p> 5395 1.9 nikita Pops a value from the stack and sets it as 5396 1.9 nikita the new <code>n</code>-th user value associated to the 5397 1.9 nikita full userdata at the given index. 5398 1.9 nikita Returns 0 if the userdata does not have that value. 5399 1.9 nikita 5400 1.9 nikita 5401 1.9 nikita 5402 1.9 nikita 5403 1.9 nikita 5404 1.1 mbalmer <hr><h3><a name="lua_setmetatable"><code>lua_setmetatable</code></a></h3><p> 5405 1.2 lneto <span class="apii">[-1, +0, –]</span> 5406 1.9 nikita <pre>int lua_setmetatable (lua_State *L, int index);</pre> 5407 1.9 nikita 5408 1.9 nikita <p> 5409 1.9 nikita Pops a table or <b>nil</b> from the stack and 5410 1.9 nikita sets that value as the new metatable for the value at the given index. 5411 1.9 nikita (<b>nil</b> means no metatable.) 5412 1.9 nikita 5413 1.1 mbalmer 5414 1.1 mbalmer <p> 5415 1.9 nikita (For historical reasons, this function returns an <code>int</code>, 5416 1.9 nikita which now is always 1.) 5417 1.1 mbalmer 5418 1.1 mbalmer 5419 1.1 mbalmer 5420 1.1 mbalmer 5421 1.1 mbalmer 5422 1.1 mbalmer <hr><h3><a name="lua_settable"><code>lua_settable</code></a></h3><p> 5423 1.1 mbalmer <span class="apii">[-2, +0, <em>e</em>]</span> 5424 1.1 mbalmer <pre>void lua_settable (lua_State *L, int index);</pre> 5425 1.1 mbalmer 5426 1.1 mbalmer <p> 5427 1.1 mbalmer Does the equivalent to <code>t[k] = v</code>, 5428 1.2 lneto where <code>t</code> is the value at the given index, 5429 1.9 nikita <code>v</code> is the value on the top of the stack, 5430 1.1 mbalmer and <code>k</code> is the value just below the top. 5431 1.1 mbalmer 5432 1.1 mbalmer 5433 1.1 mbalmer <p> 5434 1.1 mbalmer This function pops both the key and the value from the stack. 5435 1.1 mbalmer As in Lua, this function may trigger a metamethod 5436 1.2 lneto for the "newindex" event (see <a href="#2.4">§2.4</a>). 5437 1.1 mbalmer 5438 1.1 mbalmer 5439 1.1 mbalmer 5440 1.1 mbalmer 5441 1.1 mbalmer 5442 1.1 mbalmer <hr><h3><a name="lua_settop"><code>lua_settop</code></a></h3><p> 5443 1.9 nikita <span class="apii">[-?, +?, <em>e</em>]</span> 5444 1.1 mbalmer <pre>void lua_settop (lua_State *L, int index);</pre> 5445 1.1 mbalmer 5446 1.1 mbalmer <p> 5447 1.2 lneto Accepts any index, or 0, 5448 1.1 mbalmer and sets the stack top to this index. 5449 1.9 nikita If the new top is greater than the old one, 5450 1.1 mbalmer then the new elements are filled with <b>nil</b>. 5451 1.1 mbalmer If <code>index</code> is 0, then all stack elements are removed. 5452 1.1 mbalmer 5453 1.1 mbalmer 5454 1.9 nikita <p> 5455 1.9 nikita This function can run arbitrary code when removing an index 5456 1.9 nikita marked as to-be-closed from the stack. 5457 1.9 nikita 5458 1.1 mbalmer 5459 1.1 mbalmer 5460 1.1 mbalmer 5461 1.9 nikita 5462 1.9 nikita <hr><h3><a name="lua_setwarnf"><code>lua_setwarnf</code></a></h3><p> 5463 1.9 nikita <span class="apii">[-0, +0, –]</span> 5464 1.9 nikita <pre>void lua_setwarnf (lua_State *L, lua_WarnFunction f, void *ud);</pre> 5465 1.2 lneto 5466 1.2 lneto <p> 5467 1.9 nikita Sets the warning function to be used by Lua to emit warnings 5468 1.9 nikita (see <a href="#lua_WarnFunction"><code>lua_WarnFunction</code></a>). 5469 1.9 nikita The <code>ud</code> parameter sets the value <code>ud</code> passed to 5470 1.9 nikita the warning function. 5471 1.2 lneto 5472 1.2 lneto 5473 1.2 lneto 5474 1.2 lneto 5475 1.2 lneto 5476 1.1 mbalmer <hr><h3><a name="lua_State"><code>lua_State</code></a></h3> 5477 1.1 mbalmer <pre>typedef struct lua_State lua_State;</pre> 5478 1.1 mbalmer 5479 1.1 mbalmer <p> 5480 1.2 lneto An opaque structure that points to a thread and indirectly 5481 1.2 lneto (through the thread) to the whole state of a Lua interpreter. 5482 1.1 mbalmer The Lua library is fully reentrant: 5483 1.1 mbalmer it has no global variables. 5484 1.2 lneto All information about a state is accessible through this structure. 5485 1.1 mbalmer 5486 1.1 mbalmer 5487 1.1 mbalmer <p> 5488 1.2 lneto A pointer to this structure must be passed as the first argument to 5489 1.1 mbalmer every function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>, 5490 1.1 mbalmer which creates a Lua state from scratch. 5491 1.1 mbalmer 5492 1.1 mbalmer 5493 1.1 mbalmer 5494 1.1 mbalmer 5495 1.1 mbalmer 5496 1.1 mbalmer <hr><h3><a name="lua_status"><code>lua_status</code></a></h3><p> 5497 1.2 lneto <span class="apii">[-0, +0, –]</span> 5498 1.1 mbalmer <pre>int lua_status (lua_State *L);</pre> 5499 1.1 mbalmer 5500 1.1 mbalmer <p> 5501 1.1 mbalmer Returns the status of the thread <code>L</code>. 5502 1.1 mbalmer 5503 1.1 mbalmer 5504 1.1 mbalmer <p> 5505 1.9 nikita The status can be <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> for a normal thread, 5506 1.2 lneto an error code if the thread finished the execution 5507 1.2 lneto of a <a href="#lua_resume"><code>lua_resume</code></a> with an error, 5508 1.9 nikita or <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the thread is suspended. 5509 1.1 mbalmer 5510 1.1 mbalmer 5511 1.2 lneto <p> 5512 1.9 nikita You can call functions only in threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>. 5513 1.2 lneto You can resume threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> 5514 1.2 lneto (to start a new coroutine) or <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> 5515 1.2 lneto (to resume a coroutine). 5516 1.2 lneto 5517 1.2 lneto 5518 1.2 lneto 5519 1.2 lneto 5520 1.2 lneto 5521 1.3 lneto <hr><h3><a name="lua_stringtonumber"><code>lua_stringtonumber</code></a></h3><p> 5522 1.2 lneto <span class="apii">[-0, +1, –]</span> 5523 1.3 lneto <pre>size_t lua_stringtonumber (lua_State *L, const char *s);</pre> 5524 1.2 lneto 5525 1.2 lneto <p> 5526 1.2 lneto Converts the zero-terminated string <code>s</code> to a number, 5527 1.2 lneto pushes that number into the stack, 5528 1.3 lneto and returns the total size of the string, 5529 1.3 lneto that is, its length plus one. 5530 1.2 lneto The conversion can result in an integer or a float, 5531 1.2 lneto according to the lexical conventions of Lua (see <a href="#3.1">§3.1</a>). 5532 1.9 nikita The string may have leading and trailing whitespaces and a sign. 5533 1.2 lneto If the string is not a valid numeral, 5534 1.2 lneto returns 0 and pushes nothing. 5535 1.3 lneto (Note that the result can be used as a boolean, 5536 1.3 lneto true if the conversion succeeds.) 5537 1.2 lneto 5538 1.2 lneto 5539 1.1 mbalmer 5540 1.1 mbalmer 5541 1.1 mbalmer 5542 1.1 mbalmer <hr><h3><a name="lua_toboolean"><code>lua_toboolean</code></a></h3><p> 5543 1.2 lneto <span class="apii">[-0, +0, –]</span> 5544 1.1 mbalmer <pre>int lua_toboolean (lua_State *L, int index);</pre> 5545 1.1 mbalmer 5546 1.1 mbalmer <p> 5547 1.2 lneto Converts the Lua value at the given index to a C boolean 5548 1.1 mbalmer value (0 or 1). 5549 1.1 mbalmer Like all tests in Lua, 5550 1.2 lneto <a href="#lua_toboolean"><code>lua_toboolean</code></a> returns true for any Lua value 5551 1.1 mbalmer different from <b>false</b> and <b>nil</b>; 5552 1.2 lneto otherwise it returns false. 5553 1.1 mbalmer (If you want to accept only actual boolean values, 5554 1.1 mbalmer use <a href="#lua_isboolean"><code>lua_isboolean</code></a> to test the value's type.) 5555 1.1 mbalmer 5556 1.1 mbalmer 5557 1.1 mbalmer 5558 1.1 mbalmer 5559 1.1 mbalmer 5560 1.1 mbalmer <hr><h3><a name="lua_tocfunction"><code>lua_tocfunction</code></a></h3><p> 5561 1.2 lneto <span class="apii">[-0, +0, –]</span> 5562 1.1 mbalmer <pre>lua_CFunction lua_tocfunction (lua_State *L, int index);</pre> 5563 1.1 mbalmer 5564 1.1 mbalmer <p> 5565 1.2 lneto Converts a value at the given index to a C function. 5566 1.1 mbalmer That value must be a C function; 5567 1.1 mbalmer otherwise, returns <code>NULL</code>. 5568 1.1 mbalmer 5569 1.1 mbalmer 5570 1.1 mbalmer 5571 1.1 mbalmer 5572 1.1 mbalmer 5573 1.9 nikita <hr><h3><a name="lua_toclose"><code>lua_toclose</code></a></h3><p> 5574 1.9 nikita <span class="apii">[-0, +0, <em>m</em>]</span> 5575 1.9 nikita <pre>void lua_toclose (lua_State *L, int index);</pre> 5576 1.9 nikita 5577 1.9 nikita <p> 5578 1.9 nikita Marks the given index in the stack as a 5579 1.9 nikita to-be-closed slot (see <a href="#3.3.8">§3.3.8</a>). 5580 1.9 nikita Like a to-be-closed variable in Lua, 5581 1.9 nikita the value at that slot in the stack will be closed 5582 1.9 nikita when it goes out of scope. 5583 1.9 nikita Here, in the context of a C function, 5584 1.9 nikita to go out of scope means that the running function returns to Lua, 5585 1.9 nikita or there is an error, 5586 1.9 nikita or the slot is removed from the stack through 5587 1.9 nikita <a href="#lua_settop"><code>lua_settop</code></a> or <a href="#lua_pop"><code>lua_pop</code></a>, 5588 1.9 nikita or there is a call to <a href="#lua_closeslot"><code>lua_closeslot</code></a>. 5589 1.9 nikita A slot marked as to-be-closed should not be removed from the stack 5590 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>, 5591 1.9 nikita unless previously deactivated by <a href="#lua_closeslot"><code>lua_closeslot</code></a>. 5592 1.9 nikita 5593 1.9 nikita 5594 1.9 nikita <p> 5595 1.9 nikita This function should not be called for an index 5596 1.9 nikita that is equal to or below an active to-be-closed slot. 5597 1.9 nikita 5598 1.9 nikita 5599 1.9 nikita <p> 5600 1.9 nikita Note that, both in case of errors and of a regular return, 5601 1.9 nikita by the time the <code>__close</code> metamethod runs, 5602 1.9 nikita the C stack was already unwound, 5603 1.9 nikita so that any automatic C variable declared in the calling function 5604 1.9 nikita (e.g., a buffer) will be out of scope. 5605 1.9 nikita 5606 1.9 nikita 5607 1.9 nikita 5608 1.9 nikita 5609 1.9 nikita 5610 1.1 mbalmer <hr><h3><a name="lua_tointeger"><code>lua_tointeger</code></a></h3><p> 5611 1.2 lneto <span class="apii">[-0, +0, –]</span> 5612 1.1 mbalmer <pre>lua_Integer lua_tointeger (lua_State *L, int index);</pre> 5613 1.1 mbalmer 5614 1.1 mbalmer <p> 5615 1.2 lneto Equivalent to <a href="#lua_tointegerx"><code>lua_tointegerx</code></a> with <code>isnum</code> equal to <code>NULL</code>. 5616 1.2 lneto 5617 1.2 lneto 5618 1.2 lneto 5619 1.2 lneto 5620 1.2 lneto 5621 1.2 lneto <hr><h3><a name="lua_tointegerx"><code>lua_tointegerx</code></a></h3><p> 5622 1.2 lneto <span class="apii">[-0, +0, –]</span> 5623 1.2 lneto <pre>lua_Integer lua_tointegerx (lua_State *L, int index, int *isnum);</pre> 5624 1.2 lneto 5625 1.2 lneto <p> 5626 1.2 lneto Converts the Lua value at the given index 5627 1.1 mbalmer to the signed integral type <a href="#lua_Integer"><code>lua_Integer</code></a>. 5628 1.2 lneto The Lua value must be an integer, 5629 1.2 lneto or a number or string convertible to an integer (see <a href="#3.4.3">§3.4.3</a>); 5630 1.2 lneto otherwise, <code>lua_tointegerx</code> returns 0. 5631 1.1 mbalmer 5632 1.1 mbalmer 5633 1.1 mbalmer <p> 5634 1.2 lneto If <code>isnum</code> is not <code>NULL</code>, 5635 1.2 lneto its referent is assigned a boolean value that 5636 1.2 lneto indicates whether the operation succeeded. 5637 1.1 mbalmer 5638 1.1 mbalmer 5639 1.1 mbalmer 5640 1.1 mbalmer 5641 1.1 mbalmer 5642 1.1 mbalmer <hr><h3><a name="lua_tolstring"><code>lua_tolstring</code></a></h3><p> 5643 1.5 lneto <span class="apii">[-0, +0, <em>m</em>]</span> 5644 1.1 mbalmer <pre>const char *lua_tolstring (lua_State *L, int index, size_t *len);</pre> 5645 1.1 mbalmer 5646 1.1 mbalmer <p> 5647 1.2 lneto Converts the Lua value at the given index to a C string. 5648 1.1 mbalmer If <code>len</code> is not <code>NULL</code>, 5649 1.5 lneto it sets <code>*len</code> with the string length. 5650 1.1 mbalmer The Lua value must be a string or a number; 5651 1.1 mbalmer otherwise, the function returns <code>NULL</code>. 5652 1.1 mbalmer If the value is a number, 5653 1.2 lneto then <code>lua_tolstring</code> also 5654 1.1 mbalmer <em>changes the actual value in the stack to a string</em>. 5655 1.1 mbalmer (This change confuses <a href="#lua_next"><code>lua_next</code></a> 5656 1.2 lneto when <code>lua_tolstring</code> is applied to keys during a table traversal.) 5657 1.1 mbalmer 5658 1.1 mbalmer 5659 1.1 mbalmer <p> 5660 1.5 lneto <code>lua_tolstring</code> returns a pointer 5661 1.9 nikita to a string inside the Lua state (see <a href="#4.1.3">§4.1.3</a>). 5662 1.1 mbalmer This string always has a zero ('<code>\0</code>') 5663 1.1 mbalmer after its last character (as in C), 5664 1.1 mbalmer but can contain other zeros in its body. 5665 1.3 lneto 5666 1.3 lneto 5667 1.1 mbalmer 5668 1.1 mbalmer 5669 1.1 mbalmer 5670 1.1 mbalmer <hr><h3><a name="lua_tonumber"><code>lua_tonumber</code></a></h3><p> 5671 1.2 lneto <span class="apii">[-0, +0, –]</span> 5672 1.1 mbalmer <pre>lua_Number lua_tonumber (lua_State *L, int index);</pre> 5673 1.1 mbalmer 5674 1.1 mbalmer <p> 5675 1.2 lneto Equivalent to <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> with <code>isnum</code> equal to <code>NULL</code>. 5676 1.2 lneto 5677 1.2 lneto 5678 1.2 lneto 5679 1.2 lneto 5680 1.2 lneto 5681 1.2 lneto <hr><h3><a name="lua_tonumberx"><code>lua_tonumberx</code></a></h3><p> 5682 1.2 lneto <span class="apii">[-0, +0, –]</span> 5683 1.2 lneto <pre>lua_Number lua_tonumberx (lua_State *L, int index, int *isnum);</pre> 5684 1.2 lneto 5685 1.2 lneto <p> 5686 1.2 lneto Converts the Lua value at the given index 5687 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>). 5688 1.1 mbalmer The Lua value must be a number or a string convertible to a number 5689 1.2 lneto (see <a href="#3.4.3">§3.4.3</a>); 5690 1.2 lneto otherwise, <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> returns 0. 5691 1.2 lneto 5692 1.2 lneto 5693 1.2 lneto <p> 5694 1.2 lneto If <code>isnum</code> is not <code>NULL</code>, 5695 1.2 lneto its referent is assigned a boolean value that 5696 1.2 lneto indicates whether the operation succeeded. 5697 1.1 mbalmer 5698 1.1 mbalmer 5699 1.1 mbalmer 5700 1.1 mbalmer 5701 1.1 mbalmer 5702 1.1 mbalmer <hr><h3><a name="lua_topointer"><code>lua_topointer</code></a></h3><p> 5703 1.2 lneto <span class="apii">[-0, +0, –]</span> 5704 1.1 mbalmer <pre>const void *lua_topointer (lua_State *L, int index);</pre> 5705 1.1 mbalmer 5706 1.1 mbalmer <p> 5707 1.2 lneto Converts the value at the given index to a generic 5708 1.1 mbalmer C pointer (<code>void*</code>). 5709 1.9 nikita The value can be a userdata, a table, a thread, a string, or a function; 5710 1.2 lneto otherwise, <code>lua_topointer</code> returns <code>NULL</code>. 5711 1.1 mbalmer Different objects will give different pointers. 5712 1.1 mbalmer There is no way to convert the pointer back to its original value. 5713 1.1 mbalmer 5714 1.1 mbalmer 5715 1.1 mbalmer <p> 5716 1.4 mbalmer Typically this function is used only for hashing and debug information. 5717 1.1 mbalmer 5718 1.1 mbalmer 5719 1.1 mbalmer 5720 1.1 mbalmer 5721 1.1 mbalmer 5722 1.1 mbalmer <hr><h3><a name="lua_tostring"><code>lua_tostring</code></a></h3><p> 5723 1.5 lneto <span class="apii">[-0, +0, <em>m</em>]</span> 5724 1.1 mbalmer <pre>const char *lua_tostring (lua_State *L, int index);</pre> 5725 1.1 mbalmer 5726 1.1 mbalmer <p> 5727 1.1 mbalmer Equivalent to <a href="#lua_tolstring"><code>lua_tolstring</code></a> with <code>len</code> equal to <code>NULL</code>. 5728 1.1 mbalmer 5729 1.1 mbalmer 5730 1.1 mbalmer 5731 1.1 mbalmer 5732 1.1 mbalmer 5733 1.1 mbalmer <hr><h3><a name="lua_tothread"><code>lua_tothread</code></a></h3><p> 5734 1.2 lneto <span class="apii">[-0, +0, –]</span> 5735 1.1 mbalmer <pre>lua_State *lua_tothread (lua_State *L, int index);</pre> 5736 1.1 mbalmer 5737 1.1 mbalmer <p> 5738 1.2 lneto Converts the value at the given index to a Lua thread 5739 1.1 mbalmer (represented as <code>lua_State*</code>). 5740 1.1 mbalmer This value must be a thread; 5741 1.1 mbalmer otherwise, the function returns <code>NULL</code>. 5742 1.1 mbalmer 5743 1.1 mbalmer 5744 1.1 mbalmer 5745 1.1 mbalmer 5746 1.1 mbalmer 5747 1.1 mbalmer <hr><h3><a name="lua_touserdata"><code>lua_touserdata</code></a></h3><p> 5748 1.2 lneto <span class="apii">[-0, +0, –]</span> 5749 1.1 mbalmer <pre>void *lua_touserdata (lua_State *L, int index);</pre> 5750 1.1 mbalmer 5751 1.1 mbalmer <p> 5752 1.2 lneto If the value at the given index is a full userdata, 5753 1.9 nikita returns its memory-block address. 5754 1.1 mbalmer If the value is a light userdata, 5755 1.9 nikita returns its value (a pointer). 5756 1.1 mbalmer Otherwise, returns <code>NULL</code>. 5757 1.1 mbalmer 5758 1.1 mbalmer 5759 1.1 mbalmer 5760 1.1 mbalmer 5761 1.1 mbalmer 5762 1.1 mbalmer <hr><h3><a name="lua_type"><code>lua_type</code></a></h3><p> 5763 1.2 lneto <span class="apii">[-0, +0, –]</span> 5764 1.1 mbalmer <pre>int lua_type (lua_State *L, int index);</pre> 5765 1.1 mbalmer 5766 1.1 mbalmer <p> 5767 1.2 lneto Returns the type of the value in the given valid index, 5768 1.9 nikita or <code>LUA_TNONE</code> for a non-valid but acceptable index. 5769 1.1 mbalmer The types returned by <a href="#lua_type"><code>lua_type</code></a> are coded by the following constants 5770 1.1 mbalmer defined in <code>lua.h</code>: 5771 1.9 nikita <a name="pdf-LUA_TNIL"><code>LUA_TNIL</code></a>, 5772 1.2 lneto <a name="pdf-LUA_TNUMBER"><code>LUA_TNUMBER</code></a>, 5773 1.2 lneto <a name="pdf-LUA_TBOOLEAN"><code>LUA_TBOOLEAN</code></a>, 5774 1.2 lneto <a name="pdf-LUA_TSTRING"><code>LUA_TSTRING</code></a>, 5775 1.2 lneto <a name="pdf-LUA_TTABLE"><code>LUA_TTABLE</code></a>, 5776 1.2 lneto <a name="pdf-LUA_TFUNCTION"><code>LUA_TFUNCTION</code></a>, 5777 1.2 lneto <a name="pdf-LUA_TUSERDATA"><code>LUA_TUSERDATA</code></a>, 5778 1.2 lneto <a name="pdf-LUA_TTHREAD"><code>LUA_TTHREAD</code></a>, 5779 1.1 mbalmer and 5780 1.2 lneto <a name="pdf-LUA_TLIGHTUSERDATA"><code>LUA_TLIGHTUSERDATA</code></a>. 5781 1.1 mbalmer 5782 1.1 mbalmer 5783 1.1 mbalmer 5784 1.1 mbalmer 5785 1.1 mbalmer 5786 1.1 mbalmer <hr><h3><a name="lua_typename"><code>lua_typename</code></a></h3><p> 5787 1.2 lneto <span class="apii">[-0, +0, –]</span> 5788 1.2 lneto <pre>const char *lua_typename (lua_State *L, int tp);</pre> 5789 1.1 mbalmer 5790 1.1 mbalmer <p> 5791 1.1 mbalmer Returns the name of the type encoded by the value <code>tp</code>, 5792 1.1 mbalmer which must be one the values returned by <a href="#lua_type"><code>lua_type</code></a>. 5793 1.1 mbalmer 5794 1.1 mbalmer 5795 1.1 mbalmer 5796 1.1 mbalmer 5797 1.1 mbalmer 5798 1.2 lneto <hr><h3><a name="lua_Unsigned"><code>lua_Unsigned</code></a></h3> 5799 1.2 lneto <pre>typedef ... lua_Unsigned;</pre> 5800 1.2 lneto 5801 1.2 lneto <p> 5802 1.2 lneto The unsigned version of <a href="#lua_Integer"><code>lua_Integer</code></a>. 5803 1.2 lneto 5804 1.2 lneto 5805 1.2 lneto 5806 1.2 lneto 5807 1.2 lneto 5808 1.2 lneto <hr><h3><a name="lua_upvalueindex"><code>lua_upvalueindex</code></a></h3><p> 5809 1.2 lneto <span class="apii">[-0, +0, –]</span> 5810 1.2 lneto <pre>int lua_upvalueindex (int i);</pre> 5811 1.2 lneto 5812 1.2 lneto <p> 5813 1.2 lneto Returns the pseudo-index that represents the <code>i</code>-th upvalue of 5814 1.9 nikita the running function (see <a href="#4.2">§4.2</a>). 5815 1.9 nikita <code>i</code> must be in the range <em>[1,256]</em>. 5816 1.2 lneto 5817 1.2 lneto 5818 1.2 lneto 5819 1.2 lneto 5820 1.2 lneto 5821 1.2 lneto <hr><h3><a name="lua_version"><code>lua_version</code></a></h3><p> 5822 1.6 salazar <span class="apii">[-0, +0, –]</span> 5823 1.9 nikita <pre>lua_Number lua_version (lua_State *L);</pre> 5824 1.9 nikita 5825 1.9 nikita <p> 5826 1.9 nikita Returns the version number of this core. 5827 1.9 nikita 5828 1.9 nikita 5829 1.9 nikita 5830 1.9 nikita 5831 1.9 nikita 5832 1.9 nikita <hr><h3><a name="lua_WarnFunction"><code>lua_WarnFunction</code></a></h3> 5833 1.9 nikita <pre>typedef void (*lua_WarnFunction) (void *ud, const char *msg, int tocont);</pre> 5834 1.9 nikita 5835 1.9 nikita <p> 5836 1.9 nikita The type of warning functions, called by Lua to emit warnings. 5837 1.9 nikita The first parameter is an opaque pointer 5838 1.9 nikita set by <a href="#lua_setwarnf"><code>lua_setwarnf</code></a>. 5839 1.9 nikita The second parameter is the warning message. 5840 1.9 nikita The third parameter is a boolean that 5841 1.9 nikita indicates whether the message is 5842 1.9 nikita to be continued by the message in the next call. 5843 1.9 nikita 5844 1.9 nikita 5845 1.9 nikita <p> 5846 1.9 nikita See <a href="#pdf-warn"><code>warn</code></a> for more details about warnings. 5847 1.9 nikita 5848 1.9 nikita 5849 1.9 nikita 5850 1.9 nikita 5851 1.9 nikita 5852 1.9 nikita <hr><h3><a name="lua_warning"><code>lua_warning</code></a></h3><p> 5853 1.9 nikita <span class="apii">[-0, +0, –]</span> 5854 1.9 nikita <pre>void lua_warning (lua_State *L, const char *msg, int tocont);</pre> 5855 1.9 nikita 5856 1.9 nikita <p> 5857 1.9 nikita Emits a warning with the given message. 5858 1.9 nikita A message in a call with <code>tocont</code> true should be 5859 1.9 nikita continued in another call to this function. 5860 1.9 nikita 5861 1.2 lneto 5862 1.2 lneto <p> 5863 1.9 nikita See <a href="#pdf-warn"><code>warn</code></a> for more details about warnings. 5864 1.2 lneto 5865 1.2 lneto 5866 1.2 lneto 5867 1.2 lneto 5868 1.2 lneto 5869 1.1 mbalmer <hr><h3><a name="lua_Writer"><code>lua_Writer</code></a></h3> 5870 1.1 mbalmer <pre>typedef int (*lua_Writer) (lua_State *L, 5871 1.1 mbalmer const void* p, 5872 1.1 mbalmer size_t sz, 5873 1.1 mbalmer void* ud);</pre> 5874 1.1 mbalmer 5875 1.1 mbalmer <p> 5876 1.1 mbalmer The type of the writer function used by <a href="#lua_dump"><code>lua_dump</code></a>. 5877 1.9 nikita Every time <a href="#lua_dump"><code>lua_dump</code></a> produces another piece of chunk, 5878 1.9 nikita it calls the writer, 5879 1.1 mbalmer passing along the buffer to be written (<code>p</code>), 5880 1.1 mbalmer its size (<code>sz</code>), 5881 1.9 nikita and the <code>ud</code> parameter supplied to <a href="#lua_dump"><code>lua_dump</code></a>. 5882 1.1 mbalmer 5883 1.1 mbalmer 5884 1.1 mbalmer <p> 5885 1.1 mbalmer The writer returns an error code: 5886 1.1 mbalmer 0 means no errors; 5887 1.1 mbalmer any other value means an error and stops <a href="#lua_dump"><code>lua_dump</code></a> from 5888 1.1 mbalmer calling the writer again. 5889 1.1 mbalmer 5890 1.1 mbalmer 5891 1.1 mbalmer 5892 1.1 mbalmer 5893 1.1 mbalmer 5894 1.1 mbalmer <hr><h3><a name="lua_xmove"><code>lua_xmove</code></a></h3><p> 5895 1.2 lneto <span class="apii">[-?, +?, –]</span> 5896 1.1 mbalmer <pre>void lua_xmove (lua_State *from, lua_State *to, int n);</pre> 5897 1.1 mbalmer 5898 1.1 mbalmer <p> 5899 1.2 lneto Exchange values between different threads of the same state. 5900 1.1 mbalmer 5901 1.1 mbalmer 5902 1.1 mbalmer <p> 5903 1.1 mbalmer This function pops <code>n</code> values from the stack <code>from</code>, 5904 1.1 mbalmer and pushes them onto the stack <code>to</code>. 5905 1.1 mbalmer 5906 1.1 mbalmer 5907 1.1 mbalmer 5908 1.1 mbalmer 5909 1.1 mbalmer 5910 1.1 mbalmer <hr><h3><a name="lua_yield"><code>lua_yield</code></a></h3><p> 5911 1.9 nikita <span class="apii">[-?, +?, <em>v</em>]</span> 5912 1.2 lneto <pre>int lua_yield (lua_State *L, int nresults);</pre> 5913 1.2 lneto 5914 1.2 lneto <p> 5915 1.2 lneto This function is equivalent to <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 5916 1.9 nikita but it has no continuation (see <a href="#4.5">§4.5</a>). 5917 1.2 lneto Therefore, when the thread resumes, 5918 1.3 lneto it continues the function that called 5919 1.2 lneto the function calling <code>lua_yield</code>. 5920 1.9 nikita To avoid surprises, 5921 1.9 nikita this function should be called only in a tail call. 5922 1.2 lneto 5923 1.2 lneto 5924 1.2 lneto 5925 1.2 lneto 5926 1.2 lneto 5927 1.2 lneto <hr><h3><a name="lua_yieldk"><code>lua_yieldk</code></a></h3><p> 5928 1.9 nikita <span class="apii">[-?, +?, <em>v</em>]</span> 5929 1.3 lneto <pre>int lua_yieldk (lua_State *L, 5930 1.3 lneto int nresults, 5931 1.3 lneto lua_KContext ctx, 5932 1.3 lneto lua_KFunction k);</pre> 5933 1.1 mbalmer 5934 1.1 mbalmer <p> 5935 1.3 lneto Yields a coroutine (thread). 5936 1.1 mbalmer 5937 1.1 mbalmer 5938 1.1 mbalmer <p> 5939 1.3 lneto When a C function calls <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 5940 1.1 mbalmer the running coroutine suspends its execution, 5941 1.1 mbalmer and the call to <a href="#lua_resume"><code>lua_resume</code></a> that started this coroutine returns. 5942 1.1 mbalmer The parameter <code>nresults</code> is the number of values from the stack 5943 1.2 lneto that will be passed as results to <a href="#lua_resume"><code>lua_resume</code></a>. 5944 1.2 lneto 5945 1.2 lneto 5946 1.2 lneto <p> 5947 1.2 lneto When the coroutine is resumed again, 5948 1.2 lneto Lua calls the given continuation function <code>k</code> to continue 5949 1.9 nikita the execution of the C function that yielded (see <a href="#4.5">§4.5</a>). 5950 1.2 lneto This continuation function receives the same stack 5951 1.2 lneto from the previous function, 5952 1.2 lneto with the <code>n</code> results removed and 5953 1.2 lneto replaced by the arguments passed to <a href="#lua_resume"><code>lua_resume</code></a>. 5954 1.2 lneto Moreover, 5955 1.2 lneto the continuation function receives the value <code>ctx</code> 5956 1.2 lneto that was passed to <a href="#lua_yieldk"><code>lua_yieldk</code></a>. 5957 1.1 mbalmer 5958 1.1 mbalmer 5959 1.3 lneto <p> 5960 1.3 lneto Usually, this function does not return; 5961 1.3 lneto when the coroutine eventually resumes, 5962 1.3 lneto it continues executing the continuation function. 5963 1.3 lneto However, there is one special case, 5964 1.3 lneto which is when this function is called 5965 1.9 nikita from inside a line or a count hook (see <a href="#4.7">§4.7</a>). 5966 1.3 lneto In that case, <code>lua_yieldk</code> should be called with no continuation 5967 1.6 salazar (probably in the form of <a href="#lua_yield"><code>lua_yield</code></a>) and no results, 5968 1.3 lneto and the hook should return immediately after the call. 5969 1.3 lneto Lua will yield and, 5970 1.3 lneto when the coroutine resumes again, 5971 1.3 lneto it will continue the normal execution 5972 1.3 lneto of the (Lua) function that triggered the hook. 5973 1.3 lneto 5974 1.3 lneto 5975 1.3 lneto <p> 5976 1.3 lneto This function can raise an error if it is called from a thread 5977 1.9 nikita with a pending C call with no continuation function 5978 1.9 nikita (what is called a <em>C-call boundary</em>), 5979 1.3 lneto or it is called from a thread that is not running inside a resume 5980 1.9 nikita (typically the main thread). 5981 1.3 lneto 5982 1.3 lneto 5983 1.1 mbalmer 5984 1.1 mbalmer 5985 1.1 mbalmer 5986 1.1 mbalmer 5987 1.1 mbalmer 5988 1.9 nikita <h2>4.7 – <a name="4.7">The Debug Interface</a></h2> 5989 1.1 mbalmer 5990 1.1 mbalmer <p> 5991 1.1 mbalmer Lua has no built-in debugging facilities. 5992 1.1 mbalmer Instead, it offers a special interface 5993 1.1 mbalmer by means of functions and <em>hooks</em>. 5994 1.1 mbalmer This interface allows the construction of different 5995 1.1 mbalmer kinds of debuggers, profilers, and other tools 5996 1.1 mbalmer that need "inside information" from the interpreter. 5997 1.1 mbalmer 5998 1.1 mbalmer 5999 1.1 mbalmer 6000 1.1 mbalmer <hr><h3><a name="lua_Debug"><code>lua_Debug</code></a></h3> 6001 1.1 mbalmer <pre>typedef struct lua_Debug { 6002 1.1 mbalmer int event; 6003 1.1 mbalmer const char *name; /* (n) */ 6004 1.1 mbalmer const char *namewhat; /* (n) */ 6005 1.1 mbalmer const char *what; /* (S) */ 6006 1.1 mbalmer const char *source; /* (S) */ 6007 1.9 nikita size_t srclen; /* (S) */ 6008 1.1 mbalmer int currentline; /* (l) */ 6009 1.1 mbalmer int linedefined; /* (S) */ 6010 1.1 mbalmer int lastlinedefined; /* (S) */ 6011 1.2 lneto unsigned char nups; /* (u) number of upvalues */ 6012 1.2 lneto unsigned char nparams; /* (u) number of parameters */ 6013 1.2 lneto char isvararg; /* (u) */ 6014 1.2 lneto char istailcall; /* (t) */ 6015 1.9 nikita unsigned short ftransfer; /* (r) index of first value transferred */ 6016 1.9 nikita unsigned short ntransfer; /* (r) number of transferred values */ 6017 1.1 mbalmer char short_src[LUA_IDSIZE]; /* (S) */ 6018 1.1 mbalmer /* private part */ 6019 1.1 mbalmer <em>other fields</em> 6020 1.1 mbalmer } lua_Debug;</pre> 6021 1.1 mbalmer 6022 1.1 mbalmer <p> 6023 1.1 mbalmer A structure used to carry different pieces of 6024 1.2 lneto information about a function or an activation record. 6025 1.1 mbalmer <a href="#lua_getstack"><code>lua_getstack</code></a> fills only the private part 6026 1.1 mbalmer of this structure, for later use. 6027 1.1 mbalmer To fill the other fields of <a href="#lua_Debug"><code>lua_Debug</code></a> with useful information, 6028 1.9 nikita you must call <a href="#lua_getinfo"><code>lua_getinfo</code></a> with an appropriate parameter. 6029 1.9 nikita (Specifically, to get a field, 6030 1.9 nikita you must add the letter between parentheses in the field's comment 6031 1.9 nikita to the parameter <code>what</code> of <a href="#lua_getinfo"><code>lua_getinfo</code></a>.) 6032 1.1 mbalmer 6033 1.1 mbalmer 6034 1.1 mbalmer <p> 6035 1.1 mbalmer The fields of <a href="#lua_Debug"><code>lua_Debug</code></a> have the following meaning: 6036 1.1 mbalmer 6037 1.1 mbalmer <ul> 6038 1.1 mbalmer 6039 1.2 lneto <li><b><code>source</code>: </b> 6040 1.9 nikita the source of the chunk that created the function. 6041 1.2 lneto If <code>source</code> starts with a '<code>@</code>', 6042 1.2 lneto it means that the function was defined in a file where 6043 1.2 lneto the file name follows the '<code>@</code>'. 6044 1.2 lneto If <code>source</code> starts with a '<code>=</code>', 6045 1.9 nikita the remainder of its contents describes the source in a user-dependent manner. 6046 1.2 lneto Otherwise, 6047 1.2 lneto the function was defined in a string where 6048 1.2 lneto <code>source</code> is that string. 6049 1.1 mbalmer </li> 6050 1.1 mbalmer 6051 1.9 nikita <li><b><code>srclen</code>: </b> 6052 1.9 nikita The length of the string <code>source</code>. 6053 1.9 nikita </li> 6054 1.9 nikita 6055 1.2 lneto <li><b><code>short_src</code>: </b> 6056 1.1 mbalmer a "printable" version of <code>source</code>, to be used in error messages. 6057 1.1 mbalmer </li> 6058 1.1 mbalmer 6059 1.2 lneto <li><b><code>linedefined</code>: </b> 6060 1.1 mbalmer the line number where the definition of the function starts. 6061 1.1 mbalmer </li> 6062 1.1 mbalmer 6063 1.2 lneto <li><b><code>lastlinedefined</code>: </b> 6064 1.1 mbalmer the line number where the definition of the function ends. 6065 1.1 mbalmer </li> 6066 1.1 mbalmer 6067 1.2 lneto <li><b><code>what</code>: </b> 6068 1.1 mbalmer the string <code>"Lua"</code> if the function is a Lua function, 6069 1.1 mbalmer <code>"C"</code> if it is a C function, 6070 1.2 lneto <code>"main"</code> if it is the main part of a chunk. 6071 1.1 mbalmer </li> 6072 1.1 mbalmer 6073 1.2 lneto <li><b><code>currentline</code>: </b> 6074 1.1 mbalmer the current line where the given function is executing. 6075 1.1 mbalmer When no line information is available, 6076 1.1 mbalmer <code>currentline</code> is set to -1. 6077 1.1 mbalmer </li> 6078 1.1 mbalmer 6079 1.2 lneto <li><b><code>name</code>: </b> 6080 1.1 mbalmer a reasonable name for the given function. 6081 1.1 mbalmer Because functions in Lua are first-class values, 6082 1.1 mbalmer they do not have a fixed name: 6083 1.1 mbalmer some functions can be the value of multiple global variables, 6084 1.1 mbalmer while others can be stored only in a table field. 6085 1.1 mbalmer The <code>lua_getinfo</code> function checks how the function was 6086 1.1 mbalmer called to find a suitable name. 6087 1.1 mbalmer If it cannot find a name, 6088 1.1 mbalmer then <code>name</code> is set to <code>NULL</code>. 6089 1.1 mbalmer </li> 6090 1.1 mbalmer 6091 1.2 lneto <li><b><code>namewhat</code>: </b> 6092 1.1 mbalmer explains the <code>name</code> field. 6093 1.1 mbalmer The value of <code>namewhat</code> can be 6094 1.1 mbalmer <code>"global"</code>, <code>"local"</code>, <code>"method"</code>, 6095 1.1 mbalmer <code>"field"</code>, <code>"upvalue"</code>, or <code>""</code> (the empty string), 6096 1.1 mbalmer according to how the function was called. 6097 1.1 mbalmer (Lua uses the empty string when no other option seems to apply.) 6098 1.1 mbalmer </li> 6099 1.1 mbalmer 6100 1.2 lneto <li><b><code>istailcall</code>: </b> 6101 1.2 lneto true if this function invocation was called by a tail call. 6102 1.2 lneto In this case, the caller of this level is not in the stack. 6103 1.2 lneto </li> 6104 1.2 lneto 6105 1.2 lneto <li><b><code>nups</code>: </b> 6106 1.1 mbalmer the number of upvalues of the function. 6107 1.1 mbalmer </li> 6108 1.1 mbalmer 6109 1.2 lneto <li><b><code>nparams</code>: </b> 6110 1.9 nikita the number of parameters of the function 6111 1.2 lneto (always 0 for C functions). 6112 1.2 lneto </li> 6113 1.2 lneto 6114 1.2 lneto <li><b><code>isvararg</code>: </b> 6115 1.10 nikita true if the function is a variadic function 6116 1.2 lneto (always true for C functions). 6117 1.2 lneto </li> 6118 1.2 lneto 6119 1.9 nikita <li><b><code>ftransfer</code>: </b> 6120 1.9 nikita the index in the stack of the first value being "transferred", 6121 1.9 nikita that is, parameters in a call or return values in a return. 6122 1.9 nikita (The other values are in consecutive indices.) 6123 1.9 nikita Using this index, you can access and modify these values 6124 1.9 nikita through <a href="#lua_getlocal"><code>lua_getlocal</code></a> and <a href="#lua_setlocal"><code>lua_setlocal</code></a>. 6125 1.9 nikita This field is only meaningful during a 6126 1.9 nikita call hook, denoting the first parameter, 6127 1.9 nikita or a return hook, denoting the first value being returned. 6128 1.9 nikita (For call hooks, this value is always 1.) 6129 1.9 nikita </li> 6130 1.9 nikita 6131 1.9 nikita <li><b><code>ntransfer</code>: </b> 6132 1.9 nikita The number of values being transferred (see previous item). 6133 1.9 nikita (For calls of Lua functions, 6134 1.9 nikita this value is always equal to <code>nparams</code>.) 6135 1.9 nikita </li> 6136 1.9 nikita 6137 1.1 mbalmer </ul> 6138 1.1 mbalmer 6139 1.1 mbalmer 6140 1.1 mbalmer 6141 1.1 mbalmer 6142 1.1 mbalmer <hr><h3><a name="lua_gethook"><code>lua_gethook</code></a></h3><p> 6143 1.2 lneto <span class="apii">[-0, +0, –]</span> 6144 1.1 mbalmer <pre>lua_Hook lua_gethook (lua_State *L);</pre> 6145 1.1 mbalmer 6146 1.1 mbalmer <p> 6147 1.1 mbalmer Returns the current hook function. 6148 1.1 mbalmer 6149 1.1 mbalmer 6150 1.1 mbalmer 6151 1.1 mbalmer 6152 1.1 mbalmer 6153 1.1 mbalmer <hr><h3><a name="lua_gethookcount"><code>lua_gethookcount</code></a></h3><p> 6154 1.2 lneto <span class="apii">[-0, +0, –]</span> 6155 1.1 mbalmer <pre>int lua_gethookcount (lua_State *L);</pre> 6156 1.1 mbalmer 6157 1.1 mbalmer <p> 6158 1.1 mbalmer Returns the current hook count. 6159 1.1 mbalmer 6160 1.1 mbalmer 6161 1.1 mbalmer 6162 1.1 mbalmer 6163 1.1 mbalmer 6164 1.1 mbalmer <hr><h3><a name="lua_gethookmask"><code>lua_gethookmask</code></a></h3><p> 6165 1.2 lneto <span class="apii">[-0, +0, –]</span> 6166 1.1 mbalmer <pre>int lua_gethookmask (lua_State *L);</pre> 6167 1.1 mbalmer 6168 1.1 mbalmer <p> 6169 1.1 mbalmer Returns the current hook mask. 6170 1.1 mbalmer 6171 1.1 mbalmer 6172 1.1 mbalmer 6173 1.1 mbalmer 6174 1.1 mbalmer 6175 1.1 mbalmer <hr><h3><a name="lua_getinfo"><code>lua_getinfo</code></a></h3><p> 6176 1.9 nikita <span class="apii">[-(0|1), +(0|1|2), <em>m</em>]</span> 6177 1.1 mbalmer <pre>int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar);</pre> 6178 1.1 mbalmer 6179 1.1 mbalmer <p> 6180 1.2 lneto Gets information about a specific function or function invocation. 6181 1.1 mbalmer 6182 1.1 mbalmer 6183 1.1 mbalmer <p> 6184 1.1 mbalmer To get information about a function invocation, 6185 1.1 mbalmer the parameter <code>ar</code> must be a valid activation record that was 6186 1.1 mbalmer filled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or 6187 1.1 mbalmer given as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>). 6188 1.1 mbalmer 6189 1.1 mbalmer 6190 1.1 mbalmer <p> 6191 1.8 alnsn To get information about a function, you push it onto the stack 6192 1.1 mbalmer and start the <code>what</code> string with the character '<code>></code>'. 6193 1.1 mbalmer (In that case, 6194 1.2 lneto <code>lua_getinfo</code> pops the function from the top of the stack.) 6195 1.1 mbalmer For instance, to know in which line a function <code>f</code> was defined, 6196 1.1 mbalmer you can write the following code: 6197 1.1 mbalmer 6198 1.1 mbalmer <pre> 6199 1.1 mbalmer lua_Debug ar; 6200 1.2 lneto lua_getglobal(L, "f"); /* get global 'f' */ 6201 1.1 mbalmer lua_getinfo(L, ">S", &ar); 6202 1.1 mbalmer printf("%d\n", ar.linedefined); 6203 1.1 mbalmer </pre> 6204 1.1 mbalmer 6205 1.1 mbalmer <p> 6206 1.1 mbalmer Each character in the string <code>what</code> 6207 1.1 mbalmer selects some fields of the structure <code>ar</code> to be filled or 6208 1.9 nikita a value to be pushed on the stack. 6209 1.9 nikita (These characters are also documented in the declaration of 6210 1.9 nikita the structure <a href="#lua_Debug"><code>lua_Debug</code></a>, 6211 1.9 nikita between parentheses in the comments following each field.) 6212 1.1 mbalmer 6213 1.1 mbalmer <ul> 6214 1.1 mbalmer 6215 1.9 nikita <li><b>'<code>f</code>': </b> 6216 1.9 nikita pushes onto the stack the function that is 6217 1.9 nikita running at the given level; 6218 1.9 nikita </li> 6219 1.9 nikita 6220 1.9 nikita <li><b>'<code>l</code>': </b> fills in the field <code>currentline</code>; 6221 1.9 nikita </li> 6222 1.9 nikita 6223 1.9 nikita <li><b>'<code>n</code>': </b> fills in the fields <code>name</code> and <code>namewhat</code>; 6224 1.9 nikita </li> 6225 1.9 nikita 6226 1.9 nikita <li><b>'<code>r</code>': </b> fills in the fields <code>ftransfer</code> and <code>ntransfer</code>; 6227 1.1 mbalmer </li> 6228 1.1 mbalmer 6229 1.2 lneto <li><b>'<code>S</code>': </b> 6230 1.1 mbalmer fills in the fields <code>source</code>, <code>short_src</code>, 6231 1.1 mbalmer <code>linedefined</code>, <code>lastlinedefined</code>, and <code>what</code>; 6232 1.1 mbalmer </li> 6233 1.1 mbalmer 6234 1.2 lneto <li><b>'<code>t</code>': </b> fills in the field <code>istailcall</code>; 6235 1.1 mbalmer </li> 6236 1.1 mbalmer 6237 1.2 lneto <li><b>'<code>u</code>': </b> fills in the fields 6238 1.2 lneto <code>nups</code>, <code>nparams</code>, and <code>isvararg</code>; 6239 1.1 mbalmer </li> 6240 1.1 mbalmer 6241 1.2 lneto <li><b>'<code>L</code>': </b> 6242 1.9 nikita pushes onto the stack a table whose indices are 6243 1.9 nikita the lines on the function with some associated code, 6244 1.9 nikita that is, the lines where you can put a break point. 6245 1.9 nikita (Lines with no code include empty lines and comments.) 6246 1.2 lneto If this option is given together with option '<code>f</code>', 6247 1.2 lneto its table is pushed after the function. 6248 1.9 nikita This is the only option that can raise a memory error. 6249 1.1 mbalmer </li> 6250 1.1 mbalmer 6251 1.1 mbalmer </ul> 6252 1.1 mbalmer 6253 1.1 mbalmer <p> 6254 1.9 nikita This function returns 0 to signal an invalid option in <code>what</code>; 6255 1.9 nikita even then the valid options are handled correctly. 6256 1.1 mbalmer 6257 1.1 mbalmer 6258 1.1 mbalmer 6259 1.1 mbalmer 6260 1.1 mbalmer 6261 1.1 mbalmer <hr><h3><a name="lua_getlocal"><code>lua_getlocal</code></a></h3><p> 6262 1.2 lneto <span class="apii">[-0, +(0|1), –]</span> 6263 1.3 lneto <pre>const char *lua_getlocal (lua_State *L, const lua_Debug *ar, int n);</pre> 6264 1.1 mbalmer 6265 1.1 mbalmer <p> 6266 1.9 nikita Gets information about a local variable or a temporary value 6267 1.9 nikita of a given activation record or a given function. 6268 1.2 lneto 6269 1.2 lneto 6270 1.2 lneto <p> 6271 1.2 lneto In the first case, 6272 1.2 lneto the parameter <code>ar</code> must be a valid activation record that was 6273 1.1 mbalmer filled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or 6274 1.1 mbalmer given as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>). 6275 1.2 lneto The index <code>n</code> selects which local variable to inspect; 6276 1.2 lneto see <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for details about variable indices 6277 1.2 lneto and names. 6278 1.2 lneto 6279 1.2 lneto 6280 1.2 lneto <p> 6281 1.1 mbalmer <a href="#lua_getlocal"><code>lua_getlocal</code></a> pushes the variable's value onto the stack 6282 1.1 mbalmer and returns its name. 6283 1.1 mbalmer 6284 1.1 mbalmer 6285 1.1 mbalmer <p> 6286 1.2 lneto In the second case, <code>ar</code> must be <code>NULL</code> and the function 6287 1.9 nikita to be inspected must be on the top of the stack. 6288 1.2 lneto In this case, only parameters of Lua functions are visible 6289 1.2 lneto (as there is no information about what variables are active) 6290 1.2 lneto and no values are pushed onto the stack. 6291 1.1 mbalmer 6292 1.1 mbalmer 6293 1.1 mbalmer <p> 6294 1.1 mbalmer Returns <code>NULL</code> (and pushes nothing) 6295 1.1 mbalmer when the index is greater than 6296 1.1 mbalmer the number of active local variables. 6297 1.1 mbalmer 6298 1.1 mbalmer 6299 1.1 mbalmer 6300 1.1 mbalmer 6301 1.1 mbalmer 6302 1.1 mbalmer <hr><h3><a name="lua_getstack"><code>lua_getstack</code></a></h3><p> 6303 1.2 lneto <span class="apii">[-0, +0, –]</span> 6304 1.1 mbalmer <pre>int lua_getstack (lua_State *L, int level, lua_Debug *ar);</pre> 6305 1.1 mbalmer 6306 1.1 mbalmer <p> 6307 1.2 lneto Gets information about the interpreter runtime stack. 6308 1.1 mbalmer 6309 1.1 mbalmer 6310 1.1 mbalmer <p> 6311 1.1 mbalmer This function fills parts of a <a href="#lua_Debug"><code>lua_Debug</code></a> structure with 6312 1.1 mbalmer an identification of the <em>activation record</em> 6313 1.1 mbalmer of the function executing at a given level. 6314 1.1 mbalmer Level 0 is the current running function, 6315 1.2 lneto whereas level <em>n+1</em> is the function that has called level <em>n</em> 6316 1.9 nikita (except for tail calls, which do not count in the stack). 6317 1.9 nikita When called with a level greater than the stack depth, 6318 1.9 nikita <a href="#lua_getstack"><code>lua_getstack</code></a> returns 0; 6319 1.9 nikita otherwise it returns 1. 6320 1.1 mbalmer 6321 1.1 mbalmer 6322 1.1 mbalmer 6323 1.1 mbalmer 6324 1.1 mbalmer 6325 1.1 mbalmer <hr><h3><a name="lua_getupvalue"><code>lua_getupvalue</code></a></h3><p> 6326 1.2 lneto <span class="apii">[-0, +(0|1), –]</span> 6327 1.1 mbalmer <pre>const char *lua_getupvalue (lua_State *L, int funcindex, int n);</pre> 6328 1.1 mbalmer 6329 1.1 mbalmer <p> 6330 1.4 mbalmer Gets information about the <code>n</code>-th upvalue 6331 1.4 mbalmer of the closure at index <code>funcindex</code>. 6332 1.4 mbalmer It pushes the upvalue's value onto the stack 6333 1.4 mbalmer and returns its name. 6334 1.4 mbalmer Returns <code>NULL</code> (and pushes nothing) 6335 1.4 mbalmer when the index <code>n</code> is greater than the number of upvalues. 6336 1.4 mbalmer 6337 1.4 mbalmer 6338 1.4 mbalmer <p> 6339 1.9 nikita See <a href="#pdf-debug.getupvalue"><code>debug.getupvalue</code></a> for more information about upvalues. 6340 1.1 mbalmer 6341 1.1 mbalmer 6342 1.1 mbalmer 6343 1.1 mbalmer 6344 1.1 mbalmer 6345 1.1 mbalmer <hr><h3><a name="lua_Hook"><code>lua_Hook</code></a></h3> 6346 1.1 mbalmer <pre>typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar);</pre> 6347 1.1 mbalmer 6348 1.1 mbalmer <p> 6349 1.1 mbalmer Type for debugging hook functions. 6350 1.1 mbalmer 6351 1.1 mbalmer 6352 1.1 mbalmer <p> 6353 1.1 mbalmer Whenever a hook is called, its <code>ar</code> argument has its field 6354 1.1 mbalmer <code>event</code> set to the specific event that triggered the hook. 6355 1.1 mbalmer Lua identifies these events with the following constants: 6356 1.1 mbalmer <a name="pdf-LUA_HOOKCALL"><code>LUA_HOOKCALL</code></a>, <a name="pdf-LUA_HOOKRET"><code>LUA_HOOKRET</code></a>, 6357 1.2 lneto <a name="pdf-LUA_HOOKTAILCALL"><code>LUA_HOOKTAILCALL</code></a>, <a name="pdf-LUA_HOOKLINE"><code>LUA_HOOKLINE</code></a>, 6358 1.1 mbalmer and <a name="pdf-LUA_HOOKCOUNT"><code>LUA_HOOKCOUNT</code></a>. 6359 1.1 mbalmer Moreover, for line events, the field <code>currentline</code> is also set. 6360 1.1 mbalmer To get the value of any other field in <code>ar</code>, 6361 1.1 mbalmer the hook must call <a href="#lua_getinfo"><code>lua_getinfo</code></a>. 6362 1.2 lneto 6363 1.2 lneto 6364 1.2 lneto <p> 6365 1.2 lneto For call events, <code>event</code> can be <code>LUA_HOOKCALL</code>, 6366 1.2 lneto the normal value, or <code>LUA_HOOKTAILCALL</code>, for a tail call; 6367 1.2 lneto in this case, there will be no corresponding return event. 6368 1.1 mbalmer 6369 1.1 mbalmer 6370 1.1 mbalmer <p> 6371 1.1 mbalmer While Lua is running a hook, it disables other calls to hooks. 6372 1.1 mbalmer Therefore, if a hook calls back Lua to execute a function or a chunk, 6373 1.1 mbalmer this execution occurs without any calls to hooks. 6374 1.1 mbalmer 6375 1.1 mbalmer 6376 1.2 lneto <p> 6377 1.2 lneto Hook functions cannot have continuations, 6378 1.2 lneto that is, they cannot call <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 6379 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>. 6380 1.2 lneto 6381 1.2 lneto 6382 1.2 lneto <p> 6383 1.2 lneto Hook functions can yield under the following conditions: 6384 1.4 mbalmer Only count and line events can yield; 6385 1.4 mbalmer to yield, a hook function must finish its execution 6386 1.4 mbalmer calling <a href="#lua_yield"><code>lua_yield</code></a> with <code>nresults</code> equal to zero 6387 1.4 mbalmer (that is, with no values). 6388 1.2 lneto 6389 1.2 lneto 6390 1.1 mbalmer 6391 1.1 mbalmer 6392 1.1 mbalmer 6393 1.1 mbalmer <hr><h3><a name="lua_sethook"><code>lua_sethook</code></a></h3><p> 6394 1.2 lneto <span class="apii">[-0, +0, –]</span> 6395 1.2 lneto <pre>void lua_sethook (lua_State *L, lua_Hook f, int mask, int count);</pre> 6396 1.1 mbalmer 6397 1.1 mbalmer <p> 6398 1.1 mbalmer Sets the debugging hook function. 6399 1.1 mbalmer 6400 1.1 mbalmer 6401 1.1 mbalmer <p> 6402 1.1 mbalmer Argument <code>f</code> is the hook function. 6403 1.1 mbalmer <code>mask</code> specifies on which events the hook will be called: 6404 1.6 salazar it is formed by a bitwise OR of the constants 6405 1.1 mbalmer <a name="pdf-LUA_MASKCALL"><code>LUA_MASKCALL</code></a>, 6406 1.1 mbalmer <a name="pdf-LUA_MASKRET"><code>LUA_MASKRET</code></a>, 6407 1.1 mbalmer <a name="pdf-LUA_MASKLINE"><code>LUA_MASKLINE</code></a>, 6408 1.1 mbalmer and <a name="pdf-LUA_MASKCOUNT"><code>LUA_MASKCOUNT</code></a>. 6409 1.1 mbalmer The <code>count</code> argument is only meaningful when the mask 6410 1.1 mbalmer includes <code>LUA_MASKCOUNT</code>. 6411 1.1 mbalmer For each event, the hook is called as explained below: 6412 1.1 mbalmer 6413 1.1 mbalmer <ul> 6414 1.1 mbalmer 6415 1.2 lneto <li><b>The call hook: </b> is called when the interpreter calls a function. 6416 1.9 nikita The hook is called just after Lua enters the new function. 6417 1.1 mbalmer </li> 6418 1.1 mbalmer 6419 1.2 lneto <li><b>The return hook: </b> is called when the interpreter returns from a function. 6420 1.1 mbalmer The hook is called just before Lua leaves the function. 6421 1.1 mbalmer </li> 6422 1.1 mbalmer 6423 1.2 lneto <li><b>The line hook: </b> is called when the interpreter is about to 6424 1.1 mbalmer start the execution of a new line of code, 6425 1.1 mbalmer or when it jumps back in the code (even to the same line). 6426 1.9 nikita This event only happens while Lua is executing a Lua function. 6427 1.1 mbalmer </li> 6428 1.1 mbalmer 6429 1.2 lneto <li><b>The count hook: </b> is called after the interpreter executes every 6430 1.1 mbalmer <code>count</code> instructions. 6431 1.9 nikita This event only happens while Lua is executing a Lua function. 6432 1.1 mbalmer </li> 6433 1.1 mbalmer 6434 1.1 mbalmer </ul> 6435 1.1 mbalmer 6436 1.1 mbalmer <p> 6437 1.9 nikita Hooks are disabled by setting <code>mask</code> to zero. 6438 1.1 mbalmer 6439 1.1 mbalmer 6440 1.1 mbalmer 6441 1.1 mbalmer 6442 1.1 mbalmer 6443 1.1 mbalmer <hr><h3><a name="lua_setlocal"><code>lua_setlocal</code></a></h3><p> 6444 1.2 lneto <span class="apii">[-(0|1), +0, –]</span> 6445 1.3 lneto <pre>const char *lua_setlocal (lua_State *L, const lua_Debug *ar, int n);</pre> 6446 1.1 mbalmer 6447 1.1 mbalmer <p> 6448 1.1 mbalmer Sets the value of a local variable of a given activation record. 6449 1.9 nikita It assigns the value on the top of the stack 6450 1.1 mbalmer to the variable and returns its name. 6451 1.1 mbalmer It also pops the value from the stack. 6452 1.1 mbalmer 6453 1.1 mbalmer 6454 1.1 mbalmer <p> 6455 1.1 mbalmer Returns <code>NULL</code> (and pops nothing) 6456 1.1 mbalmer when the index is greater than 6457 1.1 mbalmer the number of active local variables. 6458 1.1 mbalmer 6459 1.1 mbalmer 6460 1.4 mbalmer <p> 6461 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>. 6462 1.4 mbalmer 6463 1.4 mbalmer 6464 1.1 mbalmer 6465 1.1 mbalmer 6466 1.1 mbalmer 6467 1.1 mbalmer <hr><h3><a name="lua_setupvalue"><code>lua_setupvalue</code></a></h3><p> 6468 1.2 lneto <span class="apii">[-(0|1), +0, –]</span> 6469 1.1 mbalmer <pre>const char *lua_setupvalue (lua_State *L, int funcindex, int n);</pre> 6470 1.1 mbalmer 6471 1.1 mbalmer <p> 6472 1.1 mbalmer Sets the value of a closure's upvalue. 6473 1.9 nikita It assigns the value on the top of the stack 6474 1.1 mbalmer to the upvalue and returns its name. 6475 1.1 mbalmer It also pops the value from the stack. 6476 1.1 mbalmer 6477 1.1 mbalmer 6478 1.1 mbalmer <p> 6479 1.1 mbalmer Returns <code>NULL</code> (and pops nothing) 6480 1.4 mbalmer when the index <code>n</code> is greater than the number of upvalues. 6481 1.4 mbalmer 6482 1.4 mbalmer 6483 1.4 mbalmer <p> 6484 1.9 nikita Parameters <code>funcindex</code> and <code>n</code> are as in 6485 1.9 nikita the function <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>. 6486 1.1 mbalmer 6487 1.1 mbalmer 6488 1.1 mbalmer 6489 1.1 mbalmer 6490 1.1 mbalmer 6491 1.2 lneto <hr><h3><a name="lua_upvalueid"><code>lua_upvalueid</code></a></h3><p> 6492 1.2 lneto <span class="apii">[-0, +0, –]</span> 6493 1.2 lneto <pre>void *lua_upvalueid (lua_State *L, int funcindex, int n);</pre> 6494 1.2 lneto 6495 1.2 lneto <p> 6496 1.3 lneto Returns a unique identifier for the upvalue numbered <code>n</code> 6497 1.2 lneto from the closure at index <code>funcindex</code>. 6498 1.2 lneto 6499 1.2 lneto 6500 1.2 lneto <p> 6501 1.2 lneto These unique identifiers allow a program to check whether different 6502 1.2 lneto closures share upvalues. 6503 1.2 lneto Lua closures that share an upvalue 6504 1.2 lneto (that is, that access a same external local variable) 6505 1.2 lneto will return identical ids for those upvalue indices. 6506 1.2 lneto 6507 1.2 lneto 6508 1.4 mbalmer <p> 6509 1.9 nikita Parameters <code>funcindex</code> and <code>n</code> are as in 6510 1.9 nikita the function <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>, 6511 1.4 mbalmer but <code>n</code> cannot be greater than the number of upvalues. 6512 1.4 mbalmer 6513 1.4 mbalmer 6514 1.2 lneto 6515 1.2 lneto 6516 1.2 lneto 6517 1.2 lneto <hr><h3><a name="lua_upvaluejoin"><code>lua_upvaluejoin</code></a></h3><p> 6518 1.2 lneto <span class="apii">[-0, +0, –]</span> 6519 1.2 lneto <pre>void lua_upvaluejoin (lua_State *L, int funcindex1, int n1, 6520 1.2 lneto int funcindex2, int n2);</pre> 6521 1.2 lneto 6522 1.2 lneto <p> 6523 1.2 lneto Make the <code>n1</code>-th upvalue of the Lua closure at index <code>funcindex1</code> 6524 1.2 lneto refer to the <code>n2</code>-th upvalue of the Lua closure at index <code>funcindex2</code>. 6525 1.2 lneto 6526 1.2 lneto 6527 1.2 lneto 6528 1.2 lneto 6529 1.2 lneto 6530 1.1 mbalmer 6531 1.1 mbalmer 6532 1.2 lneto <h1>5 – <a name="5">The Auxiliary Library</a></h1> 6533 1.1 mbalmer 6534 1.9 nikita 6535 1.9 nikita 6536 1.1 mbalmer <p> 6537 1.1 mbalmer 6538 1.1 mbalmer The <em>auxiliary library</em> provides several convenient functions 6539 1.1 mbalmer to interface C with Lua. 6540 1.2 lneto While the basic API provides the primitive functions for all 6541 1.1 mbalmer interactions between C and Lua, 6542 1.1 mbalmer the auxiliary library provides higher-level functions for some 6543 1.1 mbalmer common tasks. 6544 1.1 mbalmer 6545 1.1 mbalmer 6546 1.1 mbalmer <p> 6547 1.2 lneto All functions and types from the auxiliary library 6548 1.1 mbalmer are defined in header file <code>lauxlib.h</code> and 6549 1.1 mbalmer have a prefix <code>luaL_</code>. 6550 1.1 mbalmer 6551 1.1 mbalmer 6552 1.1 mbalmer <p> 6553 1.1 mbalmer All functions in the auxiliary library are built on 6554 1.1 mbalmer top of the basic API, 6555 1.2 lneto and so they provide nothing that cannot be done with that API. 6556 1.2 lneto Nevertheless, the use of the auxiliary library ensures 6557 1.2 lneto more consistency to your code. 6558 1.2 lneto 6559 1.2 lneto 6560 1.2 lneto <p> 6561 1.2 lneto Several functions in the auxiliary library use internally some 6562 1.2 lneto extra stack slots. 6563 1.2 lneto When a function in the auxiliary library uses less than five slots, 6564 1.2 lneto it does not check the stack size; 6565 1.2 lneto it simply assumes that there are enough slots. 6566 1.1 mbalmer 6567 1.1 mbalmer 6568 1.1 mbalmer <p> 6569 1.1 mbalmer Several functions in the auxiliary library are used to 6570 1.1 mbalmer check C function arguments. 6571 1.1 mbalmer Because the error message is formatted for arguments 6572 1.1 mbalmer (e.g., "<code>bad argument #1</code>"), 6573 1.1 mbalmer you should not use these functions for other stack values. 6574 1.1 mbalmer 6575 1.1 mbalmer 6576 1.2 lneto <p> 6577 1.2 lneto Functions called <code>luaL_check*</code> 6578 1.2 lneto always raise an error if the check is not satisfied. 6579 1.2 lneto 6580 1.2 lneto 6581 1.1 mbalmer 6582 1.9 nikita 6583 1.9 nikita 6584 1.2 lneto <h2>5.1 – <a name="5.1">Functions and Types</a></h2> 6585 1.1 mbalmer 6586 1.1 mbalmer <p> 6587 1.1 mbalmer Here we list all functions and types from the auxiliary library 6588 1.1 mbalmer in alphabetical order. 6589 1.1 mbalmer 6590 1.1 mbalmer 6591 1.1 mbalmer 6592 1.1 mbalmer <hr><h3><a name="luaL_addchar"><code>luaL_addchar</code></a></h3><p> 6593 1.5 lneto <span class="apii">[-?, +?, <em>m</em>]</span> 6594 1.1 mbalmer <pre>void luaL_addchar (luaL_Buffer *B, char c);</pre> 6595 1.1 mbalmer 6596 1.1 mbalmer <p> 6597 1.2 lneto Adds the byte <code>c</code> to the buffer <code>B</code> 6598 1.1 mbalmer (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6599 1.1 mbalmer 6600 1.1 mbalmer 6601 1.1 mbalmer 6602 1.1 mbalmer 6603 1.1 mbalmer 6604 1.9 nikita <hr><h3><a name="luaL_addgsub"><code>luaL_addgsub</code></a></h3><p> 6605 1.9 nikita <span class="apii">[-?, +?, <em>m</em>]</span> 6606 1.9 nikita <pre>const void luaL_addgsub (luaL_Buffer *B, const char *s, 6607 1.9 nikita const char *p, const char *r);</pre> 6608 1.9 nikita 6609 1.9 nikita <p> 6610 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>), 6611 1.9 nikita replacing any occurrence of the string <code>p</code> 6612 1.9 nikita with the string <code>r</code>. 6613 1.9 nikita 6614 1.9 nikita 6615 1.9 nikita 6616 1.9 nikita 6617 1.9 nikita 6618 1.1 mbalmer <hr><h3><a name="luaL_addlstring"><code>luaL_addlstring</code></a></h3><p> 6619 1.5 lneto <span class="apii">[-?, +?, <em>m</em>]</span> 6620 1.1 mbalmer <pre>void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l);</pre> 6621 1.1 mbalmer 6622 1.1 mbalmer <p> 6623 1.1 mbalmer Adds the string pointed to by <code>s</code> with length <code>l</code> to 6624 1.1 mbalmer the buffer <code>B</code> 6625 1.1 mbalmer (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6626 1.2 lneto The string can contain embedded zeros. 6627 1.1 mbalmer 6628 1.1 mbalmer 6629 1.1 mbalmer 6630 1.1 mbalmer 6631 1.1 mbalmer 6632 1.1 mbalmer <hr><h3><a name="luaL_addsize"><code>luaL_addsize</code></a></h3><p> 6633 1.5 lneto <span class="apii">[-?, +?, –]</span> 6634 1.1 mbalmer <pre>void luaL_addsize (luaL_Buffer *B, size_t n);</pre> 6635 1.1 mbalmer 6636 1.1 mbalmer <p> 6637 1.9 nikita Adds to the buffer <code>B</code> 6638 1.1 mbalmer a string of length <code>n</code> previously copied to the 6639 1.1 mbalmer buffer area (see <a href="#luaL_prepbuffer"><code>luaL_prepbuffer</code></a>). 6640 1.1 mbalmer 6641 1.1 mbalmer 6642 1.1 mbalmer 6643 1.1 mbalmer 6644 1.1 mbalmer 6645 1.1 mbalmer <hr><h3><a name="luaL_addstring"><code>luaL_addstring</code></a></h3><p> 6646 1.5 lneto <span class="apii">[-?, +?, <em>m</em>]</span> 6647 1.1 mbalmer <pre>void luaL_addstring (luaL_Buffer *B, const char *s);</pre> 6648 1.1 mbalmer 6649 1.1 mbalmer <p> 6650 1.1 mbalmer Adds the zero-terminated string pointed to by <code>s</code> 6651 1.1 mbalmer to the buffer <code>B</code> 6652 1.1 mbalmer (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6653 1.1 mbalmer 6654 1.1 mbalmer 6655 1.1 mbalmer 6656 1.1 mbalmer 6657 1.1 mbalmer 6658 1.1 mbalmer <hr><h3><a name="luaL_addvalue"><code>luaL_addvalue</code></a></h3><p> 6659 1.9 nikita <span class="apii">[-?, +?, <em>m</em>]</span> 6660 1.1 mbalmer <pre>void luaL_addvalue (luaL_Buffer *B);</pre> 6661 1.1 mbalmer 6662 1.1 mbalmer <p> 6663 1.9 nikita Adds the value on the top of the stack 6664 1.1 mbalmer to the buffer <code>B</code> 6665 1.1 mbalmer (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6666 1.1 mbalmer Pops the value. 6667 1.1 mbalmer 6668 1.1 mbalmer 6669 1.1 mbalmer <p> 6670 1.1 mbalmer This is the only function on string buffers that can (and must) 6671 1.1 mbalmer be called with an extra element on the stack, 6672 1.1 mbalmer which is the value to be added to the buffer. 6673 1.1 mbalmer 6674 1.1 mbalmer 6675 1.1 mbalmer 6676 1.1 mbalmer 6677 1.1 mbalmer 6678 1.1 mbalmer <hr><h3><a name="luaL_argcheck"><code>luaL_argcheck</code></a></h3><p> 6679 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 6680 1.1 mbalmer <pre>void luaL_argcheck (lua_State *L, 6681 1.1 mbalmer int cond, 6682 1.2 lneto int arg, 6683 1.1 mbalmer const char *extramsg);</pre> 6684 1.1 mbalmer 6685 1.1 mbalmer <p> 6686 1.1 mbalmer Checks whether <code>cond</code> is true. 6687 1.2 lneto If it is not, raises an error with a standard message (see <a href="#luaL_argerror"><code>luaL_argerror</code></a>). 6688 1.1 mbalmer 6689 1.1 mbalmer 6690 1.1 mbalmer 6691 1.1 mbalmer 6692 1.1 mbalmer 6693 1.1 mbalmer <hr><h3><a name="luaL_argerror"><code>luaL_argerror</code></a></h3><p> 6694 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 6695 1.2 lneto <pre>int luaL_argerror (lua_State *L, int arg, const char *extramsg);</pre> 6696 1.1 mbalmer 6697 1.1 mbalmer <p> 6698 1.2 lneto Raises an error reporting a problem with argument <code>arg</code> 6699 1.7 mbalmer of the C function that called it, 6700 1.2 lneto using a standard message 6701 1.2 lneto that includes <code>extramsg</code> as a comment: 6702 1.1 mbalmer 6703 1.1 mbalmer <pre> 6704 1.2 lneto bad argument #<em>arg</em> to '<em>funcname</em>' (<em>extramsg</em>) 6705 1.2 lneto </pre><p> 6706 1.2 lneto This function never returns. 6707 1.1 mbalmer 6708 1.1 mbalmer 6709 1.1 mbalmer 6710 1.1 mbalmer 6711 1.1 mbalmer 6712 1.9 nikita <hr><h3><a name="luaL_argexpected"><code>luaL_argexpected</code></a></h3><p> 6713 1.9 nikita <span class="apii">[-0, +0, <em>v</em>]</span> 6714 1.9 nikita <pre>void luaL_argexpected (lua_State *L, 6715 1.9 nikita int cond, 6716 1.9 nikita int arg, 6717 1.9 nikita const char *tname);</pre> 6718 1.9 nikita 6719 1.9 nikita <p> 6720 1.9 nikita Checks whether <code>cond</code> is true. 6721 1.9 nikita If it is not, raises an error about the type of the argument <code>arg</code> 6722 1.9 nikita with a standard message (see <a href="#luaL_typeerror"><code>luaL_typeerror</code></a>). 6723 1.9 nikita 6724 1.9 nikita 6725 1.9 nikita 6726 1.9 nikita 6727 1.9 nikita 6728 1.1 mbalmer <hr><h3><a name="luaL_Buffer"><code>luaL_Buffer</code></a></h3> 6729 1.1 mbalmer <pre>typedef struct luaL_Buffer luaL_Buffer;</pre> 6730 1.1 mbalmer 6731 1.1 mbalmer <p> 6732 1.1 mbalmer Type for a <em>string buffer</em>. 6733 1.1 mbalmer 6734 1.1 mbalmer 6735 1.1 mbalmer <p> 6736 1.1 mbalmer A string buffer allows C code to build Lua strings piecemeal. 6737 1.1 mbalmer Its pattern of use is as follows: 6738 1.1 mbalmer 6739 1.1 mbalmer <ul> 6740 1.1 mbalmer 6741 1.2 lneto <li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li> 6742 1.1 mbalmer 6743 1.2 lneto <li>Then initialize it with a call <code>luaL_buffinit(L, &b)</code>.</li> 6744 1.1 mbalmer 6745 1.1 mbalmer <li> 6746 1.2 lneto Then add string pieces to the buffer calling any of 6747 1.1 mbalmer the <code>luaL_add*</code> functions. 6748 1.1 mbalmer </li> 6749 1.1 mbalmer 6750 1.1 mbalmer <li> 6751 1.2 lneto Finish by calling <code>luaL_pushresult(&b)</code>. 6752 1.1 mbalmer This call leaves the final string on the top of the stack. 6753 1.1 mbalmer </li> 6754 1.1 mbalmer 6755 1.1 mbalmer </ul> 6756 1.1 mbalmer 6757 1.1 mbalmer <p> 6758 1.9 nikita If you know beforehand the maximum size of the resulting string, 6759 1.2 lneto you can use the buffer like this: 6760 1.2 lneto 6761 1.2 lneto <ul> 6762 1.2 lneto 6763 1.2 lneto <li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li> 6764 1.2 lneto 6765 1.2 lneto <li>Then initialize it and preallocate a space of 6766 1.2 lneto size <code>sz</code> with a call <code>luaL_buffinitsize(L, &b, sz)</code>.</li> 6767 1.2 lneto 6768 1.9 nikita <li>Then produce the string into that space.</li> 6769 1.2 lneto 6770 1.2 lneto <li> 6771 1.2 lneto Finish by calling <code>luaL_pushresultsize(&b, sz)</code>, 6772 1.2 lneto where <code>sz</code> is the total size of the resulting string 6773 1.9 nikita copied into that space (which may be less than or 6774 1.9 nikita equal to the preallocated size). 6775 1.2 lneto </li> 6776 1.2 lneto 6777 1.2 lneto </ul> 6778 1.2 lneto 6779 1.2 lneto <p> 6780 1.1 mbalmer During its normal operation, 6781 1.1 mbalmer a string buffer uses a variable number of stack slots. 6782 1.1 mbalmer So, while using a buffer, you cannot assume that you know where 6783 1.1 mbalmer the top of the stack is. 6784 1.1 mbalmer You can use the stack between successive calls to buffer operations 6785 1.1 mbalmer as long as that use is balanced; 6786 1.1 mbalmer that is, 6787 1.1 mbalmer when you call a buffer operation, 6788 1.1 mbalmer the stack is at the same level 6789 1.1 mbalmer it was immediately after the previous buffer operation. 6790 1.1 mbalmer (The only exception to this rule is <a href="#luaL_addvalue"><code>luaL_addvalue</code></a>.) 6791 1.9 nikita After calling <a href="#luaL_pushresult"><code>luaL_pushresult</code></a>, 6792 1.9 nikita the stack is back to its level when the buffer was initialized, 6793 1.1 mbalmer plus the final string on its top. 6794 1.1 mbalmer 6795 1.1 mbalmer 6796 1.1 mbalmer 6797 1.1 mbalmer 6798 1.1 mbalmer 6799 1.9 nikita <hr><h3><a name="luaL_buffaddr"><code>luaL_buffaddr</code></a></h3><p> 6800 1.9 nikita <span class="apii">[-0, +0, –]</span> 6801 1.9 nikita <pre>char *luaL_buffaddr (luaL_Buffer *B);</pre> 6802 1.9 nikita 6803 1.9 nikita <p> 6804 1.9 nikita Returns the address of the current content of buffer <code>B</code> 6805 1.9 nikita (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6806 1.9 nikita Note that any addition to the buffer may invalidate this address. 6807 1.9 nikita 6808 1.9 nikita 6809 1.9 nikita 6810 1.9 nikita 6811 1.9 nikita 6812 1.1 mbalmer <hr><h3><a name="luaL_buffinit"><code>luaL_buffinit</code></a></h3><p> 6813 1.9 nikita <span class="apii">[-0, +?, –]</span> 6814 1.1 mbalmer <pre>void luaL_buffinit (lua_State *L, luaL_Buffer *B);</pre> 6815 1.1 mbalmer 6816 1.1 mbalmer <p> 6817 1.9 nikita Initializes a buffer <code>B</code> 6818 1.9 nikita (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6819 1.1 mbalmer This function does not allocate any space; 6820 1.9 nikita the buffer must be declared as a variable. 6821 1.9 nikita 6822 1.9 nikita 6823 1.9 nikita 6824 1.9 nikita 6825 1.9 nikita 6826 1.9 nikita <hr><h3><a name="luaL_bufflen"><code>luaL_bufflen</code></a></h3><p> 6827 1.9 nikita <span class="apii">[-0, +0, –]</span> 6828 1.9 nikita <pre>size_t luaL_bufflen (luaL_Buffer *B);</pre> 6829 1.9 nikita 6830 1.9 nikita <p> 6831 1.9 nikita Returns the length of the current content of buffer <code>B</code> 6832 1.1 mbalmer (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6833 1.1 mbalmer 6834 1.1 mbalmer 6835 1.1 mbalmer 6836 1.1 mbalmer 6837 1.1 mbalmer 6838 1.2 lneto <hr><h3><a name="luaL_buffinitsize"><code>luaL_buffinitsize</code></a></h3><p> 6839 1.5 lneto <span class="apii">[-?, +?, <em>m</em>]</span> 6840 1.2 lneto <pre>char *luaL_buffinitsize (lua_State *L, luaL_Buffer *B, size_t sz);</pre> 6841 1.2 lneto 6842 1.2 lneto <p> 6843 1.2 lneto Equivalent to the sequence 6844 1.2 lneto <a href="#luaL_buffinit"><code>luaL_buffinit</code></a>, <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a>. 6845 1.2 lneto 6846 1.2 lneto 6847 1.2 lneto 6848 1.2 lneto 6849 1.2 lneto 6850 1.9 nikita <hr><h3><a name="luaL_buffsub"><code>luaL_buffsub</code></a></h3><p> 6851 1.9 nikita <span class="apii">[-?, +?, –]</span> 6852 1.9 nikita <pre>void luaL_buffsub (luaL_Buffer *B, int n);</pre> 6853 1.9 nikita 6854 1.9 nikita <p> 6855 1.10 nikita Removes <code>n</code> bytes from the buffer <code>B</code> 6856 1.9 nikita (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6857 1.9 nikita The buffer must have at least that many bytes. 6858 1.9 nikita 6859 1.9 nikita 6860 1.9 nikita 6861 1.9 nikita 6862 1.9 nikita 6863 1.1 mbalmer <hr><h3><a name="luaL_callmeta"><code>luaL_callmeta</code></a></h3><p> 6864 1.1 mbalmer <span class="apii">[-0, +(0|1), <em>e</em>]</span> 6865 1.1 mbalmer <pre>int luaL_callmeta (lua_State *L, int obj, const char *e);</pre> 6866 1.1 mbalmer 6867 1.1 mbalmer <p> 6868 1.1 mbalmer Calls a metamethod. 6869 1.1 mbalmer 6870 1.1 mbalmer 6871 1.1 mbalmer <p> 6872 1.1 mbalmer If the object at index <code>obj</code> has a metatable and this 6873 1.1 mbalmer metatable has a field <code>e</code>, 6874 1.2 lneto this function calls this field passing the object as its only argument. 6875 1.2 lneto In this case this function returns true and pushes onto the 6876 1.1 mbalmer stack the value returned by the call. 6877 1.1 mbalmer If there is no metatable or no metamethod, 6878 1.9 nikita this function returns false without pushing any value on the stack. 6879 1.1 mbalmer 6880 1.1 mbalmer 6881 1.1 mbalmer 6882 1.1 mbalmer 6883 1.1 mbalmer 6884 1.1 mbalmer <hr><h3><a name="luaL_checkany"><code>luaL_checkany</code></a></h3><p> 6885 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 6886 1.2 lneto <pre>void luaL_checkany (lua_State *L, int arg);</pre> 6887 1.1 mbalmer 6888 1.1 mbalmer <p> 6889 1.1 mbalmer Checks whether the function has an argument 6890 1.2 lneto of any type (including <b>nil</b>) at position <code>arg</code>. 6891 1.1 mbalmer 6892 1.1 mbalmer 6893 1.1 mbalmer 6894 1.1 mbalmer 6895 1.1 mbalmer 6896 1.1 mbalmer <hr><h3><a name="luaL_checkinteger"><code>luaL_checkinteger</code></a></h3><p> 6897 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 6898 1.2 lneto <pre>lua_Integer luaL_checkinteger (lua_State *L, int arg);</pre> 6899 1.1 mbalmer 6900 1.1 mbalmer <p> 6901 1.2 lneto Checks whether the function argument <code>arg</code> is an integer 6902 1.2 lneto (or can be converted to an integer) 6903 1.9 nikita and returns this integer. 6904 1.1 mbalmer 6905 1.1 mbalmer 6906 1.1 mbalmer 6907 1.1 mbalmer 6908 1.1 mbalmer 6909 1.1 mbalmer <hr><h3><a name="luaL_checklstring"><code>luaL_checklstring</code></a></h3><p> 6910 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 6911 1.2 lneto <pre>const char *luaL_checklstring (lua_State *L, int arg, size_t *l);</pre> 6912 1.1 mbalmer 6913 1.1 mbalmer <p> 6914 1.2 lneto Checks whether the function argument <code>arg</code> is a string 6915 1.1 mbalmer and returns this string; 6916 1.9 nikita if <code>l</code> is not <code>NULL</code> fills its referent 6917 1.1 mbalmer with the string's length. 6918 1.1 mbalmer 6919 1.1 mbalmer 6920 1.1 mbalmer <p> 6921 1.1 mbalmer This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, 6922 1.1 mbalmer so all conversions and caveats of that function apply here. 6923 1.1 mbalmer 6924 1.1 mbalmer 6925 1.1 mbalmer 6926 1.1 mbalmer 6927 1.1 mbalmer 6928 1.1 mbalmer <hr><h3><a name="luaL_checknumber"><code>luaL_checknumber</code></a></h3><p> 6929 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 6930 1.2 lneto <pre>lua_Number luaL_checknumber (lua_State *L, int arg);</pre> 6931 1.1 mbalmer 6932 1.1 mbalmer <p> 6933 1.2 lneto Checks whether the function argument <code>arg</code> is a number 6934 1.9 nikita and returns this number converted to a <code>lua_Number</code>. 6935 1.1 mbalmer 6936 1.1 mbalmer 6937 1.1 mbalmer 6938 1.1 mbalmer 6939 1.1 mbalmer 6940 1.1 mbalmer <hr><h3><a name="luaL_checkoption"><code>luaL_checkoption</code></a></h3><p> 6941 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 6942 1.1 mbalmer <pre>int luaL_checkoption (lua_State *L, 6943 1.2 lneto int arg, 6944 1.1 mbalmer const char *def, 6945 1.1 mbalmer const char *const lst[]);</pre> 6946 1.1 mbalmer 6947 1.1 mbalmer <p> 6948 1.2 lneto Checks whether the function argument <code>arg</code> is a string and 6949 1.1 mbalmer searches for this string in the array <code>lst</code> 6950 1.1 mbalmer (which must be NULL-terminated). 6951 1.1 mbalmer Returns the index in the array where the string was found. 6952 1.1 mbalmer Raises an error if the argument is not a string or 6953 1.1 mbalmer if the string cannot be found. 6954 1.1 mbalmer 6955 1.1 mbalmer 6956 1.1 mbalmer <p> 6957 1.1 mbalmer If <code>def</code> is not <code>NULL</code>, 6958 1.1 mbalmer the function uses <code>def</code> as a default value when 6959 1.2 lneto there is no argument <code>arg</code> or when this argument is <b>nil</b>. 6960 1.1 mbalmer 6961 1.1 mbalmer 6962 1.1 mbalmer <p> 6963 1.1 mbalmer This is a useful function for mapping strings to C enums. 6964 1.1 mbalmer (The usual convention in Lua libraries is 6965 1.1 mbalmer to use strings instead of numbers to select options.) 6966 1.1 mbalmer 6967 1.1 mbalmer 6968 1.1 mbalmer 6969 1.1 mbalmer 6970 1.1 mbalmer 6971 1.1 mbalmer <hr><h3><a name="luaL_checkstack"><code>luaL_checkstack</code></a></h3><p> 6972 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 6973 1.1 mbalmer <pre>void luaL_checkstack (lua_State *L, int sz, const char *msg);</pre> 6974 1.1 mbalmer 6975 1.1 mbalmer <p> 6976 1.1 mbalmer Grows the stack size to <code>top + sz</code> elements, 6977 1.1 mbalmer raising an error if the stack cannot grow to that size. 6978 1.2 lneto <code>msg</code> is an additional text to go into the error message 6979 1.2 lneto (or <code>NULL</code> for no additional text). 6980 1.1 mbalmer 6981 1.1 mbalmer 6982 1.1 mbalmer 6983 1.1 mbalmer 6984 1.1 mbalmer 6985 1.1 mbalmer <hr><h3><a name="luaL_checkstring"><code>luaL_checkstring</code></a></h3><p> 6986 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 6987 1.2 lneto <pre>const char *luaL_checkstring (lua_State *L, int arg);</pre> 6988 1.1 mbalmer 6989 1.1 mbalmer <p> 6990 1.2 lneto Checks whether the function argument <code>arg</code> is a string 6991 1.1 mbalmer and returns this string. 6992 1.1 mbalmer 6993 1.1 mbalmer 6994 1.1 mbalmer <p> 6995 1.1 mbalmer This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, 6996 1.1 mbalmer so all conversions and caveats of that function apply here. 6997 1.1 mbalmer 6998 1.1 mbalmer 6999 1.1 mbalmer 7000 1.1 mbalmer 7001 1.1 mbalmer 7002 1.1 mbalmer <hr><h3><a name="luaL_checktype"><code>luaL_checktype</code></a></h3><p> 7003 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 7004 1.2 lneto <pre>void luaL_checktype (lua_State *L, int arg, int t);</pre> 7005 1.1 mbalmer 7006 1.1 mbalmer <p> 7007 1.2 lneto Checks whether the function argument <code>arg</code> has type <code>t</code>. 7008 1.1 mbalmer See <a href="#lua_type"><code>lua_type</code></a> for the encoding of types for <code>t</code>. 7009 1.1 mbalmer 7010 1.1 mbalmer 7011 1.1 mbalmer 7012 1.1 mbalmer 7013 1.1 mbalmer 7014 1.1 mbalmer <hr><h3><a name="luaL_checkudata"><code>luaL_checkudata</code></a></h3><p> 7015 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 7016 1.2 lneto <pre>void *luaL_checkudata (lua_State *L, int arg, const char *tname);</pre> 7017 1.2 lneto 7018 1.2 lneto <p> 7019 1.2 lneto Checks whether the function argument <code>arg</code> is a userdata 7020 1.2 lneto of the type <code>tname</code> (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>) and 7021 1.9 nikita returns the userdata's memory-block address (see <a href="#lua_touserdata"><code>lua_touserdata</code></a>). 7022 1.2 lneto 7023 1.2 lneto 7024 1.2 lneto 7025 1.2 lneto 7026 1.2 lneto 7027 1.2 lneto <hr><h3><a name="luaL_checkversion"><code>luaL_checkversion</code></a></h3><p> 7028 1.6 salazar <span class="apii">[-0, +0, <em>v</em>]</span> 7029 1.2 lneto <pre>void luaL_checkversion (lua_State *L);</pre> 7030 1.1 mbalmer 7031 1.1 mbalmer <p> 7032 1.9 nikita Checks whether the code making the call and the Lua library being called 7033 1.9 nikita are using the same version of Lua and the same numeric types. 7034 1.1 mbalmer 7035 1.1 mbalmer 7036 1.1 mbalmer 7037 1.1 mbalmer 7038 1.1 mbalmer 7039 1.1 mbalmer <hr><h3><a name="luaL_dofile"><code>luaL_dofile</code></a></h3><p> 7040 1.9 nikita <span class="apii">[-0, +?, <em>m</em>]</span> 7041 1.1 mbalmer <pre>int luaL_dofile (lua_State *L, const char *filename);</pre> 7042 1.1 mbalmer 7043 1.1 mbalmer <p> 7044 1.1 mbalmer Loads and runs the given file. 7045 1.1 mbalmer It is defined as the following macro: 7046 1.1 mbalmer 7047 1.1 mbalmer <pre> 7048 1.1 mbalmer (luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0)) 7049 1.1 mbalmer </pre><p> 7050 1.10 nikita It returns 0 (<a href="#pdf-LUA_OK"><code>LUA_OK</code></a>) if there are no errors, 7051 1.10 nikita or 1 in case of errors. 7052 1.1 mbalmer 7053 1.1 mbalmer 7054 1.1 mbalmer 7055 1.1 mbalmer 7056 1.1 mbalmer 7057 1.1 mbalmer <hr><h3><a name="luaL_dostring"><code>luaL_dostring</code></a></h3><p> 7058 1.2 lneto <span class="apii">[-0, +?, –]</span> 7059 1.1 mbalmer <pre>int luaL_dostring (lua_State *L, const char *str);</pre> 7060 1.1 mbalmer 7061 1.1 mbalmer <p> 7062 1.1 mbalmer Loads and runs the given string. 7063 1.1 mbalmer It is defined as the following macro: 7064 1.1 mbalmer 7065 1.1 mbalmer <pre> 7066 1.1 mbalmer (luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0)) 7067 1.1 mbalmer </pre><p> 7068 1.10 nikita It returns 0 (<a href="#pdf-LUA_OK"><code>LUA_OK</code></a>) if there are no errors, 7069 1.10 nikita or 1 in case of errors. 7070 1.1 mbalmer 7071 1.1 mbalmer 7072 1.1 mbalmer 7073 1.1 mbalmer 7074 1.1 mbalmer 7075 1.1 mbalmer <hr><h3><a name="luaL_error"><code>luaL_error</code></a></h3><p> 7076 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 7077 1.1 mbalmer <pre>int luaL_error (lua_State *L, const char *fmt, ...);</pre> 7078 1.1 mbalmer 7079 1.1 mbalmer <p> 7080 1.1 mbalmer Raises an error. 7081 1.2 lneto The error message format is given by <code>fmt</code> 7082 1.2 lneto plus any extra arguments, 7083 1.2 lneto following the same rules of <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>. 7084 1.2 lneto It also adds at the beginning of the message the file name and 7085 1.2 lneto the line number where the error occurred, 7086 1.2 lneto if this information is available. 7087 1.2 lneto 7088 1.2 lneto 7089 1.2 lneto <p> 7090 1.2 lneto This function never returns, 7091 1.2 lneto but it is an idiom to use it in C functions 7092 1.2 lneto as <code>return luaL_error(<em>args</em>)</code>. 7093 1.2 lneto 7094 1.2 lneto 7095 1.2 lneto 7096 1.2 lneto 7097 1.2 lneto 7098 1.2 lneto <hr><h3><a name="luaL_execresult"><code>luaL_execresult</code></a></h3><p> 7099 1.5 lneto <span class="apii">[-0, +3, <em>m</em>]</span> 7100 1.2 lneto <pre>int luaL_execresult (lua_State *L, int stat);</pre> 7101 1.2 lneto 7102 1.2 lneto <p> 7103 1.2 lneto This function produces the return values for 7104 1.2 lneto process-related functions in the standard library 7105 1.2 lneto (<a href="#pdf-os.execute"><code>os.execute</code></a> and <a href="#pdf-io.close"><code>io.close</code></a>). 7106 1.2 lneto 7107 1.2 lneto 7108 1.2 lneto 7109 1.2 lneto 7110 1.1 mbalmer 7111 1.2 lneto <hr><h3><a name="luaL_fileresult"><code>luaL_fileresult</code></a></h3><p> 7112 1.5 lneto <span class="apii">[-0, +(1|3), <em>m</em>]</span> 7113 1.2 lneto <pre>int luaL_fileresult (lua_State *L, int stat, const char *fname);</pre> 7114 1.1 mbalmer 7115 1.1 mbalmer <p> 7116 1.2 lneto This function produces the return values for 7117 1.2 lneto file-related functions in the standard library 7118 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.). 7119 1.1 mbalmer 7120 1.1 mbalmer 7121 1.1 mbalmer 7122 1.1 mbalmer 7123 1.1 mbalmer 7124 1.1 mbalmer <hr><h3><a name="luaL_getmetafield"><code>luaL_getmetafield</code></a></h3><p> 7125 1.5 lneto <span class="apii">[-0, +(0|1), <em>m</em>]</span> 7126 1.1 mbalmer <pre>int luaL_getmetafield (lua_State *L, int obj, const char *e);</pre> 7127 1.1 mbalmer 7128 1.1 mbalmer <p> 7129 1.1 mbalmer Pushes onto the stack the field <code>e</code> from the metatable 7130 1.8 alnsn of the object at index <code>obj</code> and returns the type of the pushed value. 7131 1.1 mbalmer If the object does not have a metatable, 7132 1.1 mbalmer or if the metatable does not have this field, 7133 1.3 lneto pushes nothing and returns <code>LUA_TNIL</code>. 7134 1.1 mbalmer 7135 1.1 mbalmer 7136 1.1 mbalmer 7137 1.1 mbalmer 7138 1.1 mbalmer 7139 1.1 mbalmer <hr><h3><a name="luaL_getmetatable"><code>luaL_getmetatable</code></a></h3><p> 7140 1.5 lneto <span class="apii">[-0, +1, <em>m</em>]</span> 7141 1.3 lneto <pre>int luaL_getmetatable (lua_State *L, const char *tname);</pre> 7142 1.1 mbalmer 7143 1.1 mbalmer <p> 7144 1.9 nikita Pushes onto the stack the metatable associated with the name <code>tname</code> 7145 1.9 nikita in the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>), 7146 1.9 nikita or <b>nil</b> if there is no metatable associated with that name. 7147 1.4 mbalmer Returns the type of the pushed value. 7148 1.1 mbalmer 7149 1.1 mbalmer 7150 1.1 mbalmer 7151 1.1 mbalmer 7152 1.1 mbalmer 7153 1.2 lneto <hr><h3><a name="luaL_getsubtable"><code>luaL_getsubtable</code></a></h3><p> 7154 1.2 lneto <span class="apii">[-0, +1, <em>e</em>]</span> 7155 1.2 lneto <pre>int luaL_getsubtable (lua_State *L, int idx, const char *fname);</pre> 7156 1.2 lneto 7157 1.2 lneto <p> 7158 1.2 lneto Ensures that the value <code>t[fname]</code>, 7159 1.2 lneto where <code>t</code> is the value at index <code>idx</code>, 7160 1.2 lneto is a table, 7161 1.2 lneto and pushes that table onto the stack. 7162 1.2 lneto Returns true if it finds a previous table there 7163 1.2 lneto and false if it creates a new table. 7164 1.2 lneto 7165 1.2 lneto 7166 1.2 lneto 7167 1.2 lneto 7168 1.2 lneto 7169 1.1 mbalmer <hr><h3><a name="luaL_gsub"><code>luaL_gsub</code></a></h3><p> 7170 1.5 lneto <span class="apii">[-0, +1, <em>m</em>]</span> 7171 1.1 mbalmer <pre>const char *luaL_gsub (lua_State *L, 7172 1.1 mbalmer const char *s, 7173 1.1 mbalmer const char *p, 7174 1.1 mbalmer const char *r);</pre> 7175 1.1 mbalmer 7176 1.1 mbalmer <p> 7177 1.9 nikita Creates a copy of string <code>s</code>, 7178 1.9 nikita replacing any occurrence of the string <code>p</code> 7179 1.1 mbalmer with the string <code>r</code>. 7180 1.1 mbalmer Pushes the resulting string on the stack and returns it. 7181 1.1 mbalmer 7182 1.1 mbalmer 7183 1.1 mbalmer 7184 1.1 mbalmer 7185 1.1 mbalmer 7186 1.2 lneto <hr><h3><a name="luaL_len"><code>luaL_len</code></a></h3><p> 7187 1.2 lneto <span class="apii">[-0, +0, <em>e</em>]</span> 7188 1.2 lneto <pre>lua_Integer luaL_len (lua_State *L, int index);</pre> 7189 1.2 lneto 7190 1.2 lneto <p> 7191 1.2 lneto Returns the "length" of the value at the given index 7192 1.2 lneto as a number; 7193 1.2 lneto it is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">§3.4.7</a>). 7194 1.2 lneto Raises an error if the result of the operation is not an integer. 7195 1.9 nikita (This case can only happen through metamethods.) 7196 1.2 lneto 7197 1.2 lneto 7198 1.2 lneto 7199 1.2 lneto 7200 1.2 lneto 7201 1.1 mbalmer <hr><h3><a name="luaL_loadbuffer"><code>luaL_loadbuffer</code></a></h3><p> 7202 1.2 lneto <span class="apii">[-0, +1, –]</span> 7203 1.1 mbalmer <pre>int luaL_loadbuffer (lua_State *L, 7204 1.1 mbalmer const char *buff, 7205 1.1 mbalmer size_t sz, 7206 1.1 mbalmer const char *name);</pre> 7207 1.1 mbalmer 7208 1.1 mbalmer <p> 7209 1.2 lneto Equivalent to <a href="#luaL_loadbufferx"><code>luaL_loadbufferx</code></a> with <code>mode</code> equal to <code>NULL</code>. 7210 1.2 lneto 7211 1.2 lneto 7212 1.2 lneto 7213 1.2 lneto 7214 1.2 lneto 7215 1.2 lneto <hr><h3><a name="luaL_loadbufferx"><code>luaL_loadbufferx</code></a></h3><p> 7216 1.2 lneto <span class="apii">[-0, +1, –]</span> 7217 1.2 lneto <pre>int luaL_loadbufferx (lua_State *L, 7218 1.2 lneto const char *buff, 7219 1.2 lneto size_t sz, 7220 1.2 lneto const char *name, 7221 1.2 lneto const char *mode);</pre> 7222 1.2 lneto 7223 1.2 lneto <p> 7224 1.1 mbalmer Loads a buffer as a Lua chunk. 7225 1.1 mbalmer This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the 7226 1.1 mbalmer buffer pointed to by <code>buff</code> with size <code>sz</code>. 7227 1.1 mbalmer 7228 1.1 mbalmer 7229 1.1 mbalmer <p> 7230 1.1 mbalmer This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>. 7231 1.1 mbalmer <code>name</code> is the chunk name, 7232 1.1 mbalmer used for debug information and error messages. 7233 1.9 nikita The string <code>mode</code> works as in the function <a href="#lua_load"><code>lua_load</code></a>. 7234 1.1 mbalmer 7235 1.1 mbalmer 7236 1.1 mbalmer 7237 1.1 mbalmer 7238 1.1 mbalmer 7239 1.1 mbalmer <hr><h3><a name="luaL_loadfile"><code>luaL_loadfile</code></a></h3><p> 7240 1.6 salazar <span class="apii">[-0, +1, <em>m</em>]</span> 7241 1.1 mbalmer <pre>int luaL_loadfile (lua_State *L, const char *filename);</pre> 7242 1.1 mbalmer 7243 1.1 mbalmer <p> 7244 1.2 lneto Equivalent to <a href="#luaL_loadfilex"><code>luaL_loadfilex</code></a> with <code>mode</code> equal to <code>NULL</code>. 7245 1.2 lneto 7246 1.2 lneto 7247 1.2 lneto 7248 1.2 lneto 7249 1.2 lneto 7250 1.2 lneto <hr><h3><a name="luaL_loadfilex"><code>luaL_loadfilex</code></a></h3><p> 7251 1.6 salazar <span class="apii">[-0, +1, <em>m</em>]</span> 7252 1.2 lneto <pre>int luaL_loadfilex (lua_State *L, const char *filename, 7253 1.2 lneto const char *mode);</pre> 7254 1.2 lneto 7255 1.2 lneto <p> 7256 1.1 mbalmer Loads a file as a Lua chunk. 7257 1.1 mbalmer This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the file 7258 1.1 mbalmer named <code>filename</code>. 7259 1.1 mbalmer If <code>filename</code> is <code>NULL</code>, 7260 1.1 mbalmer then it loads from the standard input. 7261 1.1 mbalmer The first line in the file is ignored if it starts with a <code>#</code>. 7262 1.1 mbalmer 7263 1.1 mbalmer 7264 1.1 mbalmer <p> 7265 1.9 nikita The string <code>mode</code> works as in the function <a href="#lua_load"><code>lua_load</code></a>. 7266 1.2 lneto 7267 1.2 lneto 7268 1.2 lneto <p> 7269 1.9 nikita This function returns the same results as <a href="#lua_load"><code>lua_load</code></a> 7270 1.9 nikita or <a href="#pdf-LUA_ERRFILE"><code>LUA_ERRFILE</code></a> for file-related errors. 7271 1.1 mbalmer 7272 1.1 mbalmer 7273 1.1 mbalmer <p> 7274 1.1 mbalmer As <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk; 7275 1.1 mbalmer it does not run it. 7276 1.1 mbalmer 7277 1.1 mbalmer 7278 1.1 mbalmer 7279 1.1 mbalmer 7280 1.1 mbalmer 7281 1.1 mbalmer <hr><h3><a name="luaL_loadstring"><code>luaL_loadstring</code></a></h3><p> 7282 1.2 lneto <span class="apii">[-0, +1, –]</span> 7283 1.1 mbalmer <pre>int luaL_loadstring (lua_State *L, const char *s);</pre> 7284 1.1 mbalmer 7285 1.1 mbalmer <p> 7286 1.1 mbalmer Loads a string as a Lua chunk. 7287 1.1 mbalmer This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in 7288 1.1 mbalmer the zero-terminated string <code>s</code>. 7289 1.1 mbalmer 7290 1.1 mbalmer 7291 1.1 mbalmer <p> 7292 1.1 mbalmer This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>. 7293 1.1 mbalmer 7294 1.1 mbalmer 7295 1.1 mbalmer <p> 7296 1.1 mbalmer Also as <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk; 7297 1.1 mbalmer it does not run it. 7298 1.1 mbalmer 7299 1.1 mbalmer 7300 1.1 mbalmer 7301 1.1 mbalmer 7302 1.1 mbalmer 7303 1.2 lneto <hr><h3><a name="luaL_newlib"><code>luaL_newlib</code></a></h3><p> 7304 1.5 lneto <span class="apii">[-0, +1, <em>m</em>]</span> 7305 1.3 lneto <pre>void luaL_newlib (lua_State *L, const luaL_Reg l[]);</pre> 7306 1.2 lneto 7307 1.2 lneto <p> 7308 1.2 lneto Creates a new table and registers there 7309 1.9 nikita the functions in the list <code>l</code>. 7310 1.3 lneto 7311 1.3 lneto 7312 1.3 lneto <p> 7313 1.2 lneto It is implemented as the following macro: 7314 1.2 lneto 7315 1.2 lneto <pre> 7316 1.2 lneto (luaL_newlibtable(L,l), luaL_setfuncs(L,l,0)) 7317 1.3 lneto </pre><p> 7318 1.3 lneto The array <code>l</code> must be the actual array, 7319 1.3 lneto not a pointer to it. 7320 1.3 lneto 7321 1.2 lneto 7322 1.2 lneto 7323 1.2 lneto 7324 1.2 lneto 7325 1.2 lneto <hr><h3><a name="luaL_newlibtable"><code>luaL_newlibtable</code></a></h3><p> 7326 1.5 lneto <span class="apii">[-0, +1, <em>m</em>]</span> 7327 1.2 lneto <pre>void luaL_newlibtable (lua_State *L, const luaL_Reg l[]);</pre> 7328 1.2 lneto 7329 1.2 lneto <p> 7330 1.2 lneto Creates a new table with a size optimized 7331 1.2 lneto to store all entries in the array <code>l</code> 7332 1.2 lneto (but does not actually store them). 7333 1.2 lneto It is intended to be used in conjunction with <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a> 7334 1.2 lneto (see <a href="#luaL_newlib"><code>luaL_newlib</code></a>). 7335 1.2 lneto 7336 1.2 lneto 7337 1.2 lneto <p> 7338 1.2 lneto It is implemented as a macro. 7339 1.2 lneto The array <code>l</code> must be the actual array, 7340 1.2 lneto not a pointer to it. 7341 1.2 lneto 7342 1.2 lneto 7343 1.2 lneto 7344 1.2 lneto 7345 1.2 lneto 7346 1.1 mbalmer <hr><h3><a name="luaL_newmetatable"><code>luaL_newmetatable</code></a></h3><p> 7347 1.5 lneto <span class="apii">[-0, +1, <em>m</em>]</span> 7348 1.1 mbalmer <pre>int luaL_newmetatable (lua_State *L, const char *tname);</pre> 7349 1.1 mbalmer 7350 1.1 mbalmer <p> 7351 1.1 mbalmer If the registry already has the key <code>tname</code>, 7352 1.1 mbalmer returns 0. 7353 1.1 mbalmer Otherwise, 7354 1.1 mbalmer creates a new table to be used as a metatable for userdata, 7355 1.2 lneto adds to this new table the pair <code>__name = tname</code>, 7356 1.2 lneto adds to the registry the pair <code>[tname] = new table</code>, 7357 1.1 mbalmer and returns 1. 7358 1.1 mbalmer 7359 1.1 mbalmer 7360 1.1 mbalmer <p> 7361 1.9 nikita In both cases, 7362 1.9 nikita the function pushes onto the stack the final value associated 7363 1.1 mbalmer with <code>tname</code> in the registry. 7364 1.1 mbalmer 7365 1.1 mbalmer 7366 1.1 mbalmer 7367 1.1 mbalmer 7368 1.1 mbalmer 7369 1.1 mbalmer <hr><h3><a name="luaL_newstate"><code>luaL_newstate</code></a></h3><p> 7370 1.2 lneto <span class="apii">[-0, +0, –]</span> 7371 1.1 mbalmer <pre>lua_State *luaL_newstate (void);</pre> 7372 1.1 mbalmer 7373 1.1 mbalmer <p> 7374 1.1 mbalmer Creates a new Lua state. 7375 1.1 mbalmer It calls <a href="#lua_newstate"><code>lua_newstate</code></a> with an 7376 1.10 nikita allocator based on the ISO C allocation functions 7377 1.9 nikita and then sets a warning function and a panic function (see <a href="#4.4">§4.4</a>) 7378 1.9 nikita that print messages to the standard error output. 7379 1.1 mbalmer 7380 1.1 mbalmer 7381 1.1 mbalmer <p> 7382 1.1 mbalmer Returns the new state, 7383 1.1 mbalmer or <code>NULL</code> if there is a memory allocation error. 7384 1.1 mbalmer 7385 1.1 mbalmer 7386 1.1 mbalmer 7387 1.1 mbalmer 7388 1.1 mbalmer 7389 1.1 mbalmer <hr><h3><a name="luaL_openlibs"><code>luaL_openlibs</code></a></h3><p> 7390 1.2 lneto <span class="apii">[-0, +0, <em>e</em>]</span> 7391 1.1 mbalmer <pre>void luaL_openlibs (lua_State *L);</pre> 7392 1.1 mbalmer 7393 1.1 mbalmer <p> 7394 1.1 mbalmer Opens all standard Lua libraries into the given state. 7395 1.1 mbalmer 7396 1.1 mbalmer 7397 1.1 mbalmer 7398 1.1 mbalmer 7399 1.1 mbalmer 7400 1.6 salazar <hr><h3><a name="luaL_opt"><code>luaL_opt</code></a></h3><p> 7401 1.9 nikita <span class="apii">[-0, +0, –]</span> 7402 1.6 salazar <pre>T luaL_opt (L, func, arg, dflt);</pre> 7403 1.6 salazar 7404 1.6 salazar <p> 7405 1.6 salazar This macro is defined as follows: 7406 1.6 salazar 7407 1.6 salazar <pre> 7408 1.6 salazar (lua_isnoneornil(L,(arg)) ? (dflt) : func(L,(arg))) 7409 1.6 salazar </pre><p> 7410 1.6 salazar In words, if the argument <code>arg</code> is nil or absent, 7411 1.6 salazar the macro results in the default <code>dflt</code>. 7412 1.6 salazar Otherwise, it results in the result of calling <code>func</code> 7413 1.6 salazar with the state <code>L</code> and the argument index <code>arg</code> as 7414 1.8 alnsn arguments. 7415 1.6 salazar Note that it evaluates the expression <code>dflt</code> only if needed. 7416 1.6 salazar 7417 1.6 salazar 7418 1.6 salazar 7419 1.6 salazar 7420 1.6 salazar 7421 1.1 mbalmer <hr><h3><a name="luaL_optinteger"><code>luaL_optinteger</code></a></h3><p> 7422 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 7423 1.1 mbalmer <pre>lua_Integer luaL_optinteger (lua_State *L, 7424 1.2 lneto int arg, 7425 1.1 mbalmer lua_Integer d);</pre> 7426 1.1 mbalmer 7427 1.1 mbalmer <p> 7428 1.2 lneto If the function argument <code>arg</code> is an integer 7429 1.9 nikita (or it is convertible to an integer), 7430 1.2 lneto returns this integer. 7431 1.1 mbalmer If this argument is absent or is <b>nil</b>, 7432 1.1 mbalmer returns <code>d</code>. 7433 1.1 mbalmer Otherwise, raises an error. 7434 1.1 mbalmer 7435 1.1 mbalmer 7436 1.1 mbalmer 7437 1.1 mbalmer 7438 1.1 mbalmer 7439 1.1 mbalmer <hr><h3><a name="luaL_optlstring"><code>luaL_optlstring</code></a></h3><p> 7440 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 7441 1.1 mbalmer <pre>const char *luaL_optlstring (lua_State *L, 7442 1.2 lneto int arg, 7443 1.1 mbalmer const char *d, 7444 1.1 mbalmer size_t *l);</pre> 7445 1.1 mbalmer 7446 1.1 mbalmer <p> 7447 1.2 lneto If the function argument <code>arg</code> is a string, 7448 1.1 mbalmer returns this string. 7449 1.1 mbalmer If this argument is absent or is <b>nil</b>, 7450 1.1 mbalmer returns <code>d</code>. 7451 1.1 mbalmer Otherwise, raises an error. 7452 1.1 mbalmer 7453 1.1 mbalmer 7454 1.1 mbalmer <p> 7455 1.1 mbalmer If <code>l</code> is not <code>NULL</code>, 7456 1.9 nikita fills its referent with the result's length. 7457 1.5 lneto If the result is <code>NULL</code> 7458 1.5 lneto (only possible when returning <code>d</code> and <code>d == NULL</code>), 7459 1.5 lneto its length is considered zero. 7460 1.1 mbalmer 7461 1.1 mbalmer 7462 1.7 mbalmer <p> 7463 1.7 mbalmer This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, 7464 1.7 mbalmer so all conversions and caveats of that function apply here. 7465 1.7 mbalmer 7466 1.7 mbalmer 7467 1.1 mbalmer 7468 1.1 mbalmer 7469 1.1 mbalmer 7470 1.1 mbalmer <hr><h3><a name="luaL_optnumber"><code>luaL_optnumber</code></a></h3><p> 7471 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 7472 1.2 lneto <pre>lua_Number luaL_optnumber (lua_State *L, int arg, lua_Number d);</pre> 7473 1.1 mbalmer 7474 1.1 mbalmer <p> 7475 1.2 lneto If the function argument <code>arg</code> is a number, 7476 1.9 nikita returns this number as a <code>lua_Number</code>. 7477 1.1 mbalmer If this argument is absent or is <b>nil</b>, 7478 1.1 mbalmer returns <code>d</code>. 7479 1.1 mbalmer Otherwise, raises an error. 7480 1.1 mbalmer 7481 1.1 mbalmer 7482 1.1 mbalmer 7483 1.1 mbalmer 7484 1.1 mbalmer 7485 1.1 mbalmer <hr><h3><a name="luaL_optstring"><code>luaL_optstring</code></a></h3><p> 7486 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 7487 1.1 mbalmer <pre>const char *luaL_optstring (lua_State *L, 7488 1.2 lneto int arg, 7489 1.1 mbalmer const char *d);</pre> 7490 1.1 mbalmer 7491 1.1 mbalmer <p> 7492 1.2 lneto If the function argument <code>arg</code> is a string, 7493 1.1 mbalmer returns this string. 7494 1.1 mbalmer If this argument is absent or is <b>nil</b>, 7495 1.1 mbalmer returns <code>d</code>. 7496 1.1 mbalmer Otherwise, raises an error. 7497 1.1 mbalmer 7498 1.1 mbalmer 7499 1.1 mbalmer 7500 1.1 mbalmer 7501 1.1 mbalmer 7502 1.1 mbalmer <hr><h3><a name="luaL_prepbuffer"><code>luaL_prepbuffer</code></a></h3><p> 7503 1.5 lneto <span class="apii">[-?, +?, <em>m</em>]</span> 7504 1.1 mbalmer <pre>char *luaL_prepbuffer (luaL_Buffer *B);</pre> 7505 1.1 mbalmer 7506 1.1 mbalmer <p> 7507 1.2 lneto Equivalent to <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a> 7508 1.2 lneto with the predefined size <a name="pdf-LUAL_BUFFERSIZE"><code>LUAL_BUFFERSIZE</code></a>. 7509 1.2 lneto 7510 1.2 lneto 7511 1.2 lneto 7512 1.2 lneto 7513 1.2 lneto 7514 1.2 lneto <hr><h3><a name="luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a></h3><p> 7515 1.5 lneto <span class="apii">[-?, +?, <em>m</em>]</span> 7516 1.2 lneto <pre>char *luaL_prepbuffsize (luaL_Buffer *B, size_t sz);</pre> 7517 1.2 lneto 7518 1.2 lneto <p> 7519 1.2 lneto Returns an address to a space of size <code>sz</code> 7520 1.1 mbalmer where you can copy a string to be added to buffer <code>B</code> 7521 1.1 mbalmer (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 7522 1.1 mbalmer After copying the string into this space you must call 7523 1.2 lneto <a href="#luaL_addsize"><code>luaL_addsize</code></a> with the size of the string to actually add 7524 1.1 mbalmer it to the buffer. 7525 1.1 mbalmer 7526 1.1 mbalmer 7527 1.1 mbalmer 7528 1.1 mbalmer 7529 1.1 mbalmer 7530 1.9 nikita <hr><h3><a name="luaL_pushfail"><code>luaL_pushfail</code></a></h3><p> 7531 1.9 nikita <span class="apii">[-0, +1, –]</span> 7532 1.9 nikita <pre>void luaL_pushfail (lua_State *L);</pre> 7533 1.9 nikita 7534 1.9 nikita <p> 7535 1.9 nikita Pushes the <b>fail</b> value onto the stack (see <a href="#6">§6</a>). 7536 1.9 nikita 7537 1.9 nikita 7538 1.9 nikita 7539 1.9 nikita 7540 1.9 nikita 7541 1.1 mbalmer <hr><h3><a name="luaL_pushresult"><code>luaL_pushresult</code></a></h3><p> 7542 1.5 lneto <span class="apii">[-?, +1, <em>m</em>]</span> 7543 1.1 mbalmer <pre>void luaL_pushresult (luaL_Buffer *B);</pre> 7544 1.1 mbalmer 7545 1.1 mbalmer <p> 7546 1.1 mbalmer Finishes the use of buffer <code>B</code> leaving the final string on 7547 1.1 mbalmer the top of the stack. 7548 1.1 mbalmer 7549 1.1 mbalmer 7550 1.1 mbalmer 7551 1.1 mbalmer 7552 1.1 mbalmer 7553 1.2 lneto <hr><h3><a name="luaL_pushresultsize"><code>luaL_pushresultsize</code></a></h3><p> 7554 1.5 lneto <span class="apii">[-?, +1, <em>m</em>]</span> 7555 1.2 lneto <pre>void luaL_pushresultsize (luaL_Buffer *B, size_t sz);</pre> 7556 1.2 lneto 7557 1.2 lneto <p> 7558 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>. 7559 1.2 lneto 7560 1.2 lneto 7561 1.2 lneto 7562 1.2 lneto 7563 1.2 lneto 7564 1.1 mbalmer <hr><h3><a name="luaL_ref"><code>luaL_ref</code></a></h3><p> 7565 1.5 lneto <span class="apii">[-1, +0, <em>m</em>]</span> 7566 1.1 mbalmer <pre>int luaL_ref (lua_State *L, int t);</pre> 7567 1.1 mbalmer 7568 1.1 mbalmer <p> 7569 1.1 mbalmer Creates and returns a <em>reference</em>, 7570 1.1 mbalmer in the table at index <code>t</code>, 7571 1.9 nikita for the object on the top of the stack (and pops the object). 7572 1.1 mbalmer 7573 1.1 mbalmer 7574 1.1 mbalmer <p> 7575 1.1 mbalmer A reference is a unique integer key. 7576 1.9 nikita As long as you do not manually add integer keys into the table <code>t</code>, 7577 1.1 mbalmer <a href="#luaL_ref"><code>luaL_ref</code></a> ensures the uniqueness of the key it returns. 7578 1.9 nikita You can retrieve an object referred by the reference <code>r</code> 7579 1.1 mbalmer by calling <code>lua_rawgeti(L, t, r)</code>. 7580 1.9 nikita The function <a href="#luaL_unref"><code>luaL_unref</code></a> frees a reference. 7581 1.1 mbalmer 7582 1.1 mbalmer 7583 1.1 mbalmer <p> 7584 1.9 nikita If the object on the top of the stack is <b>nil</b>, 7585 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>. 7586 1.1 mbalmer The constant <a name="pdf-LUA_NOREF"><code>LUA_NOREF</code></a> is guaranteed to be different 7587 1.1 mbalmer from any reference returned by <a href="#luaL_ref"><code>luaL_ref</code></a>. 7588 1.1 mbalmer 7589 1.1 mbalmer 7590 1.1 mbalmer 7591 1.1 mbalmer 7592 1.1 mbalmer 7593 1.1 mbalmer <hr><h3><a name="luaL_Reg"><code>luaL_Reg</code></a></h3> 7594 1.1 mbalmer <pre>typedef struct luaL_Reg { 7595 1.1 mbalmer const char *name; 7596 1.1 mbalmer lua_CFunction func; 7597 1.1 mbalmer } luaL_Reg;</pre> 7598 1.1 mbalmer 7599 1.1 mbalmer <p> 7600 1.1 mbalmer Type for arrays of functions to be registered by 7601 1.2 lneto <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a>. 7602 1.1 mbalmer <code>name</code> is the function name and <code>func</code> is a pointer to 7603 1.1 mbalmer the function. 7604 1.3 lneto Any array of <a href="#luaL_Reg"><code>luaL_Reg</code></a> must end with a sentinel entry 7605 1.1 mbalmer in which both <code>name</code> and <code>func</code> are <code>NULL</code>. 7606 1.1 mbalmer 7607 1.1 mbalmer 7608 1.1 mbalmer 7609 1.1 mbalmer 7610 1.1 mbalmer 7611 1.2 lneto <hr><h3><a name="luaL_requiref"><code>luaL_requiref</code></a></h3><p> 7612 1.2 lneto <span class="apii">[-0, +1, <em>e</em>]</span> 7613 1.2 lneto <pre>void luaL_requiref (lua_State *L, const char *modname, 7614 1.2 lneto lua_CFunction openf, int glb);</pre> 7615 1.2 lneto 7616 1.2 lneto <p> 7617 1.9 nikita If <code>package.loaded[modname]</code> is not true, 7618 1.9 nikita calls the function <code>openf</code> with the string <code>modname</code> as an argument 7619 1.9 nikita and sets the call result to <code>package.loaded[modname]</code>, 7620 1.2 lneto as if that function has been called through <a href="#pdf-require"><code>require</code></a>. 7621 1.2 lneto 7622 1.2 lneto 7623 1.2 lneto <p> 7624 1.2 lneto If <code>glb</code> is true, 7625 1.9 nikita also stores the module into the global <code>modname</code>. 7626 1.2 lneto 7627 1.2 lneto 7628 1.2 lneto <p> 7629 1.3 lneto Leaves a copy of the module on the stack. 7630 1.2 lneto 7631 1.2 lneto 7632 1.2 lneto 7633 1.2 lneto 7634 1.2 lneto 7635 1.2 lneto <hr><h3><a name="luaL_setfuncs"><code>luaL_setfuncs</code></a></h3><p> 7636 1.5 lneto <span class="apii">[-nup, +0, <em>m</em>]</span> 7637 1.2 lneto <pre>void luaL_setfuncs (lua_State *L, const luaL_Reg *l, int nup);</pre> 7638 1.2 lneto 7639 1.2 lneto <p> 7640 1.2 lneto Registers all functions in the array <code>l</code> 7641 1.2 lneto (see <a href="#luaL_Reg"><code>luaL_Reg</code></a>) into the table on the top of the stack 7642 1.2 lneto (below optional upvalues, see next). 7643 1.2 lneto 7644 1.1 mbalmer 7645 1.1 mbalmer <p> 7646 1.2 lneto When <code>nup</code> is not zero, 7647 1.9 nikita all functions are created with <code>nup</code> upvalues, 7648 1.9 nikita initialized with copies of the <code>nup</code> values 7649 1.9 nikita previously pushed on the stack 7650 1.2 lneto on top of the library table. 7651 1.2 lneto These values are popped from the stack after the registration. 7652 1.1 mbalmer 7653 1.1 mbalmer 7654 1.9 nikita <p> 7655 1.9 nikita A function with a <code>NULL</code> value represents a placeholder, 7656 1.9 nikita which is filled with <b>false</b>. 7657 1.9 nikita 7658 1.9 nikita 7659 1.2 lneto 7660 1.2 lneto 7661 1.2 lneto 7662 1.2 lneto <hr><h3><a name="luaL_setmetatable"><code>luaL_setmetatable</code></a></h3><p> 7663 1.2 lneto <span class="apii">[-0, +0, –]</span> 7664 1.2 lneto <pre>void luaL_setmetatable (lua_State *L, const char *tname);</pre> 7665 1.2 lneto 7666 1.2 lneto <p> 7667 1.9 nikita Sets the metatable of the object on the top of the stack 7668 1.2 lneto as the metatable associated with name <code>tname</code> 7669 1.2 lneto in the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). 7670 1.2 lneto 7671 1.2 lneto 7672 1.2 lneto 7673 1.2 lneto 7674 1.2 lneto 7675 1.2 lneto <hr><h3><a name="luaL_Stream"><code>luaL_Stream</code></a></h3> 7676 1.2 lneto <pre>typedef struct luaL_Stream { 7677 1.2 lneto FILE *f; 7678 1.2 lneto lua_CFunction closef; 7679 1.2 lneto } luaL_Stream;</pre> 7680 1.2 lneto 7681 1.1 mbalmer <p> 7682 1.9 nikita The standard representation for file handles 7683 1.9 nikita used by the standard I/O library. 7684 1.1 mbalmer 7685 1.1 mbalmer 7686 1.1 mbalmer <p> 7687 1.2 lneto A file handle is implemented as a full userdata, 7688 1.3 lneto with a metatable called <code>LUA_FILEHANDLE</code> 7689 1.3 lneto (where <code>LUA_FILEHANDLE</code> is a macro with the actual metatable's name). 7690 1.2 lneto The metatable is created by the I/O library 7691 1.2 lneto (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). 7692 1.2 lneto 7693 1.2 lneto 7694 1.2 lneto <p> 7695 1.2 lneto This userdata must start with the structure <code>luaL_Stream</code>; 7696 1.2 lneto it can contain other data after this initial structure. 7697 1.9 nikita The field <code>f</code> points to the corresponding C stream 7698 1.2 lneto (or it can be <code>NULL</code> to indicate an incompletely created handle). 7699 1.9 nikita The field <code>closef</code> points to a Lua function 7700 1.2 lneto that will be called to close the stream 7701 1.2 lneto when the handle is closed or collected; 7702 1.2 lneto this function receives the file handle as its sole argument and 7703 1.9 nikita must return either a true value, in case of success, 7704 1.9 nikita or a false value plus an error message, in case of error. 7705 1.2 lneto Once Lua calls this field, 7706 1.5 lneto it changes the field value to <code>NULL</code> 7707 1.3 lneto to signal that the handle is closed. 7708 1.2 lneto 7709 1.1 mbalmer 7710 1.1 mbalmer 7711 1.2 lneto 7712 1.2 lneto 7713 1.2 lneto <hr><h3><a name="luaL_testudata"><code>luaL_testudata</code></a></h3><p> 7714 1.5 lneto <span class="apii">[-0, +0, <em>m</em>]</span> 7715 1.2 lneto <pre>void *luaL_testudata (lua_State *L, int arg, const char *tname);</pre> 7716 1.2 lneto 7717 1.1 mbalmer <p> 7718 1.2 lneto This function works like <a href="#luaL_checkudata"><code>luaL_checkudata</code></a>, 7719 1.2 lneto except that, when the test fails, 7720 1.2 lneto it returns <code>NULL</code> instead of raising an error. 7721 1.1 mbalmer 7722 1.1 mbalmer 7723 1.1 mbalmer 7724 1.1 mbalmer 7725 1.1 mbalmer 7726 1.2 lneto <hr><h3><a name="luaL_tolstring"><code>luaL_tolstring</code></a></h3><p> 7727 1.2 lneto <span class="apii">[-0, +1, <em>e</em>]</span> 7728 1.2 lneto <pre>const char *luaL_tolstring (lua_State *L, int idx, size_t *len);</pre> 7729 1.2 lneto 7730 1.2 lneto <p> 7731 1.2 lneto Converts any Lua value at the given index to a C string 7732 1.2 lneto in a reasonable format. 7733 1.2 lneto The resulting string is pushed onto the stack and also 7734 1.9 nikita returned by the function (see <a href="#4.1.3">§4.1.3</a>). 7735 1.2 lneto If <code>len</code> is not <code>NULL</code>, 7736 1.2 lneto the function also sets <code>*len</code> with the string length. 7737 1.2 lneto 7738 1.1 mbalmer 7739 1.1 mbalmer <p> 7740 1.6 salazar If the value has a metatable with a <code>__tostring</code> field, 7741 1.2 lneto then <code>luaL_tolstring</code> calls the corresponding metamethod 7742 1.2 lneto with the value as argument, 7743 1.2 lneto and uses the result of the call as its result. 7744 1.1 mbalmer 7745 1.1 mbalmer 7746 1.1 mbalmer 7747 1.1 mbalmer 7748 1.1 mbalmer 7749 1.2 lneto <hr><h3><a name="luaL_traceback"><code>luaL_traceback</code></a></h3><p> 7750 1.5 lneto <span class="apii">[-0, +1, <em>m</em>]</span> 7751 1.2 lneto <pre>void luaL_traceback (lua_State *L, lua_State *L1, const char *msg, 7752 1.2 lneto int level);</pre> 7753 1.1 mbalmer 7754 1.1 mbalmer <p> 7755 1.2 lneto Creates and pushes a traceback of the stack <code>L1</code>. 7756 1.9 nikita If <code>msg</code> is not <code>NULL</code>, it is appended 7757 1.2 lneto at the beginning of the traceback. 7758 1.2 lneto The <code>level</code> parameter tells at which level 7759 1.2 lneto to start the traceback. 7760 1.1 mbalmer 7761 1.2 lneto 7762 1.2 lneto 7763 1.2 lneto 7764 1.2 lneto 7765 1.9 nikita <hr><h3><a name="luaL_typeerror"><code>luaL_typeerror</code></a></h3><p> 7766 1.9 nikita <span class="apii">[-0, +0, <em>v</em>]</span> 7767 1.10 nikita <pre>int luaL_typeerror (lua_State *L, int arg, const char *tname);</pre> 7768 1.9 nikita 7769 1.9 nikita <p> 7770 1.9 nikita Raises a type error for the argument <code>arg</code> 7771 1.9 nikita of the C function that called it, 7772 1.9 nikita using a standard message; 7773 1.9 nikita <code>tname</code> is a "name" for the expected type. 7774 1.9 nikita This function never returns. 7775 1.9 nikita 7776 1.9 nikita 7777 1.9 nikita 7778 1.9 nikita 7779 1.9 nikita 7780 1.2 lneto <hr><h3><a name="luaL_typename"><code>luaL_typename</code></a></h3><p> 7781 1.2 lneto <span class="apii">[-0, +0, –]</span> 7782 1.2 lneto <pre>const char *luaL_typename (lua_State *L, int index);</pre> 7783 1.2 lneto 7784 1.2 lneto <p> 7785 1.2 lneto Returns the name of the type of the value at the given index. 7786 1.1 mbalmer 7787 1.1 mbalmer 7788 1.1 mbalmer 7789 1.1 mbalmer 7790 1.1 mbalmer 7791 1.1 mbalmer <hr><h3><a name="luaL_unref"><code>luaL_unref</code></a></h3><p> 7792 1.2 lneto <span class="apii">[-0, +0, –]</span> 7793 1.1 mbalmer <pre>void luaL_unref (lua_State *L, int t, int ref);</pre> 7794 1.1 mbalmer 7795 1.1 mbalmer <p> 7796 1.9 nikita Releases the reference <code>ref</code> from the table at index <code>t</code> 7797 1.1 mbalmer (see <a href="#luaL_ref"><code>luaL_ref</code></a>). 7798 1.1 mbalmer The entry is removed from the table, 7799 1.1 mbalmer so that the referred object can be collected. 7800 1.1 mbalmer The reference <code>ref</code> is also freed to be used again. 7801 1.1 mbalmer 7802 1.1 mbalmer 7803 1.1 mbalmer <p> 7804 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>, 7805 1.1 mbalmer <a href="#luaL_unref"><code>luaL_unref</code></a> does nothing. 7806 1.1 mbalmer 7807 1.1 mbalmer 7808 1.1 mbalmer 7809 1.1 mbalmer 7810 1.1 mbalmer 7811 1.1 mbalmer <hr><h3><a name="luaL_where"><code>luaL_where</code></a></h3><p> 7812 1.5 lneto <span class="apii">[-0, +1, <em>m</em>]</span> 7813 1.1 mbalmer <pre>void luaL_where (lua_State *L, int lvl);</pre> 7814 1.1 mbalmer 7815 1.1 mbalmer <p> 7816 1.1 mbalmer Pushes onto the stack a string identifying the current position 7817 1.1 mbalmer of the control at level <code>lvl</code> in the call stack. 7818 1.1 mbalmer Typically this string has the following format: 7819 1.1 mbalmer 7820 1.1 mbalmer <pre> 7821 1.1 mbalmer <em>chunkname</em>:<em>currentline</em>: 7822 1.1 mbalmer </pre><p> 7823 1.1 mbalmer Level 0 is the running function, 7824 1.1 mbalmer level 1 is the function that called the running function, 7825 1.1 mbalmer etc. 7826 1.1 mbalmer 7827 1.1 mbalmer 7828 1.1 mbalmer <p> 7829 1.1 mbalmer This function is used to build a prefix for error messages. 7830 1.1 mbalmer 7831 1.1 mbalmer 7832 1.1 mbalmer 7833 1.1 mbalmer 7834 1.1 mbalmer 7835 1.1 mbalmer 7836 1.1 mbalmer 7837 1.9 nikita <h1>6 – <a name="6">The Standard Libraries</a></h1> 7838 1.9 nikita 7839 1.9 nikita 7840 1.1 mbalmer 7841 1.1 mbalmer <p> 7842 1.1 mbalmer The standard Lua libraries provide useful functions 7843 1.9 nikita that are implemented in C through the C API. 7844 1.1 mbalmer Some of these functions provide essential services to the language 7845 1.1 mbalmer (e.g., <a href="#pdf-type"><code>type</code></a> and <a href="#pdf-getmetatable"><code>getmetatable</code></a>); 7846 1.9 nikita others provide access to outside services (e.g., I/O); 7847 1.1 mbalmer and others could be implemented in Lua itself, 7848 1.9 nikita but that for different reasons 7849 1.1 mbalmer deserve an implementation in C (e.g., <a href="#pdf-table.sort"><code>table.sort</code></a>). 7850 1.1 mbalmer 7851 1.1 mbalmer 7852 1.1 mbalmer <p> 7853 1.1 mbalmer All libraries are implemented through the official C API 7854 1.1 mbalmer and are provided as separate C modules. 7855 1.9 nikita Unless otherwise noted, 7856 1.9 nikita these library functions do not adjust its number of arguments 7857 1.9 nikita to its expected parameters. 7858 1.9 nikita For instance, a function documented as <code>foo(arg)</code> 7859 1.9 nikita should not be called without an argument. 7860 1.9 nikita 7861 1.9 nikita 7862 1.9 nikita <p> 7863 1.9 nikita The notation <b>fail</b> means a false value representing 7864 1.9 nikita some kind of failure. 7865 1.9 nikita (Currently, <b>fail</b> is equal to <b>nil</b>, 7866 1.9 nikita but that may change in future versions. 7867 1.9 nikita The recommendation is to always test the success of these functions 7868 1.9 nikita with <code>(not status)</code>, instead of <code>(status == nil)</code>.) 7869 1.9 nikita 7870 1.9 nikita 7871 1.9 nikita <p> 7872 1.1 mbalmer Currently, Lua has the following standard libraries: 7873 1.1 mbalmer 7874 1.1 mbalmer <ul> 7875 1.1 mbalmer 7876 1.2 lneto <li>basic library (<a href="#6.1">§6.1</a>);</li> 7877 1.1 mbalmer 7878 1.2 lneto <li>coroutine library (<a href="#6.2">§6.2</a>);</li> 7879 1.1 mbalmer 7880 1.2 lneto <li>package library (<a href="#6.3">§6.3</a>);</li> 7881 1.1 mbalmer 7882 1.2 lneto <li>string manipulation (<a href="#6.4">§6.4</a>);</li> 7883 1.1 mbalmer 7884 1.2 lneto <li>basic UTF-8 support (<a href="#6.5">§6.5</a>);</li> 7885 1.1 mbalmer 7886 1.2 lneto <li>table manipulation (<a href="#6.6">§6.6</a>);</li> 7887 1.1 mbalmer 7888 1.2 lneto <li>mathematical functions (<a href="#6.7">§6.7</a>) (sin, log, etc.);</li> 7889 1.1 mbalmer 7890 1.2 lneto <li>input and output (<a href="#6.8">§6.8</a>);</li> 7891 1.2 lneto 7892 1.2 lneto <li>operating system facilities (<a href="#6.9">§6.9</a>);</li> 7893 1.2 lneto 7894 1.2 lneto <li>debug facilities (<a href="#6.10">§6.10</a>).</li> 7895 1.1 mbalmer 7896 1.1 mbalmer </ul><p> 7897 1.2 lneto Except for the basic and the package libraries, 7898 1.1 mbalmer each library provides all its functions as fields of a global table 7899 1.1 mbalmer or as methods of its objects. 7900 1.1 mbalmer 7901 1.1 mbalmer 7902 1.1 mbalmer <p> 7903 1.1 mbalmer To have access to these libraries, 7904 1.1 mbalmer the C host program should call the <a href="#luaL_openlibs"><code>luaL_openlibs</code></a> function, 7905 1.1 mbalmer which opens all standard libraries. 7906 1.1 mbalmer Alternatively, 7907 1.2 lneto the host program can open them individually by using 7908 1.2 lneto <a href="#luaL_requiref"><code>luaL_requiref</code></a> to call 7909 1.1 mbalmer <a name="pdf-luaopen_base"><code>luaopen_base</code></a> (for the basic library), 7910 1.1 mbalmer <a name="pdf-luaopen_package"><code>luaopen_package</code></a> (for the package library), 7911 1.2 lneto <a name="pdf-luaopen_coroutine"><code>luaopen_coroutine</code></a> (for the coroutine library), 7912 1.1 mbalmer <a name="pdf-luaopen_string"><code>luaopen_string</code></a> (for the string library), 7913 1.9 nikita <a name="pdf-luaopen_utf8"><code>luaopen_utf8</code></a> (for the UTF-8 library), 7914 1.1 mbalmer <a name="pdf-luaopen_table"><code>luaopen_table</code></a> (for the table library), 7915 1.1 mbalmer <a name="pdf-luaopen_math"><code>luaopen_math</code></a> (for the mathematical library), 7916 1.1 mbalmer <a name="pdf-luaopen_io"><code>luaopen_io</code></a> (for the I/O library), 7917 1.3 lneto <a name="pdf-luaopen_os"><code>luaopen_os</code></a> (for the operating system library), 7918 1.1 mbalmer and <a name="pdf-luaopen_debug"><code>luaopen_debug</code></a> (for the debug library). 7919 1.2 lneto These functions are declared in <a name="pdf-lualib.h"><code>lualib.h</code></a>. 7920 1.1 mbalmer 7921 1.1 mbalmer 7922 1.1 mbalmer 7923 1.9 nikita 7924 1.9 nikita 7925 1.2 lneto <h2>6.1 – <a name="6.1">Basic Functions</a></h2> 7926 1.1 mbalmer 7927 1.1 mbalmer <p> 7928 1.2 lneto The basic library provides core functions to Lua. 7929 1.1 mbalmer If you do not include this library in your application, 7930 1.2 lneto you should check carefully whether you need to provide 7931 1.1 mbalmer implementations for some of its facilities. 7932 1.1 mbalmer 7933 1.1 mbalmer 7934 1.1 mbalmer <p> 7935 1.1 mbalmer <hr><h3><a name="pdf-assert"><code>assert (v [, message])</code></a></h3> 7936 1.2 lneto 7937 1.2 lneto 7938 1.2 lneto <p> 7939 1.9 nikita Raises an error if 7940 1.1 mbalmer the value of its argument <code>v</code> is false (i.e., <b>nil</b> or <b>false</b>); 7941 1.1 mbalmer otherwise, returns all its arguments. 7942 1.2 lneto In case of error, 7943 1.2 lneto <code>message</code> is the error object; 7944 1.2 lneto when absent, it defaults to "<code>assertion failed!</code>" 7945 1.1 mbalmer 7946 1.1 mbalmer 7947 1.1 mbalmer 7948 1.1 mbalmer 7949 1.1 mbalmer <p> 7950 1.2 lneto <hr><h3><a name="pdf-collectgarbage"><code>collectgarbage ([opt [, arg]])</code></a></h3> 7951 1.1 mbalmer 7952 1.1 mbalmer 7953 1.1 mbalmer <p> 7954 1.1 mbalmer This function is a generic interface to the garbage collector. 7955 1.1 mbalmer It performs different functions according to its first argument, <code>opt</code>: 7956 1.1 mbalmer 7957 1.1 mbalmer <ul> 7958 1.1 mbalmer 7959 1.2 lneto <li><b>"<code>collect</code>": </b> 7960 1.9 nikita Performs a full garbage-collection cycle. 7961 1.2 lneto This is the default option. 7962 1.1 mbalmer </li> 7963 1.1 mbalmer 7964 1.2 lneto <li><b>"<code>stop</code>": </b> 7965 1.9 nikita Stops automatic execution of the garbage collector. 7966 1.2 lneto The collector will run only when explicitly invoked, 7967 1.2 lneto until a call to restart it. 7968 1.1 mbalmer </li> 7969 1.1 mbalmer 7970 1.2 lneto <li><b>"<code>restart</code>": </b> 7971 1.9 nikita Restarts automatic execution of the garbage collector. 7972 1.1 mbalmer </li> 7973 1.1 mbalmer 7974 1.2 lneto <li><b>"<code>count</code>": </b> 7975 1.9 nikita Returns the total memory in use by Lua in Kbytes. 7976 1.2 lneto The value has a fractional part, 7977 1.2 lneto so that it multiplied by 1024 7978 1.9 nikita gives the exact number of bytes in use by Lua. 7979 1.1 mbalmer </li> 7980 1.1 mbalmer 7981 1.2 lneto <li><b>"<code>step</code>": </b> 7982 1.9 nikita Performs a garbage-collection step. 7983 1.2 lneto The step "size" is controlled by <code>arg</code>. 7984 1.2 lneto With a zero value, 7985 1.2 lneto the collector will perform one basic (indivisible) step. 7986 1.2 lneto For non-zero values, 7987 1.2 lneto the collector will perform as if that amount of memory 7988 1.9 nikita (in Kbytes) had been allocated by Lua. 7989 1.1 mbalmer Returns <b>true</b> if the step finished a collection cycle. 7990 1.1 mbalmer </li> 7991 1.1 mbalmer 7992 1.9 nikita <li><b>"<code>isrunning</code>": </b> 7993 1.9 nikita Returns a boolean that tells whether the collector is running 7994 1.9 nikita (i.e., not stopped). 7995 1.1 mbalmer </li> 7996 1.1 mbalmer 7997 1.9 nikita <li><b>"<code>incremental</code>": </b> 7998 1.9 nikita Change the collector mode to incremental. 7999 1.9 nikita This option can be followed by three numbers: 8000 1.9 nikita the garbage-collector pause, 8001 1.9 nikita the step multiplier, 8002 1.9 nikita and the step size (see <a href="#2.5.1">§2.5.1</a>). 8003 1.9 nikita A zero means to not change that value. 8004 1.1 mbalmer </li> 8005 1.1 mbalmer 8006 1.9 nikita <li><b>"<code>generational</code>": </b> 8007 1.9 nikita Change the collector mode to generational. 8008 1.9 nikita This option can be followed by two numbers: 8009 1.9 nikita the garbage-collector minor multiplier 8010 1.9 nikita and the major multiplier (see <a href="#2.5.2">§2.5.2</a>). 8011 1.9 nikita A zero means to not change that value. 8012 1.2 lneto </li> 8013 1.2 lneto 8014 1.9 nikita </ul><p> 8015 1.9 nikita See <a href="#2.5">§2.5</a> for more details about garbage collection 8016 1.9 nikita and some of these options. 8017 1.9 nikita 8018 1.9 nikita 8019 1.9 nikita <p> 8020 1.9 nikita This function should not be called by a finalizer. 8021 1.9 nikita 8022 1.1 mbalmer 8023 1.1 mbalmer 8024 1.1 mbalmer 8025 1.1 mbalmer <p> 8026 1.2 lneto <hr><h3><a name="pdf-dofile"><code>dofile ([filename])</code></a></h3> 8027 1.9 nikita Opens the named file and executes its content as a Lua chunk. 8028 1.1 mbalmer When called without arguments, 8029 1.9 nikita <code>dofile</code> executes the content of the standard input (<code>stdin</code>). 8030 1.1 mbalmer Returns all values returned by the chunk. 8031 1.1 mbalmer In case of errors, <code>dofile</code> propagates the error 8032 1.9 nikita to its caller. 8033 1.9 nikita (That is, <code>dofile</code> does not run in protected mode.) 8034 1.1 mbalmer 8035 1.1 mbalmer 8036 1.1 mbalmer 8037 1.1 mbalmer 8038 1.1 mbalmer <p> 8039 1.1 mbalmer <hr><h3><a name="pdf-error"><code>error (message [, level])</code></a></h3> 8040 1.9 nikita Raises an error (see <a href="#2.3">§2.3</a>) with <code>message</code> as the error object. 8041 1.9 nikita This function never returns. 8042 1.1 mbalmer 8043 1.1 mbalmer 8044 1.1 mbalmer <p> 8045 1.1 mbalmer Usually, <code>error</code> adds some information about the error position 8046 1.2 lneto at the beginning of the message, if the message is a string. 8047 1.1 mbalmer The <code>level</code> argument specifies how to get the error position. 8048 1.1 mbalmer With level 1 (the default), the error position is where the 8049 1.1 mbalmer <code>error</code> function was called. 8050 1.1 mbalmer Level 2 points the error to where the function 8051 1.1 mbalmer that called <code>error</code> was called; and so on. 8052 1.1 mbalmer Passing a level 0 avoids the addition of error position information 8053 1.1 mbalmer to the message. 8054 1.1 mbalmer 8055 1.1 mbalmer 8056 1.1 mbalmer 8057 1.1 mbalmer 8058 1.1 mbalmer <p> 8059 1.1 mbalmer <hr><h3><a name="pdf-_G"><code>_G</code></a></h3> 8060 1.1 mbalmer A global variable (not a function) that 8061 1.2 lneto holds the global environment (see <a href="#2.2">§2.2</a>). 8062 1.1 mbalmer Lua itself does not use this variable; 8063 1.1 mbalmer changing its value does not affect any environment, 8064 1.2 lneto nor vice versa. 8065 1.1 mbalmer 8066 1.1 mbalmer 8067 1.1 mbalmer 8068 1.1 mbalmer 8069 1.1 mbalmer <p> 8070 1.1 mbalmer <hr><h3><a name="pdf-getmetatable"><code>getmetatable (object)</code></a></h3> 8071 1.1 mbalmer 8072 1.1 mbalmer 8073 1.1 mbalmer <p> 8074 1.1 mbalmer If <code>object</code> does not have a metatable, returns <b>nil</b>. 8075 1.1 mbalmer Otherwise, 8076 1.6 salazar if the object's metatable has a <code>__metatable</code> field, 8077 1.1 mbalmer returns the associated value. 8078 1.1 mbalmer Otherwise, returns the metatable of the given object. 8079 1.1 mbalmer 8080 1.1 mbalmer 8081 1.1 mbalmer 8082 1.1 mbalmer 8083 1.1 mbalmer <p> 8084 1.1 mbalmer <hr><h3><a name="pdf-ipairs"><code>ipairs (t)</code></a></h3> 8085 1.1 mbalmer 8086 1.1 mbalmer 8087 1.1 mbalmer <p> 8088 1.3 lneto Returns three values (an iterator function, the table <code>t</code>, and 0) 8089 1.1 mbalmer so that the construction 8090 1.1 mbalmer 8091 1.1 mbalmer <pre> 8092 1.1 mbalmer for i,v in ipairs(t) do <em>body</em> end 8093 1.1 mbalmer </pre><p> 8094 1.3 lneto will iterate over the key–value pairs 8095 1.3 lneto (<code>1,t[1]</code>), (<code>2,t[2]</code>), ..., 8096 1.9 nikita up to the first absent index. 8097 1.1 mbalmer 8098 1.1 mbalmer 8099 1.1 mbalmer 8100 1.1 mbalmer 8101 1.1 mbalmer <p> 8102 1.3 lneto <hr><h3><a name="pdf-load"><code>load (chunk [, chunkname [, mode [, env]]])</code></a></h3> 8103 1.1 mbalmer 8104 1.1 mbalmer 8105 1.1 mbalmer <p> 8106 1.2 lneto Loads a chunk. 8107 1.2 lneto 8108 1.2 lneto 8109 1.2 lneto <p> 8110 1.3 lneto If <code>chunk</code> is a string, the chunk is this string. 8111 1.3 lneto If <code>chunk</code> is a function, 8112 1.2 lneto <code>load</code> calls it repeatedly to get the chunk pieces. 8113 1.3 lneto Each call to <code>chunk</code> must return a string that concatenates 8114 1.1 mbalmer with previous results. 8115 1.1 mbalmer A return of an empty string, <b>nil</b>, or no value signals the end of the chunk. 8116 1.1 mbalmer 8117 1.1 mbalmer 8118 1.1 mbalmer <p> 8119 1.2 lneto If there are no syntactic errors, 8120 1.9 nikita <code>load</code> returns the compiled chunk as a function; 8121 1.9 nikita otherwise, it returns <b>fail</b> plus the error message. 8122 1.1 mbalmer 8123 1.1 mbalmer 8124 1.1 mbalmer <p> 8125 1.9 nikita When you load a main chunk, 8126 1.2 lneto the resulting function will always have exactly one upvalue, 8127 1.2 lneto the <code>_ENV</code> variable (see <a href="#2.2">§2.2</a>). 8128 1.3 lneto However, 8129 1.3 lneto when you load a binary chunk created from a function (see <a href="#pdf-string.dump"><code>string.dump</code></a>), 8130 1.9 nikita the resulting function can have an arbitrary number of upvalues, 8131 1.9 nikita and there is no guarantee that its first upvalue will be 8132 1.9 nikita the <code>_ENV</code> variable. 8133 1.9 nikita (A non-main function may not even have an <code>_ENV</code> upvalue.) 8134 1.9 nikita 8135 1.9 nikita 8136 1.9 nikita <p> 8137 1.9 nikita Regardless, if the resulting function has any upvalues, 8138 1.9 nikita its first upvalue is set to the value of <code>env</code>, 8139 1.9 nikita if that parameter is given, 8140 1.9 nikita or to the value of the global environment. 8141 1.9 nikita Other upvalues are initialized with <b>nil</b>. 8142 1.3 lneto All upvalues are fresh, that is, 8143 1.3 lneto they are not shared with any other function. 8144 1.1 mbalmer 8145 1.1 mbalmer 8146 1.2 lneto <p> 8147 1.3 lneto <code>chunkname</code> is used as the name of the chunk for error messages 8148 1.9 nikita and debug information (see <a href="#4.7">§4.7</a>). 8149 1.2 lneto When absent, 8150 1.3 lneto it defaults to <code>chunk</code>, if <code>chunk</code> is a string, 8151 1.2 lneto or to "<code>=(load)</code>" otherwise. 8152 1.1 mbalmer 8153 1.1 mbalmer 8154 1.1 mbalmer <p> 8155 1.2 lneto The string <code>mode</code> controls whether the chunk can be text or binary 8156 1.2 lneto (that is, a precompiled chunk). 8157 1.2 lneto It may be the string "<code>b</code>" (only binary chunks), 8158 1.2 lneto "<code>t</code>" (only text chunks), 8159 1.2 lneto or "<code>bt</code>" (both binary and text). 8160 1.2 lneto The default is "<code>bt</code>". 8161 1.1 mbalmer 8162 1.1 mbalmer 8163 1.1 mbalmer <p> 8164 1.9 nikita It is safe to load malformed binary chunks; 8165 1.9 nikita <code>load</code> signals an appropriate error. 8166 1.9 nikita However, 8167 1.9 nikita Lua does not check the consistency of the code inside binary chunks; 8168 1.9 nikita running maliciously crafted bytecode can crash the interpreter. 8169 1.1 mbalmer 8170 1.1 mbalmer 8171 1.1 mbalmer 8172 1.1 mbalmer 8173 1.1 mbalmer <p> 8174 1.2 lneto <hr><h3><a name="pdf-loadfile"><code>loadfile ([filename [, mode [, env]]])</code></a></h3> 8175 1.1 mbalmer 8176 1.1 mbalmer 8177 1.1 mbalmer <p> 8178 1.1 mbalmer Similar to <a href="#pdf-load"><code>load</code></a>, 8179 1.2 lneto but gets the chunk from file <code>filename</code> 8180 1.2 lneto or from the standard input, 8181 1.2 lneto if no file name is given. 8182 1.1 mbalmer 8183 1.1 mbalmer 8184 1.1 mbalmer 8185 1.1 mbalmer 8186 1.1 mbalmer <p> 8187 1.1 mbalmer <hr><h3><a name="pdf-next"><code>next (table [, index])</code></a></h3> 8188 1.1 mbalmer 8189 1.1 mbalmer 8190 1.1 mbalmer <p> 8191 1.1 mbalmer Allows a program to traverse all fields of a table. 8192 1.1 mbalmer Its first argument is a table and its second argument 8193 1.1 mbalmer is an index in this table. 8194 1.9 nikita A call to <code>next</code> returns the next index of the table 8195 1.1 mbalmer and its associated value. 8196 1.1 mbalmer When called with <b>nil</b> as its second argument, 8197 1.1 mbalmer <code>next</code> returns an initial index 8198 1.1 mbalmer and its associated value. 8199 1.1 mbalmer When called with the last index, 8200 1.1 mbalmer or with <b>nil</b> in an empty table, 8201 1.1 mbalmer <code>next</code> returns <b>nil</b>. 8202 1.1 mbalmer If the second argument is absent, then it is interpreted as <b>nil</b>. 8203 1.1 mbalmer In particular, 8204 1.1 mbalmer you can use <code>next(t)</code> to check whether a table is empty. 8205 1.1 mbalmer 8206 1.1 mbalmer 8207 1.1 mbalmer <p> 8208 1.1 mbalmer The order in which the indices are enumerated is not specified, 8209 1.1 mbalmer <em>even for numeric indices</em>. 8210 1.4 mbalmer (To traverse a table in numerical order, 8211 1.2 lneto use a numerical <b>for</b>.) 8212 1.1 mbalmer 8213 1.1 mbalmer 8214 1.1 mbalmer <p> 8215 1.9 nikita You should not assign any value to a non-existent field in a table 8216 1.9 nikita during its traversal. 8217 1.1 mbalmer You may however modify existing fields. 8218 1.9 nikita In particular, you may set existing fields to nil. 8219 1.1 mbalmer 8220 1.1 mbalmer 8221 1.1 mbalmer 8222 1.1 mbalmer 8223 1.1 mbalmer <p> 8224 1.1 mbalmer <hr><h3><a name="pdf-pairs"><code>pairs (t)</code></a></h3> 8225 1.1 mbalmer 8226 1.1 mbalmer 8227 1.1 mbalmer <p> 8228 1.2 lneto If <code>t</code> has a metamethod <code>__pairs</code>, 8229 1.2 lneto calls it with <code>t</code> as argument and returns the first three 8230 1.2 lneto results from the call. 8231 1.2 lneto 8232 1.2 lneto 8233 1.2 lneto <p> 8234 1.2 lneto Otherwise, 8235 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>, 8236 1.1 mbalmer so that the construction 8237 1.1 mbalmer 8238 1.1 mbalmer <pre> 8239 1.1 mbalmer for k,v in pairs(t) do <em>body</em> end 8240 1.1 mbalmer </pre><p> 8241 1.1 mbalmer will iterate over all key–value pairs of table <code>t</code>. 8242 1.1 mbalmer 8243 1.1 mbalmer 8244 1.1 mbalmer <p> 8245 1.1 mbalmer See function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying 8246 1.1 mbalmer the table during its traversal. 8247 1.1 mbalmer 8248 1.1 mbalmer 8249 1.1 mbalmer 8250 1.1 mbalmer 8251 1.1 mbalmer <p> 8252 1.2 lneto <hr><h3><a name="pdf-pcall"><code>pcall (f [, arg1, ···])</code></a></h3> 8253 1.1 mbalmer 8254 1.1 mbalmer 8255 1.1 mbalmer <p> 8256 1.9 nikita Calls the function <code>f</code> with 8257 1.1 mbalmer the given arguments in <em>protected mode</em>. 8258 1.1 mbalmer This means that any error inside <code>f</code> is not propagated; 8259 1.1 mbalmer instead, <code>pcall</code> catches the error 8260 1.1 mbalmer and returns a status code. 8261 1.1 mbalmer Its first result is the status code (a boolean), 8262 1.9 nikita which is <b>true</b> if the call succeeds without errors. 8263 1.1 mbalmer In such case, <code>pcall</code> also returns all results from the call, 8264 1.1 mbalmer after this first result. 8265 1.9 nikita In case of any error, <code>pcall</code> returns <b>false</b> plus the error object. 8266 1.9 nikita Note that errors caught by <code>pcall</code> do not call a message handler. 8267 1.1 mbalmer 8268 1.1 mbalmer 8269 1.1 mbalmer 8270 1.1 mbalmer 8271 1.1 mbalmer <p> 8272 1.1 mbalmer <hr><h3><a name="pdf-print"><code>print (···)</code></a></h3> 8273 1.2 lneto Receives any number of arguments 8274 1.1 mbalmer and prints their values to <code>stdout</code>, 8275 1.9 nikita converting each argument to a string 8276 1.9 nikita following the same rules of <a href="#pdf-tostring"><code>tostring</code></a>. 8277 1.9 nikita 8278 1.9 nikita 8279 1.9 nikita <p> 8280 1.9 nikita The function <code>print</code> is not intended for formatted output, 8281 1.1 mbalmer but only as a quick way to show a value, 8282 1.2 lneto for instance for debugging. 8283 1.2 lneto For complete control over the output, 8284 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>. 8285 1.1 mbalmer 8286 1.1 mbalmer 8287 1.1 mbalmer 8288 1.1 mbalmer 8289 1.1 mbalmer <p> 8290 1.1 mbalmer <hr><h3><a name="pdf-rawequal"><code>rawequal (v1, v2)</code></a></h3> 8291 1.1 mbalmer Checks whether <code>v1</code> is equal to <code>v2</code>, 8292 1.6 salazar without invoking the <code>__eq</code> metamethod. 8293 1.1 mbalmer Returns a boolean. 8294 1.1 mbalmer 8295 1.1 mbalmer 8296 1.1 mbalmer 8297 1.1 mbalmer 8298 1.1 mbalmer <p> 8299 1.1 mbalmer <hr><h3><a name="pdf-rawget"><code>rawget (table, index)</code></a></h3> 8300 1.1 mbalmer Gets the real value of <code>table[index]</code>, 8301 1.9 nikita without using the <code>__index</code> metavalue. 8302 1.1 mbalmer <code>table</code> must be a table; 8303 1.1 mbalmer <code>index</code> may be any value. 8304 1.1 mbalmer 8305 1.1 mbalmer 8306 1.1 mbalmer 8307 1.1 mbalmer 8308 1.1 mbalmer <p> 8309 1.2 lneto <hr><h3><a name="pdf-rawlen"><code>rawlen (v)</code></a></h3> 8310 1.2 lneto Returns the length of the object <code>v</code>, 8311 1.2 lneto which must be a table or a string, 8312 1.6 salazar without invoking the <code>__len</code> metamethod. 8313 1.2 lneto Returns an integer. 8314 1.2 lneto 8315 1.2 lneto 8316 1.2 lneto 8317 1.2 lneto 8318 1.2 lneto <p> 8319 1.1 mbalmer <hr><h3><a name="pdf-rawset"><code>rawset (table, index, value)</code></a></h3> 8320 1.1 mbalmer Sets the real value of <code>table[index]</code> to <code>value</code>, 8321 1.9 nikita without using the <code>__newindex</code> metavalue. 8322 1.1 mbalmer <code>table</code> must be a table, 8323 1.2 lneto <code>index</code> any value different from <b>nil</b> and NaN, 8324 1.1 mbalmer and <code>value</code> any Lua value. 8325 1.1 mbalmer 8326 1.1 mbalmer 8327 1.1 mbalmer <p> 8328 1.1 mbalmer This function returns <code>table</code>. 8329 1.1 mbalmer 8330 1.1 mbalmer 8331 1.1 mbalmer 8332 1.1 mbalmer 8333 1.1 mbalmer <p> 8334 1.1 mbalmer <hr><h3><a name="pdf-select"><code>select (index, ···)</code></a></h3> 8335 1.1 mbalmer 8336 1.1 mbalmer 8337 1.1 mbalmer <p> 8338 1.1 mbalmer If <code>index</code> is a number, 8339 1.2 lneto returns all arguments after argument number <code>index</code>; 8340 1.2 lneto a negative number indexes from the end (-1 is the last argument). 8341 1.1 mbalmer Otherwise, <code>index</code> must be the string <code>"#"</code>, 8342 1.1 mbalmer and <code>select</code> returns the total number of extra arguments it received. 8343 1.1 mbalmer 8344 1.1 mbalmer 8345 1.1 mbalmer 8346 1.1 mbalmer 8347 1.1 mbalmer <p> 8348 1.1 mbalmer <hr><h3><a name="pdf-setmetatable"><code>setmetatable (table, metatable)</code></a></h3> 8349 1.1 mbalmer 8350 1.1 mbalmer 8351 1.1 mbalmer <p> 8352 1.1 mbalmer Sets the metatable for the given table. 8353 1.1 mbalmer If <code>metatable</code> is <b>nil</b>, 8354 1.1 mbalmer removes the metatable of the given table. 8355 1.6 salazar If the original metatable has a <code>__metatable</code> field, 8356 1.1 mbalmer raises an error. 8357 1.1 mbalmer 8358 1.1 mbalmer 8359 1.1 mbalmer <p> 8360 1.1 mbalmer This function returns <code>table</code>. 8361 1.1 mbalmer 8362 1.1 mbalmer 8363 1.9 nikita <p> 8364 1.9 nikita To change the metatable of other types from Lua code, 8365 1.9 nikita you must use the debug library (<a href="#6.10">§6.10</a>). 8366 1.9 nikita 8367 1.9 nikita 8368 1.1 mbalmer 8369 1.1 mbalmer 8370 1.1 mbalmer <p> 8371 1.1 mbalmer <hr><h3><a name="pdf-tonumber"><code>tonumber (e [, base])</code></a></h3> 8372 1.2 lneto 8373 1.2 lneto 8374 1.2 lneto <p> 8375 1.2 lneto When called with no <code>base</code>, 8376 1.2 lneto <code>tonumber</code> tries to convert its argument to a number. 8377 1.2 lneto If the argument is already a number or 8378 1.2 lneto a string convertible to a number, 8379 1.2 lneto then <code>tonumber</code> returns this number; 8380 1.9 nikita otherwise, it returns <b>fail</b>. 8381 1.1 mbalmer 8382 1.1 mbalmer 8383 1.1 mbalmer <p> 8384 1.2 lneto The conversion of strings can result in integers or floats, 8385 1.2 lneto according to the lexical conventions of Lua (see <a href="#3.1">§3.1</a>). 8386 1.9 nikita The string may have leading and trailing spaces and a sign. 8387 1.2 lneto 8388 1.2 lneto 8389 1.2 lneto <p> 8390 1.2 lneto When called with <code>base</code>, 8391 1.2 lneto then <code>e</code> must be a string to be interpreted as 8392 1.2 lneto an integer numeral in that base. 8393 1.1 mbalmer The base may be any integer between 2 and 36, inclusive. 8394 1.1 mbalmer In bases above 10, the letter '<code>A</code>' (in either upper or lower case) 8395 1.1 mbalmer represents 10, '<code>B</code>' represents 11, and so forth, 8396 1.1 mbalmer with '<code>Z</code>' representing 35. 8397 1.2 lneto If the string <code>e</code> is not a valid numeral in the given base, 8398 1.9 nikita the function returns <b>fail</b>. 8399 1.1 mbalmer 8400 1.1 mbalmer 8401 1.1 mbalmer 8402 1.1 mbalmer 8403 1.1 mbalmer <p> 8404 1.2 lneto <hr><h3><a name="pdf-tostring"><code>tostring (v)</code></a></h3> 8405 1.9 nikita 8406 1.9 nikita 8407 1.9 nikita <p> 8408 1.2 lneto Receives a value of any type and 8409 1.2 lneto converts it to a string in a human-readable format. 8410 1.1 mbalmer 8411 1.1 mbalmer 8412 1.1 mbalmer <p> 8413 1.6 salazar If the metatable of <code>v</code> has a <code>__tostring</code> field, 8414 1.1 mbalmer then <code>tostring</code> calls the corresponding value 8415 1.2 lneto with <code>v</code> as argument, 8416 1.1 mbalmer and uses the result of the call as its result. 8417 1.9 nikita Otherwise, if the metatable of <code>v</code> has a <code>__name</code> field 8418 1.9 nikita with a string value, 8419 1.9 nikita <code>tostring</code> may use that string in its final result. 8420 1.9 nikita 8421 1.9 nikita 8422 1.9 nikita <p> 8423 1.9 nikita For complete control of how numbers are converted, 8424 1.9 nikita use <a href="#pdf-string.format"><code>string.format</code></a>. 8425 1.1 mbalmer 8426 1.1 mbalmer 8427 1.1 mbalmer 8428 1.1 mbalmer 8429 1.1 mbalmer <p> 8430 1.1 mbalmer <hr><h3><a name="pdf-type"><code>type (v)</code></a></h3> 8431 1.9 nikita 8432 1.9 nikita 8433 1.9 nikita <p> 8434 1.1 mbalmer Returns the type of its only argument, coded as a string. 8435 1.1 mbalmer The possible results of this function are 8436 1.1 mbalmer "<code>nil</code>" (a string, not the value <b>nil</b>), 8437 1.1 mbalmer "<code>number</code>", 8438 1.1 mbalmer "<code>string</code>", 8439 1.1 mbalmer "<code>boolean</code>", 8440 1.1 mbalmer "<code>table</code>", 8441 1.1 mbalmer "<code>function</code>", 8442 1.1 mbalmer "<code>thread</code>", 8443 1.1 mbalmer and "<code>userdata</code>". 8444 1.1 mbalmer 8445 1.1 mbalmer 8446 1.1 mbalmer 8447 1.1 mbalmer 8448 1.1 mbalmer <p> 8449 1.1 mbalmer <hr><h3><a name="pdf-_VERSION"><code>_VERSION</code></a></h3> 8450 1.5 lneto 8451 1.5 lneto 8452 1.5 lneto <p> 8453 1.1 mbalmer A global variable (not a function) that 8454 1.5 lneto holds a string containing the running Lua version. 8455 1.9 nikita The current value of this variable is "<code>Lua 5.4</code>". 8456 1.9 nikita 8457 1.9 nikita 8458 1.9 nikita 8459 1.9 nikita 8460 1.9 nikita <p> 8461 1.9 nikita <hr><h3><a name="pdf-warn"><code>warn (msg1, ···)</code></a></h3> 8462 1.9 nikita 8463 1.9 nikita 8464 1.9 nikita <p> 8465 1.9 nikita Emits a warning with a message composed by the concatenation 8466 1.9 nikita of all its arguments (which should be strings). 8467 1.9 nikita 8468 1.9 nikita 8469 1.9 nikita <p> 8470 1.9 nikita By convention, 8471 1.9 nikita a one-piece message starting with '<code>@</code>' 8472 1.9 nikita is intended to be a <em>control message</em>, 8473 1.9 nikita which is a message to the warning system itself. 8474 1.9 nikita In particular, the standard warning function in Lua 8475 1.9 nikita recognizes the control messages "<code>@off</code>", 8476 1.9 nikita to stop the emission of warnings, 8477 1.9 nikita and "<code>@on</code>", to (re)start the emission; 8478 1.9 nikita it ignores unknown control messages. 8479 1.1 mbalmer 8480 1.1 mbalmer 8481 1.1 mbalmer 8482 1.1 mbalmer 8483 1.1 mbalmer <p> 8484 1.2 lneto <hr><h3><a name="pdf-xpcall"><code>xpcall (f, msgh [, arg1, ···])</code></a></h3> 8485 1.1 mbalmer 8486 1.1 mbalmer 8487 1.1 mbalmer <p> 8488 1.1 mbalmer This function is similar to <a href="#pdf-pcall"><code>pcall</code></a>, 8489 1.2 lneto except that it sets a new message handler <code>msgh</code>. 8490 1.1 mbalmer 8491 1.1 mbalmer 8492 1.1 mbalmer 8493 1.1 mbalmer 8494 1.1 mbalmer 8495 1.1 mbalmer 8496 1.1 mbalmer 8497 1.2 lneto <h2>6.2 – <a name="6.2">Coroutine Manipulation</a></h2> 8498 1.1 mbalmer 8499 1.1 mbalmer <p> 8500 1.4 mbalmer This library comprises the operations to manipulate coroutines, 8501 1.4 mbalmer which come inside the table <a name="pdf-coroutine"><code>coroutine</code></a>. 8502 1.2 lneto See <a href="#2.6">§2.6</a> for a general description of coroutines. 8503 1.1 mbalmer 8504 1.1 mbalmer 8505 1.1 mbalmer <p> 8506 1.9 nikita <hr><h3><a name="pdf-coroutine.close"><code>coroutine.close (co)</code></a></h3> 8507 1.9 nikita 8508 1.9 nikita 8509 1.9 nikita <p> 8510 1.9 nikita Closes coroutine <code>co</code>, 8511 1.9 nikita that is, 8512 1.9 nikita closes all its pending to-be-closed variables 8513 1.9 nikita and puts the coroutine in a dead state. 8514 1.9 nikita The given coroutine must be dead or suspended. 8515 1.9 nikita In case of error 8516 1.9 nikita (either the original error that stopped the coroutine or 8517 1.9 nikita errors in closing methods), 8518 1.9 nikita returns <b>false</b> plus the error object; 8519 1.9 nikita otherwise returns <b>true</b>. 8520 1.9 nikita 8521 1.9 nikita 8522 1.9 nikita 8523 1.9 nikita 8524 1.9 nikita <p> 8525 1.1 mbalmer <hr><h3><a name="pdf-coroutine.create"><code>coroutine.create (f)</code></a></h3> 8526 1.1 mbalmer 8527 1.1 mbalmer 8528 1.1 mbalmer <p> 8529 1.1 mbalmer Creates a new coroutine, with body <code>f</code>. 8530 1.4 mbalmer <code>f</code> must be a function. 8531 1.2 lneto Returns this new coroutine, 8532 1.2 lneto an object with type <code>"thread"</code>. 8533 1.2 lneto 8534 1.2 lneto 8535 1.2 lneto 8536 1.2 lneto 8537 1.2 lneto <p> 8538 1.9 nikita <hr><h3><a name="pdf-coroutine.isyieldable"><code>coroutine.isyieldable ([co])</code></a></h3> 8539 1.2 lneto 8540 1.2 lneto 8541 1.2 lneto <p> 8542 1.9 nikita Returns <b>true</b> when the coroutine <code>co</code> can yield. 8543 1.9 nikita The default for <code>co</code> is the running coroutine. 8544 1.2 lneto 8545 1.2 lneto 8546 1.2 lneto <p> 8547 1.9 nikita A coroutine is yieldable if it is not the main thread and 8548 1.7 mbalmer it is not inside a non-yieldable C function. 8549 1.1 mbalmer 8550 1.1 mbalmer 8551 1.1 mbalmer 8552 1.1 mbalmer 8553 1.1 mbalmer <p> 8554 1.1 mbalmer <hr><h3><a name="pdf-coroutine.resume"><code>coroutine.resume (co [, val1, ···])</code></a></h3> 8555 1.1 mbalmer 8556 1.1 mbalmer 8557 1.1 mbalmer <p> 8558 1.1 mbalmer Starts or continues the execution of coroutine <code>co</code>. 8559 1.1 mbalmer The first time you resume a coroutine, 8560 1.1 mbalmer it starts running its body. 8561 1.2 lneto The values <code>val1</code>, ... are passed 8562 1.1 mbalmer as the arguments to the body function. 8563 1.1 mbalmer If the coroutine has yielded, 8564 1.1 mbalmer <code>resume</code> restarts it; 8565 1.2 lneto the values <code>val1</code>, ... are passed 8566 1.1 mbalmer as the results from the yield. 8567 1.1 mbalmer 8568 1.1 mbalmer 8569 1.1 mbalmer <p> 8570 1.1 mbalmer If the coroutine runs without any errors, 8571 1.1 mbalmer <code>resume</code> returns <b>true</b> plus any values passed to <code>yield</code> 8572 1.2 lneto (when the coroutine yields) or any values returned by the body function 8573 1.2 lneto (when the coroutine terminates). 8574 1.1 mbalmer If there is any error, 8575 1.1 mbalmer <code>resume</code> returns <b>false</b> plus the error message. 8576 1.1 mbalmer 8577 1.1 mbalmer 8578 1.1 mbalmer 8579 1.1 mbalmer 8580 1.1 mbalmer <p> 8581 1.1 mbalmer <hr><h3><a name="pdf-coroutine.running"><code>coroutine.running ()</code></a></h3> 8582 1.1 mbalmer 8583 1.1 mbalmer 8584 1.1 mbalmer <p> 8585 1.2 lneto Returns the running coroutine plus a boolean, 8586 1.9 nikita <b>true</b> when the running coroutine is the main one. 8587 1.1 mbalmer 8588 1.1 mbalmer 8589 1.1 mbalmer 8590 1.1 mbalmer 8591 1.1 mbalmer <p> 8592 1.1 mbalmer <hr><h3><a name="pdf-coroutine.status"><code>coroutine.status (co)</code></a></h3> 8593 1.1 mbalmer 8594 1.1 mbalmer 8595 1.1 mbalmer <p> 8596 1.9 nikita Returns the status of the coroutine <code>co</code>, as a string: 8597 1.1 mbalmer <code>"running"</code>, 8598 1.9 nikita if the coroutine is running 8599 1.9 nikita (that is, it is the one that called <code>status</code>); 8600 1.1 mbalmer <code>"suspended"</code>, if the coroutine is suspended in a call to <code>yield</code>, 8601 1.1 mbalmer or if it has not started running yet; 8602 1.1 mbalmer <code>"normal"</code> if the coroutine is active but not running 8603 1.1 mbalmer (that is, it has resumed another coroutine); 8604 1.1 mbalmer and <code>"dead"</code> if the coroutine has finished its body function, 8605 1.1 mbalmer or if it has stopped with an error. 8606 1.1 mbalmer 8607 1.1 mbalmer 8608 1.1 mbalmer 8609 1.1 mbalmer 8610 1.1 mbalmer <p> 8611 1.1 mbalmer <hr><h3><a name="pdf-coroutine.wrap"><code>coroutine.wrap (f)</code></a></h3> 8612 1.1 mbalmer 8613 1.1 mbalmer 8614 1.1 mbalmer <p> 8615 1.9 nikita Creates a new coroutine, with body <code>f</code>; 8616 1.4 mbalmer <code>f</code> must be a function. 8617 1.1 mbalmer Returns a function that resumes the coroutine each time it is called. 8618 1.9 nikita Any arguments passed to this function behave as the 8619 1.1 mbalmer extra arguments to <code>resume</code>. 8620 1.9 nikita The function returns the same values returned by <code>resume</code>, 8621 1.1 mbalmer except the first boolean. 8622 1.9 nikita In case of error, 8623 1.9 nikita the function closes the coroutine and propagates the error. 8624 1.1 mbalmer 8625 1.1 mbalmer 8626 1.1 mbalmer 8627 1.1 mbalmer 8628 1.1 mbalmer <p> 8629 1.1 mbalmer <hr><h3><a name="pdf-coroutine.yield"><code>coroutine.yield (···)</code></a></h3> 8630 1.1 mbalmer 8631 1.1 mbalmer 8632 1.1 mbalmer <p> 8633 1.1 mbalmer Suspends the execution of the calling coroutine. 8634 1.1 mbalmer Any arguments to <code>yield</code> are passed as extra results to <code>resume</code>. 8635 1.1 mbalmer 8636 1.1 mbalmer 8637 1.1 mbalmer 8638 1.1 mbalmer 8639 1.1 mbalmer 8640 1.1 mbalmer 8641 1.1 mbalmer 8642 1.2 lneto <h2>6.3 – <a name="6.3">Modules</a></h2> 8643 1.1 mbalmer 8644 1.1 mbalmer <p> 8645 1.1 mbalmer The package library provides basic 8646 1.2 lneto facilities for loading modules in Lua. 8647 1.2 lneto It exports one function directly in the global environment: 8648 1.2 lneto <a href="#pdf-require"><code>require</code></a>. 8649 1.9 nikita Everything else is exported in the table <a name="pdf-package"><code>package</code></a>. 8650 1.1 mbalmer 8651 1.1 mbalmer 8652 1.1 mbalmer <p> 8653 1.1 mbalmer <hr><h3><a name="pdf-require"><code>require (modname)</code></a></h3> 8654 1.1 mbalmer 8655 1.1 mbalmer 8656 1.1 mbalmer <p> 8657 1.1 mbalmer Loads the given module. 8658 1.1 mbalmer The function starts by looking into the <a href="#pdf-package.loaded"><code>package.loaded</code></a> table 8659 1.1 mbalmer to determine whether <code>modname</code> is already loaded. 8660 1.1 mbalmer If it is, then <code>require</code> returns the value stored 8661 1.1 mbalmer at <code>package.loaded[modname]</code>. 8662 1.9 nikita (The absence of a second result in this case 8663 1.9 nikita signals that this call did not have to load the module.) 8664 1.1 mbalmer Otherwise, it tries to find a <em>loader</em> for the module. 8665 1.1 mbalmer 8666 1.1 mbalmer 8667 1.1 mbalmer <p> 8668 1.1 mbalmer To find a loader, 8669 1.9 nikita <code>require</code> is guided by the table <a href="#pdf-package.searchers"><code>package.searchers</code></a>. 8670 1.9 nikita Each item in this table is a search function, 8671 1.9 nikita that searches for the module in a particular way. 8672 1.9 nikita By changing this table, 8673 1.1 mbalmer we can change how <code>require</code> looks for a module. 8674 1.1 mbalmer The following explanation is based on the default configuration 8675 1.2 lneto for <a href="#pdf-package.searchers"><code>package.searchers</code></a>. 8676 1.1 mbalmer 8677 1.1 mbalmer 8678 1.1 mbalmer <p> 8679 1.1 mbalmer First <code>require</code> queries <code>package.preload[modname]</code>. 8680 1.1 mbalmer If it has a value, 8681 1.2 lneto this value (which must be a function) is the loader. 8682 1.1 mbalmer Otherwise <code>require</code> searches for a Lua loader using the 8683 1.1 mbalmer path stored in <a href="#pdf-package.path"><code>package.path</code></a>. 8684 1.1 mbalmer If that also fails, it searches for a C loader using the 8685 1.1 mbalmer path stored in <a href="#pdf-package.cpath"><code>package.cpath</code></a>. 8686 1.1 mbalmer If that also fails, 8687 1.2 lneto it tries an <em>all-in-one</em> loader (see <a href="#pdf-package.searchers"><code>package.searchers</code></a>). 8688 1.1 mbalmer 8689 1.1 mbalmer 8690 1.1 mbalmer <p> 8691 1.1 mbalmer Once a loader is found, 8692 1.2 lneto <code>require</code> calls the loader with two arguments: 8693 1.9 nikita <code>modname</code> and an extra value, 8694 1.9 nikita a <em>loader data</em>, 8695 1.9 nikita also returned by the searcher. 8696 1.9 nikita The loader data can be any value useful to the module; 8697 1.9 nikita for the default searchers, 8698 1.9 nikita it indicates where the loader was found. 8699 1.9 nikita (For instance, if the loader came from a file, 8700 1.9 nikita this extra value is the file path.) 8701 1.2 lneto If the loader returns any non-nil value, 8702 1.1 mbalmer <code>require</code> assigns the returned value to <code>package.loaded[modname]</code>. 8703 1.2 lneto If the loader does not return a non-nil value and 8704 1.1 mbalmer has not assigned any value to <code>package.loaded[modname]</code>, 8705 1.1 mbalmer then <code>require</code> assigns <b>true</b> to this entry. 8706 1.1 mbalmer In any case, <code>require</code> returns the 8707 1.1 mbalmer final value of <code>package.loaded[modname]</code>. 8708 1.9 nikita Besides that value, <code>require</code> also returns as a second result 8709 1.9 nikita the loader data returned by the searcher, 8710 1.9 nikita which indicates how <code>require</code> found the module. 8711 1.1 mbalmer 8712 1.1 mbalmer 8713 1.1 mbalmer <p> 8714 1.1 mbalmer If there is any error loading or running the module, 8715 1.1 mbalmer or if it cannot find any loader for the module, 8716 1.2 lneto then <code>require</code> raises an error. 8717 1.2 lneto 8718 1.2 lneto 8719 1.2 lneto 8720 1.2 lneto 8721 1.2 lneto <p> 8722 1.2 lneto <hr><h3><a name="pdf-package.config"><code>package.config</code></a></h3> 8723 1.2 lneto 8724 1.2 lneto 8725 1.2 lneto <p> 8726 1.2 lneto A string describing some compile-time configurations for packages. 8727 1.2 lneto This string is a sequence of lines: 8728 1.2 lneto 8729 1.2 lneto <ul> 8730 1.2 lneto 8731 1.2 lneto <li>The first line is the directory separator string. 8732 1.2 lneto Default is '<code>\</code>' for Windows and '<code>/</code>' for all other systems.</li> 8733 1.1 mbalmer 8734 1.2 lneto <li>The second line is the character that separates templates in a path. 8735 1.2 lneto Default is '<code>;</code>'.</li> 8736 1.2 lneto 8737 1.2 lneto <li>The third line is the string that marks the 8738 1.2 lneto substitution points in a template. 8739 1.2 lneto Default is '<code>?</code>'.</li> 8740 1.2 lneto 8741 1.2 lneto <li>The fourth line is a string that, in a path in Windows, 8742 1.2 lneto is replaced by the executable's directory. 8743 1.2 lneto Default is '<code>!</code>'.</li> 8744 1.2 lneto 8745 1.3 lneto <li>The fifth line is a mark to ignore all text after it 8746 1.2 lneto when building the <code>luaopen_</code> function name. 8747 1.2 lneto Default is '<code>-</code>'.</li> 8748 1.2 lneto 8749 1.2 lneto </ul> 8750 1.1 mbalmer 8751 1.1 mbalmer 8752 1.1 mbalmer 8753 1.1 mbalmer <p> 8754 1.1 mbalmer <hr><h3><a name="pdf-package.cpath"><code>package.cpath</code></a></h3> 8755 1.1 mbalmer 8756 1.1 mbalmer 8757 1.1 mbalmer <p> 8758 1.9 nikita A string with the path used by <a href="#pdf-require"><code>require</code></a> 8759 1.9 nikita to search for a C loader. 8760 1.1 mbalmer 8761 1.1 mbalmer 8762 1.1 mbalmer <p> 8763 1.1 mbalmer Lua initializes the C path <a href="#pdf-package.cpath"><code>package.cpath</code></a> in the same way 8764 1.1 mbalmer it initializes the Lua path <a href="#pdf-package.path"><code>package.path</code></a>, 8765 1.9 nikita using the environment variable <a name="pdf-LUA_CPATH_5_4"><code>LUA_CPATH_5_4</code></a>, 8766 1.7 mbalmer or the environment variable <a name="pdf-LUA_CPATH"><code>LUA_CPATH</code></a>, 8767 1.1 mbalmer or a default path defined in <code>luaconf.h</code>. 8768 1.1 mbalmer 8769 1.1 mbalmer 8770 1.1 mbalmer 8771 1.1 mbalmer 8772 1.1 mbalmer <p> 8773 1.1 mbalmer <hr><h3><a name="pdf-package.loaded"><code>package.loaded</code></a></h3> 8774 1.1 mbalmer 8775 1.1 mbalmer 8776 1.1 mbalmer <p> 8777 1.1 mbalmer A table used by <a href="#pdf-require"><code>require</code></a> to control which 8778 1.1 mbalmer modules are already loaded. 8779 1.1 mbalmer When you require a module <code>modname</code> and 8780 1.1 mbalmer <code>package.loaded[modname]</code> is not false, 8781 1.1 mbalmer <a href="#pdf-require"><code>require</code></a> simply returns the value stored there. 8782 1.1 mbalmer 8783 1.1 mbalmer 8784 1.2 lneto <p> 8785 1.2 lneto This variable is only a reference to the real table; 8786 1.2 lneto assignments to this variable do not change the 8787 1.2 lneto table used by <a href="#pdf-require"><code>require</code></a>. 8788 1.10 nikita The real table is stored in the C registry (see <a href="#4.3">§4.3</a>), 8789 1.10 nikita indexed by the key <a name="pdf-LUA_LOADED_TABLE"><code>LUA_LOADED_TABLE</code></a>, a string. 8790 1.2 lneto 8791 1.2 lneto 8792 1.2 lneto 8793 1.2 lneto 8794 1.2 lneto <p> 8795 1.2 lneto <hr><h3><a name="pdf-package.loadlib"><code>package.loadlib (libname, funcname)</code></a></h3> 8796 1.2 lneto 8797 1.2 lneto 8798 1.2 lneto <p> 8799 1.2 lneto Dynamically links the host program with the C library <code>libname</code>. 8800 1.2 lneto 8801 1.2 lneto 8802 1.2 lneto <p> 8803 1.2 lneto If <code>funcname</code> is "<code>*</code>", 8804 1.2 lneto then it only links with the library, 8805 1.2 lneto making the symbols exported by the library 8806 1.2 lneto available to other dynamically linked libraries. 8807 1.2 lneto Otherwise, 8808 1.2 lneto it looks for a function <code>funcname</code> inside the library 8809 1.2 lneto and returns this function as a C function. 8810 1.2 lneto So, <code>funcname</code> must follow the <a href="#lua_CFunction"><code>lua_CFunction</code></a> prototype 8811 1.2 lneto (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 8812 1.2 lneto 8813 1.2 lneto 8814 1.2 lneto <p> 8815 1.2 lneto This is a low-level function. 8816 1.2 lneto It completely bypasses the package and module system. 8817 1.2 lneto Unlike <a href="#pdf-require"><code>require</code></a>, 8818 1.2 lneto it does not perform any path searching and 8819 1.2 lneto does not automatically adds extensions. 8820 1.2 lneto <code>libname</code> must be the complete file name of the C library, 8821 1.2 lneto including if necessary a path and an extension. 8822 1.2 lneto <code>funcname</code> must be the exact name exported by the C library 8823 1.2 lneto (which may depend on the C compiler and linker used). 8824 1.2 lneto 8825 1.2 lneto 8826 1.2 lneto <p> 8827 1.10 nikita This functionality is not supported by ISO C. 8828 1.2 lneto As such, it is only available on some platforms 8829 1.2 lneto (Windows, Linux, Mac OS X, Solaris, BSD, 8830 1.2 lneto plus other Unix systems that support the <code>dlfcn</code> standard). 8831 1.2 lneto 8832 1.2 lneto 8833 1.9 nikita <p> 8834 1.9 nikita This function is inherently insecure, 8835 1.9 nikita as it allows Lua to call any function in any readable dynamic 8836 1.9 nikita library in the system. 8837 1.9 nikita (Lua calls any function assuming the function 8838 1.9 nikita has a proper prototype and respects a proper protocol 8839 1.9 nikita (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 8840 1.9 nikita Therefore, 8841 1.9 nikita calling an arbitrary function in an arbitrary dynamic library 8842 1.9 nikita more often than not results in an access violation.) 8843 1.9 nikita 8844 1.9 nikita 8845 1.2 lneto 8846 1.2 lneto 8847 1.2 lneto <p> 8848 1.2 lneto <hr><h3><a name="pdf-package.path"><code>package.path</code></a></h3> 8849 1.2 lneto 8850 1.2 lneto 8851 1.2 lneto <p> 8852 1.9 nikita A string with the path used by <a href="#pdf-require"><code>require</code></a> 8853 1.9 nikita to search for a Lua loader. 8854 1.2 lneto 8855 1.2 lneto 8856 1.2 lneto <p> 8857 1.2 lneto At start-up, Lua initializes this variable with 8858 1.9 nikita the value of the environment variable <a name="pdf-LUA_PATH_5_4"><code>LUA_PATH_5_4</code></a> or 8859 1.2 lneto the environment variable <a name="pdf-LUA_PATH"><code>LUA_PATH</code></a> or 8860 1.2 lneto with a default path defined in <code>luaconf.h</code>, 8861 1.2 lneto if those environment variables are not defined. 8862 1.9 nikita A "<code>;;</code>" in the value of the environment variable 8863 1.2 lneto is replaced by the default path. 8864 1.2 lneto 8865 1.2 lneto 8866 1.2 lneto 8867 1.2 lneto 8868 1.2 lneto <p> 8869 1.2 lneto <hr><h3><a name="pdf-package.preload"><code>package.preload</code></a></h3> 8870 1.2 lneto 8871 1.2 lneto 8872 1.2 lneto <p> 8873 1.2 lneto A table to store loaders for specific modules 8874 1.2 lneto (see <a href="#pdf-require"><code>require</code></a>). 8875 1.2 lneto 8876 1.2 lneto 8877 1.2 lneto <p> 8878 1.2 lneto This variable is only a reference to the real table; 8879 1.2 lneto assignments to this variable do not change the 8880 1.2 lneto table used by <a href="#pdf-require"><code>require</code></a>. 8881 1.10 nikita The real table is stored in the C registry (see <a href="#4.3">§4.3</a>), 8882 1.10 nikita indexed by the key <a name="pdf-LUA_PRELOAD_TABLE"><code>LUA_PRELOAD_TABLE</code></a>, a string. 8883 1.2 lneto 8884 1.2 lneto 8885 1.1 mbalmer 8886 1.1 mbalmer 8887 1.1 mbalmer <p> 8888 1.2 lneto <hr><h3><a name="pdf-package.searchers"><code>package.searchers</code></a></h3> 8889 1.1 mbalmer 8890 1.1 mbalmer 8891 1.1 mbalmer <p> 8892 1.9 nikita A table used by <a href="#pdf-require"><code>require</code></a> to control how to find modules. 8893 1.1 mbalmer 8894 1.1 mbalmer 8895 1.1 mbalmer <p> 8896 1.1 mbalmer Each entry in this table is a <em>searcher function</em>. 8897 1.1 mbalmer When looking for a module, 8898 1.1 mbalmer <a href="#pdf-require"><code>require</code></a> calls each of these searchers in ascending order, 8899 1.1 mbalmer with the module name (the argument given to <a href="#pdf-require"><code>require</code></a>) as its 8900 1.9 nikita sole argument. 8901 1.9 nikita If the searcher finds the module, 8902 1.9 nikita it returns another function, the module <em>loader</em>, 8903 1.9 nikita plus an extra value, a <em>loader data</em>, 8904 1.9 nikita that will be passed to that loader and 8905 1.9 nikita returned as a second result by <a href="#pdf-require"><code>require</code></a>. 8906 1.9 nikita If it cannot find the module, 8907 1.9 nikita it returns a string explaining why 8908 1.1 mbalmer (or <b>nil</b> if it has nothing to say). 8909 1.2 lneto 8910 1.2 lneto 8911 1.2 lneto <p> 8912 1.2 lneto Lua initializes this table with four searcher functions. 8913 1.1 mbalmer 8914 1.1 mbalmer 8915 1.1 mbalmer <p> 8916 1.1 mbalmer The first searcher simply looks for a loader in the 8917 1.1 mbalmer <a href="#pdf-package.preload"><code>package.preload</code></a> table. 8918 1.1 mbalmer 8919 1.1 mbalmer 8920 1.1 mbalmer <p> 8921 1.1 mbalmer The second searcher looks for a loader as a Lua library, 8922 1.1 mbalmer using the path stored at <a href="#pdf-package.path"><code>package.path</code></a>. 8923 1.2 lneto The search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. 8924 1.1 mbalmer 8925 1.1 mbalmer 8926 1.1 mbalmer <p> 8927 1.1 mbalmer The third searcher looks for a loader as a C library, 8928 1.1 mbalmer using the path given by the variable <a href="#pdf-package.cpath"><code>package.cpath</code></a>. 8929 1.2 lneto Again, 8930 1.2 lneto the search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. 8931 1.1 mbalmer For instance, 8932 1.1 mbalmer if the C path is the string 8933 1.1 mbalmer 8934 1.1 mbalmer <pre> 8935 1.1 mbalmer "./?.so;./?.dll;/usr/local/?/init.so" 8936 1.1 mbalmer </pre><p> 8937 1.1 mbalmer the searcher for module <code>foo</code> 8938 1.1 mbalmer will try to open the files <code>./foo.so</code>, <code>./foo.dll</code>, 8939 1.1 mbalmer and <code>/usr/local/foo/init.so</code>, in that order. 8940 1.1 mbalmer Once it finds a C library, 8941 1.1 mbalmer this searcher first uses a dynamic link facility to link the 8942 1.1 mbalmer application with the library. 8943 1.1 mbalmer Then it tries to find a C function inside the library to 8944 1.1 mbalmer be used as the loader. 8945 1.1 mbalmer The name of this C function is the string "<code>luaopen_</code>" 8946 1.1 mbalmer concatenated with a copy of the module name where each dot 8947 1.1 mbalmer is replaced by an underscore. 8948 1.1 mbalmer Moreover, if the module name has a hyphen, 8949 1.3 lneto its suffix after (and including) the first hyphen is removed. 8950 1.3 lneto For instance, if the module name is <code>a.b.c-v2.1</code>, 8951 1.3 lneto the function name will be <code>luaopen_a_b_c</code>. 8952 1.1 mbalmer 8953 1.1 mbalmer 8954 1.1 mbalmer <p> 8955 1.1 mbalmer The fourth searcher tries an <em>all-in-one loader</em>. 8956 1.1 mbalmer It searches the C path for a library for 8957 1.1 mbalmer the root name of the given module. 8958 1.1 mbalmer For instance, when requiring <code>a.b.c</code>, 8959 1.1 mbalmer it will search for a C library for <code>a</code>. 8960 1.1 mbalmer If found, it looks into it for an open function for 8961 1.1 mbalmer the submodule; 8962 1.1 mbalmer in our example, that would be <code>luaopen_a_b_c</code>. 8963 1.1 mbalmer With this facility, a package can pack several C submodules 8964 1.1 mbalmer into one single library, 8965 1.1 mbalmer with each submodule keeping its original open function. 8966 1.1 mbalmer 8967 1.1 mbalmer 8968 1.1 mbalmer <p> 8969 1.2 lneto All searchers except the first one (preload) return as the extra value 8970 1.9 nikita the file path where the module was found, 8971 1.2 lneto as returned by <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. 8972 1.9 nikita The first searcher always returns the string "<code>:preload:</code>". 8973 1.9 nikita 8974 1.9 nikita 8975 1.9 nikita <p> 8976 1.9 nikita Searchers should raise no errors and have no side effects in Lua. 8977 1.9 nikita (They may have side effects in C, 8978 1.9 nikita for instance by linking the application with a library.) 8979 1.1 mbalmer 8980 1.1 mbalmer 8981 1.1 mbalmer 8982 1.1 mbalmer 8983 1.1 mbalmer <p> 8984 1.2 lneto <hr><h3><a name="pdf-package.searchpath"><code>package.searchpath (name, path [, sep [, rep]])</code></a></h3> 8985 1.1 mbalmer 8986 1.1 mbalmer 8987 1.1 mbalmer <p> 8988 1.2 lneto Searches for the given <code>name</code> in the given <code>path</code>. 8989 1.1 mbalmer 8990 1.1 mbalmer 8991 1.1 mbalmer <p> 8992 1.2 lneto A path is a string containing a sequence of 8993 1.2 lneto <em>templates</em> separated by semicolons. 8994 1.2 lneto For each template, 8995 1.2 lneto the function replaces each interrogation mark (if any) 8996 1.2 lneto in the template with a copy of <code>name</code> 8997 1.2 lneto wherein all occurrences of <code>sep</code> 8998 1.2 lneto (a dot, by default) 8999 1.2 lneto were replaced by <code>rep</code> 9000 1.2 lneto (the system's directory separator, by default), 9001 1.2 lneto and then tries to open the resulting file name. 9002 1.1 mbalmer 9003 1.1 mbalmer 9004 1.1 mbalmer <p> 9005 1.2 lneto For instance, if the path is the string 9006 1.1 mbalmer 9007 1.2 lneto <pre> 9008 1.2 lneto "./?.lua;./?.lc;/usr/local/?/init.lua" 9009 1.2 lneto </pre><p> 9010 1.2 lneto the search for the name <code>foo.a</code> 9011 1.2 lneto will try to open the files 9012 1.2 lneto <code>./foo/a.lua</code>, <code>./foo/a.lc</code>, and 9013 1.2 lneto <code>/usr/local/foo/a/init.lua</code>, in that order. 9014 1.1 mbalmer 9015 1.1 mbalmer 9016 1.1 mbalmer <p> 9017 1.2 lneto Returns the resulting name of the first file that it can 9018 1.2 lneto open in read mode (after closing the file), 9019 1.9 nikita or <b>fail</b> plus an error message if none succeeds. 9020 1.2 lneto (This error message lists all file names it tried to open.) 9021 1.1 mbalmer 9022 1.1 mbalmer 9023 1.1 mbalmer 9024 1.1 mbalmer 9025 1.1 mbalmer 9026 1.1 mbalmer 9027 1.1 mbalmer 9028 1.2 lneto <h2>6.4 – <a name="6.4">String Manipulation</a></h2> 9029 1.1 mbalmer 9030 1.9 nikita 9031 1.9 nikita 9032 1.1 mbalmer <p> 9033 1.1 mbalmer This library provides generic functions for string manipulation, 9034 1.1 mbalmer such as finding and extracting substrings, and pattern matching. 9035 1.1 mbalmer When indexing a string in Lua, the first character is at position 1 9036 1.1 mbalmer (not at 0, as in C). 9037 1.1 mbalmer Indices are allowed to be negative and are interpreted as indexing backwards, 9038 1.1 mbalmer from the end of the string. 9039 1.1 mbalmer Thus, the last character is at position -1, and so on. 9040 1.1 mbalmer 9041 1.1 mbalmer 9042 1.1 mbalmer <p> 9043 1.1 mbalmer The string library provides all its functions inside the table 9044 1.1 mbalmer <a name="pdf-string"><code>string</code></a>. 9045 1.1 mbalmer It also sets a metatable for strings 9046 1.1 mbalmer where the <code>__index</code> field points to the <code>string</code> table. 9047 1.1 mbalmer Therefore, you can use the string functions in object-oriented style. 9048 1.2 lneto For instance, <code>string.byte(s,i)</code> 9049 1.1 mbalmer can be written as <code>s:byte(i)</code>. 9050 1.1 mbalmer 9051 1.1 mbalmer 9052 1.1 mbalmer <p> 9053 1.1 mbalmer The string library assumes one-byte character encodings. 9054 1.1 mbalmer 9055 1.1 mbalmer 9056 1.1 mbalmer <p> 9057 1.1 mbalmer <hr><h3><a name="pdf-string.byte"><code>string.byte (s [, i [, j]])</code></a></h3> 9058 1.4 mbalmer Returns the internal numeric codes of the characters <code>s[i]</code>, 9059 1.2 lneto <code>s[i+1]</code>, ..., <code>s[j]</code>. 9060 1.1 mbalmer The default value for <code>i</code> is 1; 9061 1.1 mbalmer the default value for <code>j</code> is <code>i</code>. 9062 1.2 lneto These indices are corrected 9063 1.2 lneto following the same rules of function <a href="#pdf-string.sub"><code>string.sub</code></a>. 9064 1.1 mbalmer 9065 1.1 mbalmer 9066 1.1 mbalmer <p> 9067 1.4 mbalmer Numeric codes are not necessarily portable across platforms. 9068 1.1 mbalmer 9069 1.1 mbalmer 9070 1.1 mbalmer 9071 1.1 mbalmer 9072 1.1 mbalmer <p> 9073 1.1 mbalmer <hr><h3><a name="pdf-string.char"><code>string.char (···)</code></a></h3> 9074 1.1 mbalmer Receives zero or more integers. 9075 1.1 mbalmer Returns a string with length equal to the number of arguments, 9076 1.4 mbalmer in which each character has the internal numeric code equal 9077 1.1 mbalmer to its corresponding argument. 9078 1.1 mbalmer 9079 1.1 mbalmer 9080 1.1 mbalmer <p> 9081 1.4 mbalmer Numeric codes are not necessarily portable across platforms. 9082 1.2 lneto 9083 1.2 lneto 9084 1.2 lneto 9085 1.2 lneto 9086 1.2 lneto <p> 9087 1.2 lneto <hr><h3><a name="pdf-string.dump"><code>string.dump (function [, strip])</code></a></h3> 9088 1.1 mbalmer 9089 1.1 mbalmer 9090 1.2 lneto <p> 9091 1.2 lneto Returns a string containing a binary representation 9092 1.2 lneto (a <em>binary chunk</em>) 9093 1.2 lneto of the given function, 9094 1.2 lneto so that a later <a href="#pdf-load"><code>load</code></a> on this string returns 9095 1.2 lneto a copy of the function (but with new upvalues). 9096 1.2 lneto If <code>strip</code> is a true value, 9097 1.4 mbalmer the binary representation may not include all debug information 9098 1.4 mbalmer about the function, 9099 1.4 mbalmer to save space. 9100 1.2 lneto 9101 1.2 lneto 9102 1.2 lneto <p> 9103 1.3 lneto Functions with upvalues have only their number of upvalues saved. 9104 1.3 lneto When (re)loaded, 9105 1.9 nikita those upvalues receive fresh instances. 9106 1.9 nikita (See the <a href="#pdf-load"><code>load</code></a> function for details about 9107 1.9 nikita how these upvalues are initialized. 9108 1.9 nikita You can use the debug library to serialize 9109 1.3 lneto and reload the upvalues of a function 9110 1.3 lneto in a way adequate to your needs.) 9111 1.1 mbalmer 9112 1.1 mbalmer 9113 1.1 mbalmer 9114 1.1 mbalmer 9115 1.1 mbalmer <p> 9116 1.1 mbalmer <hr><h3><a name="pdf-string.find"><code>string.find (s, pattern [, init [, plain]])</code></a></h3> 9117 1.2 lneto 9118 1.2 lneto 9119 1.2 lneto <p> 9120 1.1 mbalmer Looks for the first match of 9121 1.3 lneto <code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) in the string <code>s</code>. 9122 1.1 mbalmer If it finds a match, then <code>find</code> returns the indices of <code>s</code> 9123 1.1 mbalmer where this occurrence starts and ends; 9124 1.9 nikita otherwise, it returns <b>fail</b>. 9125 1.4 mbalmer A third, optional numeric argument <code>init</code> specifies 9126 1.1 mbalmer where to start the search; 9127 1.1 mbalmer its default value is 1 and can be negative. 9128 1.9 nikita A <b>true</b> as a fourth, optional argument <code>plain</code> 9129 1.1 mbalmer turns off the pattern matching facilities, 9130 1.1 mbalmer so the function does a plain "find substring" operation, 9131 1.2 lneto with no characters in <code>pattern</code> being considered magic. 9132 1.1 mbalmer 9133 1.1 mbalmer 9134 1.1 mbalmer <p> 9135 1.1 mbalmer If the pattern has captures, 9136 1.1 mbalmer then in a successful match 9137 1.1 mbalmer the captured values are also returned, 9138 1.1 mbalmer after the two indices. 9139 1.1 mbalmer 9140 1.1 mbalmer 9141 1.1 mbalmer 9142 1.1 mbalmer 9143 1.1 mbalmer <p> 9144 1.1 mbalmer <hr><h3><a name="pdf-string.format"><code>string.format (formatstring, ···)</code></a></h3> 9145 1.2 lneto 9146 1.2 lneto 9147 1.2 lneto <p> 9148 1.1 mbalmer Returns a formatted version of its variable number of arguments 9149 1.9 nikita following the description given in its first argument, 9150 1.9 nikita which must be a string. 9151 1.3 lneto The format string follows the same rules as the ISO C function <code>sprintf</code>. 9152 1.9 nikita The only differences are that the conversion specifiers and modifiers 9153 1.9 nikita <code>F</code>, <code>n</code>, <code>*</code>, <code>h</code>, <code>L</code>, and <code>l</code> are not supported 9154 1.9 nikita and that there is an extra specifier, <code>q</code>. 9155 1.9 nikita Both width and precision, when present, 9156 1.9 nikita are limited to two digits. 9157 1.6 salazar 9158 1.6 salazar 9159 1.6 salazar <p> 9160 1.9 nikita The specifier <code>q</code> formats booleans, nil, numbers, and strings 9161 1.9 nikita in a way that the result is a valid constant in Lua source code. 9162 1.9 nikita Booleans and nil are written in the obvious way 9163 1.9 nikita (<code>true</code>, <code>false</code>, <code>nil</code>). 9164 1.9 nikita Floats are written in hexadecimal, 9165 1.9 nikita to preserve full precision. 9166 1.9 nikita A string is written between double quotes, 9167 1.2 lneto using escape sequences when necessary to ensure that 9168 1.2 lneto it can safely be read back by the Lua interpreter. 9169 1.1 mbalmer For instance, the call 9170 1.1 mbalmer 9171 1.1 mbalmer <pre> 9172 1.1 mbalmer string.format('%q', 'a string with "quotes" and \n new line') 9173 1.1 mbalmer </pre><p> 9174 1.2 lneto may produce the string: 9175 1.1 mbalmer 9176 1.1 mbalmer <pre> 9177 1.1 mbalmer "a string with \"quotes\" and \ 9178 1.1 mbalmer new line" 9179 1.9 nikita </pre><p> 9180 1.9 nikita This specifier does not support modifiers (flags, width, precision). 9181 1.9 nikita 9182 1.1 mbalmer 9183 1.1 mbalmer <p> 9184 1.9 nikita The conversion specifiers 9185 1.4 mbalmer <code>A</code>, <code>a</code>, <code>E</code>, <code>e</code>, <code>f</code>, 9186 1.2 lneto <code>G</code>, and <code>g</code> all expect a number as argument. 9187 1.9 nikita The specifiers <code>c</code>, <code>d</code>, 9188 1.2 lneto <code>i</code>, <code>o</code>, <code>u</code>, <code>X</code>, and <code>x</code> 9189 1.2 lneto expect an integer. 9190 1.6 salazar When Lua is compiled with a C89 compiler, 9191 1.9 nikita the specifiers <code>A</code> and <code>a</code> (hexadecimal floats) 9192 1.9 nikita do not support modifiers. 9193 1.6 salazar 9194 1.6 salazar 9195 1.6 salazar <p> 9196 1.9 nikita The specifier <code>s</code> expects a string; 9197 1.4 mbalmer if its argument is not a string, 9198 1.2 lneto it is converted to one following the same rules of <a href="#pdf-tostring"><code>tostring</code></a>. 9199 1.9 nikita If the specifier has any modifier, 9200 1.9 nikita the corresponding string argument should not contain embedded zeros. 9201 1.9 nikita 9202 1.9 nikita 9203 1.9 nikita <p> 9204 1.9 nikita The specifier <code>p</code> formats the pointer 9205 1.9 nikita returned by <a href="#lua_topointer"><code>lua_topointer</code></a>. 9206 1.9 nikita That gives a unique string identifier for tables, userdata, 9207 1.9 nikita threads, strings, and functions. 9208 1.9 nikita For other values (numbers, nil, booleans), 9209 1.9 nikita this specifier results in a string representing 9210 1.9 nikita the pointer <code>NULL</code>. 9211 1.1 mbalmer 9212 1.1 mbalmer 9213 1.1 mbalmer 9214 1.1 mbalmer 9215 1.1 mbalmer <p> 9216 1.9 nikita <hr><h3><a name="pdf-string.gmatch"><code>string.gmatch (s, pattern [, init])</code></a></h3> 9217 1.1 mbalmer Returns an iterator function that, 9218 1.1 mbalmer each time it is called, 9219 1.3 lneto returns the next captures from <code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) 9220 1.3 lneto over the string <code>s</code>. 9221 1.1 mbalmer If <code>pattern</code> specifies no captures, 9222 1.1 mbalmer then the whole match is produced in each call. 9223 1.9 nikita A third, optional numeric argument <code>init</code> specifies 9224 1.9 nikita where to start the search; 9225 1.9 nikita its default value is 1 and can be negative. 9226 1.1 mbalmer 9227 1.1 mbalmer 9228 1.1 mbalmer <p> 9229 1.1 mbalmer As an example, the following loop 9230 1.2 lneto will iterate over all the words from string <code>s</code>, 9231 1.2 lneto printing one per line: 9232 1.1 mbalmer 9233 1.1 mbalmer <pre> 9234 1.1 mbalmer s = "hello world from Lua" 9235 1.1 mbalmer for w in string.gmatch(s, "%a+") do 9236 1.1 mbalmer print(w) 9237 1.1 mbalmer end 9238 1.1 mbalmer </pre><p> 9239 1.1 mbalmer The next example collects all pairs <code>key=value</code> from the 9240 1.1 mbalmer given string into a table: 9241 1.1 mbalmer 9242 1.1 mbalmer <pre> 9243 1.1 mbalmer t = {} 9244 1.1 mbalmer s = "from=world, to=Lua" 9245 1.1 mbalmer for k, v in string.gmatch(s, "(%w+)=(%w+)") do 9246 1.1 mbalmer t[k] = v 9247 1.1 mbalmer end 9248 1.1 mbalmer </pre> 9249 1.1 mbalmer 9250 1.1 mbalmer <p> 9251 1.2 lneto For this function, a caret '<code>^</code>' at the start of a pattern does not 9252 1.1 mbalmer work as an anchor, as this would prevent the iteration. 9253 1.1 mbalmer 9254 1.1 mbalmer 9255 1.1 mbalmer 9256 1.1 mbalmer 9257 1.1 mbalmer <p> 9258 1.1 mbalmer <hr><h3><a name="pdf-string.gsub"><code>string.gsub (s, pattern, repl [, n])</code></a></h3> 9259 1.1 mbalmer Returns a copy of <code>s</code> 9260 1.1 mbalmer in which all (or the first <code>n</code>, if given) 9261 1.3 lneto occurrences of the <code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) have been 9262 1.1 mbalmer replaced by a replacement string specified by <code>repl</code>, 9263 1.1 mbalmer which can be a string, a table, or a function. 9264 1.1 mbalmer <code>gsub</code> also returns, as its second value, 9265 1.1 mbalmer the total number of matches that occurred. 9266 1.2 lneto The name <code>gsub</code> comes from <em>Global SUBstitution</em>. 9267 1.1 mbalmer 9268 1.1 mbalmer 9269 1.1 mbalmer <p> 9270 1.1 mbalmer If <code>repl</code> is a string, then its value is used for replacement. 9271 1.1 mbalmer The character <code>%</code> works as an escape character: 9272 1.2 lneto any sequence in <code>repl</code> of the form <code>%<em>d</em></code>, 9273 1.2 lneto with <em>d</em> between 1 and 9, 9274 1.9 nikita stands for the value of the <em>d</em>-th captured substring; 9275 1.9 nikita the sequence <code>%0</code> stands for the whole match; 9276 1.9 nikita the sequence <code>%%</code> stands for a single <code>%</code>. 9277 1.1 mbalmer 9278 1.1 mbalmer 9279 1.1 mbalmer <p> 9280 1.1 mbalmer If <code>repl</code> is a table, then the table is queried for every match, 9281 1.2 lneto using the first capture as the key. 9282 1.1 mbalmer 9283 1.1 mbalmer 9284 1.1 mbalmer <p> 9285 1.1 mbalmer If <code>repl</code> is a function, then this function is called every time a 9286 1.1 mbalmer match occurs, with all captured substrings passed as arguments, 9287 1.2 lneto in order. 9288 1.2 lneto 9289 1.2 lneto 9290 1.2 lneto <p> 9291 1.2 lneto In any case, 9292 1.1 mbalmer if the pattern specifies no captures, 9293 1.2 lneto then it behaves as if the whole pattern was inside a capture. 9294 1.1 mbalmer 9295 1.1 mbalmer 9296 1.1 mbalmer <p> 9297 1.1 mbalmer If the value returned by the table query or by the function call 9298 1.1 mbalmer is a string or a number, 9299 1.1 mbalmer then it is used as the replacement string; 9300 1.1 mbalmer otherwise, if it is <b>false</b> or <b>nil</b>, 9301 1.1 mbalmer then there is no replacement 9302 1.1 mbalmer (that is, the original match is kept in the string). 9303 1.1 mbalmer 9304 1.1 mbalmer 9305 1.1 mbalmer <p> 9306 1.1 mbalmer Here are some examples: 9307 1.1 mbalmer 9308 1.1 mbalmer <pre> 9309 1.1 mbalmer x = string.gsub("hello world", "(%w+)", "%1 %1") 9310 1.1 mbalmer --> x="hello hello world world" 9311 1.1 mbalmer 9312 1.1 mbalmer x = string.gsub("hello world", "%w+", "%0 %0", 1) 9313 1.1 mbalmer --> x="hello hello world" 9314 1.1 mbalmer 9315 1.1 mbalmer x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1") 9316 1.1 mbalmer --> x="world hello Lua from" 9317 1.1 mbalmer 9318 1.1 mbalmer x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv) 9319 1.1 mbalmer --> x="home = /home/roberto, user = roberto" 9320 1.1 mbalmer 9321 1.1 mbalmer x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s) 9322 1.2 lneto return load(s)() 9323 1.1 mbalmer end) 9324 1.1 mbalmer --> x="4+5 = 9" 9325 1.1 mbalmer 9326 1.9 nikita local t = {name="lua", version="5.4"} 9327 1.1 mbalmer x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t) 9328 1.9 nikita --> x="lua-5.4.tar.gz" 9329 1.1 mbalmer </pre> 9330 1.1 mbalmer 9331 1.1 mbalmer 9332 1.1 mbalmer 9333 1.1 mbalmer <p> 9334 1.1 mbalmer <hr><h3><a name="pdf-string.len"><code>string.len (s)</code></a></h3> 9335 1.9 nikita 9336 1.9 nikita 9337 1.9 nikita <p> 9338 1.1 mbalmer Receives a string and returns its length. 9339 1.1 mbalmer The empty string <code>""</code> has length 0. 9340 1.1 mbalmer Embedded zeros are counted, 9341 1.1 mbalmer so <code>"a\000bc\000"</code> has length 5. 9342 1.1 mbalmer 9343 1.1 mbalmer 9344 1.1 mbalmer 9345 1.1 mbalmer 9346 1.1 mbalmer <p> 9347 1.1 mbalmer <hr><h3><a name="pdf-string.lower"><code>string.lower (s)</code></a></h3> 9348 1.9 nikita 9349 1.9 nikita 9350 1.9 nikita <p> 9351 1.1 mbalmer Receives a string and returns a copy of this string with all 9352 1.1 mbalmer uppercase letters changed to lowercase. 9353 1.1 mbalmer All other characters are left unchanged. 9354 1.1 mbalmer The definition of what an uppercase letter is depends on the current locale. 9355 1.1 mbalmer 9356 1.1 mbalmer 9357 1.1 mbalmer 9358 1.1 mbalmer 9359 1.1 mbalmer <p> 9360 1.1 mbalmer <hr><h3><a name="pdf-string.match"><code>string.match (s, pattern [, init])</code></a></h3> 9361 1.9 nikita 9362 1.9 nikita 9363 1.9 nikita <p> 9364 1.1 mbalmer Looks for the first <em>match</em> of 9365 1.9 nikita the <code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) in the string <code>s</code>. 9366 1.1 mbalmer If it finds one, then <code>match</code> returns 9367 1.1 mbalmer the captures from the pattern; 9368 1.9 nikita otherwise it returns <b>fail</b>. 9369 1.1 mbalmer If <code>pattern</code> specifies no captures, 9370 1.1 mbalmer then the whole match is returned. 9371 1.4 mbalmer A third, optional numeric argument <code>init</code> specifies 9372 1.1 mbalmer where to start the search; 9373 1.1 mbalmer its default value is 1 and can be negative. 9374 1.1 mbalmer 9375 1.1 mbalmer 9376 1.1 mbalmer 9377 1.1 mbalmer 9378 1.1 mbalmer <p> 9379 1.3 lneto <hr><h3><a name="pdf-string.pack"><code>string.pack (fmt, v1, v2, ···)</code></a></h3> 9380 1.3 lneto 9381 1.3 lneto 9382 1.3 lneto <p> 9383 1.3 lneto Returns a binary string containing the values <code>v1</code>, <code>v2</code>, etc. 9384 1.9 nikita serialized in binary form (packed) 9385 1.7 mbalmer according to the format string <code>fmt</code> (see <a href="#6.4.2">§6.4.2</a>). 9386 1.3 lneto 9387 1.3 lneto 9388 1.3 lneto 9389 1.3 lneto 9390 1.3 lneto <p> 9391 1.3 lneto <hr><h3><a name="pdf-string.packsize"><code>string.packsize (fmt)</code></a></h3> 9392 1.3 lneto 9393 1.3 lneto 9394 1.3 lneto <p> 9395 1.10 nikita Returns the length of a string resulting from <a href="#pdf-string.pack"><code>string.pack</code></a> 9396 1.3 lneto with the given format. 9397 1.3 lneto The format string cannot have the variable-length options 9398 1.3 lneto '<code>s</code>' or '<code>z</code>' (see <a href="#6.4.2">§6.4.2</a>). 9399 1.3 lneto 9400 1.3 lneto 9401 1.3 lneto 9402 1.3 lneto 9403 1.3 lneto <p> 9404 1.2 lneto <hr><h3><a name="pdf-string.rep"><code>string.rep (s, n [, sep])</code></a></h3> 9405 1.9 nikita 9406 1.9 nikita 9407 1.9 nikita <p> 9408 1.1 mbalmer Returns a string that is the concatenation of <code>n</code> copies of 9409 1.2 lneto the string <code>s</code> separated by the string <code>sep</code>. 9410 1.2 lneto The default value for <code>sep</code> is the empty string 9411 1.2 lneto (that is, no separator). 9412 1.3 lneto Returns the empty string if <code>n</code> is not positive. 9413 1.1 mbalmer 9414 1.1 mbalmer 9415 1.5 lneto <p> 9416 1.5 lneto (Note that it is very easy to exhaust the memory of your machine 9417 1.5 lneto with a single call to this function.) 9418 1.5 lneto 9419 1.5 lneto 9420 1.1 mbalmer 9421 1.1 mbalmer 9422 1.1 mbalmer <p> 9423 1.1 mbalmer <hr><h3><a name="pdf-string.reverse"><code>string.reverse (s)</code></a></h3> 9424 1.9 nikita 9425 1.9 nikita 9426 1.9 nikita <p> 9427 1.1 mbalmer Returns a string that is the string <code>s</code> reversed. 9428 1.1 mbalmer 9429 1.1 mbalmer 9430 1.1 mbalmer 9431 1.1 mbalmer 9432 1.1 mbalmer <p> 9433 1.1 mbalmer <hr><h3><a name="pdf-string.sub"><code>string.sub (s, i [, j])</code></a></h3> 9434 1.9 nikita 9435 1.9 nikita 9436 1.9 nikita <p> 9437 1.1 mbalmer Returns the substring of <code>s</code> that 9438 1.1 mbalmer starts at <code>i</code> and continues until <code>j</code>; 9439 1.1 mbalmer <code>i</code> and <code>j</code> can be negative. 9440 1.1 mbalmer If <code>j</code> is absent, then it is assumed to be equal to -1 9441 1.1 mbalmer (which is the same as the string length). 9442 1.1 mbalmer In particular, 9443 1.1 mbalmer the call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code> 9444 1.1 mbalmer with length <code>j</code>, 9445 1.7 mbalmer and <code>string.sub(s, -i)</code> (for a positive <code>i</code>) 9446 1.7 mbalmer returns a suffix of <code>s</code> 9447 1.1 mbalmer with length <code>i</code>. 9448 1.1 mbalmer 9449 1.1 mbalmer 9450 1.2 lneto <p> 9451 1.2 lneto If, after the translation of negative indices, 9452 1.2 lneto <code>i</code> is less than 1, 9453 1.2 lneto it is corrected to 1. 9454 1.2 lneto If <code>j</code> is greater than the string length, 9455 1.2 lneto it is corrected to that length. 9456 1.2 lneto If, after these corrections, 9457 1.2 lneto <code>i</code> is greater than <code>j</code>, 9458 1.2 lneto the function returns the empty string. 9459 1.2 lneto 9460 1.2 lneto 9461 1.2 lneto 9462 1.2 lneto 9463 1.2 lneto <p> 9464 1.3 lneto <hr><h3><a name="pdf-string.unpack"><code>string.unpack (fmt, s [, pos])</code></a></h3> 9465 1.2 lneto 9466 1.2 lneto 9467 1.2 lneto <p> 9468 1.3 lneto Returns the values packed in string <code>s</code> (see <a href="#pdf-string.pack"><code>string.pack</code></a>) 9469 1.3 lneto according to the format string <code>fmt</code> (see <a href="#6.4.2">§6.4.2</a>). 9470 1.3 lneto An optional <code>pos</code> marks where 9471 1.3 lneto to start reading in <code>s</code> (default is 1). 9472 1.3 lneto After the read values, 9473 1.3 lneto this function also returns the index of the first unread byte in <code>s</code>. 9474 1.2 lneto 9475 1.2 lneto 9476 1.1 mbalmer 9477 1.1 mbalmer 9478 1.1 mbalmer <p> 9479 1.1 mbalmer <hr><h3><a name="pdf-string.upper"><code>string.upper (s)</code></a></h3> 9480 1.9 nikita 9481 1.9 nikita 9482 1.9 nikita <p> 9483 1.1 mbalmer Receives a string and returns a copy of this string with all 9484 1.1 mbalmer lowercase letters changed to uppercase. 9485 1.1 mbalmer All other characters are left unchanged. 9486 1.1 mbalmer The definition of what a lowercase letter is depends on the current locale. 9487 1.1 mbalmer 9488 1.1 mbalmer 9489 1.1 mbalmer 9490 1.3 lneto 9491 1.3 lneto 9492 1.9 nikita 9493 1.9 nikita 9494 1.2 lneto <h3>6.4.1 – <a name="6.4.1">Patterns</a></h3> 9495 1.1 mbalmer 9496 1.9 nikita 9497 1.9 nikita 9498 1.3 lneto <p> 9499 1.3 lneto Patterns in Lua are described by regular strings, 9500 1.3 lneto which are interpreted as patterns by the pattern-matching functions 9501 1.3 lneto <a href="#pdf-string.find"><code>string.find</code></a>, 9502 1.3 lneto <a href="#pdf-string.gmatch"><code>string.gmatch</code></a>, 9503 1.3 lneto <a href="#pdf-string.gsub"><code>string.gsub</code></a>, 9504 1.3 lneto and <a href="#pdf-string.match"><code>string.match</code></a>. 9505 1.3 lneto This section describes the syntax and the meaning 9506 1.3 lneto (that is, what they match) of these strings. 9507 1.3 lneto 9508 1.3 lneto 9509 1.1 mbalmer 9510 1.9 nikita 9511 1.9 nikita 9512 1.1 mbalmer <h4>Character Class:</h4><p> 9513 1.1 mbalmer A <em>character class</em> is used to represent a set of characters. 9514 1.1 mbalmer The following combinations are allowed in describing a character class: 9515 1.1 mbalmer 9516 1.1 mbalmer <ul> 9517 1.1 mbalmer 9518 1.2 lneto <li><b><em>x</em>: </b> 9519 1.1 mbalmer (where <em>x</em> is not one of the <em>magic characters</em> 9520 1.1 mbalmer <code>^$()%.[]*+-?</code>) 9521 1.1 mbalmer represents the character <em>x</em> itself. 9522 1.1 mbalmer </li> 9523 1.1 mbalmer 9524 1.2 lneto <li><b><code>.</code>: </b> (a dot) represents all characters.</li> 9525 1.1 mbalmer 9526 1.2 lneto <li><b><code>%a</code>: </b> represents all letters.</li> 9527 1.1 mbalmer 9528 1.2 lneto <li><b><code>%c</code>: </b> represents all control characters.</li> 9529 1.1 mbalmer 9530 1.2 lneto <li><b><code>%d</code>: </b> represents all digits.</li> 9531 1.1 mbalmer 9532 1.2 lneto <li><b><code>%g</code>: </b> represents all printable characters except space.</li> 9533 1.1 mbalmer 9534 1.2 lneto <li><b><code>%l</code>: </b> represents all lowercase letters.</li> 9535 1.1 mbalmer 9536 1.2 lneto <li><b><code>%p</code>: </b> represents all punctuation characters.</li> 9537 1.1 mbalmer 9538 1.2 lneto <li><b><code>%s</code>: </b> represents all space characters.</li> 9539 1.1 mbalmer 9540 1.2 lneto <li><b><code>%u</code>: </b> represents all uppercase letters.</li> 9541 1.1 mbalmer 9542 1.2 lneto <li><b><code>%w</code>: </b> represents all alphanumeric characters.</li> 9543 1.1 mbalmer 9544 1.2 lneto <li><b><code>%x</code>: </b> represents all hexadecimal digits.</li> 9545 1.1 mbalmer 9546 1.2 lneto <li><b><code>%<em>x</em></code>: </b> (where <em>x</em> is any non-alphanumeric character) 9547 1.1 mbalmer represents the character <em>x</em>. 9548 1.1 mbalmer This is the standard way to escape the magic characters. 9549 1.3 lneto Any non-alphanumeric character 9550 1.4 mbalmer (including all punctuation characters, even the non-magical) 9551 1.9 nikita can be preceded by a '<code>%</code>' to represent itself in a pattern. 9552 1.1 mbalmer </li> 9553 1.1 mbalmer 9554 1.2 lneto <li><b><code>[<em>set</em>]</code>: </b> 9555 1.1 mbalmer represents the class which is the union of all 9556 1.1 mbalmer characters in <em>set</em>. 9557 1.1 mbalmer A range of characters can be specified by 9558 1.2 lneto separating the end characters of the range, 9559 1.2 lneto in ascending order, with a '<code>-</code>'. 9560 1.1 mbalmer All classes <code>%</code><em>x</em> described above can also be used as 9561 1.1 mbalmer components in <em>set</em>. 9562 1.1 mbalmer All other characters in <em>set</em> represent themselves. 9563 1.1 mbalmer For example, <code>[%w_]</code> (or <code>[_%w]</code>) 9564 1.1 mbalmer represents all alphanumeric characters plus the underscore, 9565 1.1 mbalmer <code>[0-7]</code> represents the octal digits, 9566 1.1 mbalmer and <code>[0-7%l%-]</code> represents the octal digits plus 9567 1.1 mbalmer the lowercase letters plus the '<code>-</code>' character. 9568 1.1 mbalmer 9569 1.1 mbalmer 9570 1.1 mbalmer <p> 9571 1.6 salazar You can put a closing square bracket in a set 9572 1.6 salazar by positioning it as the first character in the set. 9573 1.8 alnsn You can put a hyphen in a set 9574 1.6 salazar by positioning it as the first or the last character in the set. 9575 1.6 salazar (You can also use an escape for both cases.) 9576 1.6 salazar 9577 1.6 salazar 9578 1.6 salazar <p> 9579 1.1 mbalmer The interaction between ranges and classes is not defined. 9580 1.1 mbalmer Therefore, patterns like <code>[%a-z]</code> or <code>[a-%%]</code> 9581 1.1 mbalmer have no meaning. 9582 1.1 mbalmer </li> 9583 1.1 mbalmer 9584 1.2 lneto <li><b><code>[^<em>set</em>]</code>: </b> 9585 1.1 mbalmer represents the complement of <em>set</em>, 9586 1.1 mbalmer where <em>set</em> is interpreted as above. 9587 1.1 mbalmer </li> 9588 1.1 mbalmer 9589 1.1 mbalmer </ul><p> 9590 1.1 mbalmer For all classes represented by single letters (<code>%a</code>, <code>%c</code>, etc.), 9591 1.1 mbalmer the corresponding uppercase letter represents the complement of the class. 9592 1.1 mbalmer For instance, <code>%S</code> represents all non-space characters. 9593 1.1 mbalmer 9594 1.1 mbalmer 9595 1.1 mbalmer <p> 9596 1.1 mbalmer The definitions of letter, space, and other character groups 9597 1.1 mbalmer depend on the current locale. 9598 1.1 mbalmer In particular, the class <code>[a-z]</code> may not be equivalent to <code>%l</code>. 9599 1.1 mbalmer 9600 1.1 mbalmer 9601 1.1 mbalmer 9602 1.1 mbalmer 9603 1.1 mbalmer 9604 1.1 mbalmer <h4>Pattern Item:</h4><p> 9605 1.1 mbalmer A <em>pattern item</em> can be 9606 1.1 mbalmer 9607 1.1 mbalmer <ul> 9608 1.1 mbalmer 9609 1.1 mbalmer <li> 9610 1.1 mbalmer a single character class, 9611 1.1 mbalmer which matches any single character in the class; 9612 1.1 mbalmer </li> 9613 1.1 mbalmer 9614 1.1 mbalmer <li> 9615 1.1 mbalmer a single character class followed by '<code>*</code>', 9616 1.9 nikita which matches sequences of zero or more characters in the class. 9617 1.1 mbalmer These repetition items will always match the longest possible sequence; 9618 1.1 mbalmer </li> 9619 1.1 mbalmer 9620 1.1 mbalmer <li> 9621 1.1 mbalmer a single character class followed by '<code>+</code>', 9622 1.9 nikita which matches sequences of one or more characters in the class. 9623 1.1 mbalmer These repetition items will always match the longest possible sequence; 9624 1.1 mbalmer </li> 9625 1.1 mbalmer 9626 1.1 mbalmer <li> 9627 1.1 mbalmer a single character class followed by '<code>-</code>', 9628 1.9 nikita which also matches sequences of zero or more characters in the class. 9629 1.1 mbalmer Unlike '<code>*</code>', 9630 1.2 lneto these repetition items will always match the shortest possible sequence; 9631 1.1 mbalmer </li> 9632 1.1 mbalmer 9633 1.1 mbalmer <li> 9634 1.1 mbalmer a single character class followed by '<code>?</code>', 9635 1.3 lneto which matches zero or one occurrence of a character in the class. 9636 1.3 lneto It always matches one occurrence if possible; 9637 1.1 mbalmer </li> 9638 1.1 mbalmer 9639 1.1 mbalmer <li> 9640 1.1 mbalmer <code>%<em>n</em></code>, for <em>n</em> between 1 and 9; 9641 1.1 mbalmer such item matches a substring equal to the <em>n</em>-th captured string 9642 1.1 mbalmer (see below); 9643 1.1 mbalmer </li> 9644 1.1 mbalmer 9645 1.1 mbalmer <li> 9646 1.1 mbalmer <code>%b<em>xy</em></code>, where <em>x</em> and <em>y</em> are two distinct characters; 9647 1.1 mbalmer such item matches strings that start with <em>x</em>, end with <em>y</em>, 9648 1.1 mbalmer and where the <em>x</em> and <em>y</em> are <em>balanced</em>. 9649 1.1 mbalmer This means that, if one reads the string from left to right, 9650 1.1 mbalmer counting <em>+1</em> for an <em>x</em> and <em>-1</em> for a <em>y</em>, 9651 1.1 mbalmer the ending <em>y</em> is the first <em>y</em> where the count reaches 0. 9652 1.1 mbalmer For instance, the item <code>%b()</code> matches expressions with 9653 1.1 mbalmer balanced parentheses. 9654 1.1 mbalmer </li> 9655 1.1 mbalmer 9656 1.2 lneto <li> 9657 1.2 lneto <code>%f[<em>set</em>]</code>, a <em>frontier pattern</em>; 9658 1.2 lneto such item matches an empty string at any position such that 9659 1.2 lneto the next character belongs to <em>set</em> 9660 1.2 lneto and the previous character does not belong to <em>set</em>. 9661 1.2 lneto The set <em>set</em> is interpreted as previously described. 9662 1.2 lneto The beginning and the end of the subject are handled as if 9663 1.2 lneto they were the character '<code>\0</code>'. 9664 1.2 lneto </li> 9665 1.2 lneto 9666 1.1 mbalmer </ul> 9667 1.1 mbalmer 9668 1.1 mbalmer 9669 1.1 mbalmer 9670 1.1 mbalmer 9671 1.1 mbalmer <h4>Pattern:</h4><p> 9672 1.1 mbalmer A <em>pattern</em> is a sequence of pattern items. 9673 1.2 lneto A caret '<code>^</code>' at the beginning of a pattern anchors the match at the 9674 1.1 mbalmer beginning of the subject string. 9675 1.1 mbalmer A '<code>$</code>' at the end of a pattern anchors the match at the 9676 1.1 mbalmer end of the subject string. 9677 1.1 mbalmer At other positions, 9678 1.1 mbalmer '<code>^</code>' and '<code>$</code>' have no special meaning and represent themselves. 9679 1.1 mbalmer 9680 1.1 mbalmer 9681 1.1 mbalmer 9682 1.1 mbalmer 9683 1.1 mbalmer 9684 1.1 mbalmer <h4>Captures:</h4><p> 9685 1.1 mbalmer A pattern can contain sub-patterns enclosed in parentheses; 9686 1.1 mbalmer they describe <em>captures</em>. 9687 1.1 mbalmer When a match succeeds, the substrings of the subject string 9688 1.1 mbalmer that match captures are stored (<em>captured</em>) for future use. 9689 1.1 mbalmer Captures are numbered according to their left parentheses. 9690 1.1 mbalmer For instance, in the pattern <code>"(a*(.)%w(%s*))"</code>, 9691 1.1 mbalmer the part of the string matching <code>"a*(.)%w(%s*)"</code> is 9692 1.9 nikita stored as the first capture, and therefore has number 1; 9693 1.1 mbalmer the character matching "<code>.</code>" is captured with number 2, 9694 1.1 mbalmer and the part matching "<code>%s*</code>" has number 3. 9695 1.1 mbalmer 9696 1.1 mbalmer 9697 1.1 mbalmer <p> 9698 1.9 nikita As a special case, the capture <code>()</code> captures 9699 1.1 mbalmer the current string position (a number). 9700 1.1 mbalmer For instance, if we apply the pattern <code>"()aa()"</code> on the 9701 1.1 mbalmer string <code>"flaaap"</code>, there will be two captures: 3 and 5. 9702 1.1 mbalmer 9703 1.1 mbalmer 9704 1.2 lneto 9705 1.2 lneto 9706 1.2 lneto 9707 1.9 nikita <h4>Multiple matches:</h4><p> 9708 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> 9709 1.9 nikita match multiple occurrences of the given pattern in the subject. 9710 1.9 nikita For these functions, 9711 1.9 nikita a new match is considered valid only 9712 1.9 nikita if it ends at least one byte after the end of the previous match. 9713 1.9 nikita In other words, the pattern machine never accepts the 9714 1.9 nikita empty string as a match immediately after another match. 9715 1.9 nikita As an example, 9716 1.9 nikita consider the results of the following code: 9717 1.9 nikita 9718 1.9 nikita <pre> 9719 1.9 nikita > string.gsub("abc", "()a*()", print); 9720 1.9 nikita --> 1 2 9721 1.9 nikita --> 3 3 9722 1.9 nikita --> 4 4 9723 1.9 nikita </pre><p> 9724 1.9 nikita The second and third results come from Lua matching an empty 9725 1.9 nikita string after '<code>b</code>' and another one after '<code>c</code>'. 9726 1.9 nikita Lua does not match an empty string after '<code>a</code>', 9727 1.9 nikita because it would end at the same position of the previous match. 9728 1.9 nikita 9729 1.9 nikita 9730 1.9 nikita 9731 1.9 nikita 9732 1.9 nikita 9733 1.2 lneto 9734 1.2 lneto 9735 1.3 lneto <h3>6.4.2 – <a name="6.4.2">Format Strings for Pack and Unpack</a></h3> 9736 1.3 lneto 9737 1.3 lneto <p> 9738 1.3 lneto The first argument to <a href="#pdf-string.pack"><code>string.pack</code></a>, 9739 1.3 lneto <a href="#pdf-string.packsize"><code>string.packsize</code></a>, and <a href="#pdf-string.unpack"><code>string.unpack</code></a> 9740 1.3 lneto is a format string, 9741 1.3 lneto which describes the layout of the structure being created or read. 9742 1.3 lneto 9743 1.3 lneto 9744 1.3 lneto <p> 9745 1.3 lneto A format string is a sequence of conversion options. 9746 1.3 lneto The conversion options are as follows: 9747 1.3 lneto 9748 1.3 lneto <ul> 9749 1.3 lneto <li><b><code><</code>: </b>sets little endian</li> 9750 1.3 lneto <li><b><code>></code>: </b>sets big endian</li> 9751 1.3 lneto <li><b><code>=</code>: </b>sets native endian</li> 9752 1.3 lneto <li><b><code>![<em>n</em>]</code>: </b>sets maximum alignment to <code>n</code> 9753 1.3 lneto (default is native alignment)</li> 9754 1.3 lneto <li><b><code>b</code>: </b>a signed byte (<code>char</code>)</li> 9755 1.3 lneto <li><b><code>B</code>: </b>an unsigned byte (<code>char</code>)</li> 9756 1.3 lneto <li><b><code>h</code>: </b>a signed <code>short</code> (native size)</li> 9757 1.3 lneto <li><b><code>H</code>: </b>an unsigned <code>short</code> (native size)</li> 9758 1.3 lneto <li><b><code>l</code>: </b>a signed <code>long</code> (native size)</li> 9759 1.3 lneto <li><b><code>L</code>: </b>an unsigned <code>long</code> (native size)</li> 9760 1.3 lneto <li><b><code>j</code>: </b>a <code>lua_Integer</code></li> 9761 1.3 lneto <li><b><code>J</code>: </b>a <code>lua_Unsigned</code></li> 9762 1.3 lneto <li><b><code>T</code>: </b>a <code>size_t</code> (native size)</li> 9763 1.3 lneto <li><b><code>i[<em>n</em>]</code>: </b>a signed <code>int</code> with <code>n</code> bytes 9764 1.3 lneto (default is native size)</li> 9765 1.3 lneto <li><b><code>I[<em>n</em>]</code>: </b>an unsigned <code>int</code> with <code>n</code> bytes 9766 1.3 lneto (default is native size)</li> 9767 1.3 lneto <li><b><code>f</code>: </b>a <code>float</code> (native size)</li> 9768 1.3 lneto <li><b><code>d</code>: </b>a <code>double</code> (native size)</li> 9769 1.3 lneto <li><b><code>n</code>: </b>a <code>lua_Number</code></li> 9770 1.3 lneto <li><b><code>c<em>n</em></code>: </b>a fixed-sized string with <code>n</code> bytes</li> 9771 1.3 lneto <li><b><code>z</code>: </b>a zero-terminated string</li> 9772 1.3 lneto <li><b><code>s[<em>n</em>]</code>: </b>a string preceded by its length 9773 1.3 lneto coded as an unsigned integer with <code>n</code> bytes 9774 1.3 lneto (default is a <code>size_t</code>)</li> 9775 1.3 lneto <li><b><code>x</code>: </b>one byte of padding</li> 9776 1.3 lneto <li><b><code>X<em>op</em></code>: </b>an empty item that aligns 9777 1.3 lneto according to option <code>op</code> 9778 1.3 lneto (which is otherwise ignored)</li> 9779 1.9 nikita <li><b>'<code> </code>': </b>(space) ignored</li> 9780 1.3 lneto </ul><p> 9781 1.3 lneto (A "<code>[<em>n</em>]</code>" means an optional integral numeral.) 9782 1.3 lneto Except for padding, spaces, and configurations 9783 1.3 lneto (options "<code>xX <=>!</code>"), 9784 1.9 nikita each option corresponds to an argument in <a href="#pdf-string.pack"><code>string.pack</code></a> 9785 1.9 nikita or a result in <a href="#pdf-string.unpack"><code>string.unpack</code></a>. 9786 1.3 lneto 9787 1.3 lneto 9788 1.3 lneto <p> 9789 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>", 9790 1.3 lneto <code>n</code> can be any integer between 1 and 16. 9791 1.3 lneto All integral options check overflows; 9792 1.3 lneto <a href="#pdf-string.pack"><code>string.pack</code></a> checks whether the given value fits in the given size; 9793 1.3 lneto <a href="#pdf-string.unpack"><code>string.unpack</code></a> checks whether the read value fits in a Lua integer. 9794 1.9 nikita For the unsigned options, 9795 1.9 nikita Lua integers are treated as unsigned values too. 9796 1.3 lneto 9797 1.3 lneto 9798 1.3 lneto <p> 9799 1.3 lneto Any format string starts as if prefixed by "<code>!1=</code>", 9800 1.3 lneto that is, 9801 1.3 lneto with maximum alignment of 1 (no alignment) 9802 1.3 lneto and native endianness. 9803 1.3 lneto 9804 1.3 lneto 9805 1.3 lneto <p> 9806 1.9 nikita Native endianness assumes that the whole system is 9807 1.9 nikita either big or little endian. 9808 1.9 nikita The packing functions will not emulate correctly the behavior 9809 1.9 nikita of mixed-endian formats. 9810 1.9 nikita 9811 1.9 nikita 9812 1.9 nikita <p> 9813 1.3 lneto Alignment works as follows: 9814 1.3 lneto For each option, 9815 1.3 lneto the format gets extra padding until the data starts 9816 1.3 lneto at an offset that is a multiple of the minimum between the 9817 1.3 lneto option size and the maximum alignment; 9818 1.3 lneto this minimum must be a power of 2. 9819 1.3 lneto Options "<code>c</code>" and "<code>z</code>" are not aligned; 9820 1.3 lneto option "<code>s</code>" follows the alignment of its starting integer. 9821 1.3 lneto 9822 1.3 lneto 9823 1.3 lneto <p> 9824 1.3 lneto All padding is filled with zeros by <a href="#pdf-string.pack"><code>string.pack</code></a> 9825 1.9 nikita and ignored by <a href="#pdf-string.unpack"><code>string.unpack</code></a>. 9826 1.3 lneto 9827 1.3 lneto 9828 1.3 lneto 9829 1.2 lneto 9830 1.2 lneto 9831 1.2 lneto 9832 1.2 lneto 9833 1.2 lneto <h2>6.5 – <a name="6.5">UTF-8 Support</a></h2> 9834 1.2 lneto 9835 1.2 lneto <p> 9836 1.2 lneto This library provides basic support for UTF-8 encoding. 9837 1.2 lneto It provides all its functions inside the table <a name="pdf-utf8"><code>utf8</code></a>. 9838 1.2 lneto This library does not provide any support for Unicode other 9839 1.2 lneto than the handling of the encoding. 9840 1.2 lneto Any operation that needs the meaning of a character, 9841 1.2 lneto such as character classification, is outside its scope. 9842 1.2 lneto 9843 1.2 lneto 9844 1.2 lneto <p> 9845 1.2 lneto Unless stated otherwise, 9846 1.2 lneto all functions that expect a byte position as a parameter 9847 1.2 lneto assume that the given position is either the start of a byte sequence 9848 1.2 lneto or one plus the length of the subject string. 9849 1.2 lneto As in the string library, 9850 1.2 lneto negative indices count from the end of the string. 9851 1.2 lneto 9852 1.2 lneto 9853 1.2 lneto <p> 9854 1.9 nikita Functions that create byte sequences 9855 1.9 nikita accept all values up to <code>0x7FFFFFFF</code>, 9856 1.9 nikita as defined in the original UTF-8 specification; 9857 1.9 nikita that implies byte sequences of up to six bytes. 9858 1.9 nikita 9859 1.9 nikita 9860 1.9 nikita <p> 9861 1.9 nikita Functions that interpret byte sequences only accept 9862 1.9 nikita valid sequences (well formed and not overlong). 9863 1.9 nikita By default, they only accept byte sequences 9864 1.9 nikita that result in valid Unicode code points, 9865 1.9 nikita rejecting values greater than <code>10FFFF</code> and surrogates. 9866 1.9 nikita A boolean argument <code>lax</code>, when available, 9867 1.9 nikita lifts these checks, 9868 1.9 nikita so that all values up to <code>0x7FFFFFFF</code> are accepted. 9869 1.9 nikita (Not well formed and overlong sequences are still rejected.) 9870 1.9 nikita 9871 1.9 nikita 9872 1.9 nikita <p> 9873 1.2 lneto <hr><h3><a name="pdf-utf8.char"><code>utf8.char (···)</code></a></h3> 9874 1.9 nikita 9875 1.9 nikita 9876 1.9 nikita <p> 9877 1.2 lneto Receives zero or more integers, 9878 1.2 lneto converts each one to its corresponding UTF-8 byte sequence 9879 1.2 lneto and returns a string with the concatenation of all these sequences. 9880 1.2 lneto 9881 1.2 lneto 9882 1.2 lneto 9883 1.2 lneto 9884 1.2 lneto <p> 9885 1.3 lneto <hr><h3><a name="pdf-utf8.charpattern"><code>utf8.charpattern</code></a></h3> 9886 1.9 nikita 9887 1.9 nikita 9888 1.9 nikita <p> 9889 1.9 nikita The pattern (a string, not a function) "<code>[\0-\x7F\xC2-\xFD][\x80-\xBF]*</code>" 9890 1.2 lneto (see <a href="#6.4.1">§6.4.1</a>), 9891 1.2 lneto which matches exactly one UTF-8 byte sequence, 9892 1.2 lneto assuming that the subject is a valid UTF-8 string. 9893 1.2 lneto 9894 1.2 lneto 9895 1.2 lneto 9896 1.2 lneto 9897 1.2 lneto <p> 9898 1.9 nikita <hr><h3><a name="pdf-utf8.codes"><code>utf8.codes (s [, lax])</code></a></h3> 9899 1.2 lneto 9900 1.2 lneto 9901 1.2 lneto <p> 9902 1.2 lneto Returns values so that the construction 9903 1.2 lneto 9904 1.2 lneto <pre> 9905 1.2 lneto for p, c in utf8.codes(s) do <em>body</em> end 9906 1.2 lneto </pre><p> 9907 1.9 nikita will iterate over all UTF-8 characters in string <code>s</code>, 9908 1.2 lneto with <code>p</code> being the position (in bytes) and <code>c</code> the code point 9909 1.2 lneto of each character. 9910 1.2 lneto It raises an error if it meets any invalid byte sequence. 9911 1.2 lneto 9912 1.2 lneto 9913 1.2 lneto 9914 1.2 lneto 9915 1.2 lneto <p> 9916 1.9 nikita <hr><h3><a name="pdf-utf8.codepoint"><code>utf8.codepoint (s [, i [, j [, lax]]])</code></a></h3> 9917 1.9 nikita 9918 1.9 nikita 9919 1.9 nikita <p> 9920 1.9 nikita Returns the code points (as integers) from all characters in <code>s</code> 9921 1.2 lneto that start between byte position <code>i</code> and <code>j</code> (both included). 9922 1.2 lneto The default for <code>i</code> is 1 and for <code>j</code> is <code>i</code>. 9923 1.2 lneto It raises an error if it meets any invalid byte sequence. 9924 1.2 lneto 9925 1.2 lneto 9926 1.2 lneto 9927 1.2 lneto 9928 1.2 lneto <p> 9929 1.9 nikita <hr><h3><a name="pdf-utf8.len"><code>utf8.len (s [, i [, j [, lax]]])</code></a></h3> 9930 1.9 nikita 9931 1.9 nikita 9932 1.9 nikita <p> 9933 1.2 lneto Returns the number of UTF-8 characters in string <code>s</code> 9934 1.3 lneto that start between positions <code>i</code> and <code>j</code> (both inclusive). 9935 1.2 lneto The default for <code>i</code> is 1 and for <code>j</code> is -1. 9936 1.2 lneto If it finds any invalid byte sequence, 9937 1.9 nikita returns <b>fail</b> plus the position of the first invalid byte. 9938 1.2 lneto 9939 1.2 lneto 9940 1.2 lneto 9941 1.2 lneto 9942 1.2 lneto <p> 9943 1.2 lneto <hr><h3><a name="pdf-utf8.offset"><code>utf8.offset (s, n [, i])</code></a></h3> 9944 1.9 nikita 9945 1.9 nikita 9946 1.9 nikita <p> 9947 1.2 lneto Returns the position (in bytes) where the encoding of the 9948 1.2 lneto <code>n</code>-th character of <code>s</code> 9949 1.2 lneto (counting from position <code>i</code>) starts. 9950 1.2 lneto A negative <code>n</code> gets characters before position <code>i</code>. 9951 1.2 lneto The default for <code>i</code> is 1 when <code>n</code> is non-negative 9952 1.2 lneto and <code>#s + 1</code> otherwise, 9953 1.2 lneto so that <code>utf8.offset(s, -n)</code> gets the offset of the 9954 1.2 lneto <code>n</code>-th character from the end of the string. 9955 1.3 lneto If the specified character is neither in the subject 9956 1.3 lneto nor right after its end, 9957 1.9 nikita the function returns <b>fail</b>. 9958 1.2 lneto 9959 1.2 lneto 9960 1.2 lneto <p> 9961 1.2 lneto As a special case, 9962 1.2 lneto when <code>n</code> is 0 the function returns the start of the encoding 9963 1.2 lneto of the character that contains the <code>i</code>-th byte of <code>s</code>. 9964 1.2 lneto 9965 1.2 lneto 9966 1.1 mbalmer <p> 9967 1.2 lneto This function assumes that <code>s</code> is a valid UTF-8 string. 9968 1.1 mbalmer 9969 1.1 mbalmer 9970 1.1 mbalmer 9971 1.1 mbalmer 9972 1.1 mbalmer 9973 1.1 mbalmer 9974 1.1 mbalmer 9975 1.2 lneto <h2>6.6 – <a name="6.6">Table Manipulation</a></h2> 9976 1.2 lneto 9977 1.2 lneto <p> 9978 1.2 lneto This library provides generic functions for table manipulation. 9979 1.2 lneto It provides all its functions inside the table <a name="pdf-table"><code>table</code></a>. 9980 1.1 mbalmer 9981 1.1 mbalmer 9982 1.2 lneto <p> 9983 1.2 lneto Remember that, whenever an operation needs the length of a table, 9984 1.7 mbalmer all caveats about the length operator apply (see <a href="#3.4.7">§3.4.7</a>). 9985 1.2 lneto All functions ignore non-numeric keys 9986 1.3 lneto in the tables given as arguments. 9987 1.1 mbalmer 9988 1.1 mbalmer 9989 1.1 mbalmer <p> 9990 1.2 lneto <hr><h3><a name="pdf-table.concat"><code>table.concat (list [, sep [, i [, j]]])</code></a></h3> 9991 1.1 mbalmer 9992 1.1 mbalmer 9993 1.1 mbalmer <p> 9994 1.2 lneto Given a list where all elements are strings or numbers, 9995 1.2 lneto returns the string <code>list[i]..sep..list[i+1] ··· sep..list[j]</code>. 9996 1.1 mbalmer The default value for <code>sep</code> is the empty string, 9997 1.1 mbalmer the default for <code>i</code> is 1, 9998 1.2 lneto and the default for <code>j</code> is <code>#list</code>. 9999 1.1 mbalmer If <code>i</code> is greater than <code>j</code>, returns the empty string. 10000 1.1 mbalmer 10001 1.1 mbalmer 10002 1.1 mbalmer 10003 1.1 mbalmer 10004 1.1 mbalmer <p> 10005 1.2 lneto <hr><h3><a name="pdf-table.insert"><code>table.insert (list, [pos,] value)</code></a></h3> 10006 1.1 mbalmer 10007 1.1 mbalmer 10008 1.1 mbalmer <p> 10009 1.2 lneto Inserts element <code>value</code> at position <code>pos</code> in <code>list</code>, 10010 1.2 lneto shifting up the elements 10011 1.2 lneto <code>list[pos], list[pos+1], ···, list[#list]</code>. 10012 1.2 lneto The default value for <code>pos</code> is <code>#list+1</code>, 10013 1.1 mbalmer so that a call <code>table.insert(t,x)</code> inserts <code>x</code> at the end 10014 1.9 nikita of the list <code>t</code>. 10015 1.1 mbalmer 10016 1.1 mbalmer 10017 1.1 mbalmer 10018 1.1 mbalmer 10019 1.1 mbalmer <p> 10020 1.3 lneto <hr><h3><a name="pdf-table.move"><code>table.move (a1, f, e, t [,a2])</code></a></h3> 10021 1.3 lneto 10022 1.3 lneto 10023 1.3 lneto <p> 10024 1.9 nikita Moves elements from the table <code>a1</code> to the table <code>a2</code>, 10025 1.6 salazar performing the equivalent to the following 10026 1.3 lneto multiple assignment: 10027 1.3 lneto <code>a2[t],··· = a1[f],···,a1[e]</code>. 10028 1.3 lneto The default for <code>a2</code> is <code>a1</code>. 10029 1.3 lneto The destination range can overlap with the source range. 10030 1.4 mbalmer The number of elements to be moved must fit in a Lua integer. 10031 1.3 lneto 10032 1.3 lneto 10033 1.6 salazar <p> 10034 1.6 salazar Returns the destination table <code>a2</code>. 10035 1.6 salazar 10036 1.6 salazar 10037 1.3 lneto 10038 1.3 lneto 10039 1.3 lneto <p> 10040 1.2 lneto <hr><h3><a name="pdf-table.pack"><code>table.pack (···)</code></a></h3> 10041 1.1 mbalmer 10042 1.1 mbalmer 10043 1.1 mbalmer <p> 10044 1.8 alnsn Returns a new table with all arguments stored into keys 1, 2, etc. 10045 1.8 alnsn and with a field "<code>n</code>" with the total number of arguments. 10046 1.9 nikita Note that the resulting table may not be a sequence, 10047 1.9 nikita if some arguments are <b>nil</b>. 10048 1.1 mbalmer 10049 1.1 mbalmer 10050 1.1 mbalmer 10051 1.1 mbalmer 10052 1.1 mbalmer <p> 10053 1.2 lneto <hr><h3><a name="pdf-table.remove"><code>table.remove (list [, pos])</code></a></h3> 10054 1.1 mbalmer 10055 1.1 mbalmer 10056 1.1 mbalmer <p> 10057 1.2 lneto Removes from <code>list</code> the element at position <code>pos</code>, 10058 1.2 lneto returning the value of the removed element. 10059 1.2 lneto When <code>pos</code> is an integer between 1 and <code>#list</code>, 10060 1.2 lneto it shifts down the elements 10061 1.2 lneto <code>list[pos+1], list[pos+2], ···, list[#list]</code> 10062 1.2 lneto and erases element <code>list[#list]</code>; 10063 1.2 lneto The index <code>pos</code> can also be 0 when <code>#list</code> is 0, 10064 1.9 nikita or <code>#list + 1</code>. 10065 1.2 lneto 10066 1.2 lneto 10067 1.2 lneto <p> 10068 1.2 lneto The default value for <code>pos</code> is <code>#list</code>, 10069 1.2 lneto so that a call <code>table.remove(l)</code> removes the last element 10070 1.9 nikita of the list <code>l</code>. 10071 1.2 lneto 10072 1.1 mbalmer 10073 1.1 mbalmer 10074 1.1 mbalmer 10075 1.2 lneto <p> 10076 1.2 lneto <hr><h3><a name="pdf-table.sort"><code>table.sort (list [, comp])</code></a></h3> 10077 1.2 lneto 10078 1.1 mbalmer 10079 1.1 mbalmer <p> 10080 1.9 nikita Sorts the list elements in a given order, <em>in-place</em>, 10081 1.2 lneto from <code>list[1]</code> to <code>list[#list]</code>. 10082 1.1 mbalmer If <code>comp</code> is given, 10083 1.2 lneto then it must be a function that receives two list elements 10084 1.2 lneto and returns true when the first element must come 10085 1.9 nikita before the second in the final order, 10086 1.9 nikita so that, after the sort, 10087 1.9 nikita <code>i <= j</code> implies <code>not comp(list[j],list[i])</code>. 10088 1.1 mbalmer If <code>comp</code> is not given, 10089 1.1 mbalmer then the standard Lua operator <code><</code> is used instead. 10090 1.1 mbalmer 10091 1.1 mbalmer 10092 1.1 mbalmer <p> 10093 1.9 nikita The <code>comp</code> function must define a consistent order; 10094 1.9 nikita more formally, the function must define a strict weak order. 10095 1.9 nikita (A weak order is similar to a total order, 10096 1.9 nikita but it can equate different elements for comparison purposes.) 10097 1.5 lneto 10098 1.5 lneto 10099 1.5 lneto <p> 10100 1.7 mbalmer The sort algorithm is not stable: 10101 1.9 nikita Different elements considered equal by the given order 10102 1.1 mbalmer may have their relative positions changed by the sort. 10103 1.1 mbalmer 10104 1.1 mbalmer 10105 1.1 mbalmer 10106 1.1 mbalmer 10107 1.2 lneto <p> 10108 1.2 lneto <hr><h3><a name="pdf-table.unpack"><code>table.unpack (list [, i [, j]])</code></a></h3> 10109 1.2 lneto 10110 1.2 lneto 10111 1.2 lneto <p> 10112 1.2 lneto Returns the elements from the given list. 10113 1.2 lneto This function is equivalent to 10114 1.2 lneto 10115 1.2 lneto <pre> 10116 1.2 lneto return list[i], list[i+1], ···, list[j] 10117 1.2 lneto </pre><p> 10118 1.2 lneto By default, <code>i</code> is 1 and <code>j</code> is <code>#list</code>. 10119 1.2 lneto 10120 1.2 lneto 10121 1.2 lneto 10122 1.1 mbalmer 10123 1.1 mbalmer 10124 1.1 mbalmer 10125 1.2 lneto 10126 1.2 lneto <h2>6.7 – <a name="6.7">Mathematical Functions</a></h2> 10127 1.1 mbalmer 10128 1.1 mbalmer <p> 10129 1.2 lneto This library provides basic mathematical functions. 10130 1.2 lneto It provides all its functions and constants inside the table <a name="pdf-math"><code>math</code></a>. 10131 1.2 lneto Functions with the annotation "<code>integer/float</code>" give 10132 1.2 lneto integer results for integer arguments 10133 1.9 nikita and float results for non-integer arguments. 10134 1.9 nikita The rounding functions 10135 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> 10136 1.2 lneto return an integer when the result fits in the range of an integer, 10137 1.3 lneto or a float otherwise. 10138 1.1 mbalmer 10139 1.1 mbalmer 10140 1.1 mbalmer <p> 10141 1.1 mbalmer <hr><h3><a name="pdf-math.abs"><code>math.abs (x)</code></a></h3> 10142 1.1 mbalmer 10143 1.1 mbalmer 10144 1.1 mbalmer <p> 10145 1.9 nikita Returns the maximum value between <code>x</code> and <code>-x</code>. (integer/float) 10146 1.1 mbalmer 10147 1.1 mbalmer 10148 1.1 mbalmer 10149 1.1 mbalmer 10150 1.1 mbalmer <p> 10151 1.1 mbalmer <hr><h3><a name="pdf-math.acos"><code>math.acos (x)</code></a></h3> 10152 1.1 mbalmer 10153 1.1 mbalmer 10154 1.1 mbalmer <p> 10155 1.1 mbalmer Returns the arc cosine of <code>x</code> (in radians). 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.asin"><code>math.asin (x)</code></a></h3> 10162 1.1 mbalmer 10163 1.1 mbalmer 10164 1.1 mbalmer <p> 10165 1.1 mbalmer Returns the arc sine of <code>x</code> (in radians). 10166 1.1 mbalmer 10167 1.1 mbalmer 10168 1.1 mbalmer 10169 1.1 mbalmer 10170 1.1 mbalmer <p> 10171 1.2 lneto <hr><h3><a name="pdf-math.atan"><code>math.atan (y [, x])</code></a></h3> 10172 1.1 mbalmer 10173 1.1 mbalmer 10174 1.1 mbalmer <p> 10175 1.10 nikita 10176 1.1 mbalmer Returns the arc tangent of <code>y/x</code> (in radians), 10177 1.10 nikita using the signs of both arguments to find the 10178 1.1 mbalmer quadrant of the result. 10179 1.9 nikita It also handles correctly the case of <code>x</code> being zero. 10180 1.1 mbalmer 10181 1.1 mbalmer 10182 1.2 lneto <p> 10183 1.2 lneto The default value for <code>x</code> is 1, 10184 1.2 lneto so that the call <code>math.atan(y)</code> 10185 1.2 lneto returns the arc tangent of <code>y</code>. 10186 1.2 lneto 10187 1.2 lneto 10188 1.1 mbalmer 10189 1.1 mbalmer 10190 1.1 mbalmer <p> 10191 1.1 mbalmer <hr><h3><a name="pdf-math.ceil"><code>math.ceil (x)</code></a></h3> 10192 1.1 mbalmer 10193 1.1 mbalmer 10194 1.1 mbalmer <p> 10195 1.9 nikita Returns the smallest integral value greater than or equal to <code>x</code>. 10196 1.1 mbalmer 10197 1.1 mbalmer 10198 1.1 mbalmer 10199 1.1 mbalmer 10200 1.1 mbalmer <p> 10201 1.1 mbalmer <hr><h3><a name="pdf-math.cos"><code>math.cos (x)</code></a></h3> 10202 1.1 mbalmer 10203 1.1 mbalmer 10204 1.1 mbalmer <p> 10205 1.1 mbalmer Returns the cosine of <code>x</code> (assumed to be in radians). 10206 1.1 mbalmer 10207 1.1 mbalmer 10208 1.1 mbalmer 10209 1.1 mbalmer 10210 1.1 mbalmer <p> 10211 1.1 mbalmer <hr><h3><a name="pdf-math.deg"><code>math.deg (x)</code></a></h3> 10212 1.1 mbalmer 10213 1.1 mbalmer 10214 1.1 mbalmer <p> 10215 1.2 lneto Converts the angle <code>x</code> from radians to degrees. 10216 1.1 mbalmer 10217 1.1 mbalmer 10218 1.1 mbalmer 10219 1.1 mbalmer 10220 1.1 mbalmer <p> 10221 1.3 lneto <hr><h3><a name="pdf-math.exp"><code>math.exp (x)</code></a></h3> 10222 1.3 lneto 10223 1.3 lneto 10224 1.3 lneto <p> 10225 1.3 lneto Returns the value <em>e<sup>x</sup></em> 10226 1.3 lneto (where <code>e</code> is the base of natural logarithms). 10227 1.3 lneto 10228 1.3 lneto 10229 1.3 lneto 10230 1.3 lneto 10231 1.3 lneto <p> 10232 1.1 mbalmer <hr><h3><a name="pdf-math.floor"><code>math.floor (x)</code></a></h3> 10233 1.1 mbalmer 10234 1.1 mbalmer 10235 1.1 mbalmer <p> 10236 1.9 nikita Returns the largest integral value less than or equal to <code>x</code>. 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.fmod"><code>math.fmod (x, y)</code></a></h3> 10243 1.1 mbalmer 10244 1.1 mbalmer 10245 1.1 mbalmer <p> 10246 1.1 mbalmer Returns the remainder of the division of <code>x</code> by <code>y</code> 10247 1.2 lneto that rounds the quotient towards zero. (integer/float) 10248 1.1 mbalmer 10249 1.1 mbalmer 10250 1.1 mbalmer 10251 1.1 mbalmer 10252 1.1 mbalmer <p> 10253 1.2 lneto <hr><h3><a name="pdf-math.huge"><code>math.huge</code></a></h3> 10254 1.1 mbalmer 10255 1.1 mbalmer 10256 1.1 mbalmer <p> 10257 1.2 lneto The float value <code>HUGE_VAL</code>, 10258 1.9 nikita a value greater than any other numeric value. 10259 1.1 mbalmer 10260 1.1 mbalmer 10261 1.1 mbalmer 10262 1.1 mbalmer 10263 1.1 mbalmer <p> 10264 1.2 lneto <hr><h3><a name="pdf-math.log"><code>math.log (x [, base])</code></a></h3> 10265 1.1 mbalmer 10266 1.1 mbalmer 10267 1.1 mbalmer <p> 10268 1.2 lneto Returns the logarithm of <code>x</code> in the given base. 10269 1.2 lneto The default for <code>base</code> is <em>e</em> 10270 1.2 lneto (so that the function returns the natural logarithm of <code>x</code>). 10271 1.1 mbalmer 10272 1.1 mbalmer 10273 1.1 mbalmer 10274 1.1 mbalmer 10275 1.1 mbalmer <p> 10276 1.2 lneto <hr><h3><a name="pdf-math.max"><code>math.max (x, ···)</code></a></h3> 10277 1.1 mbalmer 10278 1.1 mbalmer 10279 1.1 mbalmer <p> 10280 1.2 lneto Returns the argument with the maximum value, 10281 1.9 nikita according to the Lua operator <code><</code>. 10282 1.1 mbalmer 10283 1.1 mbalmer 10284 1.1 mbalmer 10285 1.1 mbalmer 10286 1.1 mbalmer <p> 10287 1.2 lneto <hr><h3><a name="pdf-math.maxinteger"><code>math.maxinteger</code></a></h3> 10288 1.2 lneto An integer with the maximum value for an integer. 10289 1.1 mbalmer 10290 1.1 mbalmer 10291 1.1 mbalmer 10292 1.1 mbalmer 10293 1.1 mbalmer <p> 10294 1.2 lneto <hr><h3><a name="pdf-math.min"><code>math.min (x, ···)</code></a></h3> 10295 1.1 mbalmer 10296 1.1 mbalmer 10297 1.1 mbalmer <p> 10298 1.2 lneto Returns the argument with the minimum value, 10299 1.9 nikita according to the Lua operator <code><</code>. 10300 1.1 mbalmer 10301 1.1 mbalmer 10302 1.1 mbalmer 10303 1.1 mbalmer 10304 1.1 mbalmer <p> 10305 1.2 lneto <hr><h3><a name="pdf-math.mininteger"><code>math.mininteger</code></a></h3> 10306 1.2 lneto An integer with the minimum value for an integer. 10307 1.1 mbalmer 10308 1.1 mbalmer 10309 1.1 mbalmer 10310 1.1 mbalmer 10311 1.1 mbalmer <p> 10312 1.1 mbalmer <hr><h3><a name="pdf-math.modf"><code>math.modf (x)</code></a></h3> 10313 1.1 mbalmer 10314 1.1 mbalmer 10315 1.1 mbalmer <p> 10316 1.2 lneto Returns the integral part of <code>x</code> and the fractional part of <code>x</code>. 10317 1.2 lneto Its second result is always a float. 10318 1.1 mbalmer 10319 1.1 mbalmer 10320 1.1 mbalmer 10321 1.1 mbalmer 10322 1.1 mbalmer <p> 10323 1.1 mbalmer <hr><h3><a name="pdf-math.pi"><code>math.pi</code></a></h3> 10324 1.1 mbalmer 10325 1.1 mbalmer 10326 1.1 mbalmer <p> 10327 1.2 lneto The value of <em>π</em>. 10328 1.1 mbalmer 10329 1.1 mbalmer 10330 1.1 mbalmer 10331 1.1 mbalmer 10332 1.1 mbalmer <p> 10333 1.1 mbalmer <hr><h3><a name="pdf-math.rad"><code>math.rad (x)</code></a></h3> 10334 1.1 mbalmer 10335 1.1 mbalmer 10336 1.1 mbalmer <p> 10337 1.2 lneto Converts the angle <code>x</code> from degrees to radians. 10338 1.1 mbalmer 10339 1.1 mbalmer 10340 1.1 mbalmer 10341 1.1 mbalmer 10342 1.1 mbalmer <p> 10343 1.1 mbalmer <hr><h3><a name="pdf-math.random"><code>math.random ([m [, n]])</code></a></h3> 10344 1.1 mbalmer 10345 1.1 mbalmer 10346 1.1 mbalmer <p> 10347 1.2 lneto When called without arguments, 10348 1.2 lneto returns a pseudo-random float with uniform distribution 10349 1.2 lneto in the range <em>[0,1)</em>. 10350 1.2 lneto When called with two integers <code>m</code> and <code>n</code>, 10351 1.2 lneto <code>math.random</code> returns a pseudo-random integer 10352 1.2 lneto with uniform distribution in the range <em>[m, n]</em>. 10353 1.9 nikita The call <code>math.random(n)</code>, for a positive <code>n</code>, 10354 1.9 nikita is equivalent to <code>math.random(1,n)</code>. 10355 1.9 nikita The call <code>math.random(0)</code> produces an integer with 10356 1.9 nikita all bits (pseudo)random. 10357 1.9 nikita 10358 1.9 nikita 10359 1.9 nikita <p> 10360 1.9 nikita This function uses the <code>xoshiro256**</code> algorithm to produce 10361 1.9 nikita pseudo-random 64-bit integers, 10362 1.9 nikita which are the results of calls with argument 0. 10363 1.9 nikita Other results (ranges and floats) 10364 1.9 nikita are unbiased extracted from these integers. 10365 1.1 mbalmer 10366 1.1 mbalmer 10367 1.1 mbalmer <p> 10368 1.9 nikita Lua initializes its pseudo-random generator with the equivalent of 10369 1.9 nikita a call to <a href="#pdf-math.randomseed"><code>math.randomseed</code></a> with no arguments, 10370 1.9 nikita so that <code>math.random</code> should generate 10371 1.9 nikita different sequences of results each time the program runs. 10372 1.1 mbalmer 10373 1.1 mbalmer 10374 1.1 mbalmer 10375 1.1 mbalmer 10376 1.1 mbalmer <p> 10377 1.9 nikita <hr><h3><a name="pdf-math.randomseed"><code>math.randomseed ([x [, y]])</code></a></h3> 10378 1.1 mbalmer 10379 1.1 mbalmer 10380 1.1 mbalmer <p> 10381 1.9 nikita When called with at least one argument, 10382 1.9 nikita the integer parameters <code>x</code> and <code>y</code> are 10383 1.9 nikita joined into a 128-bit <em>seed</em> that 10384 1.9 nikita is used to reinitialize the pseudo-random generator; 10385 1.1 mbalmer equal seeds produce equal sequences of numbers. 10386 1.9 nikita The default for <code>y</code> is zero. 10387 1.9 nikita 10388 1.9 nikita 10389 1.9 nikita <p> 10390 1.9 nikita When called with no arguments, 10391 1.9 nikita Lua generates a seed with 10392 1.9 nikita a weak attempt for randomness. 10393 1.9 nikita 10394 1.9 nikita 10395 1.9 nikita <p> 10396 1.9 nikita This function returns the two seed components 10397 1.9 nikita that were effectively used, 10398 1.9 nikita so that setting them again repeats the sequence. 10399 1.9 nikita 10400 1.9 nikita 10401 1.9 nikita <p> 10402 1.9 nikita To ensure a required level of randomness to the initial state 10403 1.9 nikita (or contrarily, to have a deterministic sequence, 10404 1.9 nikita for instance when debugging a program), 10405 1.9 nikita you should call <a href="#pdf-math.randomseed"><code>math.randomseed</code></a> with explicit arguments. 10406 1.1 mbalmer 10407 1.1 mbalmer 10408 1.1 mbalmer 10409 1.1 mbalmer 10410 1.1 mbalmer <p> 10411 1.1 mbalmer <hr><h3><a name="pdf-math.sin"><code>math.sin (x)</code></a></h3> 10412 1.1 mbalmer 10413 1.1 mbalmer 10414 1.1 mbalmer <p> 10415 1.1 mbalmer Returns the sine of <code>x</code> (assumed to be in radians). 10416 1.1 mbalmer 10417 1.1 mbalmer 10418 1.1 mbalmer 10419 1.1 mbalmer 10420 1.1 mbalmer <p> 10421 1.1 mbalmer <hr><h3><a name="pdf-math.sqrt"><code>math.sqrt (x)</code></a></h3> 10422 1.1 mbalmer 10423 1.1 mbalmer 10424 1.1 mbalmer <p> 10425 1.1 mbalmer Returns the square root of <code>x</code>. 10426 1.1 mbalmer (You can also use the expression <code>x^0.5</code> to compute this value.) 10427 1.1 mbalmer 10428 1.1 mbalmer 10429 1.1 mbalmer 10430 1.1 mbalmer 10431 1.1 mbalmer <p> 10432 1.1 mbalmer <hr><h3><a name="pdf-math.tan"><code>math.tan (x)</code></a></h3> 10433 1.1 mbalmer 10434 1.1 mbalmer 10435 1.1 mbalmer <p> 10436 1.1 mbalmer Returns the tangent of <code>x</code> (assumed to be in radians). 10437 1.1 mbalmer 10438 1.1 mbalmer 10439 1.1 mbalmer 10440 1.1 mbalmer 10441 1.1 mbalmer <p> 10442 1.3 lneto <hr><h3><a name="pdf-math.tointeger"><code>math.tointeger (x)</code></a></h3> 10443 1.3 lneto 10444 1.3 lneto 10445 1.3 lneto <p> 10446 1.3 lneto If the value <code>x</code> is convertible to an integer, 10447 1.3 lneto returns that integer. 10448 1.9 nikita Otherwise, returns <b>fail</b>. 10449 1.3 lneto 10450 1.3 lneto 10451 1.3 lneto 10452 1.3 lneto 10453 1.3 lneto <p> 10454 1.2 lneto <hr><h3><a name="pdf-math.type"><code>math.type (x)</code></a></h3> 10455 1.1 mbalmer 10456 1.1 mbalmer 10457 1.1 mbalmer <p> 10458 1.2 lneto Returns "<code>integer</code>" if <code>x</code> is an integer, 10459 1.2 lneto "<code>float</code>" if it is a float, 10460 1.9 nikita or <b>fail</b> if <code>x</code> is not a number. 10461 1.1 mbalmer 10462 1.1 mbalmer 10463 1.1 mbalmer 10464 1.1 mbalmer 10465 1.3 lneto <p> 10466 1.3 lneto <hr><h3><a name="pdf-math.ult"><code>math.ult (m, n)</code></a></h3> 10467 1.3 lneto 10468 1.3 lneto 10469 1.3 lneto <p> 10470 1.3 lneto Returns a boolean, 10471 1.9 nikita <b>true</b> if and only if integer <code>m</code> is below integer <code>n</code> when 10472 1.3 lneto they are compared as unsigned integers. 10473 1.3 lneto 10474 1.3 lneto 10475 1.3 lneto 10476 1.3 lneto 10477 1.1 mbalmer 10478 1.1 mbalmer 10479 1.1 mbalmer 10480 1.2 lneto <h2>6.8 – <a name="6.8">Input and Output Facilities</a></h2> 10481 1.1 mbalmer 10482 1.1 mbalmer <p> 10483 1.1 mbalmer The I/O library provides two different styles for file manipulation. 10484 1.2 lneto The first one uses implicit file handles; 10485 1.1 mbalmer that is, there are operations to set a default input file and a 10486 1.1 mbalmer default output file, 10487 1.9 nikita and all input/output operations are done over these default files. 10488 1.2 lneto The second style uses explicit file handles. 10489 1.1 mbalmer 10490 1.1 mbalmer 10491 1.1 mbalmer <p> 10492 1.2 lneto When using implicit file handles, 10493 1.1 mbalmer all operations are supplied by table <a name="pdf-io"><code>io</code></a>. 10494 1.2 lneto When using explicit file handles, 10495 1.2 lneto the operation <a href="#pdf-io.open"><code>io.open</code></a> returns a file handle 10496 1.2 lneto and then all operations are supplied as methods of the file handle. 10497 1.1 mbalmer 10498 1.1 mbalmer 10499 1.1 mbalmer <p> 10500 1.9 nikita The metatable for file handles provides metamethods 10501 1.9 nikita for <code>__gc</code> and <code>__close</code> that try 10502 1.9 nikita to close the file when called. 10503 1.9 nikita 10504 1.9 nikita 10505 1.9 nikita <p> 10506 1.1 mbalmer The table <code>io</code> also provides 10507 1.2 lneto three predefined file handles with their usual meanings from C: 10508 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>. 10509 1.1 mbalmer The I/O library never closes these files. 10510 1.1 mbalmer 10511 1.1 mbalmer 10512 1.1 mbalmer <p> 10513 1.1 mbalmer Unless otherwise stated, 10514 1.9 nikita all I/O functions return <b>fail</b> on failure, 10515 1.9 nikita plus an error message as a second result and 10516 1.9 nikita a system-dependent error code as a third result, 10517 1.9 nikita and some non-false value on success. 10518 1.9 nikita On non-POSIX systems, 10519 1.2 lneto the computation of the error message and error code 10520 1.2 lneto in case of errors 10521 1.2 lneto may be not thread safe, 10522 1.2 lneto because they rely on the global C variable <code>errno</code>. 10523 1.1 mbalmer 10524 1.1 mbalmer 10525 1.1 mbalmer <p> 10526 1.1 mbalmer <hr><h3><a name="pdf-io.close"><code>io.close ([file])</code></a></h3> 10527 1.1 mbalmer 10528 1.1 mbalmer 10529 1.1 mbalmer <p> 10530 1.1 mbalmer Equivalent to <code>file:close()</code>. 10531 1.1 mbalmer Without a <code>file</code>, closes the default output file. 10532 1.1 mbalmer 10533 1.1 mbalmer 10534 1.1 mbalmer 10535 1.1 mbalmer 10536 1.1 mbalmer <p> 10537 1.1 mbalmer <hr><h3><a name="pdf-io.flush"><code>io.flush ()</code></a></h3> 10538 1.1 mbalmer 10539 1.1 mbalmer 10540 1.1 mbalmer <p> 10541 1.2 lneto Equivalent to <code>io.output():flush()</code>. 10542 1.1 mbalmer 10543 1.1 mbalmer 10544 1.1 mbalmer 10545 1.1 mbalmer 10546 1.1 mbalmer <p> 10547 1.1 mbalmer <hr><h3><a name="pdf-io.input"><code>io.input ([file])</code></a></h3> 10548 1.1 mbalmer 10549 1.1 mbalmer 10550 1.1 mbalmer <p> 10551 1.1 mbalmer When called with a file name, it opens the named file (in text mode), 10552 1.1 mbalmer and sets its handle as the default input file. 10553 1.1 mbalmer When called with a file handle, 10554 1.1 mbalmer it simply sets this file handle as the default input file. 10555 1.8 alnsn When called without arguments, 10556 1.1 mbalmer it returns the current default input file. 10557 1.1 mbalmer 10558 1.1 mbalmer 10559 1.1 mbalmer <p> 10560 1.1 mbalmer In case of errors this function raises the error, 10561 1.1 mbalmer instead of returning an error code. 10562 1.1 mbalmer 10563 1.1 mbalmer 10564 1.1 mbalmer 10565 1.1 mbalmer 10566 1.1 mbalmer <p> 10567 1.5 lneto <hr><h3><a name="pdf-io.lines"><code>io.lines ([filename, ···])</code></a></h3> 10568 1.1 mbalmer 10569 1.1 mbalmer 10570 1.1 mbalmer <p> 10571 1.1 mbalmer Opens the given file name in read mode 10572 1.2 lneto and returns an iterator function that 10573 1.2 lneto works like <code>file:lines(···)</code> over the opened file. 10574 1.9 nikita When the iterator function fails to read any value, 10575 1.9 nikita it automatically closes the file. 10576 1.9 nikita Besides the iterator function, 10577 1.9 nikita <code>io.lines</code> returns three other values: 10578 1.9 nikita two <b>nil</b> values as placeholders, 10579 1.9 nikita plus the created file handle. 10580 1.9 nikita Therefore, when used in a generic <b>for</b> loop, 10581 1.9 nikita the file is closed also if the loop is interrupted by an 10582 1.9 nikita error or a <b>break</b>. 10583 1.1 mbalmer 10584 1.1 mbalmer 10585 1.1 mbalmer <p> 10586 1.1 mbalmer The call <code>io.lines()</code> (with no file name) is equivalent 10587 1.9 nikita to <code>io.input():lines("l")</code>; 10588 1.1 mbalmer that is, it iterates over the lines of the default input file. 10589 1.8 alnsn In this case, the iterator does not close the file when the loop ends. 10590 1.1 mbalmer 10591 1.1 mbalmer 10592 1.2 lneto <p> 10593 1.9 nikita In case of errors opening the file, 10594 1.9 nikita this function raises the error, 10595 1.2 lneto instead of returning an error code. 10596 1.2 lneto 10597 1.2 lneto 10598 1.1 mbalmer 10599 1.1 mbalmer 10600 1.1 mbalmer <p> 10601 1.1 mbalmer <hr><h3><a name="pdf-io.open"><code>io.open (filename [, mode])</code></a></h3> 10602 1.1 mbalmer 10603 1.1 mbalmer 10604 1.1 mbalmer <p> 10605 1.1 mbalmer This function opens a file, 10606 1.1 mbalmer in the mode specified in the string <code>mode</code>. 10607 1.6 salazar In case of success, 10608 1.6 salazar it returns a new file handle. 10609 1.1 mbalmer 10610 1.1 mbalmer 10611 1.1 mbalmer <p> 10612 1.1 mbalmer The <code>mode</code> string can be any of the following: 10613 1.1 mbalmer 10614 1.1 mbalmer <ul> 10615 1.2 lneto <li><b>"<code>r</code>": </b> read mode (the default);</li> 10616 1.2 lneto <li><b>"<code>w</code>": </b> write mode;</li> 10617 1.2 lneto <li><b>"<code>a</code>": </b> append mode;</li> 10618 1.2 lneto <li><b>"<code>r+</code>": </b> update mode, all previous data is preserved;</li> 10619 1.2 lneto <li><b>"<code>w+</code>": </b> update mode, all previous data is erased;</li> 10620 1.2 lneto <li><b>"<code>a+</code>": </b> append update mode, previous data is preserved, 10621 1.1 mbalmer writing is only allowed at the end of file.</li> 10622 1.1 mbalmer </ul><p> 10623 1.1 mbalmer The <code>mode</code> string can also have a '<code>b</code>' at the end, 10624 1.1 mbalmer which is needed in some systems to open the file in binary mode. 10625 1.1 mbalmer 10626 1.1 mbalmer 10627 1.1 mbalmer 10628 1.1 mbalmer 10629 1.1 mbalmer <p> 10630 1.1 mbalmer <hr><h3><a name="pdf-io.output"><code>io.output ([file])</code></a></h3> 10631 1.1 mbalmer 10632 1.1 mbalmer 10633 1.1 mbalmer <p> 10634 1.1 mbalmer Similar to <a href="#pdf-io.input"><code>io.input</code></a>, but operates over the default output file. 10635 1.1 mbalmer 10636 1.1 mbalmer 10637 1.1 mbalmer 10638 1.1 mbalmer 10639 1.1 mbalmer <p> 10640 1.1 mbalmer <hr><h3><a name="pdf-io.popen"><code>io.popen (prog [, mode])</code></a></h3> 10641 1.1 mbalmer 10642 1.1 mbalmer 10643 1.1 mbalmer <p> 10644 1.2 lneto This function is system dependent and is not available 10645 1.2 lneto on all platforms. 10646 1.2 lneto 10647 1.2 lneto 10648 1.2 lneto <p> 10649 1.9 nikita Starts the program <code>prog</code> in a separated process and returns 10650 1.1 mbalmer a file handle that you can use to read data from this program 10651 1.1 mbalmer (if <code>mode</code> is <code>"r"</code>, the default) 10652 1.1 mbalmer or to write data to this program 10653 1.1 mbalmer (if <code>mode</code> is <code>"w"</code>). 10654 1.1 mbalmer 10655 1.1 mbalmer 10656 1.1 mbalmer 10657 1.1 mbalmer 10658 1.1 mbalmer <p> 10659 1.1 mbalmer <hr><h3><a name="pdf-io.read"><code>io.read (···)</code></a></h3> 10660 1.1 mbalmer 10661 1.1 mbalmer 10662 1.1 mbalmer <p> 10663 1.2 lneto Equivalent to <code>io.input():read(···)</code>. 10664 1.1 mbalmer 10665 1.1 mbalmer 10666 1.1 mbalmer 10667 1.1 mbalmer 10668 1.1 mbalmer <p> 10669 1.1 mbalmer <hr><h3><a name="pdf-io.tmpfile"><code>io.tmpfile ()</code></a></h3> 10670 1.1 mbalmer 10671 1.1 mbalmer 10672 1.1 mbalmer <p> 10673 1.6 salazar In case of success, 10674 1.6 salazar returns a handle for a temporary file. 10675 1.1 mbalmer This file is opened in update mode 10676 1.1 mbalmer and it is automatically removed when the program ends. 10677 1.1 mbalmer 10678 1.1 mbalmer 10679 1.1 mbalmer 10680 1.1 mbalmer 10681 1.1 mbalmer <p> 10682 1.1 mbalmer <hr><h3><a name="pdf-io.type"><code>io.type (obj)</code></a></h3> 10683 1.1 mbalmer 10684 1.1 mbalmer 10685 1.1 mbalmer <p> 10686 1.1 mbalmer Checks whether <code>obj</code> is a valid file handle. 10687 1.1 mbalmer Returns the string <code>"file"</code> if <code>obj</code> is an open file handle, 10688 1.1 mbalmer <code>"closed file"</code> if <code>obj</code> is a closed file handle, 10689 1.9 nikita or <b>fail</b> if <code>obj</code> is not a file handle. 10690 1.1 mbalmer 10691 1.1 mbalmer 10692 1.1 mbalmer 10693 1.1 mbalmer 10694 1.1 mbalmer <p> 10695 1.1 mbalmer <hr><h3><a name="pdf-io.write"><code>io.write (···)</code></a></h3> 10696 1.1 mbalmer 10697 1.1 mbalmer 10698 1.1 mbalmer <p> 10699 1.2 lneto Equivalent to <code>io.output():write(···)</code>. 10700 1.1 mbalmer 10701 1.1 mbalmer 10702 1.1 mbalmer 10703 1.1 mbalmer 10704 1.1 mbalmer <p> 10705 1.1 mbalmer <hr><h3><a name="pdf-file:close"><code>file:close ()</code></a></h3> 10706 1.1 mbalmer 10707 1.1 mbalmer 10708 1.1 mbalmer <p> 10709 1.1 mbalmer Closes <code>file</code>. 10710 1.1 mbalmer Note that files are automatically closed when 10711 1.1 mbalmer their handles are garbage collected, 10712 1.1 mbalmer but that takes an unpredictable amount of time to happen. 10713 1.1 mbalmer 10714 1.1 mbalmer 10715 1.2 lneto <p> 10716 1.2 lneto When closing a file handle created with <a href="#pdf-io.popen"><code>io.popen</code></a>, 10717 1.2 lneto <a href="#pdf-file:close"><code>file:close</code></a> returns the same values 10718 1.2 lneto returned by <a href="#pdf-os.execute"><code>os.execute</code></a>. 10719 1.2 lneto 10720 1.2 lneto 10721 1.1 mbalmer 10722 1.1 mbalmer 10723 1.1 mbalmer <p> 10724 1.1 mbalmer <hr><h3><a name="pdf-file:flush"><code>file:flush ()</code></a></h3> 10725 1.1 mbalmer 10726 1.1 mbalmer 10727 1.1 mbalmer <p> 10728 1.1 mbalmer Saves any written data to <code>file</code>. 10729 1.1 mbalmer 10730 1.1 mbalmer 10731 1.1 mbalmer 10732 1.1 mbalmer 10733 1.1 mbalmer <p> 10734 1.2 lneto <hr><h3><a name="pdf-file:lines"><code>file:lines (···)</code></a></h3> 10735 1.1 mbalmer 10736 1.1 mbalmer 10737 1.1 mbalmer <p> 10738 1.1 mbalmer Returns an iterator function that, 10739 1.1 mbalmer each time it is called, 10740 1.2 lneto reads the file according to the given formats. 10741 1.2 lneto When no format is given, 10742 1.2 lneto uses "<code>l</code>" as a default. 10743 1.2 lneto As an example, the construction 10744 1.1 mbalmer 10745 1.1 mbalmer <pre> 10746 1.2 lneto for c in file:lines(1) do <em>body</em> end 10747 1.2 lneto </pre><p> 10748 1.2 lneto will iterate over all characters of the file, 10749 1.2 lneto starting at the current position. 10750 1.2 lneto Unlike <a href="#pdf-io.lines"><code>io.lines</code></a>, this function does not close the file 10751 1.2 lneto when the loop ends. 10752 1.2 lneto 10753 1.2 lneto 10754 1.1 mbalmer 10755 1.1 mbalmer 10756 1.1 mbalmer <p> 10757 1.1 mbalmer <hr><h3><a name="pdf-file:read"><code>file:read (···)</code></a></h3> 10758 1.1 mbalmer 10759 1.1 mbalmer 10760 1.1 mbalmer <p> 10761 1.1 mbalmer Reads the file <code>file</code>, 10762 1.1 mbalmer according to the given formats, which specify what to read. 10763 1.1 mbalmer For each format, 10764 1.2 lneto the function returns a string or a number with the characters read, 10765 1.9 nikita or <b>fail</b> if it cannot read data with the specified format. 10766 1.3 lneto (In this latter case, 10767 1.3 lneto the function does not read subsequent formats.) 10768 1.9 nikita When called without arguments, 10769 1.2 lneto it uses a default format that reads the next line 10770 1.1 mbalmer (see below). 10771 1.1 mbalmer 10772 1.1 mbalmer 10773 1.1 mbalmer <p> 10774 1.1 mbalmer The available formats are 10775 1.1 mbalmer 10776 1.1 mbalmer <ul> 10777 1.1 mbalmer 10778 1.2 lneto <li><b>"<code>n</code>": </b> 10779 1.2 lneto reads a numeral and returns it as a float or an integer, 10780 1.2 lneto following the lexical conventions of Lua. 10781 1.9 nikita (The numeral may have leading whitespaces and a sign.) 10782 1.2 lneto This format always reads the longest input sequence that 10783 1.4 mbalmer is a valid prefix for a numeral; 10784 1.4 mbalmer if that prefix does not form a valid numeral 10785 1.9 nikita (e.g., an empty string, "<code>0x</code>", or "<code>3.4e-</code>") 10786 1.9 nikita or it is too long (more than 200 characters), 10787 1.9 nikita it is discarded and the format returns <b>fail</b>. 10788 1.2 lneto </li> 10789 1.2 lneto 10790 1.2 lneto <li><b>"<code>a</code>": </b> 10791 1.1 mbalmer reads the whole file, starting at the current position. 10792 1.9 nikita On end of file, it returns the empty string; 10793 1.9 nikita this format never fails. 10794 1.1 mbalmer </li> 10795 1.1 mbalmer 10796 1.2 lneto <li><b>"<code>l</code>": </b> 10797 1.2 lneto reads the next line skipping the end of line, 10798 1.9 nikita returning <b>fail</b> on end of file. 10799 1.1 mbalmer This is the default format. 10800 1.1 mbalmer </li> 10801 1.1 mbalmer 10802 1.2 lneto <li><b>"<code>L</code>": </b> 10803 1.2 lneto reads the next line keeping the end-of-line character (if present), 10804 1.9 nikita returning <b>fail</b> on end of file. 10805 1.2 lneto </li> 10806 1.2 lneto 10807 1.2 lneto <li><b><em>number</em>: </b> 10808 1.2 lneto reads a string with up to this number of bytes, 10809 1.9 nikita returning <b>fail</b> on end of file. 10810 1.2 lneto If <code>number</code> is zero, 10811 1.1 mbalmer it reads nothing and returns an empty string, 10812 1.9 nikita or <b>fail</b> on end of file. 10813 1.1 mbalmer </li> 10814 1.1 mbalmer 10815 1.2 lneto </ul><p> 10816 1.2 lneto The formats "<code>l</code>" and "<code>L</code>" should be used only for text files. 10817 1.2 lneto 10818 1.1 mbalmer 10819 1.1 mbalmer 10820 1.1 mbalmer 10821 1.1 mbalmer <p> 10822 1.2 lneto <hr><h3><a name="pdf-file:seek"><code>file:seek ([whence [, offset]])</code></a></h3> 10823 1.1 mbalmer 10824 1.1 mbalmer 10825 1.1 mbalmer <p> 10826 1.1 mbalmer Sets and gets the file position, 10827 1.1 mbalmer measured from the beginning of the file, 10828 1.1 mbalmer to the position given by <code>offset</code> plus a base 10829 1.1 mbalmer specified by the string <code>whence</code>, as follows: 10830 1.1 mbalmer 10831 1.1 mbalmer <ul> 10832 1.2 lneto <li><b>"<code>set</code>": </b> base is position 0 (beginning of the file);</li> 10833 1.2 lneto <li><b>"<code>cur</code>": </b> base is current position;</li> 10834 1.2 lneto <li><b>"<code>end</code>": </b> base is end of file;</li> 10835 1.1 mbalmer </ul><p> 10836 1.2 lneto In case of success, <code>seek</code> returns the final file position, 10837 1.1 mbalmer measured in bytes from the beginning of the file. 10838 1.9 nikita If <code>seek</code> fails, it returns <b>fail</b>, 10839 1.1 mbalmer plus a string describing the error. 10840 1.1 mbalmer 10841 1.1 mbalmer 10842 1.1 mbalmer <p> 10843 1.1 mbalmer The default value for <code>whence</code> is <code>"cur"</code>, 10844 1.1 mbalmer and for <code>offset</code> is 0. 10845 1.1 mbalmer Therefore, the call <code>file:seek()</code> returns the current 10846 1.1 mbalmer file position, without changing it; 10847 1.1 mbalmer the call <code>file:seek("set")</code> sets the position to the 10848 1.1 mbalmer beginning of the file (and returns 0); 10849 1.1 mbalmer and the call <code>file:seek("end")</code> sets the position to the 10850 1.1 mbalmer end of the file, and returns its size. 10851 1.1 mbalmer 10852 1.1 mbalmer 10853 1.1 mbalmer 10854 1.1 mbalmer 10855 1.1 mbalmer <p> 10856 1.1 mbalmer <hr><h3><a name="pdf-file:setvbuf"><code>file:setvbuf (mode [, size])</code></a></h3> 10857 1.1 mbalmer 10858 1.1 mbalmer 10859 1.1 mbalmer <p> 10860 1.9 nikita Sets the buffering mode for a file. 10861 1.1 mbalmer There are three available modes: 10862 1.1 mbalmer 10863 1.1 mbalmer <ul> 10864 1.9 nikita <li><b>"<code>no</code>": </b> no buffering.</li> 10865 1.9 nikita <li><b>"<code>full</code>": </b> full buffering.</li> 10866 1.9 nikita <li><b>"<code>line</code>": </b> line buffering.</li> 10867 1.9 nikita </ul> 10868 1.1 mbalmer 10869 1.9 nikita <p> 10870 1.9 nikita For the last two cases, 10871 1.9 nikita <code>size</code> is a hint for the size of the buffer, in bytes. 10872 1.9 nikita The default is an appropriate size. 10873 1.1 mbalmer 10874 1.1 mbalmer 10875 1.9 nikita <p> 10876 1.9 nikita The specific behavior of each mode is non portable; 10877 1.9 nikita check the underlying ISO C function <code>setvbuf</code> in your platform for 10878 1.9 nikita more details. 10879 1.1 mbalmer 10880 1.1 mbalmer 10881 1.1 mbalmer 10882 1.1 mbalmer 10883 1.1 mbalmer <p> 10884 1.1 mbalmer <hr><h3><a name="pdf-file:write"><code>file:write (···)</code></a></h3> 10885 1.1 mbalmer 10886 1.1 mbalmer 10887 1.1 mbalmer <p> 10888 1.2 lneto Writes the value of each of its arguments to <code>file</code>. 10889 1.1 mbalmer The arguments must be strings or numbers. 10890 1.2 lneto 10891 1.2 lneto 10892 1.2 lneto <p> 10893 1.2 lneto In case of success, this function returns <code>file</code>. 10894 1.1 mbalmer 10895 1.1 mbalmer 10896 1.1 mbalmer 10897 1.1 mbalmer 10898 1.1 mbalmer 10899 1.1 mbalmer 10900 1.1 mbalmer 10901 1.2 lneto <h2>6.9 – <a name="6.9">Operating System Facilities</a></h2> 10902 1.1 mbalmer 10903 1.1 mbalmer <p> 10904 1.1 mbalmer This library is implemented through table <a name="pdf-os"><code>os</code></a>. 10905 1.1 mbalmer 10906 1.1 mbalmer 10907 1.1 mbalmer <p> 10908 1.1 mbalmer <hr><h3><a name="pdf-os.clock"><code>os.clock ()</code></a></h3> 10909 1.1 mbalmer 10910 1.1 mbalmer 10911 1.1 mbalmer <p> 10912 1.1 mbalmer Returns an approximation of the amount in seconds of CPU time 10913 1.9 nikita used by the program, 10914 1.9 nikita as returned by the underlying ISO C function <code>clock</code>. 10915 1.1 mbalmer 10916 1.1 mbalmer 10917 1.1 mbalmer 10918 1.1 mbalmer 10919 1.1 mbalmer <p> 10920 1.1 mbalmer <hr><h3><a name="pdf-os.date"><code>os.date ([format [, time]])</code></a></h3> 10921 1.1 mbalmer 10922 1.1 mbalmer 10923 1.1 mbalmer <p> 10924 1.1 mbalmer Returns a string or a table containing date and time, 10925 1.1 mbalmer formatted according to the given string <code>format</code>. 10926 1.1 mbalmer 10927 1.1 mbalmer 10928 1.1 mbalmer <p> 10929 1.1 mbalmer If the <code>time</code> argument is present, 10930 1.1 mbalmer this is the time to be formatted 10931 1.1 mbalmer (see the <a href="#pdf-os.time"><code>os.time</code></a> function for a description of this value). 10932 1.1 mbalmer Otherwise, <code>date</code> formats the current time. 10933 1.1 mbalmer 10934 1.1 mbalmer 10935 1.1 mbalmer <p> 10936 1.1 mbalmer If <code>format</code> starts with '<code>!</code>', 10937 1.1 mbalmer then the date is formatted in Coordinated Universal Time. 10938 1.1 mbalmer After this optional character, 10939 1.1 mbalmer if <code>format</code> is the string "<code>*t</code>", 10940 1.1 mbalmer then <code>date</code> returns a table with the following fields: 10941 1.5 lneto <code>year</code>, <code>month</code> (1–12), <code>day</code> (1–31), 10942 1.9 nikita <code>hour</code> (0–23), <code>min</code> (0–59), 10943 1.9 nikita <code>sec</code> (0–61, due to leap seconds), 10944 1.6 salazar <code>wday</code> (weekday, 1–7, Sunday is 1), 10945 1.6 salazar <code>yday</code> (day of the year, 1–366), 10946 1.1 mbalmer and <code>isdst</code> (daylight saving flag, a boolean). 10947 1.2 lneto This last field may be absent 10948 1.2 lneto if the information is not available. 10949 1.1 mbalmer 10950 1.1 mbalmer 10951 1.1 mbalmer <p> 10952 1.1 mbalmer If <code>format</code> is not "<code>*t</code>", 10953 1.1 mbalmer then <code>date</code> returns the date as a string, 10954 1.3 lneto formatted according to the same rules as the ISO C function <code>strftime</code>. 10955 1.1 mbalmer 10956 1.1 mbalmer 10957 1.1 mbalmer <p> 10958 1.9 nikita If <code>format</code> is absent, it defaults to "<code>%c</code>", 10959 1.9 nikita which gives a human-readable date and time representation 10960 1.9 nikita using the current locale. 10961 1.1 mbalmer 10962 1.1 mbalmer 10963 1.2 lneto <p> 10964 1.9 nikita On non-POSIX systems, 10965 1.2 lneto this function may be not thread safe 10966 1.2 lneto because of its reliance on C function <code>gmtime</code> and C function <code>localtime</code>. 10967 1.2 lneto 10968 1.2 lneto 10969 1.1 mbalmer 10970 1.1 mbalmer 10971 1.1 mbalmer <p> 10972 1.1 mbalmer <hr><h3><a name="pdf-os.difftime"><code>os.difftime (t2, t1)</code></a></h3> 10973 1.1 mbalmer 10974 1.1 mbalmer 10975 1.1 mbalmer <p> 10976 1.3 lneto Returns the difference, in seconds, 10977 1.3 lneto from time <code>t1</code> to time <code>t2</code> 10978 1.3 lneto (where the times are values returned by <a href="#pdf-os.time"><code>os.time</code></a>). 10979 1.1 mbalmer In POSIX, Windows, and some other systems, 10980 1.1 mbalmer this value is exactly <code>t2</code><em>-</em><code>t1</code>. 10981 1.1 mbalmer 10982 1.1 mbalmer 10983 1.1 mbalmer 10984 1.1 mbalmer 10985 1.1 mbalmer <p> 10986 1.1 mbalmer <hr><h3><a name="pdf-os.execute"><code>os.execute ([command])</code></a></h3> 10987 1.1 mbalmer 10988 1.1 mbalmer 10989 1.1 mbalmer <p> 10990 1.3 lneto This function is equivalent to the ISO C function <code>system</code>. 10991 1.1 mbalmer It passes <code>command</code> to be executed by an operating system shell. 10992 1.2 lneto Its first result is <b>true</b> 10993 1.2 lneto if the command terminated successfully, 10994 1.9 nikita or <b>fail</b> otherwise. 10995 1.2 lneto After this first result 10996 1.2 lneto the function returns a string plus a number, 10997 1.2 lneto as follows: 10998 1.2 lneto 10999 1.2 lneto <ul> 11000 1.2 lneto 11001 1.2 lneto <li><b>"<code>exit</code>": </b> 11002 1.2 lneto the command terminated normally; 11003 1.2 lneto the following number is the exit status of the command. 11004 1.2 lneto </li> 11005 1.2 lneto 11006 1.2 lneto <li><b>"<code>signal</code>": </b> 11007 1.2 lneto the command was terminated by a signal; 11008 1.2 lneto the following number is the signal that terminated the command. 11009 1.2 lneto </li> 11010 1.2 lneto 11011 1.2 lneto </ul> 11012 1.2 lneto 11013 1.2 lneto <p> 11014 1.2 lneto When called without a <code>command</code>, 11015 1.2 lneto <code>os.execute</code> returns a boolean that is true if a shell is available. 11016 1.2 lneto 11017 1.1 mbalmer 11018 1.1 mbalmer 11019 1.1 mbalmer 11020 1.2 lneto <p> 11021 1.2 lneto <hr><h3><a name="pdf-os.exit"><code>os.exit ([code [, close]])</code></a></h3> 11022 1.2 lneto 11023 1.1 mbalmer 11024 1.1 mbalmer <p> 11025 1.3 lneto Calls the ISO C function <code>exit</code> to terminate the host program. 11026 1.2 lneto If <code>code</code> is <b>true</b>, 11027 1.2 lneto the returned status is <code>EXIT_SUCCESS</code>; 11028 1.2 lneto if <code>code</code> is <b>false</b>, 11029 1.2 lneto the returned status is <code>EXIT_FAILURE</code>; 11030 1.2 lneto if <code>code</code> is a number, 11031 1.2 lneto the returned status is this number. 11032 1.2 lneto The default value for <code>code</code> is <b>true</b>. 11033 1.1 mbalmer 11034 1.1 mbalmer 11035 1.1 mbalmer <p> 11036 1.2 lneto If the optional second argument <code>close</code> is true, 11037 1.10 nikita the function closes the Lua state before exiting (see <a href="#lua_close"><code>lua_close</code></a>). 11038 1.1 mbalmer 11039 1.1 mbalmer 11040 1.1 mbalmer 11041 1.1 mbalmer 11042 1.1 mbalmer <p> 11043 1.1 mbalmer <hr><h3><a name="pdf-os.getenv"><code>os.getenv (varname)</code></a></h3> 11044 1.1 mbalmer 11045 1.1 mbalmer 11046 1.1 mbalmer <p> 11047 1.9 nikita Returns the value of the process environment variable <code>varname</code> 11048 1.9 nikita or <b>fail</b> if the variable is not defined. 11049 1.1 mbalmer 11050 1.1 mbalmer 11051 1.1 mbalmer 11052 1.1 mbalmer 11053 1.1 mbalmer <p> 11054 1.1 mbalmer <hr><h3><a name="pdf-os.remove"><code>os.remove (filename)</code></a></h3> 11055 1.1 mbalmer 11056 1.1 mbalmer 11057 1.1 mbalmer <p> 11058 1.2 lneto Deletes the file (or empty directory, on POSIX systems) 11059 1.2 lneto with the given name. 11060 1.9 nikita If this function fails, it returns <b>fail</b> 11061 1.2 lneto plus a string describing the error and the error code. 11062 1.7 mbalmer Otherwise, it returns true. 11063 1.1 mbalmer 11064 1.1 mbalmer 11065 1.1 mbalmer 11066 1.1 mbalmer 11067 1.1 mbalmer <p> 11068 1.1 mbalmer <hr><h3><a name="pdf-os.rename"><code>os.rename (oldname, newname)</code></a></h3> 11069 1.1 mbalmer 11070 1.1 mbalmer 11071 1.1 mbalmer <p> 11072 1.7 mbalmer Renames the file or directory named <code>oldname</code> to <code>newname</code>. 11073 1.9 nikita If this function fails, it returns <b>fail</b>, 11074 1.2 lneto plus a string describing the error and the error code. 11075 1.7 mbalmer Otherwise, it returns true. 11076 1.1 mbalmer 11077 1.1 mbalmer 11078 1.1 mbalmer 11079 1.1 mbalmer 11080 1.1 mbalmer <p> 11081 1.1 mbalmer <hr><h3><a name="pdf-os.setlocale"><code>os.setlocale (locale [, category])</code></a></h3> 11082 1.1 mbalmer 11083 1.1 mbalmer 11084 1.1 mbalmer <p> 11085 1.1 mbalmer Sets the current locale of the program. 11086 1.2 lneto <code>locale</code> is a system-dependent string specifying a locale; 11087 1.1 mbalmer <code>category</code> is an optional string describing which category to change: 11088 1.1 mbalmer <code>"all"</code>, <code>"collate"</code>, <code>"ctype"</code>, 11089 1.1 mbalmer <code>"monetary"</code>, <code>"numeric"</code>, or <code>"time"</code>; 11090 1.1 mbalmer the default category is <code>"all"</code>. 11091 1.1 mbalmer The function returns the name of the new locale, 11092 1.9 nikita or <b>fail</b> if the request cannot be honored. 11093 1.1 mbalmer 11094 1.1 mbalmer 11095 1.1 mbalmer <p> 11096 1.1 mbalmer If <code>locale</code> is the empty string, 11097 1.1 mbalmer the current locale is set to an implementation-defined native locale. 11098 1.1 mbalmer If <code>locale</code> is the string "<code>C</code>", 11099 1.1 mbalmer the current locale is set to the standard C locale. 11100 1.1 mbalmer 11101 1.1 mbalmer 11102 1.1 mbalmer <p> 11103 1.1 mbalmer When called with <b>nil</b> as the first argument, 11104 1.1 mbalmer this function only returns the name of the current locale 11105 1.1 mbalmer for the given category. 11106 1.1 mbalmer 11107 1.1 mbalmer 11108 1.2 lneto <p> 11109 1.2 lneto This function may be not thread safe 11110 1.2 lneto because of its reliance on C function <code>setlocale</code>. 11111 1.2 lneto 11112 1.2 lneto 11113 1.1 mbalmer 11114 1.1 mbalmer 11115 1.1 mbalmer <p> 11116 1.1 mbalmer <hr><h3><a name="pdf-os.time"><code>os.time ([table])</code></a></h3> 11117 1.1 mbalmer 11118 1.1 mbalmer 11119 1.1 mbalmer <p> 11120 1.1 mbalmer Returns the current time when called without arguments, 11121 1.4 mbalmer or a time representing the local date and time specified by the given table. 11122 1.1 mbalmer This table must have fields <code>year</code>, <code>month</code>, and <code>day</code>, 11123 1.2 lneto and may have fields 11124 1.2 lneto <code>hour</code> (default is 12), 11125 1.2 lneto <code>min</code> (default is 0), 11126 1.2 lneto <code>sec</code> (default is 0), 11127 1.2 lneto and <code>isdst</code> (default is <b>nil</b>). 11128 1.4 mbalmer Other fields are ignored. 11129 1.2 lneto For a description of these fields, see the <a href="#pdf-os.date"><code>os.date</code></a> function. 11130 1.1 mbalmer 11131 1.1 mbalmer 11132 1.1 mbalmer <p> 11133 1.9 nikita When the function is called, 11134 1.9 nikita the values in these fields do not need to be inside their valid ranges. 11135 1.4 mbalmer For instance, if <code>sec</code> is -10, 11136 1.9 nikita it means 10 seconds before the time specified by the other fields; 11137 1.4 mbalmer if <code>hour</code> is 1000, 11138 1.9 nikita it means 1000 hours after the time specified by the other fields. 11139 1.4 mbalmer 11140 1.4 mbalmer 11141 1.4 mbalmer <p> 11142 1.1 mbalmer The returned value is a number, whose meaning depends on your system. 11143 1.2 lneto In POSIX, Windows, and some other systems, 11144 1.2 lneto this number counts the number 11145 1.1 mbalmer of seconds since some given start time (the "epoch"). 11146 1.1 mbalmer In other systems, the meaning is not specified, 11147 1.1 mbalmer and the number returned by <code>time</code> can be used only as an argument to 11148 1.2 lneto <a href="#pdf-os.date"><code>os.date</code></a> and <a href="#pdf-os.difftime"><code>os.difftime</code></a>. 11149 1.1 mbalmer 11150 1.1 mbalmer 11151 1.9 nikita <p> 11152 1.9 nikita When called with a table, 11153 1.9 nikita <code>os.time</code> also normalizes all the fields 11154 1.9 nikita documented in the <a href="#pdf-os.date"><code>os.date</code></a> function, 11155 1.9 nikita so that they represent the same time as before the call 11156 1.9 nikita but with values inside their valid ranges. 11157 1.9 nikita 11158 1.9 nikita 11159 1.1 mbalmer 11160 1.1 mbalmer 11161 1.1 mbalmer <p> 11162 1.1 mbalmer <hr><h3><a name="pdf-os.tmpname"><code>os.tmpname ()</code></a></h3> 11163 1.1 mbalmer 11164 1.1 mbalmer 11165 1.1 mbalmer <p> 11166 1.1 mbalmer Returns a string with a file name that can 11167 1.1 mbalmer be used for a temporary file. 11168 1.1 mbalmer The file must be explicitly opened before its use 11169 1.1 mbalmer and explicitly removed when no longer needed. 11170 1.1 mbalmer 11171 1.1 mbalmer 11172 1.1 mbalmer <p> 11173 1.8 alnsn In POSIX systems, 11174 1.1 mbalmer this function also creates a file with that name, 11175 1.1 mbalmer to avoid security risks. 11176 1.1 mbalmer (Someone else might create the file with wrong permissions 11177 1.1 mbalmer in the time between getting the name and creating the file.) 11178 1.1 mbalmer You still have to open the file to use it 11179 1.1 mbalmer and to remove it (even if you do not use it). 11180 1.1 mbalmer 11181 1.1 mbalmer 11182 1.1 mbalmer <p> 11183 1.1 mbalmer When possible, 11184 1.1 mbalmer you may prefer to use <a href="#pdf-io.tmpfile"><code>io.tmpfile</code></a>, 11185 1.1 mbalmer which automatically removes the file when the program ends. 11186 1.1 mbalmer 11187 1.1 mbalmer 11188 1.1 mbalmer 11189 1.1 mbalmer 11190 1.1 mbalmer 11191 1.1 mbalmer 11192 1.1 mbalmer 11193 1.2 lneto <h2>6.10 – <a name="6.10">The Debug Library</a></h2> 11194 1.1 mbalmer 11195 1.1 mbalmer <p> 11196 1.1 mbalmer This library provides 11197 1.9 nikita the functionality of the debug interface (<a href="#4.7">§4.7</a>) to Lua programs. 11198 1.1 mbalmer You should exert care when using this library. 11199 1.2 lneto Several of its functions 11200 1.2 lneto violate basic assumptions about Lua code 11201 1.1 mbalmer (e.g., that variables local to a function 11202 1.2 lneto cannot be accessed from outside; 11203 1.2 lneto that userdata metatables cannot be changed by Lua code; 11204 1.2 lneto that Lua programs do not crash) 11205 1.1 mbalmer and therefore can compromise otherwise secure code. 11206 1.2 lneto Moreover, some functions in this library may be slow. 11207 1.1 mbalmer 11208 1.1 mbalmer 11209 1.1 mbalmer <p> 11210 1.1 mbalmer All functions in this library are provided 11211 1.1 mbalmer inside the <a name="pdf-debug"><code>debug</code></a> table. 11212 1.1 mbalmer All functions that operate over a thread 11213 1.1 mbalmer have an optional first argument which is the 11214 1.1 mbalmer thread to operate over. 11215 1.1 mbalmer The default is always the current thread. 11216 1.1 mbalmer 11217 1.1 mbalmer 11218 1.1 mbalmer <p> 11219 1.1 mbalmer <hr><h3><a name="pdf-debug.debug"><code>debug.debug ()</code></a></h3> 11220 1.1 mbalmer 11221 1.1 mbalmer 11222 1.1 mbalmer <p> 11223 1.1 mbalmer Enters an interactive mode with the user, 11224 1.1 mbalmer running each string that the user enters. 11225 1.1 mbalmer Using simple commands and other debug facilities, 11226 1.1 mbalmer the user can inspect global and local variables, 11227 1.1 mbalmer change their values, evaluate expressions, and so on. 11228 1.1 mbalmer A line containing only the word <code>cont</code> finishes this function, 11229 1.1 mbalmer so that the caller continues its execution. 11230 1.1 mbalmer 11231 1.1 mbalmer 11232 1.1 mbalmer <p> 11233 1.1 mbalmer Note that commands for <code>debug.debug</code> are not lexically nested 11234 1.2 lneto within any function and so have no direct access to local variables. 11235 1.1 mbalmer 11236 1.1 mbalmer 11237 1.1 mbalmer 11238 1.1 mbalmer 11239 1.1 mbalmer <p> 11240 1.1 mbalmer <hr><h3><a name="pdf-debug.gethook"><code>debug.gethook ([thread])</code></a></h3> 11241 1.1 mbalmer 11242 1.1 mbalmer 11243 1.1 mbalmer <p> 11244 1.1 mbalmer Returns the current hook settings of the thread, as three values: 11245 1.1 mbalmer the current hook function, the current hook mask, 11246 1.9 nikita and the current hook count, 11247 1.9 nikita as set by the <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> function. 11248 1.9 nikita 11249 1.9 nikita 11250 1.9 nikita <p> 11251 1.9 nikita Returns <b>fail</b> if there is no active hook. 11252 1.1 mbalmer 11253 1.1 mbalmer 11254 1.1 mbalmer 11255 1.1 mbalmer 11256 1.1 mbalmer <p> 11257 1.2 lneto <hr><h3><a name="pdf-debug.getinfo"><code>debug.getinfo ([thread,] f [, what])</code></a></h3> 11258 1.1 mbalmer 11259 1.1 mbalmer 11260 1.1 mbalmer <p> 11261 1.1 mbalmer Returns a table with information about a function. 11262 1.2 lneto You can give the function directly 11263 1.2 lneto or you can give a number as the value of <code>f</code>, 11264 1.2 lneto which means the function running at level <code>f</code> of the call stack 11265 1.1 mbalmer of the given thread: 11266 1.1 mbalmer level 0 is the current function (<code>getinfo</code> itself); 11267 1.2 lneto level 1 is the function that called <code>getinfo</code> 11268 1.9 nikita (except for tail calls, which do not count in the stack); 11269 1.1 mbalmer and so on. 11270 1.9 nikita If <code>f</code> is a number greater than the number of active functions, 11271 1.9 nikita then <code>getinfo</code> returns <b>fail</b>. 11272 1.1 mbalmer 11273 1.1 mbalmer 11274 1.1 mbalmer <p> 11275 1.1 mbalmer The returned table can contain all the fields returned by <a href="#lua_getinfo"><code>lua_getinfo</code></a>, 11276 1.1 mbalmer with the string <code>what</code> describing which fields to fill in. 11277 1.1 mbalmer The default for <code>what</code> is to get all information available, 11278 1.1 mbalmer except the table of valid lines. 11279 1.1 mbalmer If present, 11280 1.1 mbalmer the option '<code>f</code>' 11281 1.1 mbalmer adds a field named <code>func</code> with the function itself. 11282 1.1 mbalmer If present, 11283 1.1 mbalmer the option '<code>L</code>' 11284 1.1 mbalmer adds a field named <code>activelines</code> with the table of 11285 1.1 mbalmer valid lines. 11286 1.1 mbalmer 11287 1.1 mbalmer 11288 1.1 mbalmer <p> 11289 1.1 mbalmer For instance, the expression <code>debug.getinfo(1,"n").name</code> returns 11290 1.4 mbalmer a name for the current function, 11291 1.1 mbalmer if a reasonable name can be found, 11292 1.1 mbalmer and the expression <code>debug.getinfo(print)</code> 11293 1.1 mbalmer returns a table with all available information 11294 1.1 mbalmer about the <a href="#pdf-print"><code>print</code></a> function. 11295 1.1 mbalmer 11296 1.1 mbalmer 11297 1.1 mbalmer 11298 1.1 mbalmer 11299 1.1 mbalmer <p> 11300 1.2 lneto <hr><h3><a name="pdf-debug.getlocal"><code>debug.getlocal ([thread,] f, local)</code></a></h3> 11301 1.1 mbalmer 11302 1.1 mbalmer 11303 1.1 mbalmer <p> 11304 1.1 mbalmer This function returns the name and the value of the local variable 11305 1.2 lneto with index <code>local</code> of the function at level <code>f</code> of the stack. 11306 1.2 lneto This function accesses not only explicit local variables, 11307 1.9 nikita but also parameters and temporary values. 11308 1.2 lneto 11309 1.2 lneto 11310 1.2 lneto <p> 11311 1.2 lneto The first parameter or local variable has index 1, and so on, 11312 1.3 lneto following the order that they are declared in the code, 11313 1.3 lneto counting only the variables that are active 11314 1.3 lneto in the current scope of the function. 11315 1.9 nikita Compile-time constants may not appear in this listing, 11316 1.9 nikita if they were optimized away by the compiler. 11317 1.8 alnsn Negative indices refer to vararg arguments; 11318 1.8 alnsn -1 is the first vararg argument. 11319 1.9 nikita The function returns <b>fail</b> 11320 1.9 nikita if there is no variable with the given index, 11321 1.2 lneto and raises an error when called with a level out of range. 11322 1.1 mbalmer (You can call <a href="#pdf-debug.getinfo"><code>debug.getinfo</code></a> to check whether the level is valid.) 11323 1.1 mbalmer 11324 1.1 mbalmer 11325 1.1 mbalmer <p> 11326 1.2 lneto Variable names starting with '<code>(</code>' (open parenthesis) 11327 1.2 lneto represent variables with no known names 11328 1.3 lneto (internal variables such as loop control variables, 11329 1.2 lneto and variables from chunks saved without debug information). 11330 1.2 lneto 11331 1.2 lneto 11332 1.2 lneto <p> 11333 1.2 lneto The parameter <code>f</code> may also be a function. 11334 1.2 lneto In that case, <code>getlocal</code> returns only the name of function parameters. 11335 1.1 mbalmer 11336 1.1 mbalmer 11337 1.1 mbalmer 11338 1.1 mbalmer 11339 1.1 mbalmer <p> 11340 1.2 lneto <hr><h3><a name="pdf-debug.getmetatable"><code>debug.getmetatable (value)</code></a></h3> 11341 1.1 mbalmer 11342 1.1 mbalmer 11343 1.1 mbalmer <p> 11344 1.2 lneto Returns the metatable of the given <code>value</code> 11345 1.1 mbalmer or <b>nil</b> if it does not have a metatable. 11346 1.1 mbalmer 11347 1.1 mbalmer 11348 1.1 mbalmer 11349 1.1 mbalmer 11350 1.1 mbalmer <p> 11351 1.1 mbalmer <hr><h3><a name="pdf-debug.getregistry"><code>debug.getregistry ()</code></a></h3> 11352 1.1 mbalmer 11353 1.1 mbalmer 11354 1.1 mbalmer <p> 11355 1.9 nikita Returns the registry table (see <a href="#4.3">§4.3</a>). 11356 1.1 mbalmer 11357 1.1 mbalmer 11358 1.1 mbalmer 11359 1.1 mbalmer 11360 1.1 mbalmer <p> 11361 1.2 lneto <hr><h3><a name="pdf-debug.getupvalue"><code>debug.getupvalue (f, up)</code></a></h3> 11362 1.1 mbalmer 11363 1.1 mbalmer 11364 1.1 mbalmer <p> 11365 1.1 mbalmer This function returns the name and the value of the upvalue 11366 1.2 lneto with index <code>up</code> of the function <code>f</code>. 11367 1.9 nikita The function returns <b>fail</b> 11368 1.9 nikita if there is no upvalue with the given index. 11369 1.1 mbalmer 11370 1.1 mbalmer 11371 1.2 lneto <p> 11372 1.9 nikita (For Lua functions, 11373 1.9 nikita upvalues are the external local variables that the function uses, 11374 1.9 nikita and that are consequently included in its closure.) 11375 1.9 nikita 11376 1.9 nikita 11377 1.9 nikita <p> 11378 1.9 nikita For C functions, this function uses the empty string <code>""</code> 11379 1.9 nikita as a name for all upvalues. 11380 1.9 nikita 11381 1.9 nikita 11382 1.9 nikita <p> 11383 1.9 nikita Variable name '<code>?</code>' (interrogation mark) 11384 1.9 nikita represents variables with no known names 11385 1.2 lneto (variables from chunks saved without debug information). 11386 1.2 lneto 11387 1.2 lneto 11388 1.1 mbalmer 11389 1.1 mbalmer 11390 1.1 mbalmer <p> 11391 1.9 nikita <hr><h3><a name="pdf-debug.getuservalue"><code>debug.getuservalue (u, n)</code></a></h3> 11392 1.1 mbalmer 11393 1.1 mbalmer 11394 1.1 mbalmer <p> 11395 1.9 nikita Returns the <code>n</code>-th user value associated 11396 1.9 nikita to the userdata <code>u</code> plus a boolean, 11397 1.9 nikita <b>false</b> if the userdata does not have that value. 11398 1.1 mbalmer 11399 1.1 mbalmer 11400 1.1 mbalmer 11401 1.1 mbalmer 11402 1.1 mbalmer <p> 11403 1.1 mbalmer <hr><h3><a name="pdf-debug.sethook"><code>debug.sethook ([thread,] hook, mask [, count])</code></a></h3> 11404 1.1 mbalmer 11405 1.1 mbalmer 11406 1.1 mbalmer <p> 11407 1.9 nikita Sets the given function as the debug hook. 11408 1.1 mbalmer The string <code>mask</code> and the number <code>count</code> describe 11409 1.1 mbalmer when the hook will be called. 11410 1.2 lneto The string mask may have any combination of the following characters, 11411 1.1 mbalmer with the given meaning: 11412 1.1 mbalmer 11413 1.1 mbalmer <ul> 11414 1.2 lneto <li><b>'<code>c</code>': </b> the hook is called every time Lua calls a function;</li> 11415 1.2 lneto <li><b>'<code>r</code>': </b> the hook is called every time Lua returns from a function;</li> 11416 1.2 lneto <li><b>'<code>l</code>': </b> the hook is called every time Lua enters a new line of code.</li> 11417 1.1 mbalmer </ul><p> 11418 1.2 lneto Moreover, 11419 1.2 lneto with a <code>count</code> different from zero, 11420 1.2 lneto the hook is called also after every <code>count</code> instructions. 11421 1.1 mbalmer 11422 1.1 mbalmer 11423 1.1 mbalmer <p> 11424 1.1 mbalmer When called without arguments, 11425 1.1 mbalmer <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> turns off the hook. 11426 1.1 mbalmer 11427 1.1 mbalmer 11428 1.1 mbalmer <p> 11429 1.9 nikita When the hook is called, its first parameter is a string 11430 1.1 mbalmer describing the event that has triggered its call: 11431 1.9 nikita <code>"call"</code>, <code>"tail call"</code>, <code>"return"</code>, 11432 1.1 mbalmer <code>"line"</code>, and <code>"count"</code>. 11433 1.1 mbalmer For line events, 11434 1.1 mbalmer the hook also gets the new line number as its second parameter. 11435 1.1 mbalmer Inside a hook, 11436 1.1 mbalmer you can call <code>getinfo</code> with level 2 to get more information about 11437 1.9 nikita the running function. 11438 1.9 nikita (Level 0 is the <code>getinfo</code> function, 11439 1.9 nikita and level 1 is the hook function.) 11440 1.1 mbalmer 11441 1.1 mbalmer 11442 1.1 mbalmer 11443 1.1 mbalmer 11444 1.1 mbalmer <p> 11445 1.1 mbalmer <hr><h3><a name="pdf-debug.setlocal"><code>debug.setlocal ([thread,] level, local, value)</code></a></h3> 11446 1.1 mbalmer 11447 1.1 mbalmer 11448 1.1 mbalmer <p> 11449 1.1 mbalmer This function assigns the value <code>value</code> to the local variable 11450 1.1 mbalmer with index <code>local</code> of the function at level <code>level</code> of the stack. 11451 1.9 nikita The function returns <b>fail</b> if there is no local 11452 1.1 mbalmer variable with the given index, 11453 1.1 mbalmer and raises an error when called with a <code>level</code> out of range. 11454 1.1 mbalmer (You can call <code>getinfo</code> to check whether the level is valid.) 11455 1.1 mbalmer Otherwise, it returns the name of the local variable. 11456 1.1 mbalmer 11457 1.1 mbalmer 11458 1.2 lneto <p> 11459 1.2 lneto See <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for more information about 11460 1.2 lneto variable indices and names. 11461 1.2 lneto 11462 1.2 lneto 11463 1.1 mbalmer 11464 1.1 mbalmer 11465 1.1 mbalmer <p> 11466 1.2 lneto <hr><h3><a name="pdf-debug.setmetatable"><code>debug.setmetatable (value, table)</code></a></h3> 11467 1.1 mbalmer 11468 1.1 mbalmer 11469 1.1 mbalmer <p> 11470 1.2 lneto Sets the metatable for the given <code>value</code> to the given <code>table</code> 11471 1.1 mbalmer (which can be <b>nil</b>). 11472 1.2 lneto Returns <code>value</code>. 11473 1.1 mbalmer 11474 1.1 mbalmer 11475 1.1 mbalmer 11476 1.1 mbalmer 11477 1.1 mbalmer <p> 11478 1.2 lneto <hr><h3><a name="pdf-debug.setupvalue"><code>debug.setupvalue (f, up, value)</code></a></h3> 11479 1.1 mbalmer 11480 1.1 mbalmer 11481 1.1 mbalmer <p> 11482 1.1 mbalmer This function assigns the value <code>value</code> to the upvalue 11483 1.2 lneto with index <code>up</code> of the function <code>f</code>. 11484 1.9 nikita The function returns <b>fail</b> if there is no upvalue 11485 1.1 mbalmer with the given index. 11486 1.1 mbalmer Otherwise, it returns the name of the upvalue. 11487 1.1 mbalmer 11488 1.1 mbalmer 11489 1.9 nikita <p> 11490 1.9 nikita See <a href="#pdf-debug.getupvalue"><code>debug.getupvalue</code></a> for more information about upvalues. 11491 1.9 nikita 11492 1.9 nikita 11493 1.1 mbalmer 11494 1.1 mbalmer 11495 1.1 mbalmer <p> 11496 1.9 nikita <hr><h3><a name="pdf-debug.setuservalue"><code>debug.setuservalue (udata, value, n)</code></a></h3> 11497 1.2 lneto 11498 1.2 lneto 11499 1.2 lneto <p> 11500 1.2 lneto Sets the given <code>value</code> as 11501 1.9 nikita the <code>n</code>-th user value associated to the given <code>udata</code>. 11502 1.2 lneto <code>udata</code> must be a full userdata. 11503 1.2 lneto 11504 1.2 lneto 11505 1.2 lneto <p> 11506 1.9 nikita Returns <code>udata</code>, 11507 1.9 nikita or <b>fail</b> if the userdata does not have that value. 11508 1.2 lneto 11509 1.2 lneto 11510 1.2 lneto 11511 1.2 lneto 11512 1.2 lneto <p> 11513 1.2 lneto <hr><h3><a name="pdf-debug.traceback"><code>debug.traceback ([thread,] [message [, level]])</code></a></h3> 11514 1.1 mbalmer 11515 1.1 mbalmer 11516 1.1 mbalmer <p> 11517 1.2 lneto If <code>message</code> is present but is neither a string nor <b>nil</b>, 11518 1.2 lneto this function returns <code>message</code> without further processing. 11519 1.2 lneto Otherwise, 11520 1.2 lneto it returns a string with a traceback of the call stack. 11521 1.3 lneto The optional <code>message</code> string is appended 11522 1.1 mbalmer at the beginning of the traceback. 11523 1.1 mbalmer An optional <code>level</code> number tells at which level 11524 1.1 mbalmer to start the traceback 11525 1.1 mbalmer (default is 1, the function calling <code>traceback</code>). 11526 1.1 mbalmer 11527 1.1 mbalmer 11528 1.1 mbalmer 11529 1.1 mbalmer 11530 1.2 lneto <p> 11531 1.2 lneto <hr><h3><a name="pdf-debug.upvalueid"><code>debug.upvalueid (f, n)</code></a></h3> 11532 1.2 lneto 11533 1.2 lneto 11534 1.2 lneto <p> 11535 1.3 lneto Returns a unique identifier (as a light userdata) 11536 1.2 lneto for the upvalue numbered <code>n</code> 11537 1.2 lneto from the given function. 11538 1.2 lneto 11539 1.2 lneto 11540 1.2 lneto <p> 11541 1.2 lneto These unique identifiers allow a program to check whether different 11542 1.2 lneto closures share upvalues. 11543 1.2 lneto Lua closures that share an upvalue 11544 1.2 lneto (that is, that access a same external local variable) 11545 1.2 lneto will return identical ids for those upvalue indices. 11546 1.2 lneto 11547 1.2 lneto 11548 1.2 lneto 11549 1.2 lneto 11550 1.2 lneto <p> 11551 1.2 lneto <hr><h3><a name="pdf-debug.upvaluejoin"><code>debug.upvaluejoin (f1, n1, f2, n2)</code></a></h3> 11552 1.2 lneto 11553 1.2 lneto 11554 1.2 lneto <p> 11555 1.2 lneto Make the <code>n1</code>-th upvalue of the Lua closure <code>f1</code> 11556 1.2 lneto refer to the <code>n2</code>-th upvalue of the Lua closure <code>f2</code>. 11557 1.2 lneto 11558 1.2 lneto 11559 1.2 lneto 11560 1.2 lneto 11561 1.1 mbalmer 11562 1.1 mbalmer 11563 1.1 mbalmer 11564 1.2 lneto <h1>7 – <a name="7">Lua Standalone</a></h1> 11565 1.1 mbalmer 11566 1.1 mbalmer <p> 11567 1.1 mbalmer Although Lua has been designed as an extension language, 11568 1.1 mbalmer to be embedded in a host C program, 11569 1.2 lneto it is also frequently used as a standalone language. 11570 1.2 lneto An interpreter for Lua as a standalone language, 11571 1.1 mbalmer called simply <code>lua</code>, 11572 1.1 mbalmer is provided with the standard distribution. 11573 1.2 lneto The standalone interpreter includes 11574 1.9 nikita all standard libraries. 11575 1.1 mbalmer Its usage is: 11576 1.1 mbalmer 11577 1.1 mbalmer <pre> 11578 1.1 mbalmer lua [options] [script [args]] 11579 1.1 mbalmer </pre><p> 11580 1.1 mbalmer The options are: 11581 1.1 mbalmer 11582 1.1 mbalmer <ul> 11583 1.9 nikita <li><b><code>-e <em>stat</em></code>: </b> execute string <em>stat</em>;</li> 11584 1.9 nikita <li><b><code>-i</code>: </b> enter interactive mode after running <em>script</em>;</li> 11585 1.9 nikita <li><b><code>-l <em>mod</em></code>: </b> "require" <em>mod</em> and assign the 11586 1.9 nikita result to global <em>mod</em>;</li> 11587 1.10 nikita <li><b><code>-l <em>g=mod</em></code>: </b> "require" <em>mod</em> and assign the 11588 1.10 nikita result to global <em>g</em>;</li> 11589 1.9 nikita <li><b><code>-v</code>: </b> print version information;</li> 11590 1.9 nikita <li><b><code>-E</code>: </b> ignore environment variables;</li> 11591 1.9 nikita <li><b><code>-W</code>: </b> turn warnings on;</li> 11592 1.9 nikita <li><b><code>--</code>: </b> stop handling options;</li> 11593 1.9 nikita <li><b><code>-</code>: </b> execute <code>stdin</code> as a file and stop handling options.</li> 11594 1.1 mbalmer </ul><p> 11595 1.10 nikita (The form <code>-l <em>g=mod</em></code> was introduced in release 5.4.4.) 11596 1.10 nikita 11597 1.10 nikita 11598 1.10 nikita <p> 11599 1.3 lneto After handling its options, <code>lua</code> runs the given <em>script</em>. 11600 1.1 mbalmer When called without arguments, 11601 1.1 mbalmer <code>lua</code> behaves as <code>lua -v -i</code> 11602 1.1 mbalmer when the standard input (<code>stdin</code>) is a terminal, 11603 1.1 mbalmer and as <code>lua -</code> otherwise. 11604 1.1 mbalmer 11605 1.1 mbalmer 11606 1.1 mbalmer <p> 11607 1.9 nikita When called without the option <code>-E</code>, 11608 1.9 nikita the interpreter checks for an environment variable <a name="pdf-LUA_INIT_5_4"><code>LUA_INIT_5_4</code></a> 11609 1.3 lneto (or <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a> if the versioned name is not defined) 11610 1.2 lneto before running any argument. 11611 1.2 lneto If the variable content has the format <code>@<em>filename</em></code>, 11612 1.1 mbalmer then <code>lua</code> executes the file. 11613 1.1 mbalmer Otherwise, <code>lua</code> executes the string itself. 11614 1.1 mbalmer 11615 1.1 mbalmer 11616 1.1 mbalmer <p> 11617 1.9 nikita When called with the option <code>-E</code>, 11618 1.9 nikita Lua does not consult any environment variables. 11619 1.9 nikita In particular, 11620 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> 11621 1.9 nikita are set with the default paths defined in <code>luaconf.h</code>. 11622 1.2 lneto 11623 1.2 lneto 11624 1.2 lneto <p> 11625 1.9 nikita The options <code>-e</code>, <code>-l</code>, and <code>-W</code> are handled in 11626 1.9 nikita the order they appear. 11627 1.1 mbalmer For instance, an invocation like 11628 1.1 mbalmer 11629 1.1 mbalmer <pre> 11630 1.9 nikita $ lua -e 'a=1' -llib1 script.lua 11631 1.1 mbalmer </pre><p> 11632 1.9 nikita will first set <code>a</code> to 1, then require the library <code>lib1</code>, 11633 1.1 mbalmer and finally run the file <code>script.lua</code> with no arguments. 11634 1.1 mbalmer (Here <code>$</code> is the shell prompt. Your prompt may be different.) 11635 1.1 mbalmer 11636 1.1 mbalmer 11637 1.1 mbalmer <p> 11638 1.2 lneto Before running any code, 11639 1.2 lneto <code>lua</code> collects all command-line arguments 11640 1.1 mbalmer in a global table called <code>arg</code>. 11641 1.2 lneto The script name goes to index 0, 11642 1.1 mbalmer the first argument after the script name goes to index 1, 11643 1.1 mbalmer and so on. 11644 1.1 mbalmer Any arguments before the script name 11645 1.2 lneto (that is, the interpreter name plus its options) 11646 1.1 mbalmer go to negative indices. 11647 1.1 mbalmer For instance, in the call 11648 1.1 mbalmer 11649 1.1 mbalmer <pre> 11650 1.1 mbalmer $ lua -la b.lua t1 t2 11651 1.1 mbalmer </pre><p> 11652 1.2 lneto the table is like this: 11653 1.1 mbalmer 11654 1.1 mbalmer <pre> 11655 1.1 mbalmer arg = { [-2] = "lua", [-1] = "-la", 11656 1.1 mbalmer [0] = "b.lua", 11657 1.1 mbalmer [1] = "t1", [2] = "t2" } 11658 1.1 mbalmer </pre><p> 11659 1.2 lneto If there is no script in the call, 11660 1.2 lneto the interpreter name goes to index 0, 11661 1.2 lneto followed by the other arguments. 11662 1.2 lneto For instance, the call 11663 1.2 lneto 11664 1.2 lneto <pre> 11665 1.2 lneto $ lua -e "print(arg[1])" 11666 1.2 lneto </pre><p> 11667 1.2 lneto will print "<code>-e</code>". 11668 1.3 lneto If there is a script, 11669 1.8 alnsn the script is called with arguments 11670 1.3 lneto <code>arg[1]</code>, ···, <code>arg[#arg]</code>. 11671 1.9 nikita Like all chunks in Lua, 11672 1.10 nikita the script is compiled as a variadic function. 11673 1.1 mbalmer 11674 1.1 mbalmer 11675 1.1 mbalmer <p> 11676 1.1 mbalmer In interactive mode, 11677 1.2 lneto Lua repeatedly prompts and waits for a line. 11678 1.2 lneto After reading a line, 11679 1.2 lneto Lua first try to interpret the line as an expression. 11680 1.2 lneto If it succeeds, it prints its value. 11681 1.2 lneto Otherwise, it interprets the line as a statement. 11682 1.2 lneto If you write an incomplete statement, 11683 1.1 mbalmer the interpreter waits for its completion 11684 1.1 mbalmer by issuing a different prompt. 11685 1.1 mbalmer 11686 1.1 mbalmer 11687 1.1 mbalmer <p> 11688 1.6 salazar If the global variable <a name="pdf-_PROMPT"><code>_PROMPT</code></a> contains a string, 11689 1.6 salazar then its value is used as the prompt. 11690 1.6 salazar Similarly, if the global variable <a name="pdf-_PROMPT2"><code>_PROMPT2</code></a> contains a string, 11691 1.6 salazar its value is used as the secondary prompt 11692 1.6 salazar (issued during incomplete statements). 11693 1.6 salazar 11694 1.6 salazar 11695 1.6 salazar <p> 11696 1.2 lneto In case of unprotected errors in the script, 11697 1.2 lneto the interpreter reports the error to the standard error stream. 11698 1.7 mbalmer If the error object is not a string but 11699 1.3 lneto has a metamethod <code>__tostring</code>, 11700 1.2 lneto the interpreter calls this metamethod to produce the final message. 11701 1.3 lneto Otherwise, the interpreter converts the error object to a string 11702 1.3 lneto and adds a stack traceback to it. 11703 1.9 nikita When warnings are on, 11704 1.9 nikita they are simply printed in the standard error output. 11705 1.2 lneto 11706 1.2 lneto 11707 1.2 lneto <p> 11708 1.2 lneto When finishing normally, 11709 1.2 lneto the interpreter closes its main Lua state 11710 1.2 lneto (see <a href="#lua_close"><code>lua_close</code></a>). 11711 1.2 lneto The script can avoid this step by 11712 1.2 lneto calling <a href="#pdf-os.exit"><code>os.exit</code></a> to terminate. 11713 1.1 mbalmer 11714 1.1 mbalmer 11715 1.1 mbalmer <p> 11716 1.1 mbalmer To allow the use of Lua as a 11717 1.1 mbalmer script interpreter in Unix systems, 11718 1.9 nikita Lua skips the first line of a file chunk if it starts with <code>#</code>. 11719 1.1 mbalmer Therefore, Lua scripts can be made into executable programs 11720 1.1 mbalmer by using <code>chmod +x</code> and the <code>#!</code> form, 11721 1.1 mbalmer as in 11722 1.1 mbalmer 11723 1.1 mbalmer <pre> 11724 1.1 mbalmer #!/usr/local/bin/lua 11725 1.1 mbalmer </pre><p> 11726 1.9 nikita Of course, 11727 1.1 mbalmer the location of the Lua interpreter may be different in your machine. 11728 1.1 mbalmer If <code>lua</code> is in your <code>PATH</code>, 11729 1.2 lneto then 11730 1.1 mbalmer 11731 1.1 mbalmer <pre> 11732 1.1 mbalmer #!/usr/bin/env lua 11733 1.1 mbalmer </pre><p> 11734 1.9 nikita is a more portable solution. 11735 1.1 mbalmer 11736 1.1 mbalmer 11737 1.1 mbalmer 11738 1.2 lneto <h1>8 – <a name="8">Incompatibilities with the Previous Version</a></h1> 11739 1.1 mbalmer 11740 1.9 nikita 11741 1.9 nikita 11742 1.1 mbalmer <p> 11743 1.1 mbalmer Here we list the incompatibilities that you may find when moving a program 11744 1.9 nikita from Lua 5.3 to Lua 5.4. 11745 1.9 nikita 11746 1.9 nikita 11747 1.9 nikita <p> 11748 1.2 lneto You can avoid some incompatibilities by compiling Lua with 11749 1.1 mbalmer appropriate options (see file <code>luaconf.h</code>). 11750 1.1 mbalmer However, 11751 1.2 lneto all these compatibility options will be removed in the future. 11752 1.9 nikita More often than not, 11753 1.9 nikita compatibility issues arise when these compatibility options 11754 1.9 nikita are removed. 11755 1.9 nikita So, whenever you have the chance, 11756 1.9 nikita you should try to test your code with a version of Lua compiled 11757 1.9 nikita with all compatibility options turned off. 11758 1.9 nikita That will ease transitions to newer versions of Lua. 11759 1.1 mbalmer 11760 1.1 mbalmer 11761 1.2 lneto <p> 11762 1.2 lneto Lua versions can always change the C API in ways that 11763 1.2 lneto do not imply source-code changes in a program, 11764 1.2 lneto such as the numeric values for constants 11765 1.2 lneto or the implementation of functions as macros. 11766 1.2 lneto Therefore, 11767 1.9 nikita you should never assume that binaries are compatible between 11768 1.2 lneto different Lua versions. 11769 1.2 lneto Always recompile clients of the Lua API when 11770 1.2 lneto using a new version. 11771 1.1 mbalmer 11772 1.1 mbalmer 11773 1.2 lneto <p> 11774 1.2 lneto Similarly, Lua versions can always change the internal representation 11775 1.2 lneto of precompiled chunks; 11776 1.3 lneto precompiled chunks are not compatible between different Lua versions. 11777 1.1 mbalmer 11778 1.1 mbalmer 11779 1.2 lneto <p> 11780 1.2 lneto The standard paths in the official distribution may 11781 1.2 lneto change between versions. 11782 1.1 mbalmer 11783 1.1 mbalmer 11784 1.1 mbalmer 11785 1.9 nikita 11786 1.9 nikita 11787 1.9 nikita <h2>8.1 – <a name="8.1">Incompatibilities in the Language</a></h2> 11788 1.1 mbalmer <ul> 11789 1.1 mbalmer 11790 1.1 mbalmer <li> 11791 1.9 nikita The coercion of strings to numbers in 11792 1.9 nikita arithmetic and bitwise operations 11793 1.9 nikita has been removed from the core language. 11794 1.9 nikita The string library does a similar job 11795 1.9 nikita for arithmetic (but not for bitwise) operations 11796 1.9 nikita using the string metamethods. 11797 1.9 nikita However, unlike in previous versions, 11798 1.9 nikita the new implementation preserves the implicit type of the numeral 11799 1.9 nikita in the string. 11800 1.9 nikita For instance, the result of <code>"1" + "2"</code> now is an integer, 11801 1.9 nikita not a float. 11802 1.9 nikita </li> 11803 1.2 lneto 11804 1.9 nikita <li> 11805 1.9 nikita Literal decimal integer constants that overflow are read as floats, 11806 1.9 nikita instead of wrapping around. 11807 1.9 nikita You can use hexadecimal notation for such constants if you 11808 1.9 nikita want the old behavior 11809 1.9 nikita (reading them as integers with wrap around). 11810 1.9 nikita </li> 11811 1.1 mbalmer 11812 1.9 nikita <li> 11813 1.9 nikita The use of the <code>__lt</code> metamethod to emulate <code>__le</code> 11814 1.9 nikita has been removed. 11815 1.9 nikita When needed, this metamethod must be explicitly defined. 11816 1.1 mbalmer </li> 11817 1.1 mbalmer 11818 1.1 mbalmer <li> 11819 1.9 nikita The semantics of the numerical <b>for</b> loop 11820 1.9 nikita over integers changed in some details. 11821 1.9 nikita In particular, the control variable never wraps around. 11822 1.9 nikita </li> 11823 1.1 mbalmer 11824 1.9 nikita <li> 11825 1.9 nikita A label for a <b>goto</b> cannot be declared where a label with the same 11826 1.9 nikita name is visible, even if this other label is declared in an enclosing 11827 1.9 nikita block. 11828 1.1 mbalmer </li> 11829 1.1 mbalmer 11830 1.1 mbalmer <li> 11831 1.9 nikita When finalizing an object, 11832 1.9 nikita Lua does not ignore <code>__gc</code> metamethods that are not functions. 11833 1.9 nikita Any value will be called, if present. 11834 1.9 nikita (Non-callable values will generate a warning, 11835 1.9 nikita like any other error when calling a finalizer.) 11836 1.1 mbalmer </li> 11837 1.1 mbalmer 11838 1.1 mbalmer </ul> 11839 1.1 mbalmer 11840 1.1 mbalmer 11841 1.1 mbalmer 11842 1.1 mbalmer 11843 1.9 nikita <h2>8.2 – <a name="8.2">Incompatibilities in the Libraries</a></h2> 11844 1.1 mbalmer <ul> 11845 1.1 mbalmer 11846 1.1 mbalmer <li> 11847 1.9 nikita The function <a href="#pdf-print"><code>print</code></a> does not call <a href="#pdf-tostring"><code>tostring</code></a> 11848 1.9 nikita to format its arguments; 11849 1.9 nikita instead, it has this functionality hardwired. 11850 1.9 nikita You should use <code>__tostring</code> to modify how values are printed. 11851 1.3 lneto </li> 11852 1.3 lneto 11853 1.3 lneto <li> 11854 1.9 nikita The pseudo-random number generator used by the function <a href="#pdf-math.random"><code>math.random</code></a> 11855 1.9 nikita now starts with a somewhat random seed. 11856 1.9 nikita Moreover, it uses a different algorithm. 11857 1.3 lneto </li> 11858 1.3 lneto 11859 1.3 lneto <li> 11860 1.9 nikita By default, the decoding functions in the <a href="#pdf-utf8"><code>utf8</code></a> library 11861 1.9 nikita do not accept surrogates as valid code points. 11862 1.9 nikita An extra parameter in these functions makes them more permissive. 11863 1.1 mbalmer </li> 11864 1.1 mbalmer 11865 1.1 mbalmer <li> 11866 1.9 nikita The options "<code>setpause</code>" and "<code>setstepmul</code>" 11867 1.9 nikita of the function <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> are deprecated. 11868 1.9 nikita You should use the new option "<code>incremental</code>" to set them. 11869 1.1 mbalmer </li> 11870 1.1 mbalmer 11871 1.1 mbalmer <li> 11872 1.9 nikita The function <a href="#pdf-io.lines"><code>io.lines</code></a> now returns four values, 11873 1.9 nikita instead of just one. 11874 1.9 nikita That can be a problem when it is used as the sole 11875 1.9 nikita argument to another function that has optional parameters, 11876 1.9 nikita such as in <code>load(io.lines(filename, "L"))</code>. 11877 1.9 nikita To fix that issue, 11878 1.9 nikita you can wrap the call into parentheses, 11879 1.9 nikita to adjust its number of results to one. 11880 1.3 lneto </li> 11881 1.3 lneto 11882 1.9 nikita </ul> 11883 1.9 nikita 11884 1.1 mbalmer 11885 1.4 mbalmer 11886 1.2 lneto 11887 1.9 nikita <h2>8.3 – <a name="8.3">Incompatibilities in the API</a></h2> 11888 1.2 lneto 11889 1.2 lneto 11890 1.9 nikita <ul> 11891 1.2 lneto 11892 1.9 nikita <li> 11893 1.9 nikita Full userdata now has an arbitrary number of associated user values. 11894 1.9 nikita Therefore, the functions <code>lua_newuserdata</code>, 11895 1.9 nikita <code>lua_setuservalue</code>, and <code>lua_getuservalue</code> were 11896 1.9 nikita replaced by <a href="#lua_newuserdatauv"><code>lua_newuserdatauv</code></a>, 11897 1.9 nikita <a href="#lua_setiuservalue"><code>lua_setiuservalue</code></a>, and <a href="#lua_getiuservalue"><code>lua_getiuservalue</code></a>, 11898 1.9 nikita which have an extra argument. 11899 1.2 lneto 11900 1.2 lneto 11901 1.9 nikita <p> 11902 1.9 nikita For compatibility, the old names still work as macros assuming 11903 1.9 nikita one single user value. 11904 1.9 nikita Note, however, that userdata with zero user values 11905 1.9 nikita are more efficient memory-wise. 11906 1.9 nikita </li> 11907 1.2 lneto 11908 1.1 mbalmer <li> 11909 1.9 nikita The function <a href="#lua_resume"><code>lua_resume</code></a> has an extra parameter. 11910 1.9 nikita This out parameter returns the number of values on 11911 1.9 nikita the top of the stack that were yielded or returned by the coroutine. 11912 1.9 nikita (In previous versions, 11913 1.9 nikita those values were the entire stack.) 11914 1.1 mbalmer </li> 11915 1.1 mbalmer 11916 1.1 mbalmer <li> 11917 1.9 nikita The function <a href="#lua_version"><code>lua_version</code></a> returns the version number, 11918 1.9 nikita instead of an address of the version number. 11919 1.9 nikita The Lua core should work correctly with libraries using their 11920 1.9 nikita own static copies of the same core, 11921 1.9 nikita so there is no need to check whether they are using the same 11922 1.9 nikita address space. 11923 1.1 mbalmer </li> 11924 1.1 mbalmer 11925 1.3 lneto <li> 11926 1.9 nikita The constant <code>LUA_ERRGCMM</code> was removed. 11927 1.9 nikita Errors in finalizers are never propagated; 11928 1.9 nikita instead, they generate a warning. 11929 1.3 lneto </li> 11930 1.3 lneto 11931 1.3 lneto <li> 11932 1.9 nikita The options <code>LUA_GCSETPAUSE</code> and <code>LUA_GCSETSTEPMUL</code> 11933 1.9 nikita of the function <a href="#lua_gc"><code>lua_gc</code></a> are deprecated. 11934 1.9 nikita You should use the new option <code>LUA_GCINC</code> to set them. 11935 1.3 lneto </li> 11936 1.3 lneto 11937 1.1 mbalmer </ul> 11938 1.1 mbalmer 11939 1.1 mbalmer 11940 1.1 mbalmer 11941 1.1 mbalmer 11942 1.2 lneto <h1>9 – <a name="9">The Complete Syntax of Lua</a></h1> 11943 1.1 mbalmer 11944 1.1 mbalmer <p> 11945 1.1 mbalmer Here is the complete syntax of Lua in extended BNF. 11946 1.3 lneto As usual in extended BNF, 11947 1.3 lneto {A} means 0 or more As, 11948 1.3 lneto and [A] means an optional A. 11949 1.3 lneto (For operator precedences, see <a href="#3.4.8">§3.4.8</a>; 11950 1.3 lneto for a description of the terminals 11951 1.3 lneto Name, Numeral, 11952 1.3 lneto and LiteralString, see <a href="#3.1">§3.1</a>.) 11953 1.1 mbalmer 11954 1.1 mbalmer 11955 1.1 mbalmer 11956 1.1 mbalmer 11957 1.1 mbalmer <pre> 11958 1.1 mbalmer 11959 1.2 lneto chunk ::= block 11960 1.1 mbalmer 11961 1.2 lneto block ::= {stat} [retstat] 11962 1.1 mbalmer 11963 1.2 lneto stat ::= ‘<b>;</b>’ | 11964 1.2 lneto varlist ‘<b>=</b>’ explist | 11965 1.1 mbalmer functioncall | 11966 1.2 lneto label | 11967 1.2 lneto <b>break</b> | 11968 1.2 lneto <b>goto</b> Name | 11969 1.1 mbalmer <b>do</b> block <b>end</b> | 11970 1.1 mbalmer <b>while</b> exp <b>do</b> block <b>end</b> | 11971 1.1 mbalmer <b>repeat</b> block <b>until</b> exp | 11972 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> | 11973 1.2 lneto <b>for</b> Name ‘<b>=</b>’ exp ‘<b>,</b>’ exp [‘<b>,</b>’ exp] <b>do</b> block <b>end</b> | 11974 1.1 mbalmer <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> | 11975 1.1 mbalmer <b>function</b> funcname funcbody | 11976 1.1 mbalmer <b>local</b> <b>function</b> Name funcbody | 11977 1.9 nikita <b>local</b> attnamelist [‘<b>=</b>’ explist] 11978 1.9 nikita 11979 1.9 nikita attnamelist ::= Name attrib {‘<b>,</b>’ Name attrib} 11980 1.9 nikita 11981 1.9 nikita attrib ::= [‘<b><</b>’ Name ‘<b>></b>’] 11982 1.1 mbalmer 11983 1.2 lneto retstat ::= <b>return</b> [explist] [‘<b>;</b>’] 11984 1.1 mbalmer 11985 1.2 lneto label ::= ‘<b>::</b>’ Name ‘<b>::</b>’ 11986 1.1 mbalmer 11987 1.2 lneto funcname ::= Name {‘<b>.</b>’ Name} [‘<b>:</b>’ Name] 11988 1.1 mbalmer 11989 1.2 lneto varlist ::= var {‘<b>,</b>’ var} 11990 1.1 mbalmer 11991 1.2 lneto var ::= Name | prefixexp ‘<b>[</b>’ exp ‘<b>]</b>’ | prefixexp ‘<b>.</b>’ Name 11992 1.1 mbalmer 11993 1.2 lneto namelist ::= Name {‘<b>,</b>’ Name} 11994 1.1 mbalmer 11995 1.2 lneto explist ::= exp {‘<b>,</b>’ exp} 11996 1.2 lneto 11997 1.3 lneto exp ::= <b>nil</b> | <b>false</b> | <b>true</b> | Numeral | LiteralString | ‘<b>...</b>’ | functiondef | 11998 1.1 mbalmer prefixexp | tableconstructor | exp binop exp | unop exp 11999 1.1 mbalmer 12000 1.2 lneto prefixexp ::= var | functioncall | ‘<b>(</b>’ exp ‘<b>)</b>’ 12001 1.1 mbalmer 12002 1.2 lneto functioncall ::= prefixexp args | prefixexp ‘<b>:</b>’ Name args 12003 1.1 mbalmer 12004 1.3 lneto args ::= ‘<b>(</b>’ [explist] ‘<b>)</b>’ | tableconstructor | LiteralString 12005 1.1 mbalmer 12006 1.2 lneto functiondef ::= <b>function</b> funcbody 12007 1.1 mbalmer 12008 1.2 lneto funcbody ::= ‘<b>(</b>’ [parlist] ‘<b>)</b>’ block <b>end</b> 12009 1.1 mbalmer 12010 1.2 lneto parlist ::= namelist [‘<b>,</b>’ ‘<b>...</b>’] | ‘<b>...</b>’ 12011 1.1 mbalmer 12012 1.2 lneto tableconstructor ::= ‘<b>{</b>’ [fieldlist] ‘<b>}</b>’ 12013 1.1 mbalmer 12014 1.1 mbalmer fieldlist ::= field {fieldsep field} [fieldsep] 12015 1.1 mbalmer 12016 1.2 lneto field ::= ‘<b>[</b>’ exp ‘<b>]</b>’ ‘<b>=</b>’ exp | Name ‘<b>=</b>’ exp | exp 12017 1.1 mbalmer 12018 1.2 lneto fieldsep ::= ‘<b>,</b>’ | ‘<b>;</b>’ 12019 1.1 mbalmer 12020 1.2 lneto binop ::= ‘<b>+</b>’ | ‘<b>-</b>’ | ‘<b>*</b>’ | ‘<b>/</b>’ | ‘<b>//</b>’ | ‘<b>^</b>’ | ‘<b>%</b>’ | 12021 1.2 lneto ‘<b>&</b>’ | ‘<b>~</b>’ | ‘<b>|</b>’ | ‘<b>>></b>’ | ‘<b><<</b>’ | ‘<b>..</b>’ | 12022 1.2 lneto ‘<b><</b>’ | ‘<b><=</b>’ | ‘<b>></b>’ | ‘<b>>=</b>’ | ‘<b>==</b>’ | ‘<b>~=</b>’ | 12023 1.1 mbalmer <b>and</b> | <b>or</b> 12024 1.1 mbalmer 12025 1.2 lneto unop ::= ‘<b>-</b>’ | <b>not</b> | ‘<b>#</b>’ | ‘<b>~</b>’ 12026 1.1 mbalmer 12027 1.1 mbalmer </pre> 12028 1.1 mbalmer 12029 1.1 mbalmer <p> 12030 1.1 mbalmer 12031 1.1 mbalmer 12032 1.1 mbalmer 12033 1.1 mbalmer 12034 1.1 mbalmer 12035 1.1 mbalmer 12036 1.1 mbalmer 12037 1.4 mbalmer <P CLASS="footer"> 12038 1.1 mbalmer Last update: 12039 1.10 nikita Tue May 2 20:09:38 UTC 2023 12040 1.4 mbalmer </P> 12041 1.1 mbalmer <!-- 12042 1.10 nikita Last change: revised for Lua 5.4.6 12043 1.1 mbalmer --> 12044 1.1 mbalmer 12045 1.1 mbalmer </body></html> 12046 1.1 mbalmer 12047