manual.html revision 1.2
1 1.1 mbalmer <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2 1.1 mbalmer <html> 3 1.1 mbalmer 4 1.1 mbalmer <head> 5 1.2 lneto <title>Lua 5.3 Reference Manual</title> 6 1.1 mbalmer <link rel="stylesheet" type="text/css" href="lua.css"> 7 1.1 mbalmer <link rel="stylesheet" type="text/css" href="manual.css"> 8 1.1 mbalmer <META HTTP-EQUIV="content-type" CONTENT="text/html; charset=iso-8859-1"> 9 1.1 mbalmer </head> 10 1.1 mbalmer 11 1.1 mbalmer <body> 12 1.1 mbalmer 13 1.1 mbalmer <hr> 14 1.1 mbalmer <h1> 15 1.1 mbalmer <a href="http://www.lua.org/"><img src="logo.gif" alt="" border="0"></a> 16 1.2 lneto Lua 5.3 Reference Manual 17 1.1 mbalmer </h1> 18 1.1 mbalmer 19 1.2 lneto <P> 20 1.2 lneto <IMG SRC="alert.png" ALIGN="absbottom"> 21 1.2 lneto <EM>All details may change in the final version.</EM> 22 1.2 lneto <P> 23 1.2 lneto 24 1.1 mbalmer by Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes 25 1.1 mbalmer <p> 26 1.1 mbalmer <small> 27 1.2 lneto Copyright © 2011–2014 Lua.org, PUC-Rio. 28 1.1 mbalmer Freely available under the terms of the 29 1.2 lneto <a href="http://www.lua.org/license.html">Lua license</a>. 30 1.1 mbalmer </small> 31 1.1 mbalmer <hr> 32 1.1 mbalmer <p> 33 1.1 mbalmer 34 1.1 mbalmer <a href="contents.html#contents">contents</A> 35 1.1 mbalmer · 36 1.1 mbalmer <a href="contents.html#index">index</A> 37 1.1 mbalmer 38 1.1 mbalmer <!-- ====================================================================== --> 39 1.1 mbalmer <p> 40 1.1 mbalmer 41 1.2 lneto <!-- $Id: manual.html,v 1.2 2014/07/19 18:38:34 lneto Exp $ --> 42 1.1 mbalmer 43 1.1 mbalmer 44 1.1 mbalmer 45 1.1 mbalmer 46 1.2 lneto <h1>1 – <a name="1">Introduction</a></h1> 47 1.1 mbalmer 48 1.1 mbalmer <p> 49 1.1 mbalmer Lua is an extension programming language designed to support 50 1.1 mbalmer general procedural programming with data description 51 1.1 mbalmer facilities. 52 1.1 mbalmer It also offers good support for object-oriented programming, 53 1.1 mbalmer functional programming, and data-driven programming. 54 1.2 lneto Lua is intended to be used as a powerful, lightweight, 55 1.2 lneto embeddable scripting language for any program that needs one. 56 1.2 lneto Lua is implemented as a library, written in <em>clean C</em>, 57 1.2 lneto the common subset of Standard C and C++. 58 1.1 mbalmer 59 1.1 mbalmer 60 1.1 mbalmer <p> 61 1.1 mbalmer Being an extension language, Lua has no notion of a "main" program: 62 1.1 mbalmer it only works <em>embedded</em> in a host client, 63 1.1 mbalmer called the <em>embedding program</em> or simply the <em>host</em>. 64 1.2 lneto The host program can invoke functions to execute a piece of Lua code, 65 1.1 mbalmer can write and read Lua variables, 66 1.1 mbalmer and can register C functions to be called by Lua code. 67 1.1 mbalmer Through the use of C functions, Lua can be augmented to cope with 68 1.1 mbalmer a wide range of different domains, 69 1.1 mbalmer thus creating customized programming languages sharing a syntactical framework. 70 1.1 mbalmer The Lua distribution includes a sample host program called <code>lua</code>, 71 1.2 lneto which uses the Lua library to offer a complete, standalone Lua interpreter, 72 1.2 lneto for interactive or batch use. 73 1.1 mbalmer 74 1.1 mbalmer 75 1.1 mbalmer <p> 76 1.1 mbalmer Lua is free software, 77 1.1 mbalmer and is provided as usual with no guarantees, 78 1.1 mbalmer as stated in its license. 79 1.1 mbalmer The implementation described in this manual is available 80 1.1 mbalmer at Lua's official web site, <code>www.lua.org</code>. 81 1.1 mbalmer 82 1.1 mbalmer 83 1.1 mbalmer <p> 84 1.1 mbalmer Like any other reference manual, 85 1.1 mbalmer this document is dry in places. 86 1.1 mbalmer For a discussion of the decisions behind the design of Lua, 87 1.1 mbalmer see the technical papers available at Lua's web site. 88 1.1 mbalmer For a detailed introduction to programming in Lua, 89 1.2 lneto see Roberto's book, <em>Programming in Lua</em>. 90 1.1 mbalmer 91 1.1 mbalmer 92 1.1 mbalmer 93 1.2 lneto <h1>2 – <a name="2">Basic Concepts</a></h1> 94 1.1 mbalmer 95 1.1 mbalmer <p> 96 1.2 lneto This section describes the basic concepts of the language. 97 1.1 mbalmer 98 1.1 mbalmer 99 1.1 mbalmer 100 1.2 lneto <h2>2.1 – <a name="2.1">Values and Types</a></h2> 101 1.1 mbalmer 102 1.1 mbalmer <p> 103 1.1 mbalmer Lua is a <em>dynamically typed language</em>. 104 1.1 mbalmer This means that 105 1.1 mbalmer variables do not have types; only values do. 106 1.1 mbalmer There are no type definitions in the language. 107 1.1 mbalmer All values carry their own type. 108 1.1 mbalmer 109 1.1 mbalmer 110 1.1 mbalmer <p> 111 1.1 mbalmer All values in Lua are <em>first-class values</em>. 112 1.1 mbalmer This means that all values can be stored in variables, 113 1.1 mbalmer passed as arguments to other functions, and returned as results. 114 1.1 mbalmer 115 1.1 mbalmer 116 1.1 mbalmer <p> 117 1.1 mbalmer There are eight basic types in Lua: 118 1.1 mbalmer <em>nil</em>, <em>boolean</em>, <em>number</em>, 119 1.1 mbalmer <em>string</em>, <em>function</em>, <em>userdata</em>, 120 1.1 mbalmer <em>thread</em>, and <em>table</em>. 121 1.1 mbalmer <em>Nil</em> is the type of the value <b>nil</b>, 122 1.1 mbalmer whose main property is to be different from any other value; 123 1.1 mbalmer it usually represents the absence of a useful value. 124 1.1 mbalmer <em>Boolean</em> is the type of the values <b>false</b> and <b>true</b>. 125 1.1 mbalmer Both <b>nil</b> and <b>false</b> make a condition false; 126 1.1 mbalmer any other value makes it true. 127 1.2 lneto <em>Number</em> represents both 128 1.2 lneto integral numbers and real (floating-point) numbers. 129 1.2 lneto <em>String</em> represents immutable sequences of bytes. 130 1.1 mbalmer 131 1.1 mbalmer Lua is 8-bit clean: 132 1.2 lneto strings can contain any 8-bit value, 133 1.2 lneto including embedded zeros ('<code>\0</code>'). 134 1.2 lneto 135 1.2 lneto 136 1.2 lneto <p> 137 1.2 lneto The type <em>number</em> uses two internal representations, 138 1.2 lneto one called <em>integer</em> and the other called <em>float</em>. 139 1.2 lneto Lua has explicit rules about when each representation is used, 140 1.2 lneto but it also converts between them automatically as needed (see <a href="#3.4.3">§3.4.3</a>). 141 1.2 lneto Therefore, 142 1.2 lneto the programmer has the option of mostly ignoring the difference 143 1.2 lneto between integers and floats 144 1.2 lneto or assuming complete control over the representation of each value. 145 1.2 lneto Standard Lua uses 64-bit integers and double-precision (64-bit) floats, 146 1.2 lneto but you can also compile Lua so that it 147 1.2 lneto uses 32-bit integers and/or single-precision (32-bit) floats. 148 1.2 lneto The option with 32 bits both for integers and floats 149 1.2 lneto (what is called <em>Small Lua</em>) is particularly attractive 150 1.2 lneto for small machines. 151 1.1 mbalmer 152 1.1 mbalmer 153 1.1 mbalmer <p> 154 1.1 mbalmer Lua can call (and manipulate) functions written in Lua and 155 1.1 mbalmer functions written in C 156 1.2 lneto (see <a href="#3.4.10">§3.4.10</a>). 157 1.1 mbalmer 158 1.1 mbalmer 159 1.1 mbalmer <p> 160 1.1 mbalmer The type <em>userdata</em> is provided to allow arbitrary C data to 161 1.1 mbalmer be stored in Lua variables. 162 1.2 lneto A userdata value is a pointer to a block of raw memory. 163 1.2 lneto There are two kinds of userdata: 164 1.2 lneto full userdata, where the block of memory is managed by Lua, 165 1.2 lneto and light userdata, where the block of memory is managed by the host. 166 1.2 lneto Userdata has no predefined operations in Lua, 167 1.1 mbalmer except assignment and identity test. 168 1.2 lneto By using <em>metatables</em>, 169 1.2 lneto the programmer can define operations for full userdata values 170 1.2 lneto (see <a href="#2.4">§2.4</a>). 171 1.1 mbalmer Userdata values cannot be created or modified in Lua, 172 1.1 mbalmer only through the C API. 173 1.1 mbalmer This guarantees the integrity of data owned by the host program. 174 1.1 mbalmer 175 1.1 mbalmer 176 1.1 mbalmer <p> 177 1.1 mbalmer The type <em>thread</em> represents independent threads of execution 178 1.2 lneto and it is used to implement coroutines (see <a href="#2.6">§2.6</a>). 179 1.1 mbalmer Do not confuse Lua threads with operating-system threads. 180 1.1 mbalmer Lua supports coroutines on all systems, 181 1.1 mbalmer even those that do not support threads. 182 1.1 mbalmer 183 1.1 mbalmer 184 1.1 mbalmer <p> 185 1.1 mbalmer The type <em>table</em> implements associative arrays, 186 1.1 mbalmer that is, arrays that can be indexed not only with numbers, 187 1.2 lneto but with any Lua value except <b>nil</b> and NaN 188 1.2 lneto (<em>Not a Number</em>, a special numeric value used to represent 189 1.2 lneto undefined or unrepresentable results, such as <code>0/0</code>). 190 1.1 mbalmer Tables can be <em>heterogeneous</em>; 191 1.1 mbalmer that is, they can contain values of all types (except <b>nil</b>). 192 1.2 lneto Any key with value <b>nil</b> is not considered part of the table. 193 1.2 lneto Conversely, any key that is not part of a table has 194 1.2 lneto an associated value <b>nil</b>. 195 1.2 lneto 196 1.2 lneto 197 1.2 lneto <p> 198 1.1 mbalmer Tables are the sole data structuring mechanism in Lua; 199 1.2 lneto they can be used to represent ordinary arrays, sequences, 200 1.1 mbalmer symbol tables, sets, records, graphs, trees, etc. 201 1.1 mbalmer To represent records, Lua uses the field name as an index. 202 1.1 mbalmer The language supports this representation by 203 1.1 mbalmer providing <code>a.name</code> as syntactic sugar for <code>a["name"]</code>. 204 1.1 mbalmer There are several convenient ways to create tables in Lua 205 1.2 lneto (see <a href="#3.4.9">§3.4.9</a>). 206 1.2 lneto 207 1.2 lneto 208 1.2 lneto <p> 209 1.2 lneto We use the term <em>sequence</em> to denote a table where 210 1.2 lneto the set of all positive numeric keys is equal to <em>{1..n}</em> 211 1.2 lneto for some integer <em>n</em>, 212 1.2 lneto which is called the length of the sequence (see <a href="#3.4.7">§3.4.7</a>). 213 1.1 mbalmer 214 1.1 mbalmer 215 1.1 mbalmer <p> 216 1.1 mbalmer Like indices, 217 1.2 lneto the values of table fields can be of any type. 218 1.1 mbalmer In particular, 219 1.1 mbalmer because functions are first-class values, 220 1.1 mbalmer table fields can contain functions. 221 1.2 lneto Thus tables can also carry <em>methods</em> (see <a href="#3.4.11">§3.4.11</a>). 222 1.2 lneto 223 1.2 lneto 224 1.2 lneto <p> 225 1.2 lneto The indexing of tables follows 226 1.2 lneto the definition of raw equality in the language. 227 1.2 lneto The expressions <code>a[i]</code> and <code>a[j]</code> 228 1.2 lneto denote the same table element 229 1.2 lneto if and only if <code>i</code> and <code>j</code> are raw equal 230 1.2 lneto (that is, equal without metamethods). 231 1.2 lneto 232 1.2 lneto 233 1.2 lneto <p> 234 1.2 lneto In particular, floats with integral values 235 1.2 lneto are equal to their respective integers 236 1.2 lneto (e.g., <code>1.0 == 1</code>). 237 1.2 lneto To avoid ambiguities, 238 1.2 lneto any float with integral value used as a key 239 1.2 lneto is converted to its respective integer. 240 1.2 lneto For instance, if you write <code>a[2.0] = true</code>, 241 1.2 lneto the actual key inserted into the table will be the 242 1.2 lneto integer <code>2</code>. 243 1.1 mbalmer 244 1.1 mbalmer 245 1.1 mbalmer <p> 246 1.1 mbalmer Tables, functions, threads, and (full) userdata values are <em>objects</em>: 247 1.1 mbalmer variables do not actually <em>contain</em> these values, 248 1.1 mbalmer only <em>references</em> to them. 249 1.1 mbalmer Assignment, parameter passing, and function returns 250 1.1 mbalmer always manipulate references to such values; 251 1.1 mbalmer these operations do not imply any kind of copy. 252 1.1 mbalmer 253 1.1 mbalmer 254 1.1 mbalmer <p> 255 1.1 mbalmer The library function <a href="#pdf-type"><code>type</code></a> returns a string describing the type 256 1.2 lneto of a given value (see <a href="#6.1">§6.1</a>). 257 1.2 lneto 258 1.1 mbalmer 259 1.1 mbalmer 260 1.1 mbalmer 261 1.2 lneto 262 1.2 lneto <h2>2.2 – <a name="2.2">Environments and the Global Environment</a></h2> 263 1.1 mbalmer 264 1.1 mbalmer <p> 265 1.2 lneto As will be discussed in <a href="#3.2">§3.2</a> and <a href="#3.3.3">§3.3.3</a>, 266 1.2 lneto any reference to a global name <code>var</code> is syntactically translated 267 1.2 lneto to <code>_ENV.var</code>. 268 1.2 lneto Moreover, every chunk is compiled in the scope of 269 1.2 lneto an external local variable called <code>_ENV</code> (see <a href="#3.3.2">§3.3.2</a>), 270 1.2 lneto so <code>_ENV</code> itself is never a global name in a chunk. 271 1.1 mbalmer 272 1.1 mbalmer 273 1.2 lneto <p> 274 1.2 lneto Despite the existence of this external <code>_ENV</code> variable and 275 1.2 lneto the translation of global names, 276 1.2 lneto <code>_ENV</code> is a completely regular name. 277 1.2 lneto In particular, 278 1.2 lneto you can define new variables and parameters with that name. 279 1.2 lneto Each reference to a global name uses the <code>_ENV</code> that is 280 1.2 lneto visible at that point in the program, 281 1.2 lneto following the usual visibility rules of Lua (see <a href="#3.5">§3.5</a>). 282 1.1 mbalmer 283 1.1 mbalmer 284 1.2 lneto <p> 285 1.2 lneto Any table used as the value of <code>_ENV</code> is called an <em>environment</em>. 286 1.1 mbalmer 287 1.1 mbalmer 288 1.2 lneto <p> 289 1.2 lneto Lua keeps a distinguished environment called the <em>global environment</em>. 290 1.2 lneto This value is kept at a special index in the C registry (see <a href="#4.5">§4.5</a>). 291 1.2 lneto In Lua, the variable <a href="#pdf-_G"><code>_G</code></a> is initialized with this same value. 292 1.1 mbalmer 293 1.1 mbalmer 294 1.1 mbalmer <p> 295 1.2 lneto When Lua compiles a chunk, 296 1.2 lneto it initializes the value of its <code>_ENV</code> upvalue 297 1.2 lneto with the global environment (see <a href="#pdf-load"><code>load</code></a>). 298 1.2 lneto Therefore, by default, 299 1.2 lneto global variables in Lua code refer to entries in the global environment. 300 1.2 lneto Moreover, all standard libraries are loaded in the global environment 301 1.2 lneto and several functions there operate on that environment. 302 1.2 lneto You can use <a href="#pdf-load"><code>load</code></a> (or <a href="#pdf-loadfile"><code>loadfile</code></a>) 303 1.2 lneto to load a chunk with a different environment. 304 1.2 lneto (In C, you have to load the chunk and then change the value 305 1.2 lneto of its first upvalue.) 306 1.1 mbalmer 307 1.1 mbalmer 308 1.1 mbalmer <p> 309 1.2 lneto If you change the global environment in the registry 310 1.2 lneto (through C code or the debug library), 311 1.2 lneto all chunks loaded after the change will get the new environment. 312 1.2 lneto Previously loaded chunks are not affected, however, 313 1.2 lneto as each has its own reference to the environment in its <code>_ENV</code> variable. 314 1.2 lneto Moreover, the variable <a href="#pdf-_G"><code>_G</code></a> 315 1.2 lneto (which is stored in the original global environment) 316 1.2 lneto is never updated by Lua. 317 1.2 lneto 318 1.1 mbalmer 319 1.1 mbalmer 320 1.1 mbalmer 321 1.1 mbalmer 322 1.2 lneto <h2>2.3 – <a name="2.3">Error Handling</a></h2> 323 1.1 mbalmer 324 1.1 mbalmer <p> 325 1.2 lneto Because Lua is an embedded extension language, 326 1.2 lneto all Lua actions start from C code in the host program 327 1.2 lneto calling a function from the Lua library (see <a href="#lua_pcall"><code>lua_pcall</code></a>). 328 1.2 lneto Whenever an error occurs during 329 1.2 lneto the compilation or execution of a Lua chunk, 330 1.2 lneto control returns to the host, 331 1.2 lneto which can take appropriate measures 332 1.2 lneto (such as printing an error message). 333 1.1 mbalmer 334 1.1 mbalmer 335 1.1 mbalmer <p> 336 1.2 lneto Lua code can explicitly generate an error by calling the 337 1.2 lneto <a href="#pdf-error"><code>error</code></a> function. 338 1.2 lneto If you need to catch errors in Lua, 339 1.2 lneto you can use <a href="#pdf-pcall"><code>pcall</code></a> or <a href="#pdf-xpcall"><code>xpcall</code></a> 340 1.2 lneto to call a given function in <em>protected mode</em>. 341 1.1 mbalmer 342 1.1 mbalmer 343 1.1 mbalmer <p> 344 1.2 lneto Whenever there is an error, 345 1.2 lneto an <em>error object</em> (also called an <em>error message</em>) 346 1.2 lneto is propagated with information about the error. 347 1.2 lneto Lua itself only generates errors where the error object is a string, 348 1.2 lneto but programs may generate errors with 349 1.2 lneto any value for the error object. 350 1.1 mbalmer 351 1.1 mbalmer 352 1.1 mbalmer <p> 353 1.2 lneto When you use <a href="#pdf-xpcall"><code>xpcall</code></a> or <a href="#lua_pcall"><code>lua_pcall</code></a>, 354 1.2 lneto you may give a <em>message handler</em> 355 1.2 lneto to be called in case of errors. 356 1.2 lneto This function is called with the original error message 357 1.2 lneto and returns a new error message. 358 1.2 lneto It is called before the error unwinds the stack, 359 1.2 lneto so that it can gather more information about the error, 360 1.2 lneto for instance by inspecting the stack and creating a stack traceback. 361 1.2 lneto This message handler is still protected by the protected call; 362 1.2 lneto so, an error inside the message handler 363 1.2 lneto will call the message handler again. 364 1.2 lneto If this loop goes on, Lua breaks it and returns an appropriate message. 365 1.1 mbalmer 366 1.1 mbalmer 367 1.1 mbalmer 368 1.1 mbalmer 369 1.1 mbalmer 370 1.2 lneto <h2>2.4 – <a name="2.4">Metatables and Metamethods</a></h2> 371 1.1 mbalmer 372 1.2 lneto <p> 373 1.2 lneto Every value in Lua can have a <em>metatable</em>. 374 1.2 lneto This <em>metatable</em> is an ordinary Lua table 375 1.2 lneto that defines the behavior of the original value 376 1.2 lneto under certain special operations. 377 1.2 lneto You can change several aspects of the behavior 378 1.2 lneto of operations over a value by setting specific fields in its metatable. 379 1.2 lneto For instance, when a non-numeric value is the operand of an addition, 380 1.2 lneto Lua checks for a function in the field "<code>__add</code>" of the value's metatable. 381 1.2 lneto If it finds one, 382 1.2 lneto Lua calls this function to perform the addition. 383 1.1 mbalmer 384 1.1 mbalmer 385 1.1 mbalmer <p> 386 1.2 lneto The keys in a metatable are derived from the <em>event</em> names; 387 1.2 lneto the corresponding values are called <em>metamethods</em>. 388 1.2 lneto In the previous example, the event is <code>"add"</code> 389 1.2 lneto and the metamethod is the function that performs the addition. 390 1.1 mbalmer 391 1.1 mbalmer 392 1.2 lneto <p> 393 1.2 lneto You can query the metatable of any value 394 1.2 lneto using the <a href="#pdf-getmetatable"><code>getmetatable</code></a> function. 395 1.1 mbalmer 396 1.1 mbalmer 397 1.1 mbalmer <p> 398 1.2 lneto You can replace the metatable of tables 399 1.2 lneto using the <a href="#pdf-setmetatable"><code>setmetatable</code></a> function. 400 1.2 lneto You cannot change the metatable of other types from Lua 401 1.2 lneto (except by using the debug library); 402 1.2 lneto you must use the C API for that. 403 1.1 mbalmer 404 1.1 mbalmer 405 1.1 mbalmer <p> 406 1.2 lneto Tables and full userdata have individual metatables 407 1.2 lneto (although multiple tables and userdata can share their metatables). 408 1.2 lneto Values of all other types share one single metatable per type; 409 1.2 lneto that is, there is one single metatable for all numbers, 410 1.2 lneto one for all strings, etc. 411 1.2 lneto By default, a value has no metatable, 412 1.2 lneto but the string library sets a metatable for the string type (see <a href="#6.4">§6.4</a>). 413 1.1 mbalmer 414 1.1 mbalmer 415 1.1 mbalmer <p> 416 1.2 lneto A metatable controls how an object behaves in 417 1.2 lneto arithmetic and bitwise operations, 418 1.2 lneto order comparisons, concatenation, length operation, calls, and indexing. 419 1.2 lneto A metatable also can define a function to be called 420 1.2 lneto when a userdata or a table is garbage collected. 421 1.1 mbalmer 422 1.1 mbalmer 423 1.1 mbalmer <p> 424 1.2 lneto A detailed list of events controlled by metatables is given next. 425 1.2 lneto Each operation is identified by its corresponding event name. 426 1.2 lneto The key for each event is a string with its name prefixed by 427 1.2 lneto two underscores, '<code>__</code>'; 428 1.2 lneto for instance, the key for operation "add" is the 429 1.2 lneto string "<code>__add</code>". 430 1.2 lneto Note that queries for metamethods are always raw; 431 1.2 lneto the access to a metamethod does not invoke other metamethods. 432 1.2 lneto You can emulate how Lua queries a metamethod for an object <code>obj</code> 433 1.2 lneto with the following code: 434 1.1 mbalmer 435 1.2 lneto <pre> 436 1.2 lneto rawget(getmetatable(obj) or {}, event_name) 437 1.2 lneto </pre> 438 1.1 mbalmer 439 1.2 lneto <p> 440 1.2 lneto For the unary operators (negation, length, and bitwise not), 441 1.2 lneto the metamethod is computed and called with a dummy second operand, 442 1.2 lneto equal to the first one. 443 1.2 lneto This extra operand is only to simplify Lua's internals 444 1.2 lneto (by making these operators behave like a binary operation) 445 1.2 lneto and may be removed in future versions. 446 1.2 lneto (For most uses this extra operand is irrelevant.) 447 1.1 mbalmer 448 1.1 mbalmer 449 1.1 mbalmer 450 1.2 lneto <ul> 451 1.1 mbalmer 452 1.2 lneto <li><b>"add": </b> 453 1.2 lneto the <code>+</code> operation. 454 1.1 mbalmer 455 1.2 lneto If any operand for an addition is not a number 456 1.2 lneto (nor a string coercible to a number), 457 1.2 lneto Lua will try to call a metamethod. 458 1.2 lneto First, Lua will check the first operand (even if it is valid). 459 1.2 lneto If that operand does not define a metamethod for the "<code>__add</code>" event, 460 1.2 lneto then Lua will check the second operand. 461 1.2 lneto If Lua cannot find a metamethod, 462 1.2 lneto it raises an error. 463 1.2 lneto Otherwise, 464 1.2 lneto it calls the metamethod with the two operands as arguments, 465 1.2 lneto and the result of the call 466 1.2 lneto (adjusted to one value) 467 1.2 lneto is the result of the operation. 468 1.2 lneto </li> 469 1.1 mbalmer 470 1.2 lneto <li><b>"sub": </b> 471 1.2 lneto the <code>-</code> operation. 472 1.1 mbalmer 473 1.2 lneto Behavior similar to the "add" operation. 474 1.2 lneto </li> 475 1.1 mbalmer 476 1.2 lneto <li><b>"mul": </b> 477 1.2 lneto the <code>*</code> operation. 478 1.1 mbalmer 479 1.2 lneto Behavior similar to the "add" operation. 480 1.2 lneto </li> 481 1.1 mbalmer 482 1.2 lneto <li><b>"div": </b> 483 1.2 lneto the <code>/</code> operation. 484 1.1 mbalmer 485 1.2 lneto Behavior similar to the "add" operation. 486 1.2 lneto </li> 487 1.1 mbalmer 488 1.2 lneto <li><b>"mod": </b> 489 1.2 lneto the <code>%</code> operation. 490 1.1 mbalmer 491 1.2 lneto Behavior similar to the "add" operation. 492 1.2 lneto </li> 493 1.1 mbalmer 494 1.2 lneto <li><b>"pow": </b> 495 1.2 lneto the <code>^</code> (exponentiation) operation. 496 1.1 mbalmer 497 1.2 lneto Behavior similar to the "add" operation. 498 1.2 lneto </li> 499 1.1 mbalmer 500 1.2 lneto <li><b>"unm": </b> 501 1.2 lneto the <code>-</code> (unary minus) operation. 502 1.1 mbalmer 503 1.2 lneto Behavior similar to the "add" operation. 504 1.2 lneto </li> 505 1.1 mbalmer 506 1.2 lneto <li><b>"idiv": </b> 507 1.2 lneto the <code>//</code> (integer division) operation. 508 1.1 mbalmer 509 1.2 lneto Behavior similar to the "add" operation, 510 1.2 lneto except that Lua will try a metamethod 511 1.2 lneto if any operator is neither an integer 512 1.2 lneto nor a value coercible to an integer (see <a href="#3.4.3">§3.4.3</a>). 513 1.2 lneto </li> 514 1.1 mbalmer 515 1.2 lneto <li><b>"band": </b> 516 1.2 lneto the <code>&</code> (bitwise and) operation. 517 1.1 mbalmer 518 1.2 lneto Behavior similar to the "idiv" operation. 519 1.2 lneto </li> 520 1.1 mbalmer 521 1.2 lneto <li><b>"bor": </b> 522 1.2 lneto the <code>|</code> (bitwise or) operation. 523 1.1 mbalmer 524 1.2 lneto Behavior similar to the "band" operation. 525 1.2 lneto </li> 526 1.1 mbalmer 527 1.2 lneto <li><b>"bxor": </b> 528 1.2 lneto the <code>~</code> (bitwise exclusive or) operation. 529 1.1 mbalmer 530 1.2 lneto Behavior similar to the "band" operation. 531 1.2 lneto </li> 532 1.1 mbalmer 533 1.2 lneto <li><b>"bnot": </b> 534 1.2 lneto the <code>~</code> (bitwise unary not) operation. 535 1.1 mbalmer 536 1.2 lneto Behavior similar to the "band" operation. 537 1.2 lneto </li> 538 1.1 mbalmer 539 1.2 lneto <li><b>"shl": </b> 540 1.2 lneto the <code><<</code> (bitwise left shift) operation. 541 1.1 mbalmer 542 1.2 lneto Behavior similar to the "band" operation. 543 1.2 lneto </li> 544 1.1 mbalmer 545 1.2 lneto <li><b>"shr": </b> 546 1.2 lneto the <code>>></code> (bitwise right shift) operation. 547 1.1 mbalmer 548 1.2 lneto Behavior similar to the "band" operation. 549 1.2 lneto </li> 550 1.1 mbalmer 551 1.2 lneto <li><b>"concat": </b> 552 1.2 lneto the <code>..</code> (concatenation) operation. 553 1.1 mbalmer 554 1.2 lneto Behavior similar to the "add" operation, 555 1.2 lneto except that Lua will try a metamethod 556 1.2 lneto if any operator is neither a string nor a number 557 1.2 lneto (which is always coercible to a string). 558 1.2 lneto </li> 559 1.2 lneto 560 1.2 lneto <li><b>"len": </b> 561 1.2 lneto the <code>#</code> (length) operation. 562 1.2 lneto 563 1.2 lneto If the object is not a string, 564 1.2 lneto Lua will try its metamethod. 565 1.2 lneto If there is a metamethod, 566 1.2 lneto Lua calls it with the object as argument, 567 1.2 lneto and the result of the call 568 1.2 lneto (always adjusted to one value) 569 1.2 lneto is the result of the operation. 570 1.2 lneto If there is no metamethod but the object is a table, 571 1.2 lneto then Lua uses the table length operation (see <a href="#3.4.7">§3.4.7</a>). 572 1.2 lneto Otherwise, Lua raises an error. 573 1.2 lneto </li> 574 1.1 mbalmer 575 1.2 lneto <li><b>"eq": </b> 576 1.2 lneto the <code>==</code> (equal) operation. 577 1.1 mbalmer 578 1.2 lneto Behavior similar to the "add" operation, 579 1.2 lneto except that Lua will try a metamethod only when the values 580 1.2 lneto being compared are either both tables or both full userdata 581 1.2 lneto and they are not primitively equal. 582 1.2 lneto The result of the call is always converted to a boolean. 583 1.2 lneto </li> 584 1.1 mbalmer 585 1.2 lneto <li><b>"lt": </b> 586 1.2 lneto the <code><</code> (less than) operation. 587 1.1 mbalmer 588 1.2 lneto Behavior similar to the "add" operation, 589 1.2 lneto except that Lua will try a metamethod only when the values 590 1.2 lneto being compared are neither both numbers nor both strings. 591 1.2 lneto The result of the call is always converted to a boolean. 592 1.2 lneto </li> 593 1.2 lneto 594 1.2 lneto <li><b>"le": </b> 595 1.2 lneto the <code><=</code> (less equal) operation. 596 1.2 lneto 597 1.2 lneto Unlike other operations, 598 1.2 lneto The less-equal operation can use two different events. 599 1.2 lneto First, Lua looks for the "<code>__le</code>" metamethod in both operands, 600 1.2 lneto like in the "lt" operation. 601 1.2 lneto If it cannot find such a metamethod, 602 1.2 lneto then it will try the "<code>__lt</code>" event, 603 1.2 lneto assuming that <code>a <= b</code> is equivalent to <code>not (b < a)</code>. 604 1.2 lneto As with the other comparison operators, 605 1.2 lneto the result is always a boolean. 606 1.2 lneto </li> 607 1.1 mbalmer 608 1.2 lneto <li><b>"index": </b> 609 1.2 lneto The indexing access <code>table[key]</code>. 610 1.1 mbalmer 611 1.2 lneto This event happens when <code>table</code> is not a table or 612 1.2 lneto when <code>key</code> is not present in <code>table</code>. 613 1.2 lneto The metamethod is looked up in <code>table</code>. 614 1.1 mbalmer 615 1.1 mbalmer 616 1.1 mbalmer <p> 617 1.2 lneto Despite the name, 618 1.2 lneto the metamethod for this event can be either a function or a table. 619 1.2 lneto If it is a function, 620 1.2 lneto it is called with <code>table</code> and <code>key</code> as arguments. 621 1.2 lneto If it is a table, 622 1.2 lneto the final result is the result of indexing this table with <code>key</code>. 623 1.2 lneto (This indexing is regular, not raw, 624 1.2 lneto and therefore can trigger another metamethod.) 625 1.2 lneto </li> 626 1.2 lneto 627 1.2 lneto <li><b>"newindex": </b> 628 1.2 lneto The indexing assignment <code>table[key] = value</code>. 629 1.1 mbalmer 630 1.2 lneto Like the index event, 631 1.2 lneto this event happens when <code>table</code> is not a table or 632 1.2 lneto when <code>key</code> is not present in <code>table</code>. 633 1.2 lneto The metamethod is looked up in <code>table</code>. 634 1.1 mbalmer 635 1.1 mbalmer 636 1.1 mbalmer <p> 637 1.2 lneto Again like with indexing, 638 1.2 lneto the metamethod for this event can be either a function or a table. 639 1.2 lneto If it is a function, 640 1.2 lneto it is called with <code>table</code>, <code>key</code>, and <code>value</code> as arguments. 641 1.2 lneto If it is a table, 642 1.2 lneto Lua does an indexing assignment to this table with the same key and value. 643 1.2 lneto (This assignment is regular, not raw, 644 1.2 lneto and therefore can trigger another metamethod.) 645 1.1 mbalmer 646 1.1 mbalmer 647 1.2 lneto <p> 648 1.2 lneto Whenever there is a metamethod, 649 1.2 lneto Lua does not perform the primitive assignment. 650 1.2 lneto (If necessary, 651 1.2 lneto the metamethod itself can call <a href="#pdf-rawset"><code>rawset</code></a> 652 1.2 lneto to do the assignment.) 653 1.2 lneto </li> 654 1.1 mbalmer 655 1.2 lneto <li><b>"call": </b> 656 1.2 lneto The call operation <code>func(args)</code>. 657 1.1 mbalmer 658 1.2 lneto This event happens when Lua tries to call a non-function value 659 1.2 lneto (that is, <code>func</code> is not a function). 660 1.2 lneto The metamethod is looked up in <code>func</code>. 661 1.2 lneto If present, 662 1.2 lneto the metamethod is called with <code>func</code> as its first argument, 663 1.2 lneto followed by the arguments of the original call (<code>args</code>). 664 1.2 lneto </li> 665 1.1 mbalmer 666 1.2 lneto </ul> 667 1.1 mbalmer 668 1.1 mbalmer 669 1.1 mbalmer 670 1.1 mbalmer 671 1.2 lneto <h2>2.5 – <a name="2.5">Garbage Collection</a></h2> 672 1.1 mbalmer 673 1.1 mbalmer <p> 674 1.2 lneto Lua performs automatic memory management. 675 1.2 lneto This means that 676 1.2 lneto you have to worry neither about allocating memory for new objects 677 1.2 lneto nor about freeing it when the objects are no longer needed. 678 1.2 lneto Lua manages memory automatically by running 679 1.2 lneto a <em>garbage collector</em> to collect all <em>dead objects</em> 680 1.2 lneto (that is, objects that are no longer accessible from Lua). 681 1.2 lneto All memory used by Lua is subject to automatic management: 682 1.2 lneto strings, tables, userdata, functions, threads, internal structures, etc. 683 1.1 mbalmer 684 1.2 lneto 685 1.2 lneto <p> 686 1.2 lneto Lua implements an incremental mark-and-sweep collector. 687 1.2 lneto It uses two numbers to control its garbage-collection cycles: 688 1.2 lneto the <em>garbage-collector pause</em> and 689 1.2 lneto the <em>garbage-collector step multiplier</em>. 690 1.2 lneto Both use percentage points as units 691 1.2 lneto (e.g., a value of 100 means an internal value of 1). 692 1.1 mbalmer 693 1.1 mbalmer 694 1.1 mbalmer <p> 695 1.2 lneto The garbage-collector pause 696 1.2 lneto controls how long the collector waits before starting a new cycle. 697 1.2 lneto Larger values make the collector less aggressive. 698 1.2 lneto Values smaller than 100 mean the collector will not wait to 699 1.2 lneto start a new cycle. 700 1.2 lneto A value of 200 means that the collector waits for the total memory in use 701 1.2 lneto to double before starting a new cycle. 702 1.2 lneto 703 1.1 mbalmer 704 1.2 lneto <p> 705 1.2 lneto The garbage-collector step multiplier 706 1.2 lneto controls the relative speed of the collector relative to 707 1.2 lneto memory allocation. 708 1.2 lneto Larger values make the collector more aggressive but also increase 709 1.2 lneto the size of each incremental step. 710 1.2 lneto You should not use values smaller than 100, 711 1.2 lneto as they make the collector too slow and 712 1.2 lneto can result in the collector never finishing a cycle. 713 1.2 lneto The default is 200, 714 1.2 lneto which means that the collector runs at "twice" 715 1.2 lneto the speed of memory allocation. 716 1.1 mbalmer 717 1.1 mbalmer 718 1.2 lneto <p> 719 1.2 lneto If you set the step multiplier to a very large number 720 1.2 lneto (larger than 10% of the maximum number of 721 1.2 lneto bytes that the program may use), 722 1.2 lneto the collector behaves like a stop-the-world collector. 723 1.2 lneto If you then set the pause to 200, 724 1.2 lneto the collector behaves as in old Lua versions, 725 1.2 lneto doing a complete collection every time Lua doubles its 726 1.2 lneto memory usage. 727 1.1 mbalmer 728 1.1 mbalmer 729 1.2 lneto <p> 730 1.2 lneto You can change these numbers by calling <a href="#lua_gc"><code>lua_gc</code></a> in C 731 1.2 lneto or <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> in Lua. 732 1.2 lneto You can also use these functions to control 733 1.2 lneto the collector directly (e.g., stop and restart it). 734 1.1 mbalmer 735 1.1 mbalmer 736 1.1 mbalmer 737 1.2 lneto <h3>2.5.1 – <a name="2.5.1">Garbage-Collection Metamethods</a></h3> 738 1.1 mbalmer 739 1.2 lneto <p> 740 1.2 lneto You can set garbage-collector metamethods for tables 741 1.2 lneto and, using the C API, 742 1.2 lneto for full userdata (see <a href="#2.4">§2.4</a>). 743 1.2 lneto These metamethods are also called <em>finalizers</em>. 744 1.2 lneto Finalizers allow you to coordinate Lua's garbage collection 745 1.2 lneto with external resource management 746 1.2 lneto (such as closing files, network or database connections, 747 1.2 lneto or freeing your own memory). 748 1.1 mbalmer 749 1.1 mbalmer 750 1.1 mbalmer <p> 751 1.2 lneto For an object (table or userdata) to be finalized when collected, 752 1.2 lneto you must <em>mark</em> it for finalization. 753 1.1 mbalmer 754 1.2 lneto You mark an object for finalization when you set its metatable 755 1.2 lneto and the metatable has a field indexed by the string "<code>__gc</code>". 756 1.2 lneto Note that if you set a metatable without a <code>__gc</code> field 757 1.2 lneto and later create that field in the metatable, 758 1.2 lneto the object will not be marked for finalization. 759 1.2 lneto However, after an object is marked, 760 1.2 lneto you can freely change the <code>__gc</code> field of its metatable. 761 1.1 mbalmer 762 1.1 mbalmer 763 1.2 lneto <p> 764 1.2 lneto When a marked object becomes garbage, 765 1.2 lneto it is not collected immediately by the garbage collector. 766 1.2 lneto Instead, Lua puts it in a list. 767 1.2 lneto After the collection, 768 1.2 lneto Lua goes through that list: 769 1.2 lneto For each object, 770 1.2 lneto it checks the object's <code>__gc</code> metamethod; 771 1.2 lneto if it is a function, 772 1.2 lneto Lua calls it with the object as its single argument. 773 1.2 lneto (If the metamethod is not a function, 774 1.2 lneto Lua simply ignores it.) 775 1.1 mbalmer 776 1.1 mbalmer 777 1.2 lneto <p> 778 1.2 lneto At the end of each garbage-collection cycle, 779 1.2 lneto the finalizers for objects are called in 780 1.2 lneto the reverse order that they were marked for finalization, 781 1.2 lneto among those collected in that cycle; 782 1.2 lneto that is, the first finalizer to be called is the one associated 783 1.2 lneto with the object marked last in the program. 784 1.2 lneto The execution of each finalizer may occur at any point during 785 1.2 lneto the execution of the regular code. 786 1.1 mbalmer 787 1.1 mbalmer 788 1.2 lneto <p> 789 1.2 lneto Because the object being collected must still be used by the finalizer, 790 1.2 lneto it (and other objects accessible only through it) 791 1.2 lneto must be <em>resurrected</em> by Lua. 792 1.2 lneto Usually, this resurrection is transient, 793 1.2 lneto and the object memory is freed in the next garbage-collection cycle. 794 1.2 lneto However, if the finalizer stores the object in some global place 795 1.2 lneto (e.g., a global variable), 796 1.2 lneto then there is a permanent resurrection. 797 1.2 lneto Moreover, if the finalizer marks a finalizing object for finalization again, 798 1.2 lneto its finalizer will be called again in the next cycle where the 799 1.2 lneto object is unreachable. 800 1.2 lneto In any case, 801 1.2 lneto the object memory is freed only in the GC cycle where 802 1.2 lneto the object is unreachable and not marked for finalization. 803 1.1 mbalmer 804 1.1 mbalmer 805 1.2 lneto <p> 806 1.2 lneto When you close a state (see <a href="#lua_close"><code>lua_close</code></a>), 807 1.2 lneto Lua calls the finalizers of all objects marked for finalization, 808 1.2 lneto following the reverse order that they were marked. 809 1.2 lneto If any finalizer marks objects for collection during that phase, 810 1.2 lneto these marks have no effect. 811 1.1 mbalmer 812 1.1 mbalmer 813 1.1 mbalmer 814 1.1 mbalmer 815 1.1 mbalmer 816 1.2 lneto <h3>2.5.2 – <a name="2.5.2">Weak Tables</a></h3> 817 1.2 lneto 818 1.2 lneto <p> 819 1.2 lneto A <em>weak table</em> is a table whose elements are 820 1.2 lneto <em>weak references</em>. 821 1.2 lneto A weak reference is ignored by the garbage collector. 822 1.2 lneto In other words, 823 1.2 lneto if the only references to an object are weak references, 824 1.2 lneto then the garbage collector will collect that object. 825 1.2 lneto 826 1.2 lneto 827 1.2 lneto <p> 828 1.2 lneto A weak table can have weak keys, weak values, or both. 829 1.2 lneto A table with weak keys allows the collection of its keys, 830 1.2 lneto but prevents the collection of its values. 831 1.2 lneto A table with both weak keys and weak values allows the collection of 832 1.2 lneto both keys and values. 833 1.2 lneto In any case, if either the key or the value is collected, 834 1.2 lneto the whole pair is removed from the table. 835 1.2 lneto The weakness of a table is controlled by the 836 1.2 lneto <code>__mode</code> field of its metatable. 837 1.2 lneto If the <code>__mode</code> field is a string containing the character '<code>k</code>', 838 1.2 lneto the keys in the table are weak. 839 1.2 lneto If <code>__mode</code> contains '<code>v</code>', 840 1.2 lneto the values in the table are weak. 841 1.1 mbalmer 842 1.1 mbalmer 843 1.2 lneto <p> 844 1.2 lneto A table with weak keys and strong values 845 1.2 lneto is also called an <em>ephemeron table</em>. 846 1.2 lneto In an ephemeron table, 847 1.2 lneto a value is considered reachable only if its key is reachable. 848 1.2 lneto In particular, 849 1.2 lneto if the only reference to a key comes through its value, 850 1.2 lneto the pair is removed. 851 1.1 mbalmer 852 1.1 mbalmer 853 1.2 lneto <p> 854 1.2 lneto Any change in the weakness of a table may take effect only 855 1.2 lneto at the next collect cycle. 856 1.2 lneto In particular, if you change the weakness to a stronger mode, 857 1.2 lneto Lua may still collect some items from that table 858 1.2 lneto before the change takes effect. 859 1.1 mbalmer 860 1.1 mbalmer 861 1.2 lneto <p> 862 1.2 lneto Only objects that have an explicit construction 863 1.2 lneto are removed from weak tables. 864 1.2 lneto Values, such as numbers and light C functions, 865 1.2 lneto are not subject to garbage collection, 866 1.2 lneto and therefore are not removed from weak tables 867 1.2 lneto (unless its associated value is collected). 868 1.2 lneto Although strings are subject to garbage collection, 869 1.2 lneto they do not have an explicit construction, 870 1.2 lneto and therefore are not removed from weak tables. 871 1.1 mbalmer 872 1.1 mbalmer 873 1.1 mbalmer <p> 874 1.2 lneto Resurrected objects 875 1.2 lneto (that is, objects being finalized 876 1.2 lneto and objects accessible only through objects being finalized) 877 1.2 lneto have a special behavior in weak tables. 878 1.2 lneto They are removed from weak values before running their finalizers, 879 1.2 lneto but are removed from weak keys only in the next collection 880 1.2 lneto after running their finalizers, when such objects are actually freed. 881 1.2 lneto This behavior allows the finalizer to access properties 882 1.2 lneto associated with the object through weak tables. 883 1.1 mbalmer 884 1.1 mbalmer 885 1.1 mbalmer <p> 886 1.2 lneto If a weak table is among the resurrected objects in a collection cycle, 887 1.2 lneto it may not be properly cleared until the next cycle. 888 1.1 mbalmer 889 1.1 mbalmer 890 1.1 mbalmer 891 1.1 mbalmer 892 1.1 mbalmer 893 1.1 mbalmer 894 1.1 mbalmer 895 1.2 lneto <h2>2.6 – <a name="2.6">Coroutines</a></h2> 896 1.1 mbalmer 897 1.1 mbalmer <p> 898 1.2 lneto Lua supports coroutines, 899 1.2 lneto also called <em>collaborative multithreading</em>. 900 1.2 lneto A coroutine in Lua represents an independent thread of execution. 901 1.2 lneto Unlike threads in multithread systems, however, 902 1.2 lneto a coroutine only suspends its execution by explicitly calling 903 1.2 lneto a yield function. 904 1.1 mbalmer 905 1.1 mbalmer 906 1.1 mbalmer <p> 907 1.2 lneto You create a coroutine by calling <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>. 908 1.2 lneto Its sole argument is a function 909 1.2 lneto that is the main function of the coroutine. 910 1.2 lneto The <code>create</code> function only creates a new coroutine and 911 1.2 lneto returns a handle to it (an object of type <em>thread</em>); 912 1.2 lneto it does not start the coroutine. 913 1.1 mbalmer 914 1.1 mbalmer 915 1.1 mbalmer <p> 916 1.2 lneto You execute a coroutine by calling <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. 917 1.2 lneto When you first call <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>, 918 1.2 lneto passing as its first argument 919 1.2 lneto a thread returned by <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>, 920 1.2 lneto the coroutine starts its execution, 921 1.2 lneto at the first line of its main function. 922 1.2 lneto Extra arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> are passed on 923 1.2 lneto to the coroutine main function. 924 1.2 lneto After the coroutine starts running, 925 1.2 lneto it runs until it terminates or <em>yields</em>. 926 1.1 mbalmer 927 1.1 mbalmer 928 1.1 mbalmer <p> 929 1.2 lneto A coroutine can terminate its execution in two ways: 930 1.2 lneto normally, when its main function returns 931 1.2 lneto (explicitly or implicitly, after the last instruction); 932 1.2 lneto and abnormally, if there is an unprotected error. 933 1.2 lneto In the first case, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>true</b>, 934 1.2 lneto plus any values returned by the coroutine main function. 935 1.2 lneto In case of errors, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>false</b> 936 1.2 lneto plus an error message. 937 1.1 mbalmer 938 1.1 mbalmer 939 1.1 mbalmer <p> 940 1.2 lneto A coroutine yields by calling <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>. 941 1.2 lneto When a coroutine yields, 942 1.2 lneto the corresponding <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns immediately, 943 1.2 lneto even if the yield happens inside nested function calls 944 1.2 lneto (that is, not in the main function, 945 1.2 lneto but in a function directly or indirectly called by the main function). 946 1.2 lneto In the case of a yield, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> also returns <b>true</b>, 947 1.2 lneto plus any values passed to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>. 948 1.2 lneto The next time you resume the same coroutine, 949 1.2 lneto it continues its execution from the point where it yielded, 950 1.2 lneto with the call to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a> returning any extra 951 1.2 lneto arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. 952 1.1 mbalmer 953 1.1 mbalmer 954 1.1 mbalmer <p> 955 1.2 lneto Like <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>, 956 1.2 lneto the <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> function also creates a coroutine, 957 1.2 lneto but instead of returning the coroutine itself, 958 1.2 lneto it returns a function that, when called, resumes the coroutine. 959 1.2 lneto Any arguments passed to this function 960 1.2 lneto go as extra arguments to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. 961 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>, 962 1.2 lneto except the first one (the boolean error code). 963 1.2 lneto Unlike <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>, 964 1.2 lneto <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> does not catch errors; 965 1.2 lneto any error is propagated to the caller. 966 1.1 mbalmer 967 1.1 mbalmer 968 1.2 lneto <p> 969 1.2 lneto As an example of how coroutines work, 970 1.2 lneto consider the following code: 971 1.1 mbalmer 972 1.1 mbalmer <pre> 973 1.2 lneto function foo (a) 974 1.2 lneto print("foo", a) 975 1.2 lneto return coroutine.yield(2*a) 976 1.2 lneto end 977 1.2 lneto 978 1.2 lneto co = coroutine.create(function (a,b) 979 1.2 lneto print("co-body", a, b) 980 1.2 lneto local r = foo(a+1) 981 1.2 lneto print("co-body", r) 982 1.2 lneto local r, s = coroutine.yield(a+b, a-b) 983 1.2 lneto print("co-body", r, s) 984 1.2 lneto return b, "end" 985 1.2 lneto end) 986 1.2 lneto 987 1.2 lneto print("main", coroutine.resume(co, 1, 10)) 988 1.2 lneto print("main", coroutine.resume(co, "r")) 989 1.2 lneto print("main", coroutine.resume(co, "x", "y")) 990 1.2 lneto print("main", coroutine.resume(co, "x", "y")) 991 1.1 mbalmer </pre><p> 992 1.2 lneto When you run it, it produces the following output: 993 1.1 mbalmer 994 1.2 lneto <pre> 995 1.2 lneto co-body 1 10 996 1.2 lneto foo 2 997 1.2 lneto main true 4 998 1.2 lneto co-body r 999 1.2 lneto main true 11 -9 1000 1.2 lneto co-body x y 1001 1.2 lneto main true 10 end 1002 1.2 lneto main false cannot resume dead coroutine 1003 1.2 lneto </pre> 1004 1.1 mbalmer 1005 1.2 lneto <p> 1006 1.2 lneto You can also create and manipulate coroutines through the C API: 1007 1.2 lneto see functions <a href="#lua_newthread"><code>lua_newthread</code></a>, <a href="#lua_resume"><code>lua_resume</code></a>, 1008 1.2 lneto and <a href="#lua_yield"><code>lua_yield</code></a>. 1009 1.1 mbalmer 1010 1.1 mbalmer 1011 1.1 mbalmer 1012 1.1 mbalmer 1013 1.1 mbalmer 1014 1.2 lneto <h1>3 – <a name="3">The Language</a></h1> 1015 1.1 mbalmer 1016 1.1 mbalmer <p> 1017 1.2 lneto This section describes the lexis, the syntax, and the semantics of Lua. 1018 1.2 lneto In other words, 1019 1.2 lneto this section describes 1020 1.2 lneto which tokens are valid, 1021 1.2 lneto how they can be combined, 1022 1.2 lneto and what their combinations mean. 1023 1.1 mbalmer 1024 1.1 mbalmer 1025 1.1 mbalmer <p> 1026 1.2 lneto Language constructs will be explained using the usual extended BNF notation, 1027 1.2 lneto in which 1028 1.2 lneto {<em>a</em>} means 0 or more <em>a</em>'s, and 1029 1.2 lneto [<em>a</em>] means an optional <em>a</em>. 1030 1.2 lneto Non-terminals are shown like non-terminal, 1031 1.2 lneto keywords are shown like <b>kword</b>, 1032 1.2 lneto and other terminal symbols are shown like ‘<b>=</b>’. 1033 1.2 lneto The complete syntax of Lua can be found in <a href="#9">§9</a> 1034 1.2 lneto at the end of this manual. 1035 1.1 mbalmer 1036 1.1 mbalmer 1037 1.1 mbalmer 1038 1.2 lneto <h2>3.1 – <a name="3.1">Lexical Conventions</a></h2> 1039 1.1 mbalmer 1040 1.1 mbalmer <p> 1041 1.2 lneto Lua is a free-form language. 1042 1.2 lneto It ignores spaces (including new lines) and comments 1043 1.2 lneto between lexical elements (tokens), 1044 1.2 lneto except as delimiters between names and keywords. 1045 1.1 mbalmer 1046 1.1 mbalmer 1047 1.1 mbalmer <p> 1048 1.2 lneto <em>Names</em> 1049 1.2 lneto (also called <em>identifiers</em>) 1050 1.2 lneto in Lua can be any string of letters, 1051 1.2 lneto digits, and underscores, 1052 1.2 lneto not beginning with a digit. 1053 1.2 lneto Identifiers are used to name variables, table fields, and labels. 1054 1.1 mbalmer 1055 1.1 mbalmer 1056 1.2 lneto <p> 1057 1.2 lneto The following <em>keywords</em> are reserved 1058 1.2 lneto and cannot be used as names: 1059 1.1 mbalmer 1060 1.1 mbalmer 1061 1.2 lneto <pre> 1062 1.2 lneto and break do else elseif end 1063 1.2 lneto false for function goto if in 1064 1.2 lneto local nil not or repeat return 1065 1.2 lneto then true until while 1066 1.2 lneto </pre> 1067 1.1 mbalmer 1068 1.2 lneto <p> 1069 1.2 lneto Lua is a case-sensitive language: 1070 1.2 lneto <code>and</code> is a reserved word, but <code>And</code> and <code>AND</code> 1071 1.2 lneto are two different, valid names. 1072 1.2 lneto As a convention, 1073 1.2 lneto programs should avoid creating 1074 1.2 lneto names that start with an underscore followed by 1075 1.2 lneto one or more uppercase letters (such as <a href="#pdf-_VERSION"><code>_VERSION</code></a>). 1076 1.1 mbalmer 1077 1.1 mbalmer 1078 1.1 mbalmer <p> 1079 1.2 lneto The following strings denote other tokens: 1080 1.1 mbalmer 1081 1.1 mbalmer <pre> 1082 1.2 lneto + - * / % ^ # 1083 1.2 lneto & ~ | << >> // 1084 1.2 lneto == ~= <= >= < > = 1085 1.2 lneto ( ) { } [ ] :: 1086 1.2 lneto ; : , . .. ... 1087 1.2 lneto </pre> 1088 1.1 mbalmer 1089 1.1 mbalmer <p> 1090 1.2 lneto <em>Literal strings</em> 1091 1.2 lneto can be delimited by matching single or double quotes, 1092 1.2 lneto and can contain the following C-like escape sequences: 1093 1.2 lneto '<code>\a</code>' (bell), 1094 1.2 lneto '<code>\b</code>' (backspace), 1095 1.2 lneto '<code>\f</code>' (form feed), 1096 1.2 lneto '<code>\n</code>' (newline), 1097 1.2 lneto '<code>\r</code>' (carriage return), 1098 1.2 lneto '<code>\t</code>' (horizontal tab), 1099 1.2 lneto '<code>\v</code>' (vertical tab), 1100 1.2 lneto '<code>\\</code>' (backslash), 1101 1.2 lneto '<code>\"</code>' (quotation mark [double quote]), 1102 1.2 lneto and '<code>\'</code>' (apostrophe [single quote]). 1103 1.2 lneto A backslash followed by a real newline 1104 1.2 lneto results in a newline in the string. 1105 1.2 lneto The escape sequence '<code>\z</code>' skips the following span 1106 1.2 lneto of white-space characters, 1107 1.2 lneto including line breaks; 1108 1.2 lneto it is particularly useful to break and indent a long literal string 1109 1.2 lneto into multiple lines without adding the newlines and spaces 1110 1.2 lneto into the string contents. 1111 1.1 mbalmer 1112 1.1 mbalmer 1113 1.1 mbalmer <p> 1114 1.2 lneto A byte in a literal string can also be specified by its numerical value. 1115 1.2 lneto This can be done with the escape sequence <code>\x<em>XX</em></code>, 1116 1.2 lneto where <em>XX</em> is a sequence of exactly two hexadecimal digits, 1117 1.2 lneto or with the escape sequence <code>\<em>ddd</em></code>, 1118 1.2 lneto where <em>ddd</em> is a sequence of up to three decimal digits. 1119 1.2 lneto (Note that if a decimal escape is to be followed by a digit, 1120 1.2 lneto it must be expressed using exactly three digits.) 1121 1.2 lneto Strings in Lua can contain any 8-bit value, including embedded zeros, 1122 1.2 lneto which can be specified as '<code>\0</code>'. 1123 1.1 mbalmer 1124 1.1 mbalmer 1125 1.2 lneto <p> 1126 1.2 lneto The UTF-8 encoding of a Unicode character 1127 1.2 lneto can be inserted in a literal string with 1128 1.2 lneto the escape sequence <code>\u{<em>XXX</em>}</code> 1129 1.2 lneto (note the mandatory enclosing brackets), 1130 1.2 lneto where <em>XXX</em> is a sequence of one or more hexadecimal digits 1131 1.2 lneto representing the character code point. 1132 1.1 mbalmer 1133 1.1 mbalmer 1134 1.2 lneto <p> 1135 1.2 lneto Literal strings can also be defined using a long format 1136 1.2 lneto enclosed by <em>long brackets</em>. 1137 1.2 lneto We define an <em>opening long bracket of level <em>n</em></em> as an opening 1138 1.2 lneto square bracket followed by <em>n</em> equal signs followed by another 1139 1.2 lneto opening square bracket. 1140 1.2 lneto So, an opening long bracket of level 0 is written as <code>[[</code>, 1141 1.2 lneto an opening long bracket of level 1 is written as <code>[=[</code>, 1142 1.2 lneto and so on. 1143 1.2 lneto A <em>closing long bracket</em> is defined similarly; 1144 1.2 lneto for instance, 1145 1.2 lneto a closing long bracket of level 4 is written as <code>]====]</code>. 1146 1.2 lneto A <em>long literal</em> starts with an opening long bracket of any level and 1147 1.2 lneto ends at the first closing long bracket of the same level. 1148 1.2 lneto It can contain any text except a closing bracket of the proper level. 1149 1.2 lneto Literals in this bracketed form can run for several lines, 1150 1.2 lneto do not interpret any escape sequences, 1151 1.2 lneto and ignore long brackets of any other level. 1152 1.2 lneto Any kind of end-of-line sequence 1153 1.2 lneto (carriage return, newline, carriage return followed by newline, 1154 1.2 lneto or newline followed by carriage return) 1155 1.2 lneto is converted to a simple newline. 1156 1.1 mbalmer 1157 1.1 mbalmer 1158 1.2 lneto <p> 1159 1.2 lneto Any byte in a literal string not 1160 1.2 lneto explicitly affected by the previous rules represents itself. 1161 1.2 lneto However, Lua opens files for parsing in text mode, 1162 1.2 lneto and the system file functions may have problems with 1163 1.2 lneto some control characters. 1164 1.2 lneto So, it is safer to represent 1165 1.2 lneto non-text data as a quoted literal with 1166 1.2 lneto explicit escape sequences for non-text characters. 1167 1.1 mbalmer 1168 1.1 mbalmer 1169 1.2 lneto <p> 1170 1.2 lneto For convenience, 1171 1.2 lneto when the opening long bracket is immediately followed by a newline, 1172 1.2 lneto the newline is not included in the string. 1173 1.2 lneto As an example, in a system using ASCII 1174 1.2 lneto (in which '<code>a</code>' is coded as 97, 1175 1.2 lneto newline is coded as 10, and '<code>1</code>' is coded as 49), 1176 1.2 lneto the five literal strings below denote the same string: 1177 1.1 mbalmer 1178 1.1 mbalmer <pre> 1179 1.2 lneto a = 'alo\n123"' 1180 1.2 lneto a = "alo\n123\"" 1181 1.2 lneto a = '\97lo\10\04923"' 1182 1.2 lneto a = [[alo 1183 1.2 lneto 123"]] 1184 1.2 lneto a = [==[ 1185 1.2 lneto alo 1186 1.2 lneto 123"]==] 1187 1.1 mbalmer </pre> 1188 1.1 mbalmer 1189 1.1 mbalmer <p> 1190 1.2 lneto A <em>numerical constant</em> can be written with an optional fractional part 1191 1.2 lneto and an optional decimal exponent, 1192 1.2 lneto marked by a letter '<code>e</code>' or '<code>E</code>'. 1193 1.2 lneto Lua also accepts hexadecimal constants, 1194 1.2 lneto which start with <code>0x</code> or <code>0X</code>. 1195 1.2 lneto Hexadecimal constants also accept an optional fractional part 1196 1.2 lneto plus an optional binary exponent, 1197 1.2 lneto marked by a letter '<code>p</code>' or '<code>P</code>'. 1198 1.2 lneto A numeric constant with a fractional dot or an exponent 1199 1.2 lneto denotes a float; 1200 1.2 lneto otherwise it denotes an integer. 1201 1.2 lneto Examples of valid integer constants are 1202 1.1 mbalmer 1203 1.1 mbalmer <pre> 1204 1.2 lneto 3 345 0xff 0xBEBADA 1205 1.1 mbalmer </pre><p> 1206 1.2 lneto Examples of valid float constants are 1207 1.1 mbalmer 1208 1.1 mbalmer <pre> 1209 1.2 lneto 3.0 3.1416 314.16e-2 0.31416E1 34e1 1210 1.2 lneto 0x0.1E 0xA23p-4 0X1.921FB54442D18P+1 1211 1.1 mbalmer </pre> 1212 1.1 mbalmer 1213 1.1 mbalmer <p> 1214 1.2 lneto A <em>comment</em> starts with a double hyphen (<code>--</code>) 1215 1.2 lneto anywhere outside a string. 1216 1.2 lneto If the text immediately after <code>--</code> is not an opening long bracket, 1217 1.2 lneto the comment is a <em>short comment</em>, 1218 1.2 lneto which runs until the end of the line. 1219 1.2 lneto Otherwise, it is a <em>long comment</em>, 1220 1.2 lneto which runs until the corresponding closing long bracket. 1221 1.2 lneto Long comments are frequently used to disable code temporarily. 1222 1.2 lneto 1223 1.1 mbalmer 1224 1.1 mbalmer 1225 1.1 mbalmer 1226 1.1 mbalmer 1227 1.2 lneto <h2>3.2 – <a name="3.2">Variables</a></h2> 1228 1.1 mbalmer 1229 1.2 lneto <p> 1230 1.2 lneto Variables are places that store values. 1231 1.2 lneto There are three kinds of variables in Lua: 1232 1.2 lneto global variables, local variables, and table fields. 1233 1.1 mbalmer 1234 1.1 mbalmer 1235 1.2 lneto <p> 1236 1.2 lneto A single name can denote a global variable or a local variable 1237 1.2 lneto (or a function's formal parameter, 1238 1.2 lneto which is a particular kind of local variable): 1239 1.1 mbalmer 1240 1.1 mbalmer <pre> 1241 1.2 lneto var ::= Name 1242 1.1 mbalmer </pre><p> 1243 1.2 lneto Name denotes identifiers, as defined in <a href="#3.1">§3.1</a>. 1244 1.1 mbalmer 1245 1.1 mbalmer 1246 1.1 mbalmer <p> 1247 1.2 lneto Any variable name is assumed to be global unless explicitly declared 1248 1.2 lneto as a local (see <a href="#3.3.7">§3.3.7</a>). 1249 1.2 lneto Local variables are <em>lexically scoped</em>: 1250 1.2 lneto local variables can be freely accessed by functions 1251 1.2 lneto defined inside their scope (see <a href="#3.5">§3.5</a>). 1252 1.2 lneto 1253 1.1 mbalmer 1254 1.2 lneto <p> 1255 1.2 lneto Before the first assignment to a variable, its value is <b>nil</b>. 1256 1.1 mbalmer 1257 1.1 mbalmer 1258 1.1 mbalmer <p> 1259 1.2 lneto Square brackets are used to index a table: 1260 1.1 mbalmer 1261 1.1 mbalmer <pre> 1262 1.2 lneto var ::= prefixexp ‘<b>[</b>’ exp ‘<b>]</b>’ 1263 1.1 mbalmer </pre><p> 1264 1.2 lneto The meaning of accesses to table fields can be changed via metatables. 1265 1.2 lneto An access to an indexed variable <code>t[i]</code> is equivalent to 1266 1.2 lneto a call <code>gettable_event(t,i)</code>. 1267 1.2 lneto (See <a href="#2.4">§2.4</a> for a complete description of the 1268 1.2 lneto <code>gettable_event</code> function. 1269 1.2 lneto This function is not defined or callable in Lua. 1270 1.2 lneto We use it here only for explanatory purposes.) 1271 1.1 mbalmer 1272 1.1 mbalmer 1273 1.1 mbalmer <p> 1274 1.2 lneto The syntax <code>var.Name</code> is just syntactic sugar for 1275 1.2 lneto <code>var["Name"]</code>: 1276 1.1 mbalmer 1277 1.1 mbalmer <pre> 1278 1.2 lneto var ::= prefixexp ‘<b>.</b>’ Name 1279 1.2 lneto </pre> 1280 1.1 mbalmer 1281 1.1 mbalmer <p> 1282 1.2 lneto An access to a global variable <code>x</code> 1283 1.2 lneto is equivalent to <code>_ENV.x</code>. 1284 1.2 lneto Due to the way that chunks are compiled, 1285 1.2 lneto <code>_ENV</code> is never a global name (see <a href="#2.2">§2.2</a>). 1286 1.1 mbalmer 1287 1.1 mbalmer 1288 1.1 mbalmer 1289 1.1 mbalmer 1290 1.1 mbalmer 1291 1.2 lneto <h2>3.3 – <a name="3.3">Statements</a></h2> 1292 1.1 mbalmer 1293 1.1 mbalmer <p> 1294 1.2 lneto Lua supports an almost conventional set of statements, 1295 1.2 lneto similar to those in Pascal or C. 1296 1.2 lneto This set includes 1297 1.2 lneto assignments, control structures, function calls, 1298 1.2 lneto and variable declarations. 1299 1.2 lneto 1300 1.2 lneto 1301 1.1 mbalmer 1302 1.2 lneto <h3>3.3.1 – <a name="3.3.1">Blocks</a></h3> 1303 1.1 mbalmer 1304 1.1 mbalmer <p> 1305 1.2 lneto A block is a list of statements, 1306 1.2 lneto which are executed sequentially: 1307 1.1 mbalmer 1308 1.1 mbalmer <pre> 1309 1.2 lneto block ::= {stat} 1310 1.1 mbalmer </pre><p> 1311 1.2 lneto Lua has <em>empty statements</em> 1312 1.2 lneto that allow you to separate statements with semicolons, 1313 1.2 lneto start a block with a semicolon 1314 1.2 lneto or write two semicolons in sequence: 1315 1.1 mbalmer 1316 1.1 mbalmer <pre> 1317 1.2 lneto stat ::= ‘<b>;</b>’ 1318 1.2 lneto </pre> 1319 1.2 lneto 1320 1.2 lneto <p> 1321 1.2 lneto Function calls and assignments 1322 1.2 lneto can start with an open parenthesis. 1323 1.2 lneto This possibility leads to an ambiguity in Lua's grammar. 1324 1.2 lneto Consider the following fragment: 1325 1.1 mbalmer 1326 1.1 mbalmer <pre> 1327 1.2 lneto a = b + c 1328 1.2 lneto (print or io.write)('done') 1329 1.1 mbalmer </pre><p> 1330 1.2 lneto The grammar could see it in two ways: 1331 1.1 mbalmer 1332 1.1 mbalmer <pre> 1333 1.2 lneto a = b + c(print or io.write)('done') 1334 1.2 lneto 1335 1.2 lneto a = b + c; (print or io.write)('done') 1336 1.1 mbalmer </pre><p> 1337 1.2 lneto The current parser always sees such constructions 1338 1.2 lneto in the first way, 1339 1.2 lneto interpreting the open parenthesis 1340 1.2 lneto as the start of the arguments to a call. 1341 1.2 lneto To avoid this ambiguity, 1342 1.2 lneto it is a good practice to always precede with a semicolon 1343 1.2 lneto statements that start with a parenthesis: 1344 1.1 mbalmer 1345 1.1 mbalmer <pre> 1346 1.2 lneto ;(print or io.write)('done') 1347 1.2 lneto </pre> 1348 1.2 lneto 1349 1.2 lneto <p> 1350 1.2 lneto A block can be explicitly delimited to produce a single statement: 1351 1.1 mbalmer 1352 1.1 mbalmer <pre> 1353 1.2 lneto stat ::= <b>do</b> block <b>end</b> 1354 1.1 mbalmer </pre><p> 1355 1.2 lneto Explicit blocks are useful 1356 1.2 lneto to control the scope of variable declarations. 1357 1.2 lneto Explicit blocks are also sometimes used to 1358 1.2 lneto add a <b>return</b> statement in the middle 1359 1.2 lneto of another block (see <a href="#3.3.4">§3.3.4</a>). 1360 1.2 lneto 1361 1.2 lneto 1362 1.2 lneto 1363 1.2 lneto 1364 1.2 lneto 1365 1.2 lneto <h3>3.3.2 – <a name="3.3.2">Chunks</a></h3> 1366 1.2 lneto 1367 1.2 lneto <p> 1368 1.2 lneto The unit of compilation of Lua is called a <em>chunk</em>. 1369 1.2 lneto Syntactically, 1370 1.2 lneto a chunk is simply a block: 1371 1.1 mbalmer 1372 1.1 mbalmer <pre> 1373 1.2 lneto chunk ::= block 1374 1.2 lneto </pre> 1375 1.1 mbalmer 1376 1.2 lneto <p> 1377 1.2 lneto Lua handles a chunk as the body of an anonymous function 1378 1.2 lneto with a variable number of arguments 1379 1.2 lneto (see <a href="#3.4.11">§3.4.11</a>). 1380 1.2 lneto As such, chunks can define local variables, 1381 1.2 lneto receive arguments, and return values. 1382 1.2 lneto Moreover, such anonymous function is compiled as in the 1383 1.2 lneto scope of an external local variable called <code>_ENV</code> (see <a href="#2.2">§2.2</a>). 1384 1.2 lneto The resulting function always has <code>_ENV</code> as its only upvalue, 1385 1.2 lneto even if it does not use that variable. 1386 1.1 mbalmer 1387 1.1 mbalmer 1388 1.1 mbalmer <p> 1389 1.2 lneto A chunk can be stored in a file or in a string inside the host program. 1390 1.2 lneto To execute a chunk, 1391 1.2 lneto Lua first precompiles the chunk into instructions for a virtual machine, 1392 1.2 lneto and then it executes the compiled code 1393 1.2 lneto with an interpreter for the virtual machine. 1394 1.1 mbalmer 1395 1.1 mbalmer 1396 1.1 mbalmer <p> 1397 1.2 lneto Chunks can also be precompiled into binary form; 1398 1.2 lneto see program <code>luac</code> and function <a href="#pdf-string.dump"><code>string.dump</code></a> for details. 1399 1.2 lneto Programs in source and compiled forms are interchangeable; 1400 1.2 lneto Lua automatically detects the file type and acts accordingly (see <a href="#pdf-load"><code>load</code></a>). 1401 1.2 lneto 1402 1.2 lneto 1403 1.2 lneto 1404 1.1 mbalmer 1405 1.1 mbalmer 1406 1.2 lneto <h3>3.3.3 – <a name="3.3.3">Assignment</a></h3> 1407 1.1 mbalmer 1408 1.1 mbalmer <p> 1409 1.2 lneto Lua allows multiple assignments. 1410 1.2 lneto Therefore, the syntax for assignment 1411 1.2 lneto defines a list of variables on the left side 1412 1.2 lneto and a list of expressions on the right side. 1413 1.2 lneto The elements in both lists are separated by commas: 1414 1.1 mbalmer 1415 1.1 mbalmer <pre> 1416 1.2 lneto stat ::= varlist ‘<b>=</b>’ explist 1417 1.2 lneto varlist ::= var {‘<b>,</b>’ var} 1418 1.2 lneto explist ::= exp {‘<b>,</b>’ exp} 1419 1.1 mbalmer </pre><p> 1420 1.2 lneto Expressions are discussed in <a href="#3.4">§3.4</a>. 1421 1.1 mbalmer 1422 1.1 mbalmer 1423 1.1 mbalmer <p> 1424 1.2 lneto Before the assignment, 1425 1.2 lneto the list of values is <em>adjusted</em> to the length of 1426 1.2 lneto the list of variables. 1427 1.2 lneto If there are more values than needed, 1428 1.2 lneto the excess values are thrown away. 1429 1.2 lneto If there are fewer values than needed, 1430 1.2 lneto the list is extended with as many <b>nil</b>'s as needed. 1431 1.2 lneto If the list of expressions ends with a function call, 1432 1.2 lneto then all values returned by that call enter the list of values, 1433 1.2 lneto before the adjustment 1434 1.2 lneto (except when the call is enclosed in parentheses; see <a href="#3.4">§3.4</a>). 1435 1.1 mbalmer 1436 1.1 mbalmer 1437 1.1 mbalmer <p> 1438 1.2 lneto The assignment statement first evaluates all its expressions 1439 1.2 lneto and only then are the assignments performed. 1440 1.2 lneto Thus the code 1441 1.1 mbalmer 1442 1.1 mbalmer <pre> 1443 1.2 lneto i = 3 1444 1.2 lneto i, a[i] = i+1, 20 1445 1.1 mbalmer </pre><p> 1446 1.2 lneto sets <code>a[3]</code> to 20, without affecting <code>a[4]</code> 1447 1.2 lneto because the <code>i</code> in <code>a[i]</code> is evaluated (to 3) 1448 1.2 lneto before it is assigned 4. 1449 1.2 lneto Similarly, the line 1450 1.1 mbalmer 1451 1.1 mbalmer <pre> 1452 1.2 lneto x, y = y, x 1453 1.2 lneto </pre><p> 1454 1.2 lneto exchanges the values of <code>x</code> and <code>y</code>, 1455 1.2 lneto and 1456 1.1 mbalmer 1457 1.2 lneto <pre> 1458 1.2 lneto x, y, z = y, z, x 1459 1.2 lneto </pre><p> 1460 1.2 lneto cyclically permutes the values of <code>x</code>, <code>y</code>, and <code>z</code>. 1461 1.1 mbalmer 1462 1.1 mbalmer 1463 1.2 lneto <p> 1464 1.2 lneto The meaning of assignments to global variables 1465 1.2 lneto and table fields can be changed via metatables. 1466 1.2 lneto An assignment to an indexed variable <code>t[i] = val</code> is equivalent to 1467 1.2 lneto <code>settable_event(t,i,val)</code>. 1468 1.2 lneto (See <a href="#2.4">§2.4</a> for a complete description of the 1469 1.2 lneto <code>settable_event</code> function. 1470 1.2 lneto This function is not defined or callable in Lua. 1471 1.2 lneto We use it here only for explanatory purposes.) 1472 1.1 mbalmer 1473 1.1 mbalmer 1474 1.2 lneto <p> 1475 1.2 lneto An assignment to a global variable <code>x = val</code> 1476 1.2 lneto is equivalent to the assignment 1477 1.2 lneto <code>_ENV.x = val</code> (see <a href="#2.2">§2.2</a>). 1478 1.1 mbalmer 1479 1.1 mbalmer 1480 1.1 mbalmer 1481 1.1 mbalmer 1482 1.1 mbalmer 1483 1.2 lneto <h3>3.3.4 – <a name="3.3.4">Control Structures</a></h3><p> 1484 1.2 lneto The control structures 1485 1.2 lneto <b>if</b>, <b>while</b>, and <b>repeat</b> have the usual meaning and 1486 1.2 lneto familiar syntax: 1487 1.1 mbalmer 1488 1.1 mbalmer 1489 1.1 mbalmer 1490 1.1 mbalmer 1491 1.1 mbalmer <pre> 1492 1.2 lneto stat ::= <b>while</b> exp <b>do</b> block <b>end</b> 1493 1.2 lneto stat ::= <b>repeat</b> block <b>until</b> exp 1494 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> 1495 1.1 mbalmer </pre><p> 1496 1.2 lneto Lua also has a <b>for</b> statement, in two flavors (see <a href="#3.3.5">§3.3.5</a>). 1497 1.1 mbalmer 1498 1.1 mbalmer 1499 1.2 lneto <p> 1500 1.2 lneto The condition expression of a 1501 1.2 lneto control structure can return any value. 1502 1.2 lneto Both <b>false</b> and <b>nil</b> are considered false. 1503 1.2 lneto All values different from <b>nil</b> and <b>false</b> are considered true 1504 1.2 lneto (in particular, the number 0 and the empty string are also true). 1505 1.1 mbalmer 1506 1.1 mbalmer 1507 1.1 mbalmer <p> 1508 1.2 lneto In the <b>repeat</b>–<b>until</b> loop, 1509 1.2 lneto the inner block does not end at the <b>until</b> keyword, 1510 1.2 lneto but only after the condition. 1511 1.2 lneto So, the condition can refer to local variables 1512 1.2 lneto declared inside the loop block. 1513 1.1 mbalmer 1514 1.1 mbalmer 1515 1.1 mbalmer <p> 1516 1.2 lneto The <b>goto</b> statement transfers the program control to a label. 1517 1.2 lneto For syntactical reasons, 1518 1.2 lneto labels in Lua are considered statements too: 1519 1.1 mbalmer 1520 1.1 mbalmer 1521 1.1 mbalmer 1522 1.2 lneto <pre> 1523 1.2 lneto stat ::= <b>goto</b> Name 1524 1.2 lneto stat ::= label 1525 1.2 lneto label ::= ‘<b>::</b>’ Name ‘<b>::</b>’ 1526 1.2 lneto </pre> 1527 1.1 mbalmer 1528 1.1 mbalmer <p> 1529 1.2 lneto A label is visible in the entire block where it is defined, 1530 1.2 lneto except 1531 1.2 lneto inside nested blocks where a label with the same name is defined and 1532 1.2 lneto inside nested functions. 1533 1.2 lneto A goto may jump to any visible label as long as it does not 1534 1.2 lneto enter into the scope of a local variable. 1535 1.1 mbalmer 1536 1.1 mbalmer 1537 1.1 mbalmer <p> 1538 1.2 lneto Labels and empty statements are called <em>void statements</em>, 1539 1.2 lneto as they perform no actions. 1540 1.1 mbalmer 1541 1.1 mbalmer 1542 1.1 mbalmer <p> 1543 1.2 lneto The <b>break</b> statement terminates the execution of a 1544 1.2 lneto <b>while</b>, <b>repeat</b>, or <b>for</b> loop, 1545 1.2 lneto skipping to the next statement after the loop: 1546 1.1 mbalmer 1547 1.1 mbalmer 1548 1.2 lneto <pre> 1549 1.2 lneto stat ::= <b>break</b> 1550 1.2 lneto </pre><p> 1551 1.2 lneto A <b>break</b> ends the innermost enclosing loop. 1552 1.1 mbalmer 1553 1.1 mbalmer 1554 1.1 mbalmer <p> 1555 1.2 lneto The <b>return</b> statement is used to return values 1556 1.2 lneto from a function or a chunk (which is a function in disguise). 1557 1.1 mbalmer 1558 1.2 lneto Functions can return more than one value, 1559 1.2 lneto so the syntax for the <b>return</b> statement is 1560 1.1 mbalmer 1561 1.2 lneto <pre> 1562 1.2 lneto stat ::= <b>return</b> [explist] [‘<b>;</b>’] 1563 1.2 lneto </pre> 1564 1.1 mbalmer 1565 1.1 mbalmer <p> 1566 1.2 lneto The <b>return</b> statement can only be written 1567 1.2 lneto as the last statement of a block. 1568 1.2 lneto If it is really necessary to <b>return</b> in the middle of a block, 1569 1.2 lneto then an explicit inner block can be used, 1570 1.2 lneto as in the idiom <code>do return end</code>, 1571 1.2 lneto because now <b>return</b> is the last statement in its (inner) block. 1572 1.1 mbalmer 1573 1.1 mbalmer 1574 1.1 mbalmer 1575 1.1 mbalmer 1576 1.1 mbalmer 1577 1.2 lneto <h3>3.3.5 – <a name="3.3.5">For Statement</a></h3> 1578 1.1 mbalmer 1579 1.2 lneto <p> 1580 1.1 mbalmer 1581 1.2 lneto The <b>for</b> statement has two forms: 1582 1.2 lneto one numeric and one generic. 1583 1.1 mbalmer 1584 1.1 mbalmer 1585 1.2 lneto <p> 1586 1.2 lneto The numeric <b>for</b> loop repeats a block of code while a 1587 1.2 lneto control variable runs through an arithmetic progression. 1588 1.2 lneto It has the following syntax: 1589 1.1 mbalmer 1590 1.2 lneto <pre> 1591 1.2 lneto stat ::= <b>for</b> Name ‘<b>=</b>’ exp ‘<b>,</b>’ exp [‘<b>,</b>’ exp] <b>do</b> block <b>end</b> 1592 1.2 lneto </pre><p> 1593 1.2 lneto The <em>block</em> is repeated for <em>name</em> starting at the value of 1594 1.2 lneto the first <em>exp</em>, until it passes the second <em>exp</em> by steps of the 1595 1.2 lneto third <em>exp</em>. 1596 1.2 lneto More precisely, a <b>for</b> statement like 1597 1.1 mbalmer 1598 1.1 mbalmer <pre> 1599 1.2 lneto for v = <em>e1</em>, <em>e2</em>, <em>e3</em> do <em>block</em> end 1600 1.1 mbalmer </pre><p> 1601 1.2 lneto is equivalent to the code: 1602 1.1 mbalmer 1603 1.1 mbalmer <pre> 1604 1.2 lneto do 1605 1.2 lneto local <em>var</em>, <em>limit</em>, <em>step</em> = tonumber(<em>e1</em>), tonumber(<em>e2</em>), tonumber(<em>e3</em>) 1606 1.2 lneto if not (<em>var</em> and <em>limit</em> and <em>step</em>) then error() end 1607 1.2 lneto <em>var</em> = <em>var</em> - <em>step</em> 1608 1.2 lneto while true do 1609 1.2 lneto <em>var</em> = <em>var</em> + <em>step</em> 1610 1.2 lneto if (<em>step</em> >= 0 and <em>var</em> > <em>limit</em>) or (<em>step</em> < 0 and <em>var</em> < <em>limit</em>) then 1611 1.2 lneto break 1612 1.1 mbalmer end 1613 1.2 lneto local v = <em>var</em> 1614 1.2 lneto <em>block</em> 1615 1.1 mbalmer end 1616 1.1 mbalmer end 1617 1.2 lneto </pre> 1618 1.2 lneto 1619 1.2 lneto <p> 1620 1.2 lneto Note the following: 1621 1.1 mbalmer 1622 1.2 lneto <ul> 1623 1.1 mbalmer 1624 1.2 lneto <li> 1625 1.2 lneto All three control expressions are evaluated only once, 1626 1.2 lneto before the loop starts. 1627 1.2 lneto They must all result in numbers. 1628 1.1 mbalmer </li> 1629 1.1 mbalmer 1630 1.2 lneto <li> 1631 1.2 lneto <code><em>var</em></code>, <code><em>limit</em></code>, and <code><em>step</em></code> are invisible variables. 1632 1.2 lneto The names shown here are for explanatory purposes only. 1633 1.1 mbalmer </li> 1634 1.1 mbalmer 1635 1.2 lneto <li> 1636 1.2 lneto If the third expression (the step) is absent, 1637 1.2 lneto then a step of 1 is used. 1638 1.2 lneto </li> 1639 1.1 mbalmer 1640 1.2 lneto <li> 1641 1.2 lneto You can use <b>break</b> and <b>goto</b> to exit a <b>for</b> loop. 1642 1.1 mbalmer </li> 1643 1.1 mbalmer 1644 1.2 lneto <li> 1645 1.2 lneto The loop variable <code>v</code> is local to the loop body. 1646 1.2 lneto If you need its value after the loop, 1647 1.2 lneto assign it to another variable before exiting the loop. 1648 1.1 mbalmer </li> 1649 1.1 mbalmer 1650 1.2 lneto </ul> 1651 1.1 mbalmer 1652 1.2 lneto <p> 1653 1.2 lneto The generic <b>for</b> statement works over functions, 1654 1.2 lneto called <em>iterators</em>. 1655 1.2 lneto On each iteration, the iterator function is called to produce a new value, 1656 1.2 lneto stopping when this new value is <b>nil</b>. 1657 1.2 lneto The generic <b>for</b> loop has the following syntax: 1658 1.1 mbalmer 1659 1.2 lneto <pre> 1660 1.2 lneto stat ::= <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> 1661 1.2 lneto namelist ::= Name {‘<b>,</b>’ Name} 1662 1.2 lneto </pre><p> 1663 1.2 lneto A <b>for</b> statement like 1664 1.1 mbalmer 1665 1.2 lneto <pre> 1666 1.2 lneto for <em>var_1</em>, ···, <em>var_n</em> in <em>explist</em> do <em>block</em> end 1667 1.2 lneto </pre><p> 1668 1.2 lneto is equivalent to the code: 1669 1.1 mbalmer 1670 1.1 mbalmer <pre> 1671 1.2 lneto do 1672 1.2 lneto local <em>f</em>, <em>s</em>, <em>var</em> = <em>explist</em> 1673 1.2 lneto while true do 1674 1.2 lneto local <em>var_1</em>, ···, <em>var_n</em> = <em>f</em>(<em>s</em>, <em>var</em>) 1675 1.2 lneto if <em>var_1</em> == nil then break end 1676 1.2 lneto <em>var</em> = <em>var_1</em> 1677 1.2 lneto <em>block</em> 1678 1.1 mbalmer end 1679 1.1 mbalmer end 1680 1.1 mbalmer </pre><p> 1681 1.2 lneto Note the following: 1682 1.2 lneto 1683 1.2 lneto <ul> 1684 1.2 lneto 1685 1.2 lneto <li> 1686 1.2 lneto <code><em>explist</em></code> is evaluated only once. 1687 1.2 lneto Its results are an <em>iterator</em> function, 1688 1.2 lneto a <em>state</em>, 1689 1.2 lneto and an initial value for the first <em>iterator variable</em>. 1690 1.1 mbalmer </li> 1691 1.1 mbalmer 1692 1.2 lneto <li> 1693 1.2 lneto <code><em>f</em></code>, <code><em>s</em></code>, and <code><em>var</em></code> are invisible variables. 1694 1.2 lneto The names are here for explanatory purposes only. 1695 1.2 lneto </li> 1696 1.1 mbalmer 1697 1.2 lneto <li> 1698 1.2 lneto You can use <b>break</b> to exit a <b>for</b> loop. 1699 1.2 lneto </li> 1700 1.1 mbalmer 1701 1.2 lneto <li> 1702 1.2 lneto The loop variables <code><em>var_i</em></code> are local to the loop; 1703 1.2 lneto you cannot use their values after the <b>for</b> ends. 1704 1.2 lneto If you need these values, 1705 1.2 lneto then assign them to other variables before breaking or exiting the loop. 1706 1.1 mbalmer </li> 1707 1.1 mbalmer 1708 1.2 lneto </ul> 1709 1.2 lneto 1710 1.2 lneto 1711 1.1 mbalmer 1712 1.1 mbalmer 1713 1.2 lneto <h3>3.3.6 – <a name="3.3.6">Function Calls as Statements</a></h3><p> 1714 1.2 lneto To allow possible side-effects, 1715 1.2 lneto function calls can be executed as statements: 1716 1.2 lneto 1717 1.1 mbalmer <pre> 1718 1.2 lneto stat ::= functioncall 1719 1.1 mbalmer </pre><p> 1720 1.2 lneto In this case, all returned values are thrown away. 1721 1.2 lneto Function calls are explained in <a href="#3.4.10">§3.4.10</a>. 1722 1.2 lneto 1723 1.2 lneto 1724 1.2 lneto 1725 1.1 mbalmer 1726 1.1 mbalmer 1727 1.2 lneto <h3>3.3.7 – <a name="3.3.7">Local Declarations</a></h3><p> 1728 1.2 lneto Local variables can be declared anywhere inside a block. 1729 1.2 lneto The declaration can include an initial assignment: 1730 1.1 mbalmer 1731 1.1 mbalmer <pre> 1732 1.2 lneto stat ::= <b>local</b> namelist [‘<b>=</b>’ explist] 1733 1.1 mbalmer </pre><p> 1734 1.2 lneto If present, an initial assignment has the same semantics 1735 1.2 lneto of a multiple assignment (see <a href="#3.3.3">§3.3.3</a>). 1736 1.2 lneto Otherwise, all variables are initialized with <b>nil</b>. 1737 1.2 lneto 1738 1.2 lneto 1739 1.2 lneto <p> 1740 1.2 lneto A chunk is also a block (see <a href="#3.3.2">§3.3.2</a>), 1741 1.2 lneto and so local variables can be declared in a chunk outside any explicit block. 1742 1.1 mbalmer 1743 1.1 mbalmer 1744 1.2 lneto <p> 1745 1.2 lneto The visibility rules for local variables are explained in <a href="#3.5">§3.5</a>. 1746 1.2 lneto 1747 1.1 mbalmer 1748 1.1 mbalmer 1749 1.1 mbalmer 1750 1.1 mbalmer 1751 1.1 mbalmer 1752 1.1 mbalmer 1753 1.2 lneto <h2>3.4 – <a name="3.4">Expressions</a></h2> 1754 1.1 mbalmer 1755 1.2 lneto <p> 1756 1.2 lneto The basic expressions in Lua are the following: 1757 1.1 mbalmer 1758 1.1 mbalmer <pre> 1759 1.2 lneto exp ::= prefixexp 1760 1.2 lneto exp ::= <b>nil</b> | <b>false</b> | <b>true</b> 1761 1.2 lneto exp ::= Number 1762 1.2 lneto exp ::= String 1763 1.2 lneto exp ::= functiondef 1764 1.2 lneto exp ::= tableconstructor 1765 1.2 lneto exp ::= ‘<b>...</b>’ 1766 1.2 lneto exp ::= exp binop exp 1767 1.2 lneto exp ::= unop exp 1768 1.2 lneto prefixexp ::= var | functioncall | ‘<b>(</b>’ exp ‘<b>)</b>’ 1769 1.2 lneto </pre> 1770 1.2 lneto 1771 1.2 lneto <p> 1772 1.2 lneto Numbers and literal strings are explained in <a href="#3.1">§3.1</a>; 1773 1.2 lneto variables are explained in <a href="#3.2">§3.2</a>; 1774 1.2 lneto function definitions are explained in <a href="#3.4.11">§3.4.11</a>; 1775 1.2 lneto function calls are explained in <a href="#3.4.10">§3.4.10</a>; 1776 1.2 lneto table constructors are explained in <a href="#3.4.9">§3.4.9</a>. 1777 1.2 lneto Vararg expressions, 1778 1.2 lneto denoted by three dots ('<code>...</code>'), can only be used when 1779 1.2 lneto directly inside a vararg function; 1780 1.2 lneto they are explained in <a href="#3.4.11">§3.4.11</a>. 1781 1.2 lneto 1782 1.1 mbalmer 1783 1.2 lneto <p> 1784 1.2 lneto Binary operators comprise arithmetic operators (see <a href="#3.4.1">§3.4.1</a>), 1785 1.2 lneto bitwise operators (see <a href="#3.4.2">§3.4.2</a>), 1786 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>), 1787 1.2 lneto and the concatenation operator (see <a href="#3.4.6">§3.4.6</a>). 1788 1.2 lneto Unary operators comprise the unary minus (see <a href="#3.4.1">§3.4.1</a>), 1789 1.2 lneto the unary bitwise not (see <a href="#3.4.2">§3.4.2</a>), 1790 1.2 lneto the unary logic <b>not</b> (see <a href="#3.4.5">§3.4.5</a>), 1791 1.2 lneto and the unary <em>length operator</em> (see <a href="#3.4.7">§3.4.7</a>). 1792 1.1 mbalmer 1793 1.1 mbalmer 1794 1.2 lneto <p> 1795 1.2 lneto Both function calls and vararg expressions can result in multiple values. 1796 1.2 lneto If a function call is used as a statement (see <a href="#3.3.6">§3.3.6</a>), 1797 1.2 lneto then its return list is adjusted to zero elements, 1798 1.2 lneto thus discarding all returned values. 1799 1.2 lneto If an expression is used as the last (or the only) element 1800 1.2 lneto of a list of expressions, 1801 1.2 lneto then no adjustment is made 1802 1.2 lneto (unless the expression is enclosed in parentheses). 1803 1.2 lneto In all other contexts, 1804 1.2 lneto Lua adjusts the result list to one element, 1805 1.2 lneto either discarding all values except the first one 1806 1.2 lneto or adding a single <b>nil</b> if there are no values. 1807 1.1 mbalmer 1808 1.1 mbalmer 1809 1.2 lneto <p> 1810 1.2 lneto Here are some examples: 1811 1.1 mbalmer 1812 1.1 mbalmer <pre> 1813 1.2 lneto f() -- adjusted to 0 results 1814 1.2 lneto g(f(), x) -- f() is adjusted to 1 result 1815 1.2 lneto g(x, f()) -- g gets x plus all results from f() 1816 1.2 lneto a,b,c = f(), x -- f() is adjusted to 1 result (c gets nil) 1817 1.2 lneto a,b = ... -- a gets the first vararg parameter, b gets 1818 1.2 lneto -- the second (both a and b can get nil if there 1819 1.2 lneto -- is no corresponding vararg parameter) 1820 1.2 lneto 1821 1.2 lneto a,b,c = x, f() -- f() is adjusted to 2 results 1822 1.2 lneto a,b,c = f() -- f() is adjusted to 3 results 1823 1.2 lneto return f() -- returns all results from f() 1824 1.2 lneto return ... -- returns all received vararg parameters 1825 1.2 lneto return x,y,f() -- returns x, y, and all results from f() 1826 1.2 lneto {f()} -- creates a list with all results from f() 1827 1.2 lneto {...} -- creates a list with all vararg parameters 1828 1.2 lneto {f(), nil} -- f() is adjusted to 1 result 1829 1.2 lneto </pre> 1830 1.2 lneto 1831 1.2 lneto <p> 1832 1.2 lneto Any expression enclosed in parentheses always results in only one value. 1833 1.2 lneto Thus, 1834 1.2 lneto <code>(f(x,y,z))</code> is always a single value, 1835 1.2 lneto even if <code>f</code> returns several values. 1836 1.2 lneto (The value of <code>(f(x,y,z))</code> is the first value returned by <code>f</code> 1837 1.2 lneto or <b>nil</b> if <code>f</code> does not return any values.) 1838 1.2 lneto 1839 1.1 mbalmer 1840 1.1 mbalmer 1841 1.2 lneto <h3>3.4.1 – <a name="3.4.1">Arithmetic Operators</a></h3><p> 1842 1.2 lneto Lua supports the following arithmetic operators: 1843 1.2 lneto <table border="1"> 1844 1.2 lneto <tr><td><code>+</code></td><td>addition</td></tr> 1845 1.2 lneto <tr><td><code>-</code></td><td>subtraction</td></tr> 1846 1.2 lneto <tr><td><code>*</code></td><td>multiplication</td></tr> 1847 1.2 lneto <tr><td><code>/</code></td><td>float division</td></tr> 1848 1.2 lneto <tr><td><code>//</code></td><td>integer division</td></tr> 1849 1.2 lneto <tr><td><code>%</code></td><td>modulo</td></tr> 1850 1.2 lneto <tr><td><code>^</code></td><td>exponentiation</td></tr> 1851 1.2 lneto <tr><td><code>-</code></td><td>unary minus</td></tr> 1852 1.2 lneto </table> 1853 1.1 mbalmer 1854 1.1 mbalmer 1855 1.2 lneto <p> 1856 1.2 lneto With the exception of divisions and exponentiation, 1857 1.2 lneto the arithmetic operators work as follows: 1858 1.2 lneto If both operands are integers, 1859 1.2 lneto the operation is performed over integers and the result is an integer. 1860 1.2 lneto Otherwise, if both operands are numbers 1861 1.2 lneto or strings that can be converted to 1862 1.2 lneto numbers (see <a href="#3.4.3">§3.4.3</a>), 1863 1.2 lneto then they are converted to floats, 1864 1.2 lneto the operation is performed following the usual rules 1865 1.2 lneto for floating-point arithmetic 1866 1.2 lneto (usually the IEEE 754 standard), 1867 1.2 lneto and the result is a float. 1868 1.1 mbalmer 1869 1.1 mbalmer 1870 1.1 mbalmer <p> 1871 1.2 lneto Float division (<code>/</code>) and exponentiation 1872 1.2 lneto always convert their operands to floats 1873 1.2 lneto and the result is always a float. 1874 1.2 lneto Exponentiation uses the ANSI C function <code>pow</code>, 1875 1.2 lneto so that it works for non-integer exponents too. 1876 1.1 mbalmer 1877 1.1 mbalmer 1878 1.1 mbalmer <p> 1879 1.2 lneto Integer division (<code>//</code>) converts its operands to integers 1880 1.2 lneto (see <a href="#3.4.3">§3.4.3</a>) 1881 1.2 lneto and its result is always an integer. 1882 1.2 lneto The result is always rounded towards minus infinite (floor). 1883 1.1 mbalmer 1884 1.1 mbalmer 1885 1.1 mbalmer <p> 1886 1.2 lneto Modulo is defined as the remainder of a division 1887 1.2 lneto that rounds the quotient towards minus infinite (floor). 1888 1.1 mbalmer 1889 1.1 mbalmer 1890 1.1 mbalmer <p> 1891 1.2 lneto In case of overflows in integer arithmetic, 1892 1.2 lneto all operations <em>wrap around</em>, 1893 1.2 lneto according to the usual rules of two-complement arithmetic. 1894 1.2 lneto (In other words, they return the correct result modulo <em>2<sup>64</sup></em>.) 1895 1.2 lneto 1896 1.2 lneto 1897 1.2 lneto 1898 1.2 lneto 1899 1.2 lneto 1900 1.2 lneto <h3>3.4.2 – <a name="3.4.2">Bitwise Operators</a></h3><p> 1901 1.2 lneto Lua supports the following bitwise operators: 1902 1.2 lneto <table border="1"> 1903 1.2 lneto <tr><td><code>&</code></td><td>bitwise and</td></tr> 1904 1.2 lneto <tr><td><code>|</code></td><td>bitwise or</td></tr> 1905 1.2 lneto <tr><td><code>~</code></td><td>bitwise exclusive or</td></tr> 1906 1.2 lneto <tr><td><code>>></code></td><td>right shift</td></tr> 1907 1.2 lneto <tr><td><code><<</code></td><td>left shift</td></tr> 1908 1.2 lneto <tr><td><code>~</code></td><td>unary bitwise not</td></tr> 1909 1.2 lneto </table> 1910 1.1 mbalmer 1911 1.1 mbalmer 1912 1.1 mbalmer <p> 1913 1.2 lneto All bitwise operations convert its operands to integers 1914 1.2 lneto (see <a href="#3.4.3">§3.4.3</a>), 1915 1.2 lneto operate on all bits of those integers, 1916 1.2 lneto and result in an integer. 1917 1.1 mbalmer 1918 1.1 mbalmer 1919 1.1 mbalmer <p> 1920 1.2 lneto Both right and left shifts fill the vacant bits with zeros. 1921 1.2 lneto Negative displacements shift to the other direction; 1922 1.2 lneto displacements with absolute values equal to or higher than 1923 1.2 lneto the number of bits in an integer 1924 1.2 lneto result in zero (all bits are shifted out). 1925 1.2 lneto 1926 1.2 lneto 1927 1.2 lneto 1928 1.2 lneto 1929 1.2 lneto 1930 1.2 lneto <h3>3.4.3 – <a name="3.4.3">Coercions and Conversions</a></h3><p> 1931 1.2 lneto Lua provides some automatic conversions between some 1932 1.2 lneto types and representations at run time. 1933 1.2 lneto Most arithmetic operations applied to mixed numbers 1934 1.2 lneto (integers and floats) convert the integer operand to a float; 1935 1.2 lneto this is called the <em>usual rule</em>. 1936 1.2 lneto Float division always convert integer operands to floats; 1937 1.2 lneto integer division and bitwise operators 1938 1.2 lneto always convert float operands to integers. 1939 1.2 lneto The C API also converts both integers to floats and 1940 1.2 lneto floats to integers, as needed. 1941 1.2 lneto Moreover, string concatenation accepts numbers as arguments, 1942 1.2 lneto besides strings. 1943 1.1 mbalmer 1944 1.1 mbalmer 1945 1.1 mbalmer <p> 1946 1.2 lneto Lua also converts strings to numbers, 1947 1.2 lneto whenever a number is expected. 1948 1.1 mbalmer 1949 1.1 mbalmer 1950 1.2 lneto <p> 1951 1.2 lneto In a conversion from integer to float, 1952 1.2 lneto if the integer value has an exact representation as a float, 1953 1.2 lneto that is the result. 1954 1.2 lneto Otherwise, 1955 1.2 lneto the conversion gets the nearest higher or lower representable value. 1956 1.2 lneto This kind of conversion never fails. 1957 1.1 mbalmer 1958 1.1 mbalmer 1959 1.2 lneto <p> 1960 1.2 lneto The conversion from float to integer 1961 1.2 lneto first takes the floor of the float number. 1962 1.2 lneto If that value can be represented as an integer 1963 1.2 lneto (that is, it is in the range of integer representation), 1964 1.2 lneto that is the result. 1965 1.2 lneto Otherwise, the conversion fails. 1966 1.1 mbalmer 1967 1.1 mbalmer 1968 1.1 mbalmer <p> 1969 1.2 lneto The conversion from strings to numbers goes as follows: 1970 1.2 lneto First, the string is converted to an integer or a float, 1971 1.2 lneto following its syntax and the rules of the Lua lexer. 1972 1.2 lneto (The string may have also leading and trailing spaces and a sign.) 1973 1.2 lneto Then, the resulting number is converted to the required type 1974 1.2 lneto (float or integer) according to the previous rules. 1975 1.1 mbalmer 1976 1.1 mbalmer 1977 1.1 mbalmer <p> 1978 1.2 lneto The conversion from numbers to strings uses a human-readable, 1979 1.2 lneto non-specified format. 1980 1.2 lneto For complete control over how numbers are converted to strings, 1981 1.2 lneto use the <code>format</code> function from the string library 1982 1.2 lneto (see <a href="#pdf-string.format"><code>string.format</code></a>). 1983 1.2 lneto 1984 1.2 lneto 1985 1.2 lneto 1986 1.2 lneto 1987 1.2 lneto 1988 1.2 lneto <h3>3.4.4 – <a name="3.4.4">Relational Operators</a></h3><p> 1989 1.2 lneto Lua supports the following relational operators: 1990 1.2 lneto <table border="1"> 1991 1.2 lneto <tr><td><code>==</code></td><td>equality</td></tr> 1992 1.2 lneto <tr><td><code>~=</code></td><td>inequality</td></tr> 1993 1.2 lneto <tr><td><code><</code></td><td>less than</td></tr> 1994 1.2 lneto <tr><td><code>></code></td><td>greater than</td></tr> 1995 1.2 lneto <tr><td><code><=</code></td><td>less or equal</td></tr> 1996 1.2 lneto <tr><td><code>>=</code></td><td>greater or equal</td></tr> 1997 1.2 lneto </table> 1998 1.2 lneto These operators always result in <b>false</b> or <b>true</b>. 1999 1.1 mbalmer 2000 1.1 mbalmer 2001 1.1 mbalmer <p> 2002 1.2 lneto Equality (<code>==</code>) first compares the type of its operands. 2003 1.2 lneto If the types are different, then the result is <b>false</b>. 2004 1.2 lneto Otherwise, the values of the operands are compared. 2005 1.2 lneto Strings are compared in the obvious way. 2006 1.2 lneto Numbers follow the usual rule for binary operations: 2007 1.2 lneto if both operands are integers, 2008 1.2 lneto the are compared as integers; 2009 1.2 lneto otherwise, they are converted to floats 2010 1.2 lneto and compared as such. 2011 1.1 mbalmer 2012 1.1 mbalmer 2013 1.1 mbalmer <p> 2014 1.2 lneto Tables, userdata, and threads 2015 1.2 lneto are compared by reference: 2016 1.2 lneto two objects are considered equal only if they are the same object. 2017 1.2 lneto Every time you create a new object 2018 1.2 lneto (a table, userdata, or thread), 2019 1.2 lneto this new object is different from any previously existing object. 2020 1.2 lneto Closures with the same reference are always equal. 2021 1.2 lneto Closures with any detectable difference 2022 1.2 lneto (different behavior, different definition) are always different. 2023 1.1 mbalmer 2024 1.1 mbalmer 2025 1.1 mbalmer <p> 2026 1.2 lneto You can change the way that Lua compares tables and userdata 2027 1.2 lneto by using the "eq" metamethod (see <a href="#2.4">§2.4</a>). 2028 1.1 mbalmer 2029 1.1 mbalmer 2030 1.2 lneto <p> 2031 1.2 lneto Equality comparisons never convert strings to numbers 2032 1.2 lneto or vice versa. 2033 1.2 lneto Thus, <code>"0"==0</code> evaluates to <b>false</b>, 2034 1.2 lneto and <code>t[0]</code> and <code>t["0"]</code> denote different 2035 1.2 lneto entries in a table. 2036 1.1 mbalmer 2037 1.1 mbalmer 2038 1.1 mbalmer <p> 2039 1.2 lneto The operator <code>~=</code> is exactly the negation of equality (<code>==</code>). 2040 1.1 mbalmer 2041 1.1 mbalmer 2042 1.2 lneto <p> 2043 1.2 lneto The order operators work as follows. 2044 1.2 lneto If both arguments are numbers, 2045 1.2 lneto then they are compared following 2046 1.2 lneto the usual rule for binary operations. 2047 1.2 lneto Otherwise, if both arguments are strings, 2048 1.2 lneto then their values are compared according to the current locale. 2049 1.2 lneto Otherwise, Lua tries to call the "lt" or the "le" 2050 1.2 lneto metamethod (see <a href="#2.4">§2.4</a>). 2051 1.2 lneto A comparison <code>a > b</code> is translated to <code>b < a</code> 2052 1.2 lneto and <code>a >= b</code> is translated to <code>b <= a</code>. 2053 1.2 lneto 2054 1.2 lneto 2055 1.2 lneto 2056 1.2 lneto 2057 1.2 lneto 2058 1.2 lneto <h3>3.4.5 – <a name="3.4.5">Logical Operators</a></h3><p> 2059 1.2 lneto The logical operators in Lua are 2060 1.2 lneto <b>and</b>, <b>or</b>, and <b>not</b>. 2061 1.2 lneto Like the control structures (see <a href="#3.3.4">§3.3.4</a>), 2062 1.2 lneto all logical operators consider both <b>false</b> and <b>nil</b> as false 2063 1.2 lneto and anything else as true. 2064 1.2 lneto 2065 1.2 lneto 2066 1.2 lneto <p> 2067 1.2 lneto The negation operator <b>not</b> always returns <b>false</b> or <b>true</b>. 2068 1.2 lneto The conjunction operator <b>and</b> returns its first argument 2069 1.2 lneto if this value is <b>false</b> or <b>nil</b>; 2070 1.2 lneto otherwise, <b>and</b> returns its second argument. 2071 1.2 lneto The disjunction operator <b>or</b> returns its first argument 2072 1.2 lneto if this value is different from <b>nil</b> and <b>false</b>; 2073 1.2 lneto otherwise, <b>or</b> returns its second argument. 2074 1.2 lneto Both <b>and</b> and <b>or</b> use short-circuit evaluation; 2075 1.2 lneto that is, 2076 1.2 lneto the second operand is evaluated only if necessary. 2077 1.2 lneto Here are some examples: 2078 1.2 lneto 2079 1.2 lneto <pre> 2080 1.2 lneto 10 or 20 --> 10 2081 1.2 lneto 10 or error() --> 10 2082 1.2 lneto nil or "a" --> "a" 2083 1.2 lneto nil and 10 --> nil 2084 1.2 lneto false and error() --> false 2085 1.2 lneto false and nil --> false 2086 1.2 lneto false or nil --> nil 2087 1.2 lneto 10 and 20 --> 20 2088 1.2 lneto </pre><p> 2089 1.2 lneto (In this manual, 2090 1.2 lneto <code>--></code> indicates the result of the preceding expression.) 2091 1.2 lneto 2092 1.2 lneto 2093 1.2 lneto 2094 1.2 lneto 2095 1.2 lneto 2096 1.2 lneto <h3>3.4.6 – <a name="3.4.6">Concatenation</a></h3><p> 2097 1.2 lneto The string concatenation operator in Lua is 2098 1.2 lneto denoted by two dots ('<code>..</code>'). 2099 1.2 lneto If both operands are strings or numbers, then they are converted to 2100 1.2 lneto strings according to the rules described in <a href="#3.4.3">§3.4.3</a>. 2101 1.2 lneto Otherwise, the <code>__concat</code> metamethod is called (see <a href="#2.4">§2.4</a>). 2102 1.2 lneto 2103 1.2 lneto 2104 1.2 lneto 2105 1.2 lneto 2106 1.2 lneto 2107 1.2 lneto <h3>3.4.7 – <a name="3.4.7">The Length Operator</a></h3> 2108 1.2 lneto 2109 1.2 lneto <p> 2110 1.2 lneto The length operator is denoted by the unary prefix operator <code>#</code>. 2111 1.2 lneto The length of a string is its number of bytes 2112 1.2 lneto (that is, the usual meaning of string length when each 2113 1.2 lneto character is one byte). 2114 1.2 lneto 2115 1.2 lneto 2116 1.2 lneto <p> 2117 1.2 lneto A program can modify the behavior of the length operator for 2118 1.2 lneto any value but strings through the <code>__len</code> metamethod (see <a href="#2.4">§2.4</a>). 2119 1.2 lneto 2120 1.2 lneto 2121 1.2 lneto <p> 2122 1.2 lneto Unless a <code>__len</code> metamethod is given, 2123 1.2 lneto the length of a table <code>t</code> is only defined if the 2124 1.2 lneto table is a <em>sequence</em>, 2125 1.2 lneto that is, 2126 1.2 lneto the set of its positive numeric keys is equal to <em>{1..n}</em> 2127 1.2 lneto for some non-negative integer <em>n</em>. 2128 1.2 lneto In that case, <em>n</em> is its length. 2129 1.2 lneto Note that a table like 2130 1.2 lneto 2131 1.2 lneto <pre> 2132 1.2 lneto {10, 20, nil, 40} 2133 1.2 lneto </pre><p> 2134 1.2 lneto is not a sequence, because it has the key <code>4</code> 2135 1.2 lneto but does not have the key <code>3</code>. 2136 1.2 lneto (So, there is no <em>n</em> such that the set <em>{1..n}</em> is equal 2137 1.2 lneto to the set of positive numeric keys of that table.) 2138 1.2 lneto Note, however, that non-numeric keys do not interfere 2139 1.2 lneto with whether a table is a sequence. 2140 1.2 lneto 2141 1.2 lneto 2142 1.2 lneto 2143 1.2 lneto 2144 1.2 lneto 2145 1.2 lneto <h3>3.4.8 – <a name="3.4.8">Precedence</a></h3><p> 2146 1.2 lneto Operator precedence in Lua follows the table below, 2147 1.2 lneto from lower to higher priority: 2148 1.2 lneto 2149 1.2 lneto <pre> 2150 1.2 lneto or 2151 1.2 lneto and 2152 1.2 lneto < > <= >= ~= == 2153 1.2 lneto | 2154 1.2 lneto ~ 2155 1.2 lneto & 2156 1.2 lneto << >> 2157 1.2 lneto .. 2158 1.2 lneto + - 2159 1.2 lneto * / // % 2160 1.2 lneto unary operators (not # - ~) 2161 1.2 lneto ^ 2162 1.2 lneto </pre><p> 2163 1.2 lneto As usual, 2164 1.2 lneto you can use parentheses to change the precedences of an expression. 2165 1.2 lneto The concatenation ('<code>..</code>') and exponentiation ('<code>^</code>') 2166 1.2 lneto operators are right associative. 2167 1.2 lneto All other binary operators are left associative. 2168 1.2 lneto 2169 1.2 lneto 2170 1.2 lneto 2171 1.2 lneto 2172 1.2 lneto 2173 1.2 lneto <h3>3.4.9 – <a name="3.4.9">Table Constructors</a></h3><p> 2174 1.2 lneto Table constructors are expressions that create tables. 2175 1.2 lneto Every time a constructor is evaluated, a new table is created. 2176 1.2 lneto A constructor can be used to create an empty table 2177 1.2 lneto or to create a table and initialize some of its fields. 2178 1.2 lneto The general syntax for constructors is 2179 1.2 lneto 2180 1.2 lneto <pre> 2181 1.2 lneto tableconstructor ::= ‘<b>{</b>’ [fieldlist] ‘<b>}</b>’ 2182 1.2 lneto fieldlist ::= field {fieldsep field} [fieldsep] 2183 1.2 lneto field ::= ‘<b>[</b>’ exp ‘<b>]</b>’ ‘<b>=</b>’ exp | Name ‘<b>=</b>’ exp | exp 2184 1.2 lneto fieldsep ::= ‘<b>,</b>’ | ‘<b>;</b>’ 2185 1.2 lneto </pre> 2186 1.2 lneto 2187 1.2 lneto <p> 2188 1.2 lneto Each field of the form <code>[exp1] = exp2</code> adds to the new table an entry 2189 1.2 lneto with key <code>exp1</code> and value <code>exp2</code>. 2190 1.2 lneto A field of the form <code>name = exp</code> is equivalent to 2191 1.2 lneto <code>["name"] = exp</code>. 2192 1.2 lneto Finally, fields of the form <code>exp</code> are equivalent to 2193 1.2 lneto <code>[i] = exp</code>, where <code>i</code> are consecutive numerical integers, 2194 1.2 lneto starting with 1. 2195 1.2 lneto Fields in the other formats do not affect this counting. 2196 1.2 lneto For example, 2197 1.2 lneto 2198 1.2 lneto <pre> 2199 1.2 lneto a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 } 2200 1.2 lneto </pre><p> 2201 1.2 lneto is equivalent to 2202 1.2 lneto 2203 1.2 lneto <pre> 2204 1.2 lneto do 2205 1.2 lneto local t = {} 2206 1.2 lneto t[f(1)] = g 2207 1.2 lneto t[1] = "x" -- 1st exp 2208 1.2 lneto t[2] = "y" -- 2nd exp 2209 1.2 lneto t.x = 1 -- t["x"] = 1 2210 1.2 lneto t[3] = f(x) -- 3rd exp 2211 1.2 lneto t[30] = 23 2212 1.2 lneto t[4] = 45 -- 4th exp 2213 1.2 lneto a = t 2214 1.2 lneto end 2215 1.2 lneto </pre> 2216 1.2 lneto 2217 1.2 lneto <p> 2218 1.2 lneto If the last field in the list has the form <code>exp</code> 2219 1.2 lneto and the expression is a function call or a vararg expression, 2220 1.2 lneto then all values returned by this expression enter the list consecutively 2221 1.2 lneto (see <a href="#3.4.10">§3.4.10</a>). 2222 1.2 lneto 2223 1.2 lneto 2224 1.2 lneto <p> 2225 1.2 lneto The field list can have an optional trailing separator, 2226 1.2 lneto as a convenience for machine-generated code. 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.10 – <a name="3.4.10">Function Calls</a></h3><p> 2233 1.2 lneto A function call in Lua has the following syntax: 2234 1.2 lneto 2235 1.2 lneto <pre> 2236 1.2 lneto functioncall ::= prefixexp args 2237 1.2 lneto </pre><p> 2238 1.2 lneto In a function call, 2239 1.2 lneto first prefixexp and args are evaluated. 2240 1.2 lneto If the value of prefixexp has type <em>function</em>, 2241 1.2 lneto then this function is called 2242 1.2 lneto with the given arguments. 2243 1.2 lneto Otherwise, the prefixexp "call" metamethod is called, 2244 1.2 lneto having as first parameter the value of prefixexp, 2245 1.2 lneto followed by the original call arguments 2246 1.2 lneto (see <a href="#2.4">§2.4</a>). 2247 1.2 lneto 2248 1.2 lneto 2249 1.2 lneto <p> 2250 1.2 lneto The form 2251 1.2 lneto 2252 1.2 lneto <pre> 2253 1.2 lneto functioncall ::= prefixexp ‘<b>:</b>’ Name args 2254 1.2 lneto </pre><p> 2255 1.2 lneto can be used to call "methods". 2256 1.2 lneto A call <code>v:name(<em>args</em>)</code> 2257 1.2 lneto is syntactic sugar for <code>v.name(v,<em>args</em>)</code>, 2258 1.2 lneto except that <code>v</code> is evaluated only once. 2259 1.2 lneto 2260 1.2 lneto 2261 1.2 lneto <p> 2262 1.2 lneto Arguments have the following syntax: 2263 1.2 lneto 2264 1.2 lneto <pre> 2265 1.2 lneto args ::= ‘<b>(</b>’ [explist] ‘<b>)</b>’ 2266 1.2 lneto args ::= tableconstructor 2267 1.2 lneto args ::= String 2268 1.2 lneto </pre><p> 2269 1.2 lneto All argument expressions are evaluated before the call. 2270 1.2 lneto A call of the form <code>f{<em>fields</em>}</code> is 2271 1.2 lneto syntactic sugar for <code>f({<em>fields</em>})</code>; 2272 1.2 lneto that is, the argument list is a single new table. 2273 1.2 lneto A call of the form <code>f'<em>string</em>'</code> 2274 1.2 lneto (or <code>f"<em>string</em>"</code> or <code>f[[<em>string</em>]]</code>) 2275 1.2 lneto is syntactic sugar for <code>f('<em>string</em>')</code>; 2276 1.2 lneto that is, the argument list is a single literal string. 2277 1.2 lneto 2278 1.2 lneto 2279 1.2 lneto <p> 2280 1.2 lneto A call of the form <code>return <em>functioncall</em></code> is called 2281 1.2 lneto a <em>tail call</em>. 2282 1.2 lneto Lua implements <em>proper tail calls</em> 2283 1.2 lneto (or <em>proper tail recursion</em>): 2284 1.2 lneto in a tail call, 2285 1.2 lneto the called function reuses the stack entry of the calling function. 2286 1.2 lneto Therefore, there is no limit on the number of nested tail calls that 2287 1.2 lneto a program can execute. 2288 1.2 lneto However, a tail call erases any debug information about the 2289 1.2 lneto calling function. 2290 1.2 lneto Note that a tail call only happens with a particular syntax, 2291 1.2 lneto where the <b>return</b> has one single function call as argument; 2292 1.2 lneto this syntax makes the calling function return exactly 2293 1.2 lneto the returns of the called function. 2294 1.2 lneto So, none of the following examples are tail calls: 2295 1.2 lneto 2296 1.2 lneto <pre> 2297 1.2 lneto return (f(x)) -- results adjusted to 1 2298 1.2 lneto return 2 * f(x) 2299 1.2 lneto return x, f(x) -- additional results 2300 1.2 lneto f(x); return -- results discarded 2301 1.2 lneto return x or f(x) -- results adjusted to 1 2302 1.2 lneto </pre> 2303 1.2 lneto 2304 1.2 lneto 2305 1.2 lneto 2306 1.2 lneto 2307 1.2 lneto <h3>3.4.11 – <a name="3.4.11">Function Definitions</a></h3> 2308 1.2 lneto 2309 1.2 lneto <p> 2310 1.2 lneto The syntax for function definition is 2311 1.2 lneto 2312 1.2 lneto <pre> 2313 1.2 lneto functiondef ::= <b>function</b> funcbody 2314 1.2 lneto funcbody ::= ‘<b>(</b>’ [parlist] ‘<b>)</b>’ block <b>end</b> 2315 1.2 lneto </pre> 2316 1.2 lneto 2317 1.2 lneto <p> 2318 1.2 lneto The following syntactic sugar simplifies function definitions: 2319 1.2 lneto 2320 1.2 lneto <pre> 2321 1.2 lneto stat ::= <b>function</b> funcname funcbody 2322 1.2 lneto stat ::= <b>local</b> <b>function</b> Name funcbody 2323 1.2 lneto funcname ::= Name {‘<b>.</b>’ Name} [‘<b>:</b>’ Name] 2324 1.2 lneto </pre><p> 2325 1.2 lneto The statement 2326 1.2 lneto 2327 1.2 lneto <pre> 2328 1.2 lneto function f () <em>body</em> end 2329 1.2 lneto </pre><p> 2330 1.2 lneto translates to 2331 1.2 lneto 2332 1.2 lneto <pre> 2333 1.2 lneto f = function () <em>body</em> end 2334 1.2 lneto </pre><p> 2335 1.2 lneto The statement 2336 1.2 lneto 2337 1.2 lneto <pre> 2338 1.2 lneto function t.a.b.c.f () <em>body</em> end 2339 1.2 lneto </pre><p> 2340 1.2 lneto translates to 2341 1.2 lneto 2342 1.2 lneto <pre> 2343 1.2 lneto t.a.b.c.f = function () <em>body</em> end 2344 1.2 lneto </pre><p> 2345 1.2 lneto The statement 2346 1.2 lneto 2347 1.2 lneto <pre> 2348 1.2 lneto local function f () <em>body</em> end 2349 1.2 lneto </pre><p> 2350 1.2 lneto translates to 2351 1.2 lneto 2352 1.2 lneto <pre> 2353 1.2 lneto local f; f = function () <em>body</em> end 2354 1.2 lneto </pre><p> 2355 1.2 lneto not to 2356 1.2 lneto 2357 1.2 lneto <pre> 2358 1.2 lneto local f = function () <em>body</em> end 2359 1.2 lneto </pre><p> 2360 1.2 lneto (This only makes a difference when the body of the function 2361 1.2 lneto contains references to <code>f</code>.) 2362 1.2 lneto 2363 1.2 lneto 2364 1.2 lneto <p> 2365 1.2 lneto A function definition is an executable expression, 2366 1.2 lneto whose value has type <em>function</em>. 2367 1.2 lneto When Lua precompiles a chunk, 2368 1.2 lneto all its function bodies are precompiled too. 2369 1.2 lneto Then, whenever Lua executes the function definition, 2370 1.2 lneto the function is <em>instantiated</em> (or <em>closed</em>). 2371 1.2 lneto This function instance (or <em>closure</em>) 2372 1.2 lneto is the final value of the expression. 2373 1.2 lneto 2374 1.2 lneto 2375 1.2 lneto <p> 2376 1.2 lneto Parameters act as local variables that are 2377 1.2 lneto initialized with the argument values: 2378 1.2 lneto 2379 1.2 lneto <pre> 2380 1.2 lneto parlist ::= namelist [‘<b>,</b>’ ‘<b>...</b>’] | ‘<b>...</b>’ 2381 1.2 lneto </pre><p> 2382 1.2 lneto When a function is called, 2383 1.2 lneto the list of arguments is adjusted to 2384 1.2 lneto the length of the list of parameters, 2385 1.2 lneto unless the function is a <em>vararg function</em>, 2386 1.2 lneto which is indicated by three dots ('<code>...</code>') 2387 1.2 lneto at the end of its parameter list. 2388 1.2 lneto A vararg function does not adjust its argument list; 2389 1.2 lneto instead, it collects all extra arguments and supplies them 2390 1.2 lneto to the function through a <em>vararg expression</em>, 2391 1.2 lneto which is also written as three dots. 2392 1.2 lneto The value of this expression is a list of all actual extra arguments, 2393 1.2 lneto similar to a function with multiple results. 2394 1.2 lneto If a vararg expression is used inside another expression 2395 1.2 lneto or in the middle of a list of expressions, 2396 1.2 lneto then its return list is adjusted to one element. 2397 1.2 lneto If the expression is used as the last element of a list of expressions, 2398 1.2 lneto then no adjustment is made 2399 1.2 lneto (unless that last expression is enclosed in parentheses). 2400 1.2 lneto 2401 1.2 lneto 2402 1.2 lneto <p> 2403 1.2 lneto As an example, consider the following definitions: 2404 1.2 lneto 2405 1.2 lneto <pre> 2406 1.2 lneto function f(a, b) end 2407 1.2 lneto function g(a, b, ...) end 2408 1.2 lneto function r() return 1,2,3 end 2409 1.2 lneto </pre><p> 2410 1.2 lneto Then, we have the following mapping from arguments to parameters and 2411 1.2 lneto to the vararg expression: 2412 1.1 mbalmer 2413 1.1 mbalmer <pre> 2414 1.2 lneto CALL PARAMETERS 2415 1.2 lneto 2416 1.2 lneto f(3) a=3, b=nil 2417 1.2 lneto f(3, 4) a=3, b=4 2418 1.2 lneto f(3, 4, 5) a=3, b=4 2419 1.2 lneto f(r(), 10) a=1, b=10 2420 1.2 lneto f(r()) a=1, b=2 2421 1.2 lneto 2422 1.2 lneto g(3) a=3, b=nil, ... --> (nothing) 2423 1.2 lneto g(3, 4) a=3, b=4, ... --> (nothing) 2424 1.2 lneto g(3, 4, 5, 8) a=3, b=4, ... --> 5 8 2425 1.2 lneto g(5, r()) a=5, b=1, ... --> 2 3 2426 1.1 mbalmer </pre> 2427 1.1 mbalmer 2428 1.1 mbalmer <p> 2429 1.2 lneto Results are returned using the <b>return</b> statement (see <a href="#3.3.4">§3.3.4</a>). 2430 1.2 lneto If control reaches the end of a function 2431 1.2 lneto without encountering a <b>return</b> statement, 2432 1.2 lneto then the function returns with no results. 2433 1.1 mbalmer 2434 1.1 mbalmer 2435 1.1 mbalmer <p> 2436 1.1 mbalmer 2437 1.2 lneto There is a system-dependent limit on the number of values 2438 1.2 lneto that a function may return. 2439 1.2 lneto This limit is guaranteed to be larger than 1000. 2440 1.1 mbalmer 2441 1.1 mbalmer 2442 1.1 mbalmer <p> 2443 1.2 lneto The <em>colon</em> syntax 2444 1.2 lneto is used for defining <em>methods</em>, 2445 1.2 lneto that is, functions that have an implicit extra parameter <code>self</code>. 2446 1.2 lneto Thus, the statement 2447 1.1 mbalmer 2448 1.2 lneto <pre> 2449 1.2 lneto function t.a.b.c:f (<em>params</em>) <em>body</em> end 2450 1.2 lneto </pre><p> 2451 1.2 lneto is syntactic sugar for 2452 1.1 mbalmer 2453 1.2 lneto <pre> 2454 1.2 lneto t.a.b.c.f = function (self, <em>params</em>) <em>body</em> end 2455 1.2 lneto </pre> 2456 1.1 mbalmer 2457 1.1 mbalmer 2458 1.1 mbalmer 2459 1.1 mbalmer 2460 1.1 mbalmer 2461 1.1 mbalmer 2462 1.2 lneto <h2>3.5 – <a name="3.5">Visibility Rules</a></h2> 2463 1.1 mbalmer 2464 1.1 mbalmer <p> 2465 1.1 mbalmer 2466 1.2 lneto Lua is a lexically scoped language. 2467 1.2 lneto The scope of a local variable begins at the first statement after 2468 1.2 lneto its declaration and lasts until the last non-void statement 2469 1.2 lneto of the innermost block that includes the declaration. 2470 1.2 lneto Consider the following example: 2471 1.1 mbalmer 2472 1.2 lneto <pre> 2473 1.2 lneto x = 10 -- global variable 2474 1.2 lneto do -- new block 2475 1.2 lneto local x = x -- new 'x', with value 10 2476 1.2 lneto print(x) --> 10 2477 1.2 lneto x = x+1 2478 1.2 lneto do -- another block 2479 1.2 lneto local x = x+1 -- another 'x' 2480 1.2 lneto print(x) --> 12 2481 1.2 lneto end 2482 1.2 lneto print(x) --> 11 2483 1.2 lneto end 2484 1.2 lneto print(x) --> 10 (the global one) 2485 1.2 lneto </pre> 2486 1.1 mbalmer 2487 1.1 mbalmer <p> 2488 1.2 lneto Notice that, in a declaration like <code>local x = x</code>, 2489 1.2 lneto the new <code>x</code> being declared is not in scope yet, 2490 1.2 lneto and so the second <code>x</code> refers to the outside variable. 2491 1.1 mbalmer 2492 1.1 mbalmer 2493 1.1 mbalmer <p> 2494 1.2 lneto Because of the lexical scoping rules, 2495 1.2 lneto local variables can be freely accessed by functions 2496 1.2 lneto defined inside their scope. 2497 1.2 lneto A local variable used by an inner function is called 2498 1.2 lneto an <em>upvalue</em>, or <em>external local variable</em>, 2499 1.2 lneto inside the inner function. 2500 1.1 mbalmer 2501 1.1 mbalmer 2502 1.1 mbalmer <p> 2503 1.2 lneto Notice that each execution of a <b>local</b> statement 2504 1.2 lneto defines new local variables. 2505 1.2 lneto Consider the following example: 2506 1.1 mbalmer 2507 1.1 mbalmer <pre> 2508 1.2 lneto a = {} 2509 1.2 lneto local x = 20 2510 1.2 lneto for i=1,10 do 2511 1.2 lneto local y = 0 2512 1.2 lneto a[i] = function () y=y+1; return x+y end 2513 1.1 mbalmer end 2514 1.1 mbalmer </pre><p> 2515 1.2 lneto The loop creates ten closures 2516 1.2 lneto (that is, ten instances of the anonymous function). 2517 1.2 lneto Each of these closures uses a different <code>y</code> variable, 2518 1.2 lneto while all of them share the same <code>x</code>. 2519 1.1 mbalmer 2520 1.1 mbalmer 2521 1.1 mbalmer 2522 1.1 mbalmer 2523 1.1 mbalmer 2524 1.2 lneto <h1>4 – <a name="4">The Application Program Interface</a></h1> 2525 1.1 mbalmer 2526 1.1 mbalmer <p> 2527 1.1 mbalmer 2528 1.1 mbalmer This section describes the C API for Lua, that is, 2529 1.1 mbalmer the set of C functions available to the host program to communicate 2530 1.1 mbalmer with Lua. 2531 1.1 mbalmer All API functions and related types and constants 2532 1.1 mbalmer are declared in the header file <a name="pdf-lua.h"><code>lua.h</code></a>. 2533 1.1 mbalmer 2534 1.1 mbalmer 2535 1.1 mbalmer <p> 2536 1.1 mbalmer Even when we use the term "function", 2537 1.1 mbalmer any facility in the API may be provided as a macro instead. 2538 1.2 lneto Except where stated otherwise, 2539 1.2 lneto all such macros use each of their arguments exactly once 2540 1.1 mbalmer (except for the first argument, which is always a Lua state), 2541 1.1 mbalmer and so do not generate any hidden side-effects. 2542 1.1 mbalmer 2543 1.1 mbalmer 2544 1.1 mbalmer <p> 2545 1.1 mbalmer As in most C libraries, 2546 1.1 mbalmer the Lua API functions do not check their arguments for validity or consistency. 2547 1.1 mbalmer However, you can change this behavior by compiling Lua 2548 1.2 lneto with the macro <a name="pdf-LUA_USE_APICHECK"><code>LUA_USE_APICHECK</code></a> defined. 2549 1.1 mbalmer 2550 1.1 mbalmer 2551 1.1 mbalmer 2552 1.2 lneto <h2>4.1 – <a name="4.1">The Stack</a></h2> 2553 1.1 mbalmer 2554 1.1 mbalmer <p> 2555 1.1 mbalmer Lua uses a <em>virtual stack</em> to pass values to and from C. 2556 1.1 mbalmer Each element in this stack represents a Lua value 2557 1.1 mbalmer (<b>nil</b>, number, string, etc.). 2558 1.1 mbalmer 2559 1.1 mbalmer 2560 1.1 mbalmer <p> 2561 1.1 mbalmer Whenever Lua calls C, the called function gets a new stack, 2562 1.1 mbalmer which is independent of previous stacks and of stacks of 2563 1.1 mbalmer C functions that are still active. 2564 1.1 mbalmer This stack initially contains any arguments to the C function 2565 1.1 mbalmer and it is where the C function pushes its results 2566 1.1 mbalmer to be returned to the caller (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 2567 1.1 mbalmer 2568 1.1 mbalmer 2569 1.1 mbalmer <p> 2570 1.1 mbalmer For convenience, 2571 1.1 mbalmer most query operations in the API do not follow a strict stack discipline. 2572 1.1 mbalmer Instead, they can refer to any element in the stack 2573 1.1 mbalmer by using an <em>index</em>: 2574 1.2 lneto A positive index represents an absolute stack position 2575 1.1 mbalmer (starting at 1); 2576 1.2 lneto a negative index represents an offset relative to the top of the stack. 2577 1.1 mbalmer More specifically, if the stack has <em>n</em> elements, 2578 1.1 mbalmer then index 1 represents the first element 2579 1.1 mbalmer (that is, the element that was pushed onto the stack first) 2580 1.1 mbalmer and 2581 1.1 mbalmer index <em>n</em> represents the last element; 2582 1.1 mbalmer index -1 also represents the last element 2583 1.1 mbalmer (that is, the element at the top) 2584 1.1 mbalmer and index <em>-n</em> represents the first element. 2585 1.1 mbalmer 2586 1.1 mbalmer 2587 1.1 mbalmer 2588 1.1 mbalmer 2589 1.1 mbalmer 2590 1.2 lneto <h2>4.2 – <a name="4.2">Stack Size</a></h2> 2591 1.1 mbalmer 2592 1.1 mbalmer <p> 2593 1.2 lneto When you interact with the Lua API, 2594 1.1 mbalmer you are responsible for ensuring consistency. 2595 1.1 mbalmer In particular, 2596 1.1 mbalmer <em>you are responsible for controlling stack overflow</em>. 2597 1.1 mbalmer You can use the function <a href="#lua_checkstack"><code>lua_checkstack</code></a> 2598 1.2 lneto to ensure that the stack has extra slots when pushing new elements. 2599 1.1 mbalmer 2600 1.1 mbalmer 2601 1.1 mbalmer <p> 2602 1.1 mbalmer Whenever Lua calls C, 2603 1.2 lneto it ensures that the stack has at least <a name="pdf-LUA_MINSTACK"><code>LUA_MINSTACK</code></a> extra slots. 2604 1.1 mbalmer <code>LUA_MINSTACK</code> is defined as 20, 2605 1.1 mbalmer so that usually you do not have to worry about stack space 2606 1.1 mbalmer unless your code has loops pushing elements onto the stack. 2607 1.1 mbalmer 2608 1.1 mbalmer 2609 1.1 mbalmer <p> 2610 1.2 lneto When you call a Lua function 2611 1.2 lneto without a fixed number of results (see <a href="#lua_call"><code>lua_call</code></a>), 2612 1.2 lneto Lua ensures that the stack has enough size for all results, 2613 1.2 lneto but it does not ensure any extra space. 2614 1.2 lneto So, before pushing anything in the stack after such a call 2615 1.2 lneto you should use <a href="#lua_checkstack"><code>lua_checkstack</code></a>. 2616 1.2 lneto 2617 1.2 lneto 2618 1.2 lneto 2619 1.2 lneto 2620 1.1 mbalmer 2621 1.2 lneto <h2>4.3 – <a name="4.3">Valid and Acceptable Indices</a></h2> 2622 1.1 mbalmer 2623 1.2 lneto <p> 2624 1.2 lneto Any function in the API that receives stack indices 2625 1.2 lneto works only with <em>valid indices</em> or <em>acceptable indices</em>. 2626 1.1 mbalmer 2627 1.1 mbalmer 2628 1.2 lneto <p> 2629 1.2 lneto A <em>valid index</em> is an index that refers to a 2630 1.2 lneto real position within the stack, that is, 2631 1.2 lneto its position lies between 1 and the stack top 2632 1.2 lneto (<code>1 ≤ abs(index) ≤ top</code>). 2633 1.1 mbalmer 2634 1.2 lneto Usually, functions that can modify the value at an index 2635 1.2 lneto require valid indices. 2636 1.1 mbalmer 2637 1.1 mbalmer 2638 1.1 mbalmer <p> 2639 1.1 mbalmer Unless otherwise noted, 2640 1.2 lneto any function that accepts valid indices also accepts <em>pseudo-indices</em>, 2641 1.1 mbalmer which represent some Lua values that are accessible to C code 2642 1.1 mbalmer but which are not in the stack. 2643 1.2 lneto Pseudo-indices are used to access the registry 2644 1.2 lneto and the upvalues of a C function (see <a href="#4.4">§4.4</a>). 2645 1.2 lneto 2646 1.2 lneto 2647 1.2 lneto <p> 2648 1.2 lneto Functions that do not need a specific stack position, 2649 1.2 lneto but only a value in the stack (e.g., query functions), 2650 1.2 lneto can be called with acceptable indices. 2651 1.2 lneto An <em>acceptable index</em> can be any valid index, 2652 1.2 lneto including the pseudo-indices, 2653 1.2 lneto but it also can be any positive index after the stack top 2654 1.2 lneto within the space allocated for the stack, 2655 1.2 lneto that is, indices up to the stack size. 2656 1.2 lneto (Note that 0 is never an acceptable index.) 2657 1.2 lneto Except when noted otherwise, 2658 1.2 lneto functions in the API work with acceptable indices. 2659 1.1 mbalmer 2660 1.1 mbalmer 2661 1.1 mbalmer <p> 2662 1.2 lneto Acceptable indices serve to avoid extra tests 2663 1.2 lneto against the stack top when querying the stack. 2664 1.2 lneto For instance, a C function can query its third argument 2665 1.2 lneto without the need to first check whether there is a third argument, 2666 1.2 lneto that is, without the need to check whether 3 is a valid index. 2667 1.1 mbalmer 2668 1.1 mbalmer 2669 1.1 mbalmer <p> 2670 1.2 lneto For functions that can be called with acceptable indices, 2671 1.2 lneto any non-valid index is treated as if it 2672 1.2 lneto contains a value of a virtual type <a name="pdf-LUA_TNONE"><code>LUA_TNONE</code></a>, 2673 1.2 lneto which behaves like a nil value. 2674 1.1 mbalmer 2675 1.1 mbalmer 2676 1.1 mbalmer 2677 1.1 mbalmer 2678 1.1 mbalmer 2679 1.2 lneto <h2>4.4 – <a name="4.4">C Closures</a></h2> 2680 1.1 mbalmer 2681 1.1 mbalmer <p> 2682 1.1 mbalmer When a C function is created, 2683 1.1 mbalmer it is possible to associate some values with it, 2684 1.2 lneto thus creating a <em>C closure</em> 2685 1.2 lneto (see <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>); 2686 1.1 mbalmer these values are called <em>upvalues</em> and are 2687 1.2 lneto accessible to the function whenever it is called. 2688 1.1 mbalmer 2689 1.1 mbalmer 2690 1.1 mbalmer <p> 2691 1.1 mbalmer Whenever a C function is called, 2692 1.1 mbalmer its upvalues are located at specific pseudo-indices. 2693 1.1 mbalmer These pseudo-indices are produced by the macro 2694 1.2 lneto <a href="#lua_upvalueindex"><code>lua_upvalueindex</code></a>. 2695 1.1 mbalmer The first value associated with a function is at position 2696 1.1 mbalmer <code>lua_upvalueindex(1)</code>, and so on. 2697 1.1 mbalmer Any access to <code>lua_upvalueindex(<em>n</em>)</code>, 2698 1.1 mbalmer where <em>n</em> is greater than the number of upvalues of the 2699 1.1 mbalmer current function (but not greater than 256), 2700 1.2 lneto produces an acceptable but invalid index. 2701 1.1 mbalmer 2702 1.1 mbalmer 2703 1.1 mbalmer 2704 1.1 mbalmer 2705 1.1 mbalmer 2706 1.2 lneto <h2>4.5 – <a name="4.5">Registry</a></h2> 2707 1.1 mbalmer 2708 1.1 mbalmer <p> 2709 1.1 mbalmer Lua provides a <em>registry</em>, 2710 1.2 lneto a predefined table that can be used by any C code to 2711 1.2 lneto store whatever Lua values it needs to store. 2712 1.2 lneto The registry table is always located at pseudo-index 2713 1.2 lneto <a name="pdf-LUA_REGISTRYINDEX"><code>LUA_REGISTRYINDEX</code></a>, 2714 1.2 lneto which is a valid index. 2715 1.1 mbalmer Any C library can store data into this table, 2716 1.2 lneto but it must take care to choose keys 2717 1.2 lneto that are different from those used 2718 1.1 mbalmer by other libraries, to avoid collisions. 2719 1.2 lneto Typically, you should use as key a string containing your library name, 2720 1.2 lneto or a light userdata with the address of a C object in your code, 2721 1.2 lneto or any Lua object created by your code. 2722 1.2 lneto As with global names, 2723 1.2 lneto string keys starting with an underscore followed by 2724 1.2 lneto uppercase letters are reserved for Lua. 2725 1.1 mbalmer 2726 1.1 mbalmer 2727 1.1 mbalmer <p> 2728 1.1 mbalmer The integer keys in the registry are used by the reference mechanism, 2729 1.1 mbalmer implemented by the auxiliary library, 2730 1.2 lneto and by some predefined values. 2731 1.2 lneto Therefore, integer keys must not be used for other purposes. 2732 1.2 lneto 2733 1.1 mbalmer 2734 1.2 lneto <p> 2735 1.2 lneto When you create a new Lua state, 2736 1.2 lneto its registry comes with some predefined values. 2737 1.2 lneto These predefined values are indexed with integer keys 2738 1.2 lneto defined as constants in <code>lua.h</code>. 2739 1.2 lneto The following constants are defined: 2740 1.2 lneto 2741 1.2 lneto <ul> 2742 1.2 lneto <li><b><a name="pdf-LUA_RIDX_MAINTHREAD"><code>LUA_RIDX_MAINTHREAD</code></a>: </b> At this index the registry has 2743 1.2 lneto the main thread of the state. 2744 1.2 lneto (The main thread is the one created together with the state.) 2745 1.2 lneto </li> 2746 1.1 mbalmer 2747 1.2 lneto <li><b><a name="pdf-LUA_RIDX_GLOBALS"><code>LUA_RIDX_GLOBALS</code></a>: </b> At this index the registry has 2748 1.2 lneto the global environment. 2749 1.2 lneto </li> 2750 1.2 lneto </ul> 2751 1.1 mbalmer 2752 1.1 mbalmer 2753 1.1 mbalmer 2754 1.2 lneto 2755 1.2 lneto <h2>4.6 – <a name="4.6">Error Handling in C</a></h2> 2756 1.1 mbalmer 2757 1.1 mbalmer <p> 2758 1.1 mbalmer Internally, Lua uses the C <code>longjmp</code> facility to handle errors. 2759 1.2 lneto (You can also choose to use exceptions if you compile Lua as C++; 2760 1.2 lneto search for <code>LUAI_THROW</code> in the source code.) 2761 1.1 mbalmer When Lua faces any error 2762 1.2 lneto (such as a memory allocation error, type errors, syntax errors, 2763 1.1 mbalmer and runtime errors) 2764 1.1 mbalmer it <em>raises</em> an error; 2765 1.1 mbalmer that is, it does a long jump. 2766 1.1 mbalmer A <em>protected environment</em> uses <code>setjmp</code> 2767 1.2 lneto to set a recovery point; 2768 1.2 lneto any error jumps to the most recent active recovery point. 2769 1.2 lneto 2770 1.2 lneto 2771 1.2 lneto <p> 2772 1.2 lneto If an error happens outside any protected environment, 2773 1.2 lneto Lua calls a <em>panic function</em> (see <a href="#lua_atpanic"><code>lua_atpanic</code></a>) 2774 1.2 lneto and then calls <code>abort</code>, 2775 1.2 lneto thus exiting the host application. 2776 1.2 lneto Your panic function can avoid this exit by 2777 1.2 lneto never returning 2778 1.2 lneto (e.g., doing a long jump to your own recovery point outside Lua). 2779 1.2 lneto 2780 1.2 lneto 2781 1.2 lneto <p> 2782 1.2 lneto The panic function runs as if it were a message handler (see <a href="#2.3">§2.3</a>); 2783 1.2 lneto in particular, the error message is at the top of the stack. 2784 1.2 lneto However, there is no guarantees about stack space. 2785 1.2 lneto To push anything on the stack, 2786 1.2 lneto the panic function must first check the available space (see <a href="#4.2">§4.2</a>). 2787 1.1 mbalmer 2788 1.1 mbalmer 2789 1.1 mbalmer <p> 2790 1.2 lneto Most functions in the API can raise an error, 2791 1.1 mbalmer for instance due to a memory allocation error. 2792 1.2 lneto The documentation for each function indicates whether 2793 1.2 lneto it can raise errors. 2794 1.2 lneto 2795 1.2 lneto 2796 1.2 lneto <p> 2797 1.2 lneto Inside a C function you can raise an error by calling <a href="#lua_error"><code>lua_error</code></a>. 2798 1.2 lneto 2799 1.2 lneto 2800 1.2 lneto 2801 1.2 lneto 2802 1.2 lneto 2803 1.2 lneto <h2>4.7 – <a name="4.7">Handling Yields in C</a></h2> 2804 1.2 lneto 2805 1.2 lneto <p> 2806 1.2 lneto Internally, Lua uses the C <code>longjmp</code> facility to yield a coroutine. 2807 1.2 lneto Therefore, if a C function <code>foo</code> calls an API function 2808 1.2 lneto and this API function yields 2809 1.2 lneto (directly or indirectly by calling another function that yields), 2810 1.2 lneto Lua cannot return to <code>foo</code> any more, 2811 1.2 lneto because the <code>longjmp</code> removes its frame from the C stack. 2812 1.2 lneto 2813 1.2 lneto 2814 1.2 lneto <p> 2815 1.2 lneto To avoid this kind of problem, 2816 1.2 lneto Lua raises an error whenever it tries to yield across an API call, 2817 1.2 lneto except for three functions: 2818 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>. 2819 1.2 lneto All those functions receive a <em>continuation function</em> 2820 1.2 lneto (as a parameter called <code>k</code>) to continue execution after a yield. 2821 1.2 lneto 2822 1.2 lneto 2823 1.2 lneto <p> 2824 1.2 lneto We need to set some terminology to explain continuations. 2825 1.2 lneto We have a C function called from Lua which we will call 2826 1.2 lneto the <em>original function</em>. 2827 1.2 lneto This original function then calls one of those three functions in the C API, 2828 1.2 lneto which we will call the <em>callee function</em>, 2829 1.2 lneto that then yields the current thread. 2830 1.2 lneto (This can happen when the callee function is <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 2831 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> 2832 1.2 lneto and the function called by them yields.) 2833 1.2 lneto 2834 1.2 lneto 2835 1.2 lneto <p> 2836 1.2 lneto Suppose the running thread yields while executing the callee function. 2837 1.2 lneto After the thread resumes, 2838 1.2 lneto it eventually will finish running the callee function. 2839 1.2 lneto However, 2840 1.2 lneto the callee function cannot return to the original function, 2841 1.2 lneto because its frame in the C stack was destroyed by the yield. 2842 1.2 lneto Instead, Lua calls a <em>continuation function</em>, 2843 1.2 lneto which was given as an argument to the callee function. 2844 1.2 lneto As the name implies, 2845 1.2 lneto the continuation function should continue the task 2846 1.2 lneto of the original function. 2847 1.2 lneto 2848 1.2 lneto 2849 1.2 lneto <p> 2850 1.2 lneto As an illustration, consider the following function: 2851 1.2 lneto 2852 1.2 lneto <pre> 2853 1.2 lneto int original_function (lua_State *L) { 2854 1.2 lneto ... /* code 1 */ 2855 1.2 lneto status = lua_pcall(L, n, m, h); /* calls Lua */ 2856 1.2 lneto ... /* code 2 */ 2857 1.2 lneto } 2858 1.2 lneto </pre><p> 2859 1.2 lneto Now we want to allow 2860 1.2 lneto the Lua code being ran by <a href="#lua_pcall"><code>lua_pcall</code></a> to yield. 2861 1.2 lneto First, we can rewrite our function like here: 2862 1.2 lneto 2863 1.2 lneto <pre> 2864 1.2 lneto int k (lua_State *L, int status, int ctx) { 2865 1.2 lneto ... /* code 2 */ 2866 1.2 lneto } 2867 1.2 lneto 2868 1.2 lneto int original_function (lua_State *L) { 2869 1.2 lneto ... /* code 1 */ 2870 1.2 lneto return k(L, lua_pcall(L, n, m, h), ctx); 2871 1.2 lneto } 2872 1.2 lneto </pre><p> 2873 1.2 lneto In the above code, 2874 1.2 lneto the new function <code>k</code> is a 2875 1.2 lneto <em>continuation function</em> (with type <a href="#lua_KFunction"><code>lua_KFunction</code></a>), 2876 1.2 lneto which should do all the work that the original function 2877 1.2 lneto was doing after calling <a href="#lua_pcall"><code>lua_pcall</code></a>. 2878 1.2 lneto Now, we must inform Lua that it must call <code>k</code> if the Lua code 2879 1.2 lneto begin running by <a href="#lua_pcall"><code>lua_pcall</code></a> gets interrupted in some way 2880 1.2 lneto (errors or yielding), 2881 1.2 lneto so we rewrite the code as here, 2882 1.2 lneto replacing <a href="#lua_pcall"><code>lua_pcall</code></a> by <a href="#lua_pcallk"><code>lua_pcallk</code></a>: 2883 1.2 lneto 2884 1.2 lneto <pre> 2885 1.2 lneto int original_function (lua_State *L) { 2886 1.2 lneto ... /* code 1 */ 2887 1.2 lneto return k(L, lua_pcallk(L, n, m, h, ctx2, k), ctx1); 2888 1.2 lneto } 2889 1.2 lneto </pre> 2890 1.2 lneto 2891 1.2 lneto <p> 2892 1.2 lneto Besides the Lua state, 2893 1.2 lneto the continuation function has two other parameters: 2894 1.2 lneto the final status of the call plus the context value (<code>ctx</code>) that 2895 1.2 lneto was passed originally to <a href="#lua_pcallk"><code>lua_pcallk</code></a>. 2896 1.2 lneto (Lua does not use this context value; 2897 1.2 lneto it only passes this value from the original function to the 2898 1.2 lneto continuation function.) 2899 1.2 lneto For <a href="#lua_pcallk"><code>lua_pcallk</code></a>, 2900 1.2 lneto the status is the same value that would be returned by <a href="#lua_pcallk"><code>lua_pcallk</code></a>, 2901 1.2 lneto except that it is <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when being executed after an yield 2902 1.2 lneto (instead of <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>). 2903 1.2 lneto For <a href="#lua_yieldk"><code>lua_yieldk</code></a> and <a href="#lua_callk"><code>lua_callk</code></a>, 2904 1.2 lneto the status is always <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when Lua calls the continuation. 2905 1.2 lneto (For these two functions, 2906 1.2 lneto Lua will not call the continuation in case of errors, 2907 1.2 lneto because they do not handle errors.) 2908 1.1 mbalmer 2909 1.1 mbalmer 2910 1.1 mbalmer <p> 2911 1.2 lneto Lua treats the continuation function as if it were the original function. 2912 1.2 lneto The continuation function receives the same Lua stack 2913 1.2 lneto from the original function, 2914 1.2 lneto in the same state it would be if the callee function had returned. 2915 1.2 lneto (For instance, 2916 1.2 lneto after a <a href="#lua_callk"><code>lua_callk</code></a> the function and its arguments are 2917 1.2 lneto removed from the stack and replaced by the results from the call.) 2918 1.2 lneto It also has the same upvalues. 2919 1.2 lneto Whatever it returns is handled by Lua as if it were the return 2920 1.2 lneto of the original function. 2921 1.1 mbalmer 2922 1.1 mbalmer 2923 1.1 mbalmer 2924 1.1 mbalmer 2925 1.1 mbalmer 2926 1.2 lneto <h2>4.8 – <a name="4.8">Functions and Types</a></h2> 2927 1.1 mbalmer 2928 1.1 mbalmer <p> 2929 1.1 mbalmer Here we list all functions and types from the C API in 2930 1.1 mbalmer alphabetical order. 2931 1.1 mbalmer Each function has an indicator like this: 2932 1.1 mbalmer <span class="apii">[-o, +p, <em>x</em>]</span> 2933 1.1 mbalmer 2934 1.1 mbalmer 2935 1.1 mbalmer <p> 2936 1.1 mbalmer The first field, <code>o</code>, 2937 1.1 mbalmer is how many elements the function pops from the stack. 2938 1.1 mbalmer The second field, <code>p</code>, 2939 1.1 mbalmer is how many elements the function pushes onto the stack. 2940 1.1 mbalmer (Any function always pushes its results after popping its arguments.) 2941 1.1 mbalmer A field in the form <code>x|y</code> means the function can push (or pop) 2942 1.1 mbalmer <code>x</code> or <code>y</code> elements, 2943 1.1 mbalmer depending on the situation; 2944 1.1 mbalmer an interrogation mark '<code>?</code>' means that 2945 1.1 mbalmer we cannot know how many elements the function pops/pushes 2946 1.1 mbalmer by looking only at its arguments 2947 1.1 mbalmer (e.g., they may depend on what is on the stack). 2948 1.1 mbalmer The third field, <code>x</code>, 2949 1.2 lneto tells whether the function may raise errors: 2950 1.2 lneto '<code>-</code>' means the function never raises any error; 2951 1.2 lneto '<code>e</code>' means the function may raise errors; 2952 1.2 lneto '<code>v</code>' means the function may raise an error on purpose. 2953 1.2 lneto 2954 1.2 lneto 2955 1.2 lneto 2956 1.2 lneto <hr><h3><a name="lua_absindex"><code>lua_absindex</code></a></h3><p> 2957 1.2 lneto <span class="apii">[-0, +0, –]</span> 2958 1.2 lneto <pre>int lua_absindex (lua_State *L, int idx);</pre> 2959 1.2 lneto 2960 1.2 lneto <p> 2961 1.2 lneto Converts the acceptable index <code>idx</code> into an absolute index 2962 1.2 lneto (that is, one that does not depend on the stack top). 2963 1.2 lneto 2964 1.2 lneto 2965 1.1 mbalmer 2966 1.1 mbalmer 2967 1.1 mbalmer 2968 1.1 mbalmer <hr><h3><a name="lua_Alloc"><code>lua_Alloc</code></a></h3> 2969 1.1 mbalmer <pre>typedef void * (*lua_Alloc) (void *ud, 2970 1.1 mbalmer void *ptr, 2971 1.1 mbalmer size_t osize, 2972 1.1 mbalmer size_t nsize);</pre> 2973 1.1 mbalmer 2974 1.1 mbalmer <p> 2975 1.1 mbalmer The type of the memory-allocation function used by Lua states. 2976 1.1 mbalmer The allocator function must provide a 2977 1.1 mbalmer functionality similar to <code>realloc</code>, 2978 1.1 mbalmer but not exactly the same. 2979 1.1 mbalmer Its arguments are 2980 1.1 mbalmer <code>ud</code>, an opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>; 2981 1.1 mbalmer <code>ptr</code>, a pointer to the block being allocated/reallocated/freed; 2982 1.2 lneto <code>osize</code>, the original size of the block or some code about what 2983 1.2 lneto is being allocated; 2984 1.1 mbalmer <code>nsize</code>, the new size of the block. 2985 1.2 lneto 2986 1.2 lneto 2987 1.2 lneto <p> 2988 1.2 lneto When <code>ptr</code> is not <code>NULL</code>, 2989 1.2 lneto <code>osize</code> is the size of the block pointed by <code>ptr</code>, 2990 1.2 lneto that is, the size given when it was allocated or reallocated. 2991 1.2 lneto 2992 1.2 lneto 2993 1.2 lneto <p> 2994 1.2 lneto When <code>ptr</code> is <code>NULL</code>, 2995 1.2 lneto <code>osize</code> encodes the kind of object that Lua is allocating. 2996 1.2 lneto <code>osize</code> is any of 2997 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>, 2998 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) 2999 1.2 lneto Lua is creating a new object of that type. 3000 1.2 lneto When <code>osize</code> is some other value, 3001 1.2 lneto Lua is allocating memory for something else. 3002 1.2 lneto 3003 1.2 lneto 3004 1.2 lneto <p> 3005 1.2 lneto Lua assumes the following behavior from the allocator function: 3006 1.2 lneto 3007 1.2 lneto 3008 1.2 lneto <p> 3009 1.2 lneto When <code>nsize</code> is zero, 3010 1.2 lneto the allocator must behave like <code>free</code> 3011 1.2 lneto and return <code>NULL</code>. 3012 1.2 lneto 3013 1.2 lneto 3014 1.2 lneto <p> 3015 1.2 lneto When <code>nsize</code> is not zero, 3016 1.2 lneto the allocator must behave like <code>realloc</code>. 3017 1.2 lneto The allocator returns <code>NULL</code> 3018 1.2 lneto if and only if it cannot fulfill the request. 3019 1.1 mbalmer Lua assumes that the allocator never fails when 3020 1.1 mbalmer <code>osize >= nsize</code>. 3021 1.1 mbalmer 3022 1.1 mbalmer 3023 1.1 mbalmer <p> 3024 1.1 mbalmer Here is a simple implementation for the allocator function. 3025 1.1 mbalmer It is used in the auxiliary library by <a href="#luaL_newstate"><code>luaL_newstate</code></a>. 3026 1.1 mbalmer 3027 1.1 mbalmer <pre> 3028 1.1 mbalmer static void *l_alloc (void *ud, void *ptr, size_t osize, 3029 1.1 mbalmer size_t nsize) { 3030 1.1 mbalmer (void)ud; (void)osize; /* not used */ 3031 1.1 mbalmer if (nsize == 0) { 3032 1.1 mbalmer free(ptr); 3033 1.1 mbalmer return NULL; 3034 1.1 mbalmer } 3035 1.1 mbalmer else 3036 1.1 mbalmer return realloc(ptr, nsize); 3037 1.1 mbalmer } 3038 1.1 mbalmer </pre><p> 3039 1.2 lneto Note that Standard C ensures 3040 1.1 mbalmer that <code>free(NULL)</code> has no effect and that 3041 1.1 mbalmer <code>realloc(NULL, size)</code> is equivalent to <code>malloc(size)</code>. 3042 1.2 lneto This code assumes that <code>realloc</code> does not fail when shrinking a block. 3043 1.2 lneto (Although Standard C does not ensure this behavior, 3044 1.2 lneto it seems to be a safe assumption.) 3045 1.1 mbalmer 3046 1.1 mbalmer 3047 1.1 mbalmer 3048 1.1 mbalmer 3049 1.1 mbalmer 3050 1.2 lneto <hr><h3><a name="lua_arith"><code>lua_arith</code></a></h3><p> 3051 1.2 lneto <span class="apii">[-(2|1), +1, <em>e</em>]</span> 3052 1.2 lneto <pre>void lua_arith (lua_State *L, int op);</pre> 3053 1.1 mbalmer 3054 1.1 mbalmer <p> 3055 1.2 lneto Performs an arithmetic or bitwise operation over the two values 3056 1.2 lneto (or one, in the case of negations) 3057 1.2 lneto at the top of the stack, 3058 1.2 lneto with the value at the top being the second operand, 3059 1.2 lneto pops these values, and pushes the result of the operation. 3060 1.2 lneto The function follows the semantics of the corresponding Lua operator 3061 1.2 lneto (that is, it may call metamethods). 3062 1.1 mbalmer 3063 1.1 mbalmer 3064 1.1 mbalmer <p> 3065 1.2 lneto The value of <code>op</code> must be one of the following constants: 3066 1.2 lneto 3067 1.2 lneto <ul> 3068 1.2 lneto 3069 1.2 lneto <li><b><a name="pdf-LUA_OPADD"><code>LUA_OPADD</code></a>: </b> performs addition (<code>+</code>)</li> 3070 1.2 lneto <li><b><a name="pdf-LUA_OPSUB"><code>LUA_OPSUB</code></a>: </b> performs subtraction (<code>-</code>)</li> 3071 1.2 lneto <li><b><a name="pdf-LUA_OPMUL"><code>LUA_OPMUL</code></a>: </b> performs multiplication (<code>*</code>)</li> 3072 1.2 lneto <li><b><a name="pdf-LUA_OPDIV"><code>LUA_OPDIV</code></a>: </b> performs float division (<code>/</code>)</li> 3073 1.2 lneto <li><b><a name="pdf-LUA_OPIDIV"><code>LUA_OPIDIV</code></a>: </b> performs integer division (<code>//</code>)</li> 3074 1.2 lneto <li><b><a name="pdf-LUA_OPMOD"><code>LUA_OPMOD</code></a>: </b> performs modulo (<code>%</code>)</li> 3075 1.2 lneto <li><b><a name="pdf-LUA_OPPOW"><code>LUA_OPPOW</code></a>: </b> performs exponentiation (<code>^</code>)</li> 3076 1.2 lneto <li><b><a name="pdf-LUA_OPUNM"><code>LUA_OPUNM</code></a>: </b> performs mathematical negation (unary <code>-</code>)</li> 3077 1.2 lneto <li><b><a name="pdf-LUA_OPBNOT"><code>LUA_OPBNOT</code></a>: </b> performs bitwise negation (<code>~</code>)</li> 3078 1.2 lneto <li><b><a name="pdf-LUA_OPBAND"><code>LUA_OPBAND</code></a>: </b> performs bitwise and (<code>&</code>)</li> 3079 1.2 lneto <li><b><a name="pdf-LUA_OPBOR"><code>LUA_OPBOR</code></a>: </b> performs bitwise or (<code>|</code>)</li> 3080 1.2 lneto <li><b><a name="pdf-LUA_OPBXOR"><code>LUA_OPBXOR</code></a>: </b> performs bitwise exclusive or (<code>~</code>)</li> 3081 1.2 lneto <li><b><a name="pdf-LUA_OPSHL"><code>LUA_OPSHL</code></a>: </b> performs left shift (<code><<</code>)</li> 3082 1.2 lneto <li><b><a name="pdf-LUA_OPSHR"><code>LUA_OPSHR</code></a>: </b> performs right shift (<code>>></code>)</li> 3083 1.2 lneto 3084 1.2 lneto </ul> 3085 1.2 lneto 3086 1.2 lneto 3087 1.2 lneto 3088 1.1 mbalmer 3089 1.2 lneto <hr><h3><a name="lua_atpanic"><code>lua_atpanic</code></a></h3><p> 3090 1.2 lneto <span class="apii">[-0, +0, –]</span> 3091 1.2 lneto <pre>lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);</pre> 3092 1.1 mbalmer 3093 1.1 mbalmer <p> 3094 1.2 lneto Sets a new panic function and returns the old one (see <a href="#4.6">§4.6</a>). 3095 1.1 mbalmer 3096 1.1 mbalmer 3097 1.1 mbalmer 3098 1.1 mbalmer 3099 1.1 mbalmer 3100 1.1 mbalmer <hr><h3><a name="lua_call"><code>lua_call</code></a></h3><p> 3101 1.2 lneto <span class="apii">[-(nargs+1), +nresults, <em>e</em>]</span> 3102 1.1 mbalmer <pre>void lua_call (lua_State *L, int nargs, int nresults);</pre> 3103 1.1 mbalmer 3104 1.1 mbalmer <p> 3105 1.1 mbalmer Calls a function. 3106 1.1 mbalmer 3107 1.1 mbalmer 3108 1.1 mbalmer <p> 3109 1.1 mbalmer To call a function you must use the following protocol: 3110 1.1 mbalmer first, the function to be called is pushed onto the stack; 3111 1.1 mbalmer then, the arguments to the function are pushed 3112 1.1 mbalmer in direct order; 3113 1.1 mbalmer that is, the first argument is pushed first. 3114 1.1 mbalmer Finally you call <a href="#lua_call"><code>lua_call</code></a>; 3115 1.1 mbalmer <code>nargs</code> is the number of arguments that you pushed onto the stack. 3116 1.1 mbalmer All arguments and the function value are popped from the stack 3117 1.1 mbalmer when the function is called. 3118 1.1 mbalmer The function results are pushed onto the stack when the function returns. 3119 1.1 mbalmer The number of results is adjusted to <code>nresults</code>, 3120 1.1 mbalmer unless <code>nresults</code> is <a name="pdf-LUA_MULTRET"><code>LUA_MULTRET</code></a>. 3121 1.2 lneto In this case, all results from the function are pushed. 3122 1.1 mbalmer Lua takes care that the returned values fit into the stack space. 3123 1.1 mbalmer The function results are pushed onto the stack in direct order 3124 1.1 mbalmer (the first result is pushed first), 3125 1.1 mbalmer so that after the call the last result is on the top of the stack. 3126 1.1 mbalmer 3127 1.1 mbalmer 3128 1.1 mbalmer <p> 3129 1.1 mbalmer Any error inside the called function is propagated upwards 3130 1.1 mbalmer (with a <code>longjmp</code>). 3131 1.1 mbalmer 3132 1.1 mbalmer 3133 1.1 mbalmer <p> 3134 1.1 mbalmer The following example shows how the host program can do the 3135 1.1 mbalmer equivalent to this Lua code: 3136 1.1 mbalmer 3137 1.1 mbalmer <pre> 3138 1.1 mbalmer a = f("how", t.x, 14) 3139 1.1 mbalmer </pre><p> 3140 1.1 mbalmer Here it is in C: 3141 1.1 mbalmer 3142 1.1 mbalmer <pre> 3143 1.2 lneto lua_getglobal(L, "f"); /* function to be called */ 3144 1.1 mbalmer lua_pushstring(L, "how"); /* 1st argument */ 3145 1.2 lneto lua_getglobal(L, "t"); /* table to be indexed */ 3146 1.1 mbalmer lua_getfield(L, -1, "x"); /* push result of t.x (2nd arg) */ 3147 1.1 mbalmer lua_remove(L, -2); /* remove 't' from the stack */ 3148 1.1 mbalmer lua_pushinteger(L, 14); /* 3rd argument */ 3149 1.1 mbalmer lua_call(L, 3, 1); /* call 'f' with 3 arguments and 1 result */ 3150 1.2 lneto lua_setglobal(L, "a"); /* set global 'a' */ 3151 1.1 mbalmer </pre><p> 3152 1.1 mbalmer Note that the code above is "balanced": 3153 1.1 mbalmer at its end, the stack is back to its original configuration. 3154 1.1 mbalmer This is considered good programming practice. 3155 1.1 mbalmer 3156 1.1 mbalmer 3157 1.1 mbalmer 3158 1.1 mbalmer 3159 1.1 mbalmer 3160 1.2 lneto <hr><h3><a name="lua_callk"><code>lua_callk</code></a></h3><p> 3161 1.2 lneto <span class="apii">[-(nargs + 1), +nresults, <em>e</em>]</span> 3162 1.2 lneto <pre>void lua_callk (lua_State *L, int nargs, int nresults, int ctx, 3163 1.2 lneto lua_KFunction k);</pre> 3164 1.2 lneto 3165 1.2 lneto <p> 3166 1.2 lneto This function behaves exactly like <a href="#lua_call"><code>lua_call</code></a>, 3167 1.2 lneto but allows the called function to yield (see <a href="#4.7">§4.7</a>). 3168 1.2 lneto 3169 1.2 lneto 3170 1.2 lneto 3171 1.2 lneto 3172 1.2 lneto 3173 1.1 mbalmer <hr><h3><a name="lua_CFunction"><code>lua_CFunction</code></a></h3> 3174 1.1 mbalmer <pre>typedef int (*lua_CFunction) (lua_State *L);</pre> 3175 1.1 mbalmer 3176 1.1 mbalmer <p> 3177 1.1 mbalmer Type for C functions. 3178 1.1 mbalmer 3179 1.1 mbalmer 3180 1.1 mbalmer <p> 3181 1.1 mbalmer In order to communicate properly with Lua, 3182 1.1 mbalmer a C function must use the following protocol, 3183 1.1 mbalmer which defines the way parameters and results are passed: 3184 1.1 mbalmer a C function receives its arguments from Lua in its stack 3185 1.1 mbalmer in direct order (the first argument is pushed first). 3186 1.1 mbalmer So, when the function starts, 3187 1.1 mbalmer <code>lua_gettop(L)</code> returns the number of arguments received by the function. 3188 1.1 mbalmer The first argument (if any) is at index 1 3189 1.1 mbalmer and its last argument is at index <code>lua_gettop(L)</code>. 3190 1.1 mbalmer To return values to Lua, a C function just pushes them onto the stack, 3191 1.1 mbalmer in direct order (the first result is pushed first), 3192 1.1 mbalmer and returns the number of results. 3193 1.1 mbalmer Any other value in the stack below the results will be properly 3194 1.1 mbalmer discarded by Lua. 3195 1.1 mbalmer Like a Lua function, a C function called by Lua can also return 3196 1.1 mbalmer many results. 3197 1.1 mbalmer 3198 1.1 mbalmer 3199 1.1 mbalmer <p> 3200 1.1 mbalmer As an example, the following function receives a variable number 3201 1.1 mbalmer of numerical arguments and returns their average and sum: 3202 1.1 mbalmer 3203 1.1 mbalmer <pre> 3204 1.1 mbalmer static int foo (lua_State *L) { 3205 1.1 mbalmer int n = lua_gettop(L); /* number of arguments */ 3206 1.1 mbalmer lua_Number sum = 0; 3207 1.1 mbalmer int i; 3208 1.1 mbalmer for (i = 1; i <= n; i++) { 3209 1.1 mbalmer if (!lua_isnumber(L, i)) { 3210 1.1 mbalmer lua_pushstring(L, "incorrect argument"); 3211 1.1 mbalmer lua_error(L); 3212 1.1 mbalmer } 3213 1.1 mbalmer sum += lua_tonumber(L, i); 3214 1.1 mbalmer } 3215 1.1 mbalmer lua_pushnumber(L, sum/n); /* first result */ 3216 1.1 mbalmer lua_pushnumber(L, sum); /* second result */ 3217 1.1 mbalmer return 2; /* number of results */ 3218 1.1 mbalmer } 3219 1.1 mbalmer </pre> 3220 1.1 mbalmer 3221 1.1 mbalmer 3222 1.1 mbalmer 3223 1.1 mbalmer 3224 1.1 mbalmer <hr><h3><a name="lua_checkstack"><code>lua_checkstack</code></a></h3><p> 3225 1.2 lneto <span class="apii">[-0, +0, –]</span> 3226 1.1 mbalmer <pre>int lua_checkstack (lua_State *L, int extra);</pre> 3227 1.1 mbalmer 3228 1.1 mbalmer <p> 3229 1.1 mbalmer Ensures that there are at least <code>extra</code> free stack slots in the stack. 3230 1.2 lneto It returns false if it cannot fulfill the request, 3231 1.2 lneto because it would cause the stack to be larger than a fixed maximum size 3232 1.2 lneto (typically at least a few thousand elements) or 3233 1.2 lneto because it cannot allocate memory for the new stack size. 3234 1.1 mbalmer This function never shrinks the stack; 3235 1.1 mbalmer if the stack is already larger than the new size, 3236 1.1 mbalmer it is left unchanged. 3237 1.1 mbalmer 3238 1.1 mbalmer 3239 1.1 mbalmer 3240 1.1 mbalmer 3241 1.1 mbalmer 3242 1.1 mbalmer <hr><h3><a name="lua_close"><code>lua_close</code></a></h3><p> 3243 1.2 lneto <span class="apii">[-0, +0, –]</span> 3244 1.1 mbalmer <pre>void lua_close (lua_State *L);</pre> 3245 1.1 mbalmer 3246 1.1 mbalmer <p> 3247 1.1 mbalmer Destroys all objects in the given Lua state 3248 1.1 mbalmer (calling the corresponding garbage-collection metamethods, if any) 3249 1.1 mbalmer and frees all dynamic memory used by this state. 3250 1.1 mbalmer On several platforms, you may not need to call this function, 3251 1.1 mbalmer because all resources are naturally released when the host program ends. 3252 1.2 lneto On the other hand, long-running programs that create multiple states, 3253 1.2 lneto such as daemons or web servers, 3254 1.2 lneto might need to close states as soon as they are not needed. 3255 1.2 lneto 3256 1.1 mbalmer 3257 1.1 mbalmer 3258 1.1 mbalmer 3259 1.1 mbalmer 3260 1.2 lneto <hr><h3><a name="lua_compare"><code>lua_compare</code></a></h3><p> 3261 1.2 lneto <span class="apii">[-0, +0, <em>e</em>]</span> 3262 1.2 lneto <pre>int lua_compare (lua_State *L, int index1, int index2, int op);</pre> 3263 1.2 lneto 3264 1.2 lneto <p> 3265 1.2 lneto Compares two Lua values. 3266 1.2 lneto Returns 1 if the value at index <code>index1</code> satisfies <code>op</code> 3267 1.2 lneto when compared with the value at index <code>index2</code>, 3268 1.2 lneto following the semantics of the corresponding Lua operator 3269 1.2 lneto (that is, it may call metamethods). 3270 1.2 lneto Otherwise returns 0. 3271 1.2 lneto Also returns 0 if any of the indices is non valid. 3272 1.2 lneto 3273 1.2 lneto 3274 1.2 lneto <p> 3275 1.2 lneto The value of <code>op</code> must be one of the following constants: 3276 1.2 lneto 3277 1.2 lneto <ul> 3278 1.2 lneto 3279 1.2 lneto <li><b><a name="pdf-LUA_OPEQ"><code>LUA_OPEQ</code></a>: </b> compares for equality (<code>==</code>)</li> 3280 1.2 lneto <li><b><a name="pdf-LUA_OPLT"><code>LUA_OPLT</code></a>: </b> compares for less than (<code><</code>)</li> 3281 1.2 lneto <li><b><a name="pdf-LUA_OPLE"><code>LUA_OPLE</code></a>: </b> compares for less or equal (<code><=</code>)</li> 3282 1.2 lneto 3283 1.2 lneto </ul> 3284 1.2 lneto 3285 1.2 lneto 3286 1.2 lneto 3287 1.1 mbalmer 3288 1.1 mbalmer <hr><h3><a name="lua_concat"><code>lua_concat</code></a></h3><p> 3289 1.1 mbalmer <span class="apii">[-n, +1, <em>e</em>]</span> 3290 1.1 mbalmer <pre>void lua_concat (lua_State *L, int n);</pre> 3291 1.1 mbalmer 3292 1.1 mbalmer <p> 3293 1.1 mbalmer Concatenates the <code>n</code> values at the top of the stack, 3294 1.1 mbalmer pops them, and leaves the result at the top. 3295 1.1 mbalmer If <code>n</code> is 1, the result is the single value on the stack 3296 1.1 mbalmer (that is, the function does nothing); 3297 1.1 mbalmer if <code>n</code> is 0, the result is the empty string. 3298 1.1 mbalmer Concatenation is performed following the usual semantics of Lua 3299 1.2 lneto (see <a href="#3.4.6">§3.4.6</a>). 3300 1.1 mbalmer 3301 1.1 mbalmer 3302 1.1 mbalmer 3303 1.1 mbalmer 3304 1.1 mbalmer 3305 1.2 lneto <hr><h3><a name="lua_copy"><code>lua_copy</code></a></h3><p> 3306 1.2 lneto <span class="apii">[-0, +0, –]</span> 3307 1.2 lneto <pre>void lua_copy (lua_State *L, int fromidx, int toidx);</pre> 3308 1.1 mbalmer 3309 1.1 mbalmer <p> 3310 1.2 lneto Moves the element at index <code>fromidx</code> 3311 1.2 lneto into the valid index <code>toidx</code> 3312 1.2 lneto without shifting any element 3313 1.2 lneto (therefore replacing the value at that position). 3314 1.1 mbalmer 3315 1.1 mbalmer 3316 1.1 mbalmer 3317 1.1 mbalmer 3318 1.1 mbalmer 3319 1.1 mbalmer <hr><h3><a name="lua_createtable"><code>lua_createtable</code></a></h3><p> 3320 1.2 lneto <span class="apii">[-0, +1, <em>e</em>]</span> 3321 1.1 mbalmer <pre>void lua_createtable (lua_State *L, int narr, int nrec);</pre> 3322 1.1 mbalmer 3323 1.1 mbalmer <p> 3324 1.1 mbalmer Creates a new empty table and pushes it onto the stack. 3325 1.2 lneto Parameter <code>narr</code> is a hint for how many elements the table 3326 1.2 lneto will have as a sequence; 3327 1.2 lneto parameter <code>nrec</code> is a hint for how many other elements 3328 1.1 mbalmer the table will have. 3329 1.2 lneto Lua may use these hints to preallocate memory for the new table. 3330 1.2 lneto This pre-allocation is useful for performance when you know in advance 3331 1.2 lneto how many elements the table will have. 3332 1.1 mbalmer Otherwise you can use the function <a href="#lua_newtable"><code>lua_newtable</code></a>. 3333 1.1 mbalmer 3334 1.1 mbalmer 3335 1.1 mbalmer 3336 1.1 mbalmer 3337 1.1 mbalmer 3338 1.1 mbalmer <hr><h3><a name="lua_dump"><code>lua_dump</code></a></h3><p> 3339 1.2 lneto <span class="apii">[-0, +0, <em>e</em>]</span> 3340 1.2 lneto <pre>int lua_dump (lua_State *L, 3341 1.2 lneto lua_Writer writer, 3342 1.2 lneto void *data, 3343 1.2 lneto int strip);</pre> 3344 1.1 mbalmer 3345 1.1 mbalmer <p> 3346 1.1 mbalmer Dumps a function as a binary chunk. 3347 1.1 mbalmer Receives a Lua function on the top of the stack 3348 1.1 mbalmer and produces a binary chunk that, 3349 1.1 mbalmer if loaded again, 3350 1.1 mbalmer results in a function equivalent to the one dumped. 3351 1.1 mbalmer As it produces parts of the chunk, 3352 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>) 3353 1.1 mbalmer with the given <code>data</code> 3354 1.1 mbalmer to write them. 3355 1.1 mbalmer 3356 1.1 mbalmer 3357 1.1 mbalmer <p> 3358 1.2 lneto If <code>strip</code> is true, 3359 1.2 lneto the binary representation is created without debug information 3360 1.2 lneto about the function. 3361 1.2 lneto 3362 1.2 lneto 3363 1.2 lneto <p> 3364 1.1 mbalmer The value returned is the error code returned by the last 3365 1.1 mbalmer call to the writer; 3366 1.1 mbalmer 0 means no errors. 3367 1.1 mbalmer 3368 1.1 mbalmer 3369 1.1 mbalmer <p> 3370 1.1 mbalmer This function does not pop the Lua function from the stack. 3371 1.1 mbalmer 3372 1.1 mbalmer 3373 1.1 mbalmer 3374 1.1 mbalmer 3375 1.1 mbalmer 3376 1.1 mbalmer <hr><h3><a name="lua_error"><code>lua_error</code></a></h3><p> 3377 1.1 mbalmer <span class="apii">[-1, +0, <em>v</em>]</span> 3378 1.1 mbalmer <pre>int lua_error (lua_State *L);</pre> 3379 1.1 mbalmer 3380 1.1 mbalmer <p> 3381 1.1 mbalmer Generates a Lua error. 3382 1.2 lneto The error object must be on the stack top. 3383 1.1 mbalmer This function does a long jump, 3384 1.2 lneto and therefore never returns 3385 1.1 mbalmer (see <a href="#luaL_error"><code>luaL_error</code></a>). 3386 1.1 mbalmer 3387 1.1 mbalmer 3388 1.1 mbalmer 3389 1.1 mbalmer 3390 1.1 mbalmer 3391 1.1 mbalmer <hr><h3><a name="lua_gc"><code>lua_gc</code></a></h3><p> 3392 1.1 mbalmer <span class="apii">[-0, +0, <em>e</em>]</span> 3393 1.1 mbalmer <pre>int lua_gc (lua_State *L, int what, int data);</pre> 3394 1.1 mbalmer 3395 1.1 mbalmer <p> 3396 1.1 mbalmer Controls the garbage collector. 3397 1.1 mbalmer 3398 1.1 mbalmer 3399 1.1 mbalmer <p> 3400 1.1 mbalmer This function performs several tasks, 3401 1.1 mbalmer according to the value of the parameter <code>what</code>: 3402 1.1 mbalmer 3403 1.1 mbalmer <ul> 3404 1.1 mbalmer 3405 1.2 lneto <li><b><code>LUA_GCSTOP</code>: </b> 3406 1.1 mbalmer stops the garbage collector. 3407 1.1 mbalmer </li> 3408 1.1 mbalmer 3409 1.2 lneto <li><b><code>LUA_GCRESTART</code>: </b> 3410 1.1 mbalmer restarts the garbage collector. 3411 1.1 mbalmer </li> 3412 1.1 mbalmer 3413 1.2 lneto <li><b><code>LUA_GCCOLLECT</code>: </b> 3414 1.1 mbalmer performs a full garbage-collection cycle. 3415 1.1 mbalmer </li> 3416 1.1 mbalmer 3417 1.2 lneto <li><b><code>LUA_GCCOUNT</code>: </b> 3418 1.1 mbalmer returns the current amount of memory (in Kbytes) in use by Lua. 3419 1.1 mbalmer </li> 3420 1.1 mbalmer 3421 1.2 lneto <li><b><code>LUA_GCCOUNTB</code>: </b> 3422 1.1 mbalmer returns the remainder of dividing the current amount of bytes of 3423 1.1 mbalmer memory in use by Lua by 1024. 3424 1.1 mbalmer </li> 3425 1.1 mbalmer 3426 1.2 lneto <li><b><code>LUA_GCSTEP</code>: </b> 3427 1.1 mbalmer performs an incremental step of garbage collection. 3428 1.1 mbalmer </li> 3429 1.1 mbalmer 3430 1.2 lneto <li><b><code>LUA_GCSETPAUSE</code>: </b> 3431 1.1 mbalmer sets <code>data</code> as the new value 3432 1.2 lneto for the <em>pause</em> of the collector (see <a href="#2.5">§2.5</a>) 3433 1.2 lneto and returns the previous value of the pause. 3434 1.1 mbalmer </li> 3435 1.1 mbalmer 3436 1.2 lneto <li><b><code>LUA_GCSETSTEPMUL</code>: </b> 3437 1.1 mbalmer sets <code>data</code> as the new value for the <em>step multiplier</em> of 3438 1.2 lneto the collector (see <a href="#2.5">§2.5</a>) 3439 1.2 lneto and returns the previous value of the step multiplier. 3440 1.2 lneto </li> 3441 1.2 lneto 3442 1.2 lneto <li><b><code>LUA_GCISRUNNING</code>: </b> 3443 1.2 lneto returns a boolean that tells whether the collector is running 3444 1.2 lneto (i.e., not stopped). 3445 1.1 mbalmer </li> 3446 1.1 mbalmer 3447 1.1 mbalmer </ul> 3448 1.1 mbalmer 3449 1.2 lneto <p> 3450 1.2 lneto For more details about these options, 3451 1.2 lneto see <a href="#pdf-collectgarbage"><code>collectgarbage</code></a>. 3452 1.2 lneto 3453 1.2 lneto 3454 1.1 mbalmer 3455 1.1 mbalmer 3456 1.1 mbalmer 3457 1.1 mbalmer <hr><h3><a name="lua_getallocf"><code>lua_getallocf</code></a></h3><p> 3458 1.2 lneto <span class="apii">[-0, +0, –]</span> 3459 1.1 mbalmer <pre>lua_Alloc lua_getallocf (lua_State *L, void **ud);</pre> 3460 1.1 mbalmer 3461 1.1 mbalmer <p> 3462 1.1 mbalmer Returns the memory-allocation function of a given state. 3463 1.1 mbalmer If <code>ud</code> is not <code>NULL</code>, Lua stores in <code>*ud</code> the 3464 1.1 mbalmer opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>. 3465 1.1 mbalmer 3466 1.1 mbalmer 3467 1.1 mbalmer 3468 1.1 mbalmer 3469 1.1 mbalmer 3470 1.1 mbalmer <hr><h3><a name="lua_getfield"><code>lua_getfield</code></a></h3><p> 3471 1.1 mbalmer <span class="apii">[-0, +1, <em>e</em>]</span> 3472 1.2 lneto <pre>int lua_getfield (lua_State *L, int index, const char *k);</pre> 3473 1.1 mbalmer 3474 1.1 mbalmer <p> 3475 1.1 mbalmer Pushes onto the stack the value <code>t[k]</code>, 3476 1.2 lneto where <code>t</code> is the value at the given index. 3477 1.1 mbalmer As in Lua, this function may trigger a metamethod 3478 1.2 lneto for the "index" event (see <a href="#2.4">§2.4</a>). 3479 1.2 lneto 3480 1.2 lneto 3481 1.2 lneto <p> 3482 1.2 lneto Returns the type of the pushed value. 3483 1.1 mbalmer 3484 1.1 mbalmer 3485 1.1 mbalmer 3486 1.1 mbalmer 3487 1.1 mbalmer 3488 1.1 mbalmer <hr><h3><a name="lua_getglobal"><code>lua_getglobal</code></a></h3><p> 3489 1.1 mbalmer <span class="apii">[-0, +1, <em>e</em>]</span> 3490 1.2 lneto <pre>int lua_getglobal (lua_State *L, const char *name);</pre> 3491 1.1 mbalmer 3492 1.1 mbalmer <p> 3493 1.1 mbalmer Pushes onto the stack the value of the global <code>name</code>. 3494 1.2 lneto Returns the type of that value. 3495 1.1 mbalmer 3496 1.1 mbalmer 3497 1.1 mbalmer 3498 1.1 mbalmer 3499 1.1 mbalmer 3500 1.1 mbalmer <hr><h3><a name="lua_getmetatable"><code>lua_getmetatable</code></a></h3><p> 3501 1.2 lneto <span class="apii">[-0, +(0|1), –]</span> 3502 1.1 mbalmer <pre>int lua_getmetatable (lua_State *L, int index);</pre> 3503 1.1 mbalmer 3504 1.1 mbalmer <p> 3505 1.2 lneto Pushes onto the stack the metatable of the value at the given index. 3506 1.2 lneto If the value does not have a metatable, 3507 1.1 mbalmer the function returns 0 and pushes nothing on the stack. 3508 1.1 mbalmer 3509 1.1 mbalmer 3510 1.1 mbalmer 3511 1.1 mbalmer 3512 1.1 mbalmer 3513 1.1 mbalmer <hr><h3><a name="lua_gettable"><code>lua_gettable</code></a></h3><p> 3514 1.1 mbalmer <span class="apii">[-1, +1, <em>e</em>]</span> 3515 1.2 lneto <pre>int lua_gettable (lua_State *L, int index);</pre> 3516 1.1 mbalmer 3517 1.1 mbalmer <p> 3518 1.1 mbalmer Pushes onto the stack the value <code>t[k]</code>, 3519 1.2 lneto where <code>t</code> is the value at the given index 3520 1.1 mbalmer and <code>k</code> is the value at the top of the stack. 3521 1.1 mbalmer 3522 1.1 mbalmer 3523 1.1 mbalmer <p> 3524 1.1 mbalmer This function pops the key from the stack 3525 1.1 mbalmer (putting the resulting value in its place). 3526 1.1 mbalmer As in Lua, this function may trigger a metamethod 3527 1.2 lneto for the "index" event (see <a href="#2.4">§2.4</a>). 3528 1.2 lneto 3529 1.2 lneto 3530 1.2 lneto <p> 3531 1.2 lneto Returns the type of the pushed value. 3532 1.1 mbalmer 3533 1.1 mbalmer 3534 1.1 mbalmer 3535 1.1 mbalmer 3536 1.1 mbalmer 3537 1.1 mbalmer <hr><h3><a name="lua_gettop"><code>lua_gettop</code></a></h3><p> 3538 1.2 lneto <span class="apii">[-0, +0, –]</span> 3539 1.1 mbalmer <pre>int lua_gettop (lua_State *L);</pre> 3540 1.1 mbalmer 3541 1.1 mbalmer <p> 3542 1.1 mbalmer Returns the index of the top element in the stack. 3543 1.1 mbalmer Because indices start at 1, 3544 1.1 mbalmer this result is equal to the number of elements in the stack 3545 1.1 mbalmer (and so 0 means an empty stack). 3546 1.1 mbalmer 3547 1.1 mbalmer 3548 1.1 mbalmer 3549 1.1 mbalmer 3550 1.1 mbalmer 3551 1.2 lneto <hr><h3><a name="lua_getuservalue"><code>lua_getuservalue</code></a></h3><p> 3552 1.2 lneto <span class="apii">[-0, +1, –]</span> 3553 1.2 lneto <pre>int lua_getuservalue (lua_State *L, int index);</pre> 3554 1.2 lneto 3555 1.2 lneto <p> 3556 1.2 lneto Pushes onto the stack the Lua value associated with the userdata 3557 1.2 lneto at the given index. 3558 1.2 lneto 3559 1.2 lneto 3560 1.2 lneto <p> 3561 1.2 lneto Returns the type of the pushed value. 3562 1.2 lneto 3563 1.2 lneto 3564 1.2 lneto 3565 1.2 lneto 3566 1.2 lneto 3567 1.1 mbalmer <hr><h3><a name="lua_insert"><code>lua_insert</code></a></h3><p> 3568 1.2 lneto <span class="apii">[-1, +1, –]</span> 3569 1.1 mbalmer <pre>void lua_insert (lua_State *L, int index);</pre> 3570 1.1 mbalmer 3571 1.1 mbalmer <p> 3572 1.1 mbalmer Moves the top element into the given valid index, 3573 1.1 mbalmer shifting up the elements above this index to open space. 3574 1.2 lneto This function cannot be called with a pseudo-index, 3575 1.1 mbalmer because a pseudo-index is not an actual stack position. 3576 1.1 mbalmer 3577 1.1 mbalmer 3578 1.1 mbalmer 3579 1.1 mbalmer 3580 1.1 mbalmer 3581 1.1 mbalmer <hr><h3><a name="lua_Integer"><code>lua_Integer</code></a></h3> 3582 1.2 lneto <pre>typedef ... lua_Integer;</pre> 3583 1.1 mbalmer 3584 1.1 mbalmer <p> 3585 1.2 lneto The type of integers in Lua. 3586 1.1 mbalmer 3587 1.1 mbalmer 3588 1.1 mbalmer <p> 3589 1.2 lneto By default this type is <code>long long</code> 3590 1.2 lneto (usually a 64-bit two-complement integer), 3591 1.2 lneto but that can be changed in <code>luaconf.h</code> 3592 1.2 lneto to <code>long</code> or <code>int</code> 3593 1.2 lneto (usually a 32-bit two-complement integer). 3594 1.2 lneto 3595 1.2 lneto 3596 1.2 lneto <p> 3597 1.2 lneto Lua also defines the constants 3598 1.2 lneto <a name="pdf-LUA_MININTEGER"><code>LUA_MININTEGER</code></a> and <a name="pdf-LUA_MAXINTEGER"><code>LUA_MAXINTEGER</code></a>, 3599 1.2 lneto with the minimum and the maximum values that fit in this type. 3600 1.1 mbalmer 3601 1.1 mbalmer 3602 1.1 mbalmer 3603 1.1 mbalmer 3604 1.1 mbalmer 3605 1.1 mbalmer <hr><h3><a name="lua_isboolean"><code>lua_isboolean</code></a></h3><p> 3606 1.2 lneto <span class="apii">[-0, +0, –]</span> 3607 1.1 mbalmer <pre>int lua_isboolean (lua_State *L, int index);</pre> 3608 1.1 mbalmer 3609 1.1 mbalmer <p> 3610 1.2 lneto Returns 1 if the value at the given index is a boolean, 3611 1.1 mbalmer and 0 otherwise. 3612 1.1 mbalmer 3613 1.1 mbalmer 3614 1.1 mbalmer 3615 1.1 mbalmer 3616 1.1 mbalmer 3617 1.1 mbalmer <hr><h3><a name="lua_iscfunction"><code>lua_iscfunction</code></a></h3><p> 3618 1.2 lneto <span class="apii">[-0, +0, –]</span> 3619 1.1 mbalmer <pre>int lua_iscfunction (lua_State *L, int index);</pre> 3620 1.1 mbalmer 3621 1.1 mbalmer <p> 3622 1.2 lneto Returns 1 if the value at the given index is a C function, 3623 1.1 mbalmer and 0 otherwise. 3624 1.1 mbalmer 3625 1.1 mbalmer 3626 1.1 mbalmer 3627 1.1 mbalmer 3628 1.1 mbalmer 3629 1.1 mbalmer <hr><h3><a name="lua_isfunction"><code>lua_isfunction</code></a></h3><p> 3630 1.2 lneto <span class="apii">[-0, +0, –]</span> 3631 1.1 mbalmer <pre>int lua_isfunction (lua_State *L, int index);</pre> 3632 1.1 mbalmer 3633 1.1 mbalmer <p> 3634 1.2 lneto Returns 1 if the value at the given index is a function 3635 1.1 mbalmer (either C or Lua), and 0 otherwise. 3636 1.1 mbalmer 3637 1.1 mbalmer 3638 1.1 mbalmer 3639 1.1 mbalmer 3640 1.1 mbalmer 3641 1.2 lneto <hr><h3><a name="lua_isinteger"><code>lua_isinteger</code></a></h3><p> 3642 1.2 lneto <span class="apii">[-0, +0, –]</span> 3643 1.2 lneto <pre>int lua_isinteger (lua_State *L, int index);</pre> 3644 1.2 lneto 3645 1.2 lneto <p> 3646 1.2 lneto Returns 1 if the value at the given index is an integer 3647 1.2 lneto (that is, the value is a number and is represented as an integer), 3648 1.2 lneto and 0 otherwise. 3649 1.2 lneto 3650 1.2 lneto 3651 1.2 lneto 3652 1.2 lneto 3653 1.2 lneto 3654 1.1 mbalmer <hr><h3><a name="lua_islightuserdata"><code>lua_islightuserdata</code></a></h3><p> 3655 1.2 lneto <span class="apii">[-0, +0, –]</span> 3656 1.1 mbalmer <pre>int lua_islightuserdata (lua_State *L, int index);</pre> 3657 1.1 mbalmer 3658 1.1 mbalmer <p> 3659 1.2 lneto Returns 1 if the value at the given index is a light userdata, 3660 1.1 mbalmer and 0 otherwise. 3661 1.1 mbalmer 3662 1.1 mbalmer 3663 1.1 mbalmer 3664 1.1 mbalmer 3665 1.1 mbalmer 3666 1.1 mbalmer <hr><h3><a name="lua_isnil"><code>lua_isnil</code></a></h3><p> 3667 1.2 lneto <span class="apii">[-0, +0, –]</span> 3668 1.1 mbalmer <pre>int lua_isnil (lua_State *L, int index);</pre> 3669 1.1 mbalmer 3670 1.1 mbalmer <p> 3671 1.2 lneto Returns 1 if the value at the given index is <b>nil</b>, 3672 1.1 mbalmer and 0 otherwise. 3673 1.1 mbalmer 3674 1.1 mbalmer 3675 1.1 mbalmer 3676 1.1 mbalmer 3677 1.1 mbalmer 3678 1.1 mbalmer <hr><h3><a name="lua_isnone"><code>lua_isnone</code></a></h3><p> 3679 1.2 lneto <span class="apii">[-0, +0, –]</span> 3680 1.1 mbalmer <pre>int lua_isnone (lua_State *L, int index);</pre> 3681 1.1 mbalmer 3682 1.1 mbalmer <p> 3683 1.2 lneto Returns 1 if the given index is not valid, 3684 1.1 mbalmer and 0 otherwise. 3685 1.1 mbalmer 3686 1.1 mbalmer 3687 1.1 mbalmer 3688 1.1 mbalmer 3689 1.1 mbalmer 3690 1.1 mbalmer <hr><h3><a name="lua_isnoneornil"><code>lua_isnoneornil</code></a></h3><p> 3691 1.2 lneto <span class="apii">[-0, +0, –]</span> 3692 1.1 mbalmer <pre>int lua_isnoneornil (lua_State *L, int index);</pre> 3693 1.1 mbalmer 3694 1.1 mbalmer <p> 3695 1.2 lneto Returns 1 if the given index is not valid 3696 1.1 mbalmer or if the value at this index is <b>nil</b>, 3697 1.1 mbalmer and 0 otherwise. 3698 1.1 mbalmer 3699 1.1 mbalmer 3700 1.1 mbalmer 3701 1.1 mbalmer 3702 1.1 mbalmer 3703 1.1 mbalmer <hr><h3><a name="lua_isnumber"><code>lua_isnumber</code></a></h3><p> 3704 1.2 lneto <span class="apii">[-0, +0, –]</span> 3705 1.1 mbalmer <pre>int lua_isnumber (lua_State *L, int index);</pre> 3706 1.1 mbalmer 3707 1.1 mbalmer <p> 3708 1.2 lneto Returns 1 if the value at the given index is a number 3709 1.1 mbalmer or a string convertible to a number, 3710 1.1 mbalmer and 0 otherwise. 3711 1.1 mbalmer 3712 1.1 mbalmer 3713 1.1 mbalmer 3714 1.1 mbalmer 3715 1.1 mbalmer 3716 1.1 mbalmer <hr><h3><a name="lua_isstring"><code>lua_isstring</code></a></h3><p> 3717 1.2 lneto <span class="apii">[-0, +0, –]</span> 3718 1.1 mbalmer <pre>int lua_isstring (lua_State *L, int index);</pre> 3719 1.1 mbalmer 3720 1.1 mbalmer <p> 3721 1.2 lneto Returns 1 if the value at the given index is a string 3722 1.1 mbalmer or a number (which is always convertible to a string), 3723 1.1 mbalmer and 0 otherwise. 3724 1.1 mbalmer 3725 1.1 mbalmer 3726 1.1 mbalmer 3727 1.1 mbalmer 3728 1.1 mbalmer 3729 1.1 mbalmer <hr><h3><a name="lua_istable"><code>lua_istable</code></a></h3><p> 3730 1.2 lneto <span class="apii">[-0, +0, –]</span> 3731 1.1 mbalmer <pre>int lua_istable (lua_State *L, int index);</pre> 3732 1.1 mbalmer 3733 1.1 mbalmer <p> 3734 1.2 lneto Returns 1 if the value at the given index is a table, 3735 1.1 mbalmer and 0 otherwise. 3736 1.1 mbalmer 3737 1.1 mbalmer 3738 1.1 mbalmer 3739 1.1 mbalmer 3740 1.1 mbalmer 3741 1.1 mbalmer <hr><h3><a name="lua_isthread"><code>lua_isthread</code></a></h3><p> 3742 1.2 lneto <span class="apii">[-0, +0, –]</span> 3743 1.1 mbalmer <pre>int lua_isthread (lua_State *L, int index);</pre> 3744 1.1 mbalmer 3745 1.1 mbalmer <p> 3746 1.2 lneto Returns 1 if the value at the given index is a thread, 3747 1.1 mbalmer and 0 otherwise. 3748 1.1 mbalmer 3749 1.1 mbalmer 3750 1.1 mbalmer 3751 1.1 mbalmer 3752 1.1 mbalmer 3753 1.1 mbalmer <hr><h3><a name="lua_isuserdata"><code>lua_isuserdata</code></a></h3><p> 3754 1.2 lneto <span class="apii">[-0, +0, –]</span> 3755 1.1 mbalmer <pre>int lua_isuserdata (lua_State *L, int index);</pre> 3756 1.1 mbalmer 3757 1.1 mbalmer <p> 3758 1.2 lneto Returns 1 if the value at the given index is a userdata 3759 1.1 mbalmer (either full or light), and 0 otherwise. 3760 1.1 mbalmer 3761 1.1 mbalmer 3762 1.1 mbalmer 3763 1.1 mbalmer 3764 1.1 mbalmer 3765 1.2 lneto <hr><h3><a name="lua_isyieldable"><code>lua_isyieldable</code></a></h3><p> 3766 1.2 lneto <span class="apii">[-0, +0, –]</span> 3767 1.2 lneto <pre>int lua_isyieldable (lua_State *L);</pre> 3768 1.2 lneto 3769 1.2 lneto <p> 3770 1.2 lneto Returns 1 if the given coroutine can yield, 3771 1.2 lneto and 0 otherwise. 3772 1.2 lneto 3773 1.2 lneto 3774 1.2 lneto 3775 1.2 lneto 3776 1.2 lneto 3777 1.2 lneto <hr><h3><a name="lua_KFunction"><code>lua_KFunction</code></a></h3> 3778 1.2 lneto <pre>typedef int (*lua_KFunction) (lua_State *L, int status, int ctx);</pre> 3779 1.2 lneto 3780 1.2 lneto <p> 3781 1.2 lneto Type for continuation functions (see <a href="#4.7">§4.7</a>). 3782 1.2 lneto 3783 1.2 lneto 3784 1.2 lneto 3785 1.2 lneto 3786 1.2 lneto 3787 1.2 lneto <hr><h3><a name="lua_len"><code>lua_len</code></a></h3><p> 3788 1.2 lneto <span class="apii">[-0, +1, <em>e</em>]</span> 3789 1.2 lneto <pre>void lua_len (lua_State *L, int index);</pre> 3790 1.1 mbalmer 3791 1.1 mbalmer <p> 3792 1.2 lneto Returns the "length" of the value at the given index; 3793 1.2 lneto it is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">§3.4.7</a>). 3794 1.2 lneto The result is pushed on the stack. 3795 1.1 mbalmer 3796 1.1 mbalmer 3797 1.1 mbalmer 3798 1.1 mbalmer 3799 1.1 mbalmer 3800 1.1 mbalmer <hr><h3><a name="lua_load"><code>lua_load</code></a></h3><p> 3801 1.2 lneto <span class="apii">[-0, +1, –]</span> 3802 1.1 mbalmer <pre>int lua_load (lua_State *L, 3803 1.1 mbalmer lua_Reader reader, 3804 1.1 mbalmer void *data, 3805 1.2 lneto const char *source, 3806 1.2 lneto const char *mode);</pre> 3807 1.1 mbalmer 3808 1.1 mbalmer <p> 3809 1.2 lneto Loads a Lua chunk (without running it). 3810 1.1 mbalmer If there are no errors, 3811 1.2 lneto <code>lua_load</code> pushes the compiled chunk as a Lua 3812 1.1 mbalmer function on top of the stack. 3813 1.1 mbalmer Otherwise, it pushes an error message. 3814 1.2 lneto 3815 1.2 lneto 3816 1.2 lneto <p> 3817 1.2 lneto The return values of <code>lua_load</code> are: 3818 1.1 mbalmer 3819 1.1 mbalmer <ul> 3820 1.1 mbalmer 3821 1.2 lneto <li><b><a href="#pdf-LUA_OK"><code>LUA_OK</code></a>: </b> no errors;</li> 3822 1.2 lneto 3823 1.2 lneto <li><b><a name="pdf-LUA_ERRSYNTAX"><code>LUA_ERRSYNTAX</code></a>: </b> 3824 1.2 lneto syntax error during precompilation;</li> 3825 1.1 mbalmer 3826 1.2 lneto <li><b><a href="#pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>: </b> 3827 1.2 lneto memory allocation error;</li> 3828 1.1 mbalmer 3829 1.2 lneto <li><b><a href="#pdf-LUA_ERRGCMM"><code>LUA_ERRGCMM</code></a>: </b> 3830 1.2 lneto error while running a <code>__gc</code> metamethod. 3831 1.2 lneto (This error has no relation with the chunk being loaded. 3832 1.2 lneto It is generated by the garbage collector.) 3833 1.2 lneto </li> 3834 1.1 mbalmer 3835 1.1 mbalmer </ul> 3836 1.1 mbalmer 3837 1.1 mbalmer <p> 3838 1.2 lneto The <code>lua_load</code> function uses a user-supplied <code>reader</code> function 3839 1.2 lneto to read the chunk (see <a href="#lua_Reader"><code>lua_Reader</code></a>). 3840 1.2 lneto The <code>data</code> argument is an opaque value passed to the reader function. 3841 1.2 lneto 3842 1.2 lneto 3843 1.2 lneto <p> 3844 1.2 lneto The <code>source</code> argument gives a name to the chunk, 3845 1.2 lneto which is used for error messages and in debug information (see <a href="#4.9">§4.9</a>). 3846 1.1 mbalmer 3847 1.1 mbalmer 3848 1.1 mbalmer <p> 3849 1.2 lneto <code>lua_load</code> automatically detects whether the chunk is text or binary 3850 1.1 mbalmer and loads it accordingly (see program <code>luac</code>). 3851 1.2 lneto The string <code>mode</code> works as in function <a href="#pdf-load"><code>load</code></a>, 3852 1.2 lneto with the addition that 3853 1.2 lneto a <code>NULL</code> value is equivalent to the string "<code>bt</code>". 3854 1.1 mbalmer 3855 1.1 mbalmer 3856 1.1 mbalmer <p> 3857 1.2 lneto <code>lua_load</code> uses the stack internally, 3858 1.2 lneto so the reader function must always leave the stack 3859 1.2 lneto unmodified when returning. 3860 1.1 mbalmer 3861 1.1 mbalmer 3862 1.1 mbalmer <p> 3863 1.2 lneto If the resulting function has one upvalue, 3864 1.2 lneto this upvalue is set to the value of the global environment 3865 1.2 lneto stored at index <code>LUA_RIDX_GLOBALS</code> in the registry (see <a href="#4.5">§4.5</a>). 3866 1.2 lneto When loading main chunks, 3867 1.2 lneto this upvalue will be the <code>_ENV</code> variable (see <a href="#2.2">§2.2</a>). 3868 1.1 mbalmer 3869 1.1 mbalmer 3870 1.1 mbalmer 3871 1.1 mbalmer 3872 1.1 mbalmer 3873 1.1 mbalmer <hr><h3><a name="lua_newstate"><code>lua_newstate</code></a></h3><p> 3874 1.2 lneto <span class="apii">[-0, +0, –]</span> 3875 1.1 mbalmer <pre>lua_State *lua_newstate (lua_Alloc f, void *ud);</pre> 3876 1.1 mbalmer 3877 1.1 mbalmer <p> 3878 1.2 lneto Creates a new thread running in a new, independent state. 3879 1.2 lneto Returns <code>NULL</code> if it cannot create the thread or the state 3880 1.1 mbalmer (due to lack of memory). 3881 1.1 mbalmer The argument <code>f</code> is the allocator function; 3882 1.1 mbalmer Lua does all memory allocation for this state through this function. 3883 1.1 mbalmer The second argument, <code>ud</code>, is an opaque pointer that Lua 3884 1.2 lneto passes to the allocator in every call. 3885 1.1 mbalmer 3886 1.1 mbalmer 3887 1.1 mbalmer 3888 1.1 mbalmer 3889 1.1 mbalmer 3890 1.1 mbalmer <hr><h3><a name="lua_newtable"><code>lua_newtable</code></a></h3><p> 3891 1.2 lneto <span class="apii">[-0, +1, <em>e</em>]</span> 3892 1.1 mbalmer <pre>void lua_newtable (lua_State *L);</pre> 3893 1.1 mbalmer 3894 1.1 mbalmer <p> 3895 1.1 mbalmer Creates a new empty table and pushes it onto the stack. 3896 1.1 mbalmer It is equivalent to <code>lua_createtable(L, 0, 0)</code>. 3897 1.1 mbalmer 3898 1.1 mbalmer 3899 1.1 mbalmer 3900 1.1 mbalmer 3901 1.1 mbalmer 3902 1.1 mbalmer <hr><h3><a name="lua_newthread"><code>lua_newthread</code></a></h3><p> 3903 1.2 lneto <span class="apii">[-0, +1, <em>e</em>]</span> 3904 1.1 mbalmer <pre>lua_State *lua_newthread (lua_State *L);</pre> 3905 1.1 mbalmer 3906 1.1 mbalmer <p> 3907 1.1 mbalmer Creates a new thread, pushes it on the stack, 3908 1.1 mbalmer and returns a pointer to a <a href="#lua_State"><code>lua_State</code></a> that represents this new thread. 3909 1.2 lneto The new thread returned by this function shares with the original thread 3910 1.2 lneto its global environment, 3911 1.1 mbalmer but has an independent execution stack. 3912 1.1 mbalmer 3913 1.1 mbalmer 3914 1.1 mbalmer <p> 3915 1.1 mbalmer There is no explicit function to close or to destroy a thread. 3916 1.1 mbalmer Threads are subject to garbage collection, 3917 1.1 mbalmer like any Lua object. 3918 1.1 mbalmer 3919 1.1 mbalmer 3920 1.1 mbalmer 3921 1.1 mbalmer 3922 1.1 mbalmer 3923 1.1 mbalmer <hr><h3><a name="lua_newuserdata"><code>lua_newuserdata</code></a></h3><p> 3924 1.2 lneto <span class="apii">[-0, +1, <em>e</em>]</span> 3925 1.1 mbalmer <pre>void *lua_newuserdata (lua_State *L, size_t size);</pre> 3926 1.1 mbalmer 3927 1.1 mbalmer <p> 3928 1.1 mbalmer This function allocates a new block of memory with the given size, 3929 1.1 mbalmer pushes onto the stack a new full userdata with the block address, 3930 1.1 mbalmer and returns this address. 3931 1.2 lneto The host program can freely use this memory. 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_next"><code>lua_next</code></a></h3><p> 3938 1.1 mbalmer <span class="apii">[-1, +(2|0), <em>e</em>]</span> 3939 1.1 mbalmer <pre>int lua_next (lua_State *L, int index);</pre> 3940 1.1 mbalmer 3941 1.1 mbalmer <p> 3942 1.1 mbalmer Pops a key from the stack, 3943 1.2 lneto and pushes a key–value pair from the table at the given index 3944 1.1 mbalmer (the "next" pair after the given key). 3945 1.1 mbalmer If there are no more elements in the table, 3946 1.1 mbalmer then <a href="#lua_next"><code>lua_next</code></a> returns 0 (and pushes nothing). 3947 1.1 mbalmer 3948 1.1 mbalmer 3949 1.1 mbalmer <p> 3950 1.1 mbalmer A typical traversal looks like this: 3951 1.1 mbalmer 3952 1.1 mbalmer <pre> 3953 1.1 mbalmer /* table is in the stack at index 't' */ 3954 1.1 mbalmer lua_pushnil(L); /* first key */ 3955 1.1 mbalmer while (lua_next(L, t) != 0) { 3956 1.1 mbalmer /* uses 'key' (at index -2) and 'value' (at index -1) */ 3957 1.1 mbalmer printf("%s - %s\n", 3958 1.1 mbalmer lua_typename(L, lua_type(L, -2)), 3959 1.1 mbalmer lua_typename(L, lua_type(L, -1))); 3960 1.1 mbalmer /* removes 'value'; keeps 'key' for next iteration */ 3961 1.1 mbalmer lua_pop(L, 1); 3962 1.1 mbalmer } 3963 1.1 mbalmer </pre> 3964 1.1 mbalmer 3965 1.1 mbalmer <p> 3966 1.1 mbalmer While traversing a table, 3967 1.1 mbalmer do not call <a href="#lua_tolstring"><code>lua_tolstring</code></a> directly on a key, 3968 1.1 mbalmer unless you know that the key is actually a string. 3969 1.2 lneto Recall that <a href="#lua_tolstring"><code>lua_tolstring</code></a> may change 3970 1.1 mbalmer the value at the given index; 3971 1.1 mbalmer this confuses the next call to <a href="#lua_next"><code>lua_next</code></a>. 3972 1.1 mbalmer 3973 1.1 mbalmer 3974 1.2 lneto <p> 3975 1.2 lneto See function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying 3976 1.2 lneto the table during its traversal. 3977 1.2 lneto 3978 1.2 lneto 3979 1.1 mbalmer 3980 1.1 mbalmer 3981 1.1 mbalmer 3982 1.1 mbalmer <hr><h3><a name="lua_Number"><code>lua_Number</code></a></h3> 3983 1.1 mbalmer <pre>typedef double lua_Number;</pre> 3984 1.1 mbalmer 3985 1.1 mbalmer <p> 3986 1.2 lneto The type of floats in Lua. 3987 1.1 mbalmer 3988 1.1 mbalmer 3989 1.1 mbalmer <p> 3990 1.2 lneto By default this type is double, 3991 1.2 lneto but that can be changed in <code>luaconf.h</code> to a single float. 3992 1.2 lneto 3993 1.2 lneto 3994 1.1 mbalmer 3995 1.1 mbalmer 3996 1.1 mbalmer 3997 1.2 lneto <hr><h3><a name="lua_numtointeger"><code>lua_numtointeger</code></a></h3> 3998 1.2 lneto <pre>int lua_numtointeger (lua_Number n, lua_Integer *p);</pre> 3999 1.1 mbalmer 4000 1.2 lneto <p> 4001 1.2 lneto Converts a Lua float to a Lua integer. 4002 1.2 lneto This macro assumes that <code>n</code> has an integral value. 4003 1.2 lneto If that value is within the range of Lua integers, 4004 1.2 lneto it is converted to an integer and assigned to <code>*p</code>. 4005 1.2 lneto The macro results in a boolean indicating whether the 4006 1.2 lneto conversion was successful. 4007 1.2 lneto (Note that this range test can be tricky to do 4008 1.2 lneto correctly without this macro, 4009 1.2 lneto due to roundings.) 4010 1.1 mbalmer 4011 1.1 mbalmer 4012 1.1 mbalmer <p> 4013 1.2 lneto This macro may evaluate its arguments more than once. 4014 1.1 mbalmer 4015 1.1 mbalmer 4016 1.1 mbalmer 4017 1.1 mbalmer 4018 1.1 mbalmer 4019 1.1 mbalmer <hr><h3><a name="lua_pcall"><code>lua_pcall</code></a></h3><p> 4020 1.2 lneto <span class="apii">[-(nargs + 1), +(nresults|1), –]</span> 4021 1.2 lneto <pre>int lua_pcall (lua_State *L, int nargs, int nresults, int msgh);</pre> 4022 1.1 mbalmer 4023 1.1 mbalmer <p> 4024 1.1 mbalmer Calls a function in protected mode. 4025 1.1 mbalmer 4026 1.1 mbalmer 4027 1.1 mbalmer <p> 4028 1.1 mbalmer Both <code>nargs</code> and <code>nresults</code> have the same meaning as 4029 1.1 mbalmer in <a href="#lua_call"><code>lua_call</code></a>. 4030 1.1 mbalmer If there are no errors during the call, 4031 1.1 mbalmer <a href="#lua_pcall"><code>lua_pcall</code></a> behaves exactly like <a href="#lua_call"><code>lua_call</code></a>. 4032 1.1 mbalmer However, if there is any error, 4033 1.1 mbalmer <a href="#lua_pcall"><code>lua_pcall</code></a> catches it, 4034 1.1 mbalmer pushes a single value on the stack (the error message), 4035 1.1 mbalmer and returns an error code. 4036 1.1 mbalmer Like <a href="#lua_call"><code>lua_call</code></a>, 4037 1.1 mbalmer <a href="#lua_pcall"><code>lua_pcall</code></a> always removes the function 4038 1.1 mbalmer and its arguments from the stack. 4039 1.1 mbalmer 4040 1.1 mbalmer 4041 1.1 mbalmer <p> 4042 1.2 lneto If <code>msgh</code> is 0, 4043 1.1 mbalmer then the error message returned on the stack 4044 1.1 mbalmer is exactly the original error message. 4045 1.2 lneto Otherwise, <code>msgh</code> is the stack index of a 4046 1.2 lneto <em>message handler</em>. 4047 1.1 mbalmer (In the current implementation, this index cannot be a pseudo-index.) 4048 1.1 mbalmer In case of runtime errors, 4049 1.1 mbalmer this function will be called with the error message 4050 1.2 lneto and its return value will be the message 4051 1.2 lneto returned on the stack by <a href="#lua_pcall"><code>lua_pcall</code></a>. 4052 1.1 mbalmer 4053 1.1 mbalmer 4054 1.1 mbalmer <p> 4055 1.2 lneto Typically, the message handler is used to add more debug 4056 1.1 mbalmer information to the error message, such as a stack traceback. 4057 1.1 mbalmer Such information cannot be gathered after the return of <a href="#lua_pcall"><code>lua_pcall</code></a>, 4058 1.1 mbalmer since by then the stack has unwound. 4059 1.1 mbalmer 4060 1.1 mbalmer 4061 1.1 mbalmer <p> 4062 1.2 lneto The <a href="#lua_pcall"><code>lua_pcall</code></a> function returns one of the following constants 4063 1.1 mbalmer (defined in <code>lua.h</code>): 4064 1.1 mbalmer 4065 1.1 mbalmer <ul> 4066 1.1 mbalmer 4067 1.2 lneto <li><b><a name="pdf-LUA_OK"><code>LUA_OK</code></a> (0): </b> 4068 1.2 lneto success.</li> 4069 1.2 lneto 4070 1.2 lneto <li><b><a name="pdf-LUA_ERRRUN"><code>LUA_ERRRUN</code></a>: </b> 4071 1.1 mbalmer a runtime error. 4072 1.1 mbalmer </li> 4073 1.1 mbalmer 4074 1.2 lneto <li><b><a name="pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>: </b> 4075 1.1 mbalmer memory allocation error. 4076 1.2 lneto For such errors, Lua does not call the message handler. 4077 1.2 lneto </li> 4078 1.2 lneto 4079 1.2 lneto <li><b><a name="pdf-LUA_ERRERR"><code>LUA_ERRERR</code></a>: </b> 4080 1.2 lneto error while running the message handler. 4081 1.1 mbalmer </li> 4082 1.1 mbalmer 4083 1.2 lneto <li><b><a name="pdf-LUA_ERRGCMM"><code>LUA_ERRGCMM</code></a>: </b> 4084 1.2 lneto error while running a <code>__gc</code> metamethod. 4085 1.2 lneto (This error typically has no relation with the function being called.) 4086 1.1 mbalmer </li> 4087 1.1 mbalmer 4088 1.1 mbalmer </ul> 4089 1.1 mbalmer 4090 1.1 mbalmer 4091 1.1 mbalmer 4092 1.1 mbalmer 4093 1.2 lneto <hr><h3><a name="lua_pcallk"><code>lua_pcallk</code></a></h3><p> 4094 1.2 lneto <span class="apii">[-(nargs + 1), +(nresults|1), –]</span> 4095 1.2 lneto <pre>int lua_pcallk (lua_State *L, 4096 1.2 lneto int nargs, 4097 1.2 lneto int nresults, 4098 1.2 lneto int errfunc, 4099 1.2 lneto int ctx, 4100 1.2 lneto lua_KFunction k);</pre> 4101 1.2 lneto 4102 1.2 lneto <p> 4103 1.2 lneto This function behaves exactly like <a href="#lua_pcall"><code>lua_pcall</code></a>, 4104 1.2 lneto but allows the called function to yield (see <a href="#4.7">§4.7</a>). 4105 1.2 lneto 4106 1.2 lneto 4107 1.2 lneto 4108 1.2 lneto 4109 1.2 lneto 4110 1.1 mbalmer <hr><h3><a name="lua_pop"><code>lua_pop</code></a></h3><p> 4111 1.2 lneto <span class="apii">[-n, +0, –]</span> 4112 1.1 mbalmer <pre>void lua_pop (lua_State *L, int n);</pre> 4113 1.1 mbalmer 4114 1.1 mbalmer <p> 4115 1.1 mbalmer Pops <code>n</code> elements from the stack. 4116 1.1 mbalmer 4117 1.1 mbalmer 4118 1.1 mbalmer 4119 1.1 mbalmer 4120 1.1 mbalmer 4121 1.1 mbalmer <hr><h3><a name="lua_pushboolean"><code>lua_pushboolean</code></a></h3><p> 4122 1.2 lneto <span class="apii">[-0, +1, –]</span> 4123 1.1 mbalmer <pre>void lua_pushboolean (lua_State *L, int b);</pre> 4124 1.1 mbalmer 4125 1.1 mbalmer <p> 4126 1.1 mbalmer Pushes a boolean value with value <code>b</code> onto the stack. 4127 1.1 mbalmer 4128 1.1 mbalmer 4129 1.1 mbalmer 4130 1.1 mbalmer 4131 1.1 mbalmer 4132 1.1 mbalmer <hr><h3><a name="lua_pushcclosure"><code>lua_pushcclosure</code></a></h3><p> 4133 1.2 lneto <span class="apii">[-n, +1, <em>e</em>]</span> 4134 1.1 mbalmer <pre>void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);</pre> 4135 1.1 mbalmer 4136 1.1 mbalmer <p> 4137 1.1 mbalmer Pushes a new C closure onto the stack. 4138 1.1 mbalmer 4139 1.1 mbalmer 4140 1.1 mbalmer <p> 4141 1.1 mbalmer When a C function is created, 4142 1.1 mbalmer it is possible to associate some values with it, 4143 1.2 lneto thus creating a C closure (see <a href="#4.4">§4.4</a>); 4144 1.1 mbalmer these values are then accessible to the function whenever it is called. 4145 1.1 mbalmer To associate values with a C function, 4146 1.2 lneto first these values must be pushed onto the stack 4147 1.1 mbalmer (when there are multiple values, the first value is pushed first). 4148 1.1 mbalmer Then <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> 4149 1.1 mbalmer is called to create and push the C function onto the stack, 4150 1.2 lneto with the argument <code>n</code> telling how many values will be 4151 1.1 mbalmer associated with the function. 4152 1.1 mbalmer <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> also pops these values from the stack. 4153 1.1 mbalmer 4154 1.1 mbalmer 4155 1.1 mbalmer <p> 4156 1.1 mbalmer The maximum value for <code>n</code> is 255. 4157 1.1 mbalmer 4158 1.1 mbalmer 4159 1.2 lneto <p> 4160 1.2 lneto When <code>n</code> is zero, 4161 1.2 lneto this function creates a <em>light C function</em>, 4162 1.2 lneto which is just a pointer to the C function. 4163 1.2 lneto In that case, it never raises a memory error. 4164 1.2 lneto 4165 1.2 lneto 4166 1.1 mbalmer 4167 1.1 mbalmer 4168 1.1 mbalmer 4169 1.1 mbalmer <hr><h3><a name="lua_pushcfunction"><code>lua_pushcfunction</code></a></h3><p> 4170 1.2 lneto <span class="apii">[-0, +1, –]</span> 4171 1.1 mbalmer <pre>void lua_pushcfunction (lua_State *L, lua_CFunction f);</pre> 4172 1.1 mbalmer 4173 1.1 mbalmer <p> 4174 1.1 mbalmer Pushes a C function onto the stack. 4175 1.1 mbalmer This function receives a pointer to a C function 4176 1.1 mbalmer and pushes onto the stack a Lua value of type <code>function</code> that, 4177 1.1 mbalmer when called, invokes the corresponding C function. 4178 1.1 mbalmer 4179 1.1 mbalmer 4180 1.1 mbalmer <p> 4181 1.1 mbalmer Any function to be registered in Lua must 4182 1.1 mbalmer follow the correct protocol to receive its parameters 4183 1.1 mbalmer and return its results (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 4184 1.1 mbalmer 4185 1.1 mbalmer 4186 1.1 mbalmer <p> 4187 1.1 mbalmer <code>lua_pushcfunction</code> is defined as a macro: 4188 1.1 mbalmer 4189 1.1 mbalmer <pre> 4190 1.1 mbalmer #define lua_pushcfunction(L,f) lua_pushcclosure(L,f,0) 4191 1.2 lneto </pre><p> 4192 1.2 lneto Note that <code>f</code> is used twice. 4193 1.2 lneto 4194 1.1 mbalmer 4195 1.1 mbalmer 4196 1.1 mbalmer 4197 1.1 mbalmer 4198 1.1 mbalmer <hr><h3><a name="lua_pushfstring"><code>lua_pushfstring</code></a></h3><p> 4199 1.2 lneto <span class="apii">[-0, +1, <em>e</em>]</span> 4200 1.1 mbalmer <pre>const char *lua_pushfstring (lua_State *L, const char *fmt, ...);</pre> 4201 1.1 mbalmer 4202 1.1 mbalmer <p> 4203 1.1 mbalmer Pushes onto the stack a formatted string 4204 1.1 mbalmer and returns a pointer to this string. 4205 1.2 lneto It is similar to the ANSI C function <code>sprintf</code>, 4206 1.1 mbalmer but has some important differences: 4207 1.1 mbalmer 4208 1.1 mbalmer <ul> 4209 1.1 mbalmer 4210 1.1 mbalmer <li> 4211 1.1 mbalmer You do not have to allocate space for the result: 4212 1.1 mbalmer the result is a Lua string and Lua takes care of memory allocation 4213 1.1 mbalmer (and deallocation, through garbage collection). 4214 1.1 mbalmer </li> 4215 1.1 mbalmer 4216 1.1 mbalmer <li> 4217 1.1 mbalmer The conversion specifiers are quite restricted. 4218 1.1 mbalmer There are no flags, widths, or precisions. 4219 1.1 mbalmer The conversion specifiers can only be 4220 1.2 lneto '<code>%%</code>' (inserts the character '<code>%</code>'), 4221 1.1 mbalmer '<code>%s</code>' (inserts a zero-terminated string, with no size restrictions), 4222 1.1 mbalmer '<code>%f</code>' (inserts a <a href="#lua_Number"><code>lua_Number</code></a>), 4223 1.2 lneto '<code>%L</code>' (inserts a <a href="#lua_Integer"><code>lua_Integer</code></a>), 4224 1.1 mbalmer '<code>%p</code>' (inserts a pointer as a hexadecimal numeral), 4225 1.2 lneto '<code>%d</code>' (inserts an <code>int</code>), 4226 1.2 lneto '<code>%c</code>' (inserts an <code>int</code> as a one-byte character), and 4227 1.2 lneto '<code>%U</code>' (inserts an <code>int</code> as a UTF-8 byte sequence). 4228 1.1 mbalmer </li> 4229 1.1 mbalmer 4230 1.1 mbalmer </ul> 4231 1.1 mbalmer 4232 1.1 mbalmer 4233 1.1 mbalmer 4234 1.1 mbalmer 4235 1.2 lneto <hr><h3><a name="lua_pushglobaltable"><code>lua_pushglobaltable</code></a></h3><p> 4236 1.2 lneto <span class="apii">[-0, +1, –]</span> 4237 1.2 lneto <pre>void lua_pushglobaltable (lua_State *L);</pre> 4238 1.2 lneto 4239 1.2 lneto <p> 4240 1.2 lneto Pushes the global environment onto the stack. 4241 1.2 lneto 4242 1.2 lneto 4243 1.2 lneto 4244 1.2 lneto 4245 1.2 lneto 4246 1.1 mbalmer <hr><h3><a name="lua_pushinteger"><code>lua_pushinteger</code></a></h3><p> 4247 1.2 lneto <span class="apii">[-0, +1, –]</span> 4248 1.1 mbalmer <pre>void lua_pushinteger (lua_State *L, lua_Integer n);</pre> 4249 1.1 mbalmer 4250 1.1 mbalmer <p> 4251 1.2 lneto Pushes an integer with value <code>n</code> onto the stack. 4252 1.1 mbalmer 4253 1.1 mbalmer 4254 1.1 mbalmer 4255 1.1 mbalmer 4256 1.1 mbalmer 4257 1.1 mbalmer <hr><h3><a name="lua_pushlightuserdata"><code>lua_pushlightuserdata</code></a></h3><p> 4258 1.2 lneto <span class="apii">[-0, +1, –]</span> 4259 1.1 mbalmer <pre>void lua_pushlightuserdata (lua_State *L, void *p);</pre> 4260 1.1 mbalmer 4261 1.1 mbalmer <p> 4262 1.1 mbalmer Pushes a light userdata onto the stack. 4263 1.1 mbalmer 4264 1.1 mbalmer 4265 1.1 mbalmer <p> 4266 1.1 mbalmer Userdata represent C values in Lua. 4267 1.2 lneto A <em>light userdata</em> represents a pointer, a <code>void*</code>. 4268 1.1 mbalmer It is a value (like a number): 4269 1.1 mbalmer you do not create it, it has no individual metatable, 4270 1.1 mbalmer and it is not collected (as it was never created). 4271 1.1 mbalmer A light userdata is equal to "any" 4272 1.1 mbalmer light userdata with the same C address. 4273 1.1 mbalmer 4274 1.1 mbalmer 4275 1.1 mbalmer 4276 1.1 mbalmer 4277 1.1 mbalmer 4278 1.1 mbalmer <hr><h3><a name="lua_pushliteral"><code>lua_pushliteral</code></a></h3><p> 4279 1.2 lneto <span class="apii">[-0, +1, <em>e</em>]</span> 4280 1.2 lneto <pre>const char *lua_pushliteral (lua_State *L, const char *s);</pre> 4281 1.1 mbalmer 4282 1.1 mbalmer <p> 4283 1.1 mbalmer This macro is equivalent to <a href="#lua_pushlstring"><code>lua_pushlstring</code></a>, 4284 1.1 mbalmer but can be used only when <code>s</code> is a literal string. 4285 1.2 lneto It automatically provides the string length. 4286 1.1 mbalmer 4287 1.1 mbalmer 4288 1.1 mbalmer 4289 1.1 mbalmer 4290 1.1 mbalmer 4291 1.1 mbalmer <hr><h3><a name="lua_pushlstring"><code>lua_pushlstring</code></a></h3><p> 4292 1.2 lneto <span class="apii">[-0, +1, <em>e</em>]</span> 4293 1.2 lneto <pre>const char *lua_pushlstring (lua_State *L, const char *s, size_t len);</pre> 4294 1.1 mbalmer 4295 1.1 mbalmer <p> 4296 1.1 mbalmer Pushes the string pointed to by <code>s</code> with size <code>len</code> 4297 1.1 mbalmer onto the stack. 4298 1.1 mbalmer Lua makes (or reuses) an internal copy of the given string, 4299 1.1 mbalmer so the memory at <code>s</code> can be freed or reused immediately after 4300 1.1 mbalmer the function returns. 4301 1.2 lneto The string can contain any binary data, 4302 1.2 lneto including embedded zeros. 4303 1.2 lneto 4304 1.2 lneto 4305 1.2 lneto <p> 4306 1.2 lneto Returns a pointer to the internal copy of the string. 4307 1.1 mbalmer 4308 1.1 mbalmer 4309 1.1 mbalmer 4310 1.1 mbalmer 4311 1.1 mbalmer 4312 1.1 mbalmer <hr><h3><a name="lua_pushnil"><code>lua_pushnil</code></a></h3><p> 4313 1.2 lneto <span class="apii">[-0, +1, –]</span> 4314 1.1 mbalmer <pre>void lua_pushnil (lua_State *L);</pre> 4315 1.1 mbalmer 4316 1.1 mbalmer <p> 4317 1.1 mbalmer Pushes a nil value onto the stack. 4318 1.1 mbalmer 4319 1.1 mbalmer 4320 1.1 mbalmer 4321 1.1 mbalmer 4322 1.1 mbalmer 4323 1.1 mbalmer <hr><h3><a name="lua_pushnumber"><code>lua_pushnumber</code></a></h3><p> 4324 1.2 lneto <span class="apii">[-0, +1, –]</span> 4325 1.1 mbalmer <pre>void lua_pushnumber (lua_State *L, lua_Number n);</pre> 4326 1.1 mbalmer 4327 1.1 mbalmer <p> 4328 1.2 lneto Pushes a float with value <code>n</code> onto the stack. 4329 1.1 mbalmer 4330 1.1 mbalmer 4331 1.1 mbalmer 4332 1.1 mbalmer 4333 1.1 mbalmer 4334 1.1 mbalmer <hr><h3><a name="lua_pushstring"><code>lua_pushstring</code></a></h3><p> 4335 1.2 lneto <span class="apii">[-0, +1, <em>e</em>]</span> 4336 1.2 lneto <pre>const char *lua_pushstring (lua_State *L, const char *s);</pre> 4337 1.1 mbalmer 4338 1.1 mbalmer <p> 4339 1.1 mbalmer Pushes the zero-terminated string pointed to by <code>s</code> 4340 1.1 mbalmer onto the stack. 4341 1.1 mbalmer Lua makes (or reuses) an internal copy of the given string, 4342 1.1 mbalmer so the memory at <code>s</code> can be freed or reused immediately after 4343 1.1 mbalmer the function returns. 4344 1.2 lneto 4345 1.2 lneto 4346 1.2 lneto <p> 4347 1.2 lneto Returns a pointer to the internal copy of the string. 4348 1.2 lneto 4349 1.2 lneto 4350 1.2 lneto <p> 4351 1.2 lneto If <code>s</code> is <code>NULL</code>, pushes <b>nil</b> and returns <code>NULL</code>. 4352 1.1 mbalmer 4353 1.1 mbalmer 4354 1.1 mbalmer 4355 1.1 mbalmer 4356 1.1 mbalmer 4357 1.1 mbalmer <hr><h3><a name="lua_pushthread"><code>lua_pushthread</code></a></h3><p> 4358 1.2 lneto <span class="apii">[-0, +1, –]</span> 4359 1.1 mbalmer <pre>int lua_pushthread (lua_State *L);</pre> 4360 1.1 mbalmer 4361 1.1 mbalmer <p> 4362 1.1 mbalmer Pushes the thread represented by <code>L</code> onto the stack. 4363 1.1 mbalmer Returns 1 if this thread is the main thread of its state. 4364 1.1 mbalmer 4365 1.1 mbalmer 4366 1.1 mbalmer 4367 1.1 mbalmer 4368 1.1 mbalmer 4369 1.2 lneto <hr><h3><a name="lua_pushunsigned"><code>lua_pushunsigned</code></a></h3><p> 4370 1.2 lneto <span class="apii">[-0, +1, –]</span> 4371 1.2 lneto <pre>void lua_pushunsigned (lua_State *L, lua_Unsigned n);</pre> 4372 1.2 lneto 4373 1.2 lneto <p> 4374 1.2 lneto Pushes an integer with value <code>n</code> onto the stack. 4375 1.2 lneto 4376 1.2 lneto 4377 1.2 lneto 4378 1.2 lneto 4379 1.2 lneto 4380 1.1 mbalmer <hr><h3><a name="lua_pushvalue"><code>lua_pushvalue</code></a></h3><p> 4381 1.2 lneto <span class="apii">[-0, +1, –]</span> 4382 1.1 mbalmer <pre>void lua_pushvalue (lua_State *L, int index);</pre> 4383 1.1 mbalmer 4384 1.1 mbalmer <p> 4385 1.2 lneto Pushes a copy of the element at the given index 4386 1.1 mbalmer onto the stack. 4387 1.1 mbalmer 4388 1.1 mbalmer 4389 1.1 mbalmer 4390 1.1 mbalmer 4391 1.1 mbalmer 4392 1.1 mbalmer <hr><h3><a name="lua_pushvfstring"><code>lua_pushvfstring</code></a></h3><p> 4393 1.2 lneto <span class="apii">[-0, +1, <em>e</em>]</span> 4394 1.1 mbalmer <pre>const char *lua_pushvfstring (lua_State *L, 4395 1.1 mbalmer const char *fmt, 4396 1.1 mbalmer va_list argp);</pre> 4397 1.1 mbalmer 4398 1.1 mbalmer <p> 4399 1.1 mbalmer Equivalent to <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>, except that it receives a <code>va_list</code> 4400 1.1 mbalmer instead of a variable number of arguments. 4401 1.1 mbalmer 4402 1.1 mbalmer 4403 1.1 mbalmer 4404 1.1 mbalmer 4405 1.1 mbalmer 4406 1.1 mbalmer <hr><h3><a name="lua_rawequal"><code>lua_rawequal</code></a></h3><p> 4407 1.2 lneto <span class="apii">[-0, +0, –]</span> 4408 1.1 mbalmer <pre>int lua_rawequal (lua_State *L, int index1, int index2);</pre> 4409 1.1 mbalmer 4410 1.1 mbalmer <p> 4411 1.2 lneto Returns 1 if the two values in indices <code>index1</code> and 4412 1.1 mbalmer <code>index2</code> are primitively equal 4413 1.1 mbalmer (that is, without calling metamethods). 4414 1.1 mbalmer Otherwise returns 0. 4415 1.1 mbalmer Also returns 0 if any of the indices are non valid. 4416 1.1 mbalmer 4417 1.1 mbalmer 4418 1.1 mbalmer 4419 1.1 mbalmer 4420 1.1 mbalmer 4421 1.1 mbalmer <hr><h3><a name="lua_rawget"><code>lua_rawget</code></a></h3><p> 4422 1.2 lneto <span class="apii">[-1, +1, –]</span> 4423 1.2 lneto <pre>int lua_rawget (lua_State *L, int index);</pre> 4424 1.1 mbalmer 4425 1.1 mbalmer <p> 4426 1.1 mbalmer Similar to <a href="#lua_gettable"><code>lua_gettable</code></a>, but does a raw access 4427 1.1 mbalmer (i.e., without metamethods). 4428 1.1 mbalmer 4429 1.1 mbalmer 4430 1.1 mbalmer 4431 1.1 mbalmer 4432 1.1 mbalmer 4433 1.2 lneto <hr><h3><a name="lua_rawgeti"><code>lua_rawgeti</code></a></h3><p> 4434 1.2 lneto <span class="apii">[-0, +1, –]</span> 4435 1.2 lneto <pre>int lua_rawgeti (lua_State *L, int index, lua_Integer n);</pre> 4436 1.2 lneto 4437 1.2 lneto <p> 4438 1.2 lneto Pushes onto the stack the value <code>t[n]</code>, 4439 1.2 lneto where <code>t</code> is the table at the given index. 4440 1.2 lneto The access is raw; 4441 1.2 lneto that is, it does not invoke metamethods. 4442 1.2 lneto 4443 1.2 lneto 4444 1.2 lneto <p> 4445 1.2 lneto Returns the type of the pushed value. 4446 1.2 lneto 4447 1.2 lneto 4448 1.2 lneto 4449 1.2 lneto 4450 1.2 lneto 4451 1.2 lneto <hr><h3><a name="lua_rawgetp"><code>lua_rawgetp</code></a></h3><p> 4452 1.2 lneto <span class="apii">[-0, +1, –]</span> 4453 1.2 lneto <pre>int lua_rawgetp (lua_State *L, int index, const void *p);</pre> 4454 1.2 lneto 4455 1.2 lneto <p> 4456 1.2 lneto Pushes onto the stack the value <code>t[k]</code>, 4457 1.2 lneto where <code>t</code> is the table at the given index and 4458 1.2 lneto <code>k</code> is the pointer <code>p</code> represented as a light userdata. 4459 1.2 lneto The access is raw; 4460 1.2 lneto that is, it does not invoke metamethods. 4461 1.2 lneto 4462 1.2 lneto 4463 1.2 lneto <p> 4464 1.2 lneto Returns the type of the pushed value. 4465 1.2 lneto 4466 1.2 lneto 4467 1.2 lneto 4468 1.2 lneto 4469 1.2 lneto 4470 1.2 lneto <hr><h3><a name="lua_rawlen"><code>lua_rawlen</code></a></h3><p> 4471 1.2 lneto <span class="apii">[-0, +0, –]</span> 4472 1.2 lneto <pre>size_t lua_rawlen (lua_State *L, int index);</pre> 4473 1.2 lneto 4474 1.2 lneto <p> 4475 1.2 lneto Returns the raw "length" of the value at the given index: 4476 1.2 lneto for strings, this is the string length; 4477 1.2 lneto for tables, this is the result of the length operator ('<code>#</code>') 4478 1.2 lneto with no metamethods; 4479 1.2 lneto for userdata, this is the size of the block of memory allocated 4480 1.2 lneto for the userdata; 4481 1.2 lneto for other values, it is 0. 4482 1.1 mbalmer 4483 1.1 mbalmer 4484 1.1 mbalmer 4485 1.1 mbalmer 4486 1.1 mbalmer 4487 1.1 mbalmer <hr><h3><a name="lua_rawset"><code>lua_rawset</code></a></h3><p> 4488 1.2 lneto <span class="apii">[-2, +0, <em>e</em>]</span> 4489 1.1 mbalmer <pre>void lua_rawset (lua_State *L, int index);</pre> 4490 1.1 mbalmer 4491 1.1 mbalmer <p> 4492 1.1 mbalmer Similar to <a href="#lua_settable"><code>lua_settable</code></a>, but does a raw assignment 4493 1.1 mbalmer (i.e., without metamethods). 4494 1.1 mbalmer 4495 1.1 mbalmer 4496 1.1 mbalmer 4497 1.1 mbalmer 4498 1.1 mbalmer 4499 1.1 mbalmer <hr><h3><a name="lua_rawseti"><code>lua_rawseti</code></a></h3><p> 4500 1.2 lneto <span class="apii">[-1, +0, <em>e</em>]</span> 4501 1.2 lneto <pre>void lua_rawseti (lua_State *L, int index, lua_Integer n);</pre> 4502 1.1 mbalmer 4503 1.1 mbalmer <p> 4504 1.1 mbalmer Does the equivalent of <code>t[n] = v</code>, 4505 1.2 lneto where <code>t</code> is the table at the given index 4506 1.2 lneto and <code>v</code> is the value at the top of the stack. 4507 1.2 lneto 4508 1.2 lneto 4509 1.2 lneto <p> 4510 1.2 lneto This function pops the value from the stack. 4511 1.2 lneto The assignment is raw; 4512 1.2 lneto that is, it does not invoke metamethods. 4513 1.2 lneto 4514 1.2 lneto 4515 1.2 lneto 4516 1.2 lneto 4517 1.2 lneto 4518 1.2 lneto <hr><h3><a name="lua_rawsetp"><code>lua_rawsetp</code></a></h3><p> 4519 1.2 lneto <span class="apii">[-1, +0, <em>e</em>]</span> 4520 1.2 lneto <pre>void lua_rawsetp (lua_State *L, int index, const void *p);</pre> 4521 1.2 lneto 4522 1.2 lneto <p> 4523 1.2 lneto Does the equivalent of <code>t[k] = v</code>, 4524 1.2 lneto where <code>t</code> is the table at the given index, 4525 1.2 lneto <code>k</code> is the pointer <code>p</code> represented as a light userdata, 4526 1.1 mbalmer and <code>v</code> is the value at the top of the stack. 4527 1.1 mbalmer 4528 1.1 mbalmer 4529 1.1 mbalmer <p> 4530 1.1 mbalmer This function pops the value from the stack. 4531 1.1 mbalmer The assignment is raw; 4532 1.1 mbalmer that is, it does not invoke metamethods. 4533 1.1 mbalmer 4534 1.1 mbalmer 4535 1.1 mbalmer 4536 1.1 mbalmer 4537 1.1 mbalmer 4538 1.1 mbalmer <hr><h3><a name="lua_Reader"><code>lua_Reader</code></a></h3> 4539 1.1 mbalmer <pre>typedef const char * (*lua_Reader) (lua_State *L, 4540 1.1 mbalmer void *data, 4541 1.1 mbalmer size_t *size);</pre> 4542 1.1 mbalmer 4543 1.1 mbalmer <p> 4544 1.1 mbalmer The reader function used by <a href="#lua_load"><code>lua_load</code></a>. 4545 1.1 mbalmer Every time it needs another piece of the chunk, 4546 1.1 mbalmer <a href="#lua_load"><code>lua_load</code></a> calls the reader, 4547 1.1 mbalmer passing along its <code>data</code> parameter. 4548 1.1 mbalmer The reader must return a pointer to a block of memory 4549 1.1 mbalmer with a new piece of the chunk 4550 1.1 mbalmer and set <code>size</code> to the block size. 4551 1.1 mbalmer The block must exist until the reader function is called again. 4552 1.1 mbalmer To signal the end of the chunk, 4553 1.1 mbalmer the reader must return <code>NULL</code> or set <code>size</code> to zero. 4554 1.1 mbalmer The reader function may return pieces of any size greater than zero. 4555 1.1 mbalmer 4556 1.1 mbalmer 4557 1.1 mbalmer 4558 1.1 mbalmer 4559 1.1 mbalmer 4560 1.1 mbalmer <hr><h3><a name="lua_register"><code>lua_register</code></a></h3><p> 4561 1.1 mbalmer <span class="apii">[-0, +0, <em>e</em>]</span> 4562 1.2 lneto <pre>void lua_register (lua_State *L, const char *name, lua_CFunction f);</pre> 4563 1.1 mbalmer 4564 1.1 mbalmer <p> 4565 1.1 mbalmer Sets the C function <code>f</code> as the new value of global <code>name</code>. 4566 1.1 mbalmer It is defined as a macro: 4567 1.1 mbalmer 4568 1.1 mbalmer <pre> 4569 1.1 mbalmer #define lua_register(L,n,f) \ 4570 1.1 mbalmer (lua_pushcfunction(L, f), lua_setglobal(L, n)) 4571 1.1 mbalmer </pre> 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_remove"><code>lua_remove</code></a></h3><p> 4577 1.2 lneto <span class="apii">[-1, +0, –]</span> 4578 1.1 mbalmer <pre>void lua_remove (lua_State *L, int index);</pre> 4579 1.1 mbalmer 4580 1.1 mbalmer <p> 4581 1.1 mbalmer Removes the element at the given valid index, 4582 1.1 mbalmer shifting down the elements above this index to fill the gap. 4583 1.2 lneto This function cannot be called with a pseudo-index, 4584 1.1 mbalmer because a pseudo-index is not an actual stack position. 4585 1.1 mbalmer 4586 1.1 mbalmer 4587 1.1 mbalmer 4588 1.1 mbalmer 4589 1.1 mbalmer 4590 1.1 mbalmer <hr><h3><a name="lua_replace"><code>lua_replace</code></a></h3><p> 4591 1.2 lneto <span class="apii">[-1, +0, –]</span> 4592 1.1 mbalmer <pre>void lua_replace (lua_State *L, int index);</pre> 4593 1.1 mbalmer 4594 1.1 mbalmer <p> 4595 1.2 lneto Moves the top element into the given valid index 4596 1.1 mbalmer without shifting any element 4597 1.2 lneto (therefore replacing the value at the given index), 4598 1.2 lneto and then pops the top element. 4599 1.1 mbalmer 4600 1.1 mbalmer 4601 1.1 mbalmer 4602 1.1 mbalmer 4603 1.1 mbalmer 4604 1.1 mbalmer <hr><h3><a name="lua_resume"><code>lua_resume</code></a></h3><p> 4605 1.2 lneto <span class="apii">[-?, +?, –]</span> 4606 1.2 lneto <pre>int lua_resume (lua_State *L, lua_State *from, int nargs);</pre> 4607 1.1 mbalmer 4608 1.1 mbalmer <p> 4609 1.1 mbalmer Starts and resumes a coroutine in a given thread. 4610 1.1 mbalmer 4611 1.1 mbalmer 4612 1.1 mbalmer <p> 4613 1.2 lneto To start a coroutine, 4614 1.2 lneto you push onto the thread stack the main function plus any arguments; 4615 1.1 mbalmer then you call <a href="#lua_resume"><code>lua_resume</code></a>, 4616 1.2 lneto with <code>nargs</code> being the number of arguments. 4617 1.1 mbalmer This call returns when the coroutine suspends or finishes its execution. 4618 1.1 mbalmer When it returns, the stack contains all values passed to <a href="#lua_yield"><code>lua_yield</code></a>, 4619 1.1 mbalmer or all values returned by the body function. 4620 1.1 mbalmer <a href="#lua_resume"><code>lua_resume</code></a> returns 4621 1.1 mbalmer <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the coroutine yields, 4622 1.2 lneto <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> if the coroutine finishes its execution 4623 1.1 mbalmer without errors, 4624 1.1 mbalmer or an error code in case of errors (see <a href="#lua_pcall"><code>lua_pcall</code></a>). 4625 1.2 lneto 4626 1.2 lneto 4627 1.2 lneto <p> 4628 1.1 mbalmer In case of errors, 4629 1.1 mbalmer the stack is not unwound, 4630 1.1 mbalmer so you can use the debug API over it. 4631 1.1 mbalmer The error message is on the top of the stack. 4632 1.2 lneto 4633 1.2 lneto 4634 1.2 lneto <p> 4635 1.2 lneto To resume a coroutine, 4636 1.2 lneto you remove any results from the last <a href="#lua_yield"><code>lua_yield</code></a>, 4637 1.2 lneto put on its stack only the values to 4638 1.1 mbalmer be passed as results from <code>yield</code>, 4639 1.1 mbalmer and then call <a href="#lua_resume"><code>lua_resume</code></a>. 4640 1.1 mbalmer 4641 1.1 mbalmer 4642 1.2 lneto <p> 4643 1.2 lneto The parameter <code>from</code> represents the coroutine that is resuming <code>L</code>. 4644 1.2 lneto If there is no such coroutine, 4645 1.2 lneto this parameter can be <code>NULL</code>. 4646 1.2 lneto 4647 1.2 lneto 4648 1.1 mbalmer 4649 1.1 mbalmer 4650 1.1 mbalmer 4651 1.2 lneto <hr><h3><a name="lua_rotate"><code>lua_rotate</code></a></h3><p> 4652 1.2 lneto <span class="apii">[-0, +0, –]</span> 4653 1.2 lneto <pre>void lua_rotate (lua_State *L, int idx, int n);</pre> 4654 1.1 mbalmer 4655 1.1 mbalmer <p> 4656 1.2 lneto Rotates the stack elements from <code>idx</code> to the top <code>n</code> positions 4657 1.2 lneto in the direction of the top, for a positive <code>n</code>, 4658 1.2 lneto or <code>-n</code> positions in the direction of the bottom, 4659 1.2 lneto for a negative <code>n</code>. 4660 1.2 lneto The absolute value of <code>n</code> must not be greater than the size 4661 1.2 lneto of the slice being rotated. 4662 1.1 mbalmer 4663 1.1 mbalmer 4664 1.1 mbalmer 4665 1.1 mbalmer 4666 1.1 mbalmer 4667 1.2 lneto <hr><h3><a name="lua_setallocf"><code>lua_setallocf</code></a></h3><p> 4668 1.2 lneto <span class="apii">[-0, +0, –]</span> 4669 1.2 lneto <pre>void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);</pre> 4670 1.1 mbalmer 4671 1.1 mbalmer <p> 4672 1.2 lneto Changes the allocator function of a given state to <code>f</code> 4673 1.2 lneto with user data <code>ud</code>. 4674 1.1 mbalmer 4675 1.1 mbalmer 4676 1.1 mbalmer 4677 1.1 mbalmer 4678 1.1 mbalmer 4679 1.1 mbalmer <hr><h3><a name="lua_setfield"><code>lua_setfield</code></a></h3><p> 4680 1.1 mbalmer <span class="apii">[-1, +0, <em>e</em>]</span> 4681 1.1 mbalmer <pre>void lua_setfield (lua_State *L, int index, const char *k);</pre> 4682 1.1 mbalmer 4683 1.1 mbalmer <p> 4684 1.1 mbalmer Does the equivalent to <code>t[k] = v</code>, 4685 1.2 lneto where <code>t</code> is the value at the given index 4686 1.1 mbalmer and <code>v</code> is the value at the top of the stack. 4687 1.1 mbalmer 4688 1.1 mbalmer 4689 1.1 mbalmer <p> 4690 1.1 mbalmer This function pops the value from the stack. 4691 1.1 mbalmer As in Lua, this function may trigger a metamethod 4692 1.2 lneto for the "newindex" event (see <a href="#2.4">§2.4</a>). 4693 1.1 mbalmer 4694 1.1 mbalmer 4695 1.1 mbalmer 4696 1.1 mbalmer 4697 1.1 mbalmer 4698 1.1 mbalmer <hr><h3><a name="lua_setglobal"><code>lua_setglobal</code></a></h3><p> 4699 1.1 mbalmer <span class="apii">[-1, +0, <em>e</em>]</span> 4700 1.1 mbalmer <pre>void lua_setglobal (lua_State *L, const char *name);</pre> 4701 1.1 mbalmer 4702 1.1 mbalmer <p> 4703 1.1 mbalmer Pops a value from the stack and 4704 1.1 mbalmer sets it as the new value of global <code>name</code>. 4705 1.1 mbalmer 4706 1.1 mbalmer 4707 1.1 mbalmer 4708 1.1 mbalmer 4709 1.1 mbalmer 4710 1.1 mbalmer <hr><h3><a name="lua_setmetatable"><code>lua_setmetatable</code></a></h3><p> 4711 1.2 lneto <span class="apii">[-1, +0, –]</span> 4712 1.2 lneto <pre>void lua_setmetatable (lua_State *L, int index);</pre> 4713 1.1 mbalmer 4714 1.1 mbalmer <p> 4715 1.1 mbalmer Pops a table from the stack and 4716 1.2 lneto sets it as the new metatable for the value at the given index. 4717 1.1 mbalmer 4718 1.1 mbalmer 4719 1.1 mbalmer 4720 1.1 mbalmer 4721 1.1 mbalmer 4722 1.1 mbalmer <hr><h3><a name="lua_settable"><code>lua_settable</code></a></h3><p> 4723 1.1 mbalmer <span class="apii">[-2, +0, <em>e</em>]</span> 4724 1.1 mbalmer <pre>void lua_settable (lua_State *L, int index);</pre> 4725 1.1 mbalmer 4726 1.1 mbalmer <p> 4727 1.1 mbalmer Does the equivalent to <code>t[k] = v</code>, 4728 1.2 lneto where <code>t</code> is the value at the given index, 4729 1.1 mbalmer <code>v</code> is the value at the top of the stack, 4730 1.1 mbalmer and <code>k</code> is the value just below the top. 4731 1.1 mbalmer 4732 1.1 mbalmer 4733 1.1 mbalmer <p> 4734 1.1 mbalmer This function pops both the key and the value from the stack. 4735 1.1 mbalmer As in Lua, this function may trigger a metamethod 4736 1.2 lneto for the "newindex" event (see <a href="#2.4">§2.4</a>). 4737 1.1 mbalmer 4738 1.1 mbalmer 4739 1.1 mbalmer 4740 1.1 mbalmer 4741 1.1 mbalmer 4742 1.1 mbalmer <hr><h3><a name="lua_settop"><code>lua_settop</code></a></h3><p> 4743 1.2 lneto <span class="apii">[-?, +?, –]</span> 4744 1.1 mbalmer <pre>void lua_settop (lua_State *L, int index);</pre> 4745 1.1 mbalmer 4746 1.1 mbalmer <p> 4747 1.2 lneto Accepts any index, or 0, 4748 1.1 mbalmer and sets the stack top to this index. 4749 1.1 mbalmer If the new top is larger than the old one, 4750 1.1 mbalmer then the new elements are filled with <b>nil</b>. 4751 1.1 mbalmer If <code>index</code> is 0, then all stack elements are removed. 4752 1.1 mbalmer 4753 1.1 mbalmer 4754 1.1 mbalmer 4755 1.1 mbalmer 4756 1.1 mbalmer 4757 1.2 lneto <hr><h3><a name="lua_setuservalue"><code>lua_setuservalue</code></a></h3><p> 4758 1.2 lneto <span class="apii">[-1, +0, –]</span> 4759 1.2 lneto <pre>void lua_setuservalue (lua_State *L, int index);</pre> 4760 1.2 lneto 4761 1.2 lneto <p> 4762 1.2 lneto Pops a value from the stack and sets it as 4763 1.2 lneto the new value associated to the userdata at the given index. 4764 1.2 lneto 4765 1.2 lneto 4766 1.2 lneto 4767 1.2 lneto 4768 1.2 lneto 4769 1.1 mbalmer <hr><h3><a name="lua_State"><code>lua_State</code></a></h3> 4770 1.1 mbalmer <pre>typedef struct lua_State lua_State;</pre> 4771 1.1 mbalmer 4772 1.1 mbalmer <p> 4773 1.2 lneto An opaque structure that points to a thread and indirectly 4774 1.2 lneto (through the thread) to the whole state of a Lua interpreter. 4775 1.1 mbalmer The Lua library is fully reentrant: 4776 1.1 mbalmer it has no global variables. 4777 1.2 lneto All information about a state is accessible through this structure. 4778 1.1 mbalmer 4779 1.1 mbalmer 4780 1.1 mbalmer <p> 4781 1.2 lneto A pointer to this structure must be passed as the first argument to 4782 1.1 mbalmer every function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>, 4783 1.1 mbalmer which creates a Lua state from scratch. 4784 1.1 mbalmer 4785 1.1 mbalmer 4786 1.1 mbalmer 4787 1.1 mbalmer 4788 1.1 mbalmer 4789 1.1 mbalmer <hr><h3><a name="lua_status"><code>lua_status</code></a></h3><p> 4790 1.2 lneto <span class="apii">[-0, +0, –]</span> 4791 1.1 mbalmer <pre>int lua_status (lua_State *L);</pre> 4792 1.1 mbalmer 4793 1.1 mbalmer <p> 4794 1.1 mbalmer Returns the status of the thread <code>L</code>. 4795 1.1 mbalmer 4796 1.1 mbalmer 4797 1.1 mbalmer <p> 4798 1.2 lneto The status can be 0 (<a href="#pdf-LUA_OK"><code>LUA_OK</code></a>) for a normal thread, 4799 1.2 lneto an error code if the thread finished the execution 4800 1.2 lneto of a <a href="#lua_resume"><code>lua_resume</code></a> with an error, 4801 1.1 mbalmer or <a name="pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the thread is suspended. 4802 1.1 mbalmer 4803 1.1 mbalmer 4804 1.2 lneto <p> 4805 1.2 lneto You can only call functions in threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>. 4806 1.2 lneto You can resume threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> 4807 1.2 lneto (to start a new coroutine) or <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> 4808 1.2 lneto (to resume a coroutine). 4809 1.2 lneto 4810 1.2 lneto 4811 1.2 lneto 4812 1.2 lneto 4813 1.2 lneto 4814 1.2 lneto <hr><h3><a name="lua_strtonum"><code>lua_strtonum</code></a></h3><p> 4815 1.2 lneto <span class="apii">[-0, +1, –]</span> 4816 1.2 lneto <pre>size_t lua_strtonum (lua_State *L, const char *s);</pre> 4817 1.2 lneto 4818 1.2 lneto <p> 4819 1.2 lneto Converts the zero-terminated string <code>s</code> to a number, 4820 1.2 lneto pushes that number into the stack, 4821 1.2 lneto and returns the total size of the string 4822 1.2 lneto (that is, its length plus one). 4823 1.2 lneto The conversion can result in an integer or a float, 4824 1.2 lneto according to the lexical conventions of Lua (see <a href="#3.1">§3.1</a>). 4825 1.2 lneto The string may have leading and trailing spaces and a sign. 4826 1.2 lneto If the string is not a valid numeral, 4827 1.2 lneto returns 0 and pushes nothing. 4828 1.2 lneto 4829 1.2 lneto 4830 1.1 mbalmer 4831 1.1 mbalmer 4832 1.1 mbalmer 4833 1.1 mbalmer <hr><h3><a name="lua_toboolean"><code>lua_toboolean</code></a></h3><p> 4834 1.2 lneto <span class="apii">[-0, +0, –]</span> 4835 1.1 mbalmer <pre>int lua_toboolean (lua_State *L, int index);</pre> 4836 1.1 mbalmer 4837 1.1 mbalmer <p> 4838 1.2 lneto Converts the Lua value at the given index to a C boolean 4839 1.1 mbalmer value (0 or 1). 4840 1.1 mbalmer Like all tests in Lua, 4841 1.2 lneto <a href="#lua_toboolean"><code>lua_toboolean</code></a> returns true for any Lua value 4842 1.1 mbalmer different from <b>false</b> and <b>nil</b>; 4843 1.2 lneto otherwise it returns false. 4844 1.1 mbalmer (If you want to accept only actual boolean values, 4845 1.1 mbalmer use <a href="#lua_isboolean"><code>lua_isboolean</code></a> to test the value's type.) 4846 1.1 mbalmer 4847 1.1 mbalmer 4848 1.1 mbalmer 4849 1.1 mbalmer 4850 1.1 mbalmer 4851 1.1 mbalmer <hr><h3><a name="lua_tocfunction"><code>lua_tocfunction</code></a></h3><p> 4852 1.2 lneto <span class="apii">[-0, +0, –]</span> 4853 1.1 mbalmer <pre>lua_CFunction lua_tocfunction (lua_State *L, int index);</pre> 4854 1.1 mbalmer 4855 1.1 mbalmer <p> 4856 1.2 lneto Converts a value at the given index to a C function. 4857 1.1 mbalmer That value must be a C function; 4858 1.1 mbalmer otherwise, returns <code>NULL</code>. 4859 1.1 mbalmer 4860 1.1 mbalmer 4861 1.1 mbalmer 4862 1.1 mbalmer 4863 1.1 mbalmer 4864 1.1 mbalmer <hr><h3><a name="lua_tointeger"><code>lua_tointeger</code></a></h3><p> 4865 1.2 lneto <span class="apii">[-0, +0, –]</span> 4866 1.1 mbalmer <pre>lua_Integer lua_tointeger (lua_State *L, int index);</pre> 4867 1.1 mbalmer 4868 1.1 mbalmer <p> 4869 1.2 lneto Equivalent to <a href="#lua_tointegerx"><code>lua_tointegerx</code></a> with <code>isnum</code> equal to <code>NULL</code>. 4870 1.2 lneto 4871 1.2 lneto 4872 1.2 lneto 4873 1.2 lneto 4874 1.2 lneto 4875 1.2 lneto <hr><h3><a name="lua_tointegerx"><code>lua_tointegerx</code></a></h3><p> 4876 1.2 lneto <span class="apii">[-0, +0, –]</span> 4877 1.2 lneto <pre>lua_Integer lua_tointegerx (lua_State *L, int index, int *isnum);</pre> 4878 1.2 lneto 4879 1.2 lneto <p> 4880 1.2 lneto Converts the Lua value at the given index 4881 1.1 mbalmer to the signed integral type <a href="#lua_Integer"><code>lua_Integer</code></a>. 4882 1.2 lneto The Lua value must be an integer, 4883 1.2 lneto or a number or string convertible to an integer (see <a href="#3.4.3">§3.4.3</a>); 4884 1.2 lneto otherwise, <code>lua_tointegerx</code> returns 0. 4885 1.1 mbalmer 4886 1.1 mbalmer 4887 1.1 mbalmer <p> 4888 1.2 lneto If <code>isnum</code> is not <code>NULL</code>, 4889 1.2 lneto its referent is assigned a boolean value that 4890 1.2 lneto indicates whether the operation succeeded. 4891 1.1 mbalmer 4892 1.1 mbalmer 4893 1.1 mbalmer 4894 1.1 mbalmer 4895 1.1 mbalmer 4896 1.1 mbalmer <hr><h3><a name="lua_tolstring"><code>lua_tolstring</code></a></h3><p> 4897 1.2 lneto <span class="apii">[-0, +0, <em>e</em>]</span> 4898 1.1 mbalmer <pre>const char *lua_tolstring (lua_State *L, int index, size_t *len);</pre> 4899 1.1 mbalmer 4900 1.1 mbalmer <p> 4901 1.2 lneto Converts the Lua value at the given index to a C string. 4902 1.1 mbalmer If <code>len</code> is not <code>NULL</code>, 4903 1.1 mbalmer it also sets <code>*len</code> with the string length. 4904 1.1 mbalmer The Lua value must be a string or a number; 4905 1.1 mbalmer otherwise, the function returns <code>NULL</code>. 4906 1.1 mbalmer If the value is a number, 4907 1.2 lneto then <code>lua_tolstring</code> also 4908 1.1 mbalmer <em>changes the actual value in the stack to a string</em>. 4909 1.1 mbalmer (This change confuses <a href="#lua_next"><code>lua_next</code></a> 4910 1.2 lneto when <code>lua_tolstring</code> is applied to keys during a table traversal.) 4911 1.1 mbalmer 4912 1.1 mbalmer 4913 1.1 mbalmer <p> 4914 1.2 lneto <code>lua_tolstring</code> returns a fully aligned pointer 4915 1.1 mbalmer to a string inside the Lua state. 4916 1.1 mbalmer This string always has a zero ('<code>\0</code>') 4917 1.1 mbalmer after its last character (as in C), 4918 1.1 mbalmer but can contain other zeros in its body. 4919 1.1 mbalmer Because Lua has garbage collection, 4920 1.2 lneto there is no guarantee that the pointer returned by <code>lua_tolstring</code> 4921 1.1 mbalmer will be valid after the corresponding value is removed from the stack. 4922 1.1 mbalmer 4923 1.1 mbalmer 4924 1.1 mbalmer 4925 1.1 mbalmer 4926 1.1 mbalmer 4927 1.1 mbalmer <hr><h3><a name="lua_tonumber"><code>lua_tonumber</code></a></h3><p> 4928 1.2 lneto <span class="apii">[-0, +0, –]</span> 4929 1.1 mbalmer <pre>lua_Number lua_tonumber (lua_State *L, int index);</pre> 4930 1.1 mbalmer 4931 1.1 mbalmer <p> 4932 1.2 lneto Equivalent to <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> with <code>isnum</code> equal to <code>NULL</code>. 4933 1.2 lneto 4934 1.2 lneto 4935 1.2 lneto 4936 1.2 lneto 4937 1.2 lneto 4938 1.2 lneto <hr><h3><a name="lua_tonumberx"><code>lua_tonumberx</code></a></h3><p> 4939 1.2 lneto <span class="apii">[-0, +0, –]</span> 4940 1.2 lneto <pre>lua_Number lua_tonumberx (lua_State *L, int index, int *isnum);</pre> 4941 1.2 lneto 4942 1.2 lneto <p> 4943 1.2 lneto Converts the Lua value at the given index 4944 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>). 4945 1.1 mbalmer The Lua value must be a number or a string convertible to a number 4946 1.2 lneto (see <a href="#3.4.3">§3.4.3</a>); 4947 1.2 lneto otherwise, <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> returns 0. 4948 1.2 lneto 4949 1.2 lneto 4950 1.2 lneto <p> 4951 1.2 lneto If <code>isnum</code> is not <code>NULL</code>, 4952 1.2 lneto its referent is assigned a boolean value that 4953 1.2 lneto indicates whether the operation succeeded. 4954 1.1 mbalmer 4955 1.1 mbalmer 4956 1.1 mbalmer 4957 1.1 mbalmer 4958 1.1 mbalmer 4959 1.1 mbalmer <hr><h3><a name="lua_topointer"><code>lua_topointer</code></a></h3><p> 4960 1.2 lneto <span class="apii">[-0, +0, –]</span> 4961 1.1 mbalmer <pre>const void *lua_topointer (lua_State *L, int index);</pre> 4962 1.1 mbalmer 4963 1.1 mbalmer <p> 4964 1.2 lneto Converts the value at the given index to a generic 4965 1.1 mbalmer C pointer (<code>void*</code>). 4966 1.1 mbalmer The value can be a userdata, a table, a thread, or a function; 4967 1.2 lneto otherwise, <code>lua_topointer</code> returns <code>NULL</code>. 4968 1.1 mbalmer Different objects will give different pointers. 4969 1.1 mbalmer There is no way to convert the pointer back to its original value. 4970 1.1 mbalmer 4971 1.1 mbalmer 4972 1.1 mbalmer <p> 4973 1.1 mbalmer Typically this function is used only for debug information. 4974 1.1 mbalmer 4975 1.1 mbalmer 4976 1.1 mbalmer 4977 1.1 mbalmer 4978 1.1 mbalmer 4979 1.1 mbalmer <hr><h3><a name="lua_tostring"><code>lua_tostring</code></a></h3><p> 4980 1.2 lneto <span class="apii">[-0, +0, <em>e</em>]</span> 4981 1.1 mbalmer <pre>const char *lua_tostring (lua_State *L, int index);</pre> 4982 1.1 mbalmer 4983 1.1 mbalmer <p> 4984 1.1 mbalmer Equivalent to <a href="#lua_tolstring"><code>lua_tolstring</code></a> with <code>len</code> equal to <code>NULL</code>. 4985 1.1 mbalmer 4986 1.1 mbalmer 4987 1.1 mbalmer 4988 1.1 mbalmer 4989 1.1 mbalmer 4990 1.1 mbalmer <hr><h3><a name="lua_tothread"><code>lua_tothread</code></a></h3><p> 4991 1.2 lneto <span class="apii">[-0, +0, –]</span> 4992 1.1 mbalmer <pre>lua_State *lua_tothread (lua_State *L, int index);</pre> 4993 1.1 mbalmer 4994 1.1 mbalmer <p> 4995 1.2 lneto Converts the value at the given index to a Lua thread 4996 1.1 mbalmer (represented as <code>lua_State*</code>). 4997 1.1 mbalmer This value must be a thread; 4998 1.1 mbalmer otherwise, the function returns <code>NULL</code>. 4999 1.1 mbalmer 5000 1.1 mbalmer 5001 1.1 mbalmer 5002 1.1 mbalmer 5003 1.1 mbalmer 5004 1.2 lneto <hr><h3><a name="lua_tounsigned"><code>lua_tounsigned</code></a></h3><p> 5005 1.2 lneto <span class="apii">[-0, +0, –]</span> 5006 1.2 lneto <pre>lua_Unsigned lua_tounsigned (lua_State *L, int index);</pre> 5007 1.2 lneto 5008 1.2 lneto <p> 5009 1.2 lneto Equivalent to <a href="#lua_tounsignedx"><code>lua_tounsignedx</code></a> with <code>isnum</code> equal to <code>NULL</code>. 5010 1.2 lneto 5011 1.2 lneto 5012 1.2 lneto 5013 1.2 lneto 5014 1.2 lneto 5015 1.2 lneto <hr><h3><a name="lua_tounsignedx"><code>lua_tounsignedx</code></a></h3><p> 5016 1.2 lneto <span class="apii">[-0, +0, –]</span> 5017 1.2 lneto <pre>lua_Unsigned lua_tounsignedx (lua_State *L, int index, int *isnum);</pre> 5018 1.2 lneto 5019 1.2 lneto <p> 5020 1.2 lneto Converts the Lua value at the given index 5021 1.2 lneto to the unsigned integral type <a href="#lua_Unsigned"><code>lua_Unsigned</code></a>. 5022 1.2 lneto The Lua value must be an integer, 5023 1.2 lneto or a float, 5024 1.2 lneto or a string convertible to a number 5025 1.2 lneto (see <a href="#3.4.3">§3.4.3</a>); 5026 1.2 lneto otherwise, <code>lua_tounsignedx</code> returns 0. 5027 1.2 lneto 5028 1.2 lneto 5029 1.2 lneto <p> 5030 1.2 lneto If the number is not an integer, 5031 1.2 lneto it is rounded towards minus infinite (floor). 5032 1.2 lneto If the result is outside the range of representable values, 5033 1.2 lneto it is normalized to the module of its division by 5034 1.2 lneto one more than the maximum representable value. 5035 1.2 lneto 5036 1.2 lneto 5037 1.2 lneto <p> 5038 1.2 lneto If <code>isnum</code> is not <code>NULL</code>, 5039 1.2 lneto its referent is assigned a boolean value that 5040 1.2 lneto indicates whether the operation succeeded. 5041 1.2 lneto 5042 1.2 lneto 5043 1.2 lneto 5044 1.2 lneto 5045 1.2 lneto 5046 1.1 mbalmer <hr><h3><a name="lua_touserdata"><code>lua_touserdata</code></a></h3><p> 5047 1.2 lneto <span class="apii">[-0, +0, –]</span> 5048 1.1 mbalmer <pre>void *lua_touserdata (lua_State *L, int index);</pre> 5049 1.1 mbalmer 5050 1.1 mbalmer <p> 5051 1.2 lneto If the value at the given index is a full userdata, 5052 1.1 mbalmer returns its block address. 5053 1.1 mbalmer If the value is a light userdata, 5054 1.1 mbalmer returns its pointer. 5055 1.1 mbalmer Otherwise, returns <code>NULL</code>. 5056 1.1 mbalmer 5057 1.1 mbalmer 5058 1.1 mbalmer 5059 1.1 mbalmer 5060 1.1 mbalmer 5061 1.1 mbalmer <hr><h3><a name="lua_type"><code>lua_type</code></a></h3><p> 5062 1.2 lneto <span class="apii">[-0, +0, –]</span> 5063 1.1 mbalmer <pre>int lua_type (lua_State *L, int index);</pre> 5064 1.1 mbalmer 5065 1.1 mbalmer <p> 5066 1.2 lneto Returns the type of the value in the given valid index, 5067 1.2 lneto or <code>LUA_TNONE</code> for a non-valid (but acceptable) index. 5068 1.1 mbalmer The types returned by <a href="#lua_type"><code>lua_type</code></a> are coded by the following constants 5069 1.1 mbalmer defined in <code>lua.h</code>: 5070 1.2 lneto <a name="pdf-LUA_TNIL"><code>LUA_TNIL</code></a>, 5071 1.2 lneto <a name="pdf-LUA_TNUMBER"><code>LUA_TNUMBER</code></a>, 5072 1.2 lneto <a name="pdf-LUA_TBOOLEAN"><code>LUA_TBOOLEAN</code></a>, 5073 1.2 lneto <a name="pdf-LUA_TSTRING"><code>LUA_TSTRING</code></a>, 5074 1.2 lneto <a name="pdf-LUA_TTABLE"><code>LUA_TTABLE</code></a>, 5075 1.2 lneto <a name="pdf-LUA_TFUNCTION"><code>LUA_TFUNCTION</code></a>, 5076 1.2 lneto <a name="pdf-LUA_TUSERDATA"><code>LUA_TUSERDATA</code></a>, 5077 1.2 lneto <a name="pdf-LUA_TTHREAD"><code>LUA_TTHREAD</code></a>, 5078 1.1 mbalmer and 5079 1.2 lneto <a name="pdf-LUA_TLIGHTUSERDATA"><code>LUA_TLIGHTUSERDATA</code></a>. 5080 1.1 mbalmer 5081 1.1 mbalmer 5082 1.1 mbalmer 5083 1.1 mbalmer 5084 1.1 mbalmer 5085 1.1 mbalmer <hr><h3><a name="lua_typename"><code>lua_typename</code></a></h3><p> 5086 1.2 lneto <span class="apii">[-0, +0, –]</span> 5087 1.2 lneto <pre>const char *lua_typename (lua_State *L, int tp);</pre> 5088 1.1 mbalmer 5089 1.1 mbalmer <p> 5090 1.1 mbalmer Returns the name of the type encoded by the value <code>tp</code>, 5091 1.1 mbalmer which must be one the values returned by <a href="#lua_type"><code>lua_type</code></a>. 5092 1.1 mbalmer 5093 1.1 mbalmer 5094 1.1 mbalmer 5095 1.1 mbalmer 5096 1.1 mbalmer 5097 1.2 lneto <hr><h3><a name="lua_Unsigned"><code>lua_Unsigned</code></a></h3> 5098 1.2 lneto <pre>typedef ... lua_Unsigned;</pre> 5099 1.2 lneto 5100 1.2 lneto <p> 5101 1.2 lneto The unsigned version of <a href="#lua_Integer"><code>lua_Integer</code></a>. 5102 1.2 lneto 5103 1.2 lneto 5104 1.2 lneto <p> 5105 1.2 lneto Lua also defines the constant <a name="pdf-LUA_MAXUNSIGNED"><code>LUA_MAXUNSIGNED</code></a>, 5106 1.2 lneto with the maximum value that fits in this type. 5107 1.2 lneto 5108 1.2 lneto 5109 1.2 lneto 5110 1.2 lneto 5111 1.2 lneto 5112 1.2 lneto <hr><h3><a name="lua_upvalueindex"><code>lua_upvalueindex</code></a></h3><p> 5113 1.2 lneto <span class="apii">[-0, +0, –]</span> 5114 1.2 lneto <pre>int lua_upvalueindex (int i);</pre> 5115 1.2 lneto 5116 1.2 lneto <p> 5117 1.2 lneto Returns the pseudo-index that represents the <code>i</code>-th upvalue of 5118 1.2 lneto the running function (see <a href="#4.4">§4.4</a>). 5119 1.2 lneto 5120 1.2 lneto 5121 1.2 lneto 5122 1.2 lneto 5123 1.2 lneto 5124 1.2 lneto <hr><h3><a name="lua_version"><code>lua_version</code></a></h3><p> 5125 1.2 lneto <span class="apii">[-0, +0, <em>v</em>]</span> 5126 1.2 lneto <pre>const lua_Number *lua_version (lua_State *L);</pre> 5127 1.2 lneto 5128 1.2 lneto <p> 5129 1.2 lneto Returns the address of the version number stored in the Lua core. 5130 1.2 lneto When called with a valid <a href="#lua_State"><code>lua_State</code></a>, 5131 1.2 lneto returns the address of the version used to create that state. 5132 1.2 lneto When called with <code>NULL</code>, 5133 1.2 lneto returns the address of the version running the call. 5134 1.2 lneto 5135 1.2 lneto 5136 1.2 lneto 5137 1.2 lneto 5138 1.2 lneto 5139 1.1 mbalmer <hr><h3><a name="lua_Writer"><code>lua_Writer</code></a></h3> 5140 1.1 mbalmer <pre>typedef int (*lua_Writer) (lua_State *L, 5141 1.1 mbalmer const void* p, 5142 1.1 mbalmer size_t sz, 5143 1.1 mbalmer void* ud);</pre> 5144 1.1 mbalmer 5145 1.1 mbalmer <p> 5146 1.1 mbalmer The type of the writer function used by <a href="#lua_dump"><code>lua_dump</code></a>. 5147 1.1 mbalmer Every time it produces another piece of chunk, 5148 1.1 mbalmer <a href="#lua_dump"><code>lua_dump</code></a> calls the writer, 5149 1.1 mbalmer passing along the buffer to be written (<code>p</code>), 5150 1.1 mbalmer its size (<code>sz</code>), 5151 1.1 mbalmer and the <code>data</code> parameter supplied to <a href="#lua_dump"><code>lua_dump</code></a>. 5152 1.1 mbalmer 5153 1.1 mbalmer 5154 1.1 mbalmer <p> 5155 1.1 mbalmer The writer returns an error code: 5156 1.1 mbalmer 0 means no errors; 5157 1.1 mbalmer any other value means an error and stops <a href="#lua_dump"><code>lua_dump</code></a> from 5158 1.1 mbalmer calling the writer again. 5159 1.1 mbalmer 5160 1.1 mbalmer 5161 1.1 mbalmer 5162 1.1 mbalmer 5163 1.1 mbalmer 5164 1.1 mbalmer <hr><h3><a name="lua_xmove"><code>lua_xmove</code></a></h3><p> 5165 1.2 lneto <span class="apii">[-?, +?, –]</span> 5166 1.1 mbalmer <pre>void lua_xmove (lua_State *from, lua_State *to, int n);</pre> 5167 1.1 mbalmer 5168 1.1 mbalmer <p> 5169 1.2 lneto Exchange values between different threads of the same state. 5170 1.1 mbalmer 5171 1.1 mbalmer 5172 1.1 mbalmer <p> 5173 1.1 mbalmer This function pops <code>n</code> values from the stack <code>from</code>, 5174 1.1 mbalmer and pushes them onto the stack <code>to</code>. 5175 1.1 mbalmer 5176 1.1 mbalmer 5177 1.1 mbalmer 5178 1.1 mbalmer 5179 1.1 mbalmer 5180 1.1 mbalmer <hr><h3><a name="lua_yield"><code>lua_yield</code></a></h3><p> 5181 1.2 lneto <span class="apii">[-?, +?, –]</span> 5182 1.2 lneto <pre>int lua_yield (lua_State *L, int nresults);</pre> 5183 1.2 lneto 5184 1.2 lneto <p> 5185 1.2 lneto This function is equivalent to <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 5186 1.2 lneto but it has no continuation (see <a href="#4.7">§4.7</a>). 5187 1.2 lneto Therefore, when the thread resumes, 5188 1.2 lneto it returns to the function that called 5189 1.2 lneto the function calling <code>lua_yield</code>. 5190 1.2 lneto 5191 1.2 lneto 5192 1.2 lneto 5193 1.2 lneto 5194 1.2 lneto 5195 1.2 lneto <hr><h3><a name="lua_yieldk"><code>lua_yieldk</code></a></h3><p> 5196 1.2 lneto <span class="apii">[-?, +?, –]</span> 5197 1.2 lneto <pre>int lua_yieldk (lua_State *L, int nresults, int ctx, lua_KFunction k);</pre> 5198 1.1 mbalmer 5199 1.1 mbalmer <p> 5200 1.1 mbalmer Yields a coroutine. 5201 1.1 mbalmer 5202 1.1 mbalmer 5203 1.1 mbalmer <p> 5204 1.1 mbalmer This function should only be called as the 5205 1.1 mbalmer return expression of a C function, as follows: 5206 1.1 mbalmer 5207 1.1 mbalmer <pre> 5208 1.2 lneto return lua_yieldk (L, n, ctx, k); 5209 1.1 mbalmer </pre><p> 5210 1.2 lneto When a C function calls <a href="#lua_yieldk"><code>lua_yieldk</code></a> in that way, 5211 1.1 mbalmer the running coroutine suspends its execution, 5212 1.1 mbalmer and the call to <a href="#lua_resume"><code>lua_resume</code></a> that started this coroutine returns. 5213 1.1 mbalmer The parameter <code>nresults</code> is the number of values from the stack 5214 1.2 lneto that will be passed as results to <a href="#lua_resume"><code>lua_resume</code></a>. 5215 1.2 lneto 5216 1.2 lneto 5217 1.2 lneto <p> 5218 1.2 lneto When the coroutine is resumed again, 5219 1.2 lneto Lua calls the given continuation function <code>k</code> to continue 5220 1.2 lneto the execution of the C function that yielded (see <a href="#4.7">§4.7</a>). 5221 1.2 lneto This continuation function receives the same stack 5222 1.2 lneto from the previous function, 5223 1.2 lneto with the <code>n</code> results removed and 5224 1.2 lneto replaced by the arguments passed to <a href="#lua_resume"><code>lua_resume</code></a>. 5225 1.2 lneto Moreover, 5226 1.2 lneto the continuation function receives the value <code>ctx</code> 5227 1.2 lneto that was passed to <a href="#lua_yieldk"><code>lua_yieldk</code></a>. 5228 1.1 mbalmer 5229 1.1 mbalmer 5230 1.1 mbalmer 5231 1.1 mbalmer 5232 1.1 mbalmer 5233 1.1 mbalmer 5234 1.1 mbalmer 5235 1.2 lneto <h2>4.9 – <a name="4.9">The Debug Interface</a></h2> 5236 1.1 mbalmer 5237 1.1 mbalmer <p> 5238 1.1 mbalmer Lua has no built-in debugging facilities. 5239 1.1 mbalmer Instead, it offers a special interface 5240 1.1 mbalmer by means of functions and <em>hooks</em>. 5241 1.1 mbalmer This interface allows the construction of different 5242 1.1 mbalmer kinds of debuggers, profilers, and other tools 5243 1.1 mbalmer that need "inside information" from the interpreter. 5244 1.1 mbalmer 5245 1.1 mbalmer 5246 1.1 mbalmer 5247 1.1 mbalmer <hr><h3><a name="lua_Debug"><code>lua_Debug</code></a></h3> 5248 1.1 mbalmer <pre>typedef struct lua_Debug { 5249 1.1 mbalmer int event; 5250 1.1 mbalmer const char *name; /* (n) */ 5251 1.1 mbalmer const char *namewhat; /* (n) */ 5252 1.1 mbalmer const char *what; /* (S) */ 5253 1.1 mbalmer const char *source; /* (S) */ 5254 1.1 mbalmer int currentline; /* (l) */ 5255 1.1 mbalmer int linedefined; /* (S) */ 5256 1.1 mbalmer int lastlinedefined; /* (S) */ 5257 1.2 lneto unsigned char nups; /* (u) number of upvalues */ 5258 1.2 lneto unsigned char nparams; /* (u) number of parameters */ 5259 1.2 lneto char isvararg; /* (u) */ 5260 1.2 lneto char istailcall; /* (t) */ 5261 1.1 mbalmer char short_src[LUA_IDSIZE]; /* (S) */ 5262 1.1 mbalmer /* private part */ 5263 1.1 mbalmer <em>other fields</em> 5264 1.1 mbalmer } lua_Debug;</pre> 5265 1.1 mbalmer 5266 1.1 mbalmer <p> 5267 1.1 mbalmer A structure used to carry different pieces of 5268 1.2 lneto information about a function or an activation record. 5269 1.1 mbalmer <a href="#lua_getstack"><code>lua_getstack</code></a> fills only the private part 5270 1.1 mbalmer of this structure, for later use. 5271 1.1 mbalmer To fill the other fields of <a href="#lua_Debug"><code>lua_Debug</code></a> with useful information, 5272 1.1 mbalmer call <a href="#lua_getinfo"><code>lua_getinfo</code></a>. 5273 1.1 mbalmer 5274 1.1 mbalmer 5275 1.1 mbalmer <p> 5276 1.1 mbalmer The fields of <a href="#lua_Debug"><code>lua_Debug</code></a> have the following meaning: 5277 1.1 mbalmer 5278 1.1 mbalmer <ul> 5279 1.1 mbalmer 5280 1.2 lneto <li><b><code>source</code>: </b> 5281 1.2 lneto the source of the chunk that created the function. 5282 1.2 lneto If <code>source</code> starts with a '<code>@</code>', 5283 1.2 lneto it means that the function was defined in a file where 5284 1.2 lneto the file name follows the '<code>@</code>'. 5285 1.2 lneto If <code>source</code> starts with a '<code>=</code>', 5286 1.2 lneto the remainder of its contents describe the source in a user-dependent manner. 5287 1.2 lneto Otherwise, 5288 1.2 lneto the function was defined in a string where 5289 1.2 lneto <code>source</code> is that string. 5290 1.1 mbalmer </li> 5291 1.1 mbalmer 5292 1.2 lneto <li><b><code>short_src</code>: </b> 5293 1.1 mbalmer a "printable" version of <code>source</code>, to be used in error messages. 5294 1.1 mbalmer </li> 5295 1.1 mbalmer 5296 1.2 lneto <li><b><code>linedefined</code>: </b> 5297 1.1 mbalmer the line number where the definition of the function starts. 5298 1.1 mbalmer </li> 5299 1.1 mbalmer 5300 1.2 lneto <li><b><code>lastlinedefined</code>: </b> 5301 1.1 mbalmer the line number where the definition of the function ends. 5302 1.1 mbalmer </li> 5303 1.1 mbalmer 5304 1.2 lneto <li><b><code>what</code>: </b> 5305 1.1 mbalmer the string <code>"Lua"</code> if the function is a Lua function, 5306 1.1 mbalmer <code>"C"</code> if it is a C function, 5307 1.2 lneto <code>"main"</code> if it is the main part of a chunk. 5308 1.1 mbalmer </li> 5309 1.1 mbalmer 5310 1.2 lneto <li><b><code>currentline</code>: </b> 5311 1.1 mbalmer the current line where the given function is executing. 5312 1.1 mbalmer When no line information is available, 5313 1.1 mbalmer <code>currentline</code> is set to -1. 5314 1.1 mbalmer </li> 5315 1.1 mbalmer 5316 1.2 lneto <li><b><code>name</code>: </b> 5317 1.1 mbalmer a reasonable name for the given function. 5318 1.1 mbalmer Because functions in Lua are first-class values, 5319 1.1 mbalmer they do not have a fixed name: 5320 1.1 mbalmer some functions can be the value of multiple global variables, 5321 1.1 mbalmer while others can be stored only in a table field. 5322 1.1 mbalmer The <code>lua_getinfo</code> function checks how the function was 5323 1.1 mbalmer called to find a suitable name. 5324 1.1 mbalmer If it cannot find a name, 5325 1.1 mbalmer then <code>name</code> is set to <code>NULL</code>. 5326 1.1 mbalmer </li> 5327 1.1 mbalmer 5328 1.2 lneto <li><b><code>namewhat</code>: </b> 5329 1.1 mbalmer explains the <code>name</code> field. 5330 1.1 mbalmer The value of <code>namewhat</code> can be 5331 1.1 mbalmer <code>"global"</code>, <code>"local"</code>, <code>"method"</code>, 5332 1.1 mbalmer <code>"field"</code>, <code>"upvalue"</code>, or <code>""</code> (the empty string), 5333 1.1 mbalmer according to how the function was called. 5334 1.1 mbalmer (Lua uses the empty string when no other option seems to apply.) 5335 1.1 mbalmer </li> 5336 1.1 mbalmer 5337 1.2 lneto <li><b><code>istailcall</code>: </b> 5338 1.2 lneto true if this function invocation was called by a tail call. 5339 1.2 lneto In this case, the caller of this level is not in the stack. 5340 1.2 lneto </li> 5341 1.2 lneto 5342 1.2 lneto <li><b><code>nups</code>: </b> 5343 1.1 mbalmer the number of upvalues of the function. 5344 1.1 mbalmer </li> 5345 1.1 mbalmer 5346 1.2 lneto <li><b><code>nparams</code>: </b> 5347 1.2 lneto the number of fixed parameters of the function 5348 1.2 lneto (always 0 for C functions). 5349 1.2 lneto </li> 5350 1.2 lneto 5351 1.2 lneto <li><b><code>isvararg</code>: </b> 5352 1.2 lneto true if the function is a vararg function 5353 1.2 lneto (always true for C functions). 5354 1.2 lneto </li> 5355 1.2 lneto 5356 1.1 mbalmer </ul> 5357 1.1 mbalmer 5358 1.1 mbalmer 5359 1.1 mbalmer 5360 1.1 mbalmer 5361 1.1 mbalmer <hr><h3><a name="lua_gethook"><code>lua_gethook</code></a></h3><p> 5362 1.2 lneto <span class="apii">[-0, +0, –]</span> 5363 1.1 mbalmer <pre>lua_Hook lua_gethook (lua_State *L);</pre> 5364 1.1 mbalmer 5365 1.1 mbalmer <p> 5366 1.1 mbalmer Returns the current hook function. 5367 1.1 mbalmer 5368 1.1 mbalmer 5369 1.1 mbalmer 5370 1.1 mbalmer 5371 1.1 mbalmer 5372 1.1 mbalmer <hr><h3><a name="lua_gethookcount"><code>lua_gethookcount</code></a></h3><p> 5373 1.2 lneto <span class="apii">[-0, +0, –]</span> 5374 1.1 mbalmer <pre>int lua_gethookcount (lua_State *L);</pre> 5375 1.1 mbalmer 5376 1.1 mbalmer <p> 5377 1.1 mbalmer Returns the current hook count. 5378 1.1 mbalmer 5379 1.1 mbalmer 5380 1.1 mbalmer 5381 1.1 mbalmer 5382 1.1 mbalmer 5383 1.1 mbalmer <hr><h3><a name="lua_gethookmask"><code>lua_gethookmask</code></a></h3><p> 5384 1.2 lneto <span class="apii">[-0, +0, –]</span> 5385 1.1 mbalmer <pre>int lua_gethookmask (lua_State *L);</pre> 5386 1.1 mbalmer 5387 1.1 mbalmer <p> 5388 1.1 mbalmer Returns the current hook mask. 5389 1.1 mbalmer 5390 1.1 mbalmer 5391 1.1 mbalmer 5392 1.1 mbalmer 5393 1.1 mbalmer 5394 1.1 mbalmer <hr><h3><a name="lua_getinfo"><code>lua_getinfo</code></a></h3><p> 5395 1.2 lneto <span class="apii">[-(0|1), +(0|1|2), <em>e</em>]</span> 5396 1.1 mbalmer <pre>int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar);</pre> 5397 1.1 mbalmer 5398 1.1 mbalmer <p> 5399 1.2 lneto Gets information about a specific function or function invocation. 5400 1.1 mbalmer 5401 1.1 mbalmer 5402 1.1 mbalmer <p> 5403 1.1 mbalmer To get information about a function invocation, 5404 1.1 mbalmer the parameter <code>ar</code> must be a valid activation record that was 5405 1.1 mbalmer filled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or 5406 1.1 mbalmer given as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>). 5407 1.1 mbalmer 5408 1.1 mbalmer 5409 1.1 mbalmer <p> 5410 1.1 mbalmer To get information about a function you push it onto the stack 5411 1.1 mbalmer and start the <code>what</code> string with the character '<code>></code>'. 5412 1.1 mbalmer (In that case, 5413 1.2 lneto <code>lua_getinfo</code> pops the function from the top of the stack.) 5414 1.1 mbalmer For instance, to know in which line a function <code>f</code> was defined, 5415 1.1 mbalmer you can write the following code: 5416 1.1 mbalmer 5417 1.1 mbalmer <pre> 5418 1.1 mbalmer lua_Debug ar; 5419 1.2 lneto lua_getglobal(L, "f"); /* get global 'f' */ 5420 1.1 mbalmer lua_getinfo(L, ">S", &ar); 5421 1.1 mbalmer printf("%d\n", ar.linedefined); 5422 1.1 mbalmer </pre> 5423 1.1 mbalmer 5424 1.1 mbalmer <p> 5425 1.1 mbalmer Each character in the string <code>what</code> 5426 1.1 mbalmer selects some fields of the structure <code>ar</code> to be filled or 5427 1.1 mbalmer a value to be pushed on the stack: 5428 1.1 mbalmer 5429 1.1 mbalmer <ul> 5430 1.1 mbalmer 5431 1.2 lneto <li><b>'<code>n</code>': </b> fills in the field <code>name</code> and <code>namewhat</code>; 5432 1.1 mbalmer </li> 5433 1.1 mbalmer 5434 1.2 lneto <li><b>'<code>S</code>': </b> 5435 1.1 mbalmer fills in the fields <code>source</code>, <code>short_src</code>, 5436 1.1 mbalmer <code>linedefined</code>, <code>lastlinedefined</code>, and <code>what</code>; 5437 1.1 mbalmer </li> 5438 1.1 mbalmer 5439 1.2 lneto <li><b>'<code>l</code>': </b> fills in the field <code>currentline</code>; 5440 1.2 lneto </li> 5441 1.2 lneto 5442 1.2 lneto <li><b>'<code>t</code>': </b> fills in the field <code>istailcall</code>; 5443 1.1 mbalmer </li> 5444 1.1 mbalmer 5445 1.2 lneto <li><b>'<code>u</code>': </b> fills in the fields 5446 1.2 lneto <code>nups</code>, <code>nparams</code>, and <code>isvararg</code>; 5447 1.1 mbalmer </li> 5448 1.1 mbalmer 5449 1.2 lneto <li><b>'<code>f</code>': </b> 5450 1.1 mbalmer pushes onto the stack the function that is 5451 1.1 mbalmer running at the given level; 5452 1.1 mbalmer </li> 5453 1.1 mbalmer 5454 1.2 lneto <li><b>'<code>L</code>': </b> 5455 1.1 mbalmer pushes onto the stack a table whose indices are the 5456 1.1 mbalmer numbers of the lines that are valid on the function. 5457 1.1 mbalmer (A <em>valid line</em> is a line with some associated code, 5458 1.1 mbalmer that is, a line where you can put a break point. 5459 1.1 mbalmer Non-valid lines include empty lines and comments.) 5460 1.2 lneto 5461 1.2 lneto 5462 1.2 lneto <p> 5463 1.2 lneto If this option is given together with option '<code>f</code>', 5464 1.2 lneto its table is pushed after the function. 5465 1.1 mbalmer </li> 5466 1.1 mbalmer 5467 1.1 mbalmer </ul> 5468 1.1 mbalmer 5469 1.1 mbalmer <p> 5470 1.1 mbalmer This function returns 0 on error 5471 1.1 mbalmer (for instance, an invalid option in <code>what</code>). 5472 1.1 mbalmer 5473 1.1 mbalmer 5474 1.1 mbalmer 5475 1.1 mbalmer 5476 1.1 mbalmer 5477 1.1 mbalmer <hr><h3><a name="lua_getlocal"><code>lua_getlocal</code></a></h3><p> 5478 1.2 lneto <span class="apii">[-0, +(0|1), –]</span> 5479 1.1 mbalmer <pre>const char *lua_getlocal (lua_State *L, lua_Debug *ar, int n);</pre> 5480 1.1 mbalmer 5481 1.1 mbalmer <p> 5482 1.2 lneto Gets information about a local variable of 5483 1.2 lneto a given activation record or a given function. 5484 1.2 lneto 5485 1.2 lneto 5486 1.2 lneto <p> 5487 1.2 lneto In the first case, 5488 1.2 lneto the parameter <code>ar</code> must be a valid activation record that was 5489 1.1 mbalmer filled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or 5490 1.1 mbalmer given as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>). 5491 1.2 lneto The index <code>n</code> selects which local variable to inspect; 5492 1.2 lneto see <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for details about variable indices 5493 1.2 lneto and names. 5494 1.2 lneto 5495 1.2 lneto 5496 1.2 lneto <p> 5497 1.1 mbalmer <a href="#lua_getlocal"><code>lua_getlocal</code></a> pushes the variable's value onto the stack 5498 1.1 mbalmer and returns its name. 5499 1.1 mbalmer 5500 1.1 mbalmer 5501 1.1 mbalmer <p> 5502 1.2 lneto In the second case, <code>ar</code> must be <code>NULL</code> and the function 5503 1.2 lneto to be inspected must be at the top of the stack. 5504 1.2 lneto In this case, only parameters of Lua functions are visible 5505 1.2 lneto (as there is no information about what variables are active) 5506 1.2 lneto and no values are pushed onto the stack. 5507 1.1 mbalmer 5508 1.1 mbalmer 5509 1.1 mbalmer <p> 5510 1.1 mbalmer Returns <code>NULL</code> (and pushes nothing) 5511 1.1 mbalmer when the index is greater than 5512 1.1 mbalmer the number of active local variables. 5513 1.1 mbalmer 5514 1.1 mbalmer 5515 1.1 mbalmer 5516 1.1 mbalmer 5517 1.1 mbalmer 5518 1.1 mbalmer <hr><h3><a name="lua_getstack"><code>lua_getstack</code></a></h3><p> 5519 1.2 lneto <span class="apii">[-0, +0, –]</span> 5520 1.1 mbalmer <pre>int lua_getstack (lua_State *L, int level, lua_Debug *ar);</pre> 5521 1.1 mbalmer 5522 1.1 mbalmer <p> 5523 1.2 lneto Gets information about the interpreter runtime stack. 5524 1.1 mbalmer 5525 1.1 mbalmer 5526 1.1 mbalmer <p> 5527 1.1 mbalmer This function fills parts of a <a href="#lua_Debug"><code>lua_Debug</code></a> structure with 5528 1.1 mbalmer an identification of the <em>activation record</em> 5529 1.1 mbalmer of the function executing at a given level. 5530 1.1 mbalmer Level 0 is the current running function, 5531 1.2 lneto whereas level <em>n+1</em> is the function that has called level <em>n</em> 5532 1.2 lneto (except for tail calls, which do not count on the stack). 5533 1.1 mbalmer When there are no errors, <a href="#lua_getstack"><code>lua_getstack</code></a> returns 1; 5534 1.1 mbalmer when called with a level greater than the stack depth, 5535 1.1 mbalmer it returns 0. 5536 1.1 mbalmer 5537 1.1 mbalmer 5538 1.1 mbalmer 5539 1.1 mbalmer 5540 1.1 mbalmer 5541 1.1 mbalmer <hr><h3><a name="lua_getupvalue"><code>lua_getupvalue</code></a></h3><p> 5542 1.2 lneto <span class="apii">[-0, +(0|1), –]</span> 5543 1.1 mbalmer <pre>const char *lua_getupvalue (lua_State *L, int funcindex, int n);</pre> 5544 1.1 mbalmer 5545 1.1 mbalmer <p> 5546 1.1 mbalmer Gets information about a closure's upvalue. 5547 1.1 mbalmer (For Lua functions, 5548 1.1 mbalmer upvalues are the external local variables that the function uses, 5549 1.1 mbalmer and that are consequently included in its closure.) 5550 1.1 mbalmer <a href="#lua_getupvalue"><code>lua_getupvalue</code></a> gets the index <code>n</code> of an upvalue, 5551 1.1 mbalmer pushes the upvalue's value onto the stack, 5552 1.1 mbalmer and returns its name. 5553 1.1 mbalmer <code>funcindex</code> points to the closure in the stack. 5554 1.1 mbalmer (Upvalues have no particular order, 5555 1.1 mbalmer as they are active through the whole function. 5556 1.1 mbalmer So, they are numbered in an arbitrary order.) 5557 1.1 mbalmer 5558 1.1 mbalmer 5559 1.1 mbalmer <p> 5560 1.1 mbalmer Returns <code>NULL</code> (and pushes nothing) 5561 1.1 mbalmer when the index is greater than the number of upvalues. 5562 1.1 mbalmer For C functions, this function uses the empty string <code>""</code> 5563 1.1 mbalmer as a name for all upvalues. 5564 1.1 mbalmer 5565 1.1 mbalmer 5566 1.1 mbalmer 5567 1.1 mbalmer 5568 1.1 mbalmer 5569 1.1 mbalmer <hr><h3><a name="lua_Hook"><code>lua_Hook</code></a></h3> 5570 1.1 mbalmer <pre>typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar);</pre> 5571 1.1 mbalmer 5572 1.1 mbalmer <p> 5573 1.1 mbalmer Type for debugging hook functions. 5574 1.1 mbalmer 5575 1.1 mbalmer 5576 1.1 mbalmer <p> 5577 1.1 mbalmer Whenever a hook is called, its <code>ar</code> argument has its field 5578 1.1 mbalmer <code>event</code> set to the specific event that triggered the hook. 5579 1.1 mbalmer Lua identifies these events with the following constants: 5580 1.1 mbalmer <a name="pdf-LUA_HOOKCALL"><code>LUA_HOOKCALL</code></a>, <a name="pdf-LUA_HOOKRET"><code>LUA_HOOKRET</code></a>, 5581 1.2 lneto <a name="pdf-LUA_HOOKTAILCALL"><code>LUA_HOOKTAILCALL</code></a>, <a name="pdf-LUA_HOOKLINE"><code>LUA_HOOKLINE</code></a>, 5582 1.1 mbalmer and <a name="pdf-LUA_HOOKCOUNT"><code>LUA_HOOKCOUNT</code></a>. 5583 1.1 mbalmer Moreover, for line events, the field <code>currentline</code> is also set. 5584 1.1 mbalmer To get the value of any other field in <code>ar</code>, 5585 1.1 mbalmer the hook must call <a href="#lua_getinfo"><code>lua_getinfo</code></a>. 5586 1.2 lneto 5587 1.2 lneto 5588 1.2 lneto <p> 5589 1.2 lneto For call events, <code>event</code> can be <code>LUA_HOOKCALL</code>, 5590 1.2 lneto the normal value, or <code>LUA_HOOKTAILCALL</code>, for a tail call; 5591 1.2 lneto in this case, there will be no corresponding return event. 5592 1.1 mbalmer 5593 1.1 mbalmer 5594 1.1 mbalmer <p> 5595 1.1 mbalmer While Lua is running a hook, it disables other calls to hooks. 5596 1.1 mbalmer Therefore, if a hook calls back Lua to execute a function or a chunk, 5597 1.1 mbalmer this execution occurs without any calls to hooks. 5598 1.1 mbalmer 5599 1.1 mbalmer 5600 1.2 lneto <p> 5601 1.2 lneto Hook functions cannot have continuations, 5602 1.2 lneto that is, they cannot call <a href="#lua_yieldk"><code>lua_yieldk</code></a>, 5603 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>. 5604 1.2 lneto 5605 1.2 lneto 5606 1.2 lneto <p> 5607 1.2 lneto Hook functions can yield under the following conditions: 5608 1.2 lneto Only count and line events can yield 5609 1.2 lneto and they cannot yield any value; 5610 1.2 lneto to yield a hook function must finish its execution 5611 1.2 lneto calling <a href="#lua_yield"><code>lua_yield</code></a> with <code>nresults</code> equal to zero. 5612 1.2 lneto 5613 1.2 lneto 5614 1.1 mbalmer 5615 1.1 mbalmer 5616 1.1 mbalmer 5617 1.1 mbalmer <hr><h3><a name="lua_sethook"><code>lua_sethook</code></a></h3><p> 5618 1.2 lneto <span class="apii">[-0, +0, –]</span> 5619 1.2 lneto <pre>void lua_sethook (lua_State *L, lua_Hook f, int mask, int count);</pre> 5620 1.1 mbalmer 5621 1.1 mbalmer <p> 5622 1.1 mbalmer Sets the debugging hook function. 5623 1.1 mbalmer 5624 1.1 mbalmer 5625 1.1 mbalmer <p> 5626 1.1 mbalmer Argument <code>f</code> is the hook function. 5627 1.1 mbalmer <code>mask</code> specifies on which events the hook will be called: 5628 1.1 mbalmer it is formed by a bitwise or of the constants 5629 1.1 mbalmer <a name="pdf-LUA_MASKCALL"><code>LUA_MASKCALL</code></a>, 5630 1.1 mbalmer <a name="pdf-LUA_MASKRET"><code>LUA_MASKRET</code></a>, 5631 1.1 mbalmer <a name="pdf-LUA_MASKLINE"><code>LUA_MASKLINE</code></a>, 5632 1.1 mbalmer and <a name="pdf-LUA_MASKCOUNT"><code>LUA_MASKCOUNT</code></a>. 5633 1.1 mbalmer The <code>count</code> argument is only meaningful when the mask 5634 1.1 mbalmer includes <code>LUA_MASKCOUNT</code>. 5635 1.1 mbalmer For each event, the hook is called as explained below: 5636 1.1 mbalmer 5637 1.1 mbalmer <ul> 5638 1.1 mbalmer 5639 1.2 lneto <li><b>The call hook: </b> is called when the interpreter calls a function. 5640 1.1 mbalmer The hook is called just after Lua enters the new function, 5641 1.1 mbalmer before the function gets its arguments. 5642 1.1 mbalmer </li> 5643 1.1 mbalmer 5644 1.2 lneto <li><b>The return hook: </b> is called when the interpreter returns from a function. 5645 1.1 mbalmer The hook is called just before Lua leaves the function. 5646 1.2 lneto There is no standard way to access the values 5647 1.2 lneto to be returned by the function. 5648 1.1 mbalmer </li> 5649 1.1 mbalmer 5650 1.2 lneto <li><b>The line hook: </b> is called when the interpreter is about to 5651 1.1 mbalmer start the execution of a new line of code, 5652 1.1 mbalmer or when it jumps back in the code (even to the same line). 5653 1.1 mbalmer (This event only happens while Lua is executing a Lua function.) 5654 1.1 mbalmer </li> 5655 1.1 mbalmer 5656 1.2 lneto <li><b>The count hook: </b> is called after the interpreter executes every 5657 1.1 mbalmer <code>count</code> instructions. 5658 1.1 mbalmer (This event only happens while Lua is executing a Lua function.) 5659 1.1 mbalmer </li> 5660 1.1 mbalmer 5661 1.1 mbalmer </ul> 5662 1.1 mbalmer 5663 1.1 mbalmer <p> 5664 1.1 mbalmer A hook is disabled by setting <code>mask</code> to zero. 5665 1.1 mbalmer 5666 1.1 mbalmer 5667 1.1 mbalmer 5668 1.1 mbalmer 5669 1.1 mbalmer 5670 1.1 mbalmer <hr><h3><a name="lua_setlocal"><code>lua_setlocal</code></a></h3><p> 5671 1.2 lneto <span class="apii">[-(0|1), +0, –]</span> 5672 1.1 mbalmer <pre>const char *lua_setlocal (lua_State *L, lua_Debug *ar, int n);</pre> 5673 1.1 mbalmer 5674 1.1 mbalmer <p> 5675 1.1 mbalmer Sets the value of a local variable of a given activation record. 5676 1.1 mbalmer Parameters <code>ar</code> and <code>n</code> are as in <a href="#lua_getlocal"><code>lua_getlocal</code></a> 5677 1.1 mbalmer (see <a href="#lua_getlocal"><code>lua_getlocal</code></a>). 5678 1.1 mbalmer <a href="#lua_setlocal"><code>lua_setlocal</code></a> assigns the value at the top of the stack 5679 1.1 mbalmer to the variable and returns its name. 5680 1.1 mbalmer It also pops the value from the stack. 5681 1.1 mbalmer 5682 1.1 mbalmer 5683 1.1 mbalmer <p> 5684 1.1 mbalmer Returns <code>NULL</code> (and pops nothing) 5685 1.1 mbalmer when the index is greater than 5686 1.1 mbalmer the number of active local variables. 5687 1.1 mbalmer 5688 1.1 mbalmer 5689 1.1 mbalmer 5690 1.1 mbalmer 5691 1.1 mbalmer 5692 1.1 mbalmer <hr><h3><a name="lua_setupvalue"><code>lua_setupvalue</code></a></h3><p> 5693 1.2 lneto <span class="apii">[-(0|1), +0, –]</span> 5694 1.1 mbalmer <pre>const char *lua_setupvalue (lua_State *L, int funcindex, int n);</pre> 5695 1.1 mbalmer 5696 1.1 mbalmer <p> 5697 1.1 mbalmer Sets the value of a closure's upvalue. 5698 1.1 mbalmer It assigns the value at the top of the stack 5699 1.1 mbalmer to the upvalue and returns its name. 5700 1.1 mbalmer It also pops the value from the stack. 5701 1.1 mbalmer Parameters <code>funcindex</code> and <code>n</code> are as in the <a href="#lua_getupvalue"><code>lua_getupvalue</code></a> 5702 1.1 mbalmer (see <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>). 5703 1.1 mbalmer 5704 1.1 mbalmer 5705 1.1 mbalmer <p> 5706 1.1 mbalmer Returns <code>NULL</code> (and pops nothing) 5707 1.1 mbalmer when the index is greater than the number of upvalues. 5708 1.1 mbalmer 5709 1.1 mbalmer 5710 1.1 mbalmer 5711 1.1 mbalmer 5712 1.1 mbalmer 5713 1.2 lneto <hr><h3><a name="lua_upvalueid"><code>lua_upvalueid</code></a></h3><p> 5714 1.2 lneto <span class="apii">[-0, +0, –]</span> 5715 1.2 lneto <pre>void *lua_upvalueid (lua_State *L, int funcindex, int n);</pre> 5716 1.2 lneto 5717 1.2 lneto <p> 5718 1.2 lneto Returns an unique identifier for the upvalue numbered <code>n</code> 5719 1.2 lneto from the closure at index <code>funcindex</code>. 5720 1.2 lneto Parameters <code>funcindex</code> and <code>n</code> are as in the <a href="#lua_getupvalue"><code>lua_getupvalue</code></a> 5721 1.2 lneto (see <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>) 5722 1.2 lneto (but <code>n</code> cannot be greater than the number of upvalues). 5723 1.2 lneto 5724 1.2 lneto 5725 1.2 lneto <p> 5726 1.2 lneto These unique identifiers allow a program to check whether different 5727 1.2 lneto closures share upvalues. 5728 1.2 lneto Lua closures that share an upvalue 5729 1.2 lneto (that is, that access a same external local variable) 5730 1.2 lneto will return identical ids for those upvalue indices. 5731 1.2 lneto 5732 1.2 lneto 5733 1.2 lneto 5734 1.2 lneto 5735 1.2 lneto 5736 1.2 lneto <hr><h3><a name="lua_upvaluejoin"><code>lua_upvaluejoin</code></a></h3><p> 5737 1.2 lneto <span class="apii">[-0, +0, –]</span> 5738 1.2 lneto <pre>void lua_upvaluejoin (lua_State *L, int funcindex1, int n1, 5739 1.2 lneto int funcindex2, int n2);</pre> 5740 1.2 lneto 5741 1.2 lneto <p> 5742 1.2 lneto Make the <code>n1</code>-th upvalue of the Lua closure at index <code>funcindex1</code> 5743 1.2 lneto refer to the <code>n2</code>-th upvalue of the Lua closure at index <code>funcindex2</code>. 5744 1.2 lneto 5745 1.2 lneto 5746 1.2 lneto 5747 1.2 lneto 5748 1.2 lneto 5749 1.1 mbalmer 5750 1.1 mbalmer 5751 1.2 lneto <h1>5 – <a name="5">The Auxiliary Library</a></h1> 5752 1.1 mbalmer 5753 1.1 mbalmer <p> 5754 1.1 mbalmer 5755 1.1 mbalmer The <em>auxiliary library</em> provides several convenient functions 5756 1.1 mbalmer to interface C with Lua. 5757 1.2 lneto While the basic API provides the primitive functions for all 5758 1.1 mbalmer interactions between C and Lua, 5759 1.1 mbalmer the auxiliary library provides higher-level functions for some 5760 1.1 mbalmer common tasks. 5761 1.1 mbalmer 5762 1.1 mbalmer 5763 1.1 mbalmer <p> 5764 1.2 lneto All functions and types from the auxiliary library 5765 1.1 mbalmer are defined in header file <code>lauxlib.h</code> and 5766 1.1 mbalmer have a prefix <code>luaL_</code>. 5767 1.1 mbalmer 5768 1.1 mbalmer 5769 1.1 mbalmer <p> 5770 1.1 mbalmer All functions in the auxiliary library are built on 5771 1.1 mbalmer top of the basic API, 5772 1.2 lneto and so they provide nothing that cannot be done with that API. 5773 1.2 lneto Nevertheless, the use of the auxiliary library ensures 5774 1.2 lneto more consistency to your code. 5775 1.2 lneto 5776 1.2 lneto 5777 1.2 lneto <p> 5778 1.2 lneto Several functions in the auxiliary library use internally some 5779 1.2 lneto extra stack slots. 5780 1.2 lneto When a function in the auxiliary library uses less than five slots, 5781 1.2 lneto it does not check the stack size; 5782 1.2 lneto it simply assumes that there are enough slots. 5783 1.1 mbalmer 5784 1.1 mbalmer 5785 1.1 mbalmer <p> 5786 1.1 mbalmer Several functions in the auxiliary library are used to 5787 1.1 mbalmer check C function arguments. 5788 1.1 mbalmer Because the error message is formatted for arguments 5789 1.1 mbalmer (e.g., "<code>bad argument #1</code>"), 5790 1.1 mbalmer you should not use these functions for other stack values. 5791 1.1 mbalmer 5792 1.1 mbalmer 5793 1.2 lneto <p> 5794 1.2 lneto Functions called <code>luaL_check*</code> 5795 1.2 lneto always raise an error if the check is not satisfied. 5796 1.2 lneto 5797 1.2 lneto 5798 1.1 mbalmer 5799 1.2 lneto <h2>5.1 – <a name="5.1">Functions and Types</a></h2> 5800 1.1 mbalmer 5801 1.1 mbalmer <p> 5802 1.1 mbalmer Here we list all functions and types from the auxiliary library 5803 1.1 mbalmer in alphabetical order. 5804 1.1 mbalmer 5805 1.1 mbalmer 5806 1.1 mbalmer 5807 1.1 mbalmer <hr><h3><a name="luaL_addchar"><code>luaL_addchar</code></a></h3><p> 5808 1.2 lneto <span class="apii">[-?, +?, <em>e</em>]</span> 5809 1.1 mbalmer <pre>void luaL_addchar (luaL_Buffer *B, char c);</pre> 5810 1.1 mbalmer 5811 1.1 mbalmer <p> 5812 1.2 lneto Adds the byte <code>c</code> to the buffer <code>B</code> 5813 1.1 mbalmer (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 5814 1.1 mbalmer 5815 1.1 mbalmer 5816 1.1 mbalmer 5817 1.1 mbalmer 5818 1.1 mbalmer 5819 1.1 mbalmer <hr><h3><a name="luaL_addlstring"><code>luaL_addlstring</code></a></h3><p> 5820 1.2 lneto <span class="apii">[-?, +?, <em>e</em>]</span> 5821 1.1 mbalmer <pre>void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l);</pre> 5822 1.1 mbalmer 5823 1.1 mbalmer <p> 5824 1.1 mbalmer Adds the string pointed to by <code>s</code> with length <code>l</code> to 5825 1.1 mbalmer the buffer <code>B</code> 5826 1.1 mbalmer (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 5827 1.2 lneto The string can contain embedded zeros. 5828 1.1 mbalmer 5829 1.1 mbalmer 5830 1.1 mbalmer 5831 1.1 mbalmer 5832 1.1 mbalmer 5833 1.1 mbalmer <hr><h3><a name="luaL_addsize"><code>luaL_addsize</code></a></h3><p> 5834 1.2 lneto <span class="apii">[-?, +?, <em>e</em>]</span> 5835 1.1 mbalmer <pre>void luaL_addsize (luaL_Buffer *B, size_t n);</pre> 5836 1.1 mbalmer 5837 1.1 mbalmer <p> 5838 1.1 mbalmer Adds to the buffer <code>B</code> (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>) 5839 1.1 mbalmer a string of length <code>n</code> previously copied to the 5840 1.1 mbalmer buffer area (see <a href="#luaL_prepbuffer"><code>luaL_prepbuffer</code></a>). 5841 1.1 mbalmer 5842 1.1 mbalmer 5843 1.1 mbalmer 5844 1.1 mbalmer 5845 1.1 mbalmer 5846 1.1 mbalmer <hr><h3><a name="luaL_addstring"><code>luaL_addstring</code></a></h3><p> 5847 1.2 lneto <span class="apii">[-?, +?, <em>e</em>]</span> 5848 1.1 mbalmer <pre>void luaL_addstring (luaL_Buffer *B, const char *s);</pre> 5849 1.1 mbalmer 5850 1.1 mbalmer <p> 5851 1.1 mbalmer Adds the zero-terminated string pointed to by <code>s</code> 5852 1.1 mbalmer to the buffer <code>B</code> 5853 1.1 mbalmer (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 5854 1.1 mbalmer 5855 1.1 mbalmer 5856 1.1 mbalmer 5857 1.1 mbalmer 5858 1.1 mbalmer 5859 1.1 mbalmer <hr><h3><a name="luaL_addvalue"><code>luaL_addvalue</code></a></h3><p> 5860 1.2 lneto <span class="apii">[-1, +?, <em>e</em>]</span> 5861 1.1 mbalmer <pre>void luaL_addvalue (luaL_Buffer *B);</pre> 5862 1.1 mbalmer 5863 1.1 mbalmer <p> 5864 1.1 mbalmer Adds the value at the top of the stack 5865 1.1 mbalmer to the buffer <code>B</code> 5866 1.1 mbalmer (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 5867 1.1 mbalmer Pops the value. 5868 1.1 mbalmer 5869 1.1 mbalmer 5870 1.1 mbalmer <p> 5871 1.1 mbalmer This is the only function on string buffers that can (and must) 5872 1.1 mbalmer be called with an extra element on the stack, 5873 1.1 mbalmer which is the value to be added to the buffer. 5874 1.1 mbalmer 5875 1.1 mbalmer 5876 1.1 mbalmer 5877 1.1 mbalmer 5878 1.1 mbalmer 5879 1.1 mbalmer <hr><h3><a name="luaL_argcheck"><code>luaL_argcheck</code></a></h3><p> 5880 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 5881 1.1 mbalmer <pre>void luaL_argcheck (lua_State *L, 5882 1.1 mbalmer int cond, 5883 1.2 lneto int arg, 5884 1.1 mbalmer const char *extramsg);</pre> 5885 1.1 mbalmer 5886 1.1 mbalmer <p> 5887 1.1 mbalmer Checks whether <code>cond</code> is true. 5888 1.2 lneto If it is not, raises an error with a standard message (see <a href="#luaL_argerror"><code>luaL_argerror</code></a>). 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="luaL_argerror"><code>luaL_argerror</code></a></h3><p> 5895 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 5896 1.2 lneto <pre>int luaL_argerror (lua_State *L, int arg, const char *extramsg);</pre> 5897 1.1 mbalmer 5898 1.1 mbalmer <p> 5899 1.2 lneto Raises an error reporting a problem with argument <code>arg</code> 5900 1.2 lneto of the C function that called it, 5901 1.2 lneto using a standard message 5902 1.2 lneto that includes <code>extramsg</code> as a comment: 5903 1.1 mbalmer 5904 1.1 mbalmer <pre> 5905 1.2 lneto bad argument #<em>arg</em> to '<em>funcname</em>' (<em>extramsg</em>) 5906 1.2 lneto </pre><p> 5907 1.2 lneto This function never returns. 5908 1.1 mbalmer 5909 1.1 mbalmer 5910 1.1 mbalmer 5911 1.1 mbalmer 5912 1.1 mbalmer 5913 1.1 mbalmer <hr><h3><a name="luaL_Buffer"><code>luaL_Buffer</code></a></h3> 5914 1.1 mbalmer <pre>typedef struct luaL_Buffer luaL_Buffer;</pre> 5915 1.1 mbalmer 5916 1.1 mbalmer <p> 5917 1.1 mbalmer Type for a <em>string buffer</em>. 5918 1.1 mbalmer 5919 1.1 mbalmer 5920 1.1 mbalmer <p> 5921 1.1 mbalmer A string buffer allows C code to build Lua strings piecemeal. 5922 1.1 mbalmer Its pattern of use is as follows: 5923 1.1 mbalmer 5924 1.1 mbalmer <ul> 5925 1.1 mbalmer 5926 1.2 lneto <li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li> 5927 1.1 mbalmer 5928 1.2 lneto <li>Then initialize it with a call <code>luaL_buffinit(L, &b)</code>.</li> 5929 1.1 mbalmer 5930 1.1 mbalmer <li> 5931 1.2 lneto Then add string pieces to the buffer calling any of 5932 1.1 mbalmer the <code>luaL_add*</code> functions. 5933 1.1 mbalmer </li> 5934 1.1 mbalmer 5935 1.1 mbalmer <li> 5936 1.2 lneto Finish by calling <code>luaL_pushresult(&b)</code>. 5937 1.1 mbalmer This call leaves the final string on the top of the stack. 5938 1.1 mbalmer </li> 5939 1.1 mbalmer 5940 1.1 mbalmer </ul> 5941 1.1 mbalmer 5942 1.1 mbalmer <p> 5943 1.2 lneto If you know beforehand the total size of the resulting string, 5944 1.2 lneto you can use the buffer like this: 5945 1.2 lneto 5946 1.2 lneto <ul> 5947 1.2 lneto 5948 1.2 lneto <li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li> 5949 1.2 lneto 5950 1.2 lneto <li>Then initialize it and preallocate a space of 5951 1.2 lneto size <code>sz</code> with a call <code>luaL_buffinitsize(L, &b, sz)</code>.</li> 5952 1.2 lneto 5953 1.2 lneto <li>Then copy the string into that space.</li> 5954 1.2 lneto 5955 1.2 lneto <li> 5956 1.2 lneto Finish by calling <code>luaL_pushresultsize(&b, sz)</code>, 5957 1.2 lneto where <code>sz</code> is the total size of the resulting string 5958 1.2 lneto copied into that space. 5959 1.2 lneto </li> 5960 1.2 lneto 5961 1.2 lneto </ul> 5962 1.2 lneto 5963 1.2 lneto <p> 5964 1.1 mbalmer During its normal operation, 5965 1.1 mbalmer a string buffer uses a variable number of stack slots. 5966 1.1 mbalmer So, while using a buffer, you cannot assume that you know where 5967 1.1 mbalmer the top of the stack is. 5968 1.1 mbalmer You can use the stack between successive calls to buffer operations 5969 1.1 mbalmer as long as that use is balanced; 5970 1.1 mbalmer that is, 5971 1.1 mbalmer when you call a buffer operation, 5972 1.1 mbalmer the stack is at the same level 5973 1.1 mbalmer it was immediately after the previous buffer operation. 5974 1.1 mbalmer (The only exception to this rule is <a href="#luaL_addvalue"><code>luaL_addvalue</code></a>.) 5975 1.1 mbalmer After calling <a href="#luaL_pushresult"><code>luaL_pushresult</code></a> the stack is back to its 5976 1.1 mbalmer level when the buffer was initialized, 5977 1.1 mbalmer plus the final string on its top. 5978 1.1 mbalmer 5979 1.1 mbalmer 5980 1.1 mbalmer 5981 1.1 mbalmer 5982 1.1 mbalmer 5983 1.1 mbalmer <hr><h3><a name="luaL_buffinit"><code>luaL_buffinit</code></a></h3><p> 5984 1.2 lneto <span class="apii">[-0, +0, –]</span> 5985 1.1 mbalmer <pre>void luaL_buffinit (lua_State *L, luaL_Buffer *B);</pre> 5986 1.1 mbalmer 5987 1.1 mbalmer <p> 5988 1.1 mbalmer Initializes a buffer <code>B</code>. 5989 1.1 mbalmer This function does not allocate any space; 5990 1.1 mbalmer the buffer must be declared as a variable 5991 1.1 mbalmer (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 5992 1.1 mbalmer 5993 1.1 mbalmer 5994 1.1 mbalmer 5995 1.1 mbalmer 5996 1.1 mbalmer 5997 1.2 lneto <hr><h3><a name="luaL_buffinitsize"><code>luaL_buffinitsize</code></a></h3><p> 5998 1.2 lneto <span class="apii">[-?, +?, <em>e</em>]</span> 5999 1.2 lneto <pre>char *luaL_buffinitsize (lua_State *L, luaL_Buffer *B, size_t sz);</pre> 6000 1.2 lneto 6001 1.2 lneto <p> 6002 1.2 lneto Equivalent to the sequence 6003 1.2 lneto <a href="#luaL_buffinit"><code>luaL_buffinit</code></a>, <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a>. 6004 1.2 lneto 6005 1.2 lneto 6006 1.2 lneto 6007 1.2 lneto 6008 1.2 lneto 6009 1.1 mbalmer <hr><h3><a name="luaL_callmeta"><code>luaL_callmeta</code></a></h3><p> 6010 1.1 mbalmer <span class="apii">[-0, +(0|1), <em>e</em>]</span> 6011 1.1 mbalmer <pre>int luaL_callmeta (lua_State *L, int obj, const char *e);</pre> 6012 1.1 mbalmer 6013 1.1 mbalmer <p> 6014 1.1 mbalmer Calls a metamethod. 6015 1.1 mbalmer 6016 1.1 mbalmer 6017 1.1 mbalmer <p> 6018 1.1 mbalmer If the object at index <code>obj</code> has a metatable and this 6019 1.1 mbalmer metatable has a field <code>e</code>, 6020 1.2 lneto this function calls this field passing the object as its only argument. 6021 1.2 lneto In this case this function returns true and pushes onto the 6022 1.1 mbalmer stack the value returned by the call. 6023 1.1 mbalmer If there is no metatable or no metamethod, 6024 1.2 lneto this function returns false (without pushing any value on the stack). 6025 1.1 mbalmer 6026 1.1 mbalmer 6027 1.1 mbalmer 6028 1.1 mbalmer 6029 1.1 mbalmer 6030 1.1 mbalmer <hr><h3><a name="luaL_checkany"><code>luaL_checkany</code></a></h3><p> 6031 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 6032 1.2 lneto <pre>void luaL_checkany (lua_State *L, int arg);</pre> 6033 1.1 mbalmer 6034 1.1 mbalmer <p> 6035 1.1 mbalmer Checks whether the function has an argument 6036 1.2 lneto of any type (including <b>nil</b>) at position <code>arg</code>. 6037 1.1 mbalmer 6038 1.1 mbalmer 6039 1.1 mbalmer 6040 1.1 mbalmer 6041 1.1 mbalmer 6042 1.1 mbalmer <hr><h3><a name="luaL_checkint"><code>luaL_checkint</code></a></h3><p> 6043 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 6044 1.2 lneto <pre>int luaL_checkint (lua_State *L, int arg);</pre> 6045 1.1 mbalmer 6046 1.1 mbalmer <p> 6047 1.2 lneto Checks whether the function argument <code>arg</code> is an integer 6048 1.2 lneto (or can be converted to an integer) 6049 1.2 lneto and returns this integer cast to an <code>int</code>. 6050 1.1 mbalmer 6051 1.1 mbalmer 6052 1.1 mbalmer 6053 1.1 mbalmer 6054 1.1 mbalmer 6055 1.1 mbalmer <hr><h3><a name="luaL_checkinteger"><code>luaL_checkinteger</code></a></h3><p> 6056 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 6057 1.2 lneto <pre>lua_Integer luaL_checkinteger (lua_State *L, int arg);</pre> 6058 1.1 mbalmer 6059 1.1 mbalmer <p> 6060 1.2 lneto Checks whether the function argument <code>arg</code> is an integer 6061 1.2 lneto (or can be converted to an integer) 6062 1.2 lneto and returns this integer cast to a <a href="#lua_Integer"><code>lua_Integer</code></a>. 6063 1.1 mbalmer 6064 1.1 mbalmer 6065 1.1 mbalmer 6066 1.1 mbalmer 6067 1.1 mbalmer 6068 1.1 mbalmer <hr><h3><a name="luaL_checklong"><code>luaL_checklong</code></a></h3><p> 6069 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 6070 1.2 lneto <pre>long luaL_checklong (lua_State *L, int arg);</pre> 6071 1.1 mbalmer 6072 1.1 mbalmer <p> 6073 1.2 lneto Checks whether the function argument <code>arg</code> is an integer 6074 1.2 lneto (or can be converted to an integer) 6075 1.2 lneto and returns this integer cast to a <code>long</code>. 6076 1.1 mbalmer 6077 1.1 mbalmer 6078 1.1 mbalmer 6079 1.1 mbalmer 6080 1.1 mbalmer 6081 1.1 mbalmer <hr><h3><a name="luaL_checklstring"><code>luaL_checklstring</code></a></h3><p> 6082 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 6083 1.2 lneto <pre>const char *luaL_checklstring (lua_State *L, int arg, size_t *l);</pre> 6084 1.1 mbalmer 6085 1.1 mbalmer <p> 6086 1.2 lneto Checks whether the function argument <code>arg</code> is a string 6087 1.1 mbalmer and returns this string; 6088 1.1 mbalmer if <code>l</code> is not <code>NULL</code> fills <code>*l</code> 6089 1.1 mbalmer with the string's length. 6090 1.1 mbalmer 6091 1.1 mbalmer 6092 1.1 mbalmer <p> 6093 1.1 mbalmer This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, 6094 1.1 mbalmer so all conversions and caveats of that function apply here. 6095 1.1 mbalmer 6096 1.1 mbalmer 6097 1.1 mbalmer 6098 1.1 mbalmer 6099 1.1 mbalmer 6100 1.1 mbalmer <hr><h3><a name="luaL_checknumber"><code>luaL_checknumber</code></a></h3><p> 6101 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 6102 1.2 lneto <pre>lua_Number luaL_checknumber (lua_State *L, int arg);</pre> 6103 1.1 mbalmer 6104 1.1 mbalmer <p> 6105 1.2 lneto Checks whether the function argument <code>arg</code> is a number 6106 1.1 mbalmer and returns this number. 6107 1.1 mbalmer 6108 1.1 mbalmer 6109 1.1 mbalmer 6110 1.1 mbalmer 6111 1.1 mbalmer 6112 1.1 mbalmer <hr><h3><a name="luaL_checkoption"><code>luaL_checkoption</code></a></h3><p> 6113 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 6114 1.1 mbalmer <pre>int luaL_checkoption (lua_State *L, 6115 1.2 lneto int arg, 6116 1.1 mbalmer const char *def, 6117 1.1 mbalmer const char *const lst[]);</pre> 6118 1.1 mbalmer 6119 1.1 mbalmer <p> 6120 1.2 lneto Checks whether the function argument <code>arg</code> is a string and 6121 1.1 mbalmer searches for this string in the array <code>lst</code> 6122 1.1 mbalmer (which must be NULL-terminated). 6123 1.1 mbalmer Returns the index in the array where the string was found. 6124 1.1 mbalmer Raises an error if the argument is not a string or 6125 1.1 mbalmer if the string cannot be found. 6126 1.1 mbalmer 6127 1.1 mbalmer 6128 1.1 mbalmer <p> 6129 1.1 mbalmer If <code>def</code> is not <code>NULL</code>, 6130 1.1 mbalmer the function uses <code>def</code> as a default value when 6131 1.2 lneto there is no argument <code>arg</code> or when this argument is <b>nil</b>. 6132 1.1 mbalmer 6133 1.1 mbalmer 6134 1.1 mbalmer <p> 6135 1.1 mbalmer This is a useful function for mapping strings to C enums. 6136 1.1 mbalmer (The usual convention in Lua libraries is 6137 1.1 mbalmer to use strings instead of numbers to select options.) 6138 1.1 mbalmer 6139 1.1 mbalmer 6140 1.1 mbalmer 6141 1.1 mbalmer 6142 1.1 mbalmer 6143 1.1 mbalmer <hr><h3><a name="luaL_checkstack"><code>luaL_checkstack</code></a></h3><p> 6144 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 6145 1.1 mbalmer <pre>void luaL_checkstack (lua_State *L, int sz, const char *msg);</pre> 6146 1.1 mbalmer 6147 1.1 mbalmer <p> 6148 1.1 mbalmer Grows the stack size to <code>top + sz</code> elements, 6149 1.1 mbalmer raising an error if the stack cannot grow to that size. 6150 1.2 lneto <code>msg</code> is an additional text to go into the error message 6151 1.2 lneto (or <code>NULL</code> for no additional text). 6152 1.1 mbalmer 6153 1.1 mbalmer 6154 1.1 mbalmer 6155 1.1 mbalmer 6156 1.1 mbalmer 6157 1.1 mbalmer <hr><h3><a name="luaL_checkstring"><code>luaL_checkstring</code></a></h3><p> 6158 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 6159 1.2 lneto <pre>const char *luaL_checkstring (lua_State *L, int arg);</pre> 6160 1.1 mbalmer 6161 1.1 mbalmer <p> 6162 1.2 lneto Checks whether the function argument <code>arg</code> is a string 6163 1.1 mbalmer and returns this string. 6164 1.1 mbalmer 6165 1.1 mbalmer 6166 1.1 mbalmer <p> 6167 1.1 mbalmer This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, 6168 1.1 mbalmer so all conversions and caveats of that function apply here. 6169 1.1 mbalmer 6170 1.1 mbalmer 6171 1.1 mbalmer 6172 1.1 mbalmer 6173 1.1 mbalmer 6174 1.1 mbalmer <hr><h3><a name="luaL_checktype"><code>luaL_checktype</code></a></h3><p> 6175 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 6176 1.2 lneto <pre>void luaL_checktype (lua_State *L, int arg, int t);</pre> 6177 1.1 mbalmer 6178 1.1 mbalmer <p> 6179 1.2 lneto Checks whether the function argument <code>arg</code> has type <code>t</code>. 6180 1.1 mbalmer See <a href="#lua_type"><code>lua_type</code></a> for the encoding of types for <code>t</code>. 6181 1.1 mbalmer 6182 1.1 mbalmer 6183 1.1 mbalmer 6184 1.1 mbalmer 6185 1.1 mbalmer 6186 1.1 mbalmer <hr><h3><a name="luaL_checkudata"><code>luaL_checkudata</code></a></h3><p> 6187 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 6188 1.2 lneto <pre>void *luaL_checkudata (lua_State *L, int arg, const char *tname);</pre> 6189 1.2 lneto 6190 1.2 lneto <p> 6191 1.2 lneto Checks whether the function argument <code>arg</code> is a userdata 6192 1.2 lneto of the type <code>tname</code> (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>) and 6193 1.2 lneto returns the userdata address (see <a href="#lua_touserdata"><code>lua_touserdata</code></a>). 6194 1.2 lneto 6195 1.2 lneto 6196 1.2 lneto 6197 1.2 lneto 6198 1.2 lneto 6199 1.2 lneto <hr><h3><a name="luaL_checkunsigned"><code>luaL_checkunsigned</code></a></h3><p> 6200 1.2 lneto <span class="apii">[-0, +0, <em>v</em>]</span> 6201 1.2 lneto <pre>lua_Unsigned luaL_checkunsigned (lua_State *L, int arg);</pre> 6202 1.2 lneto 6203 1.2 lneto <p> 6204 1.2 lneto Checks whether the function argument <code>arg</code> is a number 6205 1.2 lneto and returns this number converted to a <a href="#lua_Unsigned"><code>lua_Unsigned</code></a>. 6206 1.2 lneto 6207 1.2 lneto 6208 1.2 lneto 6209 1.2 lneto 6210 1.2 lneto 6211 1.2 lneto <hr><h3><a name="luaL_checkversion"><code>luaL_checkversion</code></a></h3><p> 6212 1.2 lneto <span class="apii">[-0, +0, –]</span> 6213 1.2 lneto <pre>void luaL_checkversion (lua_State *L);</pre> 6214 1.1 mbalmer 6215 1.1 mbalmer <p> 6216 1.2 lneto Checks whether the core running the call, 6217 1.2 lneto the core that created the Lua state, 6218 1.2 lneto and the code making the call are all using the same version of Lua. 6219 1.2 lneto Also checks whether the core running the call 6220 1.2 lneto and the core that created the Lua state 6221 1.2 lneto are using the same address space. 6222 1.1 mbalmer 6223 1.1 mbalmer 6224 1.1 mbalmer 6225 1.1 mbalmer 6226 1.1 mbalmer 6227 1.1 mbalmer <hr><h3><a name="luaL_dofile"><code>luaL_dofile</code></a></h3><p> 6228 1.2 lneto <span class="apii">[-0, +?, <em>e</em>]</span> 6229 1.1 mbalmer <pre>int luaL_dofile (lua_State *L, const char *filename);</pre> 6230 1.1 mbalmer 6231 1.1 mbalmer <p> 6232 1.1 mbalmer Loads and runs the given file. 6233 1.1 mbalmer It is defined as the following macro: 6234 1.1 mbalmer 6235 1.1 mbalmer <pre> 6236 1.1 mbalmer (luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0)) 6237 1.1 mbalmer </pre><p> 6238 1.2 lneto It returns false if there are no errors 6239 1.2 lneto or true in case of errors. 6240 1.1 mbalmer 6241 1.1 mbalmer 6242 1.1 mbalmer 6243 1.1 mbalmer 6244 1.1 mbalmer 6245 1.1 mbalmer <hr><h3><a name="luaL_dostring"><code>luaL_dostring</code></a></h3><p> 6246 1.2 lneto <span class="apii">[-0, +?, –]</span> 6247 1.1 mbalmer <pre>int luaL_dostring (lua_State *L, const char *str);</pre> 6248 1.1 mbalmer 6249 1.1 mbalmer <p> 6250 1.1 mbalmer Loads and runs the given string. 6251 1.1 mbalmer It is defined as the following macro: 6252 1.1 mbalmer 6253 1.1 mbalmer <pre> 6254 1.1 mbalmer (luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0)) 6255 1.1 mbalmer </pre><p> 6256 1.2 lneto It returns false if there are no errors 6257 1.2 lneto or true in case of errors. 6258 1.1 mbalmer 6259 1.1 mbalmer 6260 1.1 mbalmer 6261 1.1 mbalmer 6262 1.1 mbalmer 6263 1.1 mbalmer <hr><h3><a name="luaL_error"><code>luaL_error</code></a></h3><p> 6264 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 6265 1.1 mbalmer <pre>int luaL_error (lua_State *L, const char *fmt, ...);</pre> 6266 1.1 mbalmer 6267 1.1 mbalmer <p> 6268 1.1 mbalmer Raises an error. 6269 1.2 lneto The error message format is given by <code>fmt</code> 6270 1.2 lneto plus any extra arguments, 6271 1.2 lneto following the same rules of <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>. 6272 1.2 lneto It also adds at the beginning of the message the file name and 6273 1.2 lneto the line number where the error occurred, 6274 1.2 lneto if this information is available. 6275 1.2 lneto 6276 1.2 lneto 6277 1.2 lneto <p> 6278 1.2 lneto This function never returns, 6279 1.2 lneto but it is an idiom to use it in C functions 6280 1.2 lneto as <code>return luaL_error(<em>args</em>)</code>. 6281 1.2 lneto 6282 1.2 lneto 6283 1.2 lneto 6284 1.2 lneto 6285 1.2 lneto 6286 1.2 lneto <hr><h3><a name="luaL_execresult"><code>luaL_execresult</code></a></h3><p> 6287 1.2 lneto <span class="apii">[-0, +3, <em>e</em>]</span> 6288 1.2 lneto <pre>int luaL_execresult (lua_State *L, int stat);</pre> 6289 1.2 lneto 6290 1.2 lneto <p> 6291 1.2 lneto This function produces the return values for 6292 1.2 lneto process-related functions in the standard library 6293 1.2 lneto (<a href="#pdf-os.execute"><code>os.execute</code></a> and <a href="#pdf-io.close"><code>io.close</code></a>). 6294 1.2 lneto 6295 1.2 lneto 6296 1.2 lneto 6297 1.2 lneto 6298 1.1 mbalmer 6299 1.2 lneto <hr><h3><a name="luaL_fileresult"><code>luaL_fileresult</code></a></h3><p> 6300 1.2 lneto <span class="apii">[-0, +(1|3), <em>e</em>]</span> 6301 1.2 lneto <pre>int luaL_fileresult (lua_State *L, int stat, const char *fname);</pre> 6302 1.1 mbalmer 6303 1.1 mbalmer <p> 6304 1.2 lneto This function produces the return values for 6305 1.2 lneto file-related functions in the standard library 6306 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.). 6307 1.1 mbalmer 6308 1.1 mbalmer 6309 1.1 mbalmer 6310 1.1 mbalmer 6311 1.1 mbalmer 6312 1.1 mbalmer <hr><h3><a name="luaL_getmetafield"><code>luaL_getmetafield</code></a></h3><p> 6313 1.2 lneto <span class="apii">[-0, +(0|1), <em>e</em>]</span> 6314 1.1 mbalmer <pre>int luaL_getmetafield (lua_State *L, int obj, const char *e);</pre> 6315 1.1 mbalmer 6316 1.1 mbalmer <p> 6317 1.1 mbalmer Pushes onto the stack the field <code>e</code> from the metatable 6318 1.1 mbalmer of the object at index <code>obj</code>. 6319 1.1 mbalmer If the object does not have a metatable, 6320 1.1 mbalmer or if the metatable does not have this field, 6321 1.2 lneto returns false and pushes nothing. 6322 1.1 mbalmer 6323 1.1 mbalmer 6324 1.1 mbalmer 6325 1.1 mbalmer 6326 1.1 mbalmer 6327 1.1 mbalmer <hr><h3><a name="luaL_getmetatable"><code>luaL_getmetatable</code></a></h3><p> 6328 1.2 lneto <span class="apii">[-0, +1, –]</span> 6329 1.1 mbalmer <pre>void luaL_getmetatable (lua_State *L, const char *tname);</pre> 6330 1.1 mbalmer 6331 1.1 mbalmer <p> 6332 1.1 mbalmer Pushes onto the stack the metatable associated with name <code>tname</code> 6333 1.1 mbalmer in the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). 6334 1.1 mbalmer 6335 1.1 mbalmer 6336 1.1 mbalmer 6337 1.1 mbalmer 6338 1.1 mbalmer 6339 1.2 lneto <hr><h3><a name="luaL_getsubtable"><code>luaL_getsubtable</code></a></h3><p> 6340 1.2 lneto <span class="apii">[-0, +1, <em>e</em>]</span> 6341 1.2 lneto <pre>int luaL_getsubtable (lua_State *L, int idx, const char *fname);</pre> 6342 1.2 lneto 6343 1.2 lneto <p> 6344 1.2 lneto Ensures that the value <code>t[fname]</code>, 6345 1.2 lneto where <code>t</code> is the value at index <code>idx</code>, 6346 1.2 lneto is a table, 6347 1.2 lneto and pushes that table onto the stack. 6348 1.2 lneto Returns true if it finds a previous table there 6349 1.2 lneto and false if it creates a new table. 6350 1.2 lneto 6351 1.2 lneto 6352 1.2 lneto 6353 1.2 lneto 6354 1.2 lneto 6355 1.1 mbalmer <hr><h3><a name="luaL_gsub"><code>luaL_gsub</code></a></h3><p> 6356 1.2 lneto <span class="apii">[-0, +1, <em>e</em>]</span> 6357 1.1 mbalmer <pre>const char *luaL_gsub (lua_State *L, 6358 1.1 mbalmer const char *s, 6359 1.1 mbalmer const char *p, 6360 1.1 mbalmer const char *r);</pre> 6361 1.1 mbalmer 6362 1.1 mbalmer <p> 6363 1.1 mbalmer Creates a copy of string <code>s</code> by replacing 6364 1.1 mbalmer any occurrence of the string <code>p</code> 6365 1.1 mbalmer with the string <code>r</code>. 6366 1.1 mbalmer Pushes the resulting string on the stack and returns it. 6367 1.1 mbalmer 6368 1.1 mbalmer 6369 1.1 mbalmer 6370 1.1 mbalmer 6371 1.1 mbalmer 6372 1.2 lneto <hr><h3><a name="luaL_len"><code>luaL_len</code></a></h3><p> 6373 1.2 lneto <span class="apii">[-0, +0, <em>e</em>]</span> 6374 1.2 lneto <pre>lua_Integer luaL_len (lua_State *L, int index);</pre> 6375 1.2 lneto 6376 1.2 lneto <p> 6377 1.2 lneto Returns the "length" of the value at the given index 6378 1.2 lneto as a number; 6379 1.2 lneto it is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">§3.4.7</a>). 6380 1.2 lneto Raises an error if the result of the operation is not an integer. 6381 1.2 lneto (This case only can happen through metamethods.) 6382 1.2 lneto 6383 1.2 lneto 6384 1.2 lneto 6385 1.2 lneto 6386 1.2 lneto 6387 1.1 mbalmer <hr><h3><a name="luaL_loadbuffer"><code>luaL_loadbuffer</code></a></h3><p> 6388 1.2 lneto <span class="apii">[-0, +1, –]</span> 6389 1.1 mbalmer <pre>int luaL_loadbuffer (lua_State *L, 6390 1.1 mbalmer const char *buff, 6391 1.1 mbalmer size_t sz, 6392 1.1 mbalmer const char *name);</pre> 6393 1.1 mbalmer 6394 1.1 mbalmer <p> 6395 1.2 lneto Equivalent to <a href="#luaL_loadbufferx"><code>luaL_loadbufferx</code></a> with <code>mode</code> equal to <code>NULL</code>. 6396 1.2 lneto 6397 1.2 lneto 6398 1.2 lneto 6399 1.2 lneto 6400 1.2 lneto 6401 1.2 lneto <hr><h3><a name="luaL_loadbufferx"><code>luaL_loadbufferx</code></a></h3><p> 6402 1.2 lneto <span class="apii">[-0, +1, –]</span> 6403 1.2 lneto <pre>int luaL_loadbufferx (lua_State *L, 6404 1.2 lneto const char *buff, 6405 1.2 lneto size_t sz, 6406 1.2 lneto const char *name, 6407 1.2 lneto const char *mode);</pre> 6408 1.2 lneto 6409 1.2 lneto <p> 6410 1.1 mbalmer Loads a buffer as a Lua chunk. 6411 1.1 mbalmer This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the 6412 1.1 mbalmer buffer pointed to by <code>buff</code> with size <code>sz</code>. 6413 1.1 mbalmer 6414 1.1 mbalmer 6415 1.1 mbalmer <p> 6416 1.1 mbalmer This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>. 6417 1.1 mbalmer <code>name</code> is the chunk name, 6418 1.1 mbalmer used for debug information and error messages. 6419 1.2 lneto The string <code>mode</code> works as in function <a href="#lua_load"><code>lua_load</code></a>. 6420 1.1 mbalmer 6421 1.1 mbalmer 6422 1.1 mbalmer 6423 1.1 mbalmer 6424 1.1 mbalmer 6425 1.1 mbalmer <hr><h3><a name="luaL_loadfile"><code>luaL_loadfile</code></a></h3><p> 6426 1.2 lneto <span class="apii">[-0, +1, <em>e</em>]</span> 6427 1.1 mbalmer <pre>int luaL_loadfile (lua_State *L, const char *filename);</pre> 6428 1.1 mbalmer 6429 1.1 mbalmer <p> 6430 1.2 lneto Equivalent to <a href="#luaL_loadfilex"><code>luaL_loadfilex</code></a> with <code>mode</code> equal to <code>NULL</code>. 6431 1.2 lneto 6432 1.2 lneto 6433 1.2 lneto 6434 1.2 lneto 6435 1.2 lneto 6436 1.2 lneto <hr><h3><a name="luaL_loadfilex"><code>luaL_loadfilex</code></a></h3><p> 6437 1.2 lneto <span class="apii">[-0, +1, <em>e</em>]</span> 6438 1.2 lneto <pre>int luaL_loadfilex (lua_State *L, const char *filename, 6439 1.2 lneto const char *mode);</pre> 6440 1.2 lneto 6441 1.2 lneto <p> 6442 1.1 mbalmer Loads a file as a Lua chunk. 6443 1.1 mbalmer This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the file 6444 1.1 mbalmer named <code>filename</code>. 6445 1.1 mbalmer If <code>filename</code> is <code>NULL</code>, 6446 1.1 mbalmer then it loads from the standard input. 6447 1.1 mbalmer The first line in the file is ignored if it starts with a <code>#</code>. 6448 1.1 mbalmer 6449 1.1 mbalmer 6450 1.1 mbalmer <p> 6451 1.2 lneto The string <code>mode</code> works as in function <a href="#lua_load"><code>lua_load</code></a>. 6452 1.2 lneto 6453 1.2 lneto 6454 1.2 lneto <p> 6455 1.1 mbalmer This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>, 6456 1.1 mbalmer but it has an extra error code <a name="pdf-LUA_ERRFILE"><code>LUA_ERRFILE</code></a> 6457 1.2 lneto if it cannot open/read the file or the file has a wrong mode. 6458 1.1 mbalmer 6459 1.1 mbalmer 6460 1.1 mbalmer <p> 6461 1.1 mbalmer As <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk; 6462 1.1 mbalmer it does not run it. 6463 1.1 mbalmer 6464 1.1 mbalmer 6465 1.1 mbalmer 6466 1.1 mbalmer 6467 1.1 mbalmer 6468 1.1 mbalmer <hr><h3><a name="luaL_loadstring"><code>luaL_loadstring</code></a></h3><p> 6469 1.2 lneto <span class="apii">[-0, +1, –]</span> 6470 1.1 mbalmer <pre>int luaL_loadstring (lua_State *L, const char *s);</pre> 6471 1.1 mbalmer 6472 1.1 mbalmer <p> 6473 1.1 mbalmer Loads a string as a Lua chunk. 6474 1.1 mbalmer This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in 6475 1.1 mbalmer the zero-terminated string <code>s</code>. 6476 1.1 mbalmer 6477 1.1 mbalmer 6478 1.1 mbalmer <p> 6479 1.1 mbalmer This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>. 6480 1.1 mbalmer 6481 1.1 mbalmer 6482 1.1 mbalmer <p> 6483 1.1 mbalmer Also as <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk; 6484 1.1 mbalmer it does not run it. 6485 1.1 mbalmer 6486 1.1 mbalmer 6487 1.1 mbalmer 6488 1.1 mbalmer 6489 1.1 mbalmer 6490 1.2 lneto <hr><h3><a name="luaL_newlib"><code>luaL_newlib</code></a></h3><p> 6491 1.2 lneto <span class="apii">[-0, +1, <em>e</em>]</span> 6492 1.2 lneto <pre>void luaL_newlib (lua_State *L, const luaL_Reg *l);</pre> 6493 1.2 lneto 6494 1.2 lneto <p> 6495 1.2 lneto Creates a new table and registers there 6496 1.2 lneto the functions in list <code>l</code>. 6497 1.2 lneto It is implemented as the following macro: 6498 1.2 lneto 6499 1.2 lneto <pre> 6500 1.2 lneto (luaL_newlibtable(L,l), luaL_setfuncs(L,l,0)) 6501 1.2 lneto </pre> 6502 1.2 lneto 6503 1.2 lneto 6504 1.2 lneto 6505 1.2 lneto 6506 1.2 lneto <hr><h3><a name="luaL_newlibtable"><code>luaL_newlibtable</code></a></h3><p> 6507 1.2 lneto <span class="apii">[-0, +1, <em>e</em>]</span> 6508 1.2 lneto <pre>void luaL_newlibtable (lua_State *L, const luaL_Reg l[]);</pre> 6509 1.2 lneto 6510 1.2 lneto <p> 6511 1.2 lneto Creates a new table with a size optimized 6512 1.2 lneto to store all entries in the array <code>l</code> 6513 1.2 lneto (but does not actually store them). 6514 1.2 lneto It is intended to be used in conjunction with <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a> 6515 1.2 lneto (see <a href="#luaL_newlib"><code>luaL_newlib</code></a>). 6516 1.2 lneto 6517 1.2 lneto 6518 1.2 lneto <p> 6519 1.2 lneto It is implemented as a macro. 6520 1.2 lneto The array <code>l</code> must be the actual array, 6521 1.2 lneto not a pointer to it. 6522 1.2 lneto 6523 1.2 lneto 6524 1.2 lneto 6525 1.2 lneto 6526 1.2 lneto 6527 1.1 mbalmer <hr><h3><a name="luaL_newmetatable"><code>luaL_newmetatable</code></a></h3><p> 6528 1.2 lneto <span class="apii">[-0, +1, <em>e</em>]</span> 6529 1.1 mbalmer <pre>int luaL_newmetatable (lua_State *L, const char *tname);</pre> 6530 1.1 mbalmer 6531 1.1 mbalmer <p> 6532 1.1 mbalmer If the registry already has the key <code>tname</code>, 6533 1.1 mbalmer returns 0. 6534 1.1 mbalmer Otherwise, 6535 1.1 mbalmer creates a new table to be used as a metatable for userdata, 6536 1.2 lneto adds to this new table the pair <code>__name = tname</code>, 6537 1.2 lneto adds to the registry the pair <code>[tname] = new table</code>, 6538 1.1 mbalmer and returns 1. 6539 1.1 mbalmer 6540 1.1 mbalmer 6541 1.1 mbalmer <p> 6542 1.1 mbalmer In both cases pushes onto the stack the final value associated 6543 1.1 mbalmer with <code>tname</code> in the registry. 6544 1.1 mbalmer 6545 1.1 mbalmer 6546 1.1 mbalmer 6547 1.1 mbalmer 6548 1.1 mbalmer 6549 1.1 mbalmer <hr><h3><a name="luaL_newstate"><code>luaL_newstate</code></a></h3><p> 6550 1.2 lneto <span class="apii">[-0, +0, –]</span> 6551 1.1 mbalmer <pre>lua_State *luaL_newstate (void);</pre> 6552 1.1 mbalmer 6553 1.1 mbalmer <p> 6554 1.1 mbalmer Creates a new Lua state. 6555 1.1 mbalmer It calls <a href="#lua_newstate"><code>lua_newstate</code></a> with an 6556 1.1 mbalmer allocator based on the standard C <code>realloc</code> function 6557 1.2 lneto and then sets a panic function (see <a href="#4.6">§4.6</a>) that prints 6558 1.1 mbalmer an error message to the standard error output in case of fatal 6559 1.1 mbalmer errors. 6560 1.1 mbalmer 6561 1.1 mbalmer 6562 1.1 mbalmer <p> 6563 1.1 mbalmer Returns the new state, 6564 1.1 mbalmer or <code>NULL</code> if there is a memory allocation error. 6565 1.1 mbalmer 6566 1.1 mbalmer 6567 1.1 mbalmer 6568 1.1 mbalmer 6569 1.1 mbalmer 6570 1.1 mbalmer <hr><h3><a name="luaL_openlibs"><code>luaL_openlibs</code></a></h3><p> 6571 1.2 lneto <span class="apii">[-0, +0, <em>e</em>]</span> 6572 1.1 mbalmer <pre>void luaL_openlibs (lua_State *L);</pre> 6573 1.1 mbalmer 6574 1.1 mbalmer <p> 6575 1.1 mbalmer Opens all standard Lua libraries into the given state. 6576 1.1 mbalmer 6577 1.1 mbalmer 6578 1.1 mbalmer 6579 1.1 mbalmer 6580 1.1 mbalmer 6581 1.1 mbalmer <hr><h3><a name="luaL_optint"><code>luaL_optint</code></a></h3><p> 6582 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 6583 1.2 lneto <pre>int luaL_optint (lua_State *L, int arg, int d);</pre> 6584 1.1 mbalmer 6585 1.1 mbalmer <p> 6586 1.2 lneto If the function argument <code>arg</code> is a number, 6587 1.1 mbalmer returns this number cast to an <code>int</code>. 6588 1.1 mbalmer If this argument is absent or is <b>nil</b>, 6589 1.1 mbalmer returns <code>d</code>. 6590 1.1 mbalmer Otherwise, raises an error. 6591 1.1 mbalmer 6592 1.1 mbalmer 6593 1.1 mbalmer 6594 1.1 mbalmer 6595 1.1 mbalmer 6596 1.1 mbalmer <hr><h3><a name="luaL_optinteger"><code>luaL_optinteger</code></a></h3><p> 6597 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 6598 1.1 mbalmer <pre>lua_Integer luaL_optinteger (lua_State *L, 6599 1.2 lneto int arg, 6600 1.1 mbalmer lua_Integer d);</pre> 6601 1.1 mbalmer 6602 1.1 mbalmer <p> 6603 1.2 lneto If the function argument <code>arg</code> is an integer 6604 1.2 lneto (or convertible to an integer), 6605 1.2 lneto returns this integer. 6606 1.1 mbalmer If this argument is absent or is <b>nil</b>, 6607 1.1 mbalmer returns <code>d</code>. 6608 1.1 mbalmer Otherwise, raises an error. 6609 1.1 mbalmer 6610 1.1 mbalmer 6611 1.1 mbalmer 6612 1.1 mbalmer 6613 1.1 mbalmer 6614 1.1 mbalmer <hr><h3><a name="luaL_optlong"><code>luaL_optlong</code></a></h3><p> 6615 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 6616 1.2 lneto <pre>long luaL_optlong (lua_State *L, int arg, long d);</pre> 6617 1.1 mbalmer 6618 1.1 mbalmer <p> 6619 1.2 lneto If the function argument <code>arg</code> is an integer 6620 1.2 lneto (or convertible to an integer), 6621 1.2 lneto returns this integer cast to a <code>long</code>. 6622 1.1 mbalmer If this argument is absent or is <b>nil</b>, 6623 1.1 mbalmer returns <code>d</code>. 6624 1.1 mbalmer Otherwise, raises an error. 6625 1.1 mbalmer 6626 1.1 mbalmer 6627 1.1 mbalmer 6628 1.1 mbalmer 6629 1.1 mbalmer 6630 1.1 mbalmer <hr><h3><a name="luaL_optlstring"><code>luaL_optlstring</code></a></h3><p> 6631 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 6632 1.1 mbalmer <pre>const char *luaL_optlstring (lua_State *L, 6633 1.2 lneto int arg, 6634 1.1 mbalmer const char *d, 6635 1.1 mbalmer size_t *l);</pre> 6636 1.1 mbalmer 6637 1.1 mbalmer <p> 6638 1.2 lneto If the function argument <code>arg</code> is a string, 6639 1.1 mbalmer returns this string. 6640 1.1 mbalmer If this argument is absent or is <b>nil</b>, 6641 1.1 mbalmer returns <code>d</code>. 6642 1.1 mbalmer Otherwise, raises an error. 6643 1.1 mbalmer 6644 1.1 mbalmer 6645 1.1 mbalmer <p> 6646 1.1 mbalmer If <code>l</code> is not <code>NULL</code>, 6647 1.2 lneto fills the position <code>*l</code> with the result's length. 6648 1.1 mbalmer 6649 1.1 mbalmer 6650 1.1 mbalmer 6651 1.1 mbalmer 6652 1.1 mbalmer 6653 1.1 mbalmer <hr><h3><a name="luaL_optnumber"><code>luaL_optnumber</code></a></h3><p> 6654 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 6655 1.2 lneto <pre>lua_Number luaL_optnumber (lua_State *L, int arg, lua_Number d);</pre> 6656 1.1 mbalmer 6657 1.1 mbalmer <p> 6658 1.2 lneto If the function argument <code>arg</code> is a number, 6659 1.1 mbalmer returns this number. 6660 1.1 mbalmer If this argument is absent or is <b>nil</b>, 6661 1.1 mbalmer returns <code>d</code>. 6662 1.1 mbalmer Otherwise, raises an error. 6663 1.1 mbalmer 6664 1.1 mbalmer 6665 1.1 mbalmer 6666 1.1 mbalmer 6667 1.1 mbalmer 6668 1.1 mbalmer <hr><h3><a name="luaL_optstring"><code>luaL_optstring</code></a></h3><p> 6669 1.1 mbalmer <span class="apii">[-0, +0, <em>v</em>]</span> 6670 1.1 mbalmer <pre>const char *luaL_optstring (lua_State *L, 6671 1.2 lneto int arg, 6672 1.1 mbalmer const char *d);</pre> 6673 1.1 mbalmer 6674 1.1 mbalmer <p> 6675 1.2 lneto If the function argument <code>arg</code> is a string, 6676 1.1 mbalmer returns this string. 6677 1.1 mbalmer If this argument is absent or is <b>nil</b>, 6678 1.1 mbalmer returns <code>d</code>. 6679 1.1 mbalmer Otherwise, raises an error. 6680 1.1 mbalmer 6681 1.1 mbalmer 6682 1.1 mbalmer 6683 1.1 mbalmer 6684 1.1 mbalmer 6685 1.2 lneto <hr><h3><a name="luaL_optunsigned"><code>luaL_optunsigned</code></a></h3><p> 6686 1.2 lneto <span class="apii">[-0, +0, <em>v</em>]</span> 6687 1.2 lneto <pre>lua_Unsigned luaL_optunsigned (lua_State *L, 6688 1.2 lneto int arg, 6689 1.2 lneto lua_Unsigned u);</pre> 6690 1.2 lneto 6691 1.2 lneto <p> 6692 1.2 lneto If the function argument <code>arg</code> is a number, 6693 1.2 lneto returns this number converted to a <a href="#lua_Unsigned"><code>lua_Unsigned</code></a>. 6694 1.2 lneto If this argument is absent or is <b>nil</b>, 6695 1.2 lneto returns <code>u</code>. 6696 1.2 lneto Otherwise, raises an error. 6697 1.2 lneto 6698 1.2 lneto 6699 1.2 lneto 6700 1.2 lneto 6701 1.2 lneto 6702 1.1 mbalmer <hr><h3><a name="luaL_prepbuffer"><code>luaL_prepbuffer</code></a></h3><p> 6703 1.2 lneto <span class="apii">[-?, +?, <em>e</em>]</span> 6704 1.1 mbalmer <pre>char *luaL_prepbuffer (luaL_Buffer *B);</pre> 6705 1.1 mbalmer 6706 1.1 mbalmer <p> 6707 1.2 lneto Equivalent to <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a> 6708 1.2 lneto with the predefined size <a name="pdf-LUAL_BUFFERSIZE"><code>LUAL_BUFFERSIZE</code></a>. 6709 1.2 lneto 6710 1.2 lneto 6711 1.2 lneto 6712 1.2 lneto 6713 1.2 lneto 6714 1.2 lneto <hr><h3><a name="luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a></h3><p> 6715 1.2 lneto <span class="apii">[-?, +?, <em>e</em>]</span> 6716 1.2 lneto <pre>char *luaL_prepbuffsize (luaL_Buffer *B, size_t sz);</pre> 6717 1.2 lneto 6718 1.2 lneto <p> 6719 1.2 lneto Returns an address to a space of size <code>sz</code> 6720 1.1 mbalmer where you can copy a string to be added to buffer <code>B</code> 6721 1.1 mbalmer (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). 6722 1.1 mbalmer After copying the string into this space you must call 6723 1.2 lneto <a href="#luaL_addsize"><code>luaL_addsize</code></a> with the size of the string to actually add 6724 1.1 mbalmer it to the buffer. 6725 1.1 mbalmer 6726 1.1 mbalmer 6727 1.1 mbalmer 6728 1.1 mbalmer 6729 1.1 mbalmer 6730 1.1 mbalmer <hr><h3><a name="luaL_pushresult"><code>luaL_pushresult</code></a></h3><p> 6731 1.2 lneto <span class="apii">[-?, +1, <em>e</em>]</span> 6732 1.1 mbalmer <pre>void luaL_pushresult (luaL_Buffer *B);</pre> 6733 1.1 mbalmer 6734 1.1 mbalmer <p> 6735 1.1 mbalmer Finishes the use of buffer <code>B</code> leaving the final string on 6736 1.1 mbalmer the top of the stack. 6737 1.1 mbalmer 6738 1.1 mbalmer 6739 1.1 mbalmer 6740 1.1 mbalmer 6741 1.1 mbalmer 6742 1.2 lneto <hr><h3><a name="luaL_pushresultsize"><code>luaL_pushresultsize</code></a></h3><p> 6743 1.2 lneto <span class="apii">[-?, +1, <em>e</em>]</span> 6744 1.2 lneto <pre>void luaL_pushresultsize (luaL_Buffer *B, size_t sz);</pre> 6745 1.2 lneto 6746 1.2 lneto <p> 6747 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>. 6748 1.2 lneto 6749 1.2 lneto 6750 1.2 lneto 6751 1.2 lneto 6752 1.2 lneto 6753 1.1 mbalmer <hr><h3><a name="luaL_ref"><code>luaL_ref</code></a></h3><p> 6754 1.2 lneto <span class="apii">[-1, +0, <em>e</em>]</span> 6755 1.1 mbalmer <pre>int luaL_ref (lua_State *L, int t);</pre> 6756 1.1 mbalmer 6757 1.1 mbalmer <p> 6758 1.1 mbalmer Creates and returns a <em>reference</em>, 6759 1.1 mbalmer in the table at index <code>t</code>, 6760 1.1 mbalmer for the object at the top of the stack (and pops the object). 6761 1.1 mbalmer 6762 1.1 mbalmer 6763 1.1 mbalmer <p> 6764 1.1 mbalmer A reference is a unique integer key. 6765 1.1 mbalmer As long as you do not manually add integer keys into table <code>t</code>, 6766 1.1 mbalmer <a href="#luaL_ref"><code>luaL_ref</code></a> ensures the uniqueness of the key it returns. 6767 1.1 mbalmer You can retrieve an object referred by reference <code>r</code> 6768 1.1 mbalmer by calling <code>lua_rawgeti(L, t, r)</code>. 6769 1.1 mbalmer Function <a href="#luaL_unref"><code>luaL_unref</code></a> frees a reference and its associated object. 6770 1.1 mbalmer 6771 1.1 mbalmer 6772 1.1 mbalmer <p> 6773 1.1 mbalmer If the object at the top of the stack is <b>nil</b>, 6774 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>. 6775 1.1 mbalmer The constant <a name="pdf-LUA_NOREF"><code>LUA_NOREF</code></a> is guaranteed to be different 6776 1.1 mbalmer from any reference returned by <a href="#luaL_ref"><code>luaL_ref</code></a>. 6777 1.1 mbalmer 6778 1.1 mbalmer 6779 1.1 mbalmer 6780 1.1 mbalmer 6781 1.1 mbalmer 6782 1.1 mbalmer <hr><h3><a name="luaL_Reg"><code>luaL_Reg</code></a></h3> 6783 1.1 mbalmer <pre>typedef struct luaL_Reg { 6784 1.1 mbalmer const char *name; 6785 1.1 mbalmer lua_CFunction func; 6786 1.1 mbalmer } luaL_Reg;</pre> 6787 1.1 mbalmer 6788 1.1 mbalmer <p> 6789 1.1 mbalmer Type for arrays of functions to be registered by 6790 1.2 lneto <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a>. 6791 1.1 mbalmer <code>name</code> is the function name and <code>func</code> is a pointer to 6792 1.1 mbalmer the function. 6793 1.1 mbalmer Any array of <a href="#luaL_Reg"><code>luaL_Reg</code></a> must end with an sentinel entry 6794 1.1 mbalmer in which both <code>name</code> and <code>func</code> are <code>NULL</code>. 6795 1.1 mbalmer 6796 1.1 mbalmer 6797 1.1 mbalmer 6798 1.1 mbalmer 6799 1.1 mbalmer 6800 1.2 lneto <hr><h3><a name="luaL_requiref"><code>luaL_requiref</code></a></h3><p> 6801 1.2 lneto <span class="apii">[-0, +1, <em>e</em>]</span> 6802 1.2 lneto <pre>void luaL_requiref (lua_State *L, const char *modname, 6803 1.2 lneto lua_CFunction openf, int glb);</pre> 6804 1.2 lneto 6805 1.2 lneto <p> 6806 1.2 lneto Calls function <code>openf</code> with string <code>modname</code> as an argument 6807 1.2 lneto and sets the call result in <code>package.loaded[modname]</code>, 6808 1.2 lneto as if that function has been called through <a href="#pdf-require"><code>require</code></a>. 6809 1.2 lneto 6810 1.2 lneto 6811 1.2 lneto <p> 6812 1.2 lneto If <code>glb</code> is true, 6813 1.2 lneto also stores the result into global <code>modname</code>. 6814 1.2 lneto 6815 1.2 lneto 6816 1.2 lneto <p> 6817 1.2 lneto Leaves a copy of that result on the stack. 6818 1.2 lneto 6819 1.2 lneto 6820 1.2 lneto 6821 1.2 lneto 6822 1.2 lneto 6823 1.2 lneto <hr><h3><a name="luaL_setfuncs"><code>luaL_setfuncs</code></a></h3><p> 6824 1.2 lneto <span class="apii">[-nup, +0, <em>e</em>]</span> 6825 1.2 lneto <pre>void luaL_setfuncs (lua_State *L, const luaL_Reg *l, int nup);</pre> 6826 1.2 lneto 6827 1.2 lneto <p> 6828 1.2 lneto Registers all functions in the array <code>l</code> 6829 1.2 lneto (see <a href="#luaL_Reg"><code>luaL_Reg</code></a>) into the table on the top of the stack 6830 1.2 lneto (below optional upvalues, see next). 6831 1.2 lneto 6832 1.1 mbalmer 6833 1.1 mbalmer <p> 6834 1.2 lneto When <code>nup</code> is not zero, 6835 1.2 lneto all functions are created sharing <code>nup</code> upvalues, 6836 1.2 lneto which must be previously pushed on the stack 6837 1.2 lneto on top of the library table. 6838 1.2 lneto These values are popped from the stack after the registration. 6839 1.1 mbalmer 6840 1.1 mbalmer 6841 1.2 lneto 6842 1.2 lneto 6843 1.2 lneto 6844 1.2 lneto <hr><h3><a name="luaL_setmetatable"><code>luaL_setmetatable</code></a></h3><p> 6845 1.2 lneto <span class="apii">[-0, +0, –]</span> 6846 1.2 lneto <pre>void luaL_setmetatable (lua_State *L, const char *tname);</pre> 6847 1.2 lneto 6848 1.2 lneto <p> 6849 1.2 lneto Sets the metatable of the object at the top of the stack 6850 1.2 lneto as the metatable associated with name <code>tname</code> 6851 1.2 lneto in the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). 6852 1.2 lneto 6853 1.2 lneto 6854 1.2 lneto 6855 1.2 lneto 6856 1.2 lneto 6857 1.2 lneto <hr><h3><a name="luaL_Stream"><code>luaL_Stream</code></a></h3> 6858 1.2 lneto <pre>typedef struct luaL_Stream { 6859 1.2 lneto FILE *f; 6860 1.2 lneto lua_CFunction closef; 6861 1.2 lneto } luaL_Stream;</pre> 6862 1.2 lneto 6863 1.1 mbalmer <p> 6864 1.2 lneto The standard representation for file handles, 6865 1.2 lneto which is used by the standard I/O library. 6866 1.1 mbalmer 6867 1.1 mbalmer 6868 1.1 mbalmer <p> 6869 1.2 lneto A file handle is implemented as a full userdata, 6870 1.2 lneto with a metatable called <code>LUA_FILEHANDLE</code>. 6871 1.2 lneto <code>LUA_FILEHANDLE</code> is a macro with the actual metatable's name. 6872 1.2 lneto The metatable is created by the I/O library 6873 1.2 lneto (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). 6874 1.2 lneto 6875 1.2 lneto 6876 1.2 lneto <p> 6877 1.2 lneto This userdata must start with the structure <code>luaL_Stream</code>; 6878 1.2 lneto it can contain other data after this initial structure. 6879 1.2 lneto Field <code>f</code> points to the corresponding C stream 6880 1.2 lneto (or it can be <code>NULL</code> to indicate an incompletely created handle). 6881 1.2 lneto Field <code>closef</code> points to a Lua function 6882 1.2 lneto that will be called to close the stream 6883 1.2 lneto when the handle is closed or collected; 6884 1.2 lneto this function receives the file handle as its sole argument and 6885 1.2 lneto must return either <b>true</b> (in case of success) 6886 1.2 lneto or <b>nil</b> plus an error message (in case of error). 6887 1.2 lneto Once Lua calls this field, 6888 1.2 lneto the field value is changed to <b>nil</b> to signal that the handle is closed. 6889 1.2 lneto 6890 1.1 mbalmer 6891 1.1 mbalmer 6892 1.2 lneto 6893 1.2 lneto 6894 1.2 lneto <hr><h3><a name="luaL_testudata"><code>luaL_testudata</code></a></h3><p> 6895 1.2 lneto <span class="apii">[-0, +0, <em>e</em>]</span> 6896 1.2 lneto <pre>void *luaL_testudata (lua_State *L, int arg, const char *tname);</pre> 6897 1.2 lneto 6898 1.1 mbalmer <p> 6899 1.2 lneto This function works like <a href="#luaL_checkudata"><code>luaL_checkudata</code></a>, 6900 1.2 lneto except that, when the test fails, 6901 1.2 lneto it returns <code>NULL</code> instead of raising an error. 6902 1.1 mbalmer 6903 1.1 mbalmer 6904 1.1 mbalmer 6905 1.1 mbalmer 6906 1.1 mbalmer 6907 1.2 lneto <hr><h3><a name="luaL_tolstring"><code>luaL_tolstring</code></a></h3><p> 6908 1.2 lneto <span class="apii">[-0, +1, <em>e</em>]</span> 6909 1.2 lneto <pre>const char *luaL_tolstring (lua_State *L, int idx, size_t *len);</pre> 6910 1.2 lneto 6911 1.2 lneto <p> 6912 1.2 lneto Converts any Lua value at the given index to a C string 6913 1.2 lneto in a reasonable format. 6914 1.2 lneto The resulting string is pushed onto the stack and also 6915 1.2 lneto returned by the function. 6916 1.2 lneto If <code>len</code> is not <code>NULL</code>, 6917 1.2 lneto the function also sets <code>*len</code> with the string length. 6918 1.2 lneto 6919 1.1 mbalmer 6920 1.1 mbalmer <p> 6921 1.2 lneto If the value has a metatable with a <code>"__tostring"</code> field, 6922 1.2 lneto then <code>luaL_tolstring</code> calls the corresponding metamethod 6923 1.2 lneto with the value as argument, 6924 1.2 lneto and uses the result of the call as its result. 6925 1.1 mbalmer 6926 1.1 mbalmer 6927 1.1 mbalmer 6928 1.1 mbalmer 6929 1.1 mbalmer 6930 1.2 lneto <hr><h3><a name="luaL_traceback"><code>luaL_traceback</code></a></h3><p> 6931 1.2 lneto <span class="apii">[-0, +1, <em>e</em>]</span> 6932 1.2 lneto <pre>void luaL_traceback (lua_State *L, lua_State *L1, const char *msg, 6933 1.2 lneto int level);</pre> 6934 1.1 mbalmer 6935 1.1 mbalmer <p> 6936 1.2 lneto Creates and pushes a traceback of the stack <code>L1</code>. 6937 1.2 lneto If <code>msg</code> is not <code>NULL</code> it is appended 6938 1.2 lneto at the beginning of the traceback. 6939 1.2 lneto The <code>level</code> parameter tells at which level 6940 1.2 lneto to start the traceback. 6941 1.1 mbalmer 6942 1.2 lneto 6943 1.2 lneto 6944 1.2 lneto 6945 1.2 lneto 6946 1.2 lneto <hr><h3><a name="luaL_typename"><code>luaL_typename</code></a></h3><p> 6947 1.2 lneto <span class="apii">[-0, +0, –]</span> 6948 1.2 lneto <pre>const char *luaL_typename (lua_State *L, int index);</pre> 6949 1.2 lneto 6950 1.2 lneto <p> 6951 1.2 lneto Returns the name of the type of the value at the given index. 6952 1.1 mbalmer 6953 1.1 mbalmer 6954 1.1 mbalmer 6955 1.1 mbalmer 6956 1.1 mbalmer 6957 1.1 mbalmer <hr><h3><a name="luaL_unref"><code>luaL_unref</code></a></h3><p> 6958 1.2 lneto <span class="apii">[-0, +0, –]</span> 6959 1.1 mbalmer <pre>void luaL_unref (lua_State *L, int t, int ref);</pre> 6960 1.1 mbalmer 6961 1.1 mbalmer <p> 6962 1.1 mbalmer Releases reference <code>ref</code> from the table at index <code>t</code> 6963 1.1 mbalmer (see <a href="#luaL_ref"><code>luaL_ref</code></a>). 6964 1.1 mbalmer The entry is removed from the table, 6965 1.1 mbalmer so that the referred object can be collected. 6966 1.1 mbalmer The reference <code>ref</code> is also freed to be used again. 6967 1.1 mbalmer 6968 1.1 mbalmer 6969 1.1 mbalmer <p> 6970 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>, 6971 1.1 mbalmer <a href="#luaL_unref"><code>luaL_unref</code></a> does nothing. 6972 1.1 mbalmer 6973 1.1 mbalmer 6974 1.1 mbalmer 6975 1.1 mbalmer 6976 1.1 mbalmer 6977 1.1 mbalmer <hr><h3><a name="luaL_where"><code>luaL_where</code></a></h3><p> 6978 1.2 lneto <span class="apii">[-0, +1, <em>e</em>]</span> 6979 1.1 mbalmer <pre>void luaL_where (lua_State *L, int lvl);</pre> 6980 1.1 mbalmer 6981 1.1 mbalmer <p> 6982 1.1 mbalmer Pushes onto the stack a string identifying the current position 6983 1.1 mbalmer of the control at level <code>lvl</code> in the call stack. 6984 1.1 mbalmer Typically this string has the following format: 6985 1.1 mbalmer 6986 1.1 mbalmer <pre> 6987 1.1 mbalmer <em>chunkname</em>:<em>currentline</em>: 6988 1.1 mbalmer </pre><p> 6989 1.1 mbalmer Level 0 is the running function, 6990 1.1 mbalmer level 1 is the function that called the running function, 6991 1.1 mbalmer etc. 6992 1.1 mbalmer 6993 1.1 mbalmer 6994 1.1 mbalmer <p> 6995 1.1 mbalmer This function is used to build a prefix for error messages. 6996 1.1 mbalmer 6997 1.1 mbalmer 6998 1.1 mbalmer 6999 1.1 mbalmer 7000 1.1 mbalmer 7001 1.1 mbalmer 7002 1.1 mbalmer 7003 1.2 lneto <h1>6 – <a name="6">Standard Libraries</a></h1> 7004 1.1 mbalmer 7005 1.1 mbalmer <p> 7006 1.1 mbalmer The standard Lua libraries provide useful functions 7007 1.1 mbalmer that are implemented directly through the C API. 7008 1.1 mbalmer Some of these functions provide essential services to the language 7009 1.1 mbalmer (e.g., <a href="#pdf-type"><code>type</code></a> and <a href="#pdf-getmetatable"><code>getmetatable</code></a>); 7010 1.1 mbalmer others provide access to "outside" services (e.g., I/O); 7011 1.1 mbalmer and others could be implemented in Lua itself, 7012 1.1 mbalmer but are quite useful or have critical performance requirements that 7013 1.1 mbalmer deserve an implementation in C (e.g., <a href="#pdf-table.sort"><code>table.sort</code></a>). 7014 1.1 mbalmer 7015 1.1 mbalmer 7016 1.1 mbalmer <p> 7017 1.1 mbalmer All libraries are implemented through the official C API 7018 1.1 mbalmer and are provided as separate C modules. 7019 1.1 mbalmer Currently, Lua has the following standard libraries: 7020 1.1 mbalmer 7021 1.1 mbalmer <ul> 7022 1.1 mbalmer 7023 1.2 lneto <li>basic library (<a href="#6.1">§6.1</a>);</li> 7024 1.1 mbalmer 7025 1.2 lneto <li>coroutine library (<a href="#6.2">§6.2</a>);</li> 7026 1.1 mbalmer 7027 1.2 lneto <li>package library (<a href="#6.3">§6.3</a>);</li> 7028 1.1 mbalmer 7029 1.2 lneto <li>string manipulation (<a href="#6.4">§6.4</a>);</li> 7030 1.1 mbalmer 7031 1.2 lneto <li>basic UTF-8 support (<a href="#6.5">§6.5</a>);</li> 7032 1.1 mbalmer 7033 1.2 lneto <li>table manipulation (<a href="#6.6">§6.6</a>);</li> 7034 1.1 mbalmer 7035 1.2 lneto <li>mathematical functions (<a href="#6.7">§6.7</a>) (sin, log, etc.);</li> 7036 1.1 mbalmer 7037 1.2 lneto <li>input and output (<a href="#6.8">§6.8</a>);</li> 7038 1.2 lneto 7039 1.2 lneto <li>operating system facilities (<a href="#6.9">§6.9</a>);</li> 7040 1.2 lneto 7041 1.2 lneto <li>debug facilities (<a href="#6.10">§6.10</a>).</li> 7042 1.1 mbalmer 7043 1.1 mbalmer </ul><p> 7044 1.2 lneto Except for the basic and the package libraries, 7045 1.1 mbalmer each library provides all its functions as fields of a global table 7046 1.1 mbalmer or as methods of its objects. 7047 1.1 mbalmer 7048 1.1 mbalmer 7049 1.1 mbalmer <p> 7050 1.1 mbalmer To have access to these libraries, 7051 1.1 mbalmer the C host program should call the <a href="#luaL_openlibs"><code>luaL_openlibs</code></a> function, 7052 1.1 mbalmer which opens all standard libraries. 7053 1.1 mbalmer Alternatively, 7054 1.2 lneto the host program can open them individually by using 7055 1.2 lneto <a href="#luaL_requiref"><code>luaL_requiref</code></a> to call 7056 1.1 mbalmer <a name="pdf-luaopen_base"><code>luaopen_base</code></a> (for the basic library), 7057 1.1 mbalmer <a name="pdf-luaopen_package"><code>luaopen_package</code></a> (for the package library), 7058 1.2 lneto <a name="pdf-luaopen_coroutine"><code>luaopen_coroutine</code></a> (for the coroutine library), 7059 1.1 mbalmer <a name="pdf-luaopen_string"><code>luaopen_string</code></a> (for the string library), 7060 1.1 mbalmer <a name="pdf-luaopen_table"><code>luaopen_table</code></a> (for the table library), 7061 1.1 mbalmer <a name="pdf-luaopen_math"><code>luaopen_math</code></a> (for the mathematical library), 7062 1.1 mbalmer <a name="pdf-luaopen_io"><code>luaopen_io</code></a> (for the I/O library), 7063 1.1 mbalmer <a name="pdf-luaopen_os"><code>luaopen_os</code></a> (for the Operating System library), 7064 1.1 mbalmer and <a name="pdf-luaopen_debug"><code>luaopen_debug</code></a> (for the debug library). 7065 1.2 lneto These functions are declared in <a name="pdf-lualib.h"><code>lualib.h</code></a>. 7066 1.1 mbalmer 7067 1.1 mbalmer 7068 1.1 mbalmer 7069 1.2 lneto <h2>6.1 – <a name="6.1">Basic Functions</a></h2> 7070 1.1 mbalmer 7071 1.1 mbalmer <p> 7072 1.2 lneto The basic library provides core functions to Lua. 7073 1.1 mbalmer If you do not include this library in your application, 7074 1.2 lneto you should check carefully whether you need to provide 7075 1.1 mbalmer implementations for some of its facilities. 7076 1.1 mbalmer 7077 1.1 mbalmer 7078 1.1 mbalmer <p> 7079 1.1 mbalmer <hr><h3><a name="pdf-assert"><code>assert (v [, message])</code></a></h3> 7080 1.2 lneto 7081 1.2 lneto 7082 1.2 lneto <p> 7083 1.2 lneto Calls <a href="#pdf-error"><code>error</code></a> if 7084 1.1 mbalmer the value of its argument <code>v</code> is false (i.e., <b>nil</b> or <b>false</b>); 7085 1.1 mbalmer otherwise, returns all its arguments. 7086 1.2 lneto In case of error, 7087 1.2 lneto <code>message</code> is the error object; 7088 1.2 lneto when absent, it defaults to "<code>assertion failed!</code>" 7089 1.1 mbalmer 7090 1.1 mbalmer 7091 1.1 mbalmer 7092 1.1 mbalmer 7093 1.1 mbalmer <p> 7094 1.2 lneto <hr><h3><a name="pdf-collectgarbage"><code>collectgarbage ([opt [, arg]])</code></a></h3> 7095 1.1 mbalmer 7096 1.1 mbalmer 7097 1.1 mbalmer <p> 7098 1.1 mbalmer This function is a generic interface to the garbage collector. 7099 1.1 mbalmer It performs different functions according to its first argument, <code>opt</code>: 7100 1.1 mbalmer 7101 1.1 mbalmer <ul> 7102 1.1 mbalmer 7103 1.2 lneto <li><b>"<code>collect</code>": </b> 7104 1.2 lneto performs a full garbage-collection cycle. 7105 1.2 lneto This is the default option. 7106 1.1 mbalmer </li> 7107 1.1 mbalmer 7108 1.2 lneto <li><b>"<code>stop</code>": </b> 7109 1.2 lneto stops automatic execution of the garbage collector. 7110 1.2 lneto The collector will run only when explicitly invoked, 7111 1.2 lneto until a call to restart it. 7112 1.1 mbalmer </li> 7113 1.1 mbalmer 7114 1.2 lneto <li><b>"<code>restart</code>": </b> 7115 1.2 lneto restarts automatic execution of the garbage collector. 7116 1.1 mbalmer </li> 7117 1.1 mbalmer 7118 1.2 lneto <li><b>"<code>count</code>": </b> 7119 1.2 lneto returns the total memory in use by Lua in Kbytes. 7120 1.2 lneto The value has a fractional part, 7121 1.2 lneto so that it multiplied by 1024 7122 1.2 lneto gives the exact number of bytes in use by Lua 7123 1.2 lneto (except for overflows). 7124 1.1 mbalmer </li> 7125 1.1 mbalmer 7126 1.2 lneto <li><b>"<code>step</code>": </b> 7127 1.1 mbalmer performs a garbage-collection step. 7128 1.2 lneto The step "size" is controlled by <code>arg</code>. 7129 1.2 lneto With a zero value, 7130 1.2 lneto the collector will perform one basic (indivisible) step. 7131 1.2 lneto For non-zero values, 7132 1.2 lneto the collector will perform as if that amount of memory 7133 1.2 lneto (in KBytes) had been allocated by Lua. 7134 1.1 mbalmer Returns <b>true</b> if the step finished a collection cycle. 7135 1.1 mbalmer </li> 7136 1.1 mbalmer 7137 1.2 lneto <li><b>"<code>setpause</code>": </b> 7138 1.1 mbalmer sets <code>arg</code> as the new value for the <em>pause</em> of 7139 1.2 lneto the collector (see <a href="#2.5">§2.5</a>). 7140 1.1 mbalmer Returns the previous value for <em>pause</em>. 7141 1.1 mbalmer </li> 7142 1.1 mbalmer 7143 1.2 lneto <li><b>"<code>setstepmul</code>": </b> 7144 1.1 mbalmer sets <code>arg</code> as the new value for the <em>step multiplier</em> of 7145 1.2 lneto the collector (see <a href="#2.5">§2.5</a>). 7146 1.1 mbalmer Returns the previous value for <em>step</em>. 7147 1.1 mbalmer </li> 7148 1.1 mbalmer 7149 1.2 lneto <li><b>"<code>isrunning</code>": </b> 7150 1.2 lneto returns a boolean that tells whether the collector is running 7151 1.2 lneto (i.e., not stopped). 7152 1.2 lneto </li> 7153 1.2 lneto 7154 1.1 mbalmer </ul> 7155 1.1 mbalmer 7156 1.1 mbalmer 7157 1.1 mbalmer 7158 1.1 mbalmer <p> 7159 1.2 lneto <hr><h3><a name="pdf-dofile"><code>dofile ([filename])</code></a></h3> 7160 1.1 mbalmer Opens the named file and executes its contents as a Lua chunk. 7161 1.1 mbalmer When called without arguments, 7162 1.1 mbalmer <code>dofile</code> executes the contents of the standard input (<code>stdin</code>). 7163 1.1 mbalmer Returns all values returned by the chunk. 7164 1.1 mbalmer In case of errors, <code>dofile</code> propagates the error 7165 1.1 mbalmer to its caller (that is, <code>dofile</code> does not run in protected mode). 7166 1.1 mbalmer 7167 1.1 mbalmer 7168 1.1 mbalmer 7169 1.1 mbalmer 7170 1.1 mbalmer <p> 7171 1.1 mbalmer <hr><h3><a name="pdf-error"><code>error (message [, level])</code></a></h3> 7172 1.1 mbalmer Terminates the last protected function called 7173 1.2 lneto and returns <code>message</code> as the error object. 7174 1.1 mbalmer Function <code>error</code> never returns. 7175 1.1 mbalmer 7176 1.1 mbalmer 7177 1.1 mbalmer <p> 7178 1.1 mbalmer Usually, <code>error</code> adds some information about the error position 7179 1.2 lneto at the beginning of the message, if the message is a string. 7180 1.1 mbalmer The <code>level</code> argument specifies how to get the error position. 7181 1.1 mbalmer With level 1 (the default), the error position is where the 7182 1.1 mbalmer <code>error</code> function was called. 7183 1.1 mbalmer Level 2 points the error to where the function 7184 1.1 mbalmer that called <code>error</code> was called; and so on. 7185 1.1 mbalmer Passing a level 0 avoids the addition of error position information 7186 1.1 mbalmer to the message. 7187 1.1 mbalmer 7188 1.1 mbalmer 7189 1.1 mbalmer 7190 1.1 mbalmer 7191 1.1 mbalmer <p> 7192 1.1 mbalmer <hr><h3><a name="pdf-_G"><code>_G</code></a></h3> 7193 1.1 mbalmer A global variable (not a function) that 7194 1.2 lneto holds the global environment (see <a href="#2.2">§2.2</a>). 7195 1.1 mbalmer Lua itself does not use this variable; 7196 1.1 mbalmer changing its value does not affect any environment, 7197 1.2 lneto nor vice versa. 7198 1.1 mbalmer 7199 1.1 mbalmer 7200 1.1 mbalmer 7201 1.1 mbalmer 7202 1.1 mbalmer <p> 7203 1.1 mbalmer <hr><h3><a name="pdf-getmetatable"><code>getmetatable (object)</code></a></h3> 7204 1.1 mbalmer 7205 1.1 mbalmer 7206 1.1 mbalmer <p> 7207 1.1 mbalmer If <code>object</code> does not have a metatable, returns <b>nil</b>. 7208 1.1 mbalmer Otherwise, 7209 1.1 mbalmer if the object's metatable has a <code>"__metatable"</code> field, 7210 1.1 mbalmer returns the associated value. 7211 1.1 mbalmer Otherwise, returns the metatable of the given object. 7212 1.1 mbalmer 7213 1.1 mbalmer 7214 1.1 mbalmer 7215 1.1 mbalmer 7216 1.1 mbalmer <p> 7217 1.1 mbalmer <hr><h3><a name="pdf-ipairs"><code>ipairs (t)</code></a></h3> 7218 1.1 mbalmer 7219 1.1 mbalmer 7220 1.1 mbalmer <p> 7221 1.2 lneto If <code>t</code> has a metamethod <code>__ipairs</code>, 7222 1.2 lneto calls it with <code>t</code> as argument and returns the first three 7223 1.2 lneto results from the call. 7224 1.2 lneto 7225 1.2 lneto 7226 1.2 lneto <p> 7227 1.2 lneto Otherwise, 7228 1.2 lneto returns three values: an iterator function, the table <code>t</code>, and 0, 7229 1.1 mbalmer so that the construction 7230 1.1 mbalmer 7231 1.1 mbalmer <pre> 7232 1.1 mbalmer for i,v in ipairs(t) do <em>body</em> end 7233 1.1 mbalmer </pre><p> 7234 1.2 lneto will iterate over the pairs (<code>1,t[1]</code>), (<code>2,t[2]</code>), ..., 7235 1.1 mbalmer up to the first integer key absent from the table. 7236 1.1 mbalmer 7237 1.1 mbalmer 7238 1.1 mbalmer 7239 1.1 mbalmer 7240 1.1 mbalmer <p> 7241 1.2 lneto <hr><h3><a name="pdf-load"><code>load (ld [, source [, mode [, env]]])</code></a></h3> 7242 1.1 mbalmer 7243 1.1 mbalmer 7244 1.1 mbalmer <p> 7245 1.2 lneto Loads a chunk. 7246 1.2 lneto 7247 1.2 lneto 7248 1.2 lneto <p> 7249 1.2 lneto If <code>ld</code> is a string, the chunk is this string. 7250 1.2 lneto If <code>ld</code> is a function, 7251 1.2 lneto <code>load</code> calls it repeatedly to get the chunk pieces. 7252 1.2 lneto Each call to <code>ld</code> must return a string that concatenates 7253 1.1 mbalmer with previous results. 7254 1.1 mbalmer A return of an empty string, <b>nil</b>, or no value signals the end of the chunk. 7255 1.1 mbalmer 7256 1.1 mbalmer 7257 1.1 mbalmer <p> 7258 1.2 lneto If there are no syntactic errors, 7259 1.1 mbalmer returns the compiled chunk as a function; 7260 1.1 mbalmer otherwise, returns <b>nil</b> plus the error message. 7261 1.1 mbalmer 7262 1.1 mbalmer 7263 1.1 mbalmer <p> 7264 1.2 lneto If the resulting function has upvalues, 7265 1.2 lneto the first upvalue is set to the value of <code>env</code>, 7266 1.2 lneto if that parameter is given, 7267 1.2 lneto or to the value of the global environment. 7268 1.2 lneto (When you load a main chunk, 7269 1.2 lneto the resulting function will always have exactly one upvalue, 7270 1.2 lneto the <code>_ENV</code> variable (see <a href="#2.2">§2.2</a>). 7271 1.2 lneto When you load a binary chunk created from a function (see <a href="#pdf-string.dump"><code>string.dump</code></a>), 7272 1.2 lneto the resulting function can have arbitrary upvalues.) 7273 1.1 mbalmer 7274 1.1 mbalmer 7275 1.2 lneto <p> 7276 1.2 lneto <code>source</code> is used as the source of the chunk for error messages 7277 1.2 lneto and debug information (see <a href="#4.9">§4.9</a>). 7278 1.2 lneto When absent, 7279 1.2 lneto it defaults to <code>ld</code>, if <code>ld</code> is a string, 7280 1.2 lneto or to "<code>=(load)</code>" otherwise. 7281 1.1 mbalmer 7282 1.1 mbalmer 7283 1.1 mbalmer <p> 7284 1.2 lneto The string <code>mode</code> controls whether the chunk can be text or binary 7285 1.2 lneto (that is, a precompiled chunk). 7286 1.2 lneto It may be the string "<code>b</code>" (only binary chunks), 7287 1.2 lneto "<code>t</code>" (only text chunks), 7288 1.2 lneto or "<code>bt</code>" (both binary and text). 7289 1.2 lneto The default is "<code>bt</code>". 7290 1.1 mbalmer 7291 1.1 mbalmer 7292 1.1 mbalmer <p> 7293 1.2 lneto Lua does not check the consistency of binary chunks. 7294 1.2 lneto Maliciously crafted binary chunks can crash 7295 1.2 lneto the interpreter. 7296 1.1 mbalmer 7297 1.1 mbalmer 7298 1.1 mbalmer 7299 1.1 mbalmer 7300 1.1 mbalmer <p> 7301 1.2 lneto <hr><h3><a name="pdf-loadfile"><code>loadfile ([filename [, mode [, env]]])</code></a></h3> 7302 1.1 mbalmer 7303 1.1 mbalmer 7304 1.1 mbalmer <p> 7305 1.1 mbalmer Similar to <a href="#pdf-load"><code>load</code></a>, 7306 1.2 lneto but gets the chunk from file <code>filename</code> 7307 1.2 lneto or from the standard input, 7308 1.2 lneto if no file name is given. 7309 1.1 mbalmer 7310 1.1 mbalmer 7311 1.1 mbalmer 7312 1.1 mbalmer 7313 1.1 mbalmer <p> 7314 1.1 mbalmer <hr><h3><a name="pdf-next"><code>next (table [, index])</code></a></h3> 7315 1.1 mbalmer 7316 1.1 mbalmer 7317 1.1 mbalmer <p> 7318 1.1 mbalmer Allows a program to traverse all fields of a table. 7319 1.1 mbalmer Its first argument is a table and its second argument 7320 1.1 mbalmer is an index in this table. 7321 1.1 mbalmer <code>next</code> returns the next index of the table 7322 1.1 mbalmer and its associated value. 7323 1.1 mbalmer When called with <b>nil</b> as its second argument, 7324 1.1 mbalmer <code>next</code> returns an initial index 7325 1.1 mbalmer and its associated value. 7326 1.1 mbalmer When called with the last index, 7327 1.1 mbalmer or with <b>nil</b> in an empty table, 7328 1.1 mbalmer <code>next</code> returns <b>nil</b>. 7329 1.1 mbalmer If the second argument is absent, then it is interpreted as <b>nil</b>. 7330 1.1 mbalmer In particular, 7331 1.1 mbalmer you can use <code>next(t)</code> to check whether a table is empty. 7332 1.1 mbalmer 7333 1.1 mbalmer 7334 1.1 mbalmer <p> 7335 1.1 mbalmer The order in which the indices are enumerated is not specified, 7336 1.1 mbalmer <em>even for numeric indices</em>. 7337 1.1 mbalmer (To traverse a table in numeric order, 7338 1.2 lneto use a numerical <b>for</b>.) 7339 1.1 mbalmer 7340 1.1 mbalmer 7341 1.1 mbalmer <p> 7342 1.2 lneto The behavior of <code>next</code> is undefined if, 7343 1.1 mbalmer during the traversal, 7344 1.1 mbalmer you assign any value to a non-existent field in the table. 7345 1.1 mbalmer You may however modify existing fields. 7346 1.1 mbalmer In particular, you may clear existing fields. 7347 1.1 mbalmer 7348 1.1 mbalmer 7349 1.1 mbalmer 7350 1.1 mbalmer 7351 1.1 mbalmer <p> 7352 1.1 mbalmer <hr><h3><a name="pdf-pairs"><code>pairs (t)</code></a></h3> 7353 1.1 mbalmer 7354 1.1 mbalmer 7355 1.1 mbalmer <p> 7356 1.2 lneto If <code>t</code> has a metamethod <code>__pairs</code>, 7357 1.2 lneto calls it with <code>t</code> as argument and returns the first three 7358 1.2 lneto results from the call. 7359 1.2 lneto 7360 1.2 lneto 7361 1.2 lneto <p> 7362 1.2 lneto Otherwise, 7363 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>, 7364 1.1 mbalmer so that the construction 7365 1.1 mbalmer 7366 1.1 mbalmer <pre> 7367 1.1 mbalmer for k,v in pairs(t) do <em>body</em> end 7368 1.1 mbalmer </pre><p> 7369 1.1 mbalmer will iterate over all key–value pairs of table <code>t</code>. 7370 1.1 mbalmer 7371 1.1 mbalmer 7372 1.1 mbalmer <p> 7373 1.1 mbalmer See function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying 7374 1.1 mbalmer the table during its traversal. 7375 1.1 mbalmer 7376 1.1 mbalmer 7377 1.1 mbalmer 7378 1.1 mbalmer 7379 1.1 mbalmer <p> 7380 1.2 lneto <hr><h3><a name="pdf-pcall"><code>pcall (f [, arg1, ···])</code></a></h3> 7381 1.1 mbalmer 7382 1.1 mbalmer 7383 1.1 mbalmer <p> 7384 1.1 mbalmer Calls function <code>f</code> with 7385 1.1 mbalmer the given arguments in <em>protected mode</em>. 7386 1.1 mbalmer This means that any error inside <code>f</code> is not propagated; 7387 1.1 mbalmer instead, <code>pcall</code> catches the error 7388 1.1 mbalmer and returns a status code. 7389 1.1 mbalmer Its first result is the status code (a boolean), 7390 1.1 mbalmer which is true if the call succeeds without errors. 7391 1.1 mbalmer In such case, <code>pcall</code> also returns all results from the call, 7392 1.1 mbalmer after this first result. 7393 1.1 mbalmer In case of any error, <code>pcall</code> returns <b>false</b> plus the error message. 7394 1.1 mbalmer 7395 1.1 mbalmer 7396 1.1 mbalmer 7397 1.1 mbalmer 7398 1.1 mbalmer <p> 7399 1.1 mbalmer <hr><h3><a name="pdf-print"><code>print (···)</code></a></h3> 7400 1.2 lneto Receives any number of arguments 7401 1.1 mbalmer and prints their values to <code>stdout</code>, 7402 1.2 lneto using the <a href="#pdf-tostring"><code>tostring</code></a> function to convert each argument to a string. 7403 1.1 mbalmer <code>print</code> is not intended for formatted output, 7404 1.1 mbalmer but only as a quick way to show a value, 7405 1.2 lneto for instance for debugging. 7406 1.2 lneto For complete control over the output, 7407 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>. 7408 1.1 mbalmer 7409 1.1 mbalmer 7410 1.1 mbalmer 7411 1.1 mbalmer 7412 1.1 mbalmer <p> 7413 1.1 mbalmer <hr><h3><a name="pdf-rawequal"><code>rawequal (v1, v2)</code></a></h3> 7414 1.1 mbalmer Checks whether <code>v1</code> is equal to <code>v2</code>, 7415 1.1 mbalmer without invoking any metamethod. 7416 1.1 mbalmer Returns a boolean. 7417 1.1 mbalmer 7418 1.1 mbalmer 7419 1.1 mbalmer 7420 1.1 mbalmer 7421 1.1 mbalmer <p> 7422 1.1 mbalmer <hr><h3><a name="pdf-rawget"><code>rawget (table, index)</code></a></h3> 7423 1.1 mbalmer Gets the real value of <code>table[index]</code>, 7424 1.1 mbalmer without invoking any metamethod. 7425 1.1 mbalmer <code>table</code> must be a table; 7426 1.1 mbalmer <code>index</code> may be any value. 7427 1.1 mbalmer 7428 1.1 mbalmer 7429 1.1 mbalmer 7430 1.1 mbalmer 7431 1.1 mbalmer <p> 7432 1.2 lneto <hr><h3><a name="pdf-rawlen"><code>rawlen (v)</code></a></h3> 7433 1.2 lneto Returns the length of the object <code>v</code>, 7434 1.2 lneto which must be a table or a string, 7435 1.2 lneto without invoking any metamethod. 7436 1.2 lneto Returns an integer. 7437 1.2 lneto 7438 1.2 lneto 7439 1.2 lneto 7440 1.2 lneto 7441 1.2 lneto <p> 7442 1.1 mbalmer <hr><h3><a name="pdf-rawset"><code>rawset (table, index, value)</code></a></h3> 7443 1.1 mbalmer Sets the real value of <code>table[index]</code> to <code>value</code>, 7444 1.1 mbalmer without invoking any metamethod. 7445 1.1 mbalmer <code>table</code> must be a table, 7446 1.2 lneto <code>index</code> any value different from <b>nil</b> and NaN, 7447 1.1 mbalmer and <code>value</code> any Lua value. 7448 1.1 mbalmer 7449 1.1 mbalmer 7450 1.1 mbalmer <p> 7451 1.1 mbalmer This function returns <code>table</code>. 7452 1.1 mbalmer 7453 1.1 mbalmer 7454 1.1 mbalmer 7455 1.1 mbalmer 7456 1.1 mbalmer <p> 7457 1.1 mbalmer <hr><h3><a name="pdf-select"><code>select (index, ···)</code></a></h3> 7458 1.1 mbalmer 7459 1.1 mbalmer 7460 1.1 mbalmer <p> 7461 1.1 mbalmer If <code>index</code> is a number, 7462 1.2 lneto returns all arguments after argument number <code>index</code>; 7463 1.2 lneto a negative number indexes from the end (-1 is the last argument). 7464 1.1 mbalmer Otherwise, <code>index</code> must be the string <code>"#"</code>, 7465 1.1 mbalmer and <code>select</code> returns the total number of extra arguments it received. 7466 1.1 mbalmer 7467 1.1 mbalmer 7468 1.1 mbalmer 7469 1.1 mbalmer 7470 1.1 mbalmer <p> 7471 1.1 mbalmer <hr><h3><a name="pdf-setmetatable"><code>setmetatable (table, metatable)</code></a></h3> 7472 1.1 mbalmer 7473 1.1 mbalmer 7474 1.1 mbalmer <p> 7475 1.1 mbalmer Sets the metatable for the given table. 7476 1.1 mbalmer (You cannot change the metatable of other types from Lua, only from C.) 7477 1.1 mbalmer If <code>metatable</code> is <b>nil</b>, 7478 1.1 mbalmer removes the metatable of the given table. 7479 1.1 mbalmer If the original metatable has a <code>"__metatable"</code> field, 7480 1.1 mbalmer raises an error. 7481 1.1 mbalmer 7482 1.1 mbalmer 7483 1.1 mbalmer <p> 7484 1.1 mbalmer This function returns <code>table</code>. 7485 1.1 mbalmer 7486 1.1 mbalmer 7487 1.1 mbalmer 7488 1.1 mbalmer 7489 1.1 mbalmer <p> 7490 1.1 mbalmer <hr><h3><a name="pdf-tonumber"><code>tonumber (e [, base])</code></a></h3> 7491 1.2 lneto 7492 1.2 lneto 7493 1.2 lneto <p> 7494 1.2 lneto When called with no <code>base</code>, 7495 1.2 lneto <code>tonumber</code> tries to convert its argument to a number. 7496 1.2 lneto If the argument is already a number or 7497 1.2 lneto a string convertible to a number, 7498 1.2 lneto then <code>tonumber</code> returns this number; 7499 1.1 mbalmer otherwise, it returns <b>nil</b>. 7500 1.1 mbalmer 7501 1.1 mbalmer 7502 1.1 mbalmer <p> 7503 1.2 lneto The conversion of strings can result in integers or floats, 7504 1.2 lneto according to the lexical conventions of Lua (see <a href="#3.1">§3.1</a>). 7505 1.2 lneto (The string may have leading and trailing spaces and a sign.) 7506 1.2 lneto 7507 1.2 lneto 7508 1.2 lneto <p> 7509 1.2 lneto When called with <code>base</code>, 7510 1.2 lneto then <code>e</code> must be a string to be interpreted as 7511 1.2 lneto an integer numeral in that base. 7512 1.1 mbalmer The base may be any integer between 2 and 36, inclusive. 7513 1.1 mbalmer In bases above 10, the letter '<code>A</code>' (in either upper or lower case) 7514 1.1 mbalmer represents 10, '<code>B</code>' represents 11, and so forth, 7515 1.1 mbalmer with '<code>Z</code>' representing 35. 7516 1.2 lneto If the string <code>e</code> is not a valid numeral in the given base, 7517 1.2 lneto the function returns <b>nil</b>. 7518 1.1 mbalmer 7519 1.1 mbalmer 7520 1.1 mbalmer 7521 1.1 mbalmer 7522 1.1 mbalmer <p> 7523 1.2 lneto <hr><h3><a name="pdf-tostring"><code>tostring (v)</code></a></h3> 7524 1.2 lneto Receives a value of any type and 7525 1.2 lneto converts it to a string in a human-readable format. 7526 1.2 lneto Floats always produce strings with some 7527 1.2 lneto floating-point indication (either a decimal dot or an exponent). 7528 1.2 lneto (For complete control of how numbers are converted, 7529 1.2 lneto use <a href="#pdf-string.format"><code>string.format</code></a>.) 7530 1.1 mbalmer 7531 1.1 mbalmer 7532 1.1 mbalmer <p> 7533 1.2 lneto If the metatable of <code>v</code> has a <code>"__tostring"</code> field, 7534 1.1 mbalmer then <code>tostring</code> calls the corresponding value 7535 1.2 lneto with <code>v</code> as argument, 7536 1.1 mbalmer and uses the result of the call as its result. 7537 1.1 mbalmer 7538 1.1 mbalmer 7539 1.1 mbalmer 7540 1.1 mbalmer 7541 1.1 mbalmer <p> 7542 1.1 mbalmer <hr><h3><a name="pdf-type"><code>type (v)</code></a></h3> 7543 1.1 mbalmer Returns the type of its only argument, coded as a string. 7544 1.1 mbalmer The possible results of this function are 7545 1.1 mbalmer "<code>nil</code>" (a string, not the value <b>nil</b>), 7546 1.1 mbalmer "<code>number</code>", 7547 1.1 mbalmer "<code>string</code>", 7548 1.1 mbalmer "<code>boolean</code>", 7549 1.1 mbalmer "<code>table</code>", 7550 1.1 mbalmer "<code>function</code>", 7551 1.1 mbalmer "<code>thread</code>", 7552 1.1 mbalmer and "<code>userdata</code>". 7553 1.1 mbalmer 7554 1.1 mbalmer 7555 1.1 mbalmer 7556 1.1 mbalmer 7557 1.1 mbalmer <p> 7558 1.1 mbalmer <hr><h3><a name="pdf-_VERSION"><code>_VERSION</code></a></h3> 7559 1.1 mbalmer A global variable (not a function) that 7560 1.1 mbalmer holds a string containing the current interpreter version. 7561 1.2 lneto The current value of this variable is "<code>Lua 5.3</code>". 7562 1.1 mbalmer 7563 1.1 mbalmer 7564 1.1 mbalmer 7565 1.1 mbalmer 7566 1.1 mbalmer <p> 7567 1.2 lneto <hr><h3><a name="pdf-xpcall"><code>xpcall (f, msgh [, arg1, ···])</code></a></h3> 7568 1.1 mbalmer 7569 1.1 mbalmer 7570 1.1 mbalmer <p> 7571 1.1 mbalmer This function is similar to <a href="#pdf-pcall"><code>pcall</code></a>, 7572 1.2 lneto except that it sets a new message handler <code>msgh</code>. 7573 1.1 mbalmer 7574 1.1 mbalmer 7575 1.1 mbalmer 7576 1.1 mbalmer 7577 1.1 mbalmer 7578 1.1 mbalmer 7579 1.1 mbalmer 7580 1.2 lneto <h2>6.2 – <a name="6.2">Coroutine Manipulation</a></h2> 7581 1.1 mbalmer 7582 1.1 mbalmer <p> 7583 1.1 mbalmer The operations related to coroutines comprise a sub-library of 7584 1.1 mbalmer the basic library and come inside the table <a name="pdf-coroutine"><code>coroutine</code></a>. 7585 1.2 lneto See <a href="#2.6">§2.6</a> for a general description of coroutines. 7586 1.1 mbalmer 7587 1.1 mbalmer 7588 1.1 mbalmer <p> 7589 1.1 mbalmer <hr><h3><a name="pdf-coroutine.create"><code>coroutine.create (f)</code></a></h3> 7590 1.1 mbalmer 7591 1.1 mbalmer 7592 1.1 mbalmer <p> 7593 1.1 mbalmer Creates a new coroutine, with body <code>f</code>. 7594 1.2 lneto <code>f</code> must be a Lua function. 7595 1.2 lneto Returns this new coroutine, 7596 1.2 lneto an object with type <code>"thread"</code>. 7597 1.2 lneto 7598 1.2 lneto 7599 1.2 lneto 7600 1.2 lneto 7601 1.2 lneto <p> 7602 1.2 lneto <hr><h3><a name="pdf-coroutine.isyieldable"><code>coroutine.isyieldable ()</code></a></h3> 7603 1.2 lneto 7604 1.2 lneto 7605 1.2 lneto <p> 7606 1.2 lneto Returns true when the running coroutine can yield. 7607 1.2 lneto 7608 1.2 lneto 7609 1.2 lneto <p> 7610 1.2 lneto A running coroutine is yieldable if it is not the main thread and 7611 1.2 lneto it is not inside a non-yieldable C function. 7612 1.1 mbalmer 7613 1.1 mbalmer 7614 1.1 mbalmer 7615 1.1 mbalmer 7616 1.1 mbalmer <p> 7617 1.1 mbalmer <hr><h3><a name="pdf-coroutine.resume"><code>coroutine.resume (co [, val1, ···])</code></a></h3> 7618 1.1 mbalmer 7619 1.1 mbalmer 7620 1.1 mbalmer <p> 7621 1.1 mbalmer Starts or continues the execution of coroutine <code>co</code>. 7622 1.1 mbalmer The first time you resume a coroutine, 7623 1.1 mbalmer it starts running its body. 7624 1.2 lneto The values <code>val1</code>, ... are passed 7625 1.1 mbalmer as the arguments to the body function. 7626 1.1 mbalmer If the coroutine has yielded, 7627 1.1 mbalmer <code>resume</code> restarts it; 7628 1.2 lneto the values <code>val1</code>, ... are passed 7629 1.1 mbalmer as the results from the yield. 7630 1.1 mbalmer 7631 1.1 mbalmer 7632 1.1 mbalmer <p> 7633 1.1 mbalmer If the coroutine runs without any errors, 7634 1.1 mbalmer <code>resume</code> returns <b>true</b> plus any values passed to <code>yield</code> 7635 1.2 lneto (when the coroutine yields) or any values returned by the body function 7636 1.2 lneto (when the coroutine terminates). 7637 1.1 mbalmer If there is any error, 7638 1.1 mbalmer <code>resume</code> returns <b>false</b> plus the error message. 7639 1.1 mbalmer 7640 1.1 mbalmer 7641 1.1 mbalmer 7642 1.1 mbalmer 7643 1.1 mbalmer <p> 7644 1.1 mbalmer <hr><h3><a name="pdf-coroutine.running"><code>coroutine.running ()</code></a></h3> 7645 1.1 mbalmer 7646 1.1 mbalmer 7647 1.1 mbalmer <p> 7648 1.2 lneto Returns the running coroutine plus a boolean, 7649 1.2 lneto true when the running coroutine is the main one. 7650 1.1 mbalmer 7651 1.1 mbalmer 7652 1.1 mbalmer 7653 1.1 mbalmer 7654 1.1 mbalmer <p> 7655 1.1 mbalmer <hr><h3><a name="pdf-coroutine.status"><code>coroutine.status (co)</code></a></h3> 7656 1.1 mbalmer 7657 1.1 mbalmer 7658 1.1 mbalmer <p> 7659 1.1 mbalmer Returns the status of coroutine <code>co</code>, as a string: 7660 1.1 mbalmer <code>"running"</code>, 7661 1.1 mbalmer if the coroutine is running (that is, it called <code>status</code>); 7662 1.1 mbalmer <code>"suspended"</code>, if the coroutine is suspended in a call to <code>yield</code>, 7663 1.1 mbalmer or if it has not started running yet; 7664 1.1 mbalmer <code>"normal"</code> if the coroutine is active but not running 7665 1.1 mbalmer (that is, it has resumed another coroutine); 7666 1.1 mbalmer and <code>"dead"</code> if the coroutine has finished its body function, 7667 1.1 mbalmer or if it has stopped with an error. 7668 1.1 mbalmer 7669 1.1 mbalmer 7670 1.1 mbalmer 7671 1.1 mbalmer 7672 1.1 mbalmer <p> 7673 1.1 mbalmer <hr><h3><a name="pdf-coroutine.wrap"><code>coroutine.wrap (f)</code></a></h3> 7674 1.1 mbalmer 7675 1.1 mbalmer 7676 1.1 mbalmer <p> 7677 1.1 mbalmer Creates a new coroutine, with body <code>f</code>. 7678 1.1 mbalmer <code>f</code> must be a Lua function. 7679 1.1 mbalmer Returns a function that resumes the coroutine each time it is called. 7680 1.1 mbalmer Any arguments passed to the function behave as the 7681 1.1 mbalmer extra arguments to <code>resume</code>. 7682 1.1 mbalmer Returns the same values returned by <code>resume</code>, 7683 1.1 mbalmer except the first boolean. 7684 1.1 mbalmer In case of error, propagates the error. 7685 1.1 mbalmer 7686 1.1 mbalmer 7687 1.1 mbalmer 7688 1.1 mbalmer 7689 1.1 mbalmer <p> 7690 1.1 mbalmer <hr><h3><a name="pdf-coroutine.yield"><code>coroutine.yield (···)</code></a></h3> 7691 1.1 mbalmer 7692 1.1 mbalmer 7693 1.1 mbalmer <p> 7694 1.1 mbalmer Suspends the execution of the calling coroutine. 7695 1.1 mbalmer Any arguments to <code>yield</code> are passed as extra results to <code>resume</code>. 7696 1.1 mbalmer 7697 1.1 mbalmer 7698 1.1 mbalmer 7699 1.1 mbalmer 7700 1.1 mbalmer 7701 1.1 mbalmer 7702 1.1 mbalmer 7703 1.2 lneto <h2>6.3 – <a name="6.3">Modules</a></h2> 7704 1.1 mbalmer 7705 1.1 mbalmer <p> 7706 1.1 mbalmer The package library provides basic 7707 1.2 lneto facilities for loading modules in Lua. 7708 1.2 lneto It exports one function directly in the global environment: 7709 1.2 lneto <a href="#pdf-require"><code>require</code></a>. 7710 1.1 mbalmer Everything else is exported in a table <a name="pdf-package"><code>package</code></a>. 7711 1.1 mbalmer 7712 1.1 mbalmer 7713 1.1 mbalmer <p> 7714 1.1 mbalmer <hr><h3><a name="pdf-require"><code>require (modname)</code></a></h3> 7715 1.1 mbalmer 7716 1.1 mbalmer 7717 1.1 mbalmer <p> 7718 1.1 mbalmer Loads the given module. 7719 1.1 mbalmer The function starts by looking into the <a href="#pdf-package.loaded"><code>package.loaded</code></a> table 7720 1.1 mbalmer to determine whether <code>modname</code> is already loaded. 7721 1.1 mbalmer If it is, then <code>require</code> returns the value stored 7722 1.1 mbalmer at <code>package.loaded[modname]</code>. 7723 1.1 mbalmer Otherwise, it tries to find a <em>loader</em> for the module. 7724 1.1 mbalmer 7725 1.1 mbalmer 7726 1.1 mbalmer <p> 7727 1.1 mbalmer To find a loader, 7728 1.2 lneto <code>require</code> is guided by the <a href="#pdf-package.searchers"><code>package.searchers</code></a> sequence. 7729 1.2 lneto By changing this sequence, 7730 1.1 mbalmer we can change how <code>require</code> looks for a module. 7731 1.1 mbalmer The following explanation is based on the default configuration 7732 1.2 lneto for <a href="#pdf-package.searchers"><code>package.searchers</code></a>. 7733 1.1 mbalmer 7734 1.1 mbalmer 7735 1.1 mbalmer <p> 7736 1.1 mbalmer First <code>require</code> queries <code>package.preload[modname]</code>. 7737 1.1 mbalmer If it has a value, 7738 1.2 lneto this value (which must be a function) is the loader. 7739 1.1 mbalmer Otherwise <code>require</code> searches for a Lua loader using the 7740 1.1 mbalmer path stored in <a href="#pdf-package.path"><code>package.path</code></a>. 7741 1.1 mbalmer If that also fails, it searches for a C loader using the 7742 1.1 mbalmer path stored in <a href="#pdf-package.cpath"><code>package.cpath</code></a>. 7743 1.1 mbalmer If that also fails, 7744 1.2 lneto it tries an <em>all-in-one</em> loader (see <a href="#pdf-package.searchers"><code>package.searchers</code></a>). 7745 1.1 mbalmer 7746 1.1 mbalmer 7747 1.1 mbalmer <p> 7748 1.1 mbalmer Once a loader is found, 7749 1.2 lneto <code>require</code> calls the loader with two arguments: 7750 1.2 lneto <code>modname</code> and an extra value dependent on how it got the loader. 7751 1.2 lneto (If the loader came from a file, 7752 1.2 lneto this extra value is the file name.) 7753 1.2 lneto If the loader returns any non-nil value, 7754 1.1 mbalmer <code>require</code> assigns the returned value to <code>package.loaded[modname]</code>. 7755 1.2 lneto If the loader does not return a non-nil value and 7756 1.1 mbalmer has not assigned any value to <code>package.loaded[modname]</code>, 7757 1.1 mbalmer then <code>require</code> assigns <b>true</b> to this entry. 7758 1.1 mbalmer In any case, <code>require</code> returns the 7759 1.1 mbalmer final value of <code>package.loaded[modname]</code>. 7760 1.1 mbalmer 7761 1.1 mbalmer 7762 1.1 mbalmer <p> 7763 1.1 mbalmer If there is any error loading or running the module, 7764 1.1 mbalmer or if it cannot find any loader for the module, 7765 1.2 lneto then <code>require</code> raises an error. 7766 1.2 lneto 7767 1.2 lneto 7768 1.2 lneto 7769 1.2 lneto 7770 1.2 lneto <p> 7771 1.2 lneto <hr><h3><a name="pdf-package.config"><code>package.config</code></a></h3> 7772 1.2 lneto 7773 1.2 lneto 7774 1.2 lneto <p> 7775 1.2 lneto A string describing some compile-time configurations for packages. 7776 1.2 lneto This string is a sequence of lines: 7777 1.2 lneto 7778 1.2 lneto <ul> 7779 1.2 lneto 7780 1.2 lneto <li>The first line is the directory separator string. 7781 1.2 lneto Default is '<code>\</code>' for Windows and '<code>/</code>' for all other systems.</li> 7782 1.1 mbalmer 7783 1.2 lneto <li>The second line is the character that separates templates in a path. 7784 1.2 lneto Default is '<code>;</code>'.</li> 7785 1.2 lneto 7786 1.2 lneto <li>The third line is the string that marks the 7787 1.2 lneto substitution points in a template. 7788 1.2 lneto Default is '<code>?</code>'.</li> 7789 1.2 lneto 7790 1.2 lneto <li>The fourth line is a string that, in a path in Windows, 7791 1.2 lneto is replaced by the executable's directory. 7792 1.2 lneto Default is '<code>!</code>'.</li> 7793 1.2 lneto 7794 1.2 lneto <li>The fifth line is a mark to ignore all text before it 7795 1.2 lneto when building the <code>luaopen_</code> function name. 7796 1.2 lneto Default is '<code>-</code>'.</li> 7797 1.2 lneto 7798 1.2 lneto </ul> 7799 1.1 mbalmer 7800 1.1 mbalmer 7801 1.1 mbalmer 7802 1.1 mbalmer <p> 7803 1.1 mbalmer <hr><h3><a name="pdf-package.cpath"><code>package.cpath</code></a></h3> 7804 1.1 mbalmer 7805 1.1 mbalmer 7806 1.1 mbalmer <p> 7807 1.1 mbalmer The path used by <a href="#pdf-require"><code>require</code></a> to search for a C loader. 7808 1.1 mbalmer 7809 1.1 mbalmer 7810 1.1 mbalmer <p> 7811 1.1 mbalmer Lua initializes the C path <a href="#pdf-package.cpath"><code>package.cpath</code></a> in the same way 7812 1.1 mbalmer it initializes the Lua path <a href="#pdf-package.path"><code>package.path</code></a>, 7813 1.2 lneto using the environment variable <a name="pdf-LUA_CPATH_5_3"><code>LUA_CPATH_5_3</code></a> 7814 1.2 lneto or the environment variable <a name="pdf-LUA_CPATH"><code>LUA_CPATH</code></a> 7815 1.1 mbalmer or a default path defined in <code>luaconf.h</code>. 7816 1.1 mbalmer 7817 1.1 mbalmer 7818 1.1 mbalmer 7819 1.1 mbalmer 7820 1.1 mbalmer <p> 7821 1.1 mbalmer <hr><h3><a name="pdf-package.loaded"><code>package.loaded</code></a></h3> 7822 1.1 mbalmer 7823 1.1 mbalmer 7824 1.1 mbalmer <p> 7825 1.1 mbalmer A table used by <a href="#pdf-require"><code>require</code></a> to control which 7826 1.1 mbalmer modules are already loaded. 7827 1.1 mbalmer When you require a module <code>modname</code> and 7828 1.1 mbalmer <code>package.loaded[modname]</code> is not false, 7829 1.1 mbalmer <a href="#pdf-require"><code>require</code></a> simply returns the value stored there. 7830 1.1 mbalmer 7831 1.1 mbalmer 7832 1.2 lneto <p> 7833 1.2 lneto This variable is only a reference to the real table; 7834 1.2 lneto assignments to this variable do not change the 7835 1.2 lneto table used by <a href="#pdf-require"><code>require</code></a>. 7836 1.2 lneto 7837 1.2 lneto 7838 1.2 lneto 7839 1.2 lneto 7840 1.2 lneto <p> 7841 1.2 lneto <hr><h3><a name="pdf-package.loadlib"><code>package.loadlib (libname, funcname)</code></a></h3> 7842 1.2 lneto 7843 1.2 lneto 7844 1.2 lneto <p> 7845 1.2 lneto Dynamically links the host program with the C library <code>libname</code>. 7846 1.2 lneto 7847 1.2 lneto 7848 1.2 lneto <p> 7849 1.2 lneto If <code>funcname</code> is "<code>*</code>", 7850 1.2 lneto then it only links with the library, 7851 1.2 lneto making the symbols exported by the library 7852 1.2 lneto available to other dynamically linked libraries. 7853 1.2 lneto Otherwise, 7854 1.2 lneto it looks for a function <code>funcname</code> inside the library 7855 1.2 lneto and returns this function as a C function. 7856 1.2 lneto So, <code>funcname</code> must follow the <a href="#lua_CFunction"><code>lua_CFunction</code></a> prototype 7857 1.2 lneto (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). 7858 1.2 lneto 7859 1.2 lneto 7860 1.2 lneto <p> 7861 1.2 lneto This is a low-level function. 7862 1.2 lneto It completely bypasses the package and module system. 7863 1.2 lneto Unlike <a href="#pdf-require"><code>require</code></a>, 7864 1.2 lneto it does not perform any path searching and 7865 1.2 lneto does not automatically adds extensions. 7866 1.2 lneto <code>libname</code> must be the complete file name of the C library, 7867 1.2 lneto including if necessary a path and an extension. 7868 1.2 lneto <code>funcname</code> must be the exact name exported by the C library 7869 1.2 lneto (which may depend on the C compiler and linker used). 7870 1.2 lneto 7871 1.2 lneto 7872 1.2 lneto <p> 7873 1.2 lneto This function is not supported by Standard C. 7874 1.2 lneto As such, it is only available on some platforms 7875 1.2 lneto (Windows, Linux, Mac OS X, Solaris, BSD, 7876 1.2 lneto plus other Unix systems that support the <code>dlfcn</code> standard). 7877 1.2 lneto 7878 1.2 lneto 7879 1.2 lneto 7880 1.2 lneto 7881 1.2 lneto <p> 7882 1.2 lneto <hr><h3><a name="pdf-package.path"><code>package.path</code></a></h3> 7883 1.2 lneto 7884 1.2 lneto 7885 1.2 lneto <p> 7886 1.2 lneto The path used by <a href="#pdf-require"><code>require</code></a> to search for a Lua loader. 7887 1.2 lneto 7888 1.2 lneto 7889 1.2 lneto <p> 7890 1.2 lneto At start-up, Lua initializes this variable with 7891 1.2 lneto the value of the environment variable <a name="pdf-LUA_PATH_5_3"><code>LUA_PATH_5_3</code></a> or 7892 1.2 lneto the environment variable <a name="pdf-LUA_PATH"><code>LUA_PATH</code></a> or 7893 1.2 lneto with a default path defined in <code>luaconf.h</code>, 7894 1.2 lneto if those environment variables are not defined. 7895 1.2 lneto Any "<code>;;</code>" in the value of the environment variable 7896 1.2 lneto is replaced by the default path. 7897 1.2 lneto 7898 1.2 lneto 7899 1.2 lneto 7900 1.2 lneto 7901 1.2 lneto <p> 7902 1.2 lneto <hr><h3><a name="pdf-package.preload"><code>package.preload</code></a></h3> 7903 1.2 lneto 7904 1.2 lneto 7905 1.2 lneto <p> 7906 1.2 lneto A table to store loaders for specific modules 7907 1.2 lneto (see <a href="#pdf-require"><code>require</code></a>). 7908 1.2 lneto 7909 1.2 lneto 7910 1.2 lneto <p> 7911 1.2 lneto This variable is only a reference to the real table; 7912 1.2 lneto assignments to this variable do not change the 7913 1.2 lneto table used by <a href="#pdf-require"><code>require</code></a>. 7914 1.2 lneto 7915 1.2 lneto 7916 1.1 mbalmer 7917 1.1 mbalmer 7918 1.1 mbalmer <p> 7919 1.2 lneto <hr><h3><a name="pdf-package.searchers"><code>package.searchers</code></a></h3> 7920 1.1 mbalmer 7921 1.1 mbalmer 7922 1.1 mbalmer <p> 7923 1.1 mbalmer A table used by <a href="#pdf-require"><code>require</code></a> to control how to load modules. 7924 1.1 mbalmer 7925 1.1 mbalmer 7926 1.1 mbalmer <p> 7927 1.1 mbalmer Each entry in this table is a <em>searcher function</em>. 7928 1.1 mbalmer When looking for a module, 7929 1.1 mbalmer <a href="#pdf-require"><code>require</code></a> calls each of these searchers in ascending order, 7930 1.1 mbalmer with the module name (the argument given to <a href="#pdf-require"><code>require</code></a>) as its 7931 1.1 mbalmer sole parameter. 7932 1.1 mbalmer The function can return another function (the module <em>loader</em>) 7933 1.2 lneto plus an extra value that will be passed to that loader, 7934 1.1 mbalmer or a string explaining why it did not find that module 7935 1.1 mbalmer (or <b>nil</b> if it has nothing to say). 7936 1.2 lneto 7937 1.2 lneto 7938 1.2 lneto <p> 7939 1.2 lneto Lua initializes this table with four searcher functions. 7940 1.1 mbalmer 7941 1.1 mbalmer 7942 1.1 mbalmer <p> 7943 1.1 mbalmer The first searcher simply looks for a loader in the 7944 1.1 mbalmer <a href="#pdf-package.preload"><code>package.preload</code></a> table. 7945 1.1 mbalmer 7946 1.1 mbalmer 7947 1.1 mbalmer <p> 7948 1.1 mbalmer The second searcher looks for a loader as a Lua library, 7949 1.1 mbalmer using the path stored at <a href="#pdf-package.path"><code>package.path</code></a>. 7950 1.2 lneto The search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. 7951 1.1 mbalmer 7952 1.1 mbalmer 7953 1.1 mbalmer <p> 7954 1.1 mbalmer The third searcher looks for a loader as a C library, 7955 1.1 mbalmer using the path given by the variable <a href="#pdf-package.cpath"><code>package.cpath</code></a>. 7956 1.2 lneto Again, 7957 1.2 lneto the search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. 7958 1.1 mbalmer For instance, 7959 1.1 mbalmer if the C path is the string 7960 1.1 mbalmer 7961 1.1 mbalmer <pre> 7962 1.1 mbalmer "./?.so;./?.dll;/usr/local/?/init.so" 7963 1.1 mbalmer </pre><p> 7964 1.1 mbalmer the searcher for module <code>foo</code> 7965 1.1 mbalmer will try to open the files <code>./foo.so</code>, <code>./foo.dll</code>, 7966 1.1 mbalmer and <code>/usr/local/foo/init.so</code>, in that order. 7967 1.1 mbalmer Once it finds a C library, 7968 1.1 mbalmer this searcher first uses a dynamic link facility to link the 7969 1.1 mbalmer application with the library. 7970 1.1 mbalmer Then it tries to find a C function inside the library to 7971 1.1 mbalmer be used as the loader. 7972 1.1 mbalmer The name of this C function is the string "<code>luaopen_</code>" 7973 1.1 mbalmer concatenated with a copy of the module name where each dot 7974 1.1 mbalmer is replaced by an underscore. 7975 1.1 mbalmer Moreover, if the module name has a hyphen, 7976 1.1 mbalmer its prefix up to (and including) the first hyphen is removed. 7977 1.1 mbalmer For instance, if the module name is <code>a.v1-b.c</code>, 7978 1.1 mbalmer the function name will be <code>luaopen_b_c</code>. 7979 1.1 mbalmer 7980 1.1 mbalmer 7981 1.1 mbalmer <p> 7982 1.1 mbalmer The fourth searcher tries an <em>all-in-one loader</em>. 7983 1.1 mbalmer It searches the C path for a library for 7984 1.1 mbalmer the root name of the given module. 7985 1.1 mbalmer For instance, when requiring <code>a.b.c</code>, 7986 1.1 mbalmer it will search for a C library for <code>a</code>. 7987 1.1 mbalmer If found, it looks into it for an open function for 7988 1.1 mbalmer the submodule; 7989 1.1 mbalmer in our example, that would be <code>luaopen_a_b_c</code>. 7990 1.1 mbalmer With this facility, a package can pack several C submodules 7991 1.1 mbalmer into one single library, 7992 1.1 mbalmer with each submodule keeping its original open function. 7993 1.1 mbalmer 7994 1.1 mbalmer 7995 1.1 mbalmer <p> 7996 1.2 lneto All searchers except the first one (preload) return as the extra value 7997 1.2 lneto the file name where the module was found, 7998 1.2 lneto as returned by <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. 7999 1.2 lneto The first searcher returns no extra value. 8000 1.1 mbalmer 8001 1.1 mbalmer 8002 1.1 mbalmer 8003 1.1 mbalmer 8004 1.1 mbalmer <p> 8005 1.2 lneto <hr><h3><a name="pdf-package.searchpath"><code>package.searchpath (name, path [, sep [, rep]])</code></a></h3> 8006 1.1 mbalmer 8007 1.1 mbalmer 8008 1.1 mbalmer <p> 8009 1.2 lneto Searches for the given <code>name</code> in the given <code>path</code>. 8010 1.1 mbalmer 8011 1.1 mbalmer 8012 1.1 mbalmer <p> 8013 1.2 lneto A path is a string containing a sequence of 8014 1.2 lneto <em>templates</em> separated by semicolons. 8015 1.2 lneto For each template, 8016 1.2 lneto the function replaces each interrogation mark (if any) 8017 1.2 lneto in the template with a copy of <code>name</code> 8018 1.2 lneto wherein all occurrences of <code>sep</code> 8019 1.2 lneto (a dot, by default) 8020 1.2 lneto were replaced by <code>rep</code> 8021 1.2 lneto (the system's directory separator, by default), 8022 1.2 lneto and then tries to open the resulting file name. 8023 1.1 mbalmer 8024 1.1 mbalmer 8025 1.1 mbalmer <p> 8026 1.2 lneto For instance, if the path is the string 8027 1.1 mbalmer 8028 1.2 lneto <pre> 8029 1.2 lneto "./?.lua;./?.lc;/usr/local/?/init.lua" 8030 1.2 lneto </pre><p> 8031 1.2 lneto the search for the name <code>foo.a</code> 8032 1.2 lneto will try to open the files 8033 1.2 lneto <code>./foo/a.lua</code>, <code>./foo/a.lc</code>, and 8034 1.2 lneto <code>/usr/local/foo/a/init.lua</code>, in that order. 8035 1.1 mbalmer 8036 1.1 mbalmer 8037 1.1 mbalmer <p> 8038 1.2 lneto Returns the resulting name of the first file that it can 8039 1.2 lneto open in read mode (after closing the file), 8040 1.2 lneto or <b>nil</b> plus an error message if none succeeds. 8041 1.2 lneto (This error message lists all file names it tried to open.) 8042 1.1 mbalmer 8043 1.1 mbalmer 8044 1.1 mbalmer 8045 1.1 mbalmer 8046 1.1 mbalmer 8047 1.1 mbalmer 8048 1.1 mbalmer 8049 1.2 lneto <h2>6.4 – <a name="6.4">String Manipulation</a></h2> 8050 1.1 mbalmer 8051 1.1 mbalmer <p> 8052 1.1 mbalmer This library provides generic functions for string manipulation, 8053 1.1 mbalmer such as finding and extracting substrings, and pattern matching. 8054 1.1 mbalmer When indexing a string in Lua, the first character is at position 1 8055 1.1 mbalmer (not at 0, as in C). 8056 1.1 mbalmer Indices are allowed to be negative and are interpreted as indexing backwards, 8057 1.1 mbalmer from the end of the string. 8058 1.1 mbalmer Thus, the last character is at position -1, and so on. 8059 1.1 mbalmer 8060 1.1 mbalmer 8061 1.1 mbalmer <p> 8062 1.1 mbalmer The string library provides all its functions inside the table 8063 1.1 mbalmer <a name="pdf-string"><code>string</code></a>. 8064 1.1 mbalmer It also sets a metatable for strings 8065 1.1 mbalmer where the <code>__index</code> field points to the <code>string</code> table. 8066 1.1 mbalmer Therefore, you can use the string functions in object-oriented style. 8067 1.2 lneto For instance, <code>string.byte(s,i)</code> 8068 1.1 mbalmer can be written as <code>s:byte(i)</code>. 8069 1.1 mbalmer 8070 1.1 mbalmer 8071 1.1 mbalmer <p> 8072 1.1 mbalmer The string library assumes one-byte character encodings. 8073 1.1 mbalmer 8074 1.1 mbalmer 8075 1.1 mbalmer <p> 8076 1.1 mbalmer <hr><h3><a name="pdf-string.byte"><code>string.byte (s [, i [, j]])</code></a></h3> 8077 1.1 mbalmer Returns the internal numerical codes of the characters <code>s[i]</code>, 8078 1.2 lneto <code>s[i+1]</code>, ..., <code>s[j]</code>. 8079 1.1 mbalmer The default value for <code>i</code> is 1; 8080 1.1 mbalmer the default value for <code>j</code> is <code>i</code>. 8081 1.2 lneto These indices are corrected 8082 1.2 lneto following the same rules of function <a href="#pdf-string.sub"><code>string.sub</code></a>. 8083 1.1 mbalmer 8084 1.1 mbalmer 8085 1.1 mbalmer <p> 8086 1.2 lneto Numerical codes are not necessarily portable across platforms. 8087 1.1 mbalmer 8088 1.1 mbalmer 8089 1.1 mbalmer 8090 1.1 mbalmer 8091 1.1 mbalmer <p> 8092 1.1 mbalmer <hr><h3><a name="pdf-string.char"><code>string.char (···)</code></a></h3> 8093 1.1 mbalmer Receives zero or more integers. 8094 1.1 mbalmer Returns a string with length equal to the number of arguments, 8095 1.1 mbalmer in which each character has the internal numerical code equal 8096 1.1 mbalmer to its corresponding argument. 8097 1.1 mbalmer 8098 1.1 mbalmer 8099 1.1 mbalmer <p> 8100 1.2 lneto Numerical codes are not necessarily portable across platforms. 8101 1.2 lneto 8102 1.2 lneto 8103 1.2 lneto 8104 1.2 lneto 8105 1.2 lneto <p> 8106 1.2 lneto <hr><h3><a name="pdf-string.dump"><code>string.dump (function [, strip])</code></a></h3> 8107 1.1 mbalmer 8108 1.1 mbalmer 8109 1.2 lneto <p> 8110 1.2 lneto Returns a string containing a binary representation 8111 1.2 lneto (a <em>binary chunk</em>) 8112 1.2 lneto of the given function, 8113 1.2 lneto so that a later <a href="#pdf-load"><code>load</code></a> on this string returns 8114 1.2 lneto a copy of the function (but with new upvalues). 8115 1.2 lneto If <code>strip</code> is a true value, 8116 1.2 lneto the binary representation is created without debug information 8117 1.2 lneto about the function 8118 1.2 lneto (local variable names, lines, etc.). 8119 1.2 lneto 8120 1.2 lneto 8121 1.2 lneto 8122 1.2 lneto 8123 1.2 lneto <p> 8124 1.2 lneto <hr><h3><a name="pdf-string.dumpfloat"><code>string.dumpfloat (n [, size [, endianness]])</code></a></h3> 8125 1.2 lneto Returns a string with the machine representation of float <code>n</code>, 8126 1.2 lneto with given size and endianness. 8127 1.2 lneto The <code>size</code> is the string "<code>f</code>" (single precision), 8128 1.2 lneto "<code>d</code>" (double precision), or "<code>n</code>", 8129 1.2 lneto which means the size of a <a href="#lua_Number"><code>lua_Number</code></a>; 8130 1.2 lneto its default is "<code>n</code>". 8131 1.2 lneto The endianness is the string "<code>l</code>" (little endian), "<code>b</code>" (big endian), 8132 1.2 lneto or "<code>n</code>" (native); 8133 1.2 lneto the default is the native endianness. 8134 1.2 lneto 8135 1.2 lneto 8136 1.2 lneto <p> 8137 1.2 lneto This function may not work correctly in architectures 8138 1.2 lneto with mixed endian. 8139 1.1 mbalmer 8140 1.1 mbalmer 8141 1.1 mbalmer <p> 8142 1.2 lneto <hr><h3><a name="pdf-string.dumpint"><code>string.dumpint (n [, size [, endianness]])</code></a></h3> 8143 1.2 lneto Returns a string with the two-complement representation of integer <code>n</code>, 8144 1.2 lneto with <code>size</code> bytes and given endianness. 8145 1.2 lneto The <code>size</code> can be any value from 1 to 12, 8146 1.2 lneto or 0, which means the size of a <a href="#lua_Integer"><code>lua_Integer</code></a> 8147 1.2 lneto (8 bytes in standard Lua); 8148 1.2 lneto its default is zero. 8149 1.2 lneto The endianness is the string "<code>l</code>" (little endian), "<code>b</code>" (big endian), 8150 1.2 lneto or "<code>n</code>" (native); 8151 1.2 lneto the default is the native endianness. 8152 1.1 mbalmer 8153 1.1 mbalmer 8154 1.1 mbalmer <p> 8155 1.2 lneto This function may not work correctly in architectures 8156 1.2 lneto with mixed endian or 8157 1.2 lneto that do not use a two-complement representation for integers. 8158 1.1 mbalmer 8159 1.1 mbalmer 8160 1.1 mbalmer 8161 1.1 mbalmer 8162 1.1 mbalmer <p> 8163 1.1 mbalmer <hr><h3><a name="pdf-string.find"><code>string.find (s, pattern [, init [, plain]])</code></a></h3> 8164 1.2 lneto 8165 1.2 lneto 8166 1.2 lneto <p> 8167 1.1 mbalmer Looks for the first match of 8168 1.1 mbalmer <code>pattern</code> in the string <code>s</code>. 8169 1.1 mbalmer If it finds a match, then <code>find</code> returns the indices of <code>s</code> 8170 1.1 mbalmer where this occurrence starts and ends; 8171 1.1 mbalmer otherwise, it returns <b>nil</b>. 8172 1.1 mbalmer A third, optional numerical argument <code>init</code> specifies 8173 1.1 mbalmer where to start the search; 8174 1.1 mbalmer its default value is 1 and can be negative. 8175 1.1 mbalmer A value of <b>true</b> as a fourth, optional argument <code>plain</code> 8176 1.1 mbalmer turns off the pattern matching facilities, 8177 1.1 mbalmer so the function does a plain "find substring" operation, 8178 1.2 lneto with no characters in <code>pattern</code> being considered magic. 8179 1.1 mbalmer Note that if <code>plain</code> is given, then <code>init</code> must be given as well. 8180 1.1 mbalmer 8181 1.1 mbalmer 8182 1.1 mbalmer <p> 8183 1.1 mbalmer If the pattern has captures, 8184 1.1 mbalmer then in a successful match 8185 1.1 mbalmer the captured values are also returned, 8186 1.1 mbalmer after the two indices. 8187 1.1 mbalmer 8188 1.1 mbalmer 8189 1.1 mbalmer 8190 1.1 mbalmer 8191 1.1 mbalmer <p> 8192 1.1 mbalmer <hr><h3><a name="pdf-string.format"><code>string.format (formatstring, ···)</code></a></h3> 8193 1.2 lneto 8194 1.2 lneto 8195 1.2 lneto <p> 8196 1.1 mbalmer Returns a formatted version of its variable number of arguments 8197 1.1 mbalmer following the description given in its first argument (which must be a string). 8198 1.2 lneto The format string follows the same rules as the ANSI C function <code>sprintf</code>. 8199 1.1 mbalmer The only differences are that the options/modifiers 8200 1.2 lneto <code>*</code>, <code>h</code>, <code>L</code>, <code>l</code>, <code>n</code>, 8201 1.2 lneto and <code>p</code> are not supported 8202 1.1 mbalmer and that there is an extra option, <code>q</code>. 8203 1.2 lneto The <code>q</code> option formats a string between double quotes, 8204 1.2 lneto using escape sequences when necessary to ensure that 8205 1.2 lneto it can safely be read back by the Lua interpreter. 8206 1.1 mbalmer For instance, the call 8207 1.1 mbalmer 8208 1.1 mbalmer <pre> 8209 1.1 mbalmer string.format('%q', 'a string with "quotes" and \n new line') 8210 1.1 mbalmer </pre><p> 8211 1.2 lneto may produce the string: 8212 1.1 mbalmer 8213 1.1 mbalmer <pre> 8214 1.1 mbalmer "a string with \"quotes\" and \ 8215 1.1 mbalmer new line" 8216 1.1 mbalmer </pre> 8217 1.1 mbalmer 8218 1.1 mbalmer <p> 8219 1.2 lneto Options 8220 1.2 lneto <code>A</code> and <code>a</code> (when available), 8221 1.2 lneto <code>E</code>, <code>e</code>, <code>f</code>, 8222 1.2 lneto <code>G</code>, and <code>g</code> all expect a number as argument. 8223 1.2 lneto Options <code>c</code>, <code>d</code>, 8224 1.2 lneto <code>i</code>, <code>o</code>, <code>u</code>, <code>X</code>, and <code>x</code> 8225 1.2 lneto expect an integer. 8226 1.2 lneto Option <code>q</code> expects a string; 8227 1.2 lneto option <code>s</code> expects a string without embedded zeros. 8228 1.2 lneto If the argument to option <code>s</code> is not a string, 8229 1.2 lneto it is converted to one following the same rules of <a href="#pdf-tostring"><code>tostring</code></a>. 8230 1.1 mbalmer 8231 1.1 mbalmer 8232 1.1 mbalmer 8233 1.1 mbalmer 8234 1.1 mbalmer <p> 8235 1.1 mbalmer <hr><h3><a name="pdf-string.gmatch"><code>string.gmatch (s, pattern)</code></a></h3> 8236 1.1 mbalmer Returns an iterator function that, 8237 1.1 mbalmer each time it is called, 8238 1.2 lneto returns the next captures from <code>pattern</code> over the string <code>s</code>. 8239 1.1 mbalmer If <code>pattern</code> specifies no captures, 8240 1.1 mbalmer then the whole match is produced in each call. 8241 1.1 mbalmer 8242 1.1 mbalmer 8243 1.1 mbalmer <p> 8244 1.1 mbalmer As an example, the following loop 8245 1.2 lneto will iterate over all the words from string <code>s</code>, 8246 1.2 lneto printing one per line: 8247 1.1 mbalmer 8248 1.1 mbalmer <pre> 8249 1.1 mbalmer s = "hello world from Lua" 8250 1.1 mbalmer for w in string.gmatch(s, "%a+") do 8251 1.1 mbalmer print(w) 8252 1.1 mbalmer end 8253 1.1 mbalmer </pre><p> 8254 1.1 mbalmer The next example collects all pairs <code>key=value</code> from the 8255 1.1 mbalmer given string into a table: 8256 1.1 mbalmer 8257 1.1 mbalmer <pre> 8258 1.1 mbalmer t = {} 8259 1.1 mbalmer s = "from=world, to=Lua" 8260 1.1 mbalmer for k, v in string.gmatch(s, "(%w+)=(%w+)") do 8261 1.1 mbalmer t[k] = v 8262 1.1 mbalmer end 8263 1.1 mbalmer </pre> 8264 1.1 mbalmer 8265 1.1 mbalmer <p> 8266 1.2 lneto For this function, a caret '<code>^</code>' at the start of a pattern does not 8267 1.1 mbalmer work as an anchor, as this would prevent the iteration. 8268 1.1 mbalmer 8269 1.1 mbalmer 8270 1.1 mbalmer 8271 1.1 mbalmer 8272 1.1 mbalmer <p> 8273 1.1 mbalmer <hr><h3><a name="pdf-string.gsub"><code>string.gsub (s, pattern, repl [, n])</code></a></h3> 8274 1.1 mbalmer Returns a copy of <code>s</code> 8275 1.1 mbalmer in which all (or the first <code>n</code>, if given) 8276 1.1 mbalmer occurrences of the <code>pattern</code> have been 8277 1.1 mbalmer replaced by a replacement string specified by <code>repl</code>, 8278 1.1 mbalmer which can be a string, a table, or a function. 8279 1.1 mbalmer <code>gsub</code> also returns, as its second value, 8280 1.1 mbalmer the total number of matches that occurred. 8281 1.2 lneto The name <code>gsub</code> comes from <em>Global SUBstitution</em>. 8282 1.1 mbalmer 8283 1.1 mbalmer 8284 1.1 mbalmer <p> 8285 1.1 mbalmer If <code>repl</code> is a string, then its value is used for replacement. 8286 1.1 mbalmer The character <code>%</code> works as an escape character: 8287 1.2 lneto any sequence in <code>repl</code> of the form <code>%<em>d</em></code>, 8288 1.2 lneto with <em>d</em> between 1 and 9, 8289 1.2 lneto stands for the value of the <em>d</em>-th captured substring. 8290 1.1 mbalmer The sequence <code>%0</code> stands for the whole match. 8291 1.1 mbalmer The sequence <code>%%</code> stands for a single <code>%</code>. 8292 1.1 mbalmer 8293 1.1 mbalmer 8294 1.1 mbalmer <p> 8295 1.1 mbalmer If <code>repl</code> is a table, then the table is queried for every match, 8296 1.2 lneto using the first capture as the key. 8297 1.1 mbalmer 8298 1.1 mbalmer 8299 1.1 mbalmer <p> 8300 1.1 mbalmer If <code>repl</code> is a function, then this function is called every time a 8301 1.1 mbalmer match occurs, with all captured substrings passed as arguments, 8302 1.2 lneto in order. 8303 1.2 lneto 8304 1.2 lneto 8305 1.2 lneto <p> 8306 1.2 lneto In any case, 8307 1.1 mbalmer if the pattern specifies no captures, 8308 1.2 lneto then it behaves as if the whole pattern was inside a capture. 8309 1.1 mbalmer 8310 1.1 mbalmer 8311 1.1 mbalmer <p> 8312 1.1 mbalmer If the value returned by the table query or by the function call 8313 1.1 mbalmer is a string or a number, 8314 1.1 mbalmer then it is used as the replacement string; 8315 1.1 mbalmer otherwise, if it is <b>false</b> or <b>nil</b>, 8316 1.1 mbalmer then there is no replacement 8317 1.1 mbalmer (that is, the original match is kept in the string). 8318 1.1 mbalmer 8319 1.1 mbalmer 8320 1.1 mbalmer <p> 8321 1.1 mbalmer Here are some examples: 8322 1.1 mbalmer 8323 1.1 mbalmer <pre> 8324 1.1 mbalmer x = string.gsub("hello world", "(%w+)", "%1 %1") 8325 1.1 mbalmer --> x="hello hello world world" 8326 1.1 mbalmer 8327 1.1 mbalmer x = string.gsub("hello world", "%w+", "%0 %0", 1) 8328 1.1 mbalmer --> x="hello hello world" 8329 1.1 mbalmer 8330 1.1 mbalmer x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1") 8331 1.1 mbalmer --> x="world hello Lua from" 8332 1.1 mbalmer 8333 1.1 mbalmer x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv) 8334 1.1 mbalmer --> x="home = /home/roberto, user = roberto" 8335 1.1 mbalmer 8336 1.1 mbalmer x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s) 8337 1.2 lneto return load(s)() 8338 1.1 mbalmer end) 8339 1.1 mbalmer --> x="4+5 = 9" 8340 1.1 mbalmer 8341 1.2 lneto local t = {name="lua", version="5.3"} 8342 1.1 mbalmer x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t) 8343 1.2 lneto --> x="lua-5.3.tar.gz" 8344 1.1 mbalmer </pre> 8345 1.1 mbalmer 8346 1.1 mbalmer 8347 1.1 mbalmer 8348 1.1 mbalmer <p> 8349 1.1 mbalmer <hr><h3><a name="pdf-string.len"><code>string.len (s)</code></a></h3> 8350 1.1 mbalmer Receives a string and returns its length. 8351 1.1 mbalmer The empty string <code>""</code> has length 0. 8352 1.1 mbalmer Embedded zeros are counted, 8353 1.1 mbalmer so <code>"a\000bc\000"</code> has length 5. 8354 1.1 mbalmer 8355 1.1 mbalmer 8356 1.1 mbalmer 8357 1.1 mbalmer 8358 1.1 mbalmer <p> 8359 1.1 mbalmer <hr><h3><a name="pdf-string.lower"><code>string.lower (s)</code></a></h3> 8360 1.1 mbalmer Receives a string and returns a copy of this string with all 8361 1.1 mbalmer uppercase letters changed to lowercase. 8362 1.1 mbalmer All other characters are left unchanged. 8363 1.1 mbalmer The definition of what an uppercase letter is depends on the current locale. 8364 1.1 mbalmer 8365 1.1 mbalmer 8366 1.1 mbalmer 8367 1.1 mbalmer 8368 1.1 mbalmer <p> 8369 1.1 mbalmer <hr><h3><a name="pdf-string.match"><code>string.match (s, pattern [, init])</code></a></h3> 8370 1.1 mbalmer Looks for the first <em>match</em> of 8371 1.1 mbalmer <code>pattern</code> in the string <code>s</code>. 8372 1.1 mbalmer If it finds one, then <code>match</code> returns 8373 1.1 mbalmer the captures from the pattern; 8374 1.1 mbalmer otherwise it returns <b>nil</b>. 8375 1.1 mbalmer If <code>pattern</code> specifies no captures, 8376 1.1 mbalmer then the whole match is returned. 8377 1.1 mbalmer A third, optional numerical argument <code>init</code> specifies 8378 1.1 mbalmer where to start the search; 8379 1.1 mbalmer its default value is 1 and can be negative. 8380 1.1 mbalmer 8381 1.1 mbalmer 8382 1.1 mbalmer 8383 1.1 mbalmer 8384 1.1 mbalmer <p> 8385 1.2 lneto <hr><h3><a name="pdf-string.rep"><code>string.rep (s, n [, sep])</code></a></h3> 8386 1.1 mbalmer Returns a string that is the concatenation of <code>n</code> copies of 8387 1.2 lneto the string <code>s</code> separated by the string <code>sep</code>. 8388 1.2 lneto The default value for <code>sep</code> is the empty string 8389 1.2 lneto (that is, no separator). 8390 1.1 mbalmer 8391 1.1 mbalmer 8392 1.1 mbalmer 8393 1.1 mbalmer 8394 1.1 mbalmer <p> 8395 1.1 mbalmer <hr><h3><a name="pdf-string.reverse"><code>string.reverse (s)</code></a></h3> 8396 1.1 mbalmer Returns a string that is the string <code>s</code> reversed. 8397 1.1 mbalmer 8398 1.1 mbalmer 8399 1.1 mbalmer 8400 1.1 mbalmer 8401 1.1 mbalmer <p> 8402 1.1 mbalmer <hr><h3><a name="pdf-string.sub"><code>string.sub (s, i [, j])</code></a></h3> 8403 1.1 mbalmer Returns the substring of <code>s</code> that 8404 1.1 mbalmer starts at <code>i</code> and continues until <code>j</code>; 8405 1.1 mbalmer <code>i</code> and <code>j</code> can be negative. 8406 1.1 mbalmer If <code>j</code> is absent, then it is assumed to be equal to -1 8407 1.1 mbalmer (which is the same as the string length). 8408 1.1 mbalmer In particular, 8409 1.1 mbalmer the call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code> 8410 1.1 mbalmer with length <code>j</code>, 8411 1.1 mbalmer and <code>string.sub(s, -i)</code> returns a suffix of <code>s</code> 8412 1.1 mbalmer with length <code>i</code>. 8413 1.1 mbalmer 8414 1.1 mbalmer 8415 1.2 lneto <p> 8416 1.2 lneto If, after the translation of negative indices, 8417 1.2 lneto <code>i</code> is less than 1, 8418 1.2 lneto it is corrected to 1. 8419 1.2 lneto If <code>j</code> is greater than the string length, 8420 1.2 lneto it is corrected to that length. 8421 1.2 lneto If, after these corrections, 8422 1.2 lneto <code>i</code> is greater than <code>j</code>, 8423 1.2 lneto the function returns the empty string. 8424 1.2 lneto 8425 1.2 lneto 8426 1.2 lneto 8427 1.2 lneto 8428 1.2 lneto <p> 8429 1.2 lneto <hr><h3><a name="pdf-string.undumpfloat"><code>string.undumpfloat (s [, pos [, size [, endianness]]])</code></a></h3> 8430 1.2 lneto Reads the machine representation of a float starting at position 8431 1.2 lneto <code>pos</code> in string <code>s</code> and returns that number. 8432 1.2 lneto See <a href="#pdf-string.dumpfloat"><code>string.dumpfloat</code></a> for details about <code>size</code> and <code>endianness</code>. 8433 1.2 lneto 8434 1.2 lneto 8435 1.2 lneto 8436 1.2 lneto 8437 1.2 lneto <p> 8438 1.2 lneto <hr><h3><a name="pdf-string.undumpint"><code>string.undumpint (s [, pos [, size [, endianness]]])</code></a></h3> 8439 1.2 lneto Reads the machine representation of an integer starting at position 8440 1.2 lneto <code>pos</code> in string <code>s</code> and returns that integer. 8441 1.2 lneto See <a href="#pdf-string.dumpint"><code>string.dumpint</code></a> for details about <code>size</code> and <code>endianness</code>. 8442 1.2 lneto 8443 1.2 lneto 8444 1.2 lneto <p> 8445 1.2 lneto Integers are always read as signed. 8446 1.2 lneto 8447 1.2 lneto 8448 1.1 mbalmer 8449 1.1 mbalmer 8450 1.1 mbalmer <p> 8451 1.1 mbalmer <hr><h3><a name="pdf-string.upper"><code>string.upper (s)</code></a></h3> 8452 1.1 mbalmer Receives a string and returns a copy of this string with all 8453 1.1 mbalmer lowercase letters changed to uppercase. 8454 1.1 mbalmer All other characters are left unchanged. 8455 1.1 mbalmer The definition of what a lowercase letter is depends on the current locale. 8456 1.1 mbalmer 8457 1.1 mbalmer 8458 1.1 mbalmer 8459 1.2 lneto <h3>6.4.1 – <a name="6.4.1">Patterns</a></h3> 8460 1.1 mbalmer 8461 1.1 mbalmer 8462 1.1 mbalmer <h4>Character Class:</h4><p> 8463 1.1 mbalmer A <em>character class</em> is used to represent a set of characters. 8464 1.1 mbalmer The following combinations are allowed in describing a character class: 8465 1.1 mbalmer 8466 1.1 mbalmer <ul> 8467 1.1 mbalmer 8468 1.2 lneto <li><b><em>x</em>: </b> 8469 1.1 mbalmer (where <em>x</em> is not one of the <em>magic characters</em> 8470 1.1 mbalmer <code>^$()%.[]*+-?</code>) 8471 1.1 mbalmer represents the character <em>x</em> itself. 8472 1.1 mbalmer </li> 8473 1.1 mbalmer 8474 1.2 lneto <li><b><code>.</code>: </b> (a dot) represents all characters.</li> 8475 1.1 mbalmer 8476 1.2 lneto <li><b><code>%a</code>: </b> represents all letters.</li> 8477 1.1 mbalmer 8478 1.2 lneto <li><b><code>%c</code>: </b> represents all control characters.</li> 8479 1.1 mbalmer 8480 1.2 lneto <li><b><code>%d</code>: </b> represents all digits.</li> 8481 1.1 mbalmer 8482 1.2 lneto <li><b><code>%g</code>: </b> represents all printable characters except space.</li> 8483 1.1 mbalmer 8484 1.2 lneto <li><b><code>%l</code>: </b> represents all lowercase letters.</li> 8485 1.1 mbalmer 8486 1.2 lneto <li><b><code>%p</code>: </b> represents all punctuation characters.</li> 8487 1.1 mbalmer 8488 1.2 lneto <li><b><code>%s</code>: </b> represents all space characters.</li> 8489 1.1 mbalmer 8490 1.2 lneto <li><b><code>%u</code>: </b> represents all uppercase letters.</li> 8491 1.1 mbalmer 8492 1.2 lneto <li><b><code>%w</code>: </b> represents all alphanumeric characters.</li> 8493 1.1 mbalmer 8494 1.2 lneto <li><b><code>%x</code>: </b> represents all hexadecimal digits.</li> 8495 1.1 mbalmer 8496 1.2 lneto <li><b><code>%<em>x</em></code>: </b> (where <em>x</em> is any non-alphanumeric character) 8497 1.1 mbalmer represents the character <em>x</em>. 8498 1.1 mbalmer This is the standard way to escape the magic characters. 8499 1.1 mbalmer Any punctuation character (even the non magic) 8500 1.1 mbalmer can be preceded by a '<code>%</code>' 8501 1.1 mbalmer when used to represent itself in a pattern. 8502 1.1 mbalmer </li> 8503 1.1 mbalmer 8504 1.2 lneto <li><b><code>[<em>set</em>]</code>: </b> 8505 1.1 mbalmer represents the class which is the union of all 8506 1.1 mbalmer characters in <em>set</em>. 8507 1.1 mbalmer A range of characters can be specified by 8508 1.2 lneto separating the end characters of the range, 8509 1.2 lneto in ascending order, with a '<code>-</code>'. 8510 1.1 mbalmer All classes <code>%</code><em>x</em> described above can also be used as 8511 1.1 mbalmer components in <em>set</em>. 8512 1.1 mbalmer All other characters in <em>set</em> represent themselves. 8513 1.1 mbalmer For example, <code>[%w_]</code> (or <code>[_%w]</code>) 8514 1.1 mbalmer represents all alphanumeric characters plus the underscore, 8515 1.1 mbalmer <code>[0-7]</code> represents the octal digits, 8516 1.1 mbalmer and <code>[0-7%l%-]</code> represents the octal digits plus 8517 1.1 mbalmer the lowercase letters plus the '<code>-</code>' character. 8518 1.1 mbalmer 8519 1.1 mbalmer 8520 1.1 mbalmer <p> 8521 1.1 mbalmer The interaction between ranges and classes is not defined. 8522 1.1 mbalmer Therefore, patterns like <code>[%a-z]</code> or <code>[a-%%]</code> 8523 1.1 mbalmer have no meaning. 8524 1.1 mbalmer </li> 8525 1.1 mbalmer 8526 1.2 lneto <li><b><code>[^<em>set</em>]</code>: </b> 8527 1.1 mbalmer represents the complement of <em>set</em>, 8528 1.1 mbalmer where <em>set</em> is interpreted as above. 8529 1.1 mbalmer </li> 8530 1.1 mbalmer 8531 1.1 mbalmer </ul><p> 8532 1.1 mbalmer For all classes represented by single letters (<code>%a</code>, <code>%c</code>, etc.), 8533 1.1 mbalmer the corresponding uppercase letter represents the complement of the class. 8534 1.1 mbalmer For instance, <code>%S</code> represents all non-space characters. 8535 1.1 mbalmer 8536 1.1 mbalmer 8537 1.1 mbalmer <p> 8538 1.1 mbalmer The definitions of letter, space, and other character groups 8539 1.1 mbalmer depend on the current locale. 8540 1.1 mbalmer In particular, the class <code>[a-z]</code> may not be equivalent to <code>%l</code>. 8541 1.1 mbalmer 8542 1.1 mbalmer 8543 1.1 mbalmer 8544 1.1 mbalmer 8545 1.1 mbalmer 8546 1.1 mbalmer <h4>Pattern Item:</h4><p> 8547 1.1 mbalmer A <em>pattern item</em> can be 8548 1.1 mbalmer 8549 1.1 mbalmer <ul> 8550 1.1 mbalmer 8551 1.1 mbalmer <li> 8552 1.1 mbalmer a single character class, 8553 1.1 mbalmer which matches any single character in the class; 8554 1.1 mbalmer </li> 8555 1.1 mbalmer 8556 1.1 mbalmer <li> 8557 1.1 mbalmer a single character class followed by '<code>*</code>', 8558 1.1 mbalmer which matches 0 or more repetitions of characters in the class. 8559 1.1 mbalmer These repetition items will always match the longest possible sequence; 8560 1.1 mbalmer </li> 8561 1.1 mbalmer 8562 1.1 mbalmer <li> 8563 1.1 mbalmer a single character class followed by '<code>+</code>', 8564 1.1 mbalmer which matches 1 or more repetitions of characters in the class. 8565 1.1 mbalmer These repetition items will always match the longest possible sequence; 8566 1.1 mbalmer </li> 8567 1.1 mbalmer 8568 1.1 mbalmer <li> 8569 1.1 mbalmer a single character class followed by '<code>-</code>', 8570 1.1 mbalmer which also matches 0 or more repetitions of characters in the class. 8571 1.1 mbalmer Unlike '<code>*</code>', 8572 1.2 lneto these repetition items will always match the shortest possible sequence; 8573 1.1 mbalmer </li> 8574 1.1 mbalmer 8575 1.1 mbalmer <li> 8576 1.1 mbalmer a single character class followed by '<code>?</code>', 8577 1.1 mbalmer which matches 0 or 1 occurrence of a character in the class; 8578 1.1 mbalmer </li> 8579 1.1 mbalmer 8580 1.1 mbalmer <li> 8581 1.1 mbalmer <code>%<em>n</em></code>, for <em>n</em> between 1 and 9; 8582 1.1 mbalmer such item matches a substring equal to the <em>n</em>-th captured string 8583 1.1 mbalmer (see below); 8584 1.1 mbalmer </li> 8585 1.1 mbalmer 8586 1.1 mbalmer <li> 8587 1.1 mbalmer <code>%b<em>xy</em></code>, where <em>x</em> and <em>y</em> are two distinct characters; 8588 1.1 mbalmer such item matches strings that start with <em>x</em>, end with <em>y</em>, 8589 1.1 mbalmer and where the <em>x</em> and <em>y</em> are <em>balanced</em>. 8590 1.1 mbalmer This means that, if one reads the string from left to right, 8591 1.1 mbalmer counting <em>+1</em> for an <em>x</em> and <em>-1</em> for a <em>y</em>, 8592 1.1 mbalmer the ending <em>y</em> is the first <em>y</em> where the count reaches 0. 8593 1.1 mbalmer For instance, the item <code>%b()</code> matches expressions with 8594 1.1 mbalmer balanced parentheses. 8595 1.1 mbalmer </li> 8596 1.1 mbalmer 8597 1.2 lneto <li> 8598 1.2 lneto <code>%f[<em>set</em>]</code>, a <em>frontier pattern</em>; 8599 1.2 lneto such item matches an empty string at any position such that 8600 1.2 lneto the next character belongs to <em>set</em> 8601 1.2 lneto and the previous character does not belong to <em>set</em>. 8602 1.2 lneto The set <em>set</em> is interpreted as previously described. 8603 1.2 lneto The beginning and the end of the subject are handled as if 8604 1.2 lneto they were the character '<code>\0</code>'. 8605 1.2 lneto </li> 8606 1.2 lneto 8607 1.1 mbalmer </ul> 8608 1.1 mbalmer 8609 1.1 mbalmer 8610 1.1 mbalmer 8611 1.1 mbalmer 8612 1.1 mbalmer <h4>Pattern:</h4><p> 8613 1.1 mbalmer A <em>pattern</em> is a sequence of pattern items. 8614 1.2 lneto A caret '<code>^</code>' at the beginning of a pattern anchors the match at the 8615 1.1 mbalmer beginning of the subject string. 8616 1.1 mbalmer A '<code>$</code>' at the end of a pattern anchors the match at the 8617 1.1 mbalmer end of the subject string. 8618 1.1 mbalmer At other positions, 8619 1.1 mbalmer '<code>^</code>' and '<code>$</code>' have no special meaning and represent themselves. 8620 1.1 mbalmer 8621 1.1 mbalmer 8622 1.1 mbalmer 8623 1.1 mbalmer 8624 1.1 mbalmer 8625 1.1 mbalmer <h4>Captures:</h4><p> 8626 1.1 mbalmer A pattern can contain sub-patterns enclosed in parentheses; 8627 1.1 mbalmer they describe <em>captures</em>. 8628 1.1 mbalmer When a match succeeds, the substrings of the subject string 8629 1.1 mbalmer that match captures are stored (<em>captured</em>) for future use. 8630 1.1 mbalmer Captures are numbered according to their left parentheses. 8631 1.1 mbalmer For instance, in the pattern <code>"(a*(.)%w(%s*))"</code>, 8632 1.1 mbalmer the part of the string matching <code>"a*(.)%w(%s*)"</code> is 8633 1.1 mbalmer stored as the first capture (and therefore has number 1); 8634 1.1 mbalmer the character matching "<code>.</code>" is captured with number 2, 8635 1.1 mbalmer and the part matching "<code>%s*</code>" has number 3. 8636 1.1 mbalmer 8637 1.1 mbalmer 8638 1.1 mbalmer <p> 8639 1.1 mbalmer As a special case, the empty capture <code>()</code> captures 8640 1.1 mbalmer the current string position (a number). 8641 1.1 mbalmer For instance, if we apply the pattern <code>"()aa()"</code> on the 8642 1.1 mbalmer string <code>"flaaap"</code>, there will be two captures: 3 and 5. 8643 1.1 mbalmer 8644 1.1 mbalmer 8645 1.2 lneto 8646 1.2 lneto 8647 1.2 lneto 8648 1.2 lneto 8649 1.2 lneto 8650 1.2 lneto 8651 1.2 lneto 8652 1.2 lneto 8653 1.2 lneto 8654 1.2 lneto <h2>6.5 – <a name="6.5">UTF-8 Support</a></h2> 8655 1.2 lneto 8656 1.2 lneto <p> 8657 1.2 lneto This library provides basic support for UTF-8 encoding. 8658 1.2 lneto It provides all its functions inside the table <a name="pdf-utf8"><code>utf8</code></a>. 8659 1.2 lneto This library does not provide any support for Unicode other 8660 1.2 lneto than the handling of the encoding. 8661 1.2 lneto Any operation that needs the meaning of a character, 8662 1.2 lneto such as character classification, is outside its scope. 8663 1.2 lneto 8664 1.2 lneto 8665 1.2 lneto <p> 8666 1.2 lneto Unless stated otherwise, 8667 1.2 lneto all functions that expect a byte position as a parameter 8668 1.2 lneto assume that the given position is either the start of a byte sequence 8669 1.2 lneto or one plus the length of the subject string. 8670 1.2 lneto As in the string library, 8671 1.2 lneto negative indices count from the end of the string. 8672 1.2 lneto 8673 1.2 lneto 8674 1.2 lneto <p> 8675 1.2 lneto <hr><h3><a name="pdf-utf8.char"><code>utf8.char (···)</code></a></h3> 8676 1.2 lneto Receives zero or more integers, 8677 1.2 lneto converts each one to its corresponding UTF-8 byte sequence 8678 1.2 lneto and returns a string with the concatenation of all these sequences. 8679 1.2 lneto 8680 1.2 lneto 8681 1.2 lneto 8682 1.2 lneto 8683 1.2 lneto <p> 8684 1.2 lneto <hr><h3><a name="pdf-utf8.charpatt"><code>utf8.charpatt</code></a></h3> 8685 1.2 lneto The pattern (a string, not a function) "<code>[\0-\x7F\xC2-\xF4][\x80-\xBF]*</code>" 8686 1.2 lneto (see <a href="#6.4.1">§6.4.1</a>), 8687 1.2 lneto which matches exactly one UTF-8 byte sequence, 8688 1.2 lneto assuming that the subject is a valid UTF-8 string. 8689 1.2 lneto 8690 1.2 lneto 8691 1.2 lneto 8692 1.2 lneto 8693 1.2 lneto <p> 8694 1.2 lneto <hr><h3><a name="pdf-utf8.codes"><code>utf8.codes (s)</code></a></h3> 8695 1.2 lneto 8696 1.2 lneto 8697 1.2 lneto <p> 8698 1.2 lneto Returns values so that the construction 8699 1.2 lneto 8700 1.2 lneto <pre> 8701 1.2 lneto for p, c in utf8.codes(s) do <em>body</em> end 8702 1.2 lneto </pre><p> 8703 1.2 lneto will iterate over all characters in string <code>s</code>, 8704 1.2 lneto with <code>p</code> being the position (in bytes) and <code>c</code> the code point 8705 1.2 lneto of each character. 8706 1.2 lneto It raises an error if it meets any invalid byte sequence. 8707 1.2 lneto 8708 1.2 lneto 8709 1.2 lneto 8710 1.2 lneto 8711 1.2 lneto <p> 8712 1.2 lneto <hr><h3><a name="pdf-utf8.codepoint"><code>utf8.codepoint (s [, i [, j]])</code></a></h3> 8713 1.2 lneto Returns the codepoints (as integers) from all characters in <code>s</code> 8714 1.2 lneto that start between byte position <code>i</code> and <code>j</code> (both included). 8715 1.2 lneto The default for <code>i</code> is 1 and for <code>j</code> is <code>i</code>. 8716 1.2 lneto It raises an error if it meets any invalid byte sequence. 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-utf8.len"><code>utf8.len (s [, i [, j]])</code></a></h3> 8723 1.2 lneto Returns the number of UTF-8 characters in string <code>s</code> 8724 1.2 lneto that start between positions <code>i</code> and @{j} (both inclusive). 8725 1.2 lneto The default for <code>i</code> is 1 and for <code>j</code> is -1. 8726 1.2 lneto If it finds any invalid byte sequence, 8727 1.2 lneto returns <b>nil</b> plus the position of the first invalid byte. 8728 1.2 lneto 8729 1.2 lneto 8730 1.2 lneto 8731 1.2 lneto 8732 1.2 lneto <p> 8733 1.2 lneto <hr><h3><a name="pdf-utf8.offset"><code>utf8.offset (s, n [, i])</code></a></h3> 8734 1.2 lneto Returns the position (in bytes) where the encoding of the 8735 1.2 lneto <code>n</code>-th character of <code>s</code> 8736 1.2 lneto (counting from position <code>i</code>) starts. 8737 1.2 lneto A negative <code>n</code> gets characters before position <code>i</code>. 8738 1.2 lneto The default for <code>i</code> is 1 when <code>n</code> is non-negative 8739 1.2 lneto and <code>#s + 1</code> otherwise, 8740 1.2 lneto so that <code>utf8.offset(s, -n)</code> gets the offset of the 8741 1.2 lneto <code>n</code>-th character from the end of the string. 8742 1.2 lneto If the specified character is not in the subject 8743 1.2 lneto or right after its end, 8744 1.2 lneto the function returns <b>nil</b>. 8745 1.2 lneto 8746 1.2 lneto 8747 1.2 lneto <p> 8748 1.2 lneto As a special case, 8749 1.2 lneto when <code>n</code> is 0 the function returns the start of the encoding 8750 1.2 lneto of the character that contains the <code>i</code>-th byte of <code>s</code>. 8751 1.2 lneto 8752 1.2 lneto 8753 1.1 mbalmer <p> 8754 1.2 lneto This function assumes that <code>s</code> is a valid UTF-8 string. 8755 1.1 mbalmer 8756 1.1 mbalmer 8757 1.1 mbalmer 8758 1.1 mbalmer 8759 1.1 mbalmer 8760 1.1 mbalmer 8761 1.1 mbalmer 8762 1.2 lneto <h2>6.6 – <a name="6.6">Table Manipulation</a></h2> 8763 1.2 lneto 8764 1.2 lneto <p> 8765 1.2 lneto This library provides generic functions for table manipulation. 8766 1.2 lneto It provides all its functions inside the table <a name="pdf-table"><code>table</code></a>. 8767 1.1 mbalmer 8768 1.1 mbalmer 8769 1.2 lneto <p> 8770 1.2 lneto Remember that, whenever an operation needs the length of a table, 8771 1.2 lneto the table must be a proper sequence 8772 1.2 lneto or have a <code>__len</code> metamethod (see <a href="#3.4.7">§3.4.7</a>). 8773 1.2 lneto All functions ignore non-numeric keys 8774 1.2 lneto in tables given as arguments. 8775 1.1 mbalmer 8776 1.1 mbalmer 8777 1.2 lneto <p> 8778 1.2 lneto For performance reasons, 8779 1.2 lneto all table accesses (get/set) performed by these functions are raw. 8780 1.1 mbalmer 8781 1.1 mbalmer 8782 1.1 mbalmer <p> 8783 1.2 lneto <hr><h3><a name="pdf-table.concat"><code>table.concat (list [, sep [, i [, j]]])</code></a></h3> 8784 1.1 mbalmer 8785 1.1 mbalmer 8786 1.1 mbalmer <p> 8787 1.2 lneto Given a list where all elements are strings or numbers, 8788 1.2 lneto returns the string <code>list[i]..sep..list[i+1] ··· sep..list[j]</code>. 8789 1.1 mbalmer The default value for <code>sep</code> is the empty string, 8790 1.1 mbalmer the default for <code>i</code> is 1, 8791 1.2 lneto and the default for <code>j</code> is <code>#list</code>. 8792 1.1 mbalmer If <code>i</code> is greater than <code>j</code>, returns the empty string. 8793 1.1 mbalmer 8794 1.1 mbalmer 8795 1.1 mbalmer 8796 1.1 mbalmer 8797 1.1 mbalmer <p> 8798 1.2 lneto <hr><h3><a name="pdf-table.insert"><code>table.insert (list, [pos,] value)</code></a></h3> 8799 1.1 mbalmer 8800 1.1 mbalmer 8801 1.1 mbalmer <p> 8802 1.2 lneto Inserts element <code>value</code> at position <code>pos</code> in <code>list</code>, 8803 1.2 lneto shifting up the elements 8804 1.2 lneto <code>list[pos], list[pos+1], ···, list[#list]</code>. 8805 1.2 lneto The default value for <code>pos</code> is <code>#list+1</code>, 8806 1.1 mbalmer so that a call <code>table.insert(t,x)</code> inserts <code>x</code> at the end 8807 1.2 lneto of list <code>t</code>. 8808 1.1 mbalmer 8809 1.1 mbalmer 8810 1.1 mbalmer 8811 1.1 mbalmer 8812 1.1 mbalmer <p> 8813 1.2 lneto <hr><h3><a name="pdf-table.pack"><code>table.pack (···)</code></a></h3> 8814 1.1 mbalmer 8815 1.1 mbalmer 8816 1.1 mbalmer <p> 8817 1.2 lneto Returns a new table with all parameters stored into keys 1, 2, etc. 8818 1.2 lneto and with a field "<code>n</code>" with the total number of parameters. 8819 1.2 lneto Note that the resulting table may not be a sequence. 8820 1.1 mbalmer 8821 1.1 mbalmer 8822 1.1 mbalmer 8823 1.1 mbalmer 8824 1.1 mbalmer <p> 8825 1.2 lneto <hr><h3><a name="pdf-table.remove"><code>table.remove (list [, pos])</code></a></h3> 8826 1.1 mbalmer 8827 1.1 mbalmer 8828 1.1 mbalmer <p> 8829 1.2 lneto Removes from <code>list</code> the element at position <code>pos</code>, 8830 1.2 lneto returning the value of the removed element. 8831 1.2 lneto When <code>pos</code> is an integer between 1 and <code>#list</code>, 8832 1.2 lneto it shifts down the elements 8833 1.2 lneto <code>list[pos+1], list[pos+2], ···, list[#list]</code> 8834 1.2 lneto and erases element <code>list[#list]</code>; 8835 1.2 lneto The index <code>pos</code> can also be 0 when <code>#list</code> is 0, 8836 1.2 lneto or <code>#list + 1</code>; 8837 1.2 lneto in those cases, the function erases the element <code>list[pos]</code>. 8838 1.2 lneto 8839 1.2 lneto 8840 1.2 lneto <p> 8841 1.2 lneto The default value for <code>pos</code> is <code>#list</code>, 8842 1.2 lneto so that a call <code>table.remove(l)</code> removes the last element 8843 1.2 lneto of list <code>l</code>. 8844 1.2 lneto 8845 1.1 mbalmer 8846 1.1 mbalmer 8847 1.1 mbalmer 8848 1.2 lneto <p> 8849 1.2 lneto <hr><h3><a name="pdf-table.sort"><code>table.sort (list [, comp])</code></a></h3> 8850 1.2 lneto 8851 1.1 mbalmer 8852 1.1 mbalmer <p> 8853 1.2 lneto Sorts list elements in a given order, <em>in-place</em>, 8854 1.2 lneto from <code>list[1]</code> to <code>list[#list]</code>. 8855 1.1 mbalmer If <code>comp</code> is given, 8856 1.2 lneto then it must be a function that receives two list elements 8857 1.2 lneto and returns true when the first element must come 8858 1.2 lneto before the second in the final order 8859 1.2 lneto (so that <code>not comp(list[i+1],list[i])</code> will be true after the sort). 8860 1.1 mbalmer If <code>comp</code> is not given, 8861 1.1 mbalmer then the standard Lua operator <code><</code> is used instead. 8862 1.1 mbalmer 8863 1.1 mbalmer 8864 1.1 mbalmer <p> 8865 1.1 mbalmer The sort algorithm is not stable; 8866 1.1 mbalmer that is, elements considered equal by the given order 8867 1.1 mbalmer may have their relative positions changed by the sort. 8868 1.1 mbalmer 8869 1.1 mbalmer 8870 1.1 mbalmer 8871 1.1 mbalmer 8872 1.2 lneto <p> 8873 1.2 lneto <hr><h3><a name="pdf-table.unpack"><code>table.unpack (list [, i [, j]])</code></a></h3> 8874 1.2 lneto 8875 1.2 lneto 8876 1.2 lneto <p> 8877 1.2 lneto Returns the elements from the given list. 8878 1.2 lneto This function is equivalent to 8879 1.2 lneto 8880 1.2 lneto <pre> 8881 1.2 lneto return list[i], list[i+1], ···, list[j] 8882 1.2 lneto </pre><p> 8883 1.2 lneto By default, <code>i</code> is 1 and <code>j</code> is <code>#list</code>. 8884 1.2 lneto 8885 1.2 lneto 8886 1.2 lneto 8887 1.1 mbalmer 8888 1.1 mbalmer 8889 1.1 mbalmer 8890 1.2 lneto 8891 1.2 lneto <h2>6.7 – <a name="6.7">Mathematical Functions</a></h2> 8892 1.1 mbalmer 8893 1.1 mbalmer <p> 8894 1.2 lneto This library provides basic mathematical functions. 8895 1.2 lneto It provides all its functions and constants inside the table <a name="pdf-math"><code>math</code></a>. 8896 1.2 lneto Functions with the annotation "<code>integer/float</code>" give 8897 1.2 lneto integer results for integer arguments 8898 1.2 lneto and float results for float (or mixed) arguments. 8899 1.2 lneto Rounding functions 8900 1.2 lneto (<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>) 8901 1.2 lneto return an integer when the result fits in the range of an integer, 8902 1.2 lneto otherwise they return a float. 8903 1.1 mbalmer 8904 1.1 mbalmer 8905 1.1 mbalmer <p> 8906 1.1 mbalmer <hr><h3><a name="pdf-math.abs"><code>math.abs (x)</code></a></h3> 8907 1.1 mbalmer 8908 1.1 mbalmer 8909 1.1 mbalmer <p> 8910 1.2 lneto Returns the absolute value of <code>x</code>. (integer/float) 8911 1.1 mbalmer 8912 1.1 mbalmer 8913 1.1 mbalmer 8914 1.1 mbalmer 8915 1.1 mbalmer <p> 8916 1.1 mbalmer <hr><h3><a name="pdf-math.acos"><code>math.acos (x)</code></a></h3> 8917 1.1 mbalmer 8918 1.1 mbalmer 8919 1.1 mbalmer <p> 8920 1.1 mbalmer Returns the arc cosine of <code>x</code> (in radians). 8921 1.1 mbalmer 8922 1.1 mbalmer 8923 1.1 mbalmer 8924 1.1 mbalmer 8925 1.1 mbalmer <p> 8926 1.1 mbalmer <hr><h3><a name="pdf-math.asin"><code>math.asin (x)</code></a></h3> 8927 1.1 mbalmer 8928 1.1 mbalmer 8929 1.1 mbalmer <p> 8930 1.1 mbalmer Returns the arc sine of <code>x</code> (in radians). 8931 1.1 mbalmer 8932 1.1 mbalmer 8933 1.1 mbalmer 8934 1.1 mbalmer 8935 1.1 mbalmer <p> 8936 1.2 lneto <hr><h3><a name="pdf-math.atan"><code>math.atan (y [, x])</code></a></h3> 8937 1.1 mbalmer 8938 1.1 mbalmer 8939 1.1 mbalmer <p> 8940 1.1 mbalmer 8941 1.1 mbalmer Returns the arc tangent of <code>y/x</code> (in radians), 8942 1.1 mbalmer but uses the signs of both parameters to find the 8943 1.1 mbalmer quadrant of the result. 8944 1.1 mbalmer (It also handles correctly the case of <code>x</code> being zero.) 8945 1.1 mbalmer 8946 1.1 mbalmer 8947 1.2 lneto <p> 8948 1.2 lneto The default value for <code>x</code> is 1, 8949 1.2 lneto so that the call <code>math.atan(y)</code> 8950 1.2 lneto returns the arc tangent of <code>y</code>. 8951 1.2 lneto 8952 1.2 lneto 8953 1.1 mbalmer 8954 1.1 mbalmer 8955 1.1 mbalmer <p> 8956 1.1 mbalmer <hr><h3><a name="pdf-math.ceil"><code>math.ceil (x)</code></a></h3> 8957 1.1 mbalmer 8958 1.1 mbalmer 8959 1.1 mbalmer <p> 8960 1.2 lneto Returns the smaller integral value larger than or equal to <code>x</code>. 8961 1.1 mbalmer 8962 1.1 mbalmer 8963 1.1 mbalmer 8964 1.1 mbalmer 8965 1.1 mbalmer <p> 8966 1.1 mbalmer <hr><h3><a name="pdf-math.cos"><code>math.cos (x)</code></a></h3> 8967 1.1 mbalmer 8968 1.1 mbalmer 8969 1.1 mbalmer <p> 8970 1.1 mbalmer Returns the cosine of <code>x</code> (assumed to be in radians). 8971 1.1 mbalmer 8972 1.1 mbalmer 8973 1.1 mbalmer 8974 1.1 mbalmer 8975 1.1 mbalmer <p> 8976 1.1 mbalmer <hr><h3><a name="pdf-math.deg"><code>math.deg (x)</code></a></h3> 8977 1.1 mbalmer 8978 1.1 mbalmer 8979 1.1 mbalmer <p> 8980 1.2 lneto Converts the angle <code>x</code> from radians to degrees. 8981 1.1 mbalmer 8982 1.1 mbalmer 8983 1.1 mbalmer 8984 1.1 mbalmer 8985 1.1 mbalmer <p> 8986 1.1 mbalmer <hr><h3><a name="pdf-math.floor"><code>math.floor (x)</code></a></h3> 8987 1.1 mbalmer 8988 1.1 mbalmer 8989 1.1 mbalmer <p> 8990 1.2 lneto Returns the largest integral value smaller than or equal to <code>x</code>. 8991 1.1 mbalmer 8992 1.1 mbalmer 8993 1.1 mbalmer 8994 1.1 mbalmer 8995 1.1 mbalmer <p> 8996 1.1 mbalmer <hr><h3><a name="pdf-math.fmod"><code>math.fmod (x, y)</code></a></h3> 8997 1.1 mbalmer 8998 1.1 mbalmer 8999 1.1 mbalmer <p> 9000 1.1 mbalmer Returns the remainder of the division of <code>x</code> by <code>y</code> 9001 1.2 lneto that rounds the quotient towards zero. (integer/float) 9002 1.1 mbalmer 9003 1.1 mbalmer 9004 1.1 mbalmer 9005 1.1 mbalmer 9006 1.1 mbalmer <p> 9007 1.2 lneto <hr><h3><a name="pdf-math.huge"><code>math.huge</code></a></h3> 9008 1.1 mbalmer 9009 1.1 mbalmer 9010 1.1 mbalmer <p> 9011 1.2 lneto The float value <code>HUGE_VAL</code>, 9012 1.2 lneto a value larger than any other numerical value. 9013 1.1 mbalmer 9014 1.1 mbalmer 9015 1.1 mbalmer 9016 1.1 mbalmer 9017 1.1 mbalmer <p> 9018 1.2 lneto <hr><h3><a name="pdf-math.ifloor"><code>math.ifloor (x)</code></a></h3> 9019 1.1 mbalmer 9020 1.1 mbalmer 9021 1.1 mbalmer <p> 9022 1.2 lneto Returns the largest integer smaller than or equal to <code>x</code>. 9023 1.2 lneto If the value does not fit in an integer, 9024 1.2 lneto returns <b>nil</b>. 9025 1.1 mbalmer 9026 1.1 mbalmer 9027 1.1 mbalmer 9028 1.1 mbalmer 9029 1.1 mbalmer <p> 9030 1.2 lneto <hr><h3><a name="pdf-math.log"><code>math.log (x [, base])</code></a></h3> 9031 1.1 mbalmer 9032 1.1 mbalmer 9033 1.1 mbalmer <p> 9034 1.2 lneto Returns the logarithm of <code>x</code> in the given base. 9035 1.2 lneto The default for <code>base</code> is <em>e</em> 9036 1.2 lneto (so that the function returns the natural logarithm of <code>x</code>). 9037 1.1 mbalmer 9038 1.1 mbalmer 9039 1.1 mbalmer 9040 1.1 mbalmer 9041 1.1 mbalmer <p> 9042 1.2 lneto <hr><h3><a name="pdf-math.max"><code>math.max (x, ···)</code></a></h3> 9043 1.1 mbalmer 9044 1.1 mbalmer 9045 1.1 mbalmer <p> 9046 1.2 lneto Returns the argument with the maximum value, 9047 1.2 lneto according to the Lua operator <code><</code>. (integer/float) 9048 1.1 mbalmer 9049 1.1 mbalmer 9050 1.1 mbalmer 9051 1.1 mbalmer 9052 1.1 mbalmer <p> 9053 1.2 lneto <hr><h3><a name="pdf-math.maxinteger"><code>math.maxinteger</code></a></h3> 9054 1.2 lneto An integer with the maximum value for an integer. 9055 1.1 mbalmer 9056 1.1 mbalmer 9057 1.1 mbalmer 9058 1.1 mbalmer 9059 1.1 mbalmer <p> 9060 1.2 lneto <hr><h3><a name="pdf-math.min"><code>math.min (x, ···)</code></a></h3> 9061 1.1 mbalmer 9062 1.1 mbalmer 9063 1.1 mbalmer <p> 9064 1.2 lneto Returns the argument with the minimum value, 9065 1.2 lneto according to the Lua operator <code><</code>. (integer/float) 9066 1.1 mbalmer 9067 1.1 mbalmer 9068 1.1 mbalmer 9069 1.1 mbalmer 9070 1.1 mbalmer <p> 9071 1.2 lneto <hr><h3><a name="pdf-math.mininteger"><code>math.mininteger</code></a></h3> 9072 1.2 lneto An integer with the minimum value for an integer. 9073 1.1 mbalmer 9074 1.1 mbalmer 9075 1.1 mbalmer 9076 1.1 mbalmer 9077 1.1 mbalmer <p> 9078 1.1 mbalmer <hr><h3><a name="pdf-math.modf"><code>math.modf (x)</code></a></h3> 9079 1.1 mbalmer 9080 1.1 mbalmer 9081 1.1 mbalmer <p> 9082 1.2 lneto Returns the integral part of <code>x</code> and the fractional part of <code>x</code>. 9083 1.2 lneto Its second result is always a float. 9084 1.1 mbalmer 9085 1.1 mbalmer 9086 1.1 mbalmer 9087 1.1 mbalmer 9088 1.1 mbalmer <p> 9089 1.1 mbalmer <hr><h3><a name="pdf-math.pi"><code>math.pi</code></a></h3> 9090 1.1 mbalmer 9091 1.1 mbalmer 9092 1.1 mbalmer <p> 9093 1.2 lneto The value of <em>π</em>. 9094 1.1 mbalmer 9095 1.1 mbalmer 9096 1.1 mbalmer 9097 1.1 mbalmer 9098 1.1 mbalmer <p> 9099 1.1 mbalmer <hr><h3><a name="pdf-math.rad"><code>math.rad (x)</code></a></h3> 9100 1.1 mbalmer 9101 1.1 mbalmer 9102 1.1 mbalmer <p> 9103 1.2 lneto Converts the angle <code>x</code> from degrees to radians. 9104 1.1 mbalmer 9105 1.1 mbalmer 9106 1.1 mbalmer 9107 1.1 mbalmer 9108 1.1 mbalmer <p> 9109 1.1 mbalmer <hr><h3><a name="pdf-math.random"><code>math.random ([m [, n]])</code></a></h3> 9110 1.1 mbalmer 9111 1.1 mbalmer 9112 1.1 mbalmer <p> 9113 1.2 lneto When called without arguments, 9114 1.2 lneto returns a pseudo-random float with uniform distribution 9115 1.2 lneto in the range <em>[0,1)</em>. 9116 1.2 lneto When called with two integers <code>m</code> and <code>n</code>, 9117 1.2 lneto <code>math.random</code> returns a pseudo-random integer 9118 1.2 lneto with uniform distribution in the range <em>[m, n]</em>. 9119 1.2 lneto (The interval size must fit in a Lua integer.) 9120 1.2 lneto The call <code>math.random(n)</code> is equivalent to <code>math.random(1,n)</code>. 9121 1.1 mbalmer 9122 1.1 mbalmer 9123 1.1 mbalmer <p> 9124 1.2 lneto This function is an interface to the underling 9125 1.2 lneto pseudo-random generator function provided by C. 9126 1.2 lneto No guarantees can be given for its statistical properties. 9127 1.1 mbalmer 9128 1.1 mbalmer 9129 1.1 mbalmer 9130 1.1 mbalmer 9131 1.1 mbalmer <p> 9132 1.1 mbalmer <hr><h3><a name="pdf-math.randomseed"><code>math.randomseed (x)</code></a></h3> 9133 1.1 mbalmer 9134 1.1 mbalmer 9135 1.1 mbalmer <p> 9136 1.1 mbalmer Sets <code>x</code> as the "seed" 9137 1.1 mbalmer for the pseudo-random generator: 9138 1.1 mbalmer equal seeds produce equal sequences of numbers. 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-math.sin"><code>math.sin (x)</code></a></h3> 9145 1.1 mbalmer 9146 1.1 mbalmer 9147 1.1 mbalmer <p> 9148 1.1 mbalmer Returns the sine of <code>x</code> (assumed to be in radians). 9149 1.1 mbalmer 9150 1.1 mbalmer 9151 1.1 mbalmer 9152 1.1 mbalmer 9153 1.1 mbalmer <p> 9154 1.1 mbalmer <hr><h3><a name="pdf-math.sqrt"><code>math.sqrt (x)</code></a></h3> 9155 1.1 mbalmer 9156 1.1 mbalmer 9157 1.1 mbalmer <p> 9158 1.1 mbalmer Returns the square root of <code>x</code>. 9159 1.1 mbalmer (You can also use the expression <code>x^0.5</code> to compute this value.) 9160 1.1 mbalmer 9161 1.1 mbalmer 9162 1.1 mbalmer 9163 1.1 mbalmer 9164 1.1 mbalmer <p> 9165 1.1 mbalmer <hr><h3><a name="pdf-math.tan"><code>math.tan (x)</code></a></h3> 9166 1.1 mbalmer 9167 1.1 mbalmer 9168 1.1 mbalmer <p> 9169 1.1 mbalmer Returns the tangent of <code>x</code> (assumed to be in radians). 9170 1.1 mbalmer 9171 1.1 mbalmer 9172 1.1 mbalmer 9173 1.1 mbalmer 9174 1.1 mbalmer <p> 9175 1.2 lneto <hr><h3><a name="pdf-math.type"><code>math.type (x)</code></a></h3> 9176 1.1 mbalmer 9177 1.1 mbalmer 9178 1.1 mbalmer <p> 9179 1.2 lneto Returns "<code>integer</code>" if <code>x</code> is an integer, 9180 1.2 lneto "<code>float</code>" if it is a float, 9181 1.2 lneto or <b>nil</b> if <code>x</code> is not a number. 9182 1.1 mbalmer 9183 1.1 mbalmer 9184 1.1 mbalmer 9185 1.1 mbalmer 9186 1.1 mbalmer 9187 1.1 mbalmer 9188 1.1 mbalmer 9189 1.2 lneto <h2>6.8 – <a name="6.8">Input and Output Facilities</a></h2> 9190 1.1 mbalmer 9191 1.1 mbalmer <p> 9192 1.1 mbalmer The I/O library provides two different styles for file manipulation. 9193 1.2 lneto The first one uses implicit file handles; 9194 1.1 mbalmer that is, there are operations to set a default input file and a 9195 1.1 mbalmer default output file, 9196 1.1 mbalmer and all input/output operations are over these default files. 9197 1.2 lneto The second style uses explicit file handles. 9198 1.1 mbalmer 9199 1.1 mbalmer 9200 1.1 mbalmer <p> 9201 1.2 lneto When using implicit file handles, 9202 1.1 mbalmer all operations are supplied by table <a name="pdf-io"><code>io</code></a>. 9203 1.2 lneto When using explicit file handles, 9204 1.2 lneto the operation <a href="#pdf-io.open"><code>io.open</code></a> returns a file handle 9205 1.2 lneto and then all operations are supplied as methods of the file handle. 9206 1.1 mbalmer 9207 1.1 mbalmer 9208 1.1 mbalmer <p> 9209 1.1 mbalmer The table <code>io</code> also provides 9210 1.2 lneto three predefined file handles with their usual meanings from C: 9211 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>. 9212 1.1 mbalmer The I/O library never closes these files. 9213 1.1 mbalmer 9214 1.1 mbalmer 9215 1.1 mbalmer <p> 9216 1.1 mbalmer Unless otherwise stated, 9217 1.1 mbalmer all I/O functions return <b>nil</b> on failure 9218 1.1 mbalmer (plus an error message as a second result and 9219 1.1 mbalmer a system-dependent error code as a third result) 9220 1.1 mbalmer and some value different from <b>nil</b> on success. 9221 1.2 lneto On non-POSIX systems, 9222 1.2 lneto the computation of the error message and error code 9223 1.2 lneto in case of errors 9224 1.2 lneto may be not thread safe, 9225 1.2 lneto because they rely on the global C variable <code>errno</code>. 9226 1.1 mbalmer 9227 1.1 mbalmer 9228 1.1 mbalmer <p> 9229 1.1 mbalmer <hr><h3><a name="pdf-io.close"><code>io.close ([file])</code></a></h3> 9230 1.1 mbalmer 9231 1.1 mbalmer 9232 1.1 mbalmer <p> 9233 1.1 mbalmer Equivalent to <code>file:close()</code>. 9234 1.1 mbalmer Without a <code>file</code>, closes the default output file. 9235 1.1 mbalmer 9236 1.1 mbalmer 9237 1.1 mbalmer 9238 1.1 mbalmer 9239 1.1 mbalmer <p> 9240 1.1 mbalmer <hr><h3><a name="pdf-io.flush"><code>io.flush ()</code></a></h3> 9241 1.1 mbalmer 9242 1.1 mbalmer 9243 1.1 mbalmer <p> 9244 1.2 lneto Equivalent to <code>io.output():flush()</code>. 9245 1.1 mbalmer 9246 1.1 mbalmer 9247 1.1 mbalmer 9248 1.1 mbalmer 9249 1.1 mbalmer <p> 9250 1.1 mbalmer <hr><h3><a name="pdf-io.input"><code>io.input ([file])</code></a></h3> 9251 1.1 mbalmer 9252 1.1 mbalmer 9253 1.1 mbalmer <p> 9254 1.1 mbalmer When called with a file name, it opens the named file (in text mode), 9255 1.1 mbalmer and sets its handle as the default input file. 9256 1.1 mbalmer When called with a file handle, 9257 1.1 mbalmer it simply sets this file handle as the default input file. 9258 1.1 mbalmer When called without parameters, 9259 1.1 mbalmer it returns the current default input file. 9260 1.1 mbalmer 9261 1.1 mbalmer 9262 1.1 mbalmer <p> 9263 1.1 mbalmer In case of errors this function raises the error, 9264 1.1 mbalmer instead of returning an error code. 9265 1.1 mbalmer 9266 1.1 mbalmer 9267 1.1 mbalmer 9268 1.1 mbalmer 9269 1.1 mbalmer <p> 9270 1.2 lneto <hr><h3><a name="pdf-io.lines"><code>io.lines ([filename ···])</code></a></h3> 9271 1.1 mbalmer 9272 1.1 mbalmer 9273 1.1 mbalmer <p> 9274 1.1 mbalmer Opens the given file name in read mode 9275 1.2 lneto and returns an iterator function that 9276 1.2 lneto works like <code>file:lines(···)</code> over the opened file. 9277 1.1 mbalmer When the iterator function detects the end of file, 9278 1.2 lneto it returns no values (to finish the loop) and automatically closes the file. 9279 1.1 mbalmer 9280 1.1 mbalmer 9281 1.1 mbalmer <p> 9282 1.1 mbalmer The call <code>io.lines()</code> (with no file name) is equivalent 9283 1.2 lneto to <code>io.input():lines("*l")</code>; 9284 1.1 mbalmer that is, it iterates over the lines of the default input file. 9285 1.1 mbalmer In this case it does not close the file when the loop ends. 9286 1.1 mbalmer 9287 1.1 mbalmer 9288 1.2 lneto <p> 9289 1.2 lneto In case of errors this function raises the error, 9290 1.2 lneto instead of returning an error code. 9291 1.2 lneto 9292 1.2 lneto 9293 1.1 mbalmer 9294 1.1 mbalmer 9295 1.1 mbalmer <p> 9296 1.1 mbalmer <hr><h3><a name="pdf-io.open"><code>io.open (filename [, mode])</code></a></h3> 9297 1.1 mbalmer 9298 1.1 mbalmer 9299 1.1 mbalmer <p> 9300 1.1 mbalmer This function opens a file, 9301 1.1 mbalmer in the mode specified in the string <code>mode</code>. 9302 1.1 mbalmer It returns a new file handle, 9303 1.1 mbalmer or, in case of errors, <b>nil</b> plus an error message. 9304 1.1 mbalmer 9305 1.1 mbalmer 9306 1.1 mbalmer <p> 9307 1.1 mbalmer The <code>mode</code> string can be any of the following: 9308 1.1 mbalmer 9309 1.1 mbalmer <ul> 9310 1.2 lneto <li><b>"<code>r</code>": </b> read mode (the default);</li> 9311 1.2 lneto <li><b>"<code>w</code>": </b> write mode;</li> 9312 1.2 lneto <li><b>"<code>a</code>": </b> append mode;</li> 9313 1.2 lneto <li><b>"<code>r+</code>": </b> update mode, all previous data is preserved;</li> 9314 1.2 lneto <li><b>"<code>w+</code>": </b> update mode, all previous data is erased;</li> 9315 1.2 lneto <li><b>"<code>a+</code>": </b> append update mode, previous data is preserved, 9316 1.1 mbalmer writing is only allowed at the end of file.</li> 9317 1.1 mbalmer </ul><p> 9318 1.1 mbalmer The <code>mode</code> string can also have a '<code>b</code>' at the end, 9319 1.1 mbalmer which is needed in some systems to open the file in binary mode. 9320 1.1 mbalmer 9321 1.1 mbalmer 9322 1.1 mbalmer 9323 1.1 mbalmer 9324 1.1 mbalmer <p> 9325 1.1 mbalmer <hr><h3><a name="pdf-io.output"><code>io.output ([file])</code></a></h3> 9326 1.1 mbalmer 9327 1.1 mbalmer 9328 1.1 mbalmer <p> 9329 1.1 mbalmer Similar to <a href="#pdf-io.input"><code>io.input</code></a>, but operates over the default output file. 9330 1.1 mbalmer 9331 1.1 mbalmer 9332 1.1 mbalmer 9333 1.1 mbalmer 9334 1.1 mbalmer <p> 9335 1.1 mbalmer <hr><h3><a name="pdf-io.popen"><code>io.popen (prog [, mode])</code></a></h3> 9336 1.1 mbalmer 9337 1.1 mbalmer 9338 1.1 mbalmer <p> 9339 1.2 lneto This function is system dependent and is not available 9340 1.2 lneto on all platforms. 9341 1.2 lneto 9342 1.2 lneto 9343 1.2 lneto <p> 9344 1.1 mbalmer Starts program <code>prog</code> in a separated process and returns 9345 1.1 mbalmer a file handle that you can use to read data from this program 9346 1.1 mbalmer (if <code>mode</code> is <code>"r"</code>, the default) 9347 1.1 mbalmer or to write data to this program 9348 1.1 mbalmer (if <code>mode</code> is <code>"w"</code>). 9349 1.1 mbalmer 9350 1.1 mbalmer 9351 1.1 mbalmer 9352 1.1 mbalmer 9353 1.1 mbalmer <p> 9354 1.1 mbalmer <hr><h3><a name="pdf-io.read"><code>io.read (···)</code></a></h3> 9355 1.1 mbalmer 9356 1.1 mbalmer 9357 1.1 mbalmer <p> 9358 1.2 lneto Equivalent to <code>io.input():read(···)</code>. 9359 1.1 mbalmer 9360 1.1 mbalmer 9361 1.1 mbalmer 9362 1.1 mbalmer 9363 1.1 mbalmer <p> 9364 1.1 mbalmer <hr><h3><a name="pdf-io.tmpfile"><code>io.tmpfile ()</code></a></h3> 9365 1.1 mbalmer 9366 1.1 mbalmer 9367 1.1 mbalmer <p> 9368 1.1 mbalmer Returns a handle for a temporary file. 9369 1.1 mbalmer This file is opened in update mode 9370 1.1 mbalmer and it is automatically removed when the program ends. 9371 1.1 mbalmer 9372 1.1 mbalmer 9373 1.1 mbalmer 9374 1.1 mbalmer 9375 1.1 mbalmer <p> 9376 1.1 mbalmer <hr><h3><a name="pdf-io.type"><code>io.type (obj)</code></a></h3> 9377 1.1 mbalmer 9378 1.1 mbalmer 9379 1.1 mbalmer <p> 9380 1.1 mbalmer Checks whether <code>obj</code> is a valid file handle. 9381 1.1 mbalmer Returns the string <code>"file"</code> if <code>obj</code> is an open file handle, 9382 1.1 mbalmer <code>"closed file"</code> if <code>obj</code> is a closed file handle, 9383 1.1 mbalmer or <b>nil</b> if <code>obj</code> is not a file handle. 9384 1.1 mbalmer 9385 1.1 mbalmer 9386 1.1 mbalmer 9387 1.1 mbalmer 9388 1.1 mbalmer <p> 9389 1.1 mbalmer <hr><h3><a name="pdf-io.write"><code>io.write (···)</code></a></h3> 9390 1.1 mbalmer 9391 1.1 mbalmer 9392 1.1 mbalmer <p> 9393 1.2 lneto Equivalent to <code>io.output():write(···)</code>. 9394 1.1 mbalmer 9395 1.1 mbalmer 9396 1.1 mbalmer 9397 1.1 mbalmer 9398 1.1 mbalmer <p> 9399 1.1 mbalmer <hr><h3><a name="pdf-file:close"><code>file:close ()</code></a></h3> 9400 1.1 mbalmer 9401 1.1 mbalmer 9402 1.1 mbalmer <p> 9403 1.1 mbalmer Closes <code>file</code>. 9404 1.1 mbalmer Note that files are automatically closed when 9405 1.1 mbalmer their handles are garbage collected, 9406 1.1 mbalmer but that takes an unpredictable amount of time to happen. 9407 1.1 mbalmer 9408 1.1 mbalmer 9409 1.2 lneto <p> 9410 1.2 lneto When closing a file handle created with <a href="#pdf-io.popen"><code>io.popen</code></a>, 9411 1.2 lneto <a href="#pdf-file:close"><code>file:close</code></a> returns the same values 9412 1.2 lneto returned by <a href="#pdf-os.execute"><code>os.execute</code></a>. 9413 1.2 lneto 9414 1.2 lneto 9415 1.1 mbalmer 9416 1.1 mbalmer 9417 1.1 mbalmer <p> 9418 1.1 mbalmer <hr><h3><a name="pdf-file:flush"><code>file:flush ()</code></a></h3> 9419 1.1 mbalmer 9420 1.1 mbalmer 9421 1.1 mbalmer <p> 9422 1.1 mbalmer Saves any written data to <code>file</code>. 9423 1.1 mbalmer 9424 1.1 mbalmer 9425 1.1 mbalmer 9426 1.1 mbalmer 9427 1.1 mbalmer <p> 9428 1.2 lneto <hr><h3><a name="pdf-file:lines"><code>file:lines (···)</code></a></h3> 9429 1.1 mbalmer 9430 1.1 mbalmer 9431 1.1 mbalmer <p> 9432 1.1 mbalmer Returns an iterator function that, 9433 1.1 mbalmer each time it is called, 9434 1.2 lneto reads the file according to the given formats. 9435 1.2 lneto When no format is given, 9436 1.2 lneto uses "<code>l</code>" as a default. 9437 1.2 lneto As an example, the construction 9438 1.1 mbalmer 9439 1.1 mbalmer <pre> 9440 1.2 lneto for c in file:lines(1) do <em>body</em> end 9441 1.2 lneto </pre><p> 9442 1.2 lneto will iterate over all characters of the file, 9443 1.2 lneto starting at the current position. 9444 1.2 lneto Unlike <a href="#pdf-io.lines"><code>io.lines</code></a>, this function does not close the file 9445 1.2 lneto when the loop ends. 9446 1.2 lneto 9447 1.2 lneto 9448 1.2 lneto <p> 9449 1.2 lneto In case of errors this function raises the error, 9450 1.2 lneto instead of returning an error code. 9451 1.1 mbalmer 9452 1.1 mbalmer 9453 1.1 mbalmer 9454 1.1 mbalmer 9455 1.1 mbalmer <p> 9456 1.1 mbalmer <hr><h3><a name="pdf-file:read"><code>file:read (···)</code></a></h3> 9457 1.1 mbalmer 9458 1.1 mbalmer 9459 1.1 mbalmer <p> 9460 1.1 mbalmer Reads the file <code>file</code>, 9461 1.1 mbalmer according to the given formats, which specify what to read. 9462 1.1 mbalmer For each format, 9463 1.2 lneto the function returns a string or a number with the characters read, 9464 1.1 mbalmer or <b>nil</b> if it cannot read data with the specified format. 9465 1.1 mbalmer When called without formats, 9466 1.2 lneto it uses a default format that reads the next line 9467 1.1 mbalmer (see below). 9468 1.1 mbalmer 9469 1.1 mbalmer 9470 1.1 mbalmer <p> 9471 1.1 mbalmer The available formats are 9472 1.1 mbalmer 9473 1.1 mbalmer <ul> 9474 1.1 mbalmer 9475 1.2 lneto <li><b>"<code>n</code>": </b> 9476 1.2 lneto reads a numeral and returns it as a float or an integer, 9477 1.2 lneto following the lexical conventions of Lua. 9478 1.2 lneto (The numeral may have leading spaces and a sign.) 9479 1.2 lneto This format always reads the longest input sequence that 9480 1.2 lneto is a valid prefix for a number; 9481 1.2 lneto if that prefix does not form a valid number 9482 1.2 lneto (e.g., an empty string, "<code>0x</code>", or "<code>3.4e-</code>"), 9483 1.2 lneto it is discarded and the function returns <b>nil</b>. 9484 1.2 lneto </li> 9485 1.2 lneto 9486 1.2 lneto <li><b>"<code>i</code>": </b> 9487 1.2 lneto reads an integral number and returns it as an integer. 9488 1.1 mbalmer </li> 9489 1.1 mbalmer 9490 1.2 lneto <li><b>"<code>a</code>": </b> 9491 1.1 mbalmer reads the whole file, starting at the current position. 9492 1.1 mbalmer On end of file, it returns the empty string. 9493 1.1 mbalmer </li> 9494 1.1 mbalmer 9495 1.2 lneto <li><b>"<code>l</code>": </b> 9496 1.2 lneto reads the next line skipping the end of line, 9497 1.1 mbalmer returning <b>nil</b> on end of file. 9498 1.1 mbalmer This is the default format. 9499 1.1 mbalmer </li> 9500 1.1 mbalmer 9501 1.2 lneto <li><b>"<code>L</code>": </b> 9502 1.2 lneto reads the next line keeping the end-of-line character (if present), 9503 1.2 lneto returning <b>nil</b> on end of file. 9504 1.2 lneto </li> 9505 1.2 lneto 9506 1.2 lneto <li><b><em>number</em>: </b> 9507 1.2 lneto reads a string with up to this number of bytes, 9508 1.1 mbalmer returning <b>nil</b> on end of file. 9509 1.2 lneto If <code>number</code> is zero, 9510 1.1 mbalmer it reads nothing and returns an empty string, 9511 1.1 mbalmer or <b>nil</b> on end of file. 9512 1.1 mbalmer </li> 9513 1.1 mbalmer 9514 1.2 lneto </ul><p> 9515 1.2 lneto The formats "<code>l</code>" and "<code>L</code>" should be used only for text files. 9516 1.2 lneto 9517 1.1 mbalmer 9518 1.1 mbalmer 9519 1.1 mbalmer 9520 1.1 mbalmer <p> 9521 1.2 lneto <hr><h3><a name="pdf-file:seek"><code>file:seek ([whence [, offset]])</code></a></h3> 9522 1.1 mbalmer 9523 1.1 mbalmer 9524 1.1 mbalmer <p> 9525 1.1 mbalmer Sets and gets the file position, 9526 1.1 mbalmer measured from the beginning of the file, 9527 1.1 mbalmer to the position given by <code>offset</code> plus a base 9528 1.1 mbalmer specified by the string <code>whence</code>, as follows: 9529 1.1 mbalmer 9530 1.1 mbalmer <ul> 9531 1.2 lneto <li><b>"<code>set</code>": </b> base is position 0 (beginning of the file);</li> 9532 1.2 lneto <li><b>"<code>cur</code>": </b> base is current position;</li> 9533 1.2 lneto <li><b>"<code>end</code>": </b> base is end of file;</li> 9534 1.1 mbalmer </ul><p> 9535 1.2 lneto In case of success, <code>seek</code> returns the final file position, 9536 1.1 mbalmer measured in bytes from the beginning of the file. 9537 1.2 lneto If <code>seek</code> fails, it returns <b>nil</b>, 9538 1.1 mbalmer plus a string describing the error. 9539 1.1 mbalmer 9540 1.1 mbalmer 9541 1.1 mbalmer <p> 9542 1.1 mbalmer The default value for <code>whence</code> is <code>"cur"</code>, 9543 1.1 mbalmer and for <code>offset</code> is 0. 9544 1.1 mbalmer Therefore, the call <code>file:seek()</code> returns the current 9545 1.1 mbalmer file position, without changing it; 9546 1.1 mbalmer the call <code>file:seek("set")</code> sets the position to the 9547 1.1 mbalmer beginning of the file (and returns 0); 9548 1.1 mbalmer and the call <code>file:seek("end")</code> sets the position to the 9549 1.1 mbalmer end of the file, and returns its size. 9550 1.1 mbalmer 9551 1.1 mbalmer 9552 1.1 mbalmer 9553 1.1 mbalmer 9554 1.1 mbalmer <p> 9555 1.1 mbalmer <hr><h3><a name="pdf-file:setvbuf"><code>file:setvbuf (mode [, size])</code></a></h3> 9556 1.1 mbalmer 9557 1.1 mbalmer 9558 1.1 mbalmer <p> 9559 1.1 mbalmer Sets the buffering mode for an output file. 9560 1.1 mbalmer There are three available modes: 9561 1.1 mbalmer 9562 1.1 mbalmer <ul> 9563 1.1 mbalmer 9564 1.2 lneto <li><b>"<code>no</code>": </b> 9565 1.1 mbalmer no buffering; the result of any output operation appears immediately. 9566 1.1 mbalmer </li> 9567 1.1 mbalmer 9568 1.2 lneto <li><b>"<code>full</code>": </b> 9569 1.1 mbalmer full buffering; output operation is performed only 9570 1.2 lneto when the buffer is full or when 9571 1.2 lneto you explicitly <code>flush</code> the file (see <a href="#pdf-io.flush"><code>io.flush</code></a>). 9572 1.1 mbalmer </li> 9573 1.1 mbalmer 9574 1.2 lneto <li><b>"<code>line</code>": </b> 9575 1.1 mbalmer line buffering; output is buffered until a newline is output 9576 1.1 mbalmer or there is any input from some special files 9577 1.1 mbalmer (such as a terminal device). 9578 1.1 mbalmer </li> 9579 1.1 mbalmer 9580 1.1 mbalmer </ul><p> 9581 1.1 mbalmer For the last two cases, <code>size</code> 9582 1.1 mbalmer specifies the size of the buffer, in bytes. 9583 1.1 mbalmer The default is an appropriate size. 9584 1.1 mbalmer 9585 1.1 mbalmer 9586 1.1 mbalmer 9587 1.1 mbalmer 9588 1.1 mbalmer <p> 9589 1.1 mbalmer <hr><h3><a name="pdf-file:write"><code>file:write (···)</code></a></h3> 9590 1.1 mbalmer 9591 1.1 mbalmer 9592 1.1 mbalmer <p> 9593 1.2 lneto Writes the value of each of its arguments to <code>file</code>. 9594 1.1 mbalmer The arguments must be strings or numbers. 9595 1.2 lneto 9596 1.2 lneto 9597 1.2 lneto <p> 9598 1.2 lneto In case of success, this function returns <code>file</code>. 9599 1.2 lneto Otherwise it returns <b>nil</b> plus a string describing the error. 9600 1.1 mbalmer 9601 1.1 mbalmer 9602 1.1 mbalmer 9603 1.1 mbalmer 9604 1.1 mbalmer 9605 1.1 mbalmer 9606 1.1 mbalmer 9607 1.2 lneto <h2>6.9 – <a name="6.9">Operating System Facilities</a></h2> 9608 1.1 mbalmer 9609 1.1 mbalmer <p> 9610 1.1 mbalmer This library is implemented through table <a name="pdf-os"><code>os</code></a>. 9611 1.1 mbalmer 9612 1.1 mbalmer 9613 1.1 mbalmer <p> 9614 1.1 mbalmer <hr><h3><a name="pdf-os.clock"><code>os.clock ()</code></a></h3> 9615 1.1 mbalmer 9616 1.1 mbalmer 9617 1.1 mbalmer <p> 9618 1.1 mbalmer Returns an approximation of the amount in seconds of CPU time 9619 1.1 mbalmer used by the program. 9620 1.1 mbalmer 9621 1.1 mbalmer 9622 1.1 mbalmer 9623 1.1 mbalmer 9624 1.1 mbalmer <p> 9625 1.1 mbalmer <hr><h3><a name="pdf-os.date"><code>os.date ([format [, time]])</code></a></h3> 9626 1.1 mbalmer 9627 1.1 mbalmer 9628 1.1 mbalmer <p> 9629 1.1 mbalmer Returns a string or a table containing date and time, 9630 1.1 mbalmer formatted according to the given string <code>format</code>. 9631 1.1 mbalmer 9632 1.1 mbalmer 9633 1.1 mbalmer <p> 9634 1.1 mbalmer If the <code>time</code> argument is present, 9635 1.1 mbalmer this is the time to be formatted 9636 1.1 mbalmer (see the <a href="#pdf-os.time"><code>os.time</code></a> function for a description of this value). 9637 1.1 mbalmer Otherwise, <code>date</code> formats the current time. 9638 1.1 mbalmer 9639 1.1 mbalmer 9640 1.1 mbalmer <p> 9641 1.1 mbalmer If <code>format</code> starts with '<code>!</code>', 9642 1.1 mbalmer then the date is formatted in Coordinated Universal Time. 9643 1.1 mbalmer After this optional character, 9644 1.1 mbalmer if <code>format</code> is the string "<code>*t</code>", 9645 1.1 mbalmer then <code>date</code> returns a table with the following fields: 9646 1.2 lneto <code>year</code> (four digits), <code>month</code> (1–12), <code>day</code> (1–31), 9647 1.2 lneto <code>hour</code> (0–23), <code>min</code> (0–59), <code>sec</code> (0–61), 9648 1.1 mbalmer <code>wday</code> (weekday, Sunday is 1), 9649 1.1 mbalmer <code>yday</code> (day of the year), 9650 1.1 mbalmer and <code>isdst</code> (daylight saving flag, a boolean). 9651 1.2 lneto This last field may be absent 9652 1.2 lneto if the information is not available. 9653 1.1 mbalmer 9654 1.1 mbalmer 9655 1.1 mbalmer <p> 9656 1.1 mbalmer If <code>format</code> is not "<code>*t</code>", 9657 1.1 mbalmer then <code>date</code> returns the date as a string, 9658 1.2 lneto formatted according to the same rules as the ANSI C function <code>strftime</code>. 9659 1.1 mbalmer 9660 1.1 mbalmer 9661 1.1 mbalmer <p> 9662 1.1 mbalmer When called without arguments, 9663 1.1 mbalmer <code>date</code> returns a reasonable date and time representation that depends on 9664 1.1 mbalmer the host system and on the current locale 9665 1.1 mbalmer (that is, <code>os.date()</code> is equivalent to <code>os.date("%c")</code>). 9666 1.1 mbalmer 9667 1.1 mbalmer 9668 1.2 lneto <p> 9669 1.2 lneto On non-POSIX systems, 9670 1.2 lneto this function may be not thread safe 9671 1.2 lneto because of its reliance on C function <code>gmtime</code> and C function <code>localtime</code>. 9672 1.2 lneto 9673 1.2 lneto 9674 1.1 mbalmer 9675 1.1 mbalmer 9676 1.1 mbalmer <p> 9677 1.1 mbalmer <hr><h3><a name="pdf-os.difftime"><code>os.difftime (t2, t1)</code></a></h3> 9678 1.1 mbalmer 9679 1.1 mbalmer 9680 1.1 mbalmer <p> 9681 1.1 mbalmer Returns the number of seconds from time <code>t1</code> to time <code>t2</code>. 9682 1.1 mbalmer In POSIX, Windows, and some other systems, 9683 1.1 mbalmer this value is exactly <code>t2</code><em>-</em><code>t1</code>. 9684 1.1 mbalmer 9685 1.1 mbalmer 9686 1.1 mbalmer 9687 1.1 mbalmer 9688 1.1 mbalmer <p> 9689 1.1 mbalmer <hr><h3><a name="pdf-os.execute"><code>os.execute ([command])</code></a></h3> 9690 1.1 mbalmer 9691 1.1 mbalmer 9692 1.1 mbalmer <p> 9693 1.2 lneto This function is equivalent to the ANSI C function <code>system</code>. 9694 1.1 mbalmer It passes <code>command</code> to be executed by an operating system shell. 9695 1.2 lneto Its first result is <b>true</b> 9696 1.2 lneto if the command terminated successfully, 9697 1.2 lneto or <b>nil</b> otherwise. 9698 1.2 lneto After this first result 9699 1.2 lneto the function returns a string plus a number, 9700 1.2 lneto as follows: 9701 1.2 lneto 9702 1.2 lneto <ul> 9703 1.2 lneto 9704 1.2 lneto <li><b>"<code>exit</code>": </b> 9705 1.2 lneto the command terminated normally; 9706 1.2 lneto the following number is the exit status of the command. 9707 1.2 lneto </li> 9708 1.2 lneto 9709 1.2 lneto <li><b>"<code>signal</code>": </b> 9710 1.2 lneto the command was terminated by a signal; 9711 1.2 lneto the following number is the signal that terminated the command. 9712 1.2 lneto </li> 9713 1.2 lneto 9714 1.2 lneto </ul> 9715 1.2 lneto 9716 1.2 lneto <p> 9717 1.2 lneto When called without a <code>command</code>, 9718 1.2 lneto <code>os.execute</code> returns a boolean that is true if a shell is available. 9719 1.2 lneto 9720 1.1 mbalmer 9721 1.1 mbalmer 9722 1.1 mbalmer 9723 1.2 lneto <p> 9724 1.2 lneto <hr><h3><a name="pdf-os.exit"><code>os.exit ([code [, close]])</code></a></h3> 9725 1.2 lneto 9726 1.1 mbalmer 9727 1.1 mbalmer <p> 9728 1.2 lneto Calls the ANSI C function <code>exit</code> to terminate the host program. 9729 1.2 lneto If <code>code</code> is <b>true</b>, 9730 1.2 lneto the returned status is <code>EXIT_SUCCESS</code>; 9731 1.2 lneto if <code>code</code> is <b>false</b>, 9732 1.2 lneto the returned status is <code>EXIT_FAILURE</code>; 9733 1.2 lneto if <code>code</code> is a number, 9734 1.2 lneto the returned status is this number. 9735 1.2 lneto The default value for <code>code</code> is <b>true</b>. 9736 1.1 mbalmer 9737 1.1 mbalmer 9738 1.1 mbalmer <p> 9739 1.2 lneto If the optional second argument <code>close</code> is true, 9740 1.2 lneto closes the Lua state before exiting. 9741 1.1 mbalmer 9742 1.1 mbalmer 9743 1.1 mbalmer 9744 1.1 mbalmer 9745 1.1 mbalmer <p> 9746 1.1 mbalmer <hr><h3><a name="pdf-os.getenv"><code>os.getenv (varname)</code></a></h3> 9747 1.1 mbalmer 9748 1.1 mbalmer 9749 1.1 mbalmer <p> 9750 1.1 mbalmer Returns the value of the process environment variable <code>varname</code>, 9751 1.1 mbalmer or <b>nil</b> if the variable is not defined. 9752 1.1 mbalmer 9753 1.1 mbalmer 9754 1.1 mbalmer 9755 1.1 mbalmer 9756 1.1 mbalmer <p> 9757 1.1 mbalmer <hr><h3><a name="pdf-os.remove"><code>os.remove (filename)</code></a></h3> 9758 1.1 mbalmer 9759 1.1 mbalmer 9760 1.1 mbalmer <p> 9761 1.2 lneto Deletes the file (or empty directory, on POSIX systems) 9762 1.2 lneto with the given name. 9763 1.1 mbalmer If this function fails, it returns <b>nil</b>, 9764 1.2 lneto plus a string describing the error and the error code. 9765 1.1 mbalmer 9766 1.1 mbalmer 9767 1.1 mbalmer 9768 1.1 mbalmer 9769 1.1 mbalmer <p> 9770 1.1 mbalmer <hr><h3><a name="pdf-os.rename"><code>os.rename (oldname, newname)</code></a></h3> 9771 1.1 mbalmer 9772 1.1 mbalmer 9773 1.1 mbalmer <p> 9774 1.1 mbalmer Renames file or directory named <code>oldname</code> to <code>newname</code>. 9775 1.1 mbalmer If this function fails, it returns <b>nil</b>, 9776 1.2 lneto plus a string describing the error and the error code. 9777 1.1 mbalmer 9778 1.1 mbalmer 9779 1.1 mbalmer 9780 1.1 mbalmer 9781 1.1 mbalmer <p> 9782 1.1 mbalmer <hr><h3><a name="pdf-os.setlocale"><code>os.setlocale (locale [, category])</code></a></h3> 9783 1.1 mbalmer 9784 1.1 mbalmer 9785 1.1 mbalmer <p> 9786 1.1 mbalmer Sets the current locale of the program. 9787 1.2 lneto <code>locale</code> is a system-dependent string specifying a locale; 9788 1.1 mbalmer <code>category</code> is an optional string describing which category to change: 9789 1.1 mbalmer <code>"all"</code>, <code>"collate"</code>, <code>"ctype"</code>, 9790 1.1 mbalmer <code>"monetary"</code>, <code>"numeric"</code>, or <code>"time"</code>; 9791 1.1 mbalmer the default category is <code>"all"</code>. 9792 1.1 mbalmer The function returns the name of the new locale, 9793 1.1 mbalmer or <b>nil</b> if the request cannot be honored. 9794 1.1 mbalmer 9795 1.1 mbalmer 9796 1.1 mbalmer <p> 9797 1.1 mbalmer If <code>locale</code> is the empty string, 9798 1.1 mbalmer the current locale is set to an implementation-defined native locale. 9799 1.1 mbalmer If <code>locale</code> is the string "<code>C</code>", 9800 1.1 mbalmer the current locale is set to the standard C locale. 9801 1.1 mbalmer 9802 1.1 mbalmer 9803 1.1 mbalmer <p> 9804 1.1 mbalmer When called with <b>nil</b> as the first argument, 9805 1.1 mbalmer this function only returns the name of the current locale 9806 1.1 mbalmer for the given category. 9807 1.1 mbalmer 9808 1.1 mbalmer 9809 1.2 lneto <p> 9810 1.2 lneto This function may be not thread safe 9811 1.2 lneto because of its reliance on C function <code>setlocale</code>. 9812 1.2 lneto 9813 1.2 lneto 9814 1.1 mbalmer 9815 1.1 mbalmer 9816 1.1 mbalmer <p> 9817 1.1 mbalmer <hr><h3><a name="pdf-os.time"><code>os.time ([table])</code></a></h3> 9818 1.1 mbalmer 9819 1.1 mbalmer 9820 1.1 mbalmer <p> 9821 1.1 mbalmer Returns the current time when called without arguments, 9822 1.1 mbalmer or a time representing the date and time specified by the given table. 9823 1.1 mbalmer This table must have fields <code>year</code>, <code>month</code>, and <code>day</code>, 9824 1.2 lneto and may have fields 9825 1.2 lneto <code>hour</code> (default is 12), 9826 1.2 lneto <code>min</code> (default is 0), 9827 1.2 lneto <code>sec</code> (default is 0), 9828 1.2 lneto and <code>isdst</code> (default is <b>nil</b>). 9829 1.2 lneto For a description of these fields, see the <a href="#pdf-os.date"><code>os.date</code></a> function. 9830 1.1 mbalmer 9831 1.1 mbalmer 9832 1.1 mbalmer <p> 9833 1.1 mbalmer The returned value is a number, whose meaning depends on your system. 9834 1.2 lneto In POSIX, Windows, and some other systems, 9835 1.2 lneto this number counts the number 9836 1.1 mbalmer of seconds since some given start time (the "epoch"). 9837 1.1 mbalmer In other systems, the meaning is not specified, 9838 1.1 mbalmer and the number returned by <code>time</code> can be used only as an argument to 9839 1.2 lneto <a href="#pdf-os.date"><code>os.date</code></a> and <a href="#pdf-os.difftime"><code>os.difftime</code></a>. 9840 1.1 mbalmer 9841 1.1 mbalmer 9842 1.1 mbalmer 9843 1.1 mbalmer 9844 1.1 mbalmer <p> 9845 1.1 mbalmer <hr><h3><a name="pdf-os.tmpname"><code>os.tmpname ()</code></a></h3> 9846 1.1 mbalmer 9847 1.1 mbalmer 9848 1.1 mbalmer <p> 9849 1.1 mbalmer Returns a string with a file name that can 9850 1.1 mbalmer be used for a temporary file. 9851 1.1 mbalmer The file must be explicitly opened before its use 9852 1.1 mbalmer and explicitly removed when no longer needed. 9853 1.1 mbalmer 9854 1.1 mbalmer 9855 1.1 mbalmer <p> 9856 1.2 lneto On POSIX systems, 9857 1.1 mbalmer this function also creates a file with that name, 9858 1.1 mbalmer to avoid security risks. 9859 1.1 mbalmer (Someone else might create the file with wrong permissions 9860 1.1 mbalmer in the time between getting the name and creating the file.) 9861 1.1 mbalmer You still have to open the file to use it 9862 1.1 mbalmer and to remove it (even if you do not use it). 9863 1.1 mbalmer 9864 1.1 mbalmer 9865 1.1 mbalmer <p> 9866 1.1 mbalmer When possible, 9867 1.1 mbalmer you may prefer to use <a href="#pdf-io.tmpfile"><code>io.tmpfile</code></a>, 9868 1.1 mbalmer which automatically removes the file when the program ends. 9869 1.1 mbalmer 9870 1.1 mbalmer 9871 1.1 mbalmer 9872 1.1 mbalmer 9873 1.1 mbalmer 9874 1.1 mbalmer 9875 1.1 mbalmer 9876 1.2 lneto <h2>6.10 – <a name="6.10">The Debug Library</a></h2> 9877 1.1 mbalmer 9878 1.1 mbalmer <p> 9879 1.1 mbalmer This library provides 9880 1.2 lneto the functionality of the debug interface (<a href="#4.9">§4.9</a>) to Lua programs. 9881 1.1 mbalmer You should exert care when using this library. 9882 1.2 lneto Several of its functions 9883 1.2 lneto violate basic assumptions about Lua code 9884 1.1 mbalmer (e.g., that variables local to a function 9885 1.2 lneto cannot be accessed from outside; 9886 1.2 lneto that userdata metatables cannot be changed by Lua code; 9887 1.2 lneto that Lua programs do not crash) 9888 1.1 mbalmer and therefore can compromise otherwise secure code. 9889 1.2 lneto Moreover, some functions in this library may be slow. 9890 1.1 mbalmer 9891 1.1 mbalmer 9892 1.1 mbalmer <p> 9893 1.1 mbalmer All functions in this library are provided 9894 1.1 mbalmer inside the <a name="pdf-debug"><code>debug</code></a> table. 9895 1.1 mbalmer All functions that operate over a thread 9896 1.1 mbalmer have an optional first argument which is the 9897 1.1 mbalmer thread to operate over. 9898 1.1 mbalmer The default is always the current thread. 9899 1.1 mbalmer 9900 1.1 mbalmer 9901 1.1 mbalmer <p> 9902 1.2 lneto <hr><h3><a name="pdf-debug.Csize"><code>debug.Csize (t)</code></a></h3> 9903 1.2 lneto 9904 1.2 lneto 9905 1.2 lneto <p> 9906 1.2 lneto Returns the size of the underlying representation of a given C type, 9907 1.2 lneto according to the following table: 9908 1.2 lneto <table border="1"> 9909 1.2 lneto <tr><td>'<code>I</code>'</td><td><code>lua_Integer</code></td></tr> 9910 1.2 lneto <tr><td>'<code>F</code>'</td><td><code>lua_Number</code></td></tr> 9911 1.2 lneto <tr><td>'<code>b</code>'</td><td><code>byte</code></td></tr> 9912 1.2 lneto <tr><td>'<code>d</code>'</td><td><code>double</code></td></tr> 9913 1.2 lneto <tr><td>'<code>f</code>'</td><td><code>float</code></td></tr> 9914 1.2 lneto <tr><td>'<code>h</code>'</td><td><code>short int</code></td></tr> 9915 1.2 lneto <tr><td>'<code>i</code>'</td><td><code>int</code></td></tr> 9916 1.2 lneto <tr><td>'<code>l</code>'</td><td><code>long int</code></td></tr> 9917 1.2 lneto <tr><td>'<code>z</code>'</td><td><code>size_t</code></td></tr> 9918 1.2 lneto </table> 9919 1.2 lneto For all options except '<code>b</code>', 9920 1.2 lneto the size is given in number of bytes; 9921 1.2 lneto for option '<code>b</code>', 9922 1.2 lneto the size is its number of bits. 9923 1.2 lneto 9924 1.2 lneto 9925 1.2 lneto 9926 1.2 lneto 9927 1.2 lneto <p> 9928 1.1 mbalmer <hr><h3><a name="pdf-debug.debug"><code>debug.debug ()</code></a></h3> 9929 1.1 mbalmer 9930 1.1 mbalmer 9931 1.1 mbalmer <p> 9932 1.1 mbalmer Enters an interactive mode with the user, 9933 1.1 mbalmer running each string that the user enters. 9934 1.1 mbalmer Using simple commands and other debug facilities, 9935 1.1 mbalmer the user can inspect global and local variables, 9936 1.1 mbalmer change their values, evaluate expressions, and so on. 9937 1.1 mbalmer A line containing only the word <code>cont</code> finishes this function, 9938 1.1 mbalmer so that the caller continues its execution. 9939 1.1 mbalmer 9940 1.1 mbalmer 9941 1.1 mbalmer <p> 9942 1.1 mbalmer Note that commands for <code>debug.debug</code> are not lexically nested 9943 1.2 lneto within any function and so have no direct access to local variables. 9944 1.1 mbalmer 9945 1.1 mbalmer 9946 1.1 mbalmer 9947 1.1 mbalmer 9948 1.1 mbalmer <p> 9949 1.1 mbalmer <hr><h3><a name="pdf-debug.gethook"><code>debug.gethook ([thread])</code></a></h3> 9950 1.1 mbalmer 9951 1.1 mbalmer 9952 1.1 mbalmer <p> 9953 1.1 mbalmer Returns the current hook settings of the thread, as three values: 9954 1.1 mbalmer the current hook function, the current hook mask, 9955 1.1 mbalmer and the current hook count 9956 1.1 mbalmer (as set by the <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> function). 9957 1.1 mbalmer 9958 1.1 mbalmer 9959 1.1 mbalmer 9960 1.1 mbalmer 9961 1.1 mbalmer <p> 9962 1.2 lneto <hr><h3><a name="pdf-debug.getinfo"><code>debug.getinfo ([thread,] f [, what])</code></a></h3> 9963 1.1 mbalmer 9964 1.1 mbalmer 9965 1.1 mbalmer <p> 9966 1.1 mbalmer Returns a table with information about a function. 9967 1.2 lneto You can give the function directly 9968 1.2 lneto or you can give a number as the value of <code>f</code>, 9969 1.2 lneto which means the function running at level <code>f</code> of the call stack 9970 1.1 mbalmer of the given thread: 9971 1.1 mbalmer level 0 is the current function (<code>getinfo</code> itself); 9972 1.2 lneto level 1 is the function that called <code>getinfo</code> 9973 1.2 lneto (except for tail calls, which do not count on the stack); 9974 1.1 mbalmer and so on. 9975 1.2 lneto If <code>f</code> is a number larger than the number of active functions, 9976 1.1 mbalmer then <code>getinfo</code> returns <b>nil</b>. 9977 1.1 mbalmer 9978 1.1 mbalmer 9979 1.1 mbalmer <p> 9980 1.1 mbalmer The returned table can contain all the fields returned by <a href="#lua_getinfo"><code>lua_getinfo</code></a>, 9981 1.1 mbalmer with the string <code>what</code> describing which fields to fill in. 9982 1.1 mbalmer The default for <code>what</code> is to get all information available, 9983 1.1 mbalmer except the table of valid lines. 9984 1.1 mbalmer If present, 9985 1.1 mbalmer the option '<code>f</code>' 9986 1.1 mbalmer adds a field named <code>func</code> with the function itself. 9987 1.1 mbalmer If present, 9988 1.1 mbalmer the option '<code>L</code>' 9989 1.1 mbalmer adds a field named <code>activelines</code> with the table of 9990 1.1 mbalmer valid lines. 9991 1.1 mbalmer 9992 1.1 mbalmer 9993 1.1 mbalmer <p> 9994 1.1 mbalmer For instance, the expression <code>debug.getinfo(1,"n").name</code> returns 9995 1.1 mbalmer a table with a name for the current function, 9996 1.1 mbalmer if a reasonable name can be found, 9997 1.1 mbalmer and the expression <code>debug.getinfo(print)</code> 9998 1.1 mbalmer returns a table with all available information 9999 1.1 mbalmer about the <a href="#pdf-print"><code>print</code></a> function. 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-debug.getlocal"><code>debug.getlocal ([thread,] f, local)</code></a></h3> 10006 1.1 mbalmer 10007 1.1 mbalmer 10008 1.1 mbalmer <p> 10009 1.1 mbalmer This function returns the name and the value of the local variable 10010 1.2 lneto with index <code>local</code> of the function at level <code>f</code> of the stack. 10011 1.2 lneto This function accesses not only explicit local variables, 10012 1.2 lneto but also parameters, temporaries, etc. 10013 1.2 lneto 10014 1.2 lneto 10015 1.2 lneto <p> 10016 1.2 lneto The first parameter or local variable has index 1, and so on, 10017 1.2 lneto until the last active variable. 10018 1.2 lneto Negative indices refer to vararg parameters; 10019 1.2 lneto -1 is the first vararg parameter. 10020 1.2 lneto The function returns <b>nil</b> if there is no variable with the given index, 10021 1.2 lneto and raises an error when called with a level out of range. 10022 1.1 mbalmer (You can call <a href="#pdf-debug.getinfo"><code>debug.getinfo</code></a> to check whether the level is valid.) 10023 1.1 mbalmer 10024 1.1 mbalmer 10025 1.1 mbalmer <p> 10026 1.2 lneto Variable names starting with '<code>(</code>' (open parenthesis) 10027 1.2 lneto represent variables with no known names 10028 1.2 lneto (internal variables like loop control variables, 10029 1.2 lneto and variables from chunks saved without debug information). 10030 1.2 lneto 10031 1.2 lneto 10032 1.2 lneto <p> 10033 1.2 lneto The parameter <code>f</code> may also be a function. 10034 1.2 lneto In that case, <code>getlocal</code> returns only the name of function parameters. 10035 1.1 mbalmer 10036 1.1 mbalmer 10037 1.1 mbalmer 10038 1.1 mbalmer 10039 1.1 mbalmer <p> 10040 1.2 lneto <hr><h3><a name="pdf-debug.getmetatable"><code>debug.getmetatable (value)</code></a></h3> 10041 1.1 mbalmer 10042 1.1 mbalmer 10043 1.1 mbalmer <p> 10044 1.2 lneto Returns the metatable of the given <code>value</code> 10045 1.1 mbalmer or <b>nil</b> if it does not have a metatable. 10046 1.1 mbalmer 10047 1.1 mbalmer 10048 1.1 mbalmer 10049 1.1 mbalmer 10050 1.1 mbalmer <p> 10051 1.1 mbalmer <hr><h3><a name="pdf-debug.getregistry"><code>debug.getregistry ()</code></a></h3> 10052 1.1 mbalmer 10053 1.1 mbalmer 10054 1.1 mbalmer <p> 10055 1.2 lneto Returns the registry table (see <a href="#4.5">§4.5</a>). 10056 1.1 mbalmer 10057 1.1 mbalmer 10058 1.1 mbalmer 10059 1.1 mbalmer 10060 1.1 mbalmer <p> 10061 1.2 lneto <hr><h3><a name="pdf-debug.getupvalue"><code>debug.getupvalue (f, up)</code></a></h3> 10062 1.1 mbalmer 10063 1.1 mbalmer 10064 1.1 mbalmer <p> 10065 1.1 mbalmer This function returns the name and the value of the upvalue 10066 1.2 lneto with index <code>up</code> of the function <code>f</code>. 10067 1.1 mbalmer The function returns <b>nil</b> if there is no upvalue with the given index. 10068 1.1 mbalmer 10069 1.1 mbalmer 10070 1.2 lneto <p> 10071 1.2 lneto Variable names starting with '<code>(</code>' (open parenthesis) 10072 1.2 lneto represent variables with no known names 10073 1.2 lneto (variables from chunks saved without debug information). 10074 1.2 lneto 10075 1.2 lneto 10076 1.1 mbalmer 10077 1.1 mbalmer 10078 1.1 mbalmer <p> 10079 1.2 lneto <hr><h3><a name="pdf-debug.getuservalue"><code>debug.getuservalue (u)</code></a></h3> 10080 1.1 mbalmer 10081 1.1 mbalmer 10082 1.1 mbalmer <p> 10083 1.2 lneto Returns the Lua value associated to <code>u</code>. 10084 1.2 lneto If <code>u</code> is not a userdata, 10085 1.2 lneto returns <b>nil</b>. 10086 1.1 mbalmer 10087 1.1 mbalmer 10088 1.1 mbalmer 10089 1.1 mbalmer 10090 1.1 mbalmer <p> 10091 1.1 mbalmer <hr><h3><a name="pdf-debug.sethook"><code>debug.sethook ([thread,] hook, mask [, count])</code></a></h3> 10092 1.1 mbalmer 10093 1.1 mbalmer 10094 1.1 mbalmer <p> 10095 1.1 mbalmer Sets the given function as a hook. 10096 1.1 mbalmer The string <code>mask</code> and the number <code>count</code> describe 10097 1.1 mbalmer when the hook will be called. 10098 1.2 lneto The string mask may have any combination of the following characters, 10099 1.1 mbalmer with the given meaning: 10100 1.1 mbalmer 10101 1.1 mbalmer <ul> 10102 1.2 lneto <li><b>'<code>c</code>': </b> the hook is called every time Lua calls a function;</li> 10103 1.2 lneto <li><b>'<code>r</code>': </b> the hook is called every time Lua returns from a function;</li> 10104 1.2 lneto <li><b>'<code>l</code>': </b> the hook is called every time Lua enters a new line of code.</li> 10105 1.1 mbalmer </ul><p> 10106 1.2 lneto Moreover, 10107 1.2 lneto with a <code>count</code> different from zero, 10108 1.2 lneto the hook is called also after every <code>count</code> instructions. 10109 1.1 mbalmer 10110 1.1 mbalmer 10111 1.1 mbalmer <p> 10112 1.1 mbalmer When called without arguments, 10113 1.1 mbalmer <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> turns off the hook. 10114 1.1 mbalmer 10115 1.1 mbalmer 10116 1.1 mbalmer <p> 10117 1.1 mbalmer When the hook is called, its first parameter is a string 10118 1.1 mbalmer describing the event that has triggered its call: 10119 1.2 lneto <code>"call"</code> (or <code>"tail call"</code>), 10120 1.2 lneto <code>"return"</code>, 10121 1.1 mbalmer <code>"line"</code>, and <code>"count"</code>. 10122 1.1 mbalmer For line events, 10123 1.1 mbalmer the hook also gets the new line number as its second parameter. 10124 1.1 mbalmer Inside a hook, 10125 1.1 mbalmer you can call <code>getinfo</code> with level 2 to get more information about 10126 1.1 mbalmer the running function 10127 1.1 mbalmer (level 0 is the <code>getinfo</code> function, 10128 1.2 lneto and level 1 is the hook function). 10129 1.1 mbalmer 10130 1.1 mbalmer 10131 1.1 mbalmer 10132 1.1 mbalmer 10133 1.1 mbalmer <p> 10134 1.1 mbalmer <hr><h3><a name="pdf-debug.setlocal"><code>debug.setlocal ([thread,] level, local, value)</code></a></h3> 10135 1.1 mbalmer 10136 1.1 mbalmer 10137 1.1 mbalmer <p> 10138 1.1 mbalmer This function assigns the value <code>value</code> to the local variable 10139 1.1 mbalmer with index <code>local</code> of the function at level <code>level</code> of the stack. 10140 1.1 mbalmer The function returns <b>nil</b> if there is no local 10141 1.1 mbalmer variable with the given index, 10142 1.1 mbalmer and raises an error when called with a <code>level</code> out of range. 10143 1.1 mbalmer (You can call <code>getinfo</code> to check whether the level is valid.) 10144 1.1 mbalmer Otherwise, it returns the name of the local variable. 10145 1.1 mbalmer 10146 1.1 mbalmer 10147 1.2 lneto <p> 10148 1.2 lneto See <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for more information about 10149 1.2 lneto variable indices and names. 10150 1.2 lneto 10151 1.2 lneto 10152 1.1 mbalmer 10153 1.1 mbalmer 10154 1.1 mbalmer <p> 10155 1.2 lneto <hr><h3><a name="pdf-debug.setmetatable"><code>debug.setmetatable (value, table)</code></a></h3> 10156 1.1 mbalmer 10157 1.1 mbalmer 10158 1.1 mbalmer <p> 10159 1.2 lneto Sets the metatable for the given <code>value</code> to the given <code>table</code> 10160 1.1 mbalmer (which can be <b>nil</b>). 10161 1.2 lneto Returns <code>value</code>. 10162 1.1 mbalmer 10163 1.1 mbalmer 10164 1.1 mbalmer 10165 1.1 mbalmer 10166 1.1 mbalmer <p> 10167 1.2 lneto <hr><h3><a name="pdf-debug.setupvalue"><code>debug.setupvalue (f, up, value)</code></a></h3> 10168 1.1 mbalmer 10169 1.1 mbalmer 10170 1.1 mbalmer <p> 10171 1.1 mbalmer This function assigns the value <code>value</code> to the upvalue 10172 1.2 lneto with index <code>up</code> of the function <code>f</code>. 10173 1.1 mbalmer The function returns <b>nil</b> if there is no upvalue 10174 1.1 mbalmer with the given index. 10175 1.1 mbalmer Otherwise, it returns the name of the upvalue. 10176 1.1 mbalmer 10177 1.1 mbalmer 10178 1.1 mbalmer 10179 1.1 mbalmer 10180 1.1 mbalmer <p> 10181 1.2 lneto <hr><h3><a name="pdf-debug.setuservalue"><code>debug.setuservalue (udata, value)</code></a></h3> 10182 1.2 lneto 10183 1.2 lneto 10184 1.2 lneto <p> 10185 1.2 lneto Sets the given <code>value</code> as 10186 1.2 lneto the Lua value associated to the given <code>udata</code>. 10187 1.2 lneto <code>udata</code> must be a full userdata. 10188 1.2 lneto 10189 1.2 lneto 10190 1.2 lneto <p> 10191 1.2 lneto Returns <code>udata</code>. 10192 1.2 lneto 10193 1.2 lneto 10194 1.2 lneto 10195 1.2 lneto 10196 1.2 lneto <p> 10197 1.2 lneto <hr><h3><a name="pdf-debug.traceback"><code>debug.traceback ([thread,] [message [, level]])</code></a></h3> 10198 1.1 mbalmer 10199 1.1 mbalmer 10200 1.1 mbalmer <p> 10201 1.2 lneto If <code>message</code> is present but is neither a string nor <b>nil</b>, 10202 1.2 lneto this function returns <code>message</code> without further processing. 10203 1.2 lneto Otherwise, 10204 1.2 lneto it returns a string with a traceback of the call stack. 10205 1.1 mbalmer An optional <code>message</code> string is appended 10206 1.1 mbalmer at the beginning of the traceback. 10207 1.1 mbalmer An optional <code>level</code> number tells at which level 10208 1.1 mbalmer to start the traceback 10209 1.1 mbalmer (default is 1, the function calling <code>traceback</code>). 10210 1.1 mbalmer 10211 1.1 mbalmer 10212 1.1 mbalmer 10213 1.1 mbalmer 10214 1.2 lneto <p> 10215 1.2 lneto <hr><h3><a name="pdf-debug.upvalueid"><code>debug.upvalueid (f, n)</code></a></h3> 10216 1.2 lneto 10217 1.2 lneto 10218 1.2 lneto <p> 10219 1.2 lneto Returns an unique identifier (as a light userdata) 10220 1.2 lneto for the upvalue numbered <code>n</code> 10221 1.2 lneto from the given function. 10222 1.2 lneto 10223 1.2 lneto 10224 1.2 lneto <p> 10225 1.2 lneto These unique identifiers allow a program to check whether different 10226 1.2 lneto closures share upvalues. 10227 1.2 lneto Lua closures that share an upvalue 10228 1.2 lneto (that is, that access a same external local variable) 10229 1.2 lneto will return identical ids for those upvalue indices. 10230 1.2 lneto 10231 1.2 lneto 10232 1.2 lneto 10233 1.2 lneto 10234 1.2 lneto <p> 10235 1.2 lneto <hr><h3><a name="pdf-debug.upvaluejoin"><code>debug.upvaluejoin (f1, n1, f2, n2)</code></a></h3> 10236 1.2 lneto 10237 1.2 lneto 10238 1.2 lneto <p> 10239 1.2 lneto Make the <code>n1</code>-th upvalue of the Lua closure <code>f1</code> 10240 1.2 lneto refer to the <code>n2</code>-th upvalue of the Lua closure <code>f2</code>. 10241 1.2 lneto 10242 1.2 lneto 10243 1.2 lneto 10244 1.2 lneto 10245 1.1 mbalmer 10246 1.1 mbalmer 10247 1.1 mbalmer 10248 1.2 lneto <h1>7 – <a name="7">Lua Standalone</a></h1> 10249 1.1 mbalmer 10250 1.1 mbalmer <p> 10251 1.1 mbalmer Although Lua has been designed as an extension language, 10252 1.1 mbalmer to be embedded in a host C program, 10253 1.2 lneto it is also frequently used as a standalone language. 10254 1.2 lneto An interpreter for Lua as a standalone language, 10255 1.1 mbalmer called simply <code>lua</code>, 10256 1.1 mbalmer is provided with the standard distribution. 10257 1.2 lneto The standalone interpreter includes 10258 1.1 mbalmer all standard libraries, including the debug library. 10259 1.1 mbalmer Its usage is: 10260 1.1 mbalmer 10261 1.1 mbalmer <pre> 10262 1.1 mbalmer lua [options] [script [args]] 10263 1.1 mbalmer </pre><p> 10264 1.1 mbalmer The options are: 10265 1.1 mbalmer 10266 1.1 mbalmer <ul> 10267 1.2 lneto <li><b><code>-e <em>stat</em></code>: </b> executes string <em>stat</em>;</li> 10268 1.2 lneto <li><b><code>-l <em>mod</em></code>: </b> "requires" <em>mod</em>;</li> 10269 1.2 lneto <li><b><code>-i</code>: </b> enters interactive mode after running <em>script</em>;</li> 10270 1.2 lneto <li><b><code>-v</code>: </b> prints version information;</li> 10271 1.2 lneto <li><b><code>-E</code>: </b> ignores environment variables;</li> 10272 1.2 lneto <li><b><code>--</code>: </b> stops handling options;</li> 10273 1.2 lneto <li><b><code>-</code>: </b> executes <code>stdin</code> as a file and stops handling options.</li> 10274 1.1 mbalmer </ul><p> 10275 1.1 mbalmer After handling its options, <code>lua</code> runs the given <em>script</em>, 10276 1.1 mbalmer passing to it the given <em>args</em> as string arguments. 10277 1.1 mbalmer When called without arguments, 10278 1.1 mbalmer <code>lua</code> behaves as <code>lua -v -i</code> 10279 1.1 mbalmer when the standard input (<code>stdin</code>) is a terminal, 10280 1.1 mbalmer and as <code>lua -</code> otherwise. 10281 1.1 mbalmer 10282 1.1 mbalmer 10283 1.1 mbalmer <p> 10284 1.2 lneto When called without option <code>-E</code>, 10285 1.2 lneto the interpreter checks for an environment variable <a name="pdf-LUA_INIT_5_3"><code>LUA_INIT_5_3</code></a> 10286 1.2 lneto (or <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a> if it is not defined) 10287 1.2 lneto before running any argument. 10288 1.2 lneto If the variable content has the format <code>@<em>filename</em></code>, 10289 1.1 mbalmer then <code>lua</code> executes the file. 10290 1.1 mbalmer Otherwise, <code>lua</code> executes the string itself. 10291 1.1 mbalmer 10292 1.1 mbalmer 10293 1.1 mbalmer <p> 10294 1.2 lneto When called with option <code>-E</code>, 10295 1.2 lneto besides ignoring <code>LUA_INIT</code>, 10296 1.2 lneto Lua also ignores 10297 1.2 lneto the values of <code>LUA_PATH</code> and <code>LUA_CPATH</code>, 10298 1.2 lneto setting the values of 10299 1.2 lneto <a href="#pdf-package.path"><code>package.path</code></a> and <a href="#pdf-package.cpath"><code>package.cpath</code></a> 10300 1.2 lneto with the default paths defined in <code>luaconf.h</code>. 10301 1.2 lneto 10302 1.2 lneto 10303 1.2 lneto <p> 10304 1.2 lneto All options are handled in order, except <code>-i</code> and <code>-E</code>. 10305 1.1 mbalmer For instance, an invocation like 10306 1.1 mbalmer 10307 1.1 mbalmer <pre> 10308 1.1 mbalmer $ lua -e'a=1' -e 'print(a)' script.lua 10309 1.1 mbalmer </pre><p> 10310 1.2 lneto will first set <code>a</code> to 1, then print the value of <code>a</code>, 10311 1.1 mbalmer and finally run the file <code>script.lua</code> with no arguments. 10312 1.1 mbalmer (Here <code>$</code> is the shell prompt. Your prompt may be different.) 10313 1.1 mbalmer 10314 1.1 mbalmer 10315 1.1 mbalmer <p> 10316 1.2 lneto Before running any code, 10317 1.2 lneto <code>lua</code> collects all command-line arguments 10318 1.1 mbalmer in a global table called <code>arg</code>. 10319 1.2 lneto The script name goes to index 0, 10320 1.1 mbalmer the first argument after the script name goes to index 1, 10321 1.1 mbalmer and so on. 10322 1.1 mbalmer Any arguments before the script name 10323 1.2 lneto (that is, the interpreter name plus its options) 10324 1.1 mbalmer go to negative indices. 10325 1.1 mbalmer For instance, in the call 10326 1.1 mbalmer 10327 1.1 mbalmer <pre> 10328 1.1 mbalmer $ lua -la b.lua t1 t2 10329 1.1 mbalmer </pre><p> 10330 1.2 lneto the table is like this: 10331 1.1 mbalmer 10332 1.1 mbalmer <pre> 10333 1.1 mbalmer arg = { [-2] = "lua", [-1] = "-la", 10334 1.1 mbalmer [0] = "b.lua", 10335 1.1 mbalmer [1] = "t1", [2] = "t2" } 10336 1.1 mbalmer </pre><p> 10337 1.2 lneto If there is no script in the call, 10338 1.2 lneto the interpreter name goes to index 0, 10339 1.2 lneto followed by the other arguments. 10340 1.2 lneto For instance, the call 10341 1.2 lneto 10342 1.2 lneto <pre> 10343 1.2 lneto $ lua -e "print(arg[1])" 10344 1.2 lneto </pre><p> 10345 1.2 lneto will print "<code>-e</code>". 10346 1.1 mbalmer 10347 1.1 mbalmer 10348 1.1 mbalmer <p> 10349 1.1 mbalmer In interactive mode, 10350 1.2 lneto Lua repeatedly prompts and waits for a line. 10351 1.2 lneto After reading a line, 10352 1.2 lneto Lua first try to interpret the line as an expression. 10353 1.2 lneto If it succeeds, it prints its value. 10354 1.2 lneto Otherwise, it interprets the line as a statement. 10355 1.2 lneto If you write an incomplete statement, 10356 1.1 mbalmer the interpreter waits for its completion 10357 1.1 mbalmer by issuing a different prompt. 10358 1.1 mbalmer 10359 1.1 mbalmer 10360 1.1 mbalmer <p> 10361 1.2 lneto In case of unprotected errors in the script, 10362 1.2 lneto the interpreter reports the error to the standard error stream. 10363 1.2 lneto If the error object is a string, 10364 1.2 lneto the interpreter adds a stack traceback to it. 10365 1.2 lneto Otherwise, if the error object has a metamethod <code>__tostring</code>, 10366 1.2 lneto the interpreter calls this metamethod to produce the final message. 10367 1.2 lneto Finally, if the error object is <b>nil</b>, 10368 1.2 lneto the interpreter does not report the error. 10369 1.2 lneto 10370 1.2 lneto 10371 1.2 lneto <p> 10372 1.2 lneto When finishing normally, 10373 1.2 lneto the interpreter closes its main Lua state 10374 1.2 lneto (see <a href="#lua_close"><code>lua_close</code></a>). 10375 1.2 lneto The script can avoid this step by 10376 1.2 lneto calling <a href="#pdf-os.exit"><code>os.exit</code></a> to terminate. 10377 1.1 mbalmer 10378 1.1 mbalmer 10379 1.1 mbalmer <p> 10380 1.1 mbalmer To allow the use of Lua as a 10381 1.1 mbalmer script interpreter in Unix systems, 10382 1.2 lneto the standalone interpreter skips 10383 1.1 mbalmer the first line of a chunk if it starts with <code>#</code>. 10384 1.1 mbalmer Therefore, Lua scripts can be made into executable programs 10385 1.1 mbalmer by using <code>chmod +x</code> and the <code>#!</code> form, 10386 1.1 mbalmer as in 10387 1.1 mbalmer 10388 1.1 mbalmer <pre> 10389 1.1 mbalmer #!/usr/local/bin/lua 10390 1.1 mbalmer </pre><p> 10391 1.1 mbalmer (Of course, 10392 1.1 mbalmer the location of the Lua interpreter may be different in your machine. 10393 1.1 mbalmer If <code>lua</code> is in your <code>PATH</code>, 10394 1.2 lneto then 10395 1.1 mbalmer 10396 1.1 mbalmer <pre> 10397 1.1 mbalmer #!/usr/bin/env lua 10398 1.1 mbalmer </pre><p> 10399 1.2 lneto is a more portable solution.) 10400 1.1 mbalmer 10401 1.1 mbalmer 10402 1.1 mbalmer 10403 1.2 lneto <h1>8 – <a name="8">Incompatibilities with the Previous Version</a></h1> 10404 1.1 mbalmer 10405 1.1 mbalmer <p> 10406 1.1 mbalmer Here we list the incompatibilities that you may find when moving a program 10407 1.2 lneto from Lua 5.2 to Lua 5.3. 10408 1.2 lneto You can avoid some incompatibilities by compiling Lua with 10409 1.1 mbalmer appropriate options (see file <code>luaconf.h</code>). 10410 1.1 mbalmer However, 10411 1.2 lneto all these compatibility options will be removed in the future. 10412 1.1 mbalmer 10413 1.1 mbalmer 10414 1.2 lneto <p> 10415 1.2 lneto Lua versions can always change the C API in ways that 10416 1.2 lneto do not imply source-code changes in a program, 10417 1.2 lneto such as the numeric values for constants 10418 1.2 lneto or the implementation of functions as macros. 10419 1.2 lneto Therefore, 10420 1.2 lneto you should never assume that binaries are compatible between 10421 1.2 lneto different Lua versions. 10422 1.2 lneto Always recompile clients of the Lua API when 10423 1.2 lneto using a new version. 10424 1.1 mbalmer 10425 1.1 mbalmer 10426 1.2 lneto <p> 10427 1.2 lneto Similarly, Lua versions can always change the internal representation 10428 1.2 lneto of precompiled chunks; 10429 1.2 lneto precompiled chunks are never compatible between different Lua versions. 10430 1.1 mbalmer 10431 1.1 mbalmer 10432 1.2 lneto <p> 10433 1.2 lneto The standard paths in the official distribution may 10434 1.2 lneto change between versions. 10435 1.1 mbalmer 10436 1.1 mbalmer 10437 1.1 mbalmer 10438 1.2 lneto <h2>8.1 – <a name="8.1">Changes in the Language</a></h2> 10439 1.1 mbalmer <ul> 10440 1.1 mbalmer 10441 1.1 mbalmer <li> 10442 1.2 lneto The main difference between Lua 5.2 and Lua 5.3 is the 10443 1.2 lneto introduction of an integer subtype for numbers. 10444 1.2 lneto Although this change should not affect "normal" computations, 10445 1.2 lneto some computations 10446 1.2 lneto (mainly those that involve some kind of overflow) 10447 1.2 lneto can give different results. 10448 1.2 lneto 10449 1.1 mbalmer 10450 1.2 lneto <p> 10451 1.2 lneto You can fix these differences by forcing a number to be a float 10452 1.2 lneto (in Lua 5.2 all numbers were float), 10453 1.2 lneto in particular writing constants with an ending <code>.0</code> 10454 1.2 lneto or using <code>x = x + 0.0</code> to convert a variable. 10455 1.2 lneto (This recommendation is only for a quick fix 10456 1.2 lneto for an occasional incompatibility; 10457 1.2 lneto it is not a general guideline for good programming. 10458 1.2 lneto For good programming, 10459 1.2 lneto use floats where you need floats 10460 1.2 lneto and integers where you need integers.) 10461 1.1 mbalmer 10462 1.1 mbalmer 10463 1.2 lneto <p> 10464 1.2 lneto Although not formally an incompatibility, 10465 1.2 lneto the proper differentiation between floats and integers 10466 1.2 lneto have an impact on performance. 10467 1.1 mbalmer </li> 10468 1.1 mbalmer 10469 1.1 mbalmer <li> 10470 1.2 lneto The conversion of a float to a string now adds a <code>.0</code> suffix 10471 1.2 lneto to the result if it looks like an integer. 10472 1.2 lneto (For instance, the float 2.0 will be printed as <code>2.0</code>, 10473 1.2 lneto not as <code>2</code>.) 10474 1.2 lneto You should always use an explicit format 10475 1.2 lneto when you need a specific format for numbers. 10476 1.1 mbalmer 10477 1.1 mbalmer 10478 1.2 lneto <p> 10479 1.2 lneto (Formally this is not an incompatibility, 10480 1.2 lneto because Lua does not specify how numbers are formatted as strings, 10481 1.2 lneto but some programs assumed a specific format.) 10482 1.1 mbalmer </li> 10483 1.1 mbalmer 10484 1.1 mbalmer <li> 10485 1.2 lneto The generational mode for the garbage collector was removed. 10486 1.2 lneto (It was an experimental feature in Lua 5.2.) 10487 1.1 mbalmer </li> 10488 1.1 mbalmer 10489 1.1 mbalmer </ul> 10490 1.1 mbalmer 10491 1.1 mbalmer 10492 1.1 mbalmer 10493 1.1 mbalmer 10494 1.2 lneto <h2>8.2 – <a name="8.2">Changes in the Libraries</a></h2> 10495 1.1 mbalmer <ul> 10496 1.1 mbalmer 10497 1.1 mbalmer <li> 10498 1.2 lneto The <code>bit32</code> library has been deprecated. 10499 1.2 lneto It is easy to require a compatible external library or, 10500 1.2 lneto better yet, to replace its functions with appropriate bitwise operations. 10501 1.2 lneto (Keep in mind that <code>bit32</code> operates on 32-bit integers, 10502 1.2 lneto while the bitwise operators in Standard Lua operate on 64-bit integers.) 10503 1.1 mbalmer </li> 10504 1.1 mbalmer 10505 1.1 mbalmer <li> 10506 1.2 lneto Option names in <a href="#pdf-io.read"><code>io.read</code></a> do not have a starting '<code>*</code>' anymore. 10507 1.2 lneto For compatibility, Lua will continue to ignore this character. 10508 1.1 mbalmer </li> 10509 1.1 mbalmer 10510 1.1 mbalmer <li> 10511 1.2 lneto The following functions were deprecated in the mathematical library: 10512 1.2 lneto <code>atan2</code>, <code>cosh</code>, <code>sinh</code>, <code>tanh</code>, <code>pow</code>, 10513 1.2 lneto <code>frexp</code>, and <code>ldexp</code>. 10514 1.2 lneto You can replace <code>math.pow(x,y)</code> with <code>x^y</code>; 10515 1.2 lneto you can replace <code>math.atan2</code> with <code>math.atan</code>, 10516 1.2 lneto which now accepts two parameters; 10517 1.2 lneto you can replace <code>math.ldexp(x,exp)</code> with <code>x * 2.0^exp</code>. 10518 1.2 lneto For the other operations, 10519 1.2 lneto the best choice is to use an external library. 10520 1.1 mbalmer </li> 10521 1.1 mbalmer 10522 1.2 lneto </ul> 10523 1.2 lneto 10524 1.2 lneto 10525 1.2 lneto 10526 1.2 lneto 10527 1.2 lneto <h2>8.3 – <a name="8.3">Changes in the API</a></h2> 10528 1.2 lneto 10529 1.2 lneto 10530 1.2 lneto <ul> 10531 1.2 lneto 10532 1.1 mbalmer <li> 10533 1.2 lneto Continuation functions now receive as parameters what they needed 10534 1.2 lneto to get through <code>lua_getctx</code>, 10535 1.2 lneto so <code>lua_getctx</code> has been removed. 10536 1.2 lneto Adapt your code accordingly. 10537 1.1 mbalmer </li> 10538 1.1 mbalmer 10539 1.1 mbalmer <li> 10540 1.2 lneto Function <a href="#lua_dump"><code>lua_dump</code></a> has an extra parameter, <code>strip</code>. 10541 1.2 lneto Use 0 as the value of this parameter to get the old behavior. 10542 1.1 mbalmer </li> 10543 1.1 mbalmer 10544 1.1 mbalmer </ul> 10545 1.1 mbalmer 10546 1.1 mbalmer 10547 1.1 mbalmer 10548 1.1 mbalmer 10549 1.2 lneto <h1>9 – <a name="9">The Complete Syntax of Lua</a></h1> 10550 1.1 mbalmer 10551 1.1 mbalmer <p> 10552 1.1 mbalmer Here is the complete syntax of Lua in extended BNF. 10553 1.1 mbalmer (It does not describe operator precedences.) 10554 1.1 mbalmer 10555 1.1 mbalmer 10556 1.1 mbalmer 10557 1.1 mbalmer 10558 1.1 mbalmer <pre> 10559 1.1 mbalmer 10560 1.2 lneto chunk ::= block 10561 1.1 mbalmer 10562 1.2 lneto block ::= {stat} [retstat] 10563 1.1 mbalmer 10564 1.2 lneto stat ::= ‘<b>;</b>’ | 10565 1.2 lneto varlist ‘<b>=</b>’ explist | 10566 1.1 mbalmer functioncall | 10567 1.2 lneto label | 10568 1.2 lneto <b>break</b> | 10569 1.2 lneto <b>goto</b> Name | 10570 1.1 mbalmer <b>do</b> block <b>end</b> | 10571 1.1 mbalmer <b>while</b> exp <b>do</b> block <b>end</b> | 10572 1.1 mbalmer <b>repeat</b> block <b>until</b> exp | 10573 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> | 10574 1.2 lneto <b>for</b> Name ‘<b>=</b>’ exp ‘<b>,</b>’ exp [‘<b>,</b>’ exp] <b>do</b> block <b>end</b> | 10575 1.1 mbalmer <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> | 10576 1.1 mbalmer <b>function</b> funcname funcbody | 10577 1.1 mbalmer <b>local</b> <b>function</b> Name funcbody | 10578 1.2 lneto <b>local</b> namelist [‘<b>=</b>’ explist] 10579 1.1 mbalmer 10580 1.2 lneto retstat ::= <b>return</b> [explist] [‘<b>;</b>’] 10581 1.1 mbalmer 10582 1.2 lneto label ::= ‘<b>::</b>’ Name ‘<b>::</b>’ 10583 1.1 mbalmer 10584 1.2 lneto funcname ::= Name {‘<b>.</b>’ Name} [‘<b>:</b>’ Name] 10585 1.1 mbalmer 10586 1.2 lneto varlist ::= var {‘<b>,</b>’ var} 10587 1.1 mbalmer 10588 1.2 lneto var ::= Name | prefixexp ‘<b>[</b>’ exp ‘<b>]</b>’ | prefixexp ‘<b>.</b>’ Name 10589 1.1 mbalmer 10590 1.2 lneto namelist ::= Name {‘<b>,</b>’ Name} 10591 1.1 mbalmer 10592 1.2 lneto explist ::= exp {‘<b>,</b>’ exp} 10593 1.2 lneto 10594 1.2 lneto exp ::= <b>nil</b> | <b>false</b> | <b>true</b> | Number | String | ‘<b>...</b>’ | functiondef | 10595 1.1 mbalmer prefixexp | tableconstructor | exp binop exp | unop exp 10596 1.1 mbalmer 10597 1.2 lneto prefixexp ::= var | functioncall | ‘<b>(</b>’ exp ‘<b>)</b>’ 10598 1.1 mbalmer 10599 1.2 lneto functioncall ::= prefixexp args | prefixexp ‘<b>:</b>’ Name args 10600 1.1 mbalmer 10601 1.2 lneto args ::= ‘<b>(</b>’ [explist] ‘<b>)</b>’ | tableconstructor | String 10602 1.1 mbalmer 10603 1.2 lneto functiondef ::= <b>function</b> funcbody 10604 1.1 mbalmer 10605 1.2 lneto funcbody ::= ‘<b>(</b>’ [parlist] ‘<b>)</b>’ block <b>end</b> 10606 1.1 mbalmer 10607 1.2 lneto parlist ::= namelist [‘<b>,</b>’ ‘<b>...</b>’] | ‘<b>...</b>’ 10608 1.1 mbalmer 10609 1.2 lneto tableconstructor ::= ‘<b>{</b>’ [fieldlist] ‘<b>}</b>’ 10610 1.1 mbalmer 10611 1.1 mbalmer fieldlist ::= field {fieldsep field} [fieldsep] 10612 1.1 mbalmer 10613 1.2 lneto field ::= ‘<b>[</b>’ exp ‘<b>]</b>’ ‘<b>=</b>’ exp | Name ‘<b>=</b>’ exp | exp 10614 1.1 mbalmer 10615 1.2 lneto fieldsep ::= ‘<b>,</b>’ | ‘<b>;</b>’ 10616 1.1 mbalmer 10617 1.2 lneto binop ::= ‘<b>+</b>’ | ‘<b>-</b>’ | ‘<b>*</b>’ | ‘<b>/</b>’ | ‘<b>//</b>’ | ‘<b>^</b>’ | ‘<b>%</b>’ | 10618 1.2 lneto ‘<b>&</b>’ | ‘<b>~</b>’ | ‘<b>|</b>’ | ‘<b>>></b>’ | ‘<b><<</b>’ | ‘<b>..</b>’ | 10619 1.2 lneto ‘<b><</b>’ | ‘<b><=</b>’ | ‘<b>></b>’ | ‘<b>>=</b>’ | ‘<b>==</b>’ | ‘<b>~=</b>’ | 10620 1.1 mbalmer <b>and</b> | <b>or</b> 10621 1.1 mbalmer 10622 1.2 lneto unop ::= ‘<b>-</b>’ | <b>not</b> | ‘<b>#</b>’ | ‘<b>~</b>’ 10623 1.1 mbalmer 10624 1.1 mbalmer </pre> 10625 1.1 mbalmer 10626 1.1 mbalmer <p> 10627 1.1 mbalmer 10628 1.1 mbalmer 10629 1.1 mbalmer 10630 1.1 mbalmer 10631 1.1 mbalmer 10632 1.1 mbalmer 10633 1.1 mbalmer 10634 1.2 lneto 10635 1.1 mbalmer <HR> 10636 1.2 lneto <SMALL CLASS="footer"> 10637 1.1 mbalmer Last update: 10638 1.2 lneto Thu Jun 19 17:13:19 BRT 2014 10639 1.1 mbalmer </SMALL> 10640 1.1 mbalmer <!-- 10641 1.2 lneto Last change: updated for Lua 5.3.0 (work3) 10642 1.1 mbalmer --> 10643 1.1 mbalmer 10644 1.1 mbalmer </body></html> 10645 1.1 mbalmer 10646
Indexes created Mon Apr 27 00:23:16 UTC 2026