doc/manual.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <HTML>
   3 <HEAD>
   4 <TITLE>Lua 5.3 Reference Manual</TITLE>
   5 <LINK REL="stylesheet" TYPE="text/css" HREF="lua.css">
   6 <LINK REL="stylesheet" TYPE="text/css" HREF="manual.css">
   7 <META HTTP-EQUIV="content-type" CONTENT="text/html; charset=iso-8859-1">
   8 </HEAD>
   9
  10 <BODY>
  11
  12 <H1>
  13 <A HREF="http://www.lua.org/"><IMG SRC="logo.gif" ALT="Lua"></A>
  14 Lua 5.3 Reference Manual
  15 </H1>
  16
  17 <P>
  18 by Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes
  19
  20 <P>
  21 <SMALL>
  22 Copyright &copy; 2015&ndash;2017 Lua.org, PUC-Rio.
  23 Freely available under the terms of the
  24 <a href="http://www.lua.org/license.html">Lua license</a>.
  25 </SMALL>
  26
  27 <DIV CLASS="menubar">
  28 <A HREF="contents.html#contents">contents</A>
  29 &middot;
  30 <A HREF="contents.html#index">index</A>
  31 &middot;
  32 <A HREF="http://www.lua.org/manual/">other versions</A>
  33 </DIV>
  34
  35 <!-- ====================================================================== -->
  36 <p>
  37
  38 <!-- $Id: manual.of,v 1.167 2017/01/09 15:18:11 roberto Exp $ -->
  39
  40
  41
  42
  43 <h1>1 &ndash; <a name="1">Introduction</a></h1>
  44
  45 <p>
  46 Lua is a powerful, efficient, lightweight, embeddable scripting language.
  47 It supports procedural programming,
  48 object-oriented programming, functional programming,
  49 data-driven programming, and data description.
  50
  51
  52 <p>
  53 Lua combines simple procedural syntax with powerful data description
  54 constructs based on associative arrays and extensible semantics.
  55 Lua is dynamically typed,
  56 runs by interpreting bytecode with a register-based
  57 virtual machine,
  58 and has automatic memory management with
  59 incremental garbage collection,
  60 making it ideal for configuration, scripting,
  61 and rapid prototyping.
  62
  63
  64 <p>
  65 Lua is implemented as a library, written in <em>clean C</em>,
  66 the common subset of Standard&nbsp;C and C++.
  67 The Lua distribution includes a host program called <code>lua</code>,
  68 which uses the Lua library to offer a complete,
  69 standalone Lua interpreter,
  70 for interactive or batch use.
  71 Lua is intended to be used both as a powerful, lightweight,
  72 embeddable scripting language for any program that needs one,
  73 and as a powerful but lightweight and efficient stand-alone language.
  74
  75
  76 <p>
  77 As an extension language, Lua has no notion of a "main" program:
  78 it works <em>embedded</em> in a host client,
  79 called the <em>embedding program</em> or simply the <em>host</em>.
  80 (Frequently, this host is the stand-alone <code>lua</code> program.)
  81 The host program can invoke functions to execute a piece of Lua code,
  82 can write and read Lua variables,
  83 and can register C&nbsp;functions to be called by Lua code.
  84 Through the use of C&nbsp;functions, Lua can be augmented to cope with
  85 a wide range of different domains,
  86 thus creating customized programming languages sharing a syntactical framework.
  87
  88
  89 <p>
  90 Lua is free software,
  91 and is provided as usual with no guarantees,
  92 as stated in its license.
  93 The implementation described in this manual is available
  94 at Lua's official web site, <code>www.lua.org</code>.
  95
  96
  97 <p>
  98 Like any other reference manual,
  99 this document is dry in places.
 100 For a discussion of the decisions behind the design of Lua,
 101 see the technical papers available at Lua's web site.
 102 For a detailed introduction to programming in Lua,
 103 see Roberto's book, <em>Programming in Lua</em>.
 104
 105
 106
 107 <h1>2 &ndash; <a name="2">Basic Concepts</a></h1>
 108
 109 <p>
 110 This section describes the basic concepts of the language.
 111
 112
 113
 114 <h2>2.1 &ndash; <a name="2.1">Values and Types</a></h2>
 115
 116 <p>
 117 Lua is a <em>dynamically typed language</em>.
 118 This means that
 119 variables do not have types; only values do.
 120 There are no type definitions in the language.
 121 All values carry their own type.
 122
 123
 124 <p>
 125 All values in Lua are <em>first-class values</em>.
 126 This means that all values can be stored in variables,
 127 passed as arguments to other functions, and returned as results.
 128
 129
 130 <p>
 131 There are eight basic types in Lua:
 132 <em>nil</em>, <em>boolean</em>, <em>number</em>,
 133 <em>string</em>, <em>function</em>, <em>userdata</em>,
 134 <em>thread</em>, and <em>table</em>.
 135 The type <em>nil</em> has one single value, <b>nil</b>,
 136 whose main property is to be different from any other value;
 137 it usually represents the absence of a useful value.
 138 The type <em>boolean</em> has two values, <b>false</b> and <b>true</b>.
 139 Both <b>nil</b> and <b>false</b> make a condition false;
 140 any other value makes it true.
 141 The type <em>number</em> represents both
 142 integer numbers and real (floating-point) numbers.
 143 The type <em>string</em> represents immutable sequences of bytes.
 144
 145 Lua is 8-bit clean:
 146 strings can contain any 8-bit value,
 147 including embedded zeros ('<code>\0</code>').
 148 Lua is also encoding-agnostic;
 149 it makes no assumptions about the contents of a string.
 150
 151
 152 <p>
 153 The type <em>number</em> uses two internal representations,
 154 or two subtypes,
 155 one called <em>integer</em> and the other called <em>float</em>.
 156 Lua has explicit rules about when each representation is used,
 157 but it also converts between them automatically as needed (see <a href="#3.4.3">&sect;3.4.3</a>).
 158 Therefore,
 159 the programmer may choose to mostly ignore the difference
 160 between integers and floats
 161 or to assume complete control over the representation of each number.
 162 Standard Lua uses 64-bit integers and double-precision (64-bit) floats,
 163 but you can also compile Lua so that it
 164 uses 32-bit integers and/or single-precision (32-bit) floats.
 165 The option with 32 bits for both integers and floats
 166 is particularly attractive
 167 for small machines and embedded systems.
 168 (See macro <code>LUA_32BITS</code> in file <code>luaconf.h</code>.)
 169
 170
 171 <p>
 172 Lua can call (and manipulate) functions written in Lua and
 173 functions written in C (see <a href="#3.4.10">&sect;3.4.10</a>).
 174 Both are represented by the type <em>function</em>.
 175
 176
 177 <p>
 178 The type <em>userdata</em> is provided to allow arbitrary C&nbsp;data to
 179 be stored in Lua variables.
 180 A userdata value represents a block of raw memory.
 181 There are two kinds of userdata:
 182 <em>full userdata</em>,
 183 which is an object with a block of memory managed by Lua,
 184 and <em>light userdata</em>,
 185 which is simply a C&nbsp;pointer value.
 186 Userdata has no predefined operations in Lua,
 187 except assignment and identity test.
 188 By using <em>metatables</em>,
 189 the programmer can define operations for full userdata values
 190 (see <a href="#2.4">&sect;2.4</a>).
 191 Userdata values cannot be created or modified in Lua,
 192 only through the C&nbsp;API.
 193 This guarantees the integrity of data owned by the host program.
 194
 195
 196 <p>
 197 The type <em>thread</em> represents independent threads of execution
 198 and it is used to implement coroutines (see <a href="#2.6">&sect;2.6</a>).
 199 Lua threads are not related to operating-system threads.
 200 Lua supports coroutines on all systems,
 201 even those that do not support threads natively.
 202
 203
 204 <p>
 205 The type <em>table</em> implements associative arrays,
 206 that is, arrays that can be indexed not only with numbers,
 207 but with any Lua value except <b>nil</b> and NaN.
 208 (<em>Not a Number</em> is a special value used to represent
 209 undefined or unrepresentable numerical results, such as <code>0/0</code>.)
 210 Tables can be <em>heterogeneous</em>;
 211 that is, they can contain values of all types (except <b>nil</b>).
 212 Any key with value <b>nil</b> is not considered part of the table.
 213 Conversely, any key that is not part of a table has
 214 an associated value <b>nil</b>.
 215
 216
 217 <p>
 218 Tables are the sole data-structuring mechanism in Lua;
 219 they can be used to represent ordinary arrays, lists,
 220 symbol tables, sets, records, graphs, trees, etc.
 221 To represent records, Lua uses the field name as an index.
 222 The language supports this representation by
 223 providing <code>a.name</code> as syntactic sugar for <code>a["name"]</code>.
 224 There are several convenient ways to create tables in Lua
 225 (see <a href="#3.4.9">&sect;3.4.9</a>).
 226
 227
 228 <p>
 229 Like indices,
 230 the values of table fields can be of any type.
 231 In particular,
 232 because functions are first-class values,
 233 table fields can contain functions.
 234 Thus tables can also carry <em>methods</em> (see <a href="#3.4.11">&sect;3.4.11</a>).
 235
 236
 237 <p>
 238 The indexing of tables follows
 239 the definition of raw equality in the language.
 240 The expressions <code>a[i]</code> and <code>a[j]</code>
 241 denote the same table element
 242 if and only if <code>i</code> and <code>j</code> are raw equal
 243 (that is, equal without metamethods).
 244 In particular, floats with integral values
 245 are equal to their respective integers
 246 (e.g., <code>1.0 == 1</code>).
 247 To avoid ambiguities,
 248 any float with integral value used as a key
 249 is converted to its respective integer.
 250 For instance, if you write <code>a[2.0] = true</code>,
 251 the actual key inserted into the table will be the
 252 integer <code>2</code>.
 253 (On the other hand,
 254 2 and "<code>2</code>" are different Lua values and therefore
 255 denote different table entries.)
 256
 257
 258 <p>
 259 Tables, functions, threads, and (full) userdata values are <em>objects</em>:
 260 variables do not actually <em>contain</em> these values,
 261 only <em>references</em> to them.
 262 Assignment, parameter passing, and function returns
 263 always manipulate references to such values;
 264 these operations do not imply any kind of copy.
 265
 266
 267 <p>
 268 The library function <a href="#pdf-type"><code>type</code></a> returns a string describing the type
 269 of a given value (see <a href="#6.1">&sect;6.1</a>).
 270
 271
 272
 273
 274
 275 <h2>2.2 &ndash; <a name="2.2">Environments and the Global Environment</a></h2>
 276
 277 <p>
 278 As will be discussed in <a href="#3.2">&sect;3.2</a> and <a href="#3.3.3">&sect;3.3.3</a>,
 279 any reference to a free name
 280 (that is, a name not bound to any declaration) <code>var</code>
 281 is syntactically translated to <code>_ENV.var</code>.
 282 Moreover, every chunk is compiled in the scope of
 283 an external local variable named <code>_ENV</code> (see <a href="#3.3.2">&sect;3.3.2</a>),
 284 so <code>_ENV</code> itself is never a free name in a chunk.
 285
 286
 287 <p>
 288 Despite the existence of this external <code>_ENV</code> variable and
 289 the translation of free names,
 290 <code>_ENV</code> is a completely regular name.
 291 In particular,
 292 you can define new variables and parameters with that name.
 293 Each reference to a free name uses the <code>_ENV</code> that is
 294 visible at that point in the program,
 295 following the usual visibility rules of Lua (see <a href="#3.5">&sect;3.5</a>).
 296
 297
 298 <p>
 299 Any table used as the value of <code>_ENV</code> is called an <em>environment</em>.
 300
 301
 302 <p>
 303 Lua keeps a distinguished environment called the <em>global environment</em>.
 304 This value is kept at a special index in the C registry (see <a href="#4.5">&sect;4.5</a>).
 305 In Lua, the global variable <a href="#pdf-_G"><code>_G</code></a> is initialized with this same value.
 306 (<a href="#pdf-_G"><code>_G</code></a> is never used internally.)
 307
 308
 309 <p>
 310 When Lua loads a chunk,
 311 the default value for its <code>_ENV</code> upvalue
 312 is the global environment (see <a href="#pdf-load"><code>load</code></a>).
 313 Therefore, by default,
 314 free names in Lua code refer to entries in the global environment
 315 (and, therefore, they are also called <em>global variables</em>).
 316 Moreover, all standard libraries are loaded in the global environment
 317 and some functions there operate on that environment.
 318 You can use <a href="#pdf-load"><code>load</code></a> (or <a href="#pdf-loadfile"><code>loadfile</code></a>)
 319 to load a chunk with a different environment.
 320 (In C, you have to load the chunk and then change the value
 321 of its first upvalue.)
 322
 323
 324
 325
 326
 327 <h2>2.3 &ndash; <a name="2.3">Error Handling</a></h2>
 328
 329 <p>
 330 Because Lua is an embedded extension language,
 331 all Lua actions start from C&nbsp;code in the host program
 332 calling a function from the Lua library.
 333 (When you use Lua standalone,
 334 the <code>lua</code> application is the host program.)
 335 Whenever an error occurs during
 336 the compilation or execution of a Lua chunk,
 337 control returns to the host,
 338 which can take appropriate measures
 339 (such as printing an error message).
 340
 341
 342 <p>
 343 Lua code can explicitly generate an error by calling the
 344 <a href="#pdf-error"><code>error</code></a> function.
 345 If you need to catch errors in Lua,
 346 you can use <a href="#pdf-pcall"><code>pcall</code></a> or <a href="#pdf-xpcall"><code>xpcall</code></a>
 347 to call a given function in <em>protected mode</em>.
 348
 349
 350 <p>
 351 Whenever there is an error,
 352 an <em>error object</em> (also called an <em>error message</em>)
 353 is propagated with information about the error.
 354 Lua itself only generates errors whose error object is a string,
 355 but programs may generate errors with
 356 any value as the error object.
 357 It is up to the Lua program or its host to handle such error objects.
 358
 359
 360 <p>
 361 When you use <a href="#pdf-xpcall"><code>xpcall</code></a> or <a href="#lua_pcall"><code>lua_pcall</code></a>,
 362 you may give a <em>message handler</em>
 363 to be called in case of errors.
 364 This function is called with the original error object
 365 and returns a new error object.
 366 It is called before the error unwinds the stack,
 367 so that it can gather more information about the error,
 368 for instance by inspecting the stack and creating a stack traceback.
 369 This message handler is still protected by the protected call;
 370 so, an error inside the message handler
 371 will call the message handler again.
 372 If this loop goes on for too long,
 373 Lua breaks it and returns an appropriate message.
 374 (The message handler is called only for regular runtime errors.
 375 It is not called for memory-allocation errors
 376 nor for errors while running finalizers.)
 377
 378
 379
 380
 381
 382 <h2>2.4 &ndash; <a name="2.4">Metatables and Metamethods</a></h2>
 383
 384 <p>
 385 Every value in Lua can have a <em>metatable</em>.
 386 This <em>metatable</em> is an ordinary Lua table
 387 that defines the behavior of the original value
 388 under certain special operations.
 389 You can change several aspects of the behavior
 390 of operations over a value by setting specific fields in its metatable.
 391 For instance, when a non-numeric value is the operand of an addition,
 392 Lua checks for a function in the field "<code>__add</code>" of the value's metatable.
 393 If it finds one,
 394 Lua calls this function to perform the addition.
 395
 396
 397 <p>
 398 The key for each event in a metatable is a string
 399 with the event name prefixed by two underscores;
 400 the corresponding values are called <em>metamethods</em>.
 401 In the previous example, the key is "<code>__add</code>"
 402 and the metamethod is the function that performs the addition.
 403
 404
 405 <p>
 406 You can query the metatable of any value
 407 using the <a href="#pdf-getmetatable"><code>getmetatable</code></a> function.
 408 Lua queries metamethods in metatables using a raw access (see <a href="#pdf-rawget"><code>rawget</code></a>).
 409 So, to retrieve the metamethod for event <code>ev</code> in object <code>o</code>,
 410 Lua does the equivalent to the following code:
 411
 412 <pre>
 413      rawget(getmetatable(<em>o</em>) or {}, "__<em>ev</em>")
 414 </pre>
 415
 416 <p>
 417 You can replace the metatable of tables
 418 using the <a href="#pdf-setmetatable"><code>setmetatable</code></a> function.
 419 You cannot change the metatable of other types from Lua code
 420 (except by using the debug library (<a href="#6.10">&sect;6.10</a>));
 421 you should use the C&nbsp;API for that.
 422
 423
 424 <p>
 425 Tables and full userdata have individual metatables
 426 (although multiple tables and userdata can share their metatables).
 427 Values of all other types share one single metatable per type;
 428 that is, there is one single metatable for all numbers,
 429 one for all strings, etc.
 430 By default, a value has no metatable,
 431 but the string library sets a metatable for the string type (see <a href="#6.4">&sect;6.4</a>).
 432
 433
 434 <p>
 435 A metatable controls how an object behaves in
 436 arithmetic operations, bitwise operations,
 437 order comparisons, concatenation, length operation, calls, and indexing.
 438 A metatable also can define a function to be called
 439 when a userdata or a table is garbage collected (<a href="#2.5">&sect;2.5</a>).
 440
 441
 442 <p>
 443 For the unary operators (negation, length, and bitwise NOT),
 444 the metamethod is computed and called with a dummy second operand,
 445 equal to the first one.
 446 This extra operand is only to simplify Lua's internals
 447 (by making these operators behave like a binary operation)
 448 and may be removed in future versions.
 449 (For most uses this extra operand is irrelevant.)
 450
 451
 452 <p>
 453 A detailed list of events controlled by metatables is given next.
 454 Each operation is identified by its corresponding key.
 455
 456
 457
 458 <ul>
 459
 460 <li><b><code>__add</code>: </b>
 461 the addition (<code>+</code>) operation.
 462 If any operand for an addition is not a number
 463 (nor a string coercible to a number),
 464 Lua will try to call a metamethod.
 465 First, Lua will check the first operand (even if it is valid).
 466 If that operand does not define a metamethod for <code>__add</code>,
 467 then Lua will check the second operand.
 468 If Lua can find a metamethod,
 469 it calls the metamethod with the two operands as arguments,
 470 and the result of the call
 471 (adjusted to one value)
 472 is the result of the operation.
 473 Otherwise,
 474 it raises an error.
 475 </li>
 476
 477 <li><b><code>__sub</code>: </b>
 478 the subtraction (<code>-</code>) operation.
 479 Behavior similar to the addition operation.
 480 </li>
 481
 482 <li><b><code>__mul</code>: </b>
 483 the multiplication (<code>*</code>) operation.
 484 Behavior similar to the addition operation.
 485 </li>
 486
 487 <li><b><code>__div</code>: </b>
 488 the division (<code>/</code>) operation.
 489 Behavior similar to the addition operation.
 490 </li>
 491
 492 <li><b><code>__mod</code>: </b>
 493 the modulo (<code>%</code>) operation.
 494 Behavior similar to the addition operation.
 495 </li>
 496
 497 <li><b><code>__pow</code>: </b>
 498 the exponentiation (<code>^</code>) operation.
 499 Behavior similar to the addition operation.
 500 </li>
 501
 502 <li><b><code>__unm</code>: </b>
 503 the negation (unary <code>-</code>) operation.
 504 Behavior similar to the addition operation.
 505 </li>
 506
 507 <li><b><code>__idiv</code>: </b>
 508 the floor division (<code>//</code>) operation.
 509 Behavior similar to the addition operation.
 510 </li>
 511
 512 <li><b><code>__band</code>: </b>
 513 the bitwise AND (<code>&amp;</code>) operation.
 514 Behavior similar to the addition operation,
 515 except that Lua will try a metamethod
 516 if any operand is neither an integer
 517 nor a value coercible to an integer (see <a href="#3.4.3">&sect;3.4.3</a>).
 518 </li>
 519
 520 <li><b><code>__bor</code>: </b>
 521 the bitwise OR (<code>|</code>) operation.
 522 Behavior similar to the bitwise AND operation.
 523 </li>
 524
 525 <li><b><code>__bxor</code>: </b>
 526 the bitwise exclusive OR (binary <code>~</code>) operation.
 527 Behavior similar to the bitwise AND operation.
 528 </li>
 529
 530 <li><b><code>__bnot</code>: </b>
 531 the bitwise NOT (unary <code>~</code>) operation.
 532 Behavior similar to the bitwise AND operation.
 533 </li>
 534
 535 <li><b><code>__shl</code>: </b>
 536 the bitwise left shift (<code>&lt;&lt;</code>) operation.
 537 Behavior similar to the bitwise AND operation.
 538 </li>
 539
 540 <li><b><code>__shr</code>: </b>
 541 the bitwise right shift (<code>&gt;&gt;</code>) operation.
 542 Behavior similar to the bitwise AND operation.
 543 </li>
 544
 545 <li><b><code>__concat</code>: </b>
 546 the concatenation (<code>..</code>) operation.
 547 Behavior similar to the addition operation,
 548 except that Lua will try a metamethod
 549 if any operand is neither a string nor a number
 550 (which is always coercible to a string).
 551 </li>
 552
 553 <li><b><code>__len</code>: </b>
 554 the length (<code>#</code>) operation.
 555 If the object is not a string,
 556 Lua will try its metamethod.
 557 If there is a metamethod,
 558 Lua calls it with the object as argument,
 559 and the result of the call
 560 (always adjusted to one value)
 561 is the result of the operation.
 562 If there is no metamethod but the object is a table,
 563 then Lua uses the table length operation (see <a href="#3.4.7">&sect;3.4.7</a>).
 564 Otherwise, Lua raises an error.
 565 </li>
 566
 567 <li><b><code>__eq</code>: </b>
 568 the equal (<code>==</code>) operation.
 569 Behavior similar to the addition operation,
 570 except that Lua will try a metamethod only when the values
 571 being compared are either both tables or both full userdata
 572 and they are not primitively equal.
 573 The result of the call is always converted to a boolean.
 574 </li>
 575
 576 <li><b><code>__lt</code>: </b>
 577 the less than (<code>&lt;</code>) operation.
 578 Behavior similar to the addition operation,
 579 except that Lua will try a metamethod only when the values
 580 being compared are neither both numbers nor both strings.
 581 The result of the call is always converted to a boolean.
 582 </li>
 583
 584 <li><b><code>__le</code>: </b>
 585 the less equal (<code>&lt;=</code>) operation.
 586 Unlike other operations,
 587 the less-equal operation can use two different events.
 588 First, Lua looks for the <code>__le</code> metamethod in both operands,
 589 like in the less than operation.
 590 If it cannot find such a metamethod,
 591 then it will try the <code>__lt</code> metamethod,
 592 assuming that <code>a &lt;= b</code> is equivalent to <code>not (b &lt; a)</code>.
 593 As with the other comparison operators,
 594 the result is always a boolean.
 595 (This use of the <code>__lt</code> event can be removed in future versions;
 596 it is also slower than a real <code>__le</code> metamethod.)
 597 </li>
 598
 599 <li><b><code>__index</code>: </b>
 600 The indexing access <code>table[key]</code>.
 601 This event happens when <code>table</code> is not a table or
 602 when <code>key</code> is not present in <code>table</code>.
 603 The metamethod is looked up in <code>table</code>.
 604
 605
 606 <p>
 607 Despite the name,
 608 the metamethod for this event can be either a function or a table.
 609 If it is a function,
 610 it is called with <code>table</code> and <code>key</code> as arguments,
 611 and the result of the call
 612 (adjusted to one value)
 613 is the result of the operation.
 614 If it is a table,
 615 the final result is the result of indexing this table with <code>key</code>.
 616 (This indexing is regular, not raw,
 617 and therefore can trigger another metamethod.)
 618 </li>
 619
 620 <li><b><code>__newindex</code>: </b>
 621 The indexing assignment <code>table[key] = value</code>.
 622 Like the index event,
 623 this event happens when <code>table</code> is not a table or
 624 when <code>key</code> is not present in <code>table</code>.
 625 The metamethod is looked up in <code>table</code>.
 626
 627
 628 <p>
 629 Like with indexing,
 630 the metamethod for this event can be either a function or a table.
 631 If it is a function,
 632 it is called with <code>table</code>, <code>key</code>, and <code>value</code> as arguments.
 633 If it is a table,
 634 Lua does an indexing assignment to this table with the same key and value.
 635 (This assignment is regular, not raw,
 636 and therefore can trigger another metamethod.)
 637
 638
 639 <p>
 640 Whenever there is a <code>__newindex</code> metamethod,
 641 Lua does not perform the primitive assignment.
 642 (If necessary,
 643 the metamethod itself can call <a href="#pdf-rawset"><code>rawset</code></a>
 644 to do the assignment.)
 645 </li>
 646
 647 <li><b><code>__call</code>: </b>
 648 The call operation <code>func(args)</code>.
 649 This event happens when Lua tries to call a non-function value
 650 (that is, <code>func</code> is not a function).
 651 The metamethod is looked up in <code>func</code>.
 652 If present,
 653 the metamethod is called with <code>func</code> as its first argument,
 654 followed by the arguments of the original call (<code>args</code>).
 655 All results of the call
 656 are the result of the operation.
 657 (This is the only metamethod that allows multiple results.)
 658 </li>
 659
 660 </ul>
 661
 662 <p>
 663 It is a good practice to add all needed metamethods to a table
 664 before setting it as a metatable of some object.
 665 In particular, the <code>__gc</code> metamethod works only when this order
 666 is followed (see <a href="#2.5.1">&sect;2.5.1</a>).
 667
 668
 669 <p>
 670 Because metatables are regular tables,
 671 they can contain arbitrary fields,
 672 not only the event names defined above.
 673 Some functions in the standard library
 674 (e.g., <a href="#pdf-tostring"><code>tostring</code></a>)
 675 use other fields in metatables for their own purposes.
 676
 677
 678
 679
 680
 681 <h2>2.5 &ndash; <a name="2.5">Garbage Collection</a></h2>
 682
 683 <p>
 684 Lua performs automatic memory management.
 685 This means that
 686 you do not have to worry about allocating memory for new objects
 687 or freeing it when the objects are no longer needed.
 688 Lua manages memory automatically by running
 689 a <em>garbage collector</em> to collect all <em>dead objects</em>
 690 (that is, objects that are no longer accessible from Lua).
 691 All memory used by Lua is subject to automatic management:
 692 strings, tables, userdata, functions, threads, internal structures, etc.
 693
 694
 695 <p>
 696 Lua implements an incremental mark-and-sweep collector.
 697 It uses two numbers to control its garbage-collection cycles:
 698 the <em>garbage-collector pause</em> and
 699 the <em>garbage-collector step multiplier</em>.
 700 Both use percentage points as units
 701 (e.g., a value of 100 means an internal value of 1).
 702
 703
 704 <p>
 705 The garbage-collector pause
 706 controls how long the collector waits before starting a new cycle.
 707 Larger values make the collector less aggressive.
 708 Values smaller than 100 mean the collector will not wait to
 709 start a new cycle.
 710 A value of 200 means that the collector waits for the total memory in use
 711 to double before starting a new cycle.
 712
 713
 714 <p>
 715 The garbage-collector step multiplier
 716 controls the relative speed of the collector relative to
 717 memory allocation.
 718 Larger values make the collector more aggressive but also increase
 719 the size of each incremental step.
 720 You should not use values smaller than 100,
 721 because they make the collector too slow and
 722 can result in the collector never finishing a cycle.
 723 The default is 200,
 724 which means that the collector runs at "twice"
 725 the speed of memory allocation.
 726
 727
 728 <p>
 729 If you set the step multiplier to a very large number
 730 (larger than 10% of the maximum number of
 731 bytes that the program may use),
 732 the collector behaves like a stop-the-world collector.
 733 If you then set the pause to 200,
 734 the collector behaves as in old Lua versions,
 735 doing a complete collection every time Lua doubles its
 736 memory usage.
 737
 738
 739 <p>
 740 You can change these numbers by calling <a href="#lua_gc"><code>lua_gc</code></a> in C
 741 or <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> in Lua.
 742 You can also use these functions to control
 743 the collector directly (e.g., stop and restart it).
 744
 745
 746
 747 <h3>2.5.1 &ndash; <a name="2.5.1">Garbage-Collection Metamethods</a></h3>
 748
 749 <p>
 750 You can set garbage-collector metamethods for tables
 751 and, using the C&nbsp;API,
 752 for full userdata (see <a href="#2.4">&sect;2.4</a>).
 753 These metamethods are also called <em>finalizers</em>.
 754 Finalizers allow you to coordinate Lua's garbage collection
 755 with external resource management
 756 (such as closing files, network or database connections,
 757 or freeing your own memory).
 758
 759
 760 <p>
 761 For an object (table or userdata) to be finalized when collected,
 762 you must <em>mark</em> it for finalization.
 763
 764 You mark an object for finalization when you set its metatable
 765 and the metatable has a field indexed by the string "<code>__gc</code>".
 766 Note that if you set a metatable without a <code>__gc</code> field
 767 and later create that field in the metatable,
 768 the object will not be marked for finalization.
 769
 770
 771 <p>
 772 When a marked object becomes garbage,
 773 it is not collected immediately by the garbage collector.
 774 Instead, Lua puts it in a list.
 775 After the collection,
 776 Lua goes through that list.
 777 For each object in the list,
 778 it checks the object's <code>__gc</code> metamethod:
 779 If it is a function,
 780 Lua calls it with the object as its single argument;
 781 if the metamethod is not a function,
 782 Lua simply ignores it.
 783
 784
 785 <p>
 786 At the end of each garbage-collection cycle,
 787 the finalizers for objects are called in
 788 the reverse order that the objects were marked for finalization,
 789 among those collected in that cycle;
 790 that is, the first finalizer to be called is the one associated
 791 with the object marked last in the program.
 792 The execution of each finalizer may occur at any point during
 793 the execution of the regular code.
 794
 795
 796 <p>
 797 Because the object being collected must still be used by the finalizer,
 798 that object (and other objects accessible only through it)
 799 must be <em>resurrected</em> by Lua.
 800 Usually, this resurrection is transient,
 801 and the object memory is freed in the next garbage-collection cycle.
 802 However, if the finalizer stores the object in some global place
 803 (e.g., a global variable),
 804 then the resurrection is permanent.
 805 Moreover, if the finalizer marks a finalizing object for finalization again,
 806 its finalizer will be called again in the next cycle where the
 807 object is unreachable.
 808 In any case,
 809 the object memory is freed only in a GC cycle where
 810 the object is unreachable and not marked for finalization.
 811
 812
 813 <p>
 814 When you close a state (see <a href="#lua_close"><code>lua_close</code></a>),
 815 Lua calls the finalizers of all objects marked for finalization,
 816 following the reverse order that they were marked.
 817 If any finalizer marks objects for collection during that phase,
 818 these marks have no effect.
 819
 820
 821
 822
 823
 824 <h3>2.5.2 &ndash; <a name="2.5.2">Weak Tables</a></h3>
 825
 826 <p>
 827 A <em>weak table</em> is a table whose elements are
 828 <em>weak references</em>.
 829 A weak reference is ignored by the garbage collector.
 830 In other words,
 831 if the only references to an object are weak references,
 832 then the garbage collector will collect that object.
 833
 834
 835 <p>
 836 A weak table can have weak keys, weak values, or both.
 837 A table with weak values allows the collection of its values,
 838 but prevents the collection of its keys.
 839 A table with both weak keys and weak values allows the collection of
 840 both keys and values.
 841 In any case, if either the key or the value is collected,
 842 the whole pair is removed from the table.
 843 The weakness of a table is controlled by the
 844 <code>__mode</code> field of its metatable.
 845 If the <code>__mode</code> field is a string containing the character&nbsp;'<code>k</code>',
 846 the keys in the table are weak.
 847 If <code>__mode</code> contains '<code>v</code>',
 848 the values in the table are weak.
 849
 850
 851 <p>
 852 A table with weak keys and strong values
 853 is also called an <em>ephemeron table</em>.
 854 In an ephemeron table,
 855 a value is considered reachable only if its key is reachable.
 856 In particular,
 857 if the only reference to a key comes through its value,
 858 the pair is removed.
 859
 860
 861 <p>
 862 Any change in the weakness of a table may take effect only
 863 at the next collect cycle.
 864 In particular, if you change the weakness to a stronger mode,
 865 Lua may still collect some items from that table
 866 before the change takes effect.
 867
 868
 869 <p>
 870 Only objects that have an explicit construction
 871 are removed from weak tables.
 872 Values, such as numbers and light C&nbsp;functions,
 873 are not subject to garbage collection,
 874 and therefore are not removed from weak tables
 875 (unless their associated values are collected).
 876 Although strings are subject to garbage collection,
 877 they do not have an explicit construction,
 878 and therefore are not removed from weak tables.
 879
 880
 881 <p>
 882 Resurrected objects
 883 (that is, objects being finalized
 884 and objects accessible only through objects being finalized)
 885 have a special behavior in weak tables.
 886 They are removed from weak values before running their finalizers,
 887 but are removed from weak keys only in the next collection
 888 after running their finalizers, when such objects are actually freed.
 889 This behavior allows the finalizer to access properties
 890 associated with the object through weak tables.
 891
 892
 893 <p>
 894 If a weak table is among the resurrected objects in a collection cycle,
 895 it may not be properly cleared until the next cycle.
 896
 897
 898
 899
 900
 901
 902
 903 <h2>2.6 &ndash; <a name="2.6">Coroutines</a></h2>
 904
 905 <p>
 906 Lua supports coroutines,
 907 also called <em>collaborative multithreading</em>.
 908 A coroutine in Lua represents an independent thread of execution.
 909 Unlike threads in multithread systems, however,
 910 a coroutine only suspends its execution by explicitly calling
 911 a yield function.
 912
 913
 914 <p>
 915 You create a coroutine by calling <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>.
 916 Its sole argument is a function
 917 that is the main function of the coroutine.
 918 The <code>create</code> function only creates a new coroutine and
 919 returns a handle to it (an object of type <em>thread</em>);
 920 it does not start the coroutine.
 921
 922
 923 <p>
 924 You execute a coroutine by calling <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>.
 925 When you first call <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>,
 926 passing as its first argument
 927 a thread returned by <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>,
 928 the coroutine starts its execution by
 929 calling its main function.
 930 Extra arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> are passed
 931 as arguments to that function.
 932 After the coroutine starts running,
 933 it runs until it terminates or <em>yields</em>.
 934
 935
 936 <p>
 937 A coroutine can terminate its execution in two ways:
 938 normally, when its main function returns
 939 (explicitly or implicitly, after the last instruction);
 940 and abnormally, if there is an unprotected error.
 941 In case of normal termination,
 942 <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>true</b>,
 943 plus any values returned by the coroutine main function.
 944 In case of errors, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>false</b>
 945 plus an error object.
 946
 947
 948 <p>
 949 A coroutine yields by calling <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>.
 950 When a coroutine yields,
 951 the corresponding <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns immediately,
 952 even if the yield happens inside nested function calls
 953 (that is, not in the main function,
 954 but in a function directly or indirectly called by the main function).
 955 In the case of a yield, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> also returns <b>true</b>,
 956 plus any values passed to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>.
 957 The next time you resume the same coroutine,
 958 it continues its execution from the point where it yielded,
 959 with the call to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a> returning any extra
 960 arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>.
 961
 962
 963 <p>
 964 Like <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>,
 965 the <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> function also creates a coroutine,
 966 but instead of returning the coroutine itself,
 967 it returns a function that, when called, resumes the coroutine.
 968 Any arguments passed to this function
 969 go as extra arguments to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>.
 970 <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>,
 971 except the first one (the boolean error code).
 972 Unlike <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>,
 973 <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> does not catch errors;
 974 any error is propagated to the caller.
 975
 976
 977 <p>
 978 As an example of how coroutines work,
 979 consider the following code:
 980
 981 <pre>
 982      function foo (a)
 983        print("foo", a)
 984        return coroutine.yield(2*a)
 985      end
 986
 987      co = coroutine.create(function (a,b)
 988            print("co-body", a, b)
 989            local r = foo(a+1)
 990            print("co-body", r)
 991            local r, s = coroutine.yield(a+b, a-b)
 992            print("co-body", r, s)
 993            return b, "end"
 994      end)
 995
 996      print("main", coroutine.resume(co, 1, 10))
 997      print("main", coroutine.resume(co, "r"))
 998      print("main", coroutine.resume(co, "x", "y"))
 999      print("main", coroutine.resume(co, "x", "y"))
1000 </pre><p>
1001 When you run it, it produces the following output:
1002
1003 <pre>
1004      co-body 1       10
1005      foo     2
1006      main    true    4
1007      co-body r
1008      main    true    11      -9
1009      co-body x       y
1010      main    true    10      end
1011      main    false   cannot resume dead coroutine
1012 </pre>
1013
1014 <p>
1015 You can also create and manipulate coroutines through the C API:
1016 see functions <a href="#lua_newthread"><code>lua_newthread</code></a>, <a href="#lua_resume"><code>lua_resume</code></a>,
1017 and <a href="#lua_yield"><code>lua_yield</code></a>.
1018
1019
1020
1021
1022
1023 <h1>3 &ndash; <a name="3">The Language</a></h1>
1024
1025 <p>
1026 This section describes the lexis, the syntax, and the semantics of Lua.
1027 In other words,
1028 this section describes
1029 which tokens are valid,
1030 how they can be combined,
1031 and what their combinations mean.
1032
1033
1034 <p>
1035 Language constructs will be explained using the usual extended BNF notation,
1036 in which
1037 {<em>a</em>}&nbsp;means&nbsp;0 or more <em>a</em>'s, and
1038 [<em>a</em>]&nbsp;means an optional <em>a</em>.
1039 Non-terminals are shown like non-terminal,
1040 keywords are shown like <b>kword</b>,
1041 and other terminal symbols are shown like &lsquo;<b>=</b>&rsquo;.
1042 The complete syntax of Lua can be found in <a href="#9">&sect;9</a>
1043 at the end of this manual.
1044
1045
1046
1047 <h2>3.1 &ndash; <a name="3.1">Lexical Conventions</a></h2>
1048
1049 <p>
1050 Lua is a free-form language.
1051 It ignores spaces (including new lines) and comments
1052 between lexical elements (tokens),
1053 except as delimiters between names and keywords.
1054
1055
1056 <p>
1057 <em>Names</em>
1058 (also called <em>identifiers</em>)
1059 in Lua can be any string of letters,
1060 digits, and underscores,
1061 not beginning with a digit and
1062 not being a reserved word.
1063 Identifiers are used to name variables, table fields, and labels.
1064
1065
1066 <p>
1067 The following <em>keywords</em> are reserved
1068 and cannot be used as names:
1069
1070
1071 <pre>
1072      and       break     do        else      elseif    end
1073      false     for       function  goto      if        in
1074      local     nil       not       or        repeat    return
1075      then      true      until     while
1076 </pre>
1077
1078 <p>
1079 Lua is a case-sensitive language:
1080 <code>and</code> is a reserved word, but <code>And</code> and <code>AND</code>
1081 are two different, valid names.
1082 As a convention,
1083 programs should avoid creating
1084 names that start with an underscore followed by
1085 one or more uppercase letters (such as <a href="#pdf-_VERSION"><code>_VERSION</code></a>).
1086
1087
1088 <p>
1089 The following strings denote other tokens:
1090
1091 <pre>
1092      +     -     *     /     %     ^     #
1093      &amp;     ~     |     &lt;&lt;    &gt;&gt;    //
1094      ==    ~=    &lt;=    &gt;=    &lt;     &gt;     =
1095      (     )     {     }     [     ]     ::
1096      ;     :     ,     .     ..    ...
1097 </pre>
1098
1099 <p>
1100 A <em>short literal string</em>
1101 can be delimited by matching single or double quotes,
1102 and can contain the following C-like escape sequences:
1103 '<code>\a</code>' (bell),
1104 '<code>\b</code>' (backspace),
1105 '<code>\f</code>' (form feed),
1106 '<code>\n</code>' (newline),
1107 '<code>\r</code>' (carriage return),
1108 '<code>\t</code>' (horizontal tab),
1109 '<code>\v</code>' (vertical tab),
1110 '<code>\\</code>' (backslash),
1111 '<code>\"</code>' (quotation mark [double quote]),
1112 and '<code>\'</code>' (apostrophe [single quote]).
1113 A backslash followed by a line break
1114 results in a newline in the string.
1115 The escape sequence '<code>\z</code>' skips the following span
1116 of white-space characters,
1117 including line breaks;
1118 it is particularly useful to break and indent a long literal string
1119 into multiple lines without adding the newlines and spaces
1120 into the string contents.
1121 A short literal string cannot contain unescaped line breaks
1122 nor escapes not forming a valid escape sequence.
1123
1124
1125 <p>
1126 We can specify any byte in a short literal string by its numeric value
1127 (including embedded zeros).
1128 This can be done
1129 with the escape sequence <code>\x<em>XX</em></code>,
1130 where <em>XX</em> is a sequence of exactly two hexadecimal digits,
1131 or with the escape sequence <code>\<em>ddd</em></code>,
1132 where <em>ddd</em> is a sequence of up to three decimal digits.
1133 (Note that if a decimal escape sequence is to be followed by a digit,
1134 it must be expressed using exactly three digits.)
1135
1136
1137 <p>
1138 The UTF-8 encoding of a Unicode character
1139 can be inserted in a literal string with
1140 the escape sequence <code>\u{<em>XXX</em>}</code>
1141 (note the mandatory enclosing brackets),
1142 where <em>XXX</em> is a sequence of one or more hexadecimal digits
1143 representing the character code point.
1144
1145
1146 <p>
1147 Literal strings can also be defined using a long format
1148 enclosed by <em>long brackets</em>.
1149 We define an <em>opening long bracket of level <em>n</em></em> as an opening
1150 square bracket followed by <em>n</em> equal signs followed by another
1151 opening square bracket.
1152 So, an opening long bracket of level&nbsp;0 is written as <code>[[</code>,
1153 an opening long bracket of level&nbsp;1 is written as <code>[=[</code>,
1154 and so on.
1155 A <em>closing long bracket</em> is defined similarly;
1156 for instance,
1157 a closing long bracket of level&nbsp;4 is written as  <code>]====]</code>.
1158 A <em>long literal</em> starts with an opening long bracket of any level and
1159 ends at the first closing long bracket of the same level.
1160 It can contain any text except a closing bracket of the same level.
1161 Literals in this bracketed form can run for several lines,
1162 do not interpret any escape sequences,
1163 and ignore long brackets of any other level.
1164 Any kind of end-of-line sequence
1165 (carriage return, newline, carriage return followed by newline,
1166 or newline followed by carriage return)
1167 is converted to a simple newline.
1168
1169
1170 <p>
1171 For convenience,
1172 when the opening long bracket is immediately followed by a newline,
1173 the newline is not included in the string.
1174 As an example, in a system using ASCII
1175 (in which '<code>a</code>' is coded as&nbsp;97,
1176 newline is coded as&nbsp;10, and '<code>1</code>' is coded as&nbsp;49),
1177 the five literal strings below denote the same string:
1178
1179 <pre>
1180      a = 'alo\n123"'
1181      a = "alo\n123\""
1182      a = '\97lo\10\04923"'
1183      a = [[alo
1184      123"]]
1185      a = [==[
1186      alo
1187      123"]==]
1188 </pre>
1189
1190 <p>
1191 Any byte in a literal string not
1192 explicitly affected by the previous rules represents itself.
1193 However, Lua opens files for parsing in text mode,
1194 and the system file functions may have problems with
1195 some control characters.
1196 So, it is safer to represent
1197 non-text data as a quoted literal with
1198 explicit escape sequences for the non-text characters.
1199
1200
1201 <p>
1202 A <em>numeric constant</em> (or <em>numeral</em>)
1203 can be written with an optional fractional part
1204 and an optional decimal exponent,
1205 marked by a letter '<code>e</code>' or '<code>E</code>'.
1206 Lua also accepts hexadecimal constants,
1207 which start with <code>0x</code> or <code>0X</code>.
1208 Hexadecimal constants also accept an optional fractional part
1209 plus an optional binary exponent,
1210 marked by a letter '<code>p</code>' or '<code>P</code>'.
1211 A numeric constant with a radix point or an exponent
1212 denotes a float;
1213 otherwise,
1214 if its value fits in an integer,
1215 it denotes an integer.
1216 Examples of valid integer constants are
1217
1218 <pre>
1219      3   345   0xff   0xBEBADA
1220 </pre><p>
1221 Examples of valid float constants are
1222
1223 <pre>
1224      3.0     3.1416     314.16e-2     0.31416E1     34e1
1225      0x0.1E  0xA23p-4   0X1.921FB54442D18P+1
1226 </pre>
1227
1228 <p>
1229 A <em>comment</em> starts with a double hyphen (<code>--</code>)
1230 anywhere outside a string.
1231 If the text immediately after <code>--</code> is not an opening long bracket,
1232 the comment is a <em>short comment</em>,
1233 which runs until the end of the line.
1234 Otherwise, it is a <em>long comment</em>,
1235 which runs until the corresponding closing long bracket.
1236 Long comments are frequently used to disable code temporarily.
1237
1238
1239
1240
1241
1242 <h2>3.2 &ndash; <a name="3.2">Variables</a></h2>
1243
1244 <p>
1245 Variables are places that store values.
1246 There are three kinds of variables in Lua:
1247 global variables, local variables, and table fields.
1248
1249
1250 <p>
1251 A single name can denote a global variable or a local variable
1252 (or a function's formal parameter,
1253 which is a particular kind of local variable):
1254
1255 <pre>
1256         var ::= Name
1257 </pre><p>
1258 Name denotes identifiers, as defined in <a href="#3.1">&sect;3.1</a>.
1259
1260
1261 <p>
1262 Any variable name is assumed to be global unless explicitly declared
1263 as a local (see <a href="#3.3.7">&sect;3.3.7</a>).
1264 Local variables are <em>lexically scoped</em>:
1265 local variables can be freely accessed by functions
1266 defined inside their scope (see <a href="#3.5">&sect;3.5</a>).
1267
1268
1269 <p>
1270 Before the first assignment to a variable, its value is <b>nil</b>.
1271
1272
1273 <p>
1274 Square brackets are used to index a table:
1275
1276 <pre>
1277         var ::= prefixexp &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo;
1278 </pre><p>
1279 The meaning of accesses to table fields can be changed via metatables.
1280 An access to an indexed variable <code>t[i]</code> is equivalent to
1281 a call <code>gettable_event(t,i)</code>.
1282 (See <a href="#2.4">&sect;2.4</a> for a complete description of the
1283 <code>gettable_event</code> function.
1284 This function is not defined or callable in Lua.
1285 We use it here only for explanatory purposes.)
1286
1287
1288 <p>
1289 The syntax <code>var.Name</code> is just syntactic sugar for
1290 <code>var["Name"]</code>:
1291
1292 <pre>
1293         var ::= prefixexp &lsquo;<b>.</b>&rsquo; Name
1294 </pre>
1295
1296 <p>
1297 An access to a global variable <code>x</code>
1298 is equivalent to <code>_ENV.x</code>.
1299 Due to the way that chunks are compiled,
1300 <code>_ENV</code> is never a global name (see <a href="#2.2">&sect;2.2</a>).
1301
1302
1303
1304
1305
1306 <h2>3.3 &ndash; <a name="3.3">Statements</a></h2>
1307
1308 <p>
1309 Lua supports an almost conventional set of statements,
1310 similar to those in Pascal or C.
1311 This set includes
1312 assignments, control structures, function calls,
1313 and variable declarations.
1314
1315
1316
1317 <h3>3.3.1 &ndash; <a name="3.3.1">Blocks</a></h3>
1318
1319 <p>
1320 A block is a list of statements,
1321 which are executed sequentially:
1322
1323 <pre>
1324         block ::= {stat}
1325 </pre><p>
1326 Lua has <em>empty statements</em>
1327 that allow you to separate statements with semicolons,
1328 start a block with a semicolon
1329 or write two semicolons in sequence:
1330
1331 <pre>
1332         stat ::= &lsquo;<b>;</b>&rsquo;
1333 </pre>
1334
1335 <p>
1336 Function calls and assignments
1337 can start with an open parenthesis.
1338 This possibility leads to an ambiguity in Lua's grammar.
1339 Consider the following fragment:
1340
1341 <pre>
1342      a = b + c
1343      (print or io.write)('done')
1344 </pre><p>
1345 The grammar could see it in two ways:
1346
1347 <pre>
1348      a = b + c(print or io.write)('done')
1349
1350      a = b + c; (print or io.write)('done')
1351 </pre><p>
1352 The current parser always sees such constructions
1353 in the first way,
1354 interpreting the open parenthesis
1355 as the start of the arguments to a call.
1356 To avoid this ambiguity,
1357 it is a good practice to always precede with a semicolon
1358 statements that start with a parenthesis:
1359
1360 <pre>
1361      ;(print or io.write)('done')
1362 </pre>
1363
1364 <p>
1365 A block can be explicitly delimited to produce a single statement:
1366
1367 <pre>
1368         stat ::= <b>do</b> block <b>end</b>
1369 </pre><p>
1370 Explicit blocks are useful
1371 to control the scope of variable declarations.
1372 Explicit blocks are also sometimes used to
1373 add a <b>return</b> statement in the middle
1374 of another block (see <a href="#3.3.4">&sect;3.3.4</a>).
1375
1376
1377
1378
1379
1380 <h3>3.3.2 &ndash; <a name="3.3.2">Chunks</a></h3>
1381
1382 <p>
1383 The unit of compilation of Lua is called a <em>chunk</em>.
1384 Syntactically,
1385 a chunk is simply a block:
1386
1387 <pre>
1388         chunk ::= block
1389 </pre>
1390
1391 <p>
1392 Lua handles a chunk as the body of an anonymous function
1393 with a variable number of arguments
1394 (see <a href="#3.4.11">&sect;3.4.11</a>).
1395 As such, chunks can define local variables,
1396 receive arguments, and return values.
1397 Moreover, such anonymous function is compiled as in the
1398 scope of an external local variable called <code>_ENV</code> (see <a href="#2.2">&sect;2.2</a>).
1399 The resulting function always has <code>_ENV</code> as its only upvalue,
1400 even if it does not use that variable.
1401
1402
1403 <p>
1404 A chunk can be stored in a file or in a string inside the host program.
1405 To execute a chunk,
1406 Lua first <em>loads</em> it,
1407 precompiling the chunk's code into instructions for a virtual machine,
1408 and then Lua executes the compiled code
1409 with an interpreter for the virtual machine.
1410
1411
1412 <p>
1413 Chunks can also be precompiled into binary form;
1414 see program <code>luac</code> and function <a href="#pdf-string.dump"><code>string.dump</code></a> for details.
1415 Programs in source and compiled forms are interchangeable;
1416 Lua automatically detects the file type and acts accordingly (see <a href="#pdf-load"><code>load</code></a>).
1417
1418
1419
1420
1421
1422 <h3>3.3.3 &ndash; <a name="3.3.3">Assignment</a></h3>
1423
1424 <p>
1425 Lua allows multiple assignments.
1426 Therefore, the syntax for assignment
1427 defines a list of variables on the left side
1428 and a list of expressions on the right side.
1429 The elements in both lists are separated by commas:
1430
1431 <pre>
1432         stat ::= varlist &lsquo;<b>=</b>&rsquo; explist
1433         varlist ::= var {&lsquo;<b>,</b>&rsquo; var}
1434         explist ::= exp {&lsquo;<b>,</b>&rsquo; exp}
1435 </pre><p>
1436 Expressions are discussed in <a href="#3.4">&sect;3.4</a>.
1437
1438
1439 <p>
1440 Before the assignment,
1441 the list of values is <em>adjusted</em> to the length of
1442 the list of variables.
1443 If there are more values than needed,
1444 the excess values are thrown away.
1445 If there are fewer values than needed,
1446 the list is extended with as many  <b>nil</b>'s as needed.
1447 If the list of expressions ends with a function call,
1448 then all values returned by that call enter the list of values,
1449 before the adjustment
1450 (except when the call is enclosed in parentheses; see <a href="#3.4">&sect;3.4</a>).
1451
1452
1453 <p>
1454 The assignment statement first evaluates all its expressions
1455 and only then the assignments are performed.
1456 Thus the code
1457
1458 <pre>
1459      i = 3
1460      i, a[i] = i+1, 20
1461 </pre><p>
1462 sets <code>a[3]</code> to 20, without affecting <code>a[4]</code>
1463 because the <code>i</code> in <code>a[i]</code> is evaluated (to 3)
1464 before it is assigned&nbsp;4.
1465 Similarly, the line
1466
1467 <pre>
1468      x, y = y, x
1469 </pre><p>
1470 exchanges the values of <code>x</code> and <code>y</code>,
1471 and
1472
1473 <pre>
1474      x, y, z = y, z, x
1475 </pre><p>
1476 cyclically permutes the values of <code>x</code>, <code>y</code>, and <code>z</code>.
1477
1478
1479 <p>
1480 The meaning of assignments to global variables
1481 and table fields can be changed via metatables.
1482 An assignment to an indexed variable <code>t[i] = val</code> is equivalent to
1483 <code>settable_event(t,i,val)</code>.
1484 (See <a href="#2.4">&sect;2.4</a> for a complete description of the
1485 <code>settable_event</code> function.
1486 This function is not defined or callable in Lua.
1487 We use it here only for explanatory purposes.)
1488
1489
1490 <p>
1491 An assignment to a global name <code>x = val</code>
1492 is equivalent to the assignment
1493 <code>_ENV.x = val</code> (see <a href="#2.2">&sect;2.2</a>).
1494
1495
1496
1497
1498
1499 <h3>3.3.4 &ndash; <a name="3.3.4">Control Structures</a></h3><p>
1500 The control structures
1501 <b>if</b>, <b>while</b>, and <b>repeat</b> have the usual meaning and
1502 familiar syntax:
1503
1504
1505
1506
1507 <pre>
1508         stat ::= <b>while</b> exp <b>do</b> block <b>end</b>
1509         stat ::= <b>repeat</b> block <b>until</b> exp
1510         stat ::= <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b>
1511 </pre><p>
1512 Lua also has a <b>for</b> statement, in two flavors (see <a href="#3.3.5">&sect;3.3.5</a>).
1513
1514
1515 <p>
1516 The condition expression of a
1517 control structure can return any value.
1518 Both <b>false</b> and <b>nil</b> are considered false.
1519 All values different from <b>nil</b> and <b>false</b> are considered true
1520 (in particular, the number 0 and the empty string are also true).
1521
1522
1523 <p>
1524 In the <b>repeat</b>&ndash;<b>until</b> loop,
1525 the inner block does not end at the <b>until</b> keyword,
1526 but only after the condition.
1527 So, the condition can refer to local variables
1528 declared inside the loop block.
1529
1530
1531 <p>
1532 The <b>goto</b> statement transfers the program control to a label.
1533 For syntactical reasons,
1534 labels in Lua are considered statements too:
1535
1536
1537
1538 <pre>
1539         stat ::= <b>goto</b> Name
1540         stat ::= label
1541         label ::= &lsquo;<b>::</b>&rsquo; Name &lsquo;<b>::</b>&rsquo;
1542 </pre>
1543
1544 <p>
1545 A label is visible in the entire block where it is defined,
1546 except
1547 inside nested blocks where a label with the same name is defined and
1548 inside nested functions.
1549 A goto may jump to any visible label as long as it does not
1550 enter into the scope of a local variable.
1551
1552
1553 <p>
1554 Labels and empty statements are called <em>void statements</em>,
1555 as they perform no actions.
1556
1557
1558 <p>
1559 The <b>break</b> statement terminates the execution of a
1560 <b>while</b>, <b>repeat</b>, or <b>for</b> loop,
1561 skipping to the next statement after the loop:
1562
1563
1564 <pre>
1565         stat ::= <b>break</b>
1566 </pre><p>
1567 A <b>break</b> ends the innermost enclosing loop.
1568
1569
1570 <p>
1571 The <b>return</b> statement is used to return values
1572 from a function or a chunk
1573 (which is an anonymous function).
1574
1575 Functions can return more than one value,
1576 so the syntax for the <b>return</b> statement is
1577
1578 <pre>
1579         stat ::= <b>return</b> [explist] [&lsquo;<b>;</b>&rsquo;]
1580 </pre>
1581
1582 <p>
1583 The <b>return</b> statement can only be written
1584 as the last statement of a block.
1585 If it is really necessary to <b>return</b> in the middle of a block,
1586 then an explicit inner block can be used,
1587 as in the idiom <code>do return end</code>,
1588 because now <b>return</b> is the last statement in its (inner) block.
1589
1590
1591
1592
1593
1594 <h3>3.3.5 &ndash; <a name="3.3.5">For Statement</a></h3>
1595
1596 <p>
1597
1598 The <b>for</b> statement has two forms:
1599 one numerical and one generic.
1600
1601
1602 <p>
1603 The numerical <b>for</b> loop repeats a block of code while a
1604 control variable runs through an arithmetic progression.
1605 It has the following syntax:
1606
1607 <pre>
1608         stat ::= <b>for</b> Name &lsquo;<b>=</b>&rsquo; exp &lsquo;<b>,</b>&rsquo; exp [&lsquo;<b>,</b>&rsquo; exp] <b>do</b> block <b>end</b>
1609 </pre><p>
1610 The <em>block</em> is repeated for <em>name</em> starting at the value of
1611 the first <em>exp</em>, until it passes the second <em>exp</em> by steps of the
1612 third <em>exp</em>.
1613 More precisely, a <b>for</b> statement like
1614
1615 <pre>
1616      for v = <em>e1</em>, <em>e2</em>, <em>e3</em> do <em>block</em> end
1617 </pre><p>
1618 is equivalent to the code:
1619
1620 <pre>
1621      do
1622        local <em>var</em>, <em>limit</em>, <em>step</em> = tonumber(<em>e1</em>), tonumber(<em>e2</em>), tonumber(<em>e3</em>)
1623        if not (<em>var</em> and <em>limit</em> and <em>step</em>) then error() end
1624        <em>var</em> = <em>var</em> - <em>step</em>
1625        while true do
1626          <em>var</em> = <em>var</em> + <em>step</em>
1627          if (<em>step</em> &gt;= 0 and <em>var</em> &gt; <em>limit</em>) or (<em>step</em> &lt; 0 and <em>var</em> &lt; <em>limit</em>) then
1628            break
1629          end
1630          local v = <em>var</em>
1631          <em>block</em>
1632        end
1633      end
1634 </pre>
1635
1636 <p>
1637 Note the following:
1638
1639 <ul>
1640
1641 <li>
1642 All three control expressions are evaluated only once,
1643 before the loop starts.
1644 They must all result in numbers.
1645 </li>
1646
1647 <li>
1648 <code><em>var</em></code>, <code><em>limit</em></code>, and <code><em>step</em></code> are invisible variables.
1649 The names shown here are for explanatory purposes only.
1650 </li>
1651
1652 <li>
1653 If the third expression (the step) is absent,
1654 then a step of&nbsp;1 is used.
1655 </li>
1656
1657 <li>
1658 You can use <b>break</b> and <b>goto</b> to exit a <b>for</b> loop.
1659 </li>
1660
1661 <li>
1662 The loop variable <code>v</code> is local to the loop body.
1663 If you need its value after the loop,
1664 assign it to another variable before exiting the loop.
1665 </li>
1666
1667 </ul>
1668
1669 <p>
1670 The generic <b>for</b> statement works over functions,
1671 called <em>iterators</em>.
1672 On each iteration, the iterator function is called to produce a new value,
1673 stopping when this new value is <b>nil</b>.
1674 The generic <b>for</b> loop has the following syntax:
1675
1676 <pre>
1677         stat ::= <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b>
1678         namelist ::= Name {&lsquo;<b>,</b>&rsquo; Name}
1679 </pre><p>
1680 A <b>for</b> statement like
1681
1682 <pre>
1683      for <em>var_1</em>, &middot;&middot;&middot;, <em>var_n</em> in <em>explist</em> do <em>block</em> end
1684 </pre><p>
1685 is equivalent to the code:
1686
1687 <pre>
1688      do
1689        local <em>f</em>, <em>s</em>, <em>var</em> = <em>explist</em>
1690        while true do
1691          local <em>var_1</em>, &middot;&middot;&middot;, <em>var_n</em> = <em>f</em>(<em>s</em>, <em>var</em>)
1692          if <em>var_1</em> == nil then break end
1693          <em>var</em> = <em>var_1</em>
1694          <em>block</em>
1695        end
1696      end
1697 </pre><p>
1698 Note the following:
1699
1700 <ul>
1701
1702 <li>
1703 <code><em>explist</em></code> is evaluated only once.
1704 Its results are an <em>iterator</em> function,
1705 a <em>state</em>,
1706 and an initial value for the first <em>iterator variable</em>.
1707 </li>
1708
1709 <li>
1710 <code><em>f</em></code>, <code><em>s</em></code>, and <code><em>var</em></code> are invisible variables.
1711 The names are here for explanatory purposes only.
1712 </li>
1713
1714 <li>
1715 You can use <b>break</b> to exit a <b>for</b> loop.
1716 </li>
1717
1718 <li>
1719 The loop variables <code><em>var_i</em></code> are local to the loop;
1720 you cannot use their values after the <b>for</b> ends.
1721 If you need these values,
1722 then assign them to other variables before breaking or exiting the loop.
1723 </li>
1724
1725 </ul>
1726
1727
1728
1729
1730 <h3>3.3.6 &ndash; <a name="3.3.6">Function Calls as Statements</a></h3><p>
1731 To allow possible side-effects,
1732 function calls can be executed as statements:
1733
1734 <pre>
1735         stat ::= functioncall
1736 </pre><p>
1737 In this case, all returned values are thrown away.
1738 Function calls are explained in <a href="#3.4.10">&sect;3.4.10</a>.
1739
1740
1741
1742
1743
1744 <h3>3.3.7 &ndash; <a name="3.3.7">Local Declarations</a></h3><p>
1745 Local variables can be declared anywhere inside a block.
1746 The declaration can include an initial assignment:
1747
1748 <pre>
1749         stat ::= <b>local</b> namelist [&lsquo;<b>=</b>&rsquo; explist]
1750 </pre><p>
1751 If present, an initial assignment has the same semantics
1752 of a multiple assignment (see <a href="#3.3.3">&sect;3.3.3</a>).
1753 Otherwise, all variables are initialized with <b>nil</b>.
1754
1755
1756 <p>
1757 A chunk is also a block (see <a href="#3.3.2">&sect;3.3.2</a>),
1758 and so local variables can be declared in a chunk outside any explicit block.
1759
1760
1761 <p>
1762 The visibility rules for local variables are explained in <a href="#3.5">&sect;3.5</a>.
1763
1764
1765
1766
1767
1768
1769
1770 <h2>3.4 &ndash; <a name="3.4">Expressions</a></h2>
1771
1772 <p>
1773 The basic expressions in Lua are the following:
1774
1775 <pre>
1776         exp ::= prefixexp
1777         exp ::= <b>nil</b> | <b>false</b> | <b>true</b>
1778         exp ::= Numeral
1779         exp ::= LiteralString
1780         exp ::= functiondef
1781         exp ::= tableconstructor
1782         exp ::= &lsquo;<b>...</b>&rsquo;
1783         exp ::= exp binop exp
1784         exp ::= unop exp
1785         prefixexp ::= var | functioncall | &lsquo;<b>(</b>&rsquo; exp &lsquo;<b>)</b>&rsquo;
1786 </pre>
1787
1788 <p>
1789 Numerals and literal strings are explained in <a href="#3.1">&sect;3.1</a>;
1790 variables are explained in <a href="#3.2">&sect;3.2</a>;
1791 function definitions are explained in <a href="#3.4.11">&sect;3.4.11</a>;
1792 function calls are explained in <a href="#3.4.10">&sect;3.4.10</a>;
1793 table constructors are explained in <a href="#3.4.9">&sect;3.4.9</a>.
1794 Vararg expressions,
1795 denoted by three dots ('<code>...</code>'), can only be used when
1796 directly inside a vararg function;
1797 they are explained in <a href="#3.4.11">&sect;3.4.11</a>.
1798
1799
1800 <p>
1801 Binary operators comprise arithmetic operators (see <a href="#3.4.1">&sect;3.4.1</a>),
1802 bitwise operators (see <a href="#3.4.2">&sect;3.4.2</a>),
1803 relational operators (see <a href="#3.4.4">&sect;3.4.4</a>), logical operators (see <a href="#3.4.5">&sect;3.4.5</a>),
1804 and the concatenation operator (see <a href="#3.4.6">&sect;3.4.6</a>).
1805 Unary operators comprise the unary minus (see <a href="#3.4.1">&sect;3.4.1</a>),
1806 the unary bitwise NOT (see <a href="#3.4.2">&sect;3.4.2</a>),
1807 the unary logical <b>not</b> (see <a href="#3.4.5">&sect;3.4.5</a>),
1808 and the unary <em>length operator</em> (see <a href="#3.4.7">&sect;3.4.7</a>).
1809
1810
1811 <p>
1812 Both function calls and vararg expressions can result in multiple values.
1813 If a function call is used as a statement (see <a href="#3.3.6">&sect;3.3.6</a>),
1814 then its return list is adjusted to zero elements,
1815 thus discarding all returned values.
1816 If an expression is used as the last (or the only) element
1817 of a list of expressions,
1818 then no adjustment is made
1819 (unless the expression is enclosed in parentheses).
1820 In all other contexts,
1821 Lua adjusts the result list to one element,
1822 either discarding all values except the first one
1823 or adding a single <b>nil</b> if there are no values.
1824
1825
1826 <p>
1827 Here are some examples:
1828
1829 <pre>
1830      f()                -- adjusted to 0 results
1831      g(f(), x)          -- f() is adjusted to 1 result
1832      g(x, f())          -- g gets x plus all results from f()
1833      a,b,c = f(), x     -- f() is adjusted to 1 result (c gets nil)
1834      a,b = ...          -- a gets the first vararg parameter, b gets
1835                         -- the second (both a and b can get nil if there
1836                         -- is no corresponding vararg parameter)
1837
1838      a,b,c = x, f()     -- f() is adjusted to 2 results
1839      a,b,c = f()        -- f() is adjusted to 3 results
1840      return f()         -- returns all results from f()
1841      return ...         -- returns all received vararg parameters
1842      return x,y,f()     -- returns x, y, and all results from f()
1843      {f()}              -- creates a list with all results from f()
1844      {...}              -- creates a list with all vararg parameters
1845      {f(), nil}         -- f() is adjusted to 1 result
1846 </pre>
1847
1848 <p>
1849 Any expression enclosed in parentheses always results in only one value.
1850 Thus,
1851 <code>(f(x,y,z))</code> is always a single value,
1852 even if <code>f</code> returns several values.
1853 (The value of <code>(f(x,y,z))</code> is the first value returned by <code>f</code>
1854 or <b>nil</b> if <code>f</code> does not return any values.)
1855
1856
1857
1858 <h3>3.4.1 &ndash; <a name="3.4.1">Arithmetic Operators</a></h3><p>
1859 Lua supports the following arithmetic operators:
1860
1861 <ul>
1862 <li><b><code>+</code>: </b>addition</li>
1863 <li><b><code>-</code>: </b>subtraction</li>
1864 <li><b><code>*</code>: </b>multiplication</li>
1865 <li><b><code>/</code>: </b>float division</li>
1866 <li><b><code>//</code>: </b>floor division</li>
1867 <li><b><code>%</code>: </b>modulo</li>
1868 <li><b><code>^</code>: </b>exponentiation</li>
1869 <li><b><code>-</code>: </b>unary minus</li>
1870 </ul>
1871
1872 <p>
1873 With the exception of exponentiation and float division,
1874 the arithmetic operators work as follows:
1875 If both operands are integers,
1876 the operation is performed over integers and the result is an integer.
1877 Otherwise, if both operands are numbers
1878 or strings that can be converted to
1879 numbers (see <a href="#3.4.3">&sect;3.4.3</a>),
1880 then they are converted to floats,
1881 the operation is performed following the usual rules
1882 for floating-point arithmetic
1883 (usually the IEEE 754 standard),
1884 and the result is a float.
1885
1886
1887 <p>
1888 Exponentiation and float division (<code>/</code>)
1889 always convert their operands to floats
1890 and the result is always a float.
1891 Exponentiation uses the ISO&nbsp;C function <code>pow</code>,
1892 so that it works for non-integer exponents too.
1893
1894
1895 <p>
1896 Floor division (<code>//</code>) is a division
1897 that rounds the quotient towards minus infinity,
1898 that is, the floor of the division of its operands.
1899
1900
1901 <p>
1902 Modulo is defined as the remainder of a division
1903 that rounds the quotient towards minus infinity (floor division).
1904
1905
1906 <p>
1907 In case of overflows in integer arithmetic,
1908 all operations <em>wrap around</em>,
1909 according to the usual rules of two-complement arithmetic.
1910 (In other words,
1911 they return the unique representable integer
1912 that is equal modulo <em>2<sup>64</sup></em> to the mathematical result.)
1913
1914
1915
1916 <h3>3.4.2 &ndash; <a name="3.4.2">Bitwise Operators</a></h3><p>
1917 Lua supports the following bitwise operators:
1918
1919 <ul>
1920 <li><b><code>&amp;</code>: </b>bitwise AND</li>
1921 <li><b><code>&#124;</code>: </b>bitwise OR</li>
1922 <li><b><code>~</code>: </b>bitwise exclusive OR</li>
1923 <li><b><code>&gt;&gt;</code>: </b>right shift</li>
1924 <li><b><code>&lt;&lt;</code>: </b>left shift</li>
1925 <li><b><code>~</code>: </b>unary bitwise NOT</li>
1926 </ul>
1927
1928 <p>
1929 All bitwise operations convert its operands to integers
1930 (see <a href="#3.4.3">&sect;3.4.3</a>),
1931 operate on all bits of those integers,
1932 and result in an integer.
1933
1934
1935 <p>
1936 Both right and left shifts fill the vacant bits with zeros.
1937 Negative displacements shift to the other direction;
1938 displacements with absolute values equal to or higher than
1939 the number of bits in an integer
1940 result in zero (as all bits are shifted out).
1941
1942
1943
1944
1945
1946 <h3>3.4.3 &ndash; <a name="3.4.3">Coercions and Conversions</a></h3><p>
1947 Lua provides some automatic conversions between some
1948 types and representations at run time.
1949 Bitwise operators always convert float operands to integers.
1950 Exponentiation and float division
1951 always convert integer operands to floats.
1952 All other arithmetic operations applied to mixed numbers
1953 (integers and floats) convert the integer operand to a float;
1954 this is called the <em>usual rule</em>.
1955 The C API also converts both integers to floats and
1956 floats to integers, as needed.
1957 Moreover, string concatenation accepts numbers as arguments,
1958 besides strings.
1959
1960
1961 <p>
1962 Lua also converts strings to numbers,
1963 whenever a number is expected.
1964
1965
1966 <p>
1967 In a conversion from integer to float,
1968 if the integer value has an exact representation as a float,
1969 that is the result.
1970 Otherwise,
1971 the conversion gets the nearest higher or
1972 the nearest lower representable value.
1973 This kind of conversion never fails.
1974
1975
1976 <p>
1977 The conversion from float to integer
1978 checks whether the float has an exact representation as an integer
1979 (that is, the float has an integral value and
1980 it is in the range of integer representation).
1981 If it does, that representation is the result.
1982 Otherwise, the conversion fails.
1983
1984
1985 <p>
1986 The conversion from strings to numbers goes as follows:
1987 First, the string is converted to an integer or a float,
1988 following its syntax and the rules of the Lua lexer.
1989 (The string may have also leading and trailing spaces and a sign.)
1990 Then, the resulting number (float or integer)
1991 is converted to the type (float or integer) required by the context
1992 (e.g., the operation that forced the conversion).
1993
1994
1995 <p>
1996 All conversions from strings to numbers
1997 accept both a dot and the current locale mark
1998 as the radix character.
1999 (The Lua lexer, however, accepts only a dot.)
2000
2001
2002 <p>
2003 The conversion from numbers to strings uses a
2004 non-specified human-readable format.
2005 For complete control over how numbers are converted to strings,
2006 use the <code>format</code> function from the string library
2007 (see <a href="#pdf-string.format"><code>string.format</code></a>).
2008
2009
2010
2011
2012
2013 <h3>3.4.4 &ndash; <a name="3.4.4">Relational Operators</a></h3><p>
2014 Lua supports the following relational operators:
2015
2016 <ul>
2017 <li><b><code>==</code>: </b>equality</li>
2018 <li><b><code>~=</code>: </b>inequality</li>
2019 <li><b><code>&lt;</code>: </b>less than</li>
2020 <li><b><code>&gt;</code>: </b>greater than</li>
2021 <li><b><code>&lt;=</code>: </b>less or equal</li>
2022 <li><b><code>&gt;=</code>: </b>greater or equal</li>
2023 </ul><p>
2024 These operators always result in <b>false</b> or <b>true</b>.
2025
2026
2027 <p>
2028 Equality (<code>==</code>) first compares the type of its operands.
2029 If the types are different, then the result is <b>false</b>.
2030 Otherwise, the values of the operands are compared.
2031 Strings are compared in the obvious way.
2032 Numbers are equal if they denote the same mathematical value.
2033
2034
2035 <p>
2036 Tables, userdata, and threads
2037 are compared by reference:
2038 two objects are considered equal only if they are the same object.
2039 Every time you create a new object
2040 (a table, userdata, or thread),
2041 this new object is different from any previously existing object.
2042 Closures with the same reference are always equal.
2043 Closures with any detectable difference
2044 (different behavior, different definition) are always different.
2045
2046
2047 <p>
2048 You can change the way that Lua compares tables and userdata
2049 by using the "eq" metamethod (see <a href="#2.4">&sect;2.4</a>).
2050
2051
2052 <p>
2053 Equality comparisons do not convert strings to numbers
2054 or vice versa.
2055 Thus, <code>"0"==0</code> evaluates to <b>false</b>,
2056 and <code>t[0]</code> and <code>t["0"]</code> denote different
2057 entries in a table.
2058
2059
2060 <p>
2061 The operator <code>~=</code> is exactly the negation of equality (<code>==</code>).
2062
2063
2064 <p>
2065 The order operators work as follows.
2066 If both arguments are numbers,
2067 then they are compared according to their mathematical values
2068 (regardless of their subtypes).
2069 Otherwise, if both arguments are strings,
2070 then their values are compared according to the current locale.
2071 Otherwise, Lua tries to call the "lt" or the "le"
2072 metamethod (see <a href="#2.4">&sect;2.4</a>).
2073 A comparison <code>a &gt; b</code> is translated to <code>b &lt; a</code>
2074 and <code>a &gt;= b</code> is translated to <code>b &lt;= a</code>.
2075
2076
2077 <p>
2078 Following the IEEE 754 standard,
2079 NaN is considered neither smaller than,
2080 nor equal to, nor greater than any value (including itself).
2081
2082
2083
2084
2085
2086 <h3>3.4.5 &ndash; <a name="3.4.5">Logical Operators</a></h3><p>
2087 The logical operators in Lua are
2088 <b>and</b>, <b>or</b>, and <b>not</b>.
2089 Like the control structures (see <a href="#3.3.4">&sect;3.3.4</a>),
2090 all logical operators consider both <b>false</b> and <b>nil</b> as false
2091 and anything else as true.
2092
2093
2094 <p>
2095 The negation operator <b>not</b> always returns <b>false</b> or <b>true</b>.
2096 The conjunction operator <b>and</b> returns its first argument
2097 if this value is <b>false</b> or <b>nil</b>;
2098 otherwise, <b>and</b> returns its second argument.
2099 The disjunction operator <b>or</b> returns its first argument
2100 if this value is different from <b>nil</b> and <b>false</b>;
2101 otherwise, <b>or</b> returns its second argument.
2102 Both <b>and</b> and <b>or</b> use short-circuit evaluation;
2103 that is,
2104 the second operand is evaluated only if necessary.
2105 Here are some examples:
2106
2107 <pre>
2108      10 or 20            --&gt; 10
2109      10 or error()       --&gt; 10
2110      nil or "a"          --&gt; "a"
2111      nil and 10          --&gt; nil
2112      false and error()   --&gt; false
2113      false and nil       --&gt; false
2114      false or nil        --&gt; nil
2115      10 and 20           --&gt; 20
2116 </pre><p>
2117 (In this manual,
2118 <code>--&gt;</code> indicates the result of the preceding expression.)
2119
2120
2121
2122
2123
2124 <h3>3.4.6 &ndash; <a name="3.4.6">Concatenation</a></h3><p>
2125 The string concatenation operator in Lua is
2126 denoted by two dots ('<code>..</code>').
2127 If both operands are strings or numbers, then they are converted to
2128 strings according to the rules described in <a href="#3.4.3">&sect;3.4.3</a>.
2129 Otherwise, the <code>__concat</code> metamethod is called (see <a href="#2.4">&sect;2.4</a>).
2130
2131
2132
2133
2134
2135 <h3>3.4.7 &ndash; <a name="3.4.7">The Length Operator</a></h3>
2136
2137 <p>
2138 The length operator is denoted by the unary prefix operator <code>#</code>.
2139
2140
2141 <p>
2142 The length of a string is its number of bytes
2143 (that is, the usual meaning of string length when each
2144 character is one byte).
2145
2146
2147 <p>
2148 The length operator applied on a table
2149 returns a border in that table.
2150 A <em>border</em> in a table <code>t</code> is any natural number
2151 that satisfies the following condition:
2152
2153 <pre>
2154      (border == 0 or t[border] ~= nil) and t[border + 1] == nil
2155 </pre><p>
2156 In words,
2157 a border is any (natural) index in a table
2158 where a non-nil value is followed by a nil value
2159 (or zero, when index 1 is nil).
2160
2161
2162 <p>
2163 A table with exactly one border is called a <em>sequence</em>.
2164 For instance, the table <code>{10, 20, 30, 40, 50}</code> is a sequence,
2165 as it has only one border (5).
2166 The table <code>{10, 20, 30, nil, 50}</code> has two borders (3 and 5),
2167 and therefore it is not a sequence.
2168 The table <code>{nil, 20, 30, nil, nil, 60, nil}</code>
2169 has three borders (0, 3, and 6),
2170 so it is not a sequence, too.
2171 The table <code>{}</code> is a sequence with border 0.
2172 Note that non-natural keys do not interfere
2173 with whether a table is a sequence.
2174
2175
2176 <p>
2177 When <code>t</code> is a sequence,
2178 <code>#t</code> returns its only border,
2179 which corresponds to the intuitive notion of the length of the sequence.
2180 When <code>t</code> is not a sequence,
2181 <code>#t</code> can return any of its borders.
2182 (The exact one depends on details of
2183 the internal representation of the table,
2184 which in turn can depend on how the table was populated and
2185 the memory addresses of its non-numeric keys.)
2186
2187
2188 <p>
2189 The computation of the length of a table
2190 has a guaranteed worst time of <em>O(log n)</em>,
2191 where <em>n</em> is the largest natural key in the table.
2192
2193
2194 <p>
2195 A program can modify the behavior of the length operator for
2196 any value but strings through the <code>__len</code> metamethod (see <a href="#2.4">&sect;2.4</a>).
2197
2198
2199
2200
2201
2202 <h3>3.4.8 &ndash; <a name="3.4.8">Precedence</a></h3><p>
2203 Operator precedence in Lua follows the table below,
2204 from lower to higher priority:
2205
2206 <pre>
2207      or
2208      and
2209      &lt;     &gt;     &lt;=    &gt;=    ~=    ==
2210      |
2211      ~
2212      &amp;
2213      &lt;&lt;    &gt;&gt;
2214      ..
2215      +     -
2216      *     /     //    %
2217      unary operators (not   #     -     ~)
2218      ^
2219 </pre><p>
2220 As usual,
2221 you can use parentheses to change the precedences of an expression.
2222 The concatenation ('<code>..</code>') and exponentiation ('<code>^</code>')
2223 operators are right associative.
2224 All other binary operators are left associative.
2225
2226
2227
2228
2229
2230 <h3>3.4.9 &ndash; <a name="3.4.9">Table Constructors</a></h3><p>
2231 Table constructors are expressions that create tables.
2232 Every time a constructor is evaluated, a new table is created.
2233 A constructor can be used to create an empty table
2234 or to create a table and initialize some of its fields.
2235 The general syntax for constructors is
2236
2237 <pre>
2238         tableconstructor ::= &lsquo;<b>{</b>&rsquo; [fieldlist] &lsquo;<b>}</b>&rsquo;
2239         fieldlist ::= field {fieldsep field} [fieldsep]
2240         field ::= &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo; &lsquo;<b>=</b>&rsquo; exp | Name &lsquo;<b>=</b>&rsquo; exp | exp
2241         fieldsep ::= &lsquo;<b>,</b>&rsquo; | &lsquo;<b>;</b>&rsquo;
2242 </pre>
2243
2244 <p>
2245 Each field of the form <code>[exp1] = exp2</code> adds to the new table an entry
2246 with key <code>exp1</code> and value <code>exp2</code>.
2247 A field of the form <code>name = exp</code> is equivalent to
2248 <code>["name"] = exp</code>.
2249 Finally, fields of the form <code>exp</code> are equivalent to
2250 <code>[i] = exp</code>, where <code>i</code> are consecutive integers
2251 starting with 1.
2252 Fields in the other formats do not affect this counting.
2253 For example,
2254
2255 <pre>
2256      a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 }
2257 </pre><p>
2258 is equivalent to
2259
2260 <pre>
2261      do
2262        local t = {}
2263        t[f(1)] = g
2264        t[1] = "x"         -- 1st exp
2265        t[2] = "y"         -- 2nd exp
2266        t.x = 1            -- t["x"] = 1
2267        t[3] = f(x)        -- 3rd exp
2268        t[30] = 23
2269        t[4] = 45          -- 4th exp
2270        a = t
2271      end
2272 </pre>
2273
2274 <p>
2275 The order of the assignments in a constructor is undefined.
2276 (This order would be relevant only when there are repeated keys.)
2277
2278
2279 <p>
2280 If the last field in the list has the form <code>exp</code>
2281 and the expression is a function call or a vararg expression,
2282 then all values returned by this expression enter the list consecutively
2283 (see <a href="#3.4.10">&sect;3.4.10</a>).
2284
2285
2286 <p>
2287 The field list can have an optional trailing separator,
2288 as a convenience for machine-generated code.
2289
2290
2291
2292
2293
2294 <h3>3.4.10 &ndash; <a name="3.4.10">Function Calls</a></h3><p>
2295 A function call in Lua has the following syntax:
2296
2297 <pre>
2298         functioncall ::= prefixexp args
2299 </pre><p>
2300 In a function call,
2301 first prefixexp and args are evaluated.
2302 If the value of prefixexp has type <em>function</em>,
2303 then this function is called
2304 with the given arguments.
2305 Otherwise, the prefixexp "call" metamethod is called,
2306 having as first parameter the value of prefixexp,
2307 followed by the original call arguments
2308 (see <a href="#2.4">&sect;2.4</a>).
2309
2310
2311 <p>
2312 The form
2313
2314 <pre>
2315         functioncall ::= prefixexp &lsquo;<b>:</b>&rsquo; Name args
2316 </pre><p>
2317 can be used to call "methods".
2318 A call <code>v:name(<em>args</em>)</code>
2319 is syntactic sugar for <code>v.name(v,<em>args</em>)</code>,
2320 except that <code>v</code> is evaluated only once.
2321
2322
2323 <p>
2324 Arguments have the following syntax:
2325
2326 <pre>
2327         args ::= &lsquo;<b>(</b>&rsquo; [explist] &lsquo;<b>)</b>&rsquo;
2328         args ::= tableconstructor
2329         args ::= LiteralString
2330 </pre><p>
2331 All argument expressions are evaluated before the call.
2332 A call of the form <code>f{<em>fields</em>}</code> is
2333 syntactic sugar for <code>f({<em>fields</em>})</code>;
2334 that is, the argument list is a single new table.
2335 A call of the form <code>f'<em>string</em>'</code>
2336 (or <code>f"<em>string</em>"</code> or <code>f[[<em>string</em>]]</code>)
2337 is syntactic sugar for <code>f('<em>string</em>')</code>;
2338 that is, the argument list is a single literal string.
2339
2340
2341 <p>
2342 A call of the form <code>return <em>functioncall</em></code> is called
2343 a <em>tail call</em>.
2344 Lua implements <em>proper tail calls</em>
2345 (or <em>proper tail recursion</em>):
2346 in a tail call,
2347 the called function reuses the stack entry of the calling function.
2348 Therefore, there is no limit on the number of nested tail calls that
2349 a program can execute.
2350 However, a tail call erases any debug information about the
2351 calling function.
2352 Note that a tail call only happens with a particular syntax,
2353 where the <b>return</b> has one single function call as argument;
2354 this syntax makes the calling function return exactly
2355 the returns of the called function.
2356 So, none of the following examples are tail calls:
2357
2358 <pre>
2359      return (f(x))        -- results adjusted to 1
2360      return 2 * f(x)
2361      return x, f(x)       -- additional results
2362      f(x); return         -- results discarded
2363      return x or f(x)     -- results adjusted to 1
2364 </pre>
2365
2366
2367
2368
2369 <h3>3.4.11 &ndash; <a name="3.4.11">Function Definitions</a></h3>
2370
2371 <p>
2372 The syntax for function definition is
2373
2374 <pre>
2375         functiondef ::= <b>function</b> funcbody
2376         funcbody ::= &lsquo;<b>(</b>&rsquo; [parlist] &lsquo;<b>)</b>&rsquo; block <b>end</b>
2377 </pre>
2378
2379 <p>
2380 The following syntactic sugar simplifies function definitions:
2381
2382 <pre>
2383         stat ::= <b>function</b> funcname funcbody
2384         stat ::= <b>local</b> <b>function</b> Name funcbody
2385         funcname ::= Name {&lsquo;<b>.</b>&rsquo; Name} [&lsquo;<b>:</b>&rsquo; Name]
2386 </pre><p>
2387 The statement
2388
2389 <pre>
2390      function f () <em>body</em> end
2391 </pre><p>
2392 translates to
2393
2394 <pre>
2395      f = function () <em>body</em> end
2396 </pre><p>
2397 The statement
2398
2399 <pre>
2400      function t.a.b.c.f () <em>body</em> end
2401 </pre><p>
2402 translates to
2403
2404 <pre>
2405      t.a.b.c.f = function () <em>body</em> end
2406 </pre><p>
2407 The statement
2408
2409 <pre>
2410      local function f () <em>body</em> end
2411 </pre><p>
2412 translates to
2413
2414 <pre>
2415      local f; f = function () <em>body</em> end
2416 </pre><p>
2417 not to
2418
2419 <pre>
2420      local f = function () <em>body</em> end
2421 </pre><p>
2422 (This only makes a difference when the body of the function
2423 contains references to <code>f</code>.)
2424
2425
2426 <p>
2427 A function definition is an executable expression,
2428 whose value has type <em>function</em>.
2429 When Lua precompiles a chunk,
2430 all its function bodies are precompiled too.
2431 Then, whenever Lua executes the function definition,
2432 the function is <em>instantiated</em> (or <em>closed</em>).
2433 This function instance (or <em>closure</em>)
2434 is the final value of the expression.
2435
2436
2437 <p>
2438 Parameters act as local variables that are
2439 initialized with the argument values:
2440
2441 <pre>
2442         parlist ::= namelist [&lsquo;<b>,</b>&rsquo; &lsquo;<b>...</b>&rsquo;] | &lsquo;<b>...</b>&rsquo;
2443 </pre><p>
2444 When a function is called,
2445 the list of arguments is adjusted to
2446 the length of the list of parameters,
2447 unless the function is a <em>vararg function</em>,
2448 which is indicated by three dots ('<code>...</code>')
2449 at the end of its parameter list.
2450 A vararg function does not adjust its argument list;
2451 instead, it collects all extra arguments and supplies them
2452 to the function through a <em>vararg expression</em>,
2453 which is also written as three dots.
2454 The value of this expression is a list of all actual extra arguments,
2455 similar to a function with multiple results.
2456 If a vararg expression is used inside another expression
2457 or in the middle of a list of expressions,
2458 then its return list is adjusted to one element.
2459 If the expression is used as the last element of a list of expressions,
2460 then no adjustment is made
2461 (unless that last expression is enclosed in parentheses).
2462
2463
2464 <p>
2465 As an example, consider the following definitions:
2466
2467 <pre>
2468      function f(a, b) end
2469      function g(a, b, ...) end
2470      function r() return 1,2,3 end
2471 </pre><p>
2472 Then, we have the following mapping from arguments to parameters and
2473 to the vararg expression:
2474
2475 <pre>
2476      CALL            PARAMETERS
2477
2478      f(3)             a=3, b=nil
2479      f(3, 4)          a=3, b=4
2480      f(3, 4, 5)       a=3, b=4
2481      f(r(), 10)       a=1, b=10
2482      f(r())           a=1, b=2
2483
2484      g(3)             a=3, b=nil, ... --&gt;  (nothing)
2485      g(3, 4)          a=3, b=4,   ... --&gt;  (nothing)
2486      g(3, 4, 5, 8)    a=3, b=4,   ... --&gt;  5  8
2487      g(5, r())        a=5, b=1,   ... --&gt;  2  3
2488 </pre>
2489
2490 <p>
2491 Results are returned using the <b>return</b> statement (see <a href="#3.3.4">&sect;3.3.4</a>).
2492 If control reaches the end of a function
2493 without encountering a <b>return</b> statement,
2494 then the function returns with no results.
2495
2496
2497 <p>
2498
2499 There is a system-dependent limit on the number of values
2500 that a function may return.
2501 This limit is guaranteed to be larger than 1000.
2502
2503
2504 <p>
2505 The <em>colon</em> syntax
2506 is used for defining <em>methods</em>,
2507 that is, functions that have an implicit extra parameter <code>self</code>.
2508 Thus, the statement
2509
2510 <pre>
2511      function t.a.b.c:f (<em>params</em>) <em>body</em> end
2512 </pre><p>
2513 is syntactic sugar for
2514
2515 <pre>
2516      t.a.b.c.f = function (self, <em>params</em>) <em>body</em> end
2517 </pre>
2518
2519
2520
2521
2522
2523
2524 <h2>3.5 &ndash; <a name="3.5">Visibility Rules</a></h2>
2525
2526 <p>
2527
2528 Lua is a lexically scoped language.
2529 The scope of a local variable begins at the first statement after
2530 its declaration and lasts until the last non-void statement
2531 of the innermost block that includes the declaration.
2532 Consider the following example:
2533
2534 <pre>
2535      x = 10                -- global variable
2536      do                    -- new block
2537        local x = x         -- new 'x', with value 10
2538        print(x)            --&gt; 10
2539        x = x+1
2540        do                  -- another block
2541          local x = x+1     -- another 'x'
2542          print(x)          --&gt; 12
2543        end
2544        print(x)            --&gt; 11
2545      end
2546      print(x)              --&gt; 10  (the global one)
2547 </pre>
2548
2549 <p>
2550 Notice that, in a declaration like <code>local x = x</code>,
2551 the new <code>x</code> being declared is not in scope yet,
2552 and so the second <code>x</code> refers to the outside variable.
2553
2554
2555 <p>
2556 Because of the lexical scoping rules,
2557 local variables can be freely accessed by functions
2558 defined inside their scope.
2559 A local variable used by an inner function is called
2560 an <em>upvalue</em>, or <em>external local variable</em>,
2561 inside the inner function.
2562
2563
2564 <p>
2565 Notice that each execution of a <b>local</b> statement
2566 defines new local variables.
2567 Consider the following example:
2568
2569 <pre>
2570      a = {}
2571      local x = 20
2572      for i=1,10 do
2573        local y = 0
2574        a[i] = function () y=y+1; return x+y end
2575      end
2576 </pre><p>
2577 The loop creates ten closures
2578 (that is, ten instances of the anonymous function).
2579 Each of these closures uses a different <code>y</code> variable,
2580 while all of them share the same <code>x</code>.
2581
2582
2583
2584
2585
2586 <h1>4 &ndash; <a name="4">The Application Program Interface</a></h1>
2587
2588 <p>
2589
2590 This section describes the C&nbsp;API for Lua, that is,
2591 the set of C&nbsp;functions available to the host program to communicate
2592 with Lua.
2593 All API functions and related types and constants
2594 are declared in the header file <a name="pdf-lua.h"><code>lua.h</code></a>.
2595
2596
2597 <p>
2598 Even when we use the term "function",
2599 any facility in the API may be provided as a macro instead.
2600 Except where stated otherwise,
2601 all such macros use each of their arguments exactly once
2602 (except for the first argument, which is always a Lua state),
2603 and so do not generate any hidden side-effects.
2604
2605
2606 <p>
2607 As in most C&nbsp;libraries,
2608 the Lua API functions do not check their arguments for validity or consistency.
2609 However, you can change this behavior by compiling Lua
2610 with the macro <a name="pdf-LUA_USE_APICHECK"><code>LUA_USE_APICHECK</code></a> defined.
2611
2612
2613 <p>
2614 The Lua library is fully reentrant:
2615 it has no global variables.
2616 It keeps all information it needs in a dynamic structure,
2617 called the <em>Lua state</em>.
2618
2619
2620 <p>
2621 Each Lua state has one or more threads,
2622 which correspond to independent, cooperative lines of execution.
2623 The type <a href="#lua_State"><code>lua_State</code></a> (despite its name) refers to a thread.
2624 (Indirectly, through the thread, it also refers to the
2625 Lua state associated to the thread.)
2626
2627
2628 <p>
2629 A pointer to a thread must be passed as the first argument to
2630 every function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>,
2631 which creates a Lua state from scratch and returns a pointer
2632 to the <em>main thread</em> in the new state.
2633
2634
2635
2636 <h2>4.1 &ndash; <a name="4.1">The Stack</a></h2>
2637
2638 <p>
2639 Lua uses a <em>virtual stack</em> to pass values to and from C.
2640 Each element in this stack represents a Lua value
2641 (<b>nil</b>, number, string, etc.).
2642 Functions in the API can access this stack through the
2643 Lua state parameter that they receive.
2644
2645
2646 <p>
2647 Whenever Lua calls C, the called function gets a new stack,
2648 which is independent of previous stacks and of stacks of
2649 C&nbsp;functions that are still active.
2650 This stack initially contains any arguments to the C&nbsp;function
2651 and it is where the C&nbsp;function can store temporary
2652 Lua values and must push its results
2653 to be returned to the caller (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>).
2654
2655
2656 <p>
2657 For convenience,
2658 most query operations in the API do not follow a strict stack discipline.
2659 Instead, they can refer to any element in the stack
2660 by using an <em>index</em>:
2661 A positive index represents an absolute stack position
2662 (starting at&nbsp;1);
2663 a negative index represents an offset relative to the top of the stack.
2664 More specifically, if the stack has <em>n</em> elements,
2665 then index&nbsp;1 represents the first element
2666 (that is, the element that was pushed onto the stack first)
2667 and
2668 index&nbsp;<em>n</em> represents the last element;
2669 index&nbsp;-1 also represents the last element
2670 (that is, the element at the&nbsp;top)
2671 and index <em>-n</em> represents the first element.
2672
2673
2674
2675
2676
2677 <h2>4.2 &ndash; <a name="4.2">Stack Size</a></h2>
2678
2679 <p>
2680 When you interact with the Lua API,
2681 you are responsible for ensuring consistency.
2682 In particular,
2683 <em>you are responsible for controlling stack overflow</em>.
2684 You can use the function <a href="#lua_checkstack"><code>lua_checkstack</code></a>
2685 to ensure that the stack has enough space for pushing new elements.
2686
2687
2688 <p>
2689 Whenever Lua calls C,
2690 it ensures that the stack has space for
2691 at least <a name="pdf-LUA_MINSTACK"><code>LUA_MINSTACK</code></a> extra slots.
2692 <code>LUA_MINSTACK</code> is defined as 20,
2693 so that usually you do not have to worry about stack space
2694 unless your code has loops pushing elements onto the stack.
2695
2696
2697 <p>
2698 When you call a Lua function
2699 without a fixed number of results (see <a href="#lua_call"><code>lua_call</code></a>),
2700 Lua ensures that the stack has enough space for all results,
2701 but it does not ensure any extra space.
2702 So, before pushing anything in the stack after such a call
2703 you should use <a href="#lua_checkstack"><code>lua_checkstack</code></a>.
2704
2705
2706
2707
2708
2709 <h2>4.3 &ndash; <a name="4.3">Valid and Acceptable Indices</a></h2>
2710
2711 <p>
2712 Any function in the API that receives stack indices
2713 works only with <em>valid indices</em> or <em>acceptable indices</em>.
2714
2715
2716 <p>
2717 A <em>valid index</em> is an index that refers to a
2718 position that stores a modifiable Lua value.
2719 It comprises stack indices between&nbsp;1 and the stack top
2720 (<code>1 &le; abs(index) &le; top</code>)
2721
2722 plus <em>pseudo-indices</em>,
2723 which represent some positions that are accessible to C&nbsp;code
2724 but that are not in the stack.
2725 Pseudo-indices are used to access the registry (see <a href="#4.5">&sect;4.5</a>)
2726 and the upvalues of a C&nbsp;function (see <a href="#4.4">&sect;4.4</a>).
2727
2728
2729 <p>
2730 Functions that do not need a specific mutable position,
2731 but only a value (e.g., query functions),
2732 can be called with acceptable indices.
2733 An <em>acceptable index</em> can be any valid index,
2734 but it also can be any positive index after the stack top
2735 within the space allocated for the stack,
2736 that is, indices up to the stack size.
2737 (Note that 0 is never an acceptable index.)
2738 Except when noted otherwise,
2739 functions in the API work with acceptable indices.
2740
2741
2742 <p>
2743 Acceptable indices serve to avoid extra tests
2744 against the stack top when querying the stack.
2745 For instance, a C&nbsp;function can query its third argument
2746 without the need to first check whether there is a third argument,
2747 that is, without the need to check whether 3 is a valid index.
2748
2749
2750 <p>
2751 For functions that can be called with acceptable indices,
2752 any non-valid index is treated as if it
2753 contains a value of a virtual type <a name="pdf-LUA_TNONE"><code>LUA_TNONE</code></a>,
2754 which behaves like a nil value.
2755
2756
2757
2758
2759
2760 <h2>4.4 &ndash; <a name="4.4">C Closures</a></h2>
2761
2762 <p>
2763 When a C&nbsp;function is created,
2764 it is possible to associate some values with it,
2765 thus creating a <em>C&nbsp;closure</em>
2766 (see <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>);
2767 these values are called <em>upvalues</em> and are
2768 accessible to the function whenever it is called.
2769
2770
2771 <p>
2772 Whenever a C&nbsp;function is called,
2773 its upvalues are located at specific pseudo-indices.
2774 These pseudo-indices are produced by the macro
2775 <a href="#lua_upvalueindex"><code>lua_upvalueindex</code></a>.
2776 The first upvalue associated with a function is at index
2777 <code>lua_upvalueindex(1)</code>, and so on.
2778 Any access to <code>lua_upvalueindex(<em>n</em>)</code>,
2779 where <em>n</em> is greater than the number of upvalues of the
2780 current function
2781 (but not greater than 256,
2782 which is one plus the maximum number of upvalues in a closure),
2783 produces an acceptable but invalid index.
2784
2785
2786
2787
2788
2789 <h2>4.5 &ndash; <a name="4.5">Registry</a></h2>
2790
2791 <p>
2792 Lua provides a <em>registry</em>,
2793 a predefined table that can be used by any C&nbsp;code to
2794 store whatever Lua values it needs to store.
2795 The registry table is always located at pseudo-index
2796 <a name="pdf-LUA_REGISTRYINDEX"><code>LUA_REGISTRYINDEX</code></a>.
2797 Any C&nbsp;library can store data into this table,
2798 but it must take care to choose keys
2799 that are different from those used
2800 by other libraries, to avoid collisions.
2801 Typically, you should use as key a string containing your library name,
2802 or a light userdata with the address of a C&nbsp;object in your code,
2803 or any Lua object created by your code.
2804 As with variable names,
2805 string keys starting with an underscore followed by
2806 uppercase letters are reserved for Lua.
2807
2808
2809 <p>
2810 The integer keys in the registry are used
2811 by the reference mechanism (see <a href="#luaL_ref"><code>luaL_ref</code></a>)
2812 and by some predefined values.
2813 Therefore, integer keys must not be used for other purposes.
2814
2815
2816 <p>
2817 When you create a new Lua state,
2818 its registry comes with some predefined values.
2819 These predefined values are indexed with integer keys
2820 defined as constants in <code>lua.h</code>.
2821 The following constants are defined:
2822
2823 <ul>
2824 <li><b><a name="pdf-LUA_RIDX_MAINTHREAD"><code>LUA_RIDX_MAINTHREAD</code></a>: </b> At this index the registry has
2825 the main thread of the state.
2826 (The main thread is the one created together with the state.)
2827 </li>
2828
2829 <li><b><a name="pdf-LUA_RIDX_GLOBALS"><code>LUA_RIDX_GLOBALS</code></a>: </b> At this index the registry has
2830 the global environment.
2831 </li>
2832 </ul>
2833
2834
2835
2836
2837 <h2>4.6 &ndash; <a name="4.6">Error Handling in C</a></h2>
2838
2839 <p>
2840 Internally, Lua uses the C <code>longjmp</code> facility to handle errors.
2841 (Lua will use exceptions if you compile it as C++;
2842 search for <code>LUAI_THROW</code> in the source code for details.)
2843 When Lua faces any error
2844 (such as a memory allocation error or a type error)
2845 it <em>raises</em> an error;
2846 that is, it does a long jump.
2847 A <em>protected environment</em> uses <code>setjmp</code>
2848 to set a recovery point;
2849 any error jumps to the most recent active recovery point.
2850
2851
2852 <p>
2853 Inside a C&nbsp;function you can raise an error by calling <a href="#lua_error"><code>lua_error</code></a>.
2854
2855
2856 <p>
2857 Most functions in the API can raise an error,
2858 for instance due to a memory allocation error.
2859 The documentation for each function indicates whether
2860 it can raise errors.
2861
2862
2863 <p>
2864 If an error happens outside any protected environment,
2865 Lua calls a <em>panic function</em> (see <a href="#lua_atpanic"><code>lua_atpanic</code></a>)
2866 and then calls <code>abort</code>,
2867 thus exiting the host application.
2868 Your panic function can avoid this exit by
2869 never returning
2870 (e.g., doing a long jump to your own recovery point outside Lua).
2871
2872
2873 <p>
2874 The panic function,
2875 as its name implies,
2876 is a mechanism of last resort.
2877 Programs should avoid it.
2878 As a general rule,
2879 when a C&nbsp;function is called by Lua with a Lua state,
2880 it can do whatever it wants on that Lua state,
2881 as it should be already protected.
2882 However,
2883 when C code operates on other Lua states
2884 (e.g., a Lua parameter to the function,
2885 a Lua state stored in the registry, or
2886 the result of <a href="#lua_newthread"><code>lua_newthread</code></a>),
2887 it should use them only in API calls that cannot raise errors.
2888
2889
2890 <p>
2891 The panic function runs as if it were a message handler (see <a href="#2.3">&sect;2.3</a>);
2892 in particular, the error object is at the top of the stack.
2893 However, there is no guarantee about stack space.
2894 To push anything on the stack,
2895 the panic function must first check the available space (see <a href="#4.2">&sect;4.2</a>).
2896
2897
2898
2899
2900
2901 <h2>4.7 &ndash; <a name="4.7">Handling Yields in C</a></h2>
2902
2903 <p>
2904 Internally, Lua uses the C <code>longjmp</code> facility to yield a coroutine.
2905 Therefore, if a C&nbsp;function <code>foo</code> calls an API function
2906 and this API function yields
2907 (directly or indirectly by calling another function that yields),
2908 Lua cannot return to <code>foo</code> any more,
2909 because the <code>longjmp</code> removes its frame from the C stack.
2910
2911
2912 <p>
2913 To avoid this kind of problem,
2914 Lua raises an error whenever it tries to yield across an API call,
2915 except for three functions:
2916 <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>.
2917 All those functions receive a <em>continuation function</em>
2918 (as a parameter named <code>k</code>) to continue execution after a yield.
2919
2920
2921 <p>
2922 We need to set some terminology to explain continuations.
2923 We have a C&nbsp;function called from Lua which we will call
2924 the <em>original function</em>.
2925 This original function then calls one of those three functions in the C API,
2926 which we will call the <em>callee function</em>,
2927 that then yields the current thread.
2928 (This can happen when the callee function is <a href="#lua_yieldk"><code>lua_yieldk</code></a>,
2929 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>
2930 and the function called by them yields.)
2931
2932
2933 <p>
2934 Suppose the running thread yields while executing the callee function.
2935 After the thread resumes,
2936 it eventually will finish running the callee function.
2937 However,
2938 the callee function cannot return to the original function,
2939 because its frame in the C stack was destroyed by the yield.
2940 Instead, Lua calls a <em>continuation function</em>,
2941 which was given as an argument to the callee function.
2942 As the name implies,
2943 the continuation function should continue the task
2944 of the original function.
2945
2946
2947 <p>
2948 As an illustration, consider the following function:
2949
2950 <pre>
2951      int original_function (lua_State *L) {
2952        ...     /* code 1 */
2953        status = lua_pcall(L, n, m, h);  /* calls Lua */
2954        ...     /* code 2 */
2955      }
2956 </pre><p>
2957 Now we want to allow
2958 the Lua code being run by <a href="#lua_pcall"><code>lua_pcall</code></a> to yield.
2959 First, we can rewrite our function like here:
2960
2961 <pre>
2962      int k (lua_State *L, int status, lua_KContext ctx) {
2963        ...  /* code 2 */
2964      }
2965
2966      int original_function (lua_State *L) {
2967        ...     /* code 1 */
2968        return k(L, lua_pcall(L, n, m, h), ctx);
2969      }
2970 </pre><p>
2971 In the above code,
2972 the new function <code>k</code> is a
2973 <em>continuation function</em> (with type <a href="#lua_KFunction"><code>lua_KFunction</code></a>),
2974 which should do all the work that the original function
2975 was doing after calling <a href="#lua_pcall"><code>lua_pcall</code></a>.
2976 Now, we must inform Lua that it must call <code>k</code> if the Lua code
2977 being executed by <a href="#lua_pcall"><code>lua_pcall</code></a> gets interrupted in some way
2978 (errors or yielding),
2979 so we rewrite the code as here,
2980 replacing <a href="#lua_pcall"><code>lua_pcall</code></a> by <a href="#lua_pcallk"><code>lua_pcallk</code></a>:
2981
2982 <pre>
2983      int original_function (lua_State *L) {
2984        ...     /* code 1 */
2985        return k(L, lua_pcallk(L, n, m, h, ctx2, k), ctx1);
2986      }
2987 </pre><p>
2988 Note the external, explicit call to the continuation:
2989 Lua will call the continuation only if needed, that is,
2990 in case of errors or resuming after a yield.
2991 If the called function returns normally without ever yielding,
2992 <a href="#lua_pcallk"><code>lua_pcallk</code></a> (and <a href="#lua_callk"><code>lua_callk</code></a>) will also return normally.
2993 (Of course, instead of calling the continuation in that case,
2994 you can do the equivalent work directly inside the original function.)
2995
2996
2997 <p>
2998 Besides the Lua state,
2999 the continuation function has two other parameters:
3000 the final status of the call plus the context value (<code>ctx</code>) that
3001 was passed originally to <a href="#lua_pcallk"><code>lua_pcallk</code></a>.
3002 (Lua does not use this context value;
3003 it only passes this value from the original function to the
3004 continuation function.)
3005 For <a href="#lua_pcallk"><code>lua_pcallk</code></a>,
3006 the status is the same value that would be returned by <a href="#lua_pcallk"><code>lua_pcallk</code></a>,
3007 except that it is <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when being executed after a yield
3008 (instead of <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>).
3009 For <a href="#lua_yieldk"><code>lua_yieldk</code></a> and <a href="#lua_callk"><code>lua_callk</code></a>,
3010 the status is always <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when Lua calls the continuation.
3011 (For these two functions,
3012 Lua will not call the continuation in case of errors,
3013 because they do not handle errors.)
3014 Similarly, when using <a href="#lua_callk"><code>lua_callk</code></a>,
3015 you should call the continuation function
3016 with <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> as the status.
3017 (For <a href="#lua_yieldk"><code>lua_yieldk</code></a>, there is not much point in calling
3018 directly the continuation function,
3019 because <a href="#lua_yieldk"><code>lua_yieldk</code></a> usually does not return.)
3020
3021
3022 <p>
3023 Lua treats the continuation function as if it were the original function.
3024 The continuation function receives the same Lua stack
3025 from the original function,
3026 in the same state it would be if the callee function had returned.
3027 (For instance,
3028 after a <a href="#lua_callk"><code>lua_callk</code></a> the function and its arguments are
3029 removed from the stack and replaced by the results from the call.)
3030 It also has the same upvalues.
3031 Whatever it returns is handled by Lua as if it were the return
3032 of the original function.
3033
3034
3035
3036
3037
3038 <h2>4.8 &ndash; <a name="4.8">Functions and Types</a></h2>
3039
3040 <p>
3041 Here we list all functions and types from the C&nbsp;API in
3042 alphabetical order.
3043 Each function has an indicator like this:
3044 <span class="apii">[-o, +p, <em>x</em>]</span>
3045
3046
3047 <p>
3048 The first field, <code>o</code>,
3049 is how many elements the function pops from the stack.
3050 The second field, <code>p</code>,
3051 is how many elements the function pushes onto the stack.
3052 (Any function always pushes its results after popping its arguments.)
3053 A field in the form <code>x|y</code> means the function can push (or pop)
3054 <code>x</code> or <code>y</code> elements,
3055 depending on the situation;
3056 an interrogation mark '<code>?</code>' means that
3057 we cannot know how many elements the function pops/pushes
3058 by looking only at its arguments
3059 (e.g., they may depend on what is on the stack).
3060 The third field, <code>x</code>,
3061 tells whether the function may raise errors:
3062 '<code>-</code>' means the function never raises any error;
3063 '<code>m</code>' means the function may raise out-of-memory errors
3064 and errors running a <code>__gc</code> metamethod;
3065 '<code>e</code>' means the function may raise any errors
3066 (it can run arbitrary Lua code,
3067 either directly or through metamethods);
3068 '<code>v</code>' means the function may raise an error on purpose.
3069
3070
3071
3072 <hr><h3><a name="lua_absindex"><code>lua_absindex</code></a></h3><p>
3073 <span class="apii">[-0, +0, &ndash;]</span>
3074 <pre>int lua_absindex (lua_State *L, int idx);</pre>
3075
3076 <p>
3077 Converts the acceptable index <code>idx</code>
3078 into an equivalent absolute index
3079 (that is, one that does not depend on the stack top).
3080
3081
3082
3083
3084
3085 <hr><h3><a name="lua_Alloc"><code>lua_Alloc</code></a></h3>
3086 <pre>typedef void * (*lua_Alloc) (void *ud,
3087                              void *ptr,
3088                              size_t osize,
3089                              size_t nsize);</pre>
3090
3091 <p>
3092 The type of the memory-allocation function used by Lua states.
3093 The allocator function must provide a
3094 functionality similar to <code>realloc</code>,
3095 but not exactly the same.
3096 Its arguments are
3097 <code>ud</code>, an opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>;
3098 <code>ptr</code>, a pointer to the block being allocated/reallocated/freed;
3099 <code>osize</code>, the original size of the block or some code about what
3100 is being allocated;
3101 and <code>nsize</code>, the new size of the block.
3102
3103
3104 <p>
3105 When <code>ptr</code> is not <code>NULL</code>,
3106 <code>osize</code> is the size of the block pointed by <code>ptr</code>,
3107 that is, the size given when it was allocated or reallocated.
3108
3109
3110 <p>
3111 When <code>ptr</code> is <code>NULL</code>,
3112 <code>osize</code> encodes the kind of object that Lua is allocating.
3113 <code>osize</code> is any of
3114 <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>,
3115 <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)
3116 Lua is creating a new object of that type.
3117 When <code>osize</code> is some other value,
3118 Lua is allocating memory for something else.
3119
3120
3121 <p>
3122 Lua assumes the following behavior from the allocator function:
3123
3124
3125 <p>
3126 When <code>nsize</code> is zero,
3127 the allocator must behave like <code>free</code>
3128 and return <code>NULL</code>.
3129
3130
3131 <p>
3132 When <code>nsize</code> is not zero,
3133 the allocator must behave like <code>realloc</code>.
3134 The allocator returns <code>NULL</code>
3135 if and only if it cannot fulfill the request.
3136 Lua assumes that the allocator never fails when
3137 <code>osize &gt;= nsize</code>.
3138
3139
3140 <p>
3141 Here is a simple implementation for the allocator function.
3142 It is used in the auxiliary library by <a href="#luaL_newstate"><code>luaL_newstate</code></a>.
3143
3144 <pre>
3145      static void *l_alloc (void *ud, void *ptr, size_t osize,
3146                                                 size_t nsize) {
3147        (void)ud;  (void)osize;  /* not used */
3148        if (nsize == 0) {
3149          free(ptr);
3150          return NULL;
3151        }
3152        else
3153          return realloc(ptr, nsize);
3154      }
3155 </pre><p>
3156 Note that Standard&nbsp;C ensures
3157 that <code>free(NULL)</code> has no effect and that
3158 <code>realloc(NULL,size)</code> is equivalent to <code>malloc(size)</code>.
3159 This code assumes that <code>realloc</code> does not fail when shrinking a block.
3160 (Although Standard&nbsp;C does not ensure this behavior,
3161 it seems to be a safe assumption.)
3162
3163
3164
3165
3166
3167 <hr><h3><a name="lua_arith"><code>lua_arith</code></a></h3><p>
3168 <span class="apii">[-(2|1), +1, <em>e</em>]</span>
3169 <pre>void lua_arith (lua_State *L, int op);</pre>
3170
3171 <p>
3172 Performs an arithmetic or bitwise operation over the two values
3173 (or one, in the case of negations)
3174 at the top of the stack,
3175 with the value at the top being the second operand,
3176 pops these values, and pushes the result of the operation.
3177 The function follows the semantics of the corresponding Lua operator
3178 (that is, it may call metamethods).
3179
3180
3181 <p>
3182 The value of <code>op</code> must be one of the following constants:
3183
3184 <ul>
3185
3186 <li><b><a name="pdf-LUA_OPADD"><code>LUA_OPADD</code></a>: </b> performs addition (<code>+</code>)</li>
3187 <li><b><a name="pdf-LUA_OPSUB"><code>LUA_OPSUB</code></a>: </b> performs subtraction (<code>-</code>)</li>
3188 <li><b><a name="pdf-LUA_OPMUL"><code>LUA_OPMUL</code></a>: </b> performs multiplication (<code>*</code>)</li>
3189 <li><b><a name="pdf-LUA_OPDIV"><code>LUA_OPDIV</code></a>: </b> performs float division (<code>/</code>)</li>
3190 <li><b><a name="pdf-LUA_OPIDIV"><code>LUA_OPIDIV</code></a>: </b> performs floor division (<code>//</code>)</li>
3191 <li><b><a name="pdf-LUA_OPMOD"><code>LUA_OPMOD</code></a>: </b> performs modulo (<code>%</code>)</li>
3192 <li><b><a name="pdf-LUA_OPPOW"><code>LUA_OPPOW</code></a>: </b> performs exponentiation (<code>^</code>)</li>
3193 <li><b><a name="pdf-LUA_OPUNM"><code>LUA_OPUNM</code></a>: </b> performs mathematical negation (unary <code>-</code>)</li>
3194 <li><b><a name="pdf-LUA_OPBNOT"><code>LUA_OPBNOT</code></a>: </b> performs bitwise NOT (<code>~</code>)</li>
3195 <li><b><a name="pdf-LUA_OPBAND"><code>LUA_OPBAND</code></a>: </b> performs bitwise AND (<code>&amp;</code>)</li>
3196 <li><b><a name="pdf-LUA_OPBOR"><code>LUA_OPBOR</code></a>: </b> performs bitwise OR (<code>|</code>)</li>
3197 <li><b><a name="pdf-LUA_OPBXOR"><code>LUA_OPBXOR</code></a>: </b> performs bitwise exclusive OR (<code>~</code>)</li>
3198 <li><b><a name="pdf-LUA_OPSHL"><code>LUA_OPSHL</code></a>: </b> performs left shift (<code>&lt;&lt;</code>)</li>
3199 <li><b><a name="pdf-LUA_OPSHR"><code>LUA_OPSHR</code></a>: </b> performs right shift (<code>&gt;&gt;</code>)</li>
3200
3201 </ul>
3202
3203
3204
3205
3206 <hr><h3><a name="lua_atpanic"><code>lua_atpanic</code></a></h3><p>
3207 <span class="apii">[-0, +0, &ndash;]</span>
3208 <pre>lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);</pre>
3209
3210 <p>
3211 Sets a new panic function and returns the old one (see <a href="#4.6">&sect;4.6</a>).
3212
3213
3214
3215
3216
3217 <hr><h3><a name="lua_call"><code>lua_call</code></a></h3><p>
3218 <span class="apii">[-(nargs+1), +nresults, <em>e</em>]</span>
3219 <pre>void lua_call (lua_State *L, int nargs, int nresults);</pre>
3220
3221 <p>
3222 Calls a function.
3223
3224
3225 <p>
3226 To call a function you must use the following protocol:
3227 first, the function to be called is pushed onto the stack;
3228 then, the arguments to the function are pushed
3229 in direct order;
3230 that is, the first argument is pushed first.
3231 Finally you call <a href="#lua_call"><code>lua_call</code></a>;
3232 <code>nargs</code> is the number of arguments that you pushed onto the stack.
3233 All arguments and the function value are popped from the stack
3234 when the function is called.
3235 The function results are pushed onto the stack when the function returns.
3236 The number of results is adjusted to <code>nresults</code>,
3237 unless <code>nresults</code> is <a name="pdf-LUA_MULTRET"><code>LUA_MULTRET</code></a>.
3238 In this case, all results from the function are pushed;
3239 Lua takes care that the returned values fit into the stack space,
3240 but it does not ensure any extra space in the stack.
3241 The function results are pushed onto the stack in direct order
3242 (the first result is pushed first),
3243 so that after the call the last result is on the top of the stack.
3244
3245
3246 <p>
3247 Any error inside the called function is propagated upwards
3248 (with a <code>longjmp</code>).
3249
3250
3251 <p>
3252 The following example shows how the host program can do the
3253 equivalent to this Lua code:
3254
3255 <pre>
3256      a = f("how", t.x, 14)
3257 </pre><p>
3258 Here it is in&nbsp;C:
3259
3260 <pre>
3261      lua_getglobal(L, "f");                  /* function to be called */
3262      lua_pushliteral(L, "how");                       /* 1st argument */
3263      lua_getglobal(L, "t");                    /* table to be indexed */
3264      lua_getfield(L, -1, "x");        /* push result of t.x (2nd arg) */
3265      lua_remove(L, -2);                  /* remove 't' from the stack */
3266      lua_pushinteger(L, 14);                          /* 3rd argument */
3267      lua_call(L, 3, 1);     /* call 'f' with 3 arguments and 1 result */
3268      lua_setglobal(L, "a");                         /* set global 'a' */
3269 </pre><p>
3270 Note that the code above is <em>balanced</em>:
3271 at its end, the stack is back to its original configuration.
3272 This is considered good programming practice.
3273
3274
3275
3276
3277
3278 <hr><h3><a name="lua_callk"><code>lua_callk</code></a></h3><p>
3279 <span class="apii">[-(nargs + 1), +nresults, <em>e</em>]</span>
3280 <pre>void lua_callk (lua_State *L,
3281                 int nargs,
3282                 int nresults,
3283                 lua_KContext ctx,
3284                 lua_KFunction k);</pre>
3285
3286 <p>
3287 This function behaves exactly like <a href="#lua_call"><code>lua_call</code></a>,
3288 but allows the called function to yield (see <a href="#4.7">&sect;4.7</a>).
3289
3290
3291
3292
3293
3294 <hr><h3><a name="lua_CFunction"><code>lua_CFunction</code></a></h3>
3295 <pre>typedef int (*lua_CFunction) (lua_State *L);</pre>
3296
3297 <p>
3298 Type for C&nbsp;functions.
3299
3300
3301 <p>
3302 In order to communicate properly with Lua,
3303 a C&nbsp;function must use the following protocol,
3304 which defines the way parameters and results are passed:
3305 a C&nbsp;function receives its arguments from Lua in its stack
3306 in direct order (the first argument is pushed first).
3307 So, when the function starts,
3308 <code>lua_gettop(L)</code> returns the number of arguments received by the function.
3309 The first argument (if any) is at index 1
3310 and its last argument is at index <code>lua_gettop(L)</code>.
3311 To return values to Lua, a C&nbsp;function just pushes them onto the stack,
3312 in direct order (the first result is pushed first),
3313 and returns the number of results.
3314 Any other value in the stack below the results will be properly
3315 discarded by Lua.
3316 Like a Lua function, a C&nbsp;function called by Lua can also return
3317 many results.
3318
3319
3320 <p>
3321 As an example, the following function receives a variable number
3322 of numeric arguments and returns their average and their sum:
3323
3324 <pre>
3325      static int foo (lua_State *L) {
3326        int n = lua_gettop(L);    /* number of arguments */
3327        lua_Number sum = 0.0;
3328        int i;
3329        for (i = 1; i &lt;= n; i++) {
3330          if (!lua_isnumber(L, i)) {
3331            lua_pushliteral(L, "incorrect argument");
3332            lua_error(L);
3333          }
3334          sum += lua_tonumber(L, i);
3335        }
3336        lua_pushnumber(L, sum/n);        /* first result */
3337        lua_pushnumber(L, sum);         /* second result */
3338        return 2;                   /* number of results */
3339      }
3340 </pre>
3341
3342
3343
3344
3345 <hr><h3><a name="lua_checkstack"><code>lua_checkstack</code></a></h3><p>
3346 <span class="apii">[-0, +0, &ndash;]</span>
3347 <pre>int lua_checkstack (lua_State *L, int n);</pre>
3348
3349 <p>
3350 Ensures that the stack has space for at least <code>n</code> extra slots
3351 (that is, that you can safely push up to <code>n</code> values into it).
3352 It returns false if it cannot fulfill the request,
3353 either because it would cause the stack
3354 to be larger than a fixed maximum size
3355 (typically at least several thousand elements) or
3356 because it cannot allocate memory for the extra space.
3357 This function never shrinks the stack;
3358 if the stack already has space for the extra slots,
3359 it is left unchanged.
3360
3361
3362
3363
3364
3365 <hr><h3><a name="lua_close"><code>lua_close</code></a></h3><p>
3366 <span class="apii">[-0, +0, &ndash;]</span>
3367 <pre>void lua_close (lua_State *L);</pre>
3368
3369 <p>
3370 Destroys all objects in the given Lua state
3371 (calling the corresponding garbage-collection metamethods, if any)
3372 and frees all dynamic memory used by this state.
3373 On several platforms, you may not need to call this function,
3374 because all resources are naturally released when the host program ends.
3375 On the other hand, long-running programs that create multiple states,
3376 such as daemons or web servers,
3377 will probably need to close states as soon as they are not needed.
3378
3379
3380
3381
3382
3383 <hr><h3><a name="lua_compare"><code>lua_compare</code></a></h3><p>
3384 <span class="apii">[-0, +0, <em>e</em>]</span>
3385 <pre>int lua_compare (lua_State *L, int index1, int index2, int op);</pre>
3386
3387 <p>
3388 Compares two Lua values.
3389 Returns 1 if the value at index <code>index1</code> satisfies <code>op</code>
3390 when compared with the value at index <code>index2</code>,
3391 following the semantics of the corresponding Lua operator
3392 (that is, it may call metamethods).
3393 Otherwise returns&nbsp;0.
3394 Also returns&nbsp;0 if any of the indices is not valid.
3395
3396
3397 <p>
3398 The value of <code>op</code> must be one of the following constants:
3399
3400 <ul>
3401
3402 <li><b><a name="pdf-LUA_OPEQ"><code>LUA_OPEQ</code></a>: </b> compares for equality (<code>==</code>)</li>
3403 <li><b><a name="pdf-LUA_OPLT"><code>LUA_OPLT</code></a>: </b> compares for less than (<code>&lt;</code>)</li>
3404 <li><b><a name="pdf-LUA_OPLE"><code>LUA_OPLE</code></a>: </b> compares for less or equal (<code>&lt;=</code>)</li>
3405
3406 </ul>
3407
3408
3409
3410
3411 <hr><h3><a name="lua_concat"><code>lua_concat</code></a></h3><p>
3412 <span class="apii">[-n, +1, <em>e</em>]</span>
3413 <pre>void lua_concat (lua_State *L, int n);</pre>
3414
3415 <p>
3416 Concatenates the <code>n</code> values at the top of the stack,
3417 pops them, and leaves the result at the top.
3418 If <code>n</code>&nbsp;is&nbsp;1, the result is the single value on the stack
3419 (that is, the function does nothing);
3420 if <code>n</code> is 0, the result is the empty string.
3421 Concatenation is performed following the usual semantics of Lua
3422 (see <a href="#3.4.6">&sect;3.4.6</a>).
3423
3424
3425
3426
3427
3428 <hr><h3><a name="lua_copy"><code>lua_copy</code></a></h3><p>
3429 <span class="apii">[-0, +0, &ndash;]</span>
3430 <pre>void lua_copy (lua_State *L, int fromidx, int toidx);</pre>
3431
3432 <p>
3433 Copies the element at index <code>fromidx</code>
3434 into the valid index <code>toidx</code>,
3435 replacing the value at that position.
3436 Values at other positions are not affected.
3437
3438
3439
3440
3441
3442 <hr><h3><a name="lua_createtable"><code>lua_createtable</code></a></h3><p>
3443 <span class="apii">[-0, +1, <em>m</em>]</span>
3444 <pre>void lua_createtable (lua_State *L, int narr, int nrec);</pre>
3445
3446 <p>
3447 Creates a new empty table and pushes it onto the stack.
3448 Parameter <code>narr</code> is a hint for how many elements the table
3449 will have as a sequence;
3450 parameter <code>nrec</code> is a hint for how many other elements
3451 the table will have.
3452 Lua may use these hints to preallocate memory for the new table.
3453 This preallocation is useful for performance when you know in advance
3454 how many elements the table will have.
3455 Otherwise you can use the function <a href="#lua_newtable"><code>lua_newtable</code></a>.
3456
3457
3458
3459
3460
3461 <hr><h3><a name="lua_dump"><code>lua_dump</code></a></h3><p>
3462 <span class="apii">[-0, +0, &ndash;]</span>
3463 <pre>int lua_dump (lua_State *L,
3464                         lua_Writer writer,
3465                         void *data,
3466                         int strip);</pre>
3467
3468 <p>
3469 Dumps a function as a binary chunk.
3470 Receives a Lua function on the top of the stack
3471 and produces a binary chunk that,
3472 if loaded again,
3473 results in a function equivalent to the one dumped.
3474 As it produces parts of the chunk,
3475 <a href="#lua_dump"><code>lua_dump</code></a> calls function <code>writer</code> (see <a href="#lua_Writer"><code>lua_Writer</code></a>)
3476 with the given <code>data</code>
3477 to write them.
3478
3479
3480 <p>
3481 If <code>strip</code> is true,
3482 the binary representation may not include all debug information
3483 about the function,
3484 to save space.
3485
3486
3487 <p>
3488 The value returned is the error code returned by the last
3489 call to the writer;
3490 0&nbsp;means no errors.
3491
3492
3493 <p>
3494 This function does not pop the Lua function from the stack.
3495
3496
3497
3498
3499
3500 <hr><h3><a name="lua_error"><code>lua_error</code></a></h3><p>
3501 <span class="apii">[-1, +0, <em>v</em>]</span>
3502 <pre>int lua_error (lua_State *L);</pre>
3503
3504 <p>
3505 Generates a Lua error,
3506 using the value at the top of the stack as the error object.
3507 This function does a long jump,
3508 and therefore never returns
3509 (see <a href="#luaL_error"><code>luaL_error</code></a>).
3510
3511
3512
3513
3514
3515 <hr><h3><a name="lua_gc"><code>lua_gc</code></a></h3><p>
3516 <span class="apii">[-0, +0, <em>m</em>]</span>
3517 <pre>int lua_gc (lua_State *L, int what, int data);</pre>
3518
3519 <p>
3520 Controls the garbage collector.
3521
3522
3523 <p>
3524 This function performs several tasks,
3525 according to the value of the parameter <code>what</code>:
3526
3527 <ul>
3528
3529 <li><b><code>LUA_GCSTOP</code>: </b>
3530 stops the garbage collector.
3531 </li>
3532
3533 <li><b><code>LUA_GCRESTART</code>: </b>
3534 restarts the garbage collector.
3535 </li>
3536
3537 <li><b><code>LUA_GCCOLLECT</code>: </b>
3538 performs a full garbage-collection cycle.
3539 </li>
3540
3541 <li><b><code>LUA_GCCOUNT</code>: </b>
3542 returns the current amount of memory (in Kbytes) in use by Lua.
3543 </li>
3544
3545 <li><b><code>LUA_GCCOUNTB</code>: </b>
3546 returns the remainder of dividing the current amount of bytes of
3547 memory in use by Lua by 1024.
3548 </li>
3549
3550 <li><b><code>LUA_GCSTEP</code>: </b>
3551 performs an incremental step of garbage collection.
3552 </li>
3553
3554 <li><b><code>LUA_GCSETPAUSE</code>: </b>
3555 sets <code>data</code> as the new value
3556 for the <em>pause</em> of the collector (see <a href="#2.5">&sect;2.5</a>)
3557 and returns the previous value of the pause.
3558 </li>
3559
3560 <li><b><code>LUA_GCSETSTEPMUL</code>: </b>
3561 sets <code>data</code> as the new value for the <em>step multiplier</em> of
3562 the collector (see <a href="#2.5">&sect;2.5</a>)
3563 and returns the previous value of the step multiplier.
3564 </li>
3565
3566 <li><b><code>LUA_GCISRUNNING</code>: </b>
3567 returns a boolean that tells whether the collector is running
3568 (i.e., not stopped).
3569 </li>
3570
3571 </ul>
3572
3573 <p>
3574 For more details about these options,
3575 see <a href="#pdf-collectgarbage"><code>collectgarbage</code></a>.
3576
3577
3578
3579
3580
3581 <hr><h3><a name="lua_getallocf"><code>lua_getallocf</code></a></h3><p>
3582 <span class="apii">[-0, +0, &ndash;]</span>
3583 <pre>lua_Alloc lua_getallocf (lua_State *L, void **ud);</pre>
3584
3585 <p>
3586 Returns the memory-allocation function of a given state.
3587 If <code>ud</code> is not <code>NULL</code>, Lua stores in <code>*ud</code> the
3588 opaque pointer given when the memory-allocator function was set.
3589
3590
3591
3592
3593
3594 <hr><h3><a name="lua_getfield"><code>lua_getfield</code></a></h3><p>
3595 <span class="apii">[-0, +1, <em>e</em>]</span>
3596 <pre>int lua_getfield (lua_State *L, int index, const char *k);</pre>
3597
3598 <p>
3599 Pushes onto the stack the value <code>t[k]</code>,
3600 where <code>t</code> is the value at the given index.
3601 As in Lua, this function may trigger a metamethod
3602 for the "index" event (see <a href="#2.4">&sect;2.4</a>).
3603
3604
3605 <p>
3606 Returns the type of the pushed value.
3607
3608
3609
3610
3611
3612 <hr><h3><a name="lua_getextraspace"><code>lua_getextraspace</code></a></h3><p>
3613 <span class="apii">[-0, +0, &ndash;]</span>
3614 <pre>void *lua_getextraspace (lua_State *L);</pre>
3615
3616 <p>
3617 Returns a pointer to a raw memory area associated with the
3618 given Lua state.
3619 The application can use this area for any purpose;
3620 Lua does not use it for anything.
3621
3622
3623 <p>
3624 Each new thread has this area initialized with a copy
3625 of the area of the main thread.
3626
3627
3628 <p>
3629 By default, this area has the size of a pointer to void,
3630 but you can recompile Lua with a different size for this area.
3631 (See <code>LUA_EXTRASPACE</code> in <code>luaconf.h</code>.)
3632
3633
3634
3635
3636
3637 <hr><h3><a name="lua_getglobal"><code>lua_getglobal</code></a></h3><p>
3638 <span class="apii">[-0, +1, <em>e</em>]</span>
3639 <pre>int lua_getglobal (lua_State *L, const char *name);</pre>
3640
3641 <p>
3642 Pushes onto the stack the value of the global <code>name</code>.
3643 Returns the type of that value.
3644
3645
3646
3647
3648
3649 <hr><h3><a name="lua_geti"><code>lua_geti</code></a></h3><p>
3650 <span class="apii">[-0, +1, <em>e</em>]</span>
3651 <pre>int lua_geti (lua_State *L, int index, lua_Integer i);</pre>
3652
3653 <p>
3654 Pushes onto the stack the value <code>t[i]</code>,
3655 where <code>t</code> is the value at the given index.
3656 As in Lua, this function may trigger a metamethod
3657 for the "index" event (see <a href="#2.4">&sect;2.4</a>).
3658
3659
3660 <p>
3661 Returns the type of the pushed value.
3662
3663
3664
3665
3666
3667 <hr><h3><a name="lua_getmetatable"><code>lua_getmetatable</code></a></h3><p>
3668 <span class="apii">[-0, +(0|1), &ndash;]</span>
3669 <pre>int lua_getmetatable (lua_State *L, int index);</pre>
3670
3671 <p>
3672 If the value at the given index has a metatable,
3673 the function pushes that metatable onto the stack and returns&nbsp;1.
3674 Otherwise,
3675 the function returns&nbsp;0 and pushes nothing on the stack.
3676
3677
3678
3679
3680
3681 <hr><h3><a name="lua_gettable"><code>lua_gettable</code></a></h3><p>
3682 <span class="apii">[-1, +1, <em>e</em>]</span>
3683 <pre>int lua_gettable (lua_State *L, int index);</pre>
3684
3685 <p>
3686 Pushes onto the stack the value <code>t[k]</code>,
3687 where <code>t</code> is the value at the given index
3688 and <code>k</code> is the value at the top of the stack.
3689
3690
3691 <p>
3692 This function pops the key from the stack,
3693 pushing the resulting value in its place.
3694 As in Lua, this function may trigger a metamethod
3695 for the "index" event (see <a href="#2.4">&sect;2.4</a>).
3696
3697
3698 <p>
3699 Returns the type of the pushed value.
3700
3701
3702
3703
3704
3705 <hr><h3><a name="lua_gettop"><code>lua_gettop</code></a></h3><p>
3706 <span class="apii">[-0, +0, &ndash;]</span>
3707 <pre>int lua_gettop (lua_State *L);</pre>
3708
3709 <p>
3710 Returns the index of the top element in the stack.
3711 Because indices start at&nbsp;1,
3712 this result is equal to the number of elements in the stack;
3713 in particular, 0&nbsp;means an empty stack.
3714
3715
3716
3717
3718
3719 <hr><h3><a name="lua_getuservalue"><code>lua_getuservalue</code></a></h3><p>
3720 <span class="apii">[-0, +1, &ndash;]</span>
3721 <pre>int lua_getuservalue (lua_State *L, int index);</pre>
3722
3723 <p>
3724 Pushes onto the stack the Lua value associated with the full userdata
3725 at the given index.
3726
3727
3728 <p>
3729 Returns the type of the pushed value.
3730
3731
3732
3733
3734
3735 <hr><h3><a name="lua_insert"><code>lua_insert</code></a></h3><p>
3736 <span class="apii">[-1, +1, &ndash;]</span>
3737 <pre>void lua_insert (lua_State *L, int index);</pre>
3738
3739 <p>
3740 Moves the top element into the given valid index,
3741 shifting up the elements above this index to open space.
3742 This function cannot be called with a pseudo-index,
3743 because a pseudo-index is not an actual stack position.
3744
3745
3746
3747
3748
3749 <hr><h3><a name="lua_Integer"><code>lua_Integer</code></a></h3>
3750 <pre>typedef ... lua_Integer;</pre>
3751
3752 <p>
3753 The type of integers in Lua.
3754
3755
3756 <p>
3757 By default this type is <code>long long</code>,
3758 (usually a 64-bit two-complement integer),
3759 but that can be changed to <code>long</code> or <code>int</code>
3760 (usually a 32-bit two-complement integer).
3761 (See <code>LUA_INT_TYPE</code> in <code>luaconf.h</code>.)
3762
3763
3764 <p>
3765 Lua also defines the constants
3766 <a name="pdf-LUA_MININTEGER"><code>LUA_MININTEGER</code></a> and <a name="pdf-LUA_MAXINTEGER"><code>LUA_MAXINTEGER</code></a>,
3767 with the minimum and the maximum values that fit in this type.
3768
3769
3770
3771
3772
3773 <hr><h3><a name="lua_isboolean"><code>lua_isboolean</code></a></h3><p>
3774 <span class="apii">[-0, +0, &ndash;]</span>
3775 <pre>int lua_isboolean (lua_State *L, int index);</pre>
3776
3777 <p>
3778 Returns 1 if the value at the given index is a boolean,
3779 and 0&nbsp;otherwise.
3780
3781
3782
3783
3784
3785 <hr><h3><a name="lua_iscfunction"><code>lua_iscfunction</code></a></h3><p>
3786 <span class="apii">[-0, +0, &ndash;]</span>
3787 <pre>int lua_iscfunction (lua_State *L, int index);</pre>
3788
3789 <p>
3790 Returns 1 if the value at the given index is a C&nbsp;function,
3791 and 0&nbsp;otherwise.
3792
3793
3794
3795
3796
3797 <hr><h3><a name="lua_isfunction"><code>lua_isfunction</code></a></h3><p>
3798 <span class="apii">[-0, +0, &ndash;]</span>
3799 <pre>int lua_isfunction (lua_State *L, int index);</pre>
3800
3801 <p>
3802 Returns 1 if the value at the given index is a function
3803 (either C or Lua), and 0&nbsp;otherwise.
3804
3805
3806
3807
3808
3809 <hr><h3><a name="lua_isinteger"><code>lua_isinteger</code></a></h3><p>
3810 <span class="apii">[-0, +0, &ndash;]</span>
3811 <pre>int lua_isinteger (lua_State *L, int index);</pre>
3812
3813 <p>
3814 Returns 1 if the value at the given index is an integer
3815 (that is, the value is a number and is represented as an integer),
3816 and 0&nbsp;otherwise.
3817
3818
3819
3820
3821
3822 <hr><h3><a name="lua_islightuserdata"><code>lua_islightuserdata</code></a></h3><p>
3823 <span class="apii">[-0, +0, &ndash;]</span>
3824 <pre>int lua_islightuserdata (lua_State *L, int index);</pre>
3825
3826 <p>
3827 Returns 1 if the value at the given index is a light userdata,
3828 and 0&nbsp;otherwise.
3829
3830
3831
3832
3833
3834 <hr><h3><a name="lua_isnil"><code>lua_isnil</code></a></h3><p>
3835 <span class="apii">[-0, +0, &ndash;]</span>
3836 <pre>int lua_isnil (lua_State *L, int index);</pre>
3837
3838 <p>
3839 Returns 1 if the value at the given index is <b>nil</b>,
3840 and 0&nbsp;otherwise.
3841
3842
3843
3844
3845
3846 <hr><h3><a name="lua_isnone"><code>lua_isnone</code></a></h3><p>
3847 <span class="apii">[-0, +0, &ndash;]</span>
3848 <pre>int lua_isnone (lua_State *L, int index);</pre>
3849
3850 <p>
3851 Returns 1 if the given index is not valid,
3852 and 0&nbsp;otherwise.
3853
3854
3855
3856
3857
3858 <hr><h3><a name="lua_isnoneornil"><code>lua_isnoneornil</code></a></h3><p>
3859 <span class="apii">[-0, +0, &ndash;]</span>
3860 <pre>int lua_isnoneornil (lua_State *L, int index);</pre>
3861
3862 <p>
3863 Returns 1 if the given index is not valid
3864 or if the value at this index is <b>nil</b>,
3865 and 0&nbsp;otherwise.
3866
3867
3868
3869
3870
3871 <hr><h3><a name="lua_isnumber"><code>lua_isnumber</code></a></h3><p>
3872 <span class="apii">[-0, +0, &ndash;]</span>
3873 <pre>int lua_isnumber (lua_State *L, int index);</pre>
3874
3875 <p>
3876 Returns 1 if the value at the given index is a number
3877 or a string convertible to a number,
3878 and 0&nbsp;otherwise.
3879
3880
3881
3882
3883
3884 <hr><h3><a name="lua_isstring"><code>lua_isstring</code></a></h3><p>
3885 <span class="apii">[-0, +0, &ndash;]</span>
3886 <pre>int lua_isstring (lua_State *L, int index);</pre>
3887
3888 <p>
3889 Returns 1 if the value at the given index is a string
3890 or a number (which is always convertible to a string),
3891 and 0&nbsp;otherwise.
3892
3893
3894
3895
3896
3897 <hr><h3><a name="lua_istable"><code>lua_istable</code></a></h3><p>
3898 <span class="apii">[-0, +0, &ndash;]</span>
3899 <pre>int lua_istable (lua_State *L, int index);</pre>
3900
3901 <p>
3902 Returns 1 if the value at the given index is a table,
3903 and 0&nbsp;otherwise.
3904
3905
3906
3907
3908
3909 <hr><h3><a name="lua_isthread"><code>lua_isthread</code></a></h3><p>
3910 <span class="apii">[-0, +0, &ndash;]</span>
3911 <pre>int lua_isthread (lua_State *L, int index);</pre>
3912
3913 <p>
3914 Returns 1 if the value at the given index is a thread,
3915 and 0&nbsp;otherwise.
3916
3917
3918
3919
3920
3921 <hr><h3><a name="lua_isuserdata"><code>lua_isuserdata</code></a></h3><p>
3922 <span class="apii">[-0, +0, &ndash;]</span>
3923 <pre>int lua_isuserdata (lua_State *L, int index);</pre>
3924
3925 <p>
3926 Returns 1 if the value at the given index is a userdata
3927 (either full or light), and 0&nbsp;otherwise.
3928
3929
3930
3931
3932
3933 <hr><h3><a name="lua_isyieldable"><code>lua_isyieldable</code></a></h3><p>
3934 <span class="apii">[-0, +0, &ndash;]</span>
3935 <pre>int lua_isyieldable (lua_State *L);</pre>
3936
3937 <p>
3938 Returns 1 if the given coroutine can yield,
3939 and 0&nbsp;otherwise.
3940
3941
3942
3943
3944
3945 <hr><h3><a name="lua_KContext"><code>lua_KContext</code></a></h3>
3946 <pre>typedef ... lua_KContext;</pre>
3947
3948 <p>
3949 The type for continuation-function contexts.
3950 It must be a numeric type.
3951 This type is defined as <code>intptr_t</code>
3952 when <code>intptr_t</code> is available,
3953 so that it can store pointers too.
3954 Otherwise, it is defined as <code>ptrdiff_t</code>.
3955
3956
3957
3958
3959
3960 <hr><h3><a name="lua_KFunction"><code>lua_KFunction</code></a></h3>
3961 <pre>typedef int (*lua_KFunction) (lua_State *L, int status, lua_KContext ctx);</pre>
3962
3963 <p>
3964 Type for continuation functions (see <a href="#4.7">&sect;4.7</a>).
3965
3966
3967
3968
3969
3970 <hr><h3><a name="lua_len"><code>lua_len</code></a></h3><p>
3971 <span class="apii">[-0, +1, <em>e</em>]</span>
3972 <pre>void lua_len (lua_State *L, int index);</pre>
3973
3974 <p>
3975 Returns the length of the value at the given index.
3976 It is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">&sect;3.4.7</a>) and
3977 may trigger a metamethod for the "length" event (see <a href="#2.4">&sect;2.4</a>).
3978 The result is pushed on the stack.
3979
3980
3981
3982
3983
3984 <hr><h3><a name="lua_load"><code>lua_load</code></a></h3><p>
3985 <span class="apii">[-0, +1, &ndash;]</span>
3986 <pre>int lua_load (lua_State *L,
3987               lua_Reader reader,
3988               void *data,
3989               const char *chunkname,
3990               const char *mode);</pre>
3991
3992 <p>
3993 Loads a Lua chunk without running it.
3994 If there are no errors,
3995 <code>lua_load</code> pushes the compiled chunk as a Lua
3996 function on top of the stack.
3997 Otherwise, it pushes an error message.
3998
3999
4000 <p>
4001 The return values of <code>lua_load</code> are:
4002
4003 <ul>
4004
4005 <li><b><a href="#pdf-LUA_OK"><code>LUA_OK</code></a>: </b> no errors;</li>
4006
4007 <li><b><a name="pdf-LUA_ERRSYNTAX"><code>LUA_ERRSYNTAX</code></a>: </b>
4008 syntax error during precompilation;</li>
4009
4010 <li><b><a href="#pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>: </b>
4011 memory allocation (out-of-memory) error;</li>
4012
4013 <li><b><a href="#pdf-LUA_ERRGCMM"><code>LUA_ERRGCMM</code></a>: </b>
4014 error while running a <code>__gc</code> metamethod.
4015 (This error has no relation with the chunk being loaded.
4016 It is generated by the garbage collector.)
4017 </li>
4018
4019 </ul>
4020
4021 <p>
4022 The <code>lua_load</code> function uses a user-supplied <code>reader</code> function
4023 to read the chunk (see <a href="#lua_Reader"><code>lua_Reader</code></a>).
4024 The <code>data</code> argument is an opaque value passed to the reader function.
4025
4026
4027 <p>
4028 The <code>chunkname</code> argument gives a name to the chunk,
4029 which is used for error messages and in debug information (see <a href="#4.9">&sect;4.9</a>).
4030
4031
4032 <p>
4033 <code>lua_load</code> automatically detects whether the chunk is text or binary
4034 and loads it accordingly (see program <code>luac</code>).
4035 The string <code>mode</code> works as in function <a href="#pdf-load"><code>load</code></a>,
4036 with the addition that
4037 a <code>NULL</code> value is equivalent to the string "<code>bt</code>".
4038
4039
4040 <p>
4041 <code>lua_load</code> uses the stack internally,
4042 so the reader function must always leave the stack
4043 unmodified when returning.
4044
4045
4046 <p>
4047 If the resulting function has upvalues,
4048 its first upvalue is set to the value of the global environment
4049 stored at index <code>LUA_RIDX_GLOBALS</code> in the registry (see <a href="#4.5">&sect;4.5</a>).
4050 When loading main chunks,
4051 this upvalue will be the <code>_ENV</code> variable (see <a href="#2.2">&sect;2.2</a>).
4052 Other upvalues are initialized with <b>nil</b>.
4053
4054
4055
4056
4057
4058 <hr><h3><a name="lua_newstate"><code>lua_newstate</code></a></h3><p>
4059 <span class="apii">[-0, +0, &ndash;]</span>
4060 <pre>lua_State *lua_newstate (lua_Alloc f, void *ud);</pre>
4061
4062 <p>
4063 Creates a new thread running in a new, independent state.
4064 Returns <code>NULL</code> if it cannot create the thread or the state
4065 (due to lack of memory).
4066 The argument <code>f</code> is the allocator function;
4067 Lua does all memory allocation for this state
4068 through this function (see <a href="#lua_Alloc"><code>lua_Alloc</code></a>).
4069 The second argument, <code>ud</code>, is an opaque pointer that Lua
4070 passes to the allocator in every call.
4071
4072
4073
4074
4075
4076 <hr><h3><a name="lua_newtable"><code>lua_newtable</code></a></h3><p>
4077 <span class="apii">[-0, +1, <em>m</em>]</span>
4078 <pre>void lua_newtable (lua_State *L);</pre>
4079
4080 <p>
4081 Creates a new empty table and pushes it onto the stack.
4082 It is equivalent to <code>lua_createtable(L, 0, 0)</code>.
4083
4084
4085
4086
4087
4088 <hr><h3><a name="lua_newthread"><code>lua_newthread</code></a></h3><p>
4089 <span class="apii">[-0, +1, <em>m</em>]</span>
4090 <pre>lua_State *lua_newthread (lua_State *L);</pre>
4091
4092 <p>
4093 Creates a new thread, pushes it on the stack,
4094 and returns a pointer to a <a href="#lua_State"><code>lua_State</code></a> that represents this new thread.
4095 The new thread returned by this function shares with the original thread
4096 its global environment,
4097 but has an independent execution stack.
4098
4099
4100 <p>
4101 There is no explicit function to close or to destroy a thread.
4102 Threads are subject to garbage collection,
4103 like any Lua object.
4104
4105
4106
4107
4108
4109 <hr><h3><a name="lua_newuserdata"><code>lua_newuserdata</code></a></h3><p>
4110 <span class="apii">[-0, +1, <em>m</em>]</span>
4111 <pre>void *lua_newuserdata (lua_State *L, size_t size);</pre>
4112
4113 <p>
4114 This function allocates a new block of memory with the given size,
4115 pushes onto the stack a new full userdata with the block address,
4116 and returns this address.
4117 The host program can freely use this memory.
4118
4119
4120
4121
4122
4123 <hr><h3><a name="lua_next"><code>lua_next</code></a></h3><p>
4124 <span class="apii">[-1, +(2|0), <em>e</em>]</span>
4125 <pre>int lua_next (lua_State *L, int index);</pre>
4126
4127 <p>
4128 Pops a key from the stack,
4129 and pushes a key&ndash;value pair from the table at the given index
4130 (the "next" pair after the given key).
4131 If there are no more elements in the table,
4132 then <a href="#lua_next"><code>lua_next</code></a> returns 0 (and pushes nothing).
4133
4134
4135 <p>
4136 A typical traversal looks like this:
4137
4138 <pre>
4139      /* table is in the stack at index 't' */
4140      lua_pushnil(L);  /* first key */
4141      while (lua_next(L, t) != 0) {
4142        /* uses 'key' (at index -2) and 'value' (at index -1) */
4143        printf("%s - %s\n",
4144               lua_typename(L, lua_type(L, -2)),
4145               lua_typename(L, lua_type(L, -1)));
4146        /* removes 'value'; keeps 'key' for next iteration */
4147        lua_pop(L, 1);
4148      }
4149 </pre>
4150
4151 <p>
4152 While traversing a table,
4153 do not call <a href="#lua_tolstring"><code>lua_tolstring</code></a> directly on a key,
4154 unless you know that the key is actually a string.
4155 Recall that <a href="#lua_tolstring"><code>lua_tolstring</code></a> may change
4156 the value at the given index;
4157 this confuses the next call to <a href="#lua_next"><code>lua_next</code></a>.
4158
4159
4160 <p>
4161 See function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying
4162 the table during its traversal.
4163
4164
4165
4166
4167
4168 <hr><h3><a name="lua_Number"><code>lua_Number</code></a></h3>
4169 <pre>typedef ... lua_Number;</pre>
4170
4171 <p>
4172 The type of floats in Lua.
4173
4174
4175 <p>
4176 By default this type is double,
4177 but that can be changed to a single float or a long double.
4178 (See <code>LUA_FLOAT_TYPE</code> in <code>luaconf.h</code>.)
4179
4180
4181
4182
4183
4184 <hr><h3><a name="lua_numbertointeger"><code>lua_numbertointeger</code></a></h3>
4185 <pre>int lua_numbertointeger (lua_Number n, lua_Integer *p);</pre>
4186
4187 <p>
4188 Converts a Lua float to a Lua integer.
4189 This macro assumes that <code>n</code> has an integral value.
4190 If that value is within the range of Lua integers,
4191 it is converted to an integer and assigned to <code>*p</code>.
4192 The macro results in a boolean indicating whether the
4193 conversion was successful.
4194 (Note that this range test can be tricky to do
4195 correctly without this macro,
4196 due to roundings.)
4197
4198
4199 <p>
4200 This macro may evaluate its arguments more than once.
4201
4202
4203
4204
4205
4206 <hr><h3><a name="lua_pcall"><code>lua_pcall</code></a></h3><p>
4207 <span class="apii">[-(nargs + 1), +(nresults|1), &ndash;]</span>
4208 <pre>int lua_pcall (lua_State *L, int nargs, int nresults, int msgh);</pre>
4209
4210 <p>
4211 Calls a function in protected mode.
4212
4213
4214 <p>
4215 Both <code>nargs</code> and <code>nresults</code> have the same meaning as
4216 in <a href="#lua_call"><code>lua_call</code></a>.
4217 If there are no errors during the call,
4218 <a href="#lua_pcall"><code>lua_pcall</code></a> behaves exactly like <a href="#lua_call"><code>lua_call</code></a>.
4219 However, if there is any error,
4220 <a href="#lua_pcall"><code>lua_pcall</code></a> catches it,
4221 pushes a single value on the stack (the error object),
4222 and returns an error code.
4223 Like <a href="#lua_call"><code>lua_call</code></a>,
4224 <a href="#lua_pcall"><code>lua_pcall</code></a> always removes the function
4225 and its arguments from the stack.
4226
4227
4228 <p>
4229 If <code>msgh</code> is 0,
4230 then the error object returned on the stack
4231 is exactly the original error object.
4232 Otherwise, <code>msgh</code> is the stack index of a
4233 <em>message handler</em>.
4234 (This index cannot be a pseudo-index.)
4235 In case of runtime errors,
4236 this function will be called with the error object
4237 and its return value will be the object
4238 returned on the stack by <a href="#lua_pcall"><code>lua_pcall</code></a>.
4239
4240
4241 <p>
4242 Typically, the message handler is used to add more debug
4243 information to the error object, such as a stack traceback.
4244 Such information cannot be gathered after the return of <a href="#lua_pcall"><code>lua_pcall</code></a>,
4245 since by then the stack has unwound.
4246
4247
4248 <p>
4249 The <a href="#lua_pcall"><code>lua_pcall</code></a> function returns one of the following constants
4250 (defined in <code>lua.h</code>):
4251
4252 <ul>
4253
4254 <li><b><a name="pdf-LUA_OK"><code>LUA_OK</code></a> (0): </b>
4255 success.</li>
4256
4257 <li><b><a name="pdf-LUA_ERRRUN"><code>LUA_ERRRUN</code></a>: </b>
4258 a runtime error.
4259 </li>
4260
4261 <li><b><a name="pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>: </b>
4262 memory allocation error.
4263 For such errors, Lua does not call the message handler.
4264 </li>
4265
4266 <li><b><a name="pdf-LUA_ERRERR"><code>LUA_ERRERR</code></a>: </b>
4267 error while running the message handler.
4268 </li>
4269
4270 <li><b><a name="pdf-LUA_ERRGCMM"><code>LUA_ERRGCMM</code></a>: </b>
4271 error while running a <code>__gc</code> metamethod.
4272 For such errors, Lua does not call the message handler
4273 (as this kind of error typically has no relation
4274 with the function being called).
4275 </li>
4276
4277 </ul>
4278
4279
4280
4281
4282 <hr><h3><a name="lua_pcallk"><code>lua_pcallk</code></a></h3><p>
4283 <span class="apii">[-(nargs + 1), +(nresults|1), &ndash;]</span>
4284 <pre>int lua_pcallk (lua_State *L,
4285                 int nargs,
4286                 int nresults,
4287                 int msgh,
4288                 lua_KContext ctx,
4289                 lua_KFunction k);</pre>
4290
4291 <p>
4292 This function behaves exactly like <a href="#lua_pcall"><code>lua_pcall</code></a>,
4293 but allows the called function to yield (see <a href="#4.7">&sect;4.7</a>).
4294
4295
4296
4297
4298
4299 <hr><h3><a name="lua_pop"><code>lua_pop</code></a></h3><p>
4300 <span class="apii">[-n, +0, &ndash;]</span>
4301 <pre>void lua_pop (lua_State *L, int n);</pre>
4302
4303 <p>
4304 Pops <code>n</code> elements from the stack.
4305
4306
4307
4308
4309
4310 <hr><h3><a name="lua_pushboolean"><code>lua_pushboolean</code></a></h3><p>
4311 <span class="apii">[-0, +1, &ndash;]</span>
4312 <pre>void lua_pushboolean (lua_State *L, int b);</pre>
4313
4314 <p>
4315 Pushes a boolean value with value <code>b</code> onto the stack.
4316
4317
4318
4319
4320
4321 <hr><h3><a name="lua_pushcclosure"><code>lua_pushcclosure</code></a></h3><p>
4322 <span class="apii">[-n, +1, <em>m</em>]</span>
4323 <pre>void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);</pre>
4324
4325 <p>
4326 Pushes a new C&nbsp;closure onto the stack.
4327
4328
4329 <p>
4330 When a C&nbsp;function is created,
4331 it is possible to associate some values with it,
4332 thus creating a C&nbsp;closure (see <a href="#4.4">&sect;4.4</a>);
4333 these values are then accessible to the function whenever it is called.
4334 To associate values with a C&nbsp;function,
4335 first these values must be pushed onto the stack
4336 (when there are multiple values, the first value is pushed first).
4337 Then <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>
4338 is called to create and push the C&nbsp;function onto the stack,
4339 with the argument <code>n</code> telling how many values will be
4340 associated with the function.
4341 <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> also pops these values from the stack.
4342
4343
4344 <p>
4345 The maximum value for <code>n</code> is 255.
4346
4347
4348 <p>
4349 When <code>n</code> is zero,
4350 this function creates a <em>light C&nbsp;function</em>,
4351 which is just a pointer to the C&nbsp;function.
4352 In that case, it never raises a memory error.
4353
4354
4355
4356
4357
4358 <hr><h3><a name="lua_pushcfunction"><code>lua_pushcfunction</code></a></h3><p>
4359 <span class="apii">[-0, +1, &ndash;]</span>
4360 <pre>void lua_pushcfunction (lua_State *L, lua_CFunction f);</pre>
4361
4362 <p>
4363 Pushes a C&nbsp;function onto the stack.
4364 This function receives a pointer to a C&nbsp;function
4365 and pushes onto the stack a Lua value of type <code>function</code> that,
4366 when called, invokes the corresponding C&nbsp;function.
4367
4368
4369 <p>
4370 Any function to be callable by Lua must
4371 follow the correct protocol to receive its parameters
4372 and return its results (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>).
4373
4374
4375
4376
4377
4378 <hr><h3><a name="lua_pushfstring"><code>lua_pushfstring</code></a></h3><p>
4379 <span class="apii">[-0, +1, <em>e</em>]</span>
4380 <pre>const char *lua_pushfstring (lua_State *L, const char *fmt, ...);</pre>
4381
4382 <p>
4383 Pushes onto the stack a formatted string
4384 and returns a pointer to this string.
4385 It is similar to the ISO&nbsp;C function <code>sprintf</code>,
4386 but has some important differences:
4387
4388 <ul>
4389
4390 <li>
4391 You do not have to allocate space for the result:
4392 the result is a Lua string and Lua takes care of memory allocation
4393 (and deallocation, through garbage collection).
4394 </li>
4395
4396 <li>
4397 The conversion specifiers are quite restricted.
4398 There are no flags, widths, or precisions.
4399 The conversion specifiers can only be
4400 '<code>%%</code>' (inserts the character '<code>%</code>'),
4401 '<code>%s</code>' (inserts a zero-terminated string, with no size restrictions),
4402 '<code>%f</code>' (inserts a <a href="#lua_Number"><code>lua_Number</code></a>),
4403 '<code>%I</code>' (inserts a <a href="#lua_Integer"><code>lua_Integer</code></a>),
4404 '<code>%p</code>' (inserts a pointer as a hexadecimal numeral),
4405 '<code>%d</code>' (inserts an <code>int</code>),
4406 '<code>%c</code>' (inserts an <code>int</code> as a one-byte character), and
4407 '<code>%U</code>' (inserts a <code>long int</code> as a UTF-8 byte sequence).
4408 </li>
4409
4410 </ul>
4411
4412 <p>
4413 Unlike other push functions,
4414 this function checks for the stack space it needs,
4415 including the slot for its result.
4416
4417
4418
4419
4420
4421 <hr><h3><a name="lua_pushglobaltable"><code>lua_pushglobaltable</code></a></h3><p>
4422 <span class="apii">[-0, +1, &ndash;]</span>
4423 <pre>void lua_pushglobaltable (lua_State *L);</pre>
4424
4425 <p>
4426 Pushes the global environment onto the stack.
4427
4428
4429
4430
4431
4432 <hr><h3><a name="lua_pushinteger"><code>lua_pushinteger</code></a></h3><p>
4433 <span class="apii">[-0, +1, &ndash;]</span>
4434 <pre>void lua_pushinteger (lua_State *L, lua_Integer n);</pre>
4435
4436 <p>
4437 Pushes an integer with value <code>n</code> onto the stack.
4438
4439
4440
4441
4442
4443 <hr><h3><a name="lua_pushlightuserdata"><code>lua_pushlightuserdata</code></a></h3><p>
4444 <span class="apii">[-0, +1, &ndash;]</span>
4445 <pre>void lua_pushlightuserdata (lua_State *L, void *p);</pre>
4446
4447 <p>
4448 Pushes a light userdata onto the stack.
4449
4450
4451 <p>
4452 Userdata represent C&nbsp;values in Lua.
4453 A <em>light userdata</em> represents a pointer, a <code>void*</code>.
4454 It is a value (like a number):
4455 you do not create it, it has no individual metatable,
4456 and it is not collected (as it was never created).
4457 A light userdata is equal to "any"
4458 light userdata with the same C&nbsp;address.
4459
4460
4461
4462
4463
4464 <hr><h3><a name="lua_pushliteral"><code>lua_pushliteral</code></a></h3><p>
4465 <span class="apii">[-0, +1, <em>m</em>]</span>
4466 <pre>const char *lua_pushliteral (lua_State *L, const char *s);</pre>
4467
4468 <p>
4469 This macro is equivalent to <a href="#lua_pushstring"><code>lua_pushstring</code></a>,
4470 but should be used only when <code>s</code> is a literal string.
4471
4472
4473
4474
4475
4476 <hr><h3><a name="lua_pushlstring"><code>lua_pushlstring</code></a></h3><p>
4477 <span class="apii">[-0, +1, <em>m</em>]</span>
4478 <pre>const char *lua_pushlstring (lua_State *L, const char *s, size_t len);</pre>
4479
4480 <p>
4481 Pushes the string pointed to by <code>s</code> with size <code>len</code>
4482 onto the stack.
4483 Lua makes (or reuses) an internal copy of the given string,
4484 so the memory at <code>s</code> can be freed or reused immediately after
4485 the function returns.
4486 The string can contain any binary data,
4487 including embedded zeros.
4488
4489
4490 <p>
4491 Returns a pointer to the internal copy of the string.
4492
4493
4494
4495
4496
4497 <hr><h3><a name="lua_pushnil"><code>lua_pushnil</code></a></h3><p>
4498 <span class="apii">[-0, +1, &ndash;]</span>
4499 <pre>void lua_pushnil (lua_State *L);</pre>
4500
4501 <p>
4502 Pushes a nil value onto the stack.
4503
4504
4505
4506
4507
4508 <hr><h3><a name="lua_pushnumber"><code>lua_pushnumber</code></a></h3><p>
4509 <span class="apii">[-0, +1, &ndash;]</span>
4510 <pre>void lua_pushnumber (lua_State *L, lua_Number n);</pre>
4511
4512 <p>
4513 Pushes a float with value <code>n</code> onto the stack.
4514
4515
4516
4517
4518
4519 <hr><h3><a name="lua_pushstring"><code>lua_pushstring</code></a></h3><p>
4520 <span class="apii">[-0, +1, <em>m</em>]</span>
4521 <pre>const char *lua_pushstring (lua_State *L, const char *s);</pre>
4522
4523 <p>
4524 Pushes the zero-terminated string pointed to by <code>s</code>
4525 onto the stack.
4526 Lua makes (or reuses) an internal copy of the given string,
4527 so the memory at <code>s</code> can be freed or reused immediately after
4528 the function returns.
4529
4530
4531 <p>
4532 Returns a pointer to the internal copy of the string.
4533
4534
4535 <p>
4536 If <code>s</code> is <code>NULL</code>, pushes <b>nil</b> and returns <code>NULL</code>.
4537
4538
4539
4540
4541
4542 <hr><h3><a name="lua_pushthread"><code>lua_pushthread</code></a></h3><p>
4543 <span class="apii">[-0, +1, &ndash;]</span>
4544 <pre>int lua_pushthread (lua_State *L);</pre>
4545
4546 <p>
4547 Pushes the thread represented by <code>L</code> onto the stack.
4548 Returns 1 if this thread is the main thread of its state.
4549
4550
4551
4552
4553
4554 <hr><h3><a name="lua_pushvalue"><code>lua_pushvalue</code></a></h3><p>
4555 <span class="apii">[-0, +1, &ndash;]</span>
4556 <pre>void lua_pushvalue (lua_State *L, int index);</pre>
4557
4558 <p>
4559 Pushes a copy of the element at the given index
4560 onto the stack.
4561
4562
4563
4564
4565
4566 <hr><h3><a name="lua_pushvfstring"><code>lua_pushvfstring</code></a></h3><p>
4567 <span class="apii">[-0, +1, <em>m</em>]</span>
4568 <pre>const char *lua_pushvfstring (lua_State *L,
4569                               const char *fmt,
4570                               va_list argp);</pre>
4571
4572 <p>
4573 Equivalent to <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>, except that it receives a <code>va_list</code>
4574 instead of a variable number of arguments.
4575
4576
4577
4578
4579
4580 <hr><h3><a name="lua_rawequal"><code>lua_rawequal</code></a></h3><p>
4581 <span class="apii">[-0, +0, &ndash;]</span>
4582 <pre>int lua_rawequal (lua_State *L, int index1, int index2);</pre>
4583
4584 <p>
4585 Returns 1 if the two values in indices <code>index1</code> and
4586 <code>index2</code> are primitively equal
4587 (that is, without calling the <code>__eq</code> metamethod).
4588 Otherwise returns&nbsp;0.
4589 Also returns&nbsp;0 if any of the indices are not valid.
4590
4591
4592
4593
4594
4595 <hr><h3><a name="lua_rawget"><code>lua_rawget</code></a></h3><p>
4596 <span class="apii">[-1, +1, &ndash;]</span>
4597 <pre>int lua_rawget (lua_State *L, int index);</pre>
4598
4599 <p>
4600 Similar to <a href="#lua_gettable"><code>lua_gettable</code></a>, but does a raw access
4601 (i.e., without metamethods).
4602
4603
4604
4605
4606
4607 <hr><h3><a name="lua_rawgeti"><code>lua_rawgeti</code></a></h3><p>
4608 <span class="apii">[-0, +1, &ndash;]</span>
4609 <pre>int lua_rawgeti (lua_State *L, int index, lua_Integer n);</pre>
4610
4611 <p>
4612 Pushes onto the stack the value <code>t[n]</code>,
4613 where <code>t</code> is the table at the given index.
4614 The access is raw,
4615 that is, it does not invoke the <code>__index</code> metamethod.
4616
4617
4618 <p>
4619 Returns the type of the pushed value.
4620
4621
4622
4623
4624
4625 <hr><h3><a name="lua_rawgetp"><code>lua_rawgetp</code></a></h3><p>
4626 <span class="apii">[-0, +1, &ndash;]</span>
4627 <pre>int lua_rawgetp (lua_State *L, int index, const void *p);</pre>
4628
4629 <p>
4630 Pushes onto the stack the value <code>t[k]</code>,
4631 where <code>t</code> is the table at the given index and
4632 <code>k</code> is the pointer <code>p</code> represented as a light userdata.
4633 The access is raw;
4634 that is, it does not invoke the <code>__index</code> metamethod.
4635
4636
4637 <p>
4638 Returns the type of the pushed value.
4639
4640
4641
4642
4643
4644 <hr><h3><a name="lua_rawlen"><code>lua_rawlen</code></a></h3><p>
4645 <span class="apii">[-0, +0, &ndash;]</span>
4646 <pre>size_t lua_rawlen (lua_State *L, int index);</pre>
4647
4648 <p>
4649 Returns the raw "length" of the value at the given index:
4650 for strings, this is the string length;
4651 for tables, this is the result of the length operator ('<code>#</code>')
4652 with no metamethods;
4653 for userdata, this is the size of the block of memory allocated
4654 for the userdata;
4655 for other values, it is&nbsp;0.
4656
4657
4658
4659
4660
4661 <hr><h3><a name="lua_rawset"><code>lua_rawset</code></a></h3><p>
4662 <span class="apii">[-2, +0, <em>m</em>]</span>
4663 <pre>void lua_rawset (lua_State *L, int index);</pre>
4664
4665 <p>
4666 Similar to <a href="#lua_settable"><code>lua_settable</code></a>, but does a raw assignment
4667 (i.e., without metamethods).
4668
4669
4670
4671
4672
4673 <hr><h3><a name="lua_rawseti"><code>lua_rawseti</code></a></h3><p>
4674 <span class="apii">[-1, +0, <em>m</em>]</span>
4675 <pre>void lua_rawseti (lua_State *L, int index, lua_Integer i);</pre>
4676
4677 <p>
4678 Does the equivalent of <code>t[i] = v</code>,
4679 where <code>t</code> is the table at the given index
4680 and <code>v</code> is the value at the top of the stack.
4681
4682
4683 <p>
4684 This function pops the value from the stack.
4685 The assignment is raw,
4686 that is, it does not invoke the <code>__newindex</code> metamethod.
4687
4688
4689
4690
4691
4692 <hr><h3><a name="lua_rawsetp"><code>lua_rawsetp</code></a></h3><p>
4693 <span class="apii">[-1, +0, <em>m</em>]</span>
4694 <pre>void lua_rawsetp (lua_State *L, int index, const void *p);</pre>
4695
4696 <p>
4697 Does the equivalent of <code>t[p] = v</code>,
4698 where <code>t</code> is the table at the given index,
4699 <code>p</code> is encoded as a light userdata,
4700 and <code>v</code> is the value at the top of the stack.
4701
4702
4703 <p>
4704 This function pops the value from the stack.
4705 The assignment is raw,
4706 that is, it does not invoke <code>__newindex</code> metamethod.
4707
4708
4709
4710
4711
4712 <hr><h3><a name="lua_Reader"><code>lua_Reader</code></a></h3>
4713 <pre>typedef const char * (*lua_Reader) (lua_State *L,
4714                                     void *data,
4715                                     size_t *size);</pre>
4716
4717 <p>
4718 The reader function used by <a href="#lua_load"><code>lua_load</code></a>.
4719 Every time it needs another piece of the chunk,
4720 <a href="#lua_load"><code>lua_load</code></a> calls the reader,
4721 passing along its <code>data</code> parameter.
4722 The reader must return a pointer to a block of memory
4723 with a new piece of the chunk
4724 and set <code>size</code> to the block size.
4725 The block must exist until the reader function is called again.
4726 To signal the end of the chunk,
4727 the reader must return <code>NULL</code> or set <code>size</code> to zero.
4728 The reader function may return pieces of any size greater than zero.
4729
4730
4731
4732
4733
4734 <hr><h3><a name="lua_register"><code>lua_register</code></a></h3><p>
4735 <span class="apii">[-0, +0, <em>e</em>]</span>
4736 <pre>void lua_register (lua_State *L, const char *name, lua_CFunction f);</pre>
4737
4738 <p>
4739 Sets the C&nbsp;function <code>f</code> as the new value of global <code>name</code>.
4740 It is defined as a macro:
4741
4742 <pre>
4743      #define lua_register(L,n,f) \
4744             (lua_pushcfunction(L, f), lua_setglobal(L, n))
4745 </pre>
4746
4747
4748
4749
4750 <hr><h3><a name="lua_remove"><code>lua_remove</code></a></h3><p>
4751 <span class="apii">[-1, +0, &ndash;]</span>
4752 <pre>void lua_remove (lua_State *L, int index);</pre>
4753
4754 <p>
4755 Removes the element at the given valid index,
4756 shifting down the elements above this index to fill the gap.
4757 This function cannot be called with a pseudo-index,
4758 because a pseudo-index is not an actual stack position.
4759
4760
4761
4762
4763
4764 <hr><h3><a name="lua_replace"><code>lua_replace</code></a></h3><p>
4765 <span class="apii">[-1, +0, &ndash;]</span>
4766 <pre>void lua_replace (lua_State *L, int index);</pre>
4767
4768 <p>
4769 Moves the top element into the given valid index
4770 without shifting any element
4771 (therefore replacing the value at that given index),
4772 and then pops the top element.
4773
4774
4775
4776
4777
4778 <hr><h3><a name="lua_resume"><code>lua_resume</code></a></h3><p>
4779 <span class="apii">[-?, +?, &ndash;]</span>
4780 <pre>int lua_resume (lua_State *L, lua_State *from, int nargs);</pre>
4781
4782 <p>
4783 Starts and resumes a coroutine in the given thread <code>L</code>.
4784
4785
4786 <p>
4787 To start a coroutine,
4788 you push onto the thread stack the main function plus any arguments;
4789 then you call <a href="#lua_resume"><code>lua_resume</code></a>,
4790 with <code>nargs</code> being the number of arguments.
4791 This call returns when the coroutine suspends or finishes its execution.
4792 When it returns, the stack contains all values passed to <a href="#lua_yield"><code>lua_yield</code></a>,
4793 or all values returned by the body function.
4794 <a href="#lua_resume"><code>lua_resume</code></a> returns
4795 <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the coroutine yields,
4796 <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> if the coroutine finishes its execution
4797 without errors,
4798 or an error code in case of errors (see <a href="#lua_pcall"><code>lua_pcall</code></a>).
4799
4800
4801 <p>
4802 In case of errors,
4803 the stack is not unwound,
4804 so you can use the debug API over it.
4805 The error object is on the top of the stack.
4806
4807
4808 <p>
4809 To resume a coroutine,
4810 you remove any results from the last <a href="#lua_yield"><code>lua_yield</code></a>,
4811 put on its stack only the values to
4812 be passed as results from <code>yield</code>,
4813 and then call <a href="#lua_resume"><code>lua_resume</code></a>.
4814
4815
4816 <p>
4817 The parameter <code>from</code> represents the coroutine that is resuming <code>L</code>.
4818 If there is no such coroutine,
4819 this parameter can be <code>NULL</code>.
4820
4821
4822
4823
4824
4825 <hr><h3><a name="lua_rotate"><code>lua_rotate</code></a></h3><p>
4826 <span class="apii">[-0, +0, &ndash;]</span>
4827 <pre>void lua_rotate (lua_State *L, int idx, int n);</pre>
4828
4829 <p>
4830 Rotates the stack elements between the valid index <code>idx</code>
4831 and the top of the stack.
4832 The elements are rotated <code>n</code> positions in the direction of the top,
4833 for a positive <code>n</code>,
4834 or <code>-n</code> positions in the direction of the bottom,
4835 for a negative <code>n</code>.
4836 The absolute value of <code>n</code> must not be greater than the size
4837 of the slice being rotated.
4838 This function cannot be called with a pseudo-index,
4839 because a pseudo-index is not an actual stack position.
4840
4841
4842
4843
4844
4845 <hr><h3><a name="lua_setallocf"><code>lua_setallocf</code></a></h3><p>
4846 <span class="apii">[-0, +0, &ndash;]</span>
4847 <pre>void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);</pre>
4848
4849 <p>
4850 Changes the allocator function of a given state to <code>f</code>
4851 with user data <code>ud</code>.
4852
4853
4854
4855
4856
4857 <hr><h3><a name="lua_setfield"><code>lua_setfield</code></a></h3><p>
4858 <span class="apii">[-1, +0, <em>e</em>]</span>
4859 <pre>void lua_setfield (lua_State *L, int index, const char *k);</pre>
4860
4861 <p>
4862 Does the equivalent to <code>t[k] = v</code>,
4863 where <code>t</code> is the value at the given index
4864 and <code>v</code> is the value at the top of the stack.
4865
4866
4867 <p>
4868 This function pops the value from the stack.
4869 As in Lua, this function may trigger a metamethod
4870 for the "newindex" event (see <a href="#2.4">&sect;2.4</a>).
4871
4872
4873
4874
4875
4876 <hr><h3><a name="lua_setglobal"><code>lua_setglobal</code></a></h3><p>
4877 <span class="apii">[-1, +0, <em>e</em>]</span>
4878 <pre>void lua_setglobal (lua_State *L, const char *name);</pre>
4879
4880 <p>
4881 Pops a value from the stack and
4882 sets it as the new value of global <code>name</code>.
4883
4884
4885
4886
4887
4888 <hr><h3><a name="lua_seti"><code>lua_seti</code></a></h3><p>
4889 <span class="apii">[-1, +0, <em>e</em>]</span>
4890 <pre>void lua_seti (lua_State *L, int index, lua_Integer n);</pre>
4891
4892 <p>
4893 Does the equivalent to <code>t[n] = v</code>,
4894 where <code>t</code> is the value at the given index
4895 and <code>v</code> is the value at the top of the stack.
4896
4897
4898 <p>
4899 This function pops the value from the stack.
4900 As in Lua, this function may trigger a metamethod
4901 for the "newindex" event (see <a href="#2.4">&sect;2.4</a>).
4902
4903
4904
4905
4906
4907 <hr><h3><a name="lua_setmetatable"><code>lua_setmetatable</code></a></h3><p>
4908 <span class="apii">[-1, +0, &ndash;]</span>
4909 <pre>void lua_setmetatable (lua_State *L, int index);</pre>
4910
4911 <p>
4912 Pops a table from the stack and
4913 sets it as the new metatable for the value at the given index.
4914
4915
4916
4917
4918
4919 <hr><h3><a name="lua_settable"><code>lua_settable</code></a></h3><p>
4920 <span class="apii">[-2, +0, <em>e</em>]</span>
4921 <pre>void lua_settable (lua_State *L, int index);</pre>
4922
4923 <p>
4924 Does the equivalent to <code>t[k] = v</code>,
4925 where <code>t</code> is the value at the given index,
4926 <code>v</code> is the value at the top of the stack,
4927 and <code>k</code> is the value just below the top.
4928
4929
4930 <p>
4931 This function pops both the key and the value from the stack.
4932 As in Lua, this function may trigger a metamethod
4933 for the "newindex" event (see <a href="#2.4">&sect;2.4</a>).
4934
4935
4936
4937
4938
4939 <hr><h3><a name="lua_settop"><code>lua_settop</code></a></h3><p>
4940 <span class="apii">[-?, +?, &ndash;]</span>
4941 <pre>void lua_settop (lua_State *L, int index);</pre>
4942
4943 <p>
4944 Accepts any index, or&nbsp;0,
4945 and sets the stack top to this index.
4946 If the new top is larger than the old one,
4947 then the new elements are filled with <b>nil</b>.
4948 If <code>index</code> is&nbsp;0, then all stack elements are removed.
4949
4950
4951
4952
4953
4954 <hr><h3><a name="lua_setuservalue"><code>lua_setuservalue</code></a></h3><p>
4955 <span class="apii">[-1, +0, &ndash;]</span>
4956 <pre>void lua_setuservalue (lua_State *L, int index);</pre>
4957
4958 <p>
4959 Pops a value from the stack and sets it as
4960 the new value associated to the full userdata at the given index.
4961
4962
4963
4964
4965
4966 <hr><h3><a name="lua_State"><code>lua_State</code></a></h3>
4967 <pre>typedef struct lua_State lua_State;</pre>
4968
4969 <p>
4970 An opaque structure that points to a thread and indirectly
4971 (through the thread) to the whole state of a Lua interpreter.
4972 The Lua library is fully reentrant:
4973 it has no global variables.
4974 All information about a state is accessible through this structure.
4975
4976
4977 <p>
4978 A pointer to this structure must be passed as the first argument to
4979 every function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>,
4980 which creates a Lua state from scratch.
4981
4982
4983
4984
4985
4986 <hr><h3><a name="lua_status"><code>lua_status</code></a></h3><p>
4987 <span class="apii">[-0, +0, &ndash;]</span>
4988 <pre>int lua_status (lua_State *L);</pre>
4989
4990 <p>
4991 Returns the status of the thread <code>L</code>.
4992
4993
4994 <p>
4995 The status can be 0 (<a href="#pdf-LUA_OK"><code>LUA_OK</code></a>) for a normal thread,
4996 an error code if the thread finished the execution
4997 of a <a href="#lua_resume"><code>lua_resume</code></a> with an error,
4998 or <a name="pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the thread is suspended.
4999
5000
5001 <p>
5002 You can only call functions in threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>.
5003 You can resume threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>
5004 (to start a new coroutine) or <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a>
5005 (to resume a coroutine).
5006
5007
5008
5009
5010
5011 <hr><h3><a name="lua_stringtonumber"><code>lua_stringtonumber</code></a></h3><p>
5012 <span class="apii">[-0, +1, &ndash;]</span>
5013 <pre>size_t lua_stringtonumber (lua_State *L, const char *s);</pre>
5014
5015 <p>
5016 Converts the zero-terminated string <code>s</code> to a number,
5017 pushes that number into the stack,
5018 and returns the total size of the string,
5019 that is, its length plus one.
5020 The conversion can result in an integer or a float,
5021 according to the lexical conventions of Lua (see <a href="#3.1">&sect;3.1</a>).
5022 The string may have leading and trailing spaces and a sign.
5023 If the string is not a valid numeral,
5024 returns 0 and pushes nothing.
5025 (Note that the result can be used as a boolean,
5026 true if the conversion succeeds.)
5027
5028
5029
5030
5031
5032 <hr><h3><a name="lua_toboolean"><code>lua_toboolean</code></a></h3><p>
5033 <span class="apii">[-0, +0, &ndash;]</span>
5034 <pre>int lua_toboolean (lua_State *L, int index);</pre>
5035
5036 <p>
5037 Converts the Lua value at the given index to a C&nbsp;boolean
5038 value (0&nbsp;or&nbsp;1).
5039 Like all tests in Lua,
5040 <a href="#lua_toboolean"><code>lua_toboolean</code></a> returns true for any Lua value
5041 different from <b>false</b> and <b>nil</b>;
5042 otherwise it returns false.
5043 (If you want to accept only actual boolean values,
5044 use <a href="#lua_isboolean"><code>lua_isboolean</code></a> to test the value's type.)
5045
5046
5047
5048
5049
5050 <hr><h3><a name="lua_tocfunction"><code>lua_tocfunction</code></a></h3><p>
5051 <span class="apii">[-0, +0, &ndash;]</span>
5052 <pre>lua_CFunction lua_tocfunction (lua_State *L, int index);</pre>
5053
5054 <p>
5055 Converts a value at the given index to a C&nbsp;function.
5056 That value must be a C&nbsp;function;
5057 otherwise, returns <code>NULL</code>.
5058
5059
5060
5061
5062
5063 <hr><h3><a name="lua_tointeger"><code>lua_tointeger</code></a></h3><p>
5064 <span class="apii">[-0, +0, &ndash;]</span>
5065 <pre>lua_Integer lua_tointeger (lua_State *L, int index);</pre>
5066
5067 <p>
5068 Equivalent to <a href="#lua_tointegerx"><code>lua_tointegerx</code></a> with <code>isnum</code> equal to <code>NULL</code>.
5069
5070
5071
5072
5073
5074 <hr><h3><a name="lua_tointegerx"><code>lua_tointegerx</code></a></h3><p>
5075 <span class="apii">[-0, +0, &ndash;]</span>
5076 <pre>lua_Integer lua_tointegerx (lua_State *L, int index, int *isnum);</pre>
5077
5078 <p>
5079 Converts the Lua value at the given index
5080 to the signed integral type <a href="#lua_Integer"><code>lua_Integer</code></a>.
5081 The Lua value must be an integer,
5082 or a number or string convertible to an integer (see <a href="#3.4.3">&sect;3.4.3</a>);
5083 otherwise, <code>lua_tointegerx</code> returns&nbsp;0.
5084
5085
5086 <p>
5087 If <code>isnum</code> is not <code>NULL</code>,
5088 its referent is assigned a boolean value that
5089 indicates whether the operation succeeded.
5090
5091
5092
5093
5094
5095 <hr><h3><a name="lua_tolstring"><code>lua_tolstring</code></a></h3><p>
5096 <span class="apii">[-0, +0, <em>m</em>]</span>
5097 <pre>const char *lua_tolstring (lua_State *L, int index, size_t *len);</pre>
5098
5099 <p>
5100 Converts the Lua value at the given index to a C&nbsp;string.
5101 If <code>len</code> is not <code>NULL</code>,
5102 it sets <code>*len</code> with the string length.
5103 The Lua value must be a string or a number;
5104 otherwise, the function returns <code>NULL</code>.
5105 If the value is a number,
5106 then <code>lua_tolstring</code> also
5107 <em>changes the actual value in the stack to a string</em>.
5108 (This change confuses <a href="#lua_next"><code>lua_next</code></a>
5109 when <code>lua_tolstring</code> is applied to keys during a table traversal.)
5110
5111
5112 <p>
5113 <code>lua_tolstring</code> returns a pointer
5114 to a string inside the Lua state.
5115 This string always has a zero ('<code>\0</code>')
5116 after its last character (as in&nbsp;C),
5117 but can contain other zeros in its body.
5118
5119
5120 <p>
5121 Because Lua has garbage collection,
5122 there is no guarantee that the pointer returned by <code>lua_tolstring</code>
5123 will be valid after the corresponding Lua value is removed from the stack.
5124
5125
5126
5127
5128
5129 <hr><h3><a name="lua_tonumber"><code>lua_tonumber</code></a></h3><p>
5130 <span class="apii">[-0, +0, &ndash;]</span>
5131 <pre>lua_Number lua_tonumber (lua_State *L, int index);</pre>
5132
5133 <p>
5134 Equivalent to <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> with <code>isnum</code> equal to <code>NULL</code>.
5135
5136
5137
5138
5139
5140 <hr><h3><a name="lua_tonumberx"><code>lua_tonumberx</code></a></h3><p>
5141 <span class="apii">[-0, +0, &ndash;]</span>
5142 <pre>lua_Number lua_tonumberx (lua_State *L, int index, int *isnum);</pre>
5143
5144 <p>
5145 Converts the Lua value at the given index
5146 to the C&nbsp;type <a href="#lua_Number"><code>lua_Number</code></a> (see <a href="#lua_Number"><code>lua_Number</code></a>).
5147 The Lua value must be a number or a string convertible to a number
5148 (see <a href="#3.4.3">&sect;3.4.3</a>);
5149 otherwise, <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> returns&nbsp;0.
5150
5151
5152 <p>
5153 If <code>isnum</code> is not <code>NULL</code>,
5154 its referent is assigned a boolean value that
5155 indicates whether the operation succeeded.
5156
5157
5158
5159
5160
5161 <hr><h3><a name="lua_topointer"><code>lua_topointer</code></a></h3><p>
5162 <span class="apii">[-0, +0, &ndash;]</span>
5163 <pre>const void *lua_topointer (lua_State *L, int index);</pre>
5164
5165 <p>
5166 Converts the value at the given index to a generic
5167 C&nbsp;pointer (<code>void*</code>).
5168 The value can be a userdata, a table, a thread, or a function;
5169 otherwise, <code>lua_topointer</code> returns <code>NULL</code>.
5170 Different objects will give different pointers.
5171 There is no way to convert the pointer back to its original value.
5172
5173
5174 <p>
5175 Typically this function is used only for hashing and debug information.
5176
5177
5178
5179
5180
5181 <hr><h3><a name="lua_tostring"><code>lua_tostring</code></a></h3><p>
5182 <span class="apii">[-0, +0, <em>m</em>]</span>
5183 <pre>const char *lua_tostring (lua_State *L, int index);</pre>
5184
5185 <p>
5186 Equivalent to <a href="#lua_tolstring"><code>lua_tolstring</code></a> with <code>len</code> equal to <code>NULL</code>.
5187
5188
5189
5190
5191
5192 <hr><h3><a name="lua_tothread"><code>lua_tothread</code></a></h3><p>
5193 <span class="apii">[-0, +0, &ndash;]</span>
5194 <pre>lua_State *lua_tothread (lua_State *L, int index);</pre>
5195
5196 <p>
5197 Converts the value at the given index to a Lua thread
5198 (represented as <code>lua_State*</code>).
5199 This value must be a thread;
5200 otherwise, the function returns <code>NULL</code>.
5201
5202
5203
5204
5205
5206 <hr><h3><a name="lua_touserdata"><code>lua_touserdata</code></a></h3><p>
5207 <span class="apii">[-0, +0, &ndash;]</span>
5208 <pre>void *lua_touserdata (lua_State *L, int index);</pre>
5209
5210 <p>
5211 If the value at the given index is a full userdata,
5212 returns its block address.
5213 If the value is a light userdata,
5214 returns its pointer.
5215 Otherwise, returns <code>NULL</code>.
5216
5217
5218
5219
5220
5221 <hr><h3><a name="lua_type"><code>lua_type</code></a></h3><p>
5222 <span class="apii">[-0, +0, &ndash;]</span>
5223 <pre>int lua_type (lua_State *L, int index);</pre>
5224
5225 <p>
5226 Returns the type of the value in the given valid index,
5227 or <code>LUA_TNONE</code> for a non-valid (but acceptable) index.
5228 The types returned by <a href="#lua_type"><code>lua_type</code></a> are coded by the following constants
5229 defined in <code>lua.h</code>:
5230 <a name="pdf-LUA_TNIL"><code>LUA_TNIL</code></a> (0),
5231 <a name="pdf-LUA_TNUMBER"><code>LUA_TNUMBER</code></a>,
5232 <a name="pdf-LUA_TBOOLEAN"><code>LUA_TBOOLEAN</code></a>,
5233 <a name="pdf-LUA_TSTRING"><code>LUA_TSTRING</code></a>,
5234 <a name="pdf-LUA_TTABLE"><code>LUA_TTABLE</code></a>,
5235 <a name="pdf-LUA_TFUNCTION"><code>LUA_TFUNCTION</code></a>,
5236 <a name="pdf-LUA_TUSERDATA"><code>LUA_TUSERDATA</code></a>,
5237 <a name="pdf-LUA_TTHREAD"><code>LUA_TTHREAD</code></a>,
5238 and
5239 <a name="pdf-LUA_TLIGHTUSERDATA"><code>LUA_TLIGHTUSERDATA</code></a>.
5240
5241
5242
5243
5244
5245 <hr><h3><a name="lua_typename"><code>lua_typename</code></a></h3><p>
5246 <span class="apii">[-0, +0, &ndash;]</span>
5247 <pre>const char *lua_typename (lua_State *L, int tp);</pre>
5248
5249 <p>
5250 Returns the name of the type encoded by the value <code>tp</code>,
5251 which must be one the values returned by <a href="#lua_type"><code>lua_type</code></a>.
5252
5253
5254
5255
5256
5257 <hr><h3><a name="lua_Unsigned"><code>lua_Unsigned</code></a></h3>
5258 <pre>typedef ... lua_Unsigned;</pre>
5259
5260 <p>
5261 The unsigned version of <a href="#lua_Integer"><code>lua_Integer</code></a>.
5262
5263
5264
5265
5266
5267 <hr><h3><a name="lua_upvalueindex"><code>lua_upvalueindex</code></a></h3><p>
5268 <span class="apii">[-0, +0, &ndash;]</span>
5269 <pre>int lua_upvalueindex (int i);</pre>
5270
5271 <p>
5272 Returns the pseudo-index that represents the <code>i</code>-th upvalue of
5273 the running function (see <a href="#4.4">&sect;4.4</a>).
5274
5275
5276
5277
5278
5279 <hr><h3><a name="lua_version"><code>lua_version</code></a></h3><p>
5280 <span class="apii">[-0, +0, &ndash;]</span>
5281 <pre>const lua_Number *lua_version (lua_State *L);</pre>
5282
5283 <p>
5284 Returns the address of the version number
5285 (a C static variable)
5286 stored in the Lua core.
5287 When called with a valid <a href="#lua_State"><code>lua_State</code></a>,
5288 returns the address of the version used to create that state.
5289 When called with <code>NULL</code>,
5290 returns the address of the version running the call.
5291
5292
5293
5294
5295
5296 <hr><h3><a name="lua_Writer"><code>lua_Writer</code></a></h3>
5297 <pre>typedef int (*lua_Writer) (lua_State *L,
5298                            const void* p,
5299                            size_t sz,
5300                            void* ud);</pre>
5301
5302 <p>
5303 The type of the writer function used by <a href="#lua_dump"><code>lua_dump</code></a>.
5304 Every time it produces another piece of chunk,
5305 <a href="#lua_dump"><code>lua_dump</code></a> calls the writer,
5306 passing along the buffer to be written (<code>p</code>),
5307 its size (<code>sz</code>),
5308 and the <code>data</code> parameter supplied to <a href="#lua_dump"><code>lua_dump</code></a>.
5309
5310
5311 <p>
5312 The writer returns an error code:
5313 0&nbsp;means no errors;
5314 any other value means an error and stops <a href="#lua_dump"><code>lua_dump</code></a> from
5315 calling the writer again.
5316
5317
5318
5319
5320
5321 <hr><h3><a name="lua_xmove"><code>lua_xmove</code></a></h3><p>
5322 <span class="apii">[-?, +?, &ndash;]</span>
5323 <pre>void lua_xmove (lua_State *from, lua_State *to, int n);</pre>
5324
5325 <p>
5326 Exchange values between different threads of the same state.
5327
5328
5329 <p>
5330 This function pops <code>n</code> values from the stack <code>from</code>,
5331 and pushes them onto the stack <code>to</code>.
5332
5333
5334
5335
5336
5337 <hr><h3><a name="lua_yield"><code>lua_yield</code></a></h3><p>
5338 <span class="apii">[-?, +?, <em>e</em>]</span>
5339 <pre>int lua_yield (lua_State *L, int nresults);</pre>
5340
5341 <p>
5342 This function is equivalent to <a href="#lua_yieldk"><code>lua_yieldk</code></a>,
5343 but it has no continuation (see <a href="#4.7">&sect;4.7</a>).
5344 Therefore, when the thread resumes,
5345 it continues the function that called
5346 the function calling <code>lua_yield</code>.
5347
5348
5349
5350
5351
5352 <hr><h3><a name="lua_yieldk"><code>lua_yieldk</code></a></h3><p>
5353 <span class="apii">[-?, +?, <em>e</em>]</span>
5354 <pre>int lua_yieldk (lua_State *L,
5355                 int nresults,
5356                 lua_KContext ctx,
5357                 lua_KFunction k);</pre>
5358
5359 <p>
5360 Yields a coroutine (thread).
5361
5362
5363 <p>
5364 When a C&nbsp;function calls <a href="#lua_yieldk"><code>lua_yieldk</code></a>,
5365 the running coroutine suspends its execution,
5366 and the call to <a href="#lua_resume"><code>lua_resume</code></a> that started this coroutine returns.
5367 The parameter <code>nresults</code> is the number of values from the stack
5368 that will be passed as results to <a href="#lua_resume"><code>lua_resume</code></a>.
5369
5370
5371 <p>
5372 When the coroutine is resumed again,
5373 Lua calls the given continuation function <code>k</code> to continue
5374 the execution of the C&nbsp;function that yielded (see <a href="#4.7">&sect;4.7</a>).
5375 This continuation function receives the same stack
5376 from the previous function,
5377 with the <code>n</code> results removed and
5378 replaced by the arguments passed to <a href="#lua_resume"><code>lua_resume</code></a>.
5379 Moreover,
5380 the continuation function receives the value <code>ctx</code>
5381 that was passed to <a href="#lua_yieldk"><code>lua_yieldk</code></a>.
5382
5383
5384 <p>
5385 Usually, this function does not return;
5386 when the coroutine eventually resumes,
5387 it continues executing the continuation function.
5388 However, there is one special case,
5389 which is when this function is called
5390 from inside a line or a count hook (see <a href="#4.9">&sect;4.9</a>).
5391 In that case, <code>lua_yieldk</code> should be called with no continuation
5392 (probably in the form of <a href="#lua_yield"><code>lua_yield</code></a>) and no results,
5393 and the hook should return immediately after the call.
5394 Lua will yield and,
5395 when the coroutine resumes again,
5396 it will continue the normal execution
5397 of the (Lua) function that triggered the hook.
5398
5399
5400 <p>
5401 This function can raise an error if it is called from a thread
5402 with a pending C call with no continuation function,
5403 or it is called from a thread that is not running inside a resume
5404 (e.g., the main thread).
5405
5406
5407
5408
5409
5410
5411
5412 <h2>4.9 &ndash; <a name="4.9">The Debug Interface</a></h2>
5413
5414 <p>
5415 Lua has no built-in debugging facilities.
5416 Instead, it offers a special interface
5417 by means of functions and <em>hooks</em>.
5418 This interface allows the construction of different
5419 kinds of debuggers, profilers, and other tools
5420 that need "inside information" from the interpreter.
5421
5422
5423
5424 <hr><h3><a name="lua_Debug"><code>lua_Debug</code></a></h3>
5425 <pre>typedef struct lua_Debug {
5426   int event;
5427   const char *name;           /* (n) */
5428   const char *namewhat;       /* (n) */
5429   const char *what;           /* (S) */
5430   const char *source;         /* (S) */
5431   int currentline;            /* (l) */
5432   int linedefined;            /* (S) */
5433   int lastlinedefined;        /* (S) */
5434   unsigned char nups;         /* (u) number of upvalues */
5435   unsigned char nparams;      /* (u) number of parameters */
5436   char isvararg;              /* (u) */
5437   char istailcall;            /* (t) */
5438   char short_src[LUA_IDSIZE]; /* (S) */
5439   /* private part */
5440   <em>other fields</em>
5441 } lua_Debug;</pre>
5442
5443 <p>
5444 A structure used to carry different pieces of
5445 information about a function or an activation record.
5446 <a href="#lua_getstack"><code>lua_getstack</code></a> fills only the private part
5447 of this structure, for later use.
5448 To fill the other fields of <a href="#lua_Debug"><code>lua_Debug</code></a> with useful information,
5449 call <a href="#lua_getinfo"><code>lua_getinfo</code></a>.
5450
5451
5452 <p>
5453 The fields of <a href="#lua_Debug"><code>lua_Debug</code></a> have the following meaning:
5454
5455 <ul>
5456
5457 <li><b><code>source</code>: </b>
5458 the name of the chunk that created the function.
5459 If <code>source</code> starts with a '<code>@</code>',
5460 it means that the function was defined in a file where
5461 the file name follows the '<code>@</code>'.
5462 If <code>source</code> starts with a '<code>=</code>',
5463 the remainder of its contents describe the source in a user-dependent manner.
5464 Otherwise,
5465 the function was defined in a string where
5466 <code>source</code> is that string.
5467 </li>
5468
5469 <li><b><code>short_src</code>: </b>
5470 a "printable" version of <code>source</code>, to be used in error messages.
5471 </li>
5472
5473 <li><b><code>linedefined</code>: </b>
5474 the line number where the definition of the function starts.
5475 </li>
5476
5477 <li><b><code>lastlinedefined</code>: </b>
5478 the line number where the definition of the function ends.
5479 </li>
5480
5481 <li><b><code>what</code>: </b>
5482 the string <code>"Lua"</code> if the function is a Lua function,
5483 <code>"C"</code> if it is a C&nbsp;function,
5484 <code>"main"</code> if it is the main part of a chunk.
5485 </li>
5486
5487 <li><b><code>currentline</code>: </b>
5488 the current line where the given function is executing.
5489 When no line information is available,
5490 <code>currentline</code> is set to -1.
5491 </li>
5492
5493 <li><b><code>name</code>: </b>
5494 a reasonable name for the given function.
5495 Because functions in Lua are first-class values,
5496 they do not have a fixed name:
5497 some functions can be the value of multiple global variables,
5498 while others can be stored only in a table field.
5499 The <code>lua_getinfo</code> function checks how the function was
5500 called to find a suitable name.
5501 If it cannot find a name,
5502 then <code>name</code> is set to <code>NULL</code>.
5503 </li>
5504
5505 <li><b><code>namewhat</code>: </b>
5506 explains the <code>name</code> field.
5507 The value of <code>namewhat</code> can be
5508 <code>"global"</code>, <code>"local"</code>, <code>"method"</code>,
5509 <code>"field"</code>, <code>"upvalue"</code>, or <code>""</code> (the empty string),
5510 according to how the function was called.
5511 (Lua uses the empty string when no other option seems to apply.)
5512 </li>
5513
5514 <li><b><code>istailcall</code>: </b>
5515 true if this function invocation was called by a tail call.
5516 In this case, the caller of this level is not in the stack.
5517 </li>
5518
5519 <li><b><code>nups</code>: </b>
5520 the number of upvalues of the function.
5521 </li>
5522
5523 <li><b><code>nparams</code>: </b>
5524 the number of fixed parameters of the function
5525 (always 0&nbsp;for C&nbsp;functions).
5526 </li>
5527
5528 <li><b><code>isvararg</code>: </b>
5529 true if the function is a vararg function
5530 (always true for C&nbsp;functions).
5531 </li>
5532
5533 </ul>
5534
5535
5536
5537
5538 <hr><h3><a name="lua_gethook"><code>lua_gethook</code></a></h3><p>
5539 <span class="apii">[-0, +0, &ndash;]</span>
5540 <pre>lua_Hook lua_gethook (lua_State *L);</pre>
5541
5542 <p>
5543 Returns the current hook function.
5544
5545
5546
5547
5548
5549 <hr><h3><a name="lua_gethookcount"><code>lua_gethookcount</code></a></h3><p>
5550 <span class="apii">[-0, +0, &ndash;]</span>
5551 <pre>int lua_gethookcount (lua_State *L);</pre>
5552
5553 <p>
5554 Returns the current hook count.
5555
5556
5557
5558
5559
5560 <hr><h3><a name="lua_gethookmask"><code>lua_gethookmask</code></a></h3><p>
5561 <span class="apii">[-0, +0, &ndash;]</span>
5562 <pre>int lua_gethookmask (lua_State *L);</pre>
5563
5564 <p>
5565 Returns the current hook mask.
5566
5567
5568
5569
5570
5571 <hr><h3><a name="lua_getinfo"><code>lua_getinfo</code></a></h3><p>
5572 <span class="apii">[-(0|1), +(0|1|2), <em>e</em>]</span>
5573 <pre>int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar);</pre>
5574
5575 <p>
5576 Gets information about a specific function or function invocation.
5577
5578
5579 <p>
5580 To get information about a function invocation,
5581 the parameter <code>ar</code> must be a valid activation record that was
5582 filled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or
5583 given as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>).
5584
5585
5586 <p>
5587 To get information about a function you push it onto the stack
5588 and start the <code>what</code> string with the character '<code>&gt;</code>'.
5589 (In that case,
5590 <code>lua_getinfo</code> pops the function from the top of the stack.)
5591 For instance, to know in which line a function <code>f</code> was defined,
5592 you can write the following code:
5593
5594 <pre>
5595      lua_Debug ar;
5596      lua_getglobal(L, "f");  /* get global 'f' */
5597      lua_getinfo(L, "&gt;S", &amp;ar);
5598      printf("%d\n", ar.linedefined);
5599 </pre>
5600
5601 <p>
5602 Each character in the string <code>what</code>
5603 selects some fields of the structure <code>ar</code> to be filled or
5604 a value to be pushed on the stack:
5605
5606 <ul>
5607
5608 <li><b>'<code>n</code>': </b> fills in the field <code>name</code> and <code>namewhat</code>;
5609 </li>
5610
5611 <li><b>'<code>S</code>': </b>
5612 fills in the fields <code>source</code>, <code>short_src</code>,
5613 <code>linedefined</code>, <code>lastlinedefined</code>, and <code>what</code>;
5614 </li>
5615
5616 <li><b>'<code>l</code>': </b> fills in the field <code>currentline</code>;
5617 </li>
5618
5619 <li><b>'<code>t</code>': </b> fills in the field <code>istailcall</code>;
5620 </li>
5621
5622 <li><b>'<code>u</code>': </b> fills in the fields
5623 <code>nups</code>, <code>nparams</code>, and <code>isvararg</code>;
5624 </li>
5625
5626 <li><b>'<code>f</code>': </b>
5627 pushes onto the stack the function that is
5628 running at the given level;
5629 </li>
5630
5631 <li><b>'<code>L</code>': </b>
5632 pushes onto the stack a table whose indices are the
5633 numbers of the lines that are valid on the function.
5634 (A <em>valid line</em> is a line with some associated code,
5635 that is, a line where you can put a break point.
5636 Non-valid lines include empty lines and comments.)
5637
5638
5639 <p>
5640 If this option is given together with option '<code>f</code>',
5641 its table is pushed after the function.
5642 </li>
5643
5644 </ul>
5645
5646 <p>
5647 This function returns 0 on error
5648 (for instance, an invalid option in <code>what</code>).
5649
5650
5651
5652
5653
5654 <hr><h3><a name="lua_getlocal"><code>lua_getlocal</code></a></h3><p>
5655 <span class="apii">[-0, +(0|1), &ndash;]</span>
5656 <pre>const char *lua_getlocal (lua_State *L, const lua_Debug *ar, int n);</pre>
5657
5658 <p>
5659 Gets information about a local variable of
5660 a given activation record or a given function.
5661
5662
5663 <p>
5664 In the first case,
5665 the parameter <code>ar</code> must be a valid activation record that was
5666 filled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or
5667 given as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>).
5668 The index <code>n</code> selects which local variable to inspect;
5669 see <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for details about variable indices
5670 and names.
5671
5672
5673 <p>
5674 <a href="#lua_getlocal"><code>lua_getlocal</code></a> pushes the variable's value onto the stack
5675 and returns its name.
5676
5677
5678 <p>
5679 In the second case, <code>ar</code> must be <code>NULL</code> and the function
5680 to be inspected must be at the top of the stack.
5681 In this case, only parameters of Lua functions are visible
5682 (as there is no information about what variables are active)
5683 and no values are pushed onto the stack.
5684
5685
5686 <p>
5687 Returns <code>NULL</code> (and pushes nothing)
5688 when the index is greater than
5689 the number of active local variables.
5690
5691
5692
5693
5694
5695 <hr><h3><a name="lua_getstack"><code>lua_getstack</code></a></h3><p>
5696 <span class="apii">[-0, +0, &ndash;]</span>
5697 <pre>int lua_getstack (lua_State *L, int level, lua_Debug *ar);</pre>
5698
5699 <p>
5700 Gets information about the interpreter runtime stack.
5701
5702
5703 <p>
5704 This function fills parts of a <a href="#lua_Debug"><code>lua_Debug</code></a> structure with
5705 an identification of the <em>activation record</em>
5706 of the function executing at a given level.
5707 Level&nbsp;0 is the current running function,
5708 whereas level <em>n+1</em> is the function that has called level <em>n</em>
5709 (except for tail calls, which do not count on the stack).
5710 When there are no errors, <a href="#lua_getstack"><code>lua_getstack</code></a> returns 1;
5711 when called with a level greater than the stack depth,
5712 it returns 0.
5713
5714
5715
5716
5717
5718 <hr><h3><a name="lua_getupvalue"><code>lua_getupvalue</code></a></h3><p>
5719 <span class="apii">[-0, +(0|1), &ndash;]</span>
5720 <pre>const char *lua_getupvalue (lua_State *L, int funcindex, int n);</pre>
5721
5722 <p>
5723 Gets information about the <code>n</code>-th upvalue
5724 of the closure at index <code>funcindex</code>.
5725 It pushes the upvalue's value onto the stack
5726 and returns its name.
5727 Returns <code>NULL</code> (and pushes nothing)
5728 when the index <code>n</code> is greater than the number of upvalues.
5729
5730
5731 <p>
5732 For C&nbsp;functions, this function uses the empty string <code>""</code>
5733 as a name for all upvalues.
5734 (For Lua functions,
5735 upvalues are the external local variables that the function uses,
5736 and that are consequently included in its closure.)
5737
5738
5739 <p>
5740 Upvalues have no particular order,
5741 as they are active through the whole function.
5742 They are numbered in an arbitrary order.
5743
5744
5745
5746
5747
5748 <hr><h3><a name="lua_Hook"><code>lua_Hook</code></a></h3>
5749 <pre>typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar);</pre>
5750
5751 <p>
5752 Type for debugging hook functions.
5753
5754
5755 <p>
5756 Whenever a hook is called, its <code>ar</code> argument has its field
5757 <code>event</code> set to the specific event that triggered the hook.
5758 Lua identifies these events with the following constants:
5759 <a name="pdf-LUA_HOOKCALL"><code>LUA_HOOKCALL</code></a>, <a name="pdf-LUA_HOOKRET"><code>LUA_HOOKRET</code></a>,
5760 <a name="pdf-LUA_HOOKTAILCALL"><code>LUA_HOOKTAILCALL</code></a>, <a name="pdf-LUA_HOOKLINE"><code>LUA_HOOKLINE</code></a>,
5761 and <a name="pdf-LUA_HOOKCOUNT"><code>LUA_HOOKCOUNT</code></a>.
5762 Moreover, for line events, the field <code>currentline</code> is also set.
5763 To get the value of any other field in <code>ar</code>,
5764 the hook must call <a href="#lua_getinfo"><code>lua_getinfo</code></a>.
5765
5766
5767 <p>
5768 For call events, <code>event</code> can be <code>LUA_HOOKCALL</code>,
5769 the normal value, or <code>LUA_HOOKTAILCALL</code>, for a tail call;
5770 in this case, there will be no corresponding return event.
5771
5772
5773 <p>
5774 While Lua is running a hook, it disables other calls to hooks.
5775 Therefore, if a hook calls back Lua to execute a function or a chunk,
5776 this execution occurs without any calls to hooks.
5777
5778
5779 <p>
5780 Hook functions cannot have continuations,
5781 that is, they cannot call <a href="#lua_yieldk"><code>lua_yieldk</code></a>,
5782 <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>.
5783
5784
5785 <p>
5786 Hook functions can yield under the following conditions:
5787 Only count and line events can yield;
5788 to yield, a hook function must finish its execution
5789 calling <a href="#lua_yield"><code>lua_yield</code></a> with <code>nresults</code> equal to zero
5790 (that is, with no values).
5791
5792
5793
5794
5795
5796 <hr><h3><a name="lua_sethook"><code>lua_sethook</code></a></h3><p>
5797 <span class="apii">[-0, +0, &ndash;]</span>
5798 <pre>void lua_sethook (lua_State *L, lua_Hook f, int mask, int count);</pre>
5799
5800 <p>
5801 Sets the debugging hook function.
5802
5803
5804 <p>
5805 Argument <code>f</code> is the hook function.
5806 <code>mask</code> specifies on which events the hook will be called:
5807 it is formed by a bitwise OR of the constants
5808 <a name="pdf-LUA_MASKCALL"><code>LUA_MASKCALL</code></a>,
5809 <a name="pdf-LUA_MASKRET"><code>LUA_MASKRET</code></a>,
5810 <a name="pdf-LUA_MASKLINE"><code>LUA_MASKLINE</code></a>,
5811 and <a name="pdf-LUA_MASKCOUNT"><code>LUA_MASKCOUNT</code></a>.
5812 The <code>count</code> argument is only meaningful when the mask
5813 includes <code>LUA_MASKCOUNT</code>.
5814 For each event, the hook is called as explained below:
5815
5816 <ul>
5817
5818 <li><b>The call hook: </b> is called when the interpreter calls a function.
5819 The hook is called just after Lua enters the new function,
5820 before the function gets its arguments.
5821 </li>
5822
5823 <li><b>The return hook: </b> is called when the interpreter returns from a function.
5824 The hook is called just before Lua leaves the function.
5825 There is no standard way to access the values
5826 to be returned by the function.
5827 </li>
5828
5829 <li><b>The line hook: </b> is called when the interpreter is about to
5830 start the execution of a new line of code,
5831 or when it jumps back in the code (even to the same line).
5832 (This event only happens while Lua is executing a Lua function.)
5833 </li>
5834
5835 <li><b>The count hook: </b> is called after the interpreter executes every
5836 <code>count</code> instructions.
5837 (This event only happens while Lua is executing a Lua function.)
5838 </li>
5839
5840 </ul>
5841
5842 <p>
5843 A hook is disabled by setting <code>mask</code> to zero.
5844
5845
5846
5847
5848
5849 <hr><h3><a name="lua_setlocal"><code>lua_setlocal</code></a></h3><p>
5850 <span class="apii">[-(0|1), +0, &ndash;]</span>
5851 <pre>const char *lua_setlocal (lua_State *L, const lua_Debug *ar, int n);</pre>
5852
5853 <p>
5854 Sets the value of a local variable of a given activation record.
5855 It assigns the value at the top of the stack
5856 to the variable and returns its name.
5857 It also pops the value from the stack.
5858
5859
5860 <p>
5861 Returns <code>NULL</code> (and pops nothing)
5862 when the index is greater than
5863 the number of active local variables.
5864
5865
5866 <p>
5867 Parameters <code>ar</code> and <code>n</code> are as in function <a href="#lua_getlocal"><code>lua_getlocal</code></a>.
5868
5869
5870
5871
5872
5873 <hr><h3><a name="lua_setupvalue"><code>lua_setupvalue</code></a></h3><p>
5874 <span class="apii">[-(0|1), +0, &ndash;]</span>
5875 <pre>const char *lua_setupvalue (lua_State *L, int funcindex, int n);</pre>
5876
5877 <p>
5878 Sets the value of a closure's upvalue.
5879 It assigns the value at the top of the stack
5880 to the upvalue and returns its name.
5881 It also pops the value from the stack.
5882
5883
5884 <p>
5885 Returns <code>NULL</code> (and pops nothing)
5886 when the index <code>n</code> is greater than the number of upvalues.
5887
5888
5889 <p>
5890 Parameters <code>funcindex</code> and <code>n</code> are as in function <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>.
5891
5892
5893
5894
5895
5896 <hr><h3><a name="lua_upvalueid"><code>lua_upvalueid</code></a></h3><p>
5897 <span class="apii">[-0, +0, &ndash;]</span>
5898 <pre>void *lua_upvalueid (lua_State *L, int funcindex, int n);</pre>
5899
5900 <p>
5901 Returns a unique identifier for the upvalue numbered <code>n</code>
5902 from the closure at index <code>funcindex</code>.
5903
5904
5905 <p>
5906 These unique identifiers allow a program to check whether different
5907 closures share upvalues.
5908 Lua closures that share an upvalue
5909 (that is, that access a same external local variable)
5910 will return identical ids for those upvalue indices.
5911
5912
5913 <p>
5914 Parameters <code>funcindex</code> and <code>n</code> are as in function <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>,
5915 but <code>n</code> cannot be greater than the number of upvalues.
5916
5917
5918
5919
5920
5921 <hr><h3><a name="lua_upvaluejoin"><code>lua_upvaluejoin</code></a></h3><p>
5922 <span class="apii">[-0, +0, &ndash;]</span>
5923 <pre>void lua_upvaluejoin (lua_State *L, int funcindex1, int n1,
5924                                     int funcindex2, int n2);</pre>
5925
5926 <p>
5927 Make the <code>n1</code>-th upvalue of the Lua closure at index <code>funcindex1</code>
5928 refer to the <code>n2</code>-th upvalue of the Lua closure at index <code>funcindex2</code>.
5929
5930
5931
5932
5933
5934
5935
5936 <h1>5 &ndash; <a name="5">The Auxiliary Library</a></h1>
5937
5938 <p>
5939
5940 The <em>auxiliary library</em> provides several convenient functions
5941 to interface C with Lua.
5942 While the basic API provides the primitive functions for all
5943 interactions between C and Lua,
5944 the auxiliary library provides higher-level functions for some
5945 common tasks.
5946
5947
5948 <p>
5949 All functions and types from the auxiliary library
5950 are defined in header file <code>lauxlib.h</code> and
5951 have a prefix <code>luaL_</code>.
5952
5953
5954 <p>
5955 All functions in the auxiliary library are built on
5956 top of the basic API,
5957 and so they provide nothing that cannot be done with that API.
5958 Nevertheless, the use of the auxiliary library ensures
5959 more consistency to your code.
5960
5961
5962 <p>
5963 Several functions in the auxiliary library use internally some
5964 extra stack slots.
5965 When a function in the auxiliary library uses less than five slots,
5966 it does not check the stack size;
5967 it simply assumes that there are enough slots.
5968
5969
5970 <p>
5971 Several functions in the auxiliary library are used to
5972 check C&nbsp;function arguments.
5973 Because the error message is formatted for arguments
5974 (e.g., "<code>bad argument #1</code>"),
5975 you should not use these functions for other stack values.
5976
5977
5978 <p>
5979 Functions called <code>luaL_check*</code>
5980 always raise an error if the check is not satisfied.
5981
5982
5983
5984 <h2>5.1 &ndash; <a name="5.1">Functions and Types</a></h2>
5985
5986 <p>
5987 Here we list all functions and types from the auxiliary library
5988 in alphabetical order.
5989
5990
5991
5992 <hr><h3><a name="luaL_addchar"><code>luaL_addchar</code></a></h3><p>
5993 <span class="apii">[-?, +?, <em>m</em>]</span>
5994 <pre>void luaL_addchar (luaL_Buffer *B, char c);</pre>
5995
5996 <p>
5997 Adds the byte <code>c</code> to the buffer <code>B</code>
5998 (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
5999
6000
6001
6002
6003
6004 <hr><h3><a name="luaL_addlstring"><code>luaL_addlstring</code></a></h3><p>
6005 <span class="apii">[-?, +?, <em>m</em>]</span>
6006 <pre>void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l);</pre>
6007
6008 <p>
6009 Adds the string pointed to by <code>s</code> with length <code>l</code> to
6010 the buffer <code>B</code>
6011 (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
6012 The string can contain embedded zeros.
6013
6014
6015
6016
6017
6018 <hr><h3><a name="luaL_addsize"><code>luaL_addsize</code></a></h3><p>
6019 <span class="apii">[-?, +?, &ndash;]</span>
6020 <pre>void luaL_addsize (luaL_Buffer *B, size_t n);</pre>
6021
6022 <p>
6023 Adds to the buffer <code>B</code> (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>)
6024 a string of length <code>n</code> previously copied to the
6025 buffer area (see <a href="#luaL_prepbuffer"><code>luaL_prepbuffer</code></a>).
6026
6027
6028
6029
6030
6031 <hr><h3><a name="luaL_addstring"><code>luaL_addstring</code></a></h3><p>
6032 <span class="apii">[-?, +?, <em>m</em>]</span>
6033 <pre>void luaL_addstring (luaL_Buffer *B, const char *s);</pre>
6034
6035 <p>
6036 Adds the zero-terminated string pointed to by <code>s</code>
6037 to the buffer <code>B</code>
6038 (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
6039
6040
6041
6042
6043
6044 <hr><h3><a name="luaL_addvalue"><code>luaL_addvalue</code></a></h3><p>
6045 <span class="apii">[-1, +?, <em>m</em>]</span>
6046 <pre>void luaL_addvalue (luaL_Buffer *B);</pre>
6047
6048 <p>
6049 Adds the value at the top of the stack
6050 to the buffer <code>B</code>
6051 (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
6052 Pops the value.
6053
6054
6055 <p>
6056 This is the only function on string buffers that can (and must)
6057 be called with an extra element on the stack,
6058 which is the value to be added to the buffer.
6059
6060
6061
6062
6063
6064 <hr><h3><a name="luaL_argcheck"><code>luaL_argcheck</code></a></h3><p>
6065 <span class="apii">[-0, +0, <em>v</em>]</span>
6066 <pre>void luaL_argcheck (lua_State *L,
6067                     int cond,
6068                     int arg,
6069                     const char *extramsg);</pre>
6070
6071 <p>
6072 Checks whether <code>cond</code> is true.
6073 If it is not, raises an error with a standard message (see <a href="#luaL_argerror"><code>luaL_argerror</code></a>).
6074
6075
6076
6077
6078
6079 <hr><h3><a name="luaL_argerror"><code>luaL_argerror</code></a></h3><p>
6080 <span class="apii">[-0, +0, <em>v</em>]</span>
6081 <pre>int luaL_argerror (lua_State *L, int arg, const char *extramsg);</pre>
6082
6083 <p>
6084 Raises an error reporting a problem with argument <code>arg</code>
6085 of the C&nbsp;function that called it,
6086 using a standard message
6087 that includes <code>extramsg</code> as a comment:
6088
6089 <pre>
6090      bad argument #<em>arg</em> to '<em>funcname</em>' (<em>extramsg</em>)
6091 </pre><p>
6092 This function never returns.
6093
6094
6095
6096
6097
6098 <hr><h3><a name="luaL_Buffer"><code>luaL_Buffer</code></a></h3>
6099 <pre>typedef struct luaL_Buffer luaL_Buffer;</pre>
6100
6101 <p>
6102 Type for a <em>string buffer</em>.
6103
6104
6105 <p>
6106 A string buffer allows C&nbsp;code to build Lua strings piecemeal.
6107 Its pattern of use is as follows:
6108
6109 <ul>
6110
6111 <li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li>
6112
6113 <li>Then initialize it with a call <code>luaL_buffinit(L, &amp;b)</code>.</li>
6114
6115 <li>
6116 Then add string pieces to the buffer calling any of
6117 the <code>luaL_add*</code> functions.
6118 </li>
6119
6120 <li>
6121 Finish by calling <code>luaL_pushresult(&amp;b)</code>.
6122 This call leaves the final string on the top of the stack.
6123 </li>
6124
6125 </ul>
6126
6127 <p>
6128 If you know beforehand the total size of the resulting string,
6129 you can use the buffer like this:
6130
6131 <ul>
6132
6133 <li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li>
6134
6135 <li>Then initialize it and preallocate a space of
6136 size <code>sz</code> with a call <code>luaL_buffinitsize(L, &amp;b, sz)</code>.</li>
6137
6138 <li>Then copy the string into that space.</li>
6139
6140 <li>
6141 Finish by calling <code>luaL_pushresultsize(&amp;b, sz)</code>,
6142 where <code>sz</code> is the total size of the resulting string
6143 copied into that space.
6144 </li>
6145
6146 </ul>
6147
6148 <p>
6149 During its normal operation,
6150 a string buffer uses a variable number of stack slots.
6151 So, while using a buffer, you cannot assume that you know where
6152 the top of the stack is.
6153 You can use the stack between successive calls to buffer operations
6154 as long as that use is balanced;
6155 that is,
6156 when you call a buffer operation,
6157 the stack is at the same level
6158 it was immediately after the previous buffer operation.
6159 (The only exception to this rule is <a href="#luaL_addvalue"><code>luaL_addvalue</code></a>.)
6160 After calling <a href="#luaL_pushresult"><code>luaL_pushresult</code></a> the stack is back to its
6161 level when the buffer was initialized,
6162 plus the final string on its top.
6163
6164
6165
6166
6167
6168 <hr><h3><a name="luaL_buffinit"><code>luaL_buffinit</code></a></h3><p>
6169 <span class="apii">[-0, +0, &ndash;]</span>
6170 <pre>void luaL_buffinit (lua_State *L, luaL_Buffer *B);</pre>
6171
6172 <p>
6173 Initializes a buffer <code>B</code>.
6174 This function does not allocate any space;
6175 the buffer must be declared as a variable
6176 (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
6177
6178
6179
6180
6181
6182 <hr><h3><a name="luaL_buffinitsize"><code>luaL_buffinitsize</code></a></h3><p>
6183 <span class="apii">[-?, +?, <em>m</em>]</span>
6184 <pre>char *luaL_buffinitsize (lua_State *L, luaL_Buffer *B, size_t sz);</pre>
6185
6186 <p>
6187 Equivalent to the sequence
6188 <a href="#luaL_buffinit"><code>luaL_buffinit</code></a>, <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a>.
6189
6190
6191
6192
6193
6194 <hr><h3><a name="luaL_callmeta"><code>luaL_callmeta</code></a></h3><p>
6195 <span class="apii">[-0, +(0|1), <em>e</em>]</span>
6196 <pre>int luaL_callmeta (lua_State *L, int obj, const char *e);</pre>
6197
6198 <p>
6199 Calls a metamethod.
6200
6201
6202 <p>
6203 If the object at index <code>obj</code> has a metatable and this
6204 metatable has a field <code>e</code>,
6205 this function calls this field passing the object as its only argument.
6206 In this case this function returns true and pushes onto the
6207 stack the value returned by the call.
6208 If there is no metatable or no metamethod,
6209 this function returns false (without pushing any value on the stack).
6210
6211
6212
6213
6214
6215 <hr><h3><a name="luaL_checkany"><code>luaL_checkany</code></a></h3><p>
6216 <span class="apii">[-0, +0, <em>v</em>]</span>
6217 <pre>void luaL_checkany (lua_State *L, int arg);</pre>
6218
6219 <p>
6220 Checks whether the function has an argument
6221 of any type (including <b>nil</b>) at position <code>arg</code>.
6222
6223
6224
6225
6226
6227 <hr><h3><a name="luaL_checkinteger"><code>luaL_checkinteger</code></a></h3><p>
6228 <span class="apii">[-0, +0, <em>v</em>]</span>
6229 <pre>lua_Integer luaL_checkinteger (lua_State *L, int arg);</pre>
6230
6231 <p>
6232 Checks whether the function argument <code>arg</code> is an integer
6233 (or can be converted to an integer)
6234 and returns this integer cast to a <a href="#lua_Integer"><code>lua_Integer</code></a>.
6235
6236
6237
6238
6239
6240 <hr><h3><a name="luaL_checklstring"><code>luaL_checklstring</code></a></h3><p>
6241 <span class="apii">[-0, +0, <em>v</em>]</span>
6242 <pre>const char *luaL_checklstring (lua_State *L, int arg, size_t *l);</pre>
6243
6244 <p>
6245 Checks whether the function argument <code>arg</code> is a string
6246 and returns this string;
6247 if <code>l</code> is not <code>NULL</code> fills <code>*l</code>
6248 with the string's length.
6249
6250
6251 <p>
6252 This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result,
6253 so all conversions and caveats of that function apply here.
6254
6255
6256
6257
6258
6259 <hr><h3><a name="luaL_checknumber"><code>luaL_checknumber</code></a></h3><p>
6260 <span class="apii">[-0, +0, <em>v</em>]</span>
6261 <pre>lua_Number luaL_checknumber (lua_State *L, int arg);</pre>
6262
6263 <p>
6264 Checks whether the function argument <code>arg</code> is a number
6265 and returns this number.
6266
6267
6268
6269
6270
6271 <hr><h3><a name="luaL_checkoption"><code>luaL_checkoption</code></a></h3><p>
6272 <span class="apii">[-0, +0, <em>v</em>]</span>
6273 <pre>int luaL_checkoption (lua_State *L,
6274                       int arg,
6275                       const char *def,
6276                       const char *const lst[]);</pre>
6277
6278 <p>
6279 Checks whether the function argument <code>arg</code> is a string and
6280 searches for this string in the array <code>lst</code>
6281 (which must be NULL-terminated).
6282 Returns the index in the array where the string was found.
6283 Raises an error if the argument is not a string or
6284 if the string cannot be found.
6285
6286
6287 <p>
6288 If <code>def</code> is not <code>NULL</code>,
6289 the function uses <code>def</code> as a default value when
6290 there is no argument <code>arg</code> or when this argument is <b>nil</b>.
6291
6292
6293 <p>
6294 This is a useful function for mapping strings to C&nbsp;enums.
6295 (The usual convention in Lua libraries is
6296 to use strings instead of numbers to select options.)
6297
6298
6299
6300
6301
6302 <hr><h3><a name="luaL_checkstack"><code>luaL_checkstack</code></a></h3><p>
6303 <span class="apii">[-0, +0, <em>v</em>]</span>
6304 <pre>void luaL_checkstack (lua_State *L, int sz, const char *msg);</pre>
6305
6306 <p>
6307 Grows the stack size to <code>top + sz</code> elements,
6308 raising an error if the stack cannot grow to that size.
6309 <code>msg</code> is an additional text to go into the error message
6310 (or <code>NULL</code> for no additional text).
6311
6312
6313
6314
6315
6316 <hr><h3><a name="luaL_checkstring"><code>luaL_checkstring</code></a></h3><p>
6317 <span class="apii">[-0, +0, <em>v</em>]</span>
6318 <pre>const char *luaL_checkstring (lua_State *L, int arg);</pre>
6319
6320 <p>
6321 Checks whether the function argument <code>arg</code> is a string
6322 and returns this string.
6323
6324
6325 <p>
6326 This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result,
6327 so all conversions and caveats of that function apply here.
6328
6329
6330
6331
6332
6333 <hr><h3><a name="luaL_checktype"><code>luaL_checktype</code></a></h3><p>
6334 <span class="apii">[-0, +0, <em>v</em>]</span>
6335 <pre>void luaL_checktype (lua_State *L, int arg, int t);</pre>
6336
6337 <p>
6338 Checks whether the function argument <code>arg</code> has type <code>t</code>.
6339 See <a href="#lua_type"><code>lua_type</code></a> for the encoding of types for <code>t</code>.
6340
6341
6342
6343
6344
6345 <hr><h3><a name="luaL_checkudata"><code>luaL_checkudata</code></a></h3><p>
6346 <span class="apii">[-0, +0, <em>v</em>]</span>
6347 <pre>void *luaL_checkudata (lua_State *L, int arg, const char *tname);</pre>
6348
6349 <p>
6350 Checks whether the function argument <code>arg</code> is a userdata
6351 of the type <code>tname</code> (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>) and
6352 returns the userdata address (see <a href="#lua_touserdata"><code>lua_touserdata</code></a>).
6353
6354
6355
6356
6357
6358 <hr><h3><a name="luaL_checkversion"><code>luaL_checkversion</code></a></h3><p>
6359 <span class="apii">[-0, +0, <em>v</em>]</span>
6360 <pre>void luaL_checkversion (lua_State *L);</pre>
6361
6362 <p>
6363 Checks whether the core running the call,
6364 the core that created the Lua state,
6365 and the code making the call are all using the same version of Lua.
6366 Also checks whether the core running the call
6367 and the core that created the Lua state
6368 are using the same address space.
6369
6370
6371
6372
6373
6374 <hr><h3><a name="luaL_dofile"><code>luaL_dofile</code></a></h3><p>
6375 <span class="apii">[-0, +?, <em>e</em>]</span>
6376 <pre>int luaL_dofile (lua_State *L, const char *filename);</pre>
6377
6378 <p>
6379 Loads and runs the given file.
6380 It is defined as the following macro:
6381
6382 <pre>
6383      (luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0))
6384 </pre><p>
6385 It returns false if there are no errors
6386 or true in case of errors.
6387
6388
6389
6390
6391
6392 <hr><h3><a name="luaL_dostring"><code>luaL_dostring</code></a></h3><p>
6393 <span class="apii">[-0, +?, &ndash;]</span>
6394 <pre>int luaL_dostring (lua_State *L, const char *str);</pre>
6395
6396 <p>
6397 Loads and runs the given string.
6398 It is defined as the following macro:
6399
6400 <pre>
6401      (luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0))
6402 </pre><p>
6403 It returns false if there are no errors
6404 or true in case of errors.
6405
6406
6407
6408
6409
6410 <hr><h3><a name="luaL_error"><code>luaL_error</code></a></h3><p>
6411 <span class="apii">[-0, +0, <em>v</em>]</span>
6412 <pre>int luaL_error (lua_State *L, const char *fmt, ...);</pre>
6413
6414 <p>
6415 Raises an error.
6416 The error message format is given by <code>fmt</code>
6417 plus any extra arguments,
6418 following the same rules of <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>.
6419 It also adds at the beginning of the message the file name and
6420 the line number where the error occurred,
6421 if this information is available.
6422
6423
6424 <p>
6425 This function never returns,
6426 but it is an idiom to use it in C&nbsp;functions
6427 as <code>return luaL_error(<em>args</em>)</code>.
6428
6429
6430
6431
6432
6433 <hr><h3><a name="luaL_execresult"><code>luaL_execresult</code></a></h3><p>
6434 <span class="apii">[-0, +3, <em>m</em>]</span>
6435 <pre>int luaL_execresult (lua_State *L, int stat);</pre>
6436
6437 <p>
6438 This function produces the return values for
6439 process-related functions in the standard library
6440 (<a href="#pdf-os.execute"><code>os.execute</code></a> and <a href="#pdf-io.close"><code>io.close</code></a>).
6441
6442
6443
6444
6445
6446 <hr><h3><a name="luaL_fileresult"><code>luaL_fileresult</code></a></h3><p>
6447 <span class="apii">[-0, +(1|3), <em>m</em>]</span>
6448 <pre>int luaL_fileresult (lua_State *L, int stat, const char *fname);</pre>
6449
6450 <p>
6451 This function produces the return values for
6452 file-related functions in the standard library
6453 (<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.).
6454
6455
6456
6457
6458
6459 <hr><h3><a name="luaL_getmetafield"><code>luaL_getmetafield</code></a></h3><p>
6460 <span class="apii">[-0, +(0|1), <em>m</em>]</span>
6461 <pre>int luaL_getmetafield (lua_State *L, int obj, const char *e);</pre>
6462
6463 <p>
6464 Pushes onto the stack the field <code>e</code> from the metatable
6465 of the object at index <code>obj</code> and returns the type of pushed value.
6466 If the object does not have a metatable,
6467 or if the metatable does not have this field,
6468 pushes nothing and returns <code>LUA_TNIL</code>.
6469
6470
6471
6472
6473
6474 <hr><h3><a name="luaL_getmetatable"><code>luaL_getmetatable</code></a></h3><p>
6475 <span class="apii">[-0, +1, <em>m</em>]</span>
6476 <pre>int luaL_getmetatable (lua_State *L, const char *tname);</pre>
6477
6478 <p>
6479 Pushes onto the stack the metatable associated with name <code>tname</code>
6480 in the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>)
6481 (<b>nil</b> if there is no metatable associated with that name).
6482 Returns the type of the pushed value.
6483
6484
6485
6486
6487
6488 <hr><h3><a name="luaL_getsubtable"><code>luaL_getsubtable</code></a></h3><p>
6489 <span class="apii">[-0, +1, <em>e</em>]</span>
6490 <pre>int luaL_getsubtable (lua_State *L, int idx, const char *fname);</pre>
6491
6492 <p>
6493 Ensures that the value <code>t[fname]</code>,
6494 where <code>t</code> is the value at index <code>idx</code>,
6495 is a table,
6496 and pushes that table onto the stack.
6497 Returns true if it finds a previous table there
6498 and false if it creates a new table.
6499
6500
6501
6502
6503
6504 <hr><h3><a name="luaL_gsub"><code>luaL_gsub</code></a></h3><p>
6505 <span class="apii">[-0, +1, <em>m</em>]</span>
6506 <pre>const char *luaL_gsub (lua_State *L,
6507                        const char *s,
6508                        const char *p,
6509                        const char *r);</pre>
6510
6511 <p>
6512 Creates a copy of string <code>s</code> by replacing
6513 any occurrence of the string <code>p</code>
6514 with the string <code>r</code>.
6515 Pushes the resulting string on the stack and returns it.
6516
6517
6518
6519
6520
6521 <hr><h3><a name="luaL_len"><code>luaL_len</code></a></h3><p>
6522 <span class="apii">[-0, +0, <em>e</em>]</span>
6523 <pre>lua_Integer luaL_len (lua_State *L, int index);</pre>
6524
6525 <p>
6526 Returns the "length" of the value at the given index
6527 as a number;
6528 it is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">&sect;3.4.7</a>).
6529 Raises an error if the result of the operation is not an integer.
6530 (This case only can happen through metamethods.)
6531
6532
6533
6534
6535
6536 <hr><h3><a name="luaL_loadbuffer"><code>luaL_loadbuffer</code></a></h3><p>
6537 <span class="apii">[-0, +1, &ndash;]</span>
6538 <pre>int luaL_loadbuffer (lua_State *L,
6539                      const char *buff,
6540                      size_t sz,
6541                      const char *name);</pre>
6542
6543 <p>
6544 Equivalent to <a href="#luaL_loadbufferx"><code>luaL_loadbufferx</code></a> with <code>mode</code> equal to <code>NULL</code>.
6545
6546
6547
6548
6549
6550 <hr><h3><a name="luaL_loadbufferx"><code>luaL_loadbufferx</code></a></h3><p>
6551 <span class="apii">[-0, +1, &ndash;]</span>
6552 <pre>int luaL_loadbufferx (lua_State *L,
6553                       const char *buff,
6554                       size_t sz,
6555                       const char *name,
6556                       const char *mode);</pre>
6557
6558 <p>
6559 Loads a buffer as a Lua chunk.
6560 This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the
6561 buffer pointed to by <code>buff</code> with size <code>sz</code>.
6562
6563
6564 <p>
6565 This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>.
6566 <code>name</code> is the chunk name,
6567 used for debug information and error messages.
6568 The string <code>mode</code> works as in function <a href="#lua_load"><code>lua_load</code></a>.
6569
6570
6571
6572
6573
6574 <hr><h3><a name="luaL_loadfile"><code>luaL_loadfile</code></a></h3><p>
6575 <span class="apii">[-0, +1, <em>m</em>]</span>
6576 <pre>int luaL_loadfile (lua_State *L, const char *filename);</pre>
6577
6578 <p>
6579 Equivalent to <a href="#luaL_loadfilex"><code>luaL_loadfilex</code></a> with <code>mode</code> equal to <code>NULL</code>.
6580
6581
6582
6583
6584
6585 <hr><h3><a name="luaL_loadfilex"><code>luaL_loadfilex</code></a></h3><p>
6586 <span class="apii">[-0, +1, <em>m</em>]</span>
6587 <pre>int luaL_loadfilex (lua_State *L, const char *filename,
6588                                             const char *mode);</pre>
6589
6590 <p>
6591 Loads a file as a Lua chunk.
6592 This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the file
6593 named <code>filename</code>.
6594 If <code>filename</code> is <code>NULL</code>,
6595 then it loads from the standard input.
6596 The first line in the file is ignored if it starts with a <code>#</code>.
6597
6598
6599 <p>
6600 The string <code>mode</code> works as in function <a href="#lua_load"><code>lua_load</code></a>.
6601
6602
6603 <p>
6604 This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>,
6605 but it has an extra error code <a name="pdf-LUA_ERRFILE"><code>LUA_ERRFILE</code></a>
6606 for file-related errors
6607 (e.g., it cannot open or read the file).
6608
6609
6610 <p>
6611 As <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk;
6612 it does not run it.
6613
6614
6615
6616
6617
6618 <hr><h3><a name="luaL_loadstring"><code>luaL_loadstring</code></a></h3><p>
6619 <span class="apii">[-0, +1, &ndash;]</span>
6620 <pre>int luaL_loadstring (lua_State *L, const char *s);</pre>
6621
6622 <p>
6623 Loads a string as a Lua chunk.
6624 This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in
6625 the zero-terminated string <code>s</code>.
6626
6627
6628 <p>
6629 This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>.
6630
6631
6632 <p>
6633 Also as <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk;
6634 it does not run it.
6635
6636
6637
6638
6639
6640 <hr><h3><a name="luaL_newlib"><code>luaL_newlib</code></a></h3><p>
6641 <span class="apii">[-0, +1, <em>m</em>]</span>
6642 <pre>void luaL_newlib (lua_State *L, const luaL_Reg l[]);</pre>
6643
6644 <p>
6645 Creates a new table and registers there
6646 the functions in list <code>l</code>.
6647
6648
6649 <p>
6650 It is implemented as the following macro:
6651
6652 <pre>
6653      (luaL_newlibtable(L,l), luaL_setfuncs(L,l,0))
6654 </pre><p>
6655 The array <code>l</code> must be the actual array,
6656 not a pointer to it.
6657
6658
6659
6660
6661
6662 <hr><h3><a name="luaL_newlibtable"><code>luaL_newlibtable</code></a></h3><p>
6663 <span class="apii">[-0, +1, <em>m</em>]</span>
6664 <pre>void luaL_newlibtable (lua_State *L, const luaL_Reg l[]);</pre>
6665
6666 <p>
6667 Creates a new table with a size optimized
6668 to store all entries in the array <code>l</code>
6669 (but does not actually store them).
6670 It is intended to be used in conjunction with <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a>
6671 (see <a href="#luaL_newlib"><code>luaL_newlib</code></a>).
6672
6673
6674 <p>
6675 It is implemented as a macro.
6676 The array <code>l</code> must be the actual array,
6677 not a pointer to it.
6678
6679
6680
6681
6682
6683 <hr><h3><a name="luaL_newmetatable"><code>luaL_newmetatable</code></a></h3><p>
6684 <span class="apii">[-0, +1, <em>m</em>]</span>
6685 <pre>int luaL_newmetatable (lua_State *L, const char *tname);</pre>
6686
6687 <p>
6688 If the registry already has the key <code>tname</code>,
6689 returns 0.
6690 Otherwise,
6691 creates a new table to be used as a metatable for userdata,
6692 adds to this new table the pair <code>__name = tname</code>,
6693 adds to the registry the pair <code>[tname] = new table</code>,
6694 and returns 1.
6695 (The entry <code>__name</code> is used by some error-reporting functions.)
6696
6697
6698 <p>
6699 In both cases pushes onto the stack the final value associated
6700 with <code>tname</code> in the registry.
6701
6702
6703
6704
6705
6706 <hr><h3><a name="luaL_newstate"><code>luaL_newstate</code></a></h3><p>
6707 <span class="apii">[-0, +0, &ndash;]</span>
6708 <pre>lua_State *luaL_newstate (void);</pre>
6709
6710 <p>
6711 Creates a new Lua state.
6712 It calls <a href="#lua_newstate"><code>lua_newstate</code></a> with an
6713 allocator based on the standard&nbsp;C <code>realloc</code> function
6714 and then sets a panic function (see <a href="#4.6">&sect;4.6</a>) that prints
6715 an error message to the standard error output in case of fatal
6716 errors.
6717
6718
6719 <p>
6720 Returns the new state,
6721 or <code>NULL</code> if there is a memory allocation error.
6722
6723
6724
6725
6726
6727 <hr><h3><a name="luaL_openlibs"><code>luaL_openlibs</code></a></h3><p>
6728 <span class="apii">[-0, +0, <em>e</em>]</span>
6729 <pre>void luaL_openlibs (lua_State *L);</pre>
6730
6731 <p>
6732 Opens all standard Lua libraries into the given state.
6733
6734
6735
6736
6737
6738 <hr><h3><a name="luaL_opt"><code>luaL_opt</code></a></h3><p>
6739 <span class="apii">[-0, +0, <em>e</em>]</span>
6740 <pre>T luaL_opt (L, func, arg, dflt);</pre>
6741
6742 <p>
6743 This macro is defined as follows:
6744
6745 <pre>
6746      (lua_isnoneornil(L,(arg)) ? (dflt) : func(L,(arg)))
6747 </pre><p>
6748 In words, if the argument <code>arg</code> is nil or absent,
6749 the macro results in the default <code>dflt</code>.
6750 Otherwise, it results in the result of calling <code>func</code>
6751 with the state <code>L</code> and the argument index <code>arg</code> as
6752 parameters.
6753 Note that it evaluates the expression <code>dflt</code> only if needed.
6754
6755
6756
6757
6758
6759 <hr><h3><a name="luaL_optinteger"><code>luaL_optinteger</code></a></h3><p>
6760 <span class="apii">[-0, +0, <em>v</em>]</span>
6761 <pre>lua_Integer luaL_optinteger (lua_State *L,
6762                              int arg,
6763                              lua_Integer d);</pre>
6764
6765 <p>
6766 If the function argument <code>arg</code> is an integer
6767 (or convertible to an integer),
6768 returns this integer.
6769 If this argument is absent or is <b>nil</b>,
6770 returns <code>d</code>.
6771 Otherwise, raises an error.
6772
6773
6774
6775
6776
6777 <hr><h3><a name="luaL_optlstring"><code>luaL_optlstring</code></a></h3><p>
6778 <span class="apii">[-0, +0, <em>v</em>]</span>
6779 <pre>const char *luaL_optlstring (lua_State *L,
6780                              int arg,
6781                              const char *d,
6782                              size_t *l);</pre>
6783
6784 <p>
6785 If the function argument <code>arg</code> is a string,
6786 returns this string.
6787 If this argument is absent or is <b>nil</b>,
6788 returns <code>d</code>.
6789 Otherwise, raises an error.
6790
6791
6792 <p>
6793 If <code>l</code> is not <code>NULL</code>,
6794 fills the position <code>*l</code> with the result's length.
6795 If the result is <code>NULL</code>
6796 (only possible when returning <code>d</code> and <code>d == NULL</code>),
6797 its length is considered zero.
6798
6799
6800 <p>
6801 This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result,
6802 so all conversions and caveats of that function apply here.
6803
6804
6805
6806
6807
6808 <hr><h3><a name="luaL_optnumber"><code>luaL_optnumber</code></a></h3><p>
6809 <span class="apii">[-0, +0, <em>v</em>]</span>
6810 <pre>lua_Number luaL_optnumber (lua_State *L, int arg, lua_Number d);</pre>
6811
6812 <p>
6813 If the function argument <code>arg</code> is a number,
6814 returns this number.
6815 If this argument is absent or is <b>nil</b>,
6816 returns <code>d</code>.
6817 Otherwise, raises an error.
6818
6819
6820
6821
6822
6823 <hr><h3><a name="luaL_optstring"><code>luaL_optstring</code></a></h3><p>
6824 <span class="apii">[-0, +0, <em>v</em>]</span>
6825 <pre>const char *luaL_optstring (lua_State *L,
6826                             int arg,
6827                             const char *d);</pre>
6828
6829 <p>
6830 If the function argument <code>arg</code> is a string,
6831 returns this string.
6832 If this argument is absent or is <b>nil</b>,
6833 returns <code>d</code>.
6834 Otherwise, raises an error.
6835
6836
6837
6838
6839
6840 <hr><h3><a name="luaL_prepbuffer"><code>luaL_prepbuffer</code></a></h3><p>
6841 <span class="apii">[-?, +?, <em>m</em>]</span>
6842 <pre>char *luaL_prepbuffer (luaL_Buffer *B);</pre>
6843
6844 <p>
6845 Equivalent to <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a>
6846 with the predefined size <a name="pdf-LUAL_BUFFERSIZE"><code>LUAL_BUFFERSIZE</code></a>.
6847
6848
6849
6850
6851
6852 <hr><h3><a name="luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a></h3><p>
6853 <span class="apii">[-?, +?, <em>m</em>]</span>
6854 <pre>char *luaL_prepbuffsize (luaL_Buffer *B, size_t sz);</pre>
6855
6856 <p>
6857 Returns an address to a space of size <code>sz</code>
6858 where you can copy a string to be added to buffer <code>B</code>
6859 (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
6860 After copying the string into this space you must call
6861 <a href="#luaL_addsize"><code>luaL_addsize</code></a> with the size of the string to actually add
6862 it to the buffer.
6863
6864
6865
6866
6867
6868 <hr><h3><a name="luaL_pushresult"><code>luaL_pushresult</code></a></h3><p>
6869 <span class="apii">[-?, +1, <em>m</em>]</span>
6870 <pre>void luaL_pushresult (luaL_Buffer *B);</pre>
6871
6872 <p>
6873 Finishes the use of buffer <code>B</code> leaving the final string on
6874 the top of the stack.
6875
6876
6877
6878
6879
6880 <hr><h3><a name="luaL_pushresultsize"><code>luaL_pushresultsize</code></a></h3><p>
6881 <span class="apii">[-?, +1, <em>m</em>]</span>
6882 <pre>void luaL_pushresultsize (luaL_Buffer *B, size_t sz);</pre>
6883
6884 <p>
6885 Equivalent to the sequence <a href="#luaL_addsize"><code>luaL_addsize</code></a>, <a href="#luaL_pushresult"><code>luaL_pushresult</code></a>.
6886
6887
6888
6889
6890
6891 <hr><h3><a name="luaL_ref"><code>luaL_ref</code></a></h3><p>
6892 <span class="apii">[-1, +0, <em>m</em>]</span>
6893 <pre>int luaL_ref (lua_State *L, int t);</pre>
6894
6895 <p>
6896 Creates and returns a <em>reference</em>,
6897 in the table at index <code>t</code>,
6898 for the object at the top of the stack (and pops the object).
6899
6900
6901 <p>
6902 A reference is a unique integer key.
6903 As long as you do not manually add integer keys into table <code>t</code>,
6904 <a href="#luaL_ref"><code>luaL_ref</code></a> ensures the uniqueness of the key it returns.
6905 You can retrieve an object referred by reference <code>r</code>
6906 by calling <code>lua_rawgeti(L, t, r)</code>.
6907 Function <a href="#luaL_unref"><code>luaL_unref</code></a> frees a reference and its associated object.
6908
6909
6910 <p>
6911 If the object at the top of the stack is <b>nil</b>,
6912 <a href="#luaL_ref"><code>luaL_ref</code></a> returns the constant <a name="pdf-LUA_REFNIL"><code>LUA_REFNIL</code></a>.
6913 The constant <a name="pdf-LUA_NOREF"><code>LUA_NOREF</code></a> is guaranteed to be different
6914 from any reference returned by <a href="#luaL_ref"><code>luaL_ref</code></a>.
6915
6916
6917
6918
6919
6920 <hr><h3><a name="luaL_Reg"><code>luaL_Reg</code></a></h3>
6921 <pre>typedef struct luaL_Reg {
6922   const char *name;
6923   lua_CFunction func;
6924 } luaL_Reg;</pre>
6925
6926 <p>
6927 Type for arrays of functions to be registered by
6928 <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a>.
6929 <code>name</code> is the function name and <code>func</code> is a pointer to
6930 the function.
6931 Any array of <a href="#luaL_Reg"><code>luaL_Reg</code></a> must end with a sentinel entry
6932 in which both <code>name</code> and <code>func</code> are <code>NULL</code>.
6933
6934
6935
6936
6937
6938 <hr><h3><a name="luaL_requiref"><code>luaL_requiref</code></a></h3><p>
6939 <span class="apii">[-0, +1, <em>e</em>]</span>
6940 <pre>void luaL_requiref (lua_State *L, const char *modname,
6941                     lua_CFunction openf, int glb);</pre>
6942
6943 <p>
6944 If <code>modname</code> is not already present in <a href="#pdf-package.loaded"><code>package.loaded</code></a>,
6945 calls function <code>openf</code> with string <code>modname</code> as an argument
6946 and sets the call result in <code>package.loaded[modname]</code>,
6947 as if that function has been called through <a href="#pdf-require"><code>require</code></a>.
6948
6949
6950 <p>
6951 If <code>glb</code> is true,
6952 also stores the module into global <code>modname</code>.
6953
6954
6955 <p>
6956 Leaves a copy of the module on the stack.
6957
6958
6959
6960
6961
6962 <hr><h3><a name="luaL_setfuncs"><code>luaL_setfuncs</code></a></h3><p>
6963 <span class="apii">[-nup, +0, <em>m</em>]</span>
6964 <pre>void luaL_setfuncs (lua_State *L, const luaL_Reg *l, int nup);</pre>
6965
6966 <p>
6967 Registers all functions in the array <code>l</code>
6968 (see <a href="#luaL_Reg"><code>luaL_Reg</code></a>) into the table on the top of the stack
6969 (below optional upvalues, see next).
6970
6971
6972 <p>
6973 When <code>nup</code> is not zero,
6974 all functions are created sharing <code>nup</code> upvalues,
6975 which must be previously pushed on the stack
6976 on top of the library table.
6977 These values are popped from the stack after the registration.
6978
6979
6980
6981
6982
6983 <hr><h3><a name="luaL_setmetatable"><code>luaL_setmetatable</code></a></h3><p>
6984 <span class="apii">[-0, +0, &ndash;]</span>
6985 <pre>void luaL_setmetatable (lua_State *L, const char *tname);</pre>
6986
6987 <p>
6988 Sets the metatable of the object at the top of the stack
6989 as the metatable associated with name <code>tname</code>
6990 in the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>).
6991
6992
6993
6994
6995
6996 <hr><h3><a name="luaL_Stream"><code>luaL_Stream</code></a></h3>
6997 <pre>typedef struct luaL_Stream {
6998   FILE *f;
6999   lua_CFunction closef;
7000 } luaL_Stream;</pre>
7001
7002 <p>
7003 The standard representation for file handles,
7004 which is used by the standard I/O library.
7005
7006
7007 <p>
7008 A file handle is implemented as a full userdata,
7009 with a metatable called <code>LUA_FILEHANDLE</code>
7010 (where <code>LUA_FILEHANDLE</code> is a macro with the actual metatable's name).
7011 The metatable is created by the I/O library
7012 (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>).
7013
7014
7015 <p>
7016 This userdata must start with the structure <code>luaL_Stream</code>;
7017 it can contain other data after this initial structure.
7018 Field <code>f</code> points to the corresponding C stream
7019 (or it can be <code>NULL</code> to indicate an incompletely created handle).
7020 Field <code>closef</code> points to a Lua function
7021 that will be called to close the stream
7022 when the handle is closed or collected;
7023 this function receives the file handle as its sole argument and
7024 must return either <b>true</b> (in case of success)
7025 or <b>nil</b> plus an error message (in case of error).
7026 Once Lua calls this field,
7027 it changes the field value to <code>NULL</code>
7028 to signal that the handle is closed.
7029
7030
7031
7032
7033
7034 <hr><h3><a name="luaL_testudata"><code>luaL_testudata</code></a></h3><p>
7035 <span class="apii">[-0, +0, <em>m</em>]</span>
7036 <pre>void *luaL_testudata (lua_State *L, int arg, const char *tname);</pre>
7037
7038 <p>
7039 This function works like <a href="#luaL_checkudata"><code>luaL_checkudata</code></a>,
7040 except that, when the test fails,
7041 it returns <code>NULL</code> instead of raising an error.
7042
7043
7044
7045
7046
7047 <hr><h3><a name="luaL_tolstring"><code>luaL_tolstring</code></a></h3><p>
7048 <span class="apii">[-0, +1, <em>e</em>]</span>
7049 <pre>const char *luaL_tolstring (lua_State *L, int idx, size_t *len);</pre>
7050
7051 <p>
7052 Converts any Lua value at the given index to a C&nbsp;string
7053 in a reasonable format.
7054 The resulting string is pushed onto the stack and also
7055 returned by the function.
7056 If <code>len</code> is not <code>NULL</code>,
7057 the function also sets <code>*len</code> with the string length.
7058
7059
7060 <p>
7061 If the value has a metatable with a <code>__tostring</code> field,
7062 then <code>luaL_tolstring</code> calls the corresponding metamethod
7063 with the value as argument,
7064 and uses the result of the call as its result.
7065
7066
7067
7068
7069
7070 <hr><h3><a name="luaL_traceback"><code>luaL_traceback</code></a></h3><p>
7071 <span class="apii">[-0, +1, <em>m</em>]</span>
7072 <pre>void luaL_traceback (lua_State *L, lua_State *L1, const char *msg,
7073                      int level);</pre>
7074
7075 <p>
7076 Creates and pushes a traceback of the stack <code>L1</code>.
7077 If <code>msg</code> is not <code>NULL</code> it is appended
7078 at the beginning of the traceback.
7079 The <code>level</code> parameter tells at which level
7080 to start the traceback.
7081
7082
7083
7084
7085
7086 <hr><h3><a name="luaL_typename"><code>luaL_typename</code></a></h3><p>
7087 <span class="apii">[-0, +0, &ndash;]</span>
7088 <pre>const char *luaL_typename (lua_State *L, int index);</pre>
7089
7090 <p>
7091 Returns the name of the type of the value at the given index.
7092
7093
7094
7095
7096
7097 <hr><h3><a name="luaL_unref"><code>luaL_unref</code></a></h3><p>
7098 <span class="apii">[-0, +0, &ndash;]</span>
7099 <pre>void luaL_unref (lua_State *L, int t, int ref);</pre>
7100
7101 <p>
7102 Releases reference <code>ref</code> from the table at index <code>t</code>
7103 (see <a href="#luaL_ref"><code>luaL_ref</code></a>).
7104 The entry is removed from the table,
7105 so that the referred object can be collected.
7106 The reference <code>ref</code> is also freed to be used again.
7107
7108
7109 <p>
7110 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>,
7111 <a href="#luaL_unref"><code>luaL_unref</code></a> does nothing.
7112
7113
7114
7115
7116
7117 <hr><h3><a name="luaL_where"><code>luaL_where</code></a></h3><p>
7118 <span class="apii">[-0, +1, <em>m</em>]</span>
7119 <pre>void luaL_where (lua_State *L, int lvl);</pre>
7120
7121 <p>
7122 Pushes onto the stack a string identifying the current position
7123 of the control at level <code>lvl</code> in the call stack.
7124 Typically this string has the following format:
7125
7126 <pre>
7127      <em>chunkname</em>:<em>currentline</em>:
7128 </pre><p>
7129 Level&nbsp;0 is the running function,
7130 level&nbsp;1 is the function that called the running function,
7131 etc.
7132
7133
7134 <p>
7135 This function is used to build a prefix for error messages.
7136
7137
7138
7139
7140
7141
7142
7143 <h1>6 &ndash; <a name="6">Standard Libraries</a></h1>
7144
7145 <p>
7146 The standard Lua libraries provide useful functions
7147 that are implemented directly through the C&nbsp;API.
7148 Some of these functions provide essential services to the language
7149 (e.g., <a href="#pdf-type"><code>type</code></a> and <a href="#pdf-getmetatable"><code>getmetatable</code></a>);
7150 others provide access to "outside" services (e.g., I/O);
7151 and others could be implemented in Lua itself,
7152 but are quite useful or have critical performance requirements that
7153 deserve an implementation in C (e.g., <a href="#pdf-table.sort"><code>table.sort</code></a>).
7154
7155
7156 <p>
7157 All libraries are implemented through the official C&nbsp;API
7158 and are provided as separate C&nbsp;modules.
7159 Currently, Lua has the following standard libraries:
7160
7161 <ul>
7162
7163 <li>basic library (<a href="#6.1">&sect;6.1</a>);</li>
7164
7165 <li>coroutine library (<a href="#6.2">&sect;6.2</a>);</li>
7166
7167 <li>package library (<a href="#6.3">&sect;6.3</a>);</li>
7168
7169 <li>string manipulation (<a href="#6.4">&sect;6.4</a>);</li>
7170
7171 <li>basic UTF-8 support (<a href="#6.5">&sect;6.5</a>);</li>
7172
7173 <li>table manipulation (<a href="#6.6">&sect;6.6</a>);</li>
7174
7175 <li>mathematical functions (<a href="#6.7">&sect;6.7</a>) (sin, log, etc.);</li>
7176
7177 <li>input and output (<a href="#6.8">&sect;6.8</a>);</li>
7178
7179 <li>operating system facilities (<a href="#6.9">&sect;6.9</a>);</li>
7180
7181 <li>debug facilities (<a href="#6.10">&sect;6.10</a>).</li>
7182
7183 </ul><p>
7184 Except for the basic and the package libraries,
7185 each library provides all its functions as fields of a global table
7186 or as methods of its objects.
7187
7188
7189 <p>
7190 To have access to these libraries,
7191 the C&nbsp;host program should call the <a href="#luaL_openlibs"><code>luaL_openlibs</code></a> function,
7192 which opens all standard libraries.
7193 Alternatively,
7194 the host program can open them individually by using
7195 <a href="#luaL_requiref"><code>luaL_requiref</code></a> to call
7196 <a name="pdf-luaopen_base"><code>luaopen_base</code></a> (for the basic library),
7197 <a name="pdf-luaopen_package"><code>luaopen_package</code></a> (for the package library),
7198 <a name="pdf-luaopen_coroutine"><code>luaopen_coroutine</code></a> (for the coroutine library),
7199 <a name="pdf-luaopen_string"><code>luaopen_string</code></a> (for the string library),
7200 <a name="pdf-luaopen_utf8"><code>luaopen_utf8</code></a> (for the UTF8 library),
7201 <a name="pdf-luaopen_table"><code>luaopen_table</code></a> (for the table library),
7202 <a name="pdf-luaopen_math"><code>luaopen_math</code></a> (for the mathematical library),
7203 <a name="pdf-luaopen_io"><code>luaopen_io</code></a> (for the I/O library),
7204 <a name="pdf-luaopen_os"><code>luaopen_os</code></a> (for the operating system library),
7205 and <a name="pdf-luaopen_debug"><code>luaopen_debug</code></a> (for the debug library).
7206 These functions are declared in <a name="pdf-lualib.h"><code>lualib.h</code></a>.
7207
7208
7209
7210 <h2>6.1 &ndash; <a name="6.1">Basic Functions</a></h2>
7211
7212 <p>
7213 The basic library provides core functions to Lua.
7214 If you do not include this library in your application,
7215 you should check carefully whether you need to provide
7216 implementations for some of its facilities.
7217
7218
7219 <p>
7220 <hr><h3><a name="pdf-assert"><code>assert (v [, message])</code></a></h3>
7221
7222
7223 <p>
7224 Calls <a href="#pdf-error"><code>error</code></a> if
7225 the value of its argument <code>v</code> is false (i.e., <b>nil</b> or <b>false</b>);
7226 otherwise, returns all its arguments.
7227 In case of error,
7228 <code>message</code> is the error object;
7229 when absent, it defaults to "<code>assertion failed!</code>"
7230
7231
7232
7233
7234 <p>
7235 <hr><h3><a name="pdf-collectgarbage"><code>collectgarbage ([opt [, arg]])</code></a></h3>
7236
7237
7238 <p>
7239 This function is a generic interface to the garbage collector.
7240 It performs different functions according to its first argument, <code>opt</code>:
7241
7242 <ul>
7243
7244 <li><b>"<code>collect</code>": </b>
7245 performs a full garbage-collection cycle.
7246 This is the default option.
7247 </li>
7248
7249 <li><b>"<code>stop</code>": </b>
7250 stops automatic execution of the garbage collector.
7251 The collector will run only when explicitly invoked,
7252 until a call to restart it.
7253 </li>
7254
7255 <li><b>"<code>restart</code>": </b>
7256 restarts automatic execution of the garbage collector.
7257 </li>
7258
7259 <li><b>"<code>count</code>": </b>
7260 returns the total memory in use by Lua in Kbytes.
7261 The value has a fractional part,
7262 so that it multiplied by 1024
7263 gives the exact number of bytes in use by Lua
7264 (except for overflows).
7265 </li>
7266
7267 <li><b>"<code>step</code>": </b>
7268 performs a garbage-collection step.
7269 The step "size" is controlled by <code>arg</code>.
7270 With a zero value,
7271 the collector will perform one basic (indivisible) step.
7272 For non-zero values,
7273 the collector will perform as if that amount of memory
7274 (in KBytes) had been allocated by Lua.
7275 Returns <b>true</b> if the step finished a collection cycle.
7276 </li>
7277
7278 <li><b>"<code>setpause</code>": </b>
7279 sets <code>arg</code> as the new value for the <em>pause</em> of
7280 the collector (see <a href="#2.5">&sect;2.5</a>).
7281 Returns the previous value for <em>pause</em>.
7282 </li>
7283
7284 <li><b>"<code>setstepmul</code>": </b>
7285 sets <code>arg</code> as the new value for the <em>step multiplier</em> of
7286 the collector (see <a href="#2.5">&sect;2.5</a>).
7287 Returns the previous value for <em>step</em>.
7288 </li>
7289
7290 <li><b>"<code>isrunning</code>": </b>
7291 returns a boolean that tells whether the collector is running
7292 (i.e., not stopped).
7293 </li>
7294
7295 </ul>
7296
7297
7298
7299 <p>
7300 <hr><h3><a name="pdf-dofile"><code>dofile ([filename])</code></a></h3>
7301 Opens the named file and executes its contents as a Lua chunk.
7302 When called without arguments,
7303 <code>dofile</code> executes the contents of the standard input (<code>stdin</code>).
7304 Returns all values returned by the chunk.
7305 In case of errors, <code>dofile</code> propagates the error
7306 to its caller (that is, <code>dofile</code> does not run in protected mode).
7307
7308
7309
7310
7311 <p>
7312 <hr><h3><a name="pdf-error"><code>error (message [, level])</code></a></h3>
7313 Terminates the last protected function called
7314 and returns <code>message</code> as the error object.
7315 Function <code>error</code> never returns.
7316
7317
7318 <p>
7319 Usually, <code>error</code> adds some information about the error position
7320 at the beginning of the message, if the message is a string.
7321 The <code>level</code> argument specifies how to get the error position.
7322 With level&nbsp;1 (the default), the error position is where the
7323 <code>error</code> function was called.
7324 Level&nbsp;2 points the error to where the function
7325 that called <code>error</code> was called; and so on.
7326 Passing a level&nbsp;0 avoids the addition of error position information
7327 to the message.
7328
7329
7330
7331
7332 <p>
7333 <hr><h3><a name="pdf-_G"><code>_G</code></a></h3>
7334 A global variable (not a function) that
7335 holds the global environment (see <a href="#2.2">&sect;2.2</a>).
7336 Lua itself does not use this variable;
7337 changing its value does not affect any environment,
7338 nor vice versa.
7339
7340
7341
7342
7343 <p>
7344 <hr><h3><a name="pdf-getmetatable"><code>getmetatable (object)</code></a></h3>
7345
7346
7347 <p>
7348 If <code>object</code> does not have a metatable, returns <b>nil</b>.
7349 Otherwise,
7350 if the object's metatable has a <code>__metatable</code> field,
7351 returns the associated value.
7352 Otherwise, returns the metatable of the given object.
7353
7354
7355
7356
7357 <p>
7358 <hr><h3><a name="pdf-ipairs"><code>ipairs (t)</code></a></h3>
7359
7360
7361 <p>
7362 Returns three values (an iterator function, the table <code>t</code>, and 0)
7363 so that the construction
7364
7365 <pre>
7366      for i,v in ipairs(t) do <em>body</em> end
7367 </pre><p>
7368 will iterate over the key&ndash;value pairs
7369 (<code>1,t[1]</code>), (<code>2,t[2]</code>), ...,
7370 up to the first nil value.
7371
7372
7373
7374
7375 <p>
7376 <hr><h3><a name="pdf-load"><code>load (chunk [, chunkname [, mode [, env]]])</code></a></h3>
7377
7378
7379 <p>
7380 Loads a chunk.
7381
7382
7383 <p>
7384 If <code>chunk</code> is a string, the chunk is this string.
7385 If <code>chunk</code> is a function,
7386 <code>load</code> calls it repeatedly to get the chunk pieces.
7387 Each call to <code>chunk</code> must return a string that concatenates
7388 with previous results.
7389 A return of an empty string, <b>nil</b>, or no value signals the end of the chunk.
7390
7391
7392 <p>
7393 If there are no syntactic errors,
7394 returns the compiled chunk as a function;
7395 otherwise, returns <b>nil</b> plus the error message.
7396
7397
7398 <p>
7399 If the resulting function has upvalues,
7400 the first upvalue is set to the value of <code>env</code>,
7401 if that parameter is given,
7402 or to the value of the global environment.
7403 Other upvalues are initialized with <b>nil</b>.
7404 (When you load a main chunk,
7405 the resulting function will always have exactly one upvalue,
7406 the <code>_ENV</code> variable (see <a href="#2.2">&sect;2.2</a>).
7407 However,
7408 when you load a binary chunk created from a function (see <a href="#pdf-string.dump"><code>string.dump</code></a>),
7409 the resulting function can have an arbitrary number of upvalues.)
7410 All upvalues are fresh, that is,
7411 they are not shared with any other function.
7412
7413
7414 <p>
7415 <code>chunkname</code> is used as the name of the chunk for error messages
7416 and debug information (see <a href="#4.9">&sect;4.9</a>).
7417 When absent,
7418 it defaults to <code>chunk</code>, if <code>chunk</code> is a string,
7419 or to "<code>=(load)</code>" otherwise.
7420
7421
7422 <p>
7423 The string <code>mode</code> controls whether the chunk can be text or binary
7424 (that is, a precompiled chunk).
7425 It may be the string "<code>b</code>" (only binary chunks),
7426 "<code>t</code>" (only text chunks),
7427 or "<code>bt</code>" (both binary and text).
7428 The default is "<code>bt</code>".
7429
7430
7431 <p>
7432 Lua does not check the consistency of binary chunks.
7433 Maliciously crafted binary chunks can crash
7434 the interpreter.
7435
7436
7437
7438
7439 <p>
7440 <hr><h3><a name="pdf-loadfile"><code>loadfile ([filename [, mode [, env]]])</code></a></h3>
7441
7442
7443 <p>
7444 Similar to <a href="#pdf-load"><code>load</code></a>,
7445 but gets the chunk from file <code>filename</code>
7446 or from the standard input,
7447 if no file name is given.
7448
7449
7450
7451
7452 <p>
7453 <hr><h3><a name="pdf-next"><code>next (table [, index])</code></a></h3>
7454
7455
7456 <p>
7457 Allows a program to traverse all fields of a table.
7458 Its first argument is a table and its second argument
7459 is an index in this table.
7460 <code>next</code> returns the next index of the table
7461 and its associated value.
7462 When called with <b>nil</b> as its second argument,
7463 <code>next</code> returns an initial index
7464 and its associated value.
7465 When called with the last index,
7466 or with <b>nil</b> in an empty table,
7467 <code>next</code> returns <b>nil</b>.
7468 If the second argument is absent, then it is interpreted as <b>nil</b>.
7469 In particular,
7470 you can use <code>next(t)</code> to check whether a table is empty.
7471
7472
7473 <p>
7474 The order in which the indices are enumerated is not specified,
7475 <em>even for numeric indices</em>.
7476 (To traverse a table in numerical order,
7477 use a numerical <b>for</b>.)
7478
7479
7480 <p>
7481 The behavior of <code>next</code> is undefined if,
7482 during the traversal,
7483 you assign any value to a non-existent field in the table.
7484 You may however modify existing fields.
7485 In particular, you may clear existing fields.
7486
7487
7488
7489
7490 <p>
7491 <hr><h3><a name="pdf-pairs"><code>pairs (t)</code></a></h3>
7492
7493
7494 <p>
7495 If <code>t</code> has a metamethod <code>__pairs</code>,
7496 calls it with <code>t</code> as argument and returns the first three
7497 results from the call.
7498
7499
7500 <p>
7501 Otherwise,
7502 returns three values: the <a href="#pdf-next"><code>next</code></a> function, the table <code>t</code>, and <b>nil</b>,
7503 so that the construction
7504
7505 <pre>
7506      for k,v in pairs(t) do <em>body</em> end
7507 </pre><p>
7508 will iterate over all key&ndash;value pairs of table <code>t</code>.
7509
7510
7511 <p>
7512 See function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying
7513 the table during its traversal.
7514
7515
7516
7517
7518 <p>
7519 <hr><h3><a name="pdf-pcall"><code>pcall (f [, arg1, &middot;&middot;&middot;])</code></a></h3>
7520
7521
7522 <p>
7523 Calls function <code>f</code> with
7524 the given arguments in <em>protected mode</em>.
7525 This means that any error inside&nbsp;<code>f</code> is not propagated;
7526 instead, <code>pcall</code> catches the error
7527 and returns a status code.
7528 Its first result is the status code (a boolean),
7529 which is true if the call succeeds without errors.
7530 In such case, <code>pcall</code> also returns all results from the call,
7531 after this first result.
7532 In case of any error, <code>pcall</code> returns <b>false</b> plus the error message.
7533
7534
7535
7536
7537 <p>
7538 <hr><h3><a name="pdf-print"><code>print (&middot;&middot;&middot;)</code></a></h3>
7539 Receives any number of arguments
7540 and prints their values to <code>stdout</code>,
7541 using the <a href="#pdf-tostring"><code>tostring</code></a> function to convert each argument to a string.
7542 <code>print</code> is not intended for formatted output,
7543 but only as a quick way to show a value,
7544 for instance for debugging.
7545 For complete control over the output,
7546 use <a href="#pdf-string.format"><code>string.format</code></a> and <a href="#pdf-io.write"><code>io.write</code></a>.
7547
7548
7549
7550
7551 <p>
7552 <hr><h3><a name="pdf-rawequal"><code>rawequal (v1, v2)</code></a></h3>
7553 Checks whether <code>v1</code> is equal to <code>v2</code>,
7554 without invoking the <code>__eq</code> metamethod.
7555 Returns a boolean.
7556
7557
7558
7559
7560 <p>
7561 <hr><h3><a name="pdf-rawget"><code>rawget (table, index)</code></a></h3>
7562 Gets the real value of <code>table[index]</code>,
7563 without invoking the <code>__index</code> metamethod.
7564 <code>table</code> must be a table;
7565 <code>index</code> may be any value.
7566
7567
7568
7569
7570 <p>
7571 <hr><h3><a name="pdf-rawlen"><code>rawlen (v)</code></a></h3>
7572 Returns the length of the object <code>v</code>,
7573 which must be a table or a string,
7574 without invoking the <code>__len</code> metamethod.
7575 Returns an integer.
7576
7577
7578
7579
7580 <p>
7581 <hr><h3><a name="pdf-rawset"><code>rawset (table, index, value)</code></a></h3>
7582 Sets the real value of <code>table[index]</code> to <code>value</code>,
7583 without invoking the <code>__newindex</code> metamethod.
7584 <code>table</code> must be a table,
7585 <code>index</code> any value different from <b>nil</b> and NaN,
7586 and <code>value</code> any Lua value.
7587
7588
7589 <p>
7590 This function returns <code>table</code>.
7591
7592
7593
7594
7595 <p>
7596 <hr><h3><a name="pdf-select"><code>select (index, &middot;&middot;&middot;)</code></a></h3>
7597
7598
7599 <p>
7600 If <code>index</code> is a number,
7601 returns all arguments after argument number <code>index</code>;
7602 a negative number indexes from the end (-1 is the last argument).
7603 Otherwise, <code>index</code> must be the string <code>"#"</code>,
7604 and <code>select</code> returns the total number of extra arguments it received.
7605
7606
7607
7608
7609 <p>
7610 <hr><h3><a name="pdf-setmetatable"><code>setmetatable (table, metatable)</code></a></h3>
7611
7612
7613 <p>
7614 Sets the metatable for the given table.
7615 (To change the metatable of other types from Lua code,
7616 you must use the debug library (<a href="#6.10">&sect;6.10</a>).)
7617 If <code>metatable</code> is <b>nil</b>,
7618 removes the metatable of the given table.
7619 If the original metatable has a <code>__metatable</code> field,
7620 raises an error.
7621
7622
7623 <p>
7624 This function returns <code>table</code>.
7625
7626
7627
7628
7629 <p>
7630 <hr><h3><a name="pdf-tonumber"><code>tonumber (e [, base])</code></a></h3>
7631
7632
7633 <p>
7634 When called with no <code>base</code>,
7635 <code>tonumber</code> tries to convert its argument to a number.
7636 If the argument is already a number or
7637 a string convertible to a number,
7638 then <code>tonumber</code> returns this number;
7639 otherwise, it returns <b>nil</b>.
7640
7641
7642 <p>
7643 The conversion of strings can result in integers or floats,
7644 according to the lexical conventions of Lua (see <a href="#3.1">&sect;3.1</a>).
7645 (The string may have leading and trailing spaces and a sign.)
7646
7647
7648 <p>
7649 When called with <code>base</code>,
7650 then <code>e</code> must be a string to be interpreted as
7651 an integer numeral in that base.
7652 The base may be any integer between 2 and 36, inclusive.
7653 In bases above&nbsp;10, the letter '<code>A</code>' (in either upper or lower case)
7654 represents&nbsp;10, '<code>B</code>' represents&nbsp;11, and so forth,
7655 with '<code>Z</code>' representing 35.
7656 If the string <code>e</code> is not a valid numeral in the given base,
7657 the function returns <b>nil</b>.
7658
7659
7660
7661
7662 <p>
7663 <hr><h3><a name="pdf-tostring"><code>tostring (v)</code></a></h3>
7664 Receives a value of any type and
7665 converts it to a string in a human-readable format.
7666 (For complete control of how numbers are converted,
7667 use <a href="#pdf-string.format"><code>string.format</code></a>.)
7668
7669
7670 <p>
7671 If the metatable of <code>v</code> has a <code>__tostring</code> field,
7672 then <code>tostring</code> calls the corresponding value
7673 with <code>v</code> as argument,
7674 and uses the result of the call as its result.
7675
7676
7677
7678
7679 <p>
7680 <hr><h3><a name="pdf-type"><code>type (v)</code></a></h3>
7681 Returns the type of its only argument, coded as a string.
7682 The possible results of this function are
7683 "<code>nil</code>" (a string, not the value <b>nil</b>),
7684 "<code>number</code>",
7685 "<code>string</code>",
7686 "<code>boolean</code>",
7687 "<code>table</code>",
7688 "<code>function</code>",
7689 "<code>thread</code>",
7690 and "<code>userdata</code>".
7691
7692
7693
7694
7695 <p>
7696 <hr><h3><a name="pdf-_VERSION"><code>_VERSION</code></a></h3>
7697
7698
7699 <p>
7700 A global variable (not a function) that
7701 holds a string containing the running Lua version.
7702 The current value of this variable is "<code>Lua 5.3</code>".
7703
7704
7705
7706
7707 <p>
7708 <hr><h3><a name="pdf-xpcall"><code>xpcall (f, msgh [, arg1, &middot;&middot;&middot;])</code></a></h3>
7709
7710
7711 <p>
7712 This function is similar to <a href="#pdf-pcall"><code>pcall</code></a>,
7713 except that it sets a new message handler <code>msgh</code>.
7714
7715
7716
7717
7718
7719
7720
7721 <h2>6.2 &ndash; <a name="6.2">Coroutine Manipulation</a></h2>
7722
7723 <p>
7724 This library comprises the operations to manipulate coroutines,
7725 which come inside the table <a name="pdf-coroutine"><code>coroutine</code></a>.
7726 See <a href="#2.6">&sect;2.6</a> for a general description of coroutines.
7727
7728
7729 <p>
7730 <hr><h3><a name="pdf-coroutine.create"><code>coroutine.create (f)</code></a></h3>
7731
7732
7733 <p>
7734 Creates a new coroutine, with body <code>f</code>.
7735 <code>f</code> must be a function.
7736 Returns this new coroutine,
7737 an object with type <code>"thread"</code>.
7738
7739
7740
7741
7742 <p>
7743 <hr><h3><a name="pdf-coroutine.isyieldable"><code>coroutine.isyieldable ()</code></a></h3>
7744
7745
7746 <p>
7747 Returns true when the running coroutine can yield.
7748
7749
7750 <p>
7751 A running coroutine is yieldable if it is not the main thread and
7752 it is not inside a non-yieldable C&nbsp;function.
7753
7754
7755
7756
7757 <p>
7758 <hr><h3><a name="pdf-coroutine.resume"><code>coroutine.resume (co [, val1, &middot;&middot;&middot;])</code></a></h3>
7759
7760
7761 <p>
7762 Starts or continues the execution of coroutine <code>co</code>.
7763 The first time you resume a coroutine,
7764 it starts running its body.
7765 The values <code>val1</code>, ... are passed
7766 as the arguments to the body function.
7767 If the coroutine has yielded,
7768 <code>resume</code> restarts it;
7769 the values <code>val1</code>, ... are passed
7770 as the results from the yield.
7771
7772
7773 <p>
7774 If the coroutine runs without any errors,
7775 <code>resume</code> returns <b>true</b> plus any values passed to <code>yield</code>
7776 (when the coroutine yields) or any values returned by the body function
7777 (when the coroutine terminates).
7778 If there is any error,
7779 <code>resume</code> returns <b>false</b> plus the error message.
7780
7781
7782
7783
7784 <p>
7785 <hr><h3><a name="pdf-coroutine.running"><code>coroutine.running ()</code></a></h3>
7786
7787
7788 <p>
7789 Returns the running coroutine plus a boolean,
7790 true when the running coroutine is the main one.
7791
7792
7793
7794
7795 <p>
7796 <hr><h3><a name="pdf-coroutine.status"><code>coroutine.status (co)</code></a></h3>
7797
7798
7799 <p>
7800 Returns the status of coroutine <code>co</code>, as a string:
7801 <code>"running"</code>,
7802 if the coroutine is running (that is, it called <code>status</code>);
7803 <code>"suspended"</code>, if the coroutine is suspended in a call to <code>yield</code>,
7804 or if it has not started running yet;
7805 <code>"normal"</code> if the coroutine is active but not running
7806 (that is, it has resumed another coroutine);
7807 and <code>"dead"</code> if the coroutine has finished its body function,
7808 or if it has stopped with an error.
7809
7810
7811
7812
7813 <p>
7814 <hr><h3><a name="pdf-coroutine.wrap"><code>coroutine.wrap (f)</code></a></h3>
7815
7816
7817 <p>
7818 Creates a new coroutine, with body <code>f</code>.
7819 <code>f</code> must be a function.
7820 Returns a function that resumes the coroutine each time it is called.
7821 Any arguments passed to the function behave as the
7822 extra arguments to <code>resume</code>.
7823 Returns the same values returned by <code>resume</code>,
7824 except the first boolean.
7825 In case of error, propagates the error.
7826
7827
7828
7829
7830 <p>
7831 <hr><h3><a name="pdf-coroutine.yield"><code>coroutine.yield (&middot;&middot;&middot;)</code></a></h3>
7832
7833
7834 <p>
7835 Suspends the execution of the calling coroutine.
7836 Any arguments to <code>yield</code> are passed as extra results to <code>resume</code>.
7837
7838
7839
7840
7841
7842
7843
7844 <h2>6.3 &ndash; <a name="6.3">Modules</a></h2>
7845
7846 <p>
7847 The package library provides basic
7848 facilities for loading modules in Lua.
7849 It exports one function directly in the global environment:
7850 <a href="#pdf-require"><code>require</code></a>.
7851 Everything else is exported in a table <a name="pdf-package"><code>package</code></a>.
7852
7853
7854 <p>
7855 <hr><h3><a name="pdf-require"><code>require (modname)</code></a></h3>
7856
7857
7858 <p>
7859 Loads the given module.
7860 The function starts by looking into the <a href="#pdf-package.loaded"><code>package.loaded</code></a> table
7861 to determine whether <code>modname</code> is already loaded.
7862 If it is, then <code>require</code> returns the value stored
7863 at <code>package.loaded[modname]</code>.
7864 Otherwise, it tries to find a <em>loader</em> for the module.
7865
7866
7867 <p>
7868 To find a loader,
7869 <code>require</code> is guided by the <a href="#pdf-package.searchers"><code>package.searchers</code></a> sequence.
7870 By changing this sequence,
7871 we can change how <code>require</code> looks for a module.
7872 The following explanation is based on the default configuration
7873 for <a href="#pdf-package.searchers"><code>package.searchers</code></a>.
7874
7875
7876 <p>
7877 First <code>require</code> queries <code>package.preload[modname]</code>.
7878 If it has a value,
7879 this value (which must be a function) is the loader.
7880 Otherwise <code>require</code> searches for a Lua loader using the
7881 path stored in <a href="#pdf-package.path"><code>package.path</code></a>.
7882 If that also fails, it searches for a C&nbsp;loader using the
7883 path stored in <a href="#pdf-package.cpath"><code>package.cpath</code></a>.
7884 If that also fails,
7885 it tries an <em>all-in-one</em> loader (see <a href="#pdf-package.searchers"><code>package.searchers</code></a>).
7886
7887
7888 <p>
7889 Once a loader is found,
7890 <code>require</code> calls the loader with two arguments:
7891 <code>modname</code> and an extra value dependent on how it got the loader.
7892 (If the loader came from a file,
7893 this extra value is the file name.)
7894 If the loader returns any non-nil value,
7895 <code>require</code> assigns the returned value to <code>package.loaded[modname]</code>.
7896 If the loader does not return a non-nil value and
7897 has not assigned any value to <code>package.loaded[modname]</code>,
7898 then <code>require</code> assigns <b>true</b> to this entry.
7899 In any case, <code>require</code> returns the
7900 final value of <code>package.loaded[modname]</code>.
7901
7902
7903 <p>
7904 If there is any error loading or running the module,
7905 or if it cannot find any loader for the module,
7906 then <code>require</code> raises an error.
7907
7908
7909
7910
7911 <p>
7912 <hr><h3><a name="pdf-package.config"><code>package.config</code></a></h3>
7913
7914
7915 <p>
7916 A string describing some compile-time configurations for packages.
7917 This string is a sequence of lines:
7918
7919 <ul>
7920
7921 <li>The first line is the directory separator string.
7922 Default is '<code>\</code>' for Windows and '<code>/</code>' for all other systems.</li>
7923
7924 <li>The second line is the character that separates templates in a path.
7925 Default is '<code>;</code>'.</li>
7926
7927 <li>The third line is the string that marks the
7928 substitution points in a template.
7929 Default is '<code>?</code>'.</li>
7930
7931 <li>The fourth line is a string that, in a path in Windows,
7932 is replaced by the executable's directory.
7933 Default is '<code>!</code>'.</li>
7934
7935 <li>The fifth line is a mark to ignore all text after it
7936 when building the <code>luaopen_</code> function name.
7937 Default is '<code>-</code>'.</li>
7938
7939 </ul>
7940
7941
7942
7943 <p>
7944 <hr><h3><a name="pdf-package.cpath"><code>package.cpath</code></a></h3>
7945
7946
7947 <p>
7948 The path used by <a href="#pdf-require"><code>require</code></a> to search for a C&nbsp;loader.
7949
7950
7951 <p>
7952 Lua initializes the C&nbsp;path <a href="#pdf-package.cpath"><code>package.cpath</code></a> in the same way
7953 it initializes the Lua path <a href="#pdf-package.path"><code>package.path</code></a>,
7954 using the environment variable <a name="pdf-LUA_CPATH_5_3"><code>LUA_CPATH_5_3</code></a>,
7955 or the environment variable <a name="pdf-LUA_CPATH"><code>LUA_CPATH</code></a>,
7956 or a default path defined in <code>luaconf.h</code>.
7957
7958
7959
7960
7961 <p>
7962 <hr><h3><a name="pdf-package.loaded"><code>package.loaded</code></a></h3>
7963
7964
7965 <p>
7966 A table used by <a href="#pdf-require"><code>require</code></a> to control which
7967 modules are already loaded.
7968 When you require a module <code>modname</code> and
7969 <code>package.loaded[modname]</code> is not false,
7970 <a href="#pdf-require"><code>require</code></a> simply returns the value stored there.
7971
7972
7973 <p>
7974 This variable is only a reference to the real table;
7975 assignments to this variable do not change the
7976 table used by <a href="#pdf-require"><code>require</code></a>.
7977
7978
7979
7980
7981 <p>
7982 <hr><h3><a name="pdf-package.loadlib"><code>package.loadlib (libname, funcname)</code></a></h3>
7983
7984
7985 <p>
7986 Dynamically links the host program with the C&nbsp;library <code>libname</code>.
7987
7988
7989 <p>
7990 If <code>funcname</code> is "<code>*</code>",
7991 then it only links with the library,
7992 making the symbols exported by the library
7993 available to other dynamically linked libraries.
7994 Otherwise,
7995 it looks for a function <code>funcname</code> inside the library
7996 and returns this function as a C&nbsp;function.
7997 So, <code>funcname</code> must follow the <a href="#lua_CFunction"><code>lua_CFunction</code></a> prototype
7998 (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>).
7999
8000
8001 <p>
8002 This is a low-level function.
8003 It completely bypasses the package and module system.
8004 Unlike <a href="#pdf-require"><code>require</code></a>,
8005 it does not perform any path searching and
8006 does not automatically adds extensions.
8007 <code>libname</code> must be the complete file name of the C&nbsp;library,
8008 including if necessary a path and an extension.
8009 <code>funcname</code> must be the exact name exported by the C&nbsp;library
8010 (which may depend on the C&nbsp;compiler and linker used).
8011
8012
8013 <p>
8014 This function is not supported by Standard&nbsp;C.
8015 As such, it is only available on some platforms
8016 (Windows, Linux, Mac OS X, Solaris, BSD,
8017 plus other Unix systems that support the <code>dlfcn</code> standard).
8018
8019
8020
8021
8022 <p>
8023 <hr><h3><a name="pdf-package.path"><code>package.path</code></a></h3>
8024
8025
8026 <p>
8027 The path used by <a href="#pdf-require"><code>require</code></a> to search for a Lua loader.
8028
8029
8030 <p>
8031 At start-up, Lua initializes this variable with
8032 the value of the environment variable <a name="pdf-LUA_PATH_5_3"><code>LUA_PATH_5_3</code></a> or
8033 the environment variable <a name="pdf-LUA_PATH"><code>LUA_PATH</code></a> or
8034 with a default path defined in <code>luaconf.h</code>,
8035 if those environment variables are not defined.
8036 Any "<code>;;</code>" in the value of the environment variable
8037 is replaced by the default path.
8038
8039
8040
8041
8042 <p>
8043 <hr><h3><a name="pdf-package.preload"><code>package.preload</code></a></h3>
8044
8045
8046 <p>
8047 A table to store loaders for specific modules
8048 (see <a href="#pdf-require"><code>require</code></a>).
8049
8050
8051 <p>
8052 This variable is only a reference to the real table;
8053 assignments to this variable do not change the
8054 table used by <a href="#pdf-require"><code>require</code></a>.
8055
8056
8057
8058
8059 <p>
8060 <hr><h3><a name="pdf-package.searchers"><code>package.searchers</code></a></h3>
8061
8062
8063 <p>
8064 A table used by <a href="#pdf-require"><code>require</code></a> to control how to load modules.
8065
8066
8067 <p>
8068 Each entry in this table is a <em>searcher function</em>.
8069 When looking for a module,
8070 <a href="#pdf-require"><code>require</code></a> calls each of these searchers in ascending order,
8071 with the module name (the argument given to <a href="#pdf-require"><code>require</code></a>) as its
8072 sole parameter.
8073 The function can return another function (the module <em>loader</em>)
8074 plus an extra value that will be passed to that loader,
8075 or a string explaining why it did not find that module
8076 (or <b>nil</b> if it has nothing to say).
8077
8078
8079 <p>
8080 Lua initializes this table with four searcher functions.
8081
8082
8083 <p>
8084 The first searcher simply looks for a loader in the
8085 <a href="#pdf-package.preload"><code>package.preload</code></a> table.
8086
8087
8088 <p>
8089 The second searcher looks for a loader as a Lua library,
8090 using the path stored at <a href="#pdf-package.path"><code>package.path</code></a>.
8091 The search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>.
8092
8093
8094 <p>
8095 The third searcher looks for a loader as a C&nbsp;library,
8096 using the path given by the variable <a href="#pdf-package.cpath"><code>package.cpath</code></a>.
8097 Again,
8098 the search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>.
8099 For instance,
8100 if the C&nbsp;path is the string
8101
8102 <pre>
8103      "./?.so;./?.dll;/usr/local/?/init.so"
8104 </pre><p>
8105 the searcher for module <code>foo</code>
8106 will try to open the files <code>./foo.so</code>, <code>./foo.dll</code>,
8107 and <code>/usr/local/foo/init.so</code>, in that order.
8108 Once it finds a C&nbsp;library,
8109 this searcher first uses a dynamic link facility to link the
8110 application with the library.
8111 Then it tries to find a C&nbsp;function inside the library to
8112 be used as the loader.
8113 The name of this C&nbsp;function is the string "<code>luaopen_</code>"
8114 concatenated with a copy of the module name where each dot
8115 is replaced by an underscore.
8116 Moreover, if the module name has a hyphen,
8117 its suffix after (and including) the first hyphen is removed.
8118 For instance, if the module name is <code>a.b.c-v2.1</code>,
8119 the function name will be <code>luaopen_a_b_c</code>.
8120
8121
8122 <p>
8123 The fourth searcher tries an <em>all-in-one loader</em>.
8124 It searches the C&nbsp;path for a library for
8125 the root name of the given module.
8126 For instance, when requiring <code>a.b.c</code>,
8127 it will search for a C&nbsp;library for <code>a</code>.
8128 If found, it looks into it for an open function for
8129 the submodule;
8130 in our example, that would be <code>luaopen_a_b_c</code>.
8131 With this facility, a package can pack several C&nbsp;submodules
8132 into one single library,
8133 with each submodule keeping its original open function.
8134
8135
8136 <p>
8137 All searchers except the first one (preload) return as the extra value
8138 the file name where the module was found,
8139 as returned by <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>.
8140 The first searcher returns no extra value.
8141
8142
8143
8144
8145 <p>
8146 <hr><h3><a name="pdf-package.searchpath"><code>package.searchpath (name, path [, sep [, rep]])</code></a></h3>
8147
8148
8149 <p>
8150 Searches for the given <code>name</code> in the given <code>path</code>.
8151
8152
8153 <p>
8154 A path is a string containing a sequence of
8155 <em>templates</em> separated by semicolons.
8156 For each template,
8157 the function replaces each interrogation mark (if any)
8158 in the template with a copy of <code>name</code>
8159 wherein all occurrences of <code>sep</code>
8160 (a dot, by default)
8161 were replaced by <code>rep</code>
8162 (the system's directory separator, by default),
8163 and then tries to open the resulting file name.
8164
8165
8166 <p>
8167 For instance, if the path is the string
8168
8169 <pre>
8170      "./?.lua;./?.lc;/usr/local/?/init.lua"
8171 </pre><p>
8172 the search for the name <code>foo.a</code>
8173 will try to open the files
8174 <code>./foo/a.lua</code>, <code>./foo/a.lc</code>, and
8175 <code>/usr/local/foo/a/init.lua</code>, in that order.
8176
8177
8178 <p>
8179 Returns the resulting name of the first file that it can
8180 open in read mode (after closing the file),
8181 or <b>nil</b> plus an error message if none succeeds.
8182 (This error message lists all file names it tried to open.)
8183
8184
8185
8186
8187
8188
8189
8190 <h2>6.4 &ndash; <a name="6.4">String Manipulation</a></h2>
8191
8192 <p>
8193 This library provides generic functions for string manipulation,
8194 such as finding and extracting substrings, and pattern matching.
8195 When indexing a string in Lua, the first character is at position&nbsp;1
8196 (not at&nbsp;0, as in C).
8197 Indices are allowed to be negative and are interpreted as indexing backwards,
8198 from the end of the string.
8199 Thus, the last character is at position -1, and so on.
8200
8201
8202 <p>
8203 The string library provides all its functions inside the table
8204 <a name="pdf-string"><code>string</code></a>.
8205 It also sets a metatable for strings
8206 where the <code>__index</code> field points to the <code>string</code> table.
8207 Therefore, you can use the string functions in object-oriented style.
8208 For instance, <code>string.byte(s,i)</code>
8209 can be written as <code>s:byte(i)</code>.
8210
8211
8212 <p>
8213 The string library assumes one-byte character encodings.
8214
8215
8216 <p>
8217 <hr><h3><a name="pdf-string.byte"><code>string.byte (s [, i [, j]])</code></a></h3>
8218 Returns the internal numeric codes of the characters <code>s[i]</code>,
8219 <code>s[i+1]</code>, ..., <code>s[j]</code>.
8220 The default value for <code>i</code> is&nbsp;1;
8221 the default value for <code>j</code> is&nbsp;<code>i</code>.
8222 These indices are corrected
8223 following the same rules of function <a href="#pdf-string.sub"><code>string.sub</code></a>.
8224
8225
8226 <p>
8227 Numeric codes are not necessarily portable across platforms.
8228
8229
8230
8231
8232 <p>
8233 <hr><h3><a name="pdf-string.char"><code>string.char (&middot;&middot;&middot;)</code></a></h3>
8234 Receives zero or more integers.
8235 Returns a string with length equal to the number of arguments,
8236 in which each character has the internal numeric code equal
8237 to its corresponding argument.
8238
8239
8240 <p>
8241 Numeric codes are not necessarily portable across platforms.
8242
8243
8244
8245
8246 <p>
8247 <hr><h3><a name="pdf-string.dump"><code>string.dump (function [, strip])</code></a></h3>
8248
8249
8250 <p>
8251 Returns a string containing a binary representation
8252 (a <em>binary chunk</em>)
8253 of the given function,
8254 so that a later <a href="#pdf-load"><code>load</code></a> on this string returns
8255 a copy of the function (but with new upvalues).
8256 If <code>strip</code> is a true value,
8257 the binary representation may not include all debug information
8258 about the function,
8259 to save space.
8260
8261
8262 <p>
8263 Functions with upvalues have only their number of upvalues saved.
8264 When (re)loaded,
8265 those upvalues receive fresh instances containing <b>nil</b>.
8266 (You can use the debug library to serialize
8267 and reload the upvalues of a function
8268 in a way adequate to your needs.)
8269
8270
8271
8272
8273 <p>
8274 <hr><h3><a name="pdf-string.find"><code>string.find (s, pattern [, init [, plain]])</code></a></h3>
8275
8276
8277 <p>
8278 Looks for the first match of
8279 <code>pattern</code> (see <a href="#6.4.1">&sect;6.4.1</a>) in the string <code>s</code>.
8280 If it finds a match, then <code>find</code> returns the indices of&nbsp;<code>s</code>
8281 where this occurrence starts and ends;
8282 otherwise, it returns <b>nil</b>.
8283 A third, optional numeric argument <code>init</code> specifies
8284 where to start the search;
8285 its default value is&nbsp;1 and can be negative.
8286 A value of <b>true</b> as a fourth, optional argument <code>plain</code>
8287 turns off the pattern matching facilities,
8288 so the function does a plain "find substring" operation,
8289 with no characters in <code>pattern</code> being considered magic.
8290 Note that if <code>plain</code> is given, then <code>init</code> must be given as well.
8291
8292
8293 <p>
8294 If the pattern has captures,
8295 then in a successful match
8296 the captured values are also returned,
8297 after the two indices.
8298
8299
8300
8301
8302 <p>
8303 <hr><h3><a name="pdf-string.format"><code>string.format (formatstring, &middot;&middot;&middot;)</code></a></h3>
8304
8305
8306 <p>
8307 Returns a formatted version of its variable number of arguments
8308 following the description given in its first argument (which must be a string).
8309 The format string follows the same rules as the ISO&nbsp;C function <code>sprintf</code>.
8310 The only differences are that the options/modifiers
8311 <code>*</code>, <code>h</code>, <code>L</code>, <code>l</code>, <code>n</code>,
8312 and <code>p</code> are not supported
8313 and that there is an extra option, <code>q</code>.
8314
8315
8316 <p>
8317 The <code>q</code> option formats a string between double quotes,
8318 using escape sequences when necessary to ensure that
8319 it can safely be read back by the Lua interpreter.
8320 For instance, the call
8321
8322 <pre>
8323      string.format('%q', 'a string with "quotes" and \n new line')
8324 </pre><p>
8325 may produce the string:
8326
8327 <pre>
8328      "a string with \"quotes\" and \
8329       new line"
8330 </pre>
8331
8332 <p>
8333 Options
8334 <code>A</code>, <code>a</code>, <code>E</code>, <code>e</code>, <code>f</code>,
8335 <code>G</code>, and <code>g</code> all expect a number as argument.
8336 Options <code>c</code>, <code>d</code>,
8337 <code>i</code>, <code>o</code>, <code>u</code>, <code>X</code>, and <code>x</code>
8338 expect an integer.
8339 When Lua is compiled with a C89 compiler,
8340 options <code>A</code> and <code>a</code> (hexadecimal floats)
8341 do not support any modifier (flags, width, length).
8342
8343
8344 <p>
8345 Option <code>s</code> expects a string;
8346 if its argument is not a string,
8347 it is converted to one following the same rules of <a href="#pdf-tostring"><code>tostring</code></a>.
8348 If the option has any modifier (flags, width, length),
8349 the string argument should not contain embedded zeros.
8350
8351
8352
8353
8354 <p>
8355 <hr><h3><a name="pdf-string.gmatch"><code>string.gmatch (s, pattern)</code></a></h3>
8356 Returns an iterator function that,
8357 each time it is called,
8358 returns the next captures from <code>pattern</code> (see <a href="#6.4.1">&sect;6.4.1</a>)
8359 over the string <code>s</code>.
8360 If <code>pattern</code> specifies no captures,
8361 then the whole match is produced in each call.
8362
8363
8364 <p>
8365 As an example, the following loop
8366 will iterate over all the words from string <code>s</code>,
8367 printing one per line:
8368
8369 <pre>
8370      s = "hello world from Lua"
8371      for w in string.gmatch(s, "%a+") do
8372        print(w)
8373      end
8374 </pre><p>
8375 The next example collects all pairs <code>key=value</code> from the
8376 given string into a table:
8377
8378 <pre>
8379      t = {}
8380      s = "from=world, to=Lua"
8381      for k, v in string.gmatch(s, "(%w+)=(%w+)") do
8382        t[k] = v
8383      end
8384 </pre>
8385
8386 <p>
8387 For this function, a caret '<code>^</code>' at the start of a pattern does not
8388 work as an anchor, as this would prevent the iteration.
8389
8390
8391
8392
8393 <p>
8394 <hr><h3><a name="pdf-string.gsub"><code>string.gsub (s, pattern, repl [, n])</code></a></h3>
8395 Returns a copy of <code>s</code>
8396 in which all (or the first <code>n</code>, if given)
8397 occurrences of the <code>pattern</code> (see <a href="#6.4.1">&sect;6.4.1</a>) have been
8398 replaced by a replacement string specified by <code>repl</code>,
8399 which can be a string, a table, or a function.
8400 <code>gsub</code> also returns, as its second value,
8401 the total number of matches that occurred.
8402 The name <code>gsub</code> comes from <em>Global SUBstitution</em>.
8403
8404
8405 <p>
8406 If <code>repl</code> is a string, then its value is used for replacement.
8407 The character&nbsp;<code>%</code> works as an escape character:
8408 any sequence in <code>repl</code> of the form <code>%<em>d</em></code>,
8409 with <em>d</em> between 1 and 9,
8410 stands for the value of the <em>d</em>-th captured substring.
8411 The sequence <code>%0</code> stands for the whole match.
8412 The sequence <code>%%</code> stands for a single&nbsp;<code>%</code>.
8413
8414
8415 <p>
8416 If <code>repl</code> is a table, then the table is queried for every match,
8417 using the first capture as the key.
8418
8419
8420 <p>
8421 If <code>repl</code> is a function, then this function is called every time a
8422 match occurs, with all captured substrings passed as arguments,
8423 in order.
8424
8425
8426 <p>
8427 In any case,
8428 if the pattern specifies no captures,
8429 then it behaves as if the whole pattern was inside a capture.
8430
8431
8432 <p>
8433 If the value returned by the table query or by the function call
8434 is a string or a number,
8435 then it is used as the replacement string;
8436 otherwise, if it is <b>false</b> or <b>nil</b>,
8437 then there is no replacement
8438 (that is, the original match is kept in the string).
8439
8440
8441 <p>
8442 Here are some examples:
8443
8444 <pre>
8445      x = string.gsub("hello world", "(%w+)", "%1 %1")
8446      --&gt; x="hello hello world world"
8447
8448      x = string.gsub("hello world", "%w+", "%0 %0", 1)
8449      --&gt; x="hello hello world"
8450
8451      x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1")
8452      --&gt; x="world hello Lua from"
8453
8454      x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv)
8455      --&gt; x="home = /home/roberto, user = roberto"
8456
8457      x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s)
8458            return load(s)()
8459          end)
8460      --&gt; x="4+5 = 9"
8461
8462      local t = {name="lua", version="5.3"}
8463      x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t)
8464      --&gt; x="lua-5.3.tar.gz"
8465 </pre>
8466
8467
8468
8469 <p>
8470 <hr><h3><a name="pdf-string.len"><code>string.len (s)</code></a></h3>
8471 Receives a string and returns its length.
8472 The empty string <code>""</code> has length 0.
8473 Embedded zeros are counted,
8474 so <code>"a\000bc\000"</code> has length 5.
8475
8476
8477
8478
8479 <p>
8480 <hr><h3><a name="pdf-string.lower"><code>string.lower (s)</code></a></h3>
8481 Receives a string and returns a copy of this string with all
8482 uppercase letters changed to lowercase.
8483 All other characters are left unchanged.
8484 The definition of what an uppercase letter is depends on the current locale.
8485
8486
8487
8488
8489 <p>
8490 <hr><h3><a name="pdf-string.match"><code>string.match (s, pattern [, init])</code></a></h3>
8491 Looks for the first <em>match</em> of
8492 <code>pattern</code> (see <a href="#6.4.1">&sect;6.4.1</a>) in the string <code>s</code>.
8493 If it finds one, then <code>match</code> returns
8494 the captures from the pattern;
8495 otherwise it returns <b>nil</b>.
8496 If <code>pattern</code> specifies no captures,
8497 then the whole match is returned.
8498 A third, optional numeric argument <code>init</code> specifies
8499 where to start the search;
8500 its default value is&nbsp;1 and can be negative.
8501
8502
8503
8504
8505 <p>
8506 <hr><h3><a name="pdf-string.pack"><code>string.pack (fmt, v1, v2, &middot;&middot;&middot;)</code></a></h3>
8507
8508
8509 <p>
8510 Returns a binary string containing the values <code>v1</code>, <code>v2</code>, etc.
8511 packed (that is, serialized in binary form)
8512 according to the format string <code>fmt</code> (see <a href="#6.4.2">&sect;6.4.2</a>).
8513
8514
8515
8516
8517 <p>
8518 <hr><h3><a name="pdf-string.packsize"><code>string.packsize (fmt)</code></a></h3>
8519
8520
8521 <p>
8522 Returns the size of a string resulting from <a href="#pdf-string.pack"><code>string.pack</code></a>
8523 with the given format.
8524 The format string cannot have the variable-length options
8525 '<code>s</code>' or '<code>z</code>' (see <a href="#6.4.2">&sect;6.4.2</a>).
8526
8527
8528
8529
8530 <p>
8531 <hr><h3><a name="pdf-string.rep"><code>string.rep (s, n [, sep])</code></a></h3>
8532 Returns a string that is the concatenation of <code>n</code> copies of
8533 the string <code>s</code> separated by the string <code>sep</code>.
8534 The default value for <code>sep</code> is the empty string
8535 (that is, no separator).
8536 Returns the empty string if <code>n</code> is not positive.
8537
8538
8539 <p>
8540 (Note that it is very easy to exhaust the memory of your machine
8541 with a single call to this function.)
8542
8543
8544
8545
8546 <p>
8547 <hr><h3><a name="pdf-string.reverse"><code>string.reverse (s)</code></a></h3>
8548 Returns a string that is the string <code>s</code> reversed.
8549
8550
8551
8552
8553 <p>
8554 <hr><h3><a name="pdf-string.sub"><code>string.sub (s, i [, j])</code></a></h3>
8555 Returns the substring of <code>s</code> that
8556 starts at <code>i</code>  and continues until <code>j</code>;
8557 <code>i</code> and <code>j</code> can be negative.
8558 If <code>j</code> is absent, then it is assumed to be equal to -1
8559 (which is the same as the string length).
8560 In particular,
8561 the call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code>
8562 with length <code>j</code>,
8563 and <code>string.sub(s, -i)</code> (for a positive <code>i</code>)
8564 returns a suffix of <code>s</code>
8565 with length <code>i</code>.
8566
8567
8568 <p>
8569 If, after the translation of negative indices,
8570 <code>i</code> is less than 1,
8571 it is corrected to 1.
8572 If <code>j</code> is greater than the string length,
8573 it is corrected to that length.
8574 If, after these corrections,
8575 <code>i</code> is greater than <code>j</code>,
8576 the function returns the empty string.
8577
8578
8579
8580
8581 <p>
8582 <hr><h3><a name="pdf-string.unpack"><code>string.unpack (fmt, s [, pos])</code></a></h3>
8583
8584
8585 <p>
8586 Returns the values packed in string <code>s</code> (see <a href="#pdf-string.pack"><code>string.pack</code></a>)
8587 according to the format string <code>fmt</code> (see <a href="#6.4.2">&sect;6.4.2</a>).
8588 An optional <code>pos</code> marks where
8589 to start reading in <code>s</code> (default is 1).
8590 After the read values,
8591 this function also returns the index of the first unread byte in <code>s</code>.
8592
8593
8594
8595
8596 <p>
8597 <hr><h3><a name="pdf-string.upper"><code>string.upper (s)</code></a></h3>
8598 Receives a string and returns a copy of this string with all
8599 lowercase letters changed to uppercase.
8600 All other characters are left unchanged.
8601 The definition of what a lowercase letter is depends on the current locale.
8602
8603
8604
8605
8606
8607 <h3>6.4.1 &ndash; <a name="6.4.1">Patterns</a></h3>
8608
8609 <p>
8610 Patterns in Lua are described by regular strings,
8611 which are interpreted as patterns by the pattern-matching functions
8612 <a href="#pdf-string.find"><code>string.find</code></a>,
8613 <a href="#pdf-string.gmatch"><code>string.gmatch</code></a>,
8614 <a href="#pdf-string.gsub"><code>string.gsub</code></a>,
8615 and <a href="#pdf-string.match"><code>string.match</code></a>.
8616 This section describes the syntax and the meaning
8617 (that is, what they match) of these strings.
8618
8619
8620
8621 <h4>Character Class:</h4><p>
8622 A <em>character class</em> is used to represent a set of characters.
8623 The following combinations are allowed in describing a character class:
8624
8625 <ul>
8626
8627 <li><b><em>x</em>: </b>
8628 (where <em>x</em> is not one of the <em>magic characters</em>
8629 <code>^$()%.[]*+-?</code>)
8630 represents the character <em>x</em> itself.
8631 </li>
8632
8633 <li><b><code>.</code>: </b> (a dot) represents all characters.</li>
8634
8635 <li><b><code>%a</code>: </b> represents all letters.</li>
8636
8637 <li><b><code>%c</code>: </b> represents all control characters.</li>
8638
8639 <li><b><code>%d</code>: </b> represents all digits.</li>
8640
8641 <li><b><code>%g</code>: </b> represents all printable characters except space.</li>
8642
8643 <li><b><code>%l</code>: </b> represents all lowercase letters.</li>
8644
8645 <li><b><code>%p</code>: </b> represents all punctuation characters.</li>
8646
8647 <li><b><code>%s</code>: </b> represents all space characters.</li>
8648
8649 <li><b><code>%u</code>: </b> represents all uppercase letters.</li>
8650
8651 <li><b><code>%w</code>: </b> represents all alphanumeric characters.</li>
8652
8653 <li><b><code>%x</code>: </b> represents all hexadecimal digits.</li>
8654
8655 <li><b><code>%<em>x</em></code>: </b> (where <em>x</em> is any non-alphanumeric character)
8656 represents the character <em>x</em>.
8657 This is the standard way to escape the magic characters.
8658 Any non-alphanumeric character
8659 (including all punctuation characters, even the non-magical)
8660 can be preceded by a '<code>%</code>'
8661 when used to represent itself in a pattern.
8662 </li>
8663
8664 <li><b><code>[<em>set</em>]</code>: </b>
8665 represents the class which is the union of all
8666 characters in <em>set</em>.
8667 A range of characters can be specified by
8668 separating the end characters of the range,
8669 in ascending order, with a '<code>-</code>'.
8670 All classes <code>%</code><em>x</em> described above can also be used as
8671 components in <em>set</em>.
8672 All other characters in <em>set</em> represent themselves.
8673 For example, <code>[%w_]</code> (or <code>[_%w]</code>)
8674 represents all alphanumeric characters plus the underscore,
8675 <code>[0-7]</code> represents the octal digits,
8676 and <code>[0-7%l%-]</code> represents the octal digits plus
8677 the lowercase letters plus the '<code>-</code>' character.
8678
8679
8680 <p>
8681 You can put a closing square bracket in a set
8682 by positioning it as the first character in the set.
8683 You can put an hyphen in a set
8684 by positioning it as the first or the last character in the set.
8685 (You can also use an escape for both cases.)
8686
8687
8688 <p>
8689 The interaction between ranges and classes is not defined.
8690 Therefore, patterns like <code>[%a-z]</code> or <code>[a-%%]</code>
8691 have no meaning.
8692 </li>
8693
8694 <li><b><code>[^<em>set</em>]</code>: </b>
8695 represents the complement of <em>set</em>,
8696 where <em>set</em> is interpreted as above.
8697 </li>
8698
8699 </ul><p>
8700 For all classes represented by single letters (<code>%a</code>, <code>%c</code>, etc.),
8701 the corresponding uppercase letter represents the complement of the class.
8702 For instance, <code>%S</code> represents all non-space characters.
8703
8704
8705 <p>
8706 The definitions of letter, space, and other character groups
8707 depend on the current locale.
8708 In particular, the class <code>[a-z]</code> may not be equivalent to <code>%l</code>.
8709
8710
8711
8712
8713
8714 <h4>Pattern Item:</h4><p>
8715 A <em>pattern item</em> can be
8716
8717 <ul>
8718
8719 <li>
8720 a single character class,
8721 which matches any single character in the class;
8722 </li>
8723
8724 <li>
8725 a single character class followed by '<code>*</code>',
8726 which matches zero or more repetitions of characters in the class.
8727 These repetition items will always match the longest possible sequence;
8728 </li>
8729
8730 <li>
8731 a single character class followed by '<code>+</code>',
8732 which matches one or more repetitions of characters in the class.
8733 These repetition items will always match the longest possible sequence;
8734 </li>
8735
8736 <li>
8737 a single character class followed by '<code>-</code>',
8738 which also matches zero or more repetitions of characters in the class.
8739 Unlike '<code>*</code>',
8740 these repetition items will always match the shortest possible sequence;
8741 </li>
8742
8743 <li>
8744 a single character class followed by '<code>?</code>',
8745 which matches zero or one occurrence of a character in the class.
8746 It always matches one occurrence if possible;
8747 </li>
8748
8749 <li>
8750 <code>%<em>n</em></code>, for <em>n</em> between 1 and 9;
8751 such item matches a substring equal to the <em>n</em>-th captured string
8752 (see below);
8753 </li>
8754
8755 <li>
8756 <code>%b<em>xy</em></code>, where <em>x</em> and <em>y</em> are two distinct characters;
8757 such item matches strings that start with&nbsp;<em>x</em>, end with&nbsp;<em>y</em>,
8758 and where the <em>x</em> and <em>y</em> are <em>balanced</em>.
8759 This means that, if one reads the string from left to right,
8760 counting <em>+1</em> for an <em>x</em> and <em>-1</em> for a <em>y</em>,
8761 the ending <em>y</em> is the first <em>y</em> where the count reaches 0.
8762 For instance, the item <code>%b()</code> matches expressions with
8763 balanced parentheses.
8764 </li>
8765
8766 <li>
8767 <code>%f[<em>set</em>]</code>, a <em>frontier pattern</em>;
8768 such item matches an empty string at any position such that
8769 the next character belongs to <em>set</em>
8770 and the previous character does not belong to <em>set</em>.
8771 The set <em>set</em> is interpreted as previously described.
8772 The beginning and the end of the subject are handled as if
8773 they were the character '<code>\0</code>'.
8774 </li>
8775
8776 </ul>
8777
8778
8779
8780
8781 <h4>Pattern:</h4><p>
8782 A <em>pattern</em> is a sequence of pattern items.
8783 A caret '<code>^</code>' at the beginning of a pattern anchors the match at the
8784 beginning of the subject string.
8785 A '<code>$</code>' at the end of a pattern anchors the match at the
8786 end of the subject string.
8787 At other positions,
8788 '<code>^</code>' and '<code>$</code>' have no special meaning and represent themselves.
8789
8790
8791
8792
8793
8794 <h4>Captures:</h4><p>
8795 A pattern can contain sub-patterns enclosed in parentheses;
8796 they describe <em>captures</em>.
8797 When a match succeeds, the substrings of the subject string
8798 that match captures are stored (<em>captured</em>) for future use.
8799 Captures are numbered according to their left parentheses.
8800 For instance, in the pattern <code>"(a*(.)%w(%s*))"</code>,
8801 the part of the string matching <code>"a*(.)%w(%s*)"</code> is
8802 stored as the first capture (and therefore has number&nbsp;1);
8803 the character matching "<code>.</code>" is captured with number&nbsp;2,
8804 and the part matching "<code>%s*</code>" has number&nbsp;3.
8805
8806
8807 <p>
8808 As a special case, the empty capture <code>()</code> captures
8809 the current string position (a number).
8810 For instance, if we apply the pattern <code>"()aa()"</code> on the
8811 string <code>"flaaap"</code>, there will be two captures: 3&nbsp;and&nbsp;5.
8812
8813
8814
8815
8816
8817
8818
8819 <h3>6.4.2 &ndash; <a name="6.4.2">Format Strings for Pack and Unpack</a></h3>
8820
8821 <p>
8822 The first argument to <a href="#pdf-string.pack"><code>string.pack</code></a>,
8823 <a href="#pdf-string.packsize"><code>string.packsize</code></a>, and <a href="#pdf-string.unpack"><code>string.unpack</code></a>
8824 is a format string,
8825 which describes the layout of the structure being created or read.
8826
8827
8828 <p>
8829 A format string is a sequence of conversion options.
8830 The conversion options are as follows:
8831
8832 <ul>
8833 <li><b><code>&lt;</code>: </b>sets little endian</li>
8834 <li><b><code>&gt;</code>: </b>sets big endian</li>
8835 <li><b><code>=</code>: </b>sets native endian</li>
8836 <li><b><code>![<em>n</em>]</code>: </b>sets maximum alignment to <code>n</code>
8837 (default is native alignment)</li>
8838 <li><b><code>b</code>: </b>a signed byte (<code>char</code>)</li>
8839 <li><b><code>B</code>: </b>an unsigned byte (<code>char</code>)</li>
8840 <li><b><code>h</code>: </b>a signed <code>short</code> (native size)</li>
8841 <li><b><code>H</code>: </b>an unsigned <code>short</code> (native size)</li>
8842 <li><b><code>l</code>: </b>a signed <code>long</code> (native size)</li>
8843 <li><b><code>L</code>: </b>an unsigned <code>long</code> (native size)</li>
8844 <li><b><code>j</code>: </b>a <code>lua_Integer</code></li>
8845 <li><b><code>J</code>: </b>a <code>lua_Unsigned</code></li>
8846 <li><b><code>T</code>: </b>a <code>size_t</code> (native size)</li>
8847 <li><b><code>i[<em>n</em>]</code>: </b>a signed <code>int</code> with <code>n</code> bytes
8848 (default is native size)</li>
8849 <li><b><code>I[<em>n</em>]</code>: </b>an unsigned <code>int</code> with <code>n</code> bytes
8850 (default is native size)</li>
8851 <li><b><code>f</code>: </b>a <code>float</code> (native size)</li>
8852 <li><b><code>d</code>: </b>a <code>double</code> (native size)</li>
8853 <li><b><code>n</code>: </b>a <code>lua_Number</code></li>
8854 <li><b><code>c<em>n</em></code>: </b>a fixed-sized string with <code>n</code> bytes</li>
8855 <li><b><code>z</code>: </b>a zero-terminated string</li>
8856 <li><b><code>s[<em>n</em>]</code>: </b>a string preceded by its length
8857 coded as an unsigned integer with <code>n</code> bytes
8858 (default is a <code>size_t</code>)</li>
8859 <li><b><code>x</code>: </b>one byte of padding</li>
8860 <li><b><code>X<em>op</em></code>: </b>an empty item that aligns
8861 according to option <code>op</code>
8862 (which is otherwise ignored)</li>
8863 <li><b>'<code> </code>': </b>(empty space) ignored</li>
8864 </ul><p>
8865 (A "<code>[<em>n</em>]</code>" means an optional integral numeral.)
8866 Except for padding, spaces, and configurations
8867 (options "<code>xX &lt;=&gt;!</code>"),
8868 each option corresponds to an argument (in <a href="#pdf-string.pack"><code>string.pack</code></a>)
8869 or a result (in <a href="#pdf-string.unpack"><code>string.unpack</code></a>).
8870
8871
8872 <p>
8873 For options "<code>!<em>n</em></code>", "<code>s<em>n</em></code>", "<code>i<em>n</em></code>", and "<code>I<em>n</em></code>",
8874 <code>n</code> can be any integer between 1 and 16.
8875 All integral options check overflows;
8876 <a href="#pdf-string.pack"><code>string.pack</code></a> checks whether the given value fits in the given size;
8877 <a href="#pdf-string.unpack"><code>string.unpack</code></a> checks whether the read value fits in a Lua integer.
8878
8879
8880 <p>
8881 Any format string starts as if prefixed by "<code>!1=</code>",
8882 that is,
8883 with maximum alignment of 1 (no alignment)
8884 and native endianness.
8885
8886
8887 <p>
8888 Alignment works as follows:
8889 For each option,
8890 the format gets extra padding until the data starts
8891 at an offset that is a multiple of the minimum between the
8892 option size and the maximum alignment;
8893 this minimum must be a power of 2.
8894 Options "<code>c</code>" and "<code>z</code>" are not aligned;
8895 option "<code>s</code>" follows the alignment of its starting integer.
8896
8897
8898 <p>
8899 All padding is filled with zeros by <a href="#pdf-string.pack"><code>string.pack</code></a>
8900 (and ignored by <a href="#pdf-string.unpack"><code>string.unpack</code></a>).
8901
8902
8903
8904
8905
8906
8907
8908 <h2>6.5 &ndash; <a name="6.5">UTF-8 Support</a></h2>
8909
8910 <p>
8911 This library provides basic support for UTF-8 encoding.
8912 It provides all its functions inside the table <a name="pdf-utf8"><code>utf8</code></a>.
8913 This library does not provide any support for Unicode other
8914 than the handling of the encoding.
8915 Any operation that needs the meaning of a character,
8916 such as character classification, is outside its scope.
8917
8918
8919 <p>
8920 Unless stated otherwise,
8921 all functions that expect a byte position as a parameter
8922 assume that the given position is either the start of a byte sequence
8923 or one plus the length of the subject string.
8924 As in the string library,
8925 negative indices count from the end of the string.
8926
8927
8928 <p>
8929 <hr><h3><a name="pdf-utf8.char"><code>utf8.char (&middot;&middot;&middot;)</code></a></h3>
8930 Receives zero or more integers,
8931 converts each one to its corresponding UTF-8 byte sequence
8932 and returns a string with the concatenation of all these sequences.
8933
8934
8935
8936
8937 <p>
8938 <hr><h3><a name="pdf-utf8.charpattern"><code>utf8.charpattern</code></a></h3>
8939 The pattern (a string, not a function) "<code>[\0-\x7F\xC2-\xF4][\x80-\xBF]*</code>"
8940 (see <a href="#6.4.1">&sect;6.4.1</a>),
8941 which matches exactly one UTF-8 byte sequence,
8942 assuming that the subject is a valid UTF-8 string.
8943
8944
8945
8946
8947 <p>
8948 <hr><h3><a name="pdf-utf8.codes"><code>utf8.codes (s)</code></a></h3>
8949
8950
8951 <p>
8952 Returns values so that the construction
8953
8954 <pre>
8955      for p, c in utf8.codes(s) do <em>body</em> end
8956 </pre><p>
8957 will iterate over all characters in string <code>s</code>,
8958 with <code>p</code> being the position (in bytes) and <code>c</code> the code point
8959 of each character.
8960 It raises an error if it meets any invalid byte sequence.
8961
8962
8963
8964
8965 <p>
8966 <hr><h3><a name="pdf-utf8.codepoint"><code>utf8.codepoint (s [, i [, j]])</code></a></h3>
8967 Returns the codepoints (as integers) from all characters in <code>s</code>
8968 that start between byte position <code>i</code> and <code>j</code> (both included).
8969 The default for <code>i</code> is 1 and for <code>j</code> is <code>i</code>.
8970 It raises an error if it meets any invalid byte sequence.
8971
8972
8973
8974
8975 <p>
8976 <hr><h3><a name="pdf-utf8.len"><code>utf8.len (s [, i [, j]])</code></a></h3>
8977 Returns the number of UTF-8 characters in string <code>s</code>
8978 that start between positions <code>i</code> and <code>j</code> (both inclusive).
8979 The default for <code>i</code> is 1 and for <code>j</code> is -1.
8980 If it finds any invalid byte sequence,
8981 returns a false value plus the position of the first invalid byte.
8982
8983
8984
8985
8986 <p>
8987 <hr><h3><a name="pdf-utf8.offset"><code>utf8.offset (s, n [, i])</code></a></h3>
8988 Returns the position (in bytes) where the encoding of the
8989 <code>n</code>-th character of <code>s</code>
8990 (counting from position <code>i</code>) starts.
8991 A negative <code>n</code> gets characters before position <code>i</code>.
8992 The default for <code>i</code> is 1 when <code>n</code> is non-negative
8993 and <code>#s + 1</code> otherwise,
8994 so that <code>utf8.offset(s, -n)</code> gets the offset of the
8995 <code>n</code>-th character from the end of the string.
8996 If the specified character is neither in the subject
8997 nor right after its end,
8998 the function returns <b>nil</b>.
8999
9000
9001 <p>
9002 As a special case,
9003 when <code>n</code> is 0 the function returns the start of the encoding
9004 of the character that contains the <code>i</code>-th byte of <code>s</code>.
9005
9006
9007 <p>
9008 This function assumes that <code>s</code> is a valid UTF-8 string.
9009
9010
9011
9012
9013
9014
9015
9016 <h2>6.6 &ndash; <a name="6.6">Table Manipulation</a></h2>
9017
9018 <p>
9019 This library provides generic functions for table manipulation.
9020 It provides all its functions inside the table <a name="pdf-table"><code>table</code></a>.
9021
9022
9023 <p>
9024 Remember that, whenever an operation needs the length of a table,
9025 all caveats about the length operator apply (see <a href="#3.4.7">&sect;3.4.7</a>).
9026 All functions ignore non-numeric keys
9027 in the tables given as arguments.
9028
9029
9030 <p>
9031 <hr><h3><a name="pdf-table.concat"><code>table.concat (list [, sep [, i [, j]]])</code></a></h3>
9032
9033
9034 <p>
9035 Given a list where all elements are strings or numbers,
9036 returns the string <code>list[i]..sep..list[i+1] &middot;&middot;&middot; sep..list[j]</code>.
9037 The default value for <code>sep</code> is the empty string,
9038 the default for <code>i</code> is 1,
9039 and the default for <code>j</code> is <code>#list</code>.
9040 If <code>i</code> is greater than <code>j</code>, returns the empty string.
9041
9042
9043
9044
9045 <p>
9046 <hr><h3><a name="pdf-table.insert"><code>table.insert (list, [pos,] value)</code></a></h3>
9047
9048
9049 <p>
9050 Inserts element <code>value</code> at position <code>pos</code> in <code>list</code>,
9051 shifting up the elements
9052 <code>list[pos], list[pos+1], &middot;&middot;&middot;, list[#list]</code>.
9053 The default value for <code>pos</code> is <code>#list+1</code>,
9054 so that a call <code>table.insert(t,x)</code> inserts <code>x</code> at the end
9055 of list <code>t</code>.
9056
9057
9058
9059
9060 <p>
9061 <hr><h3><a name="pdf-table.move"><code>table.move (a1, f, e, t [,a2])</code></a></h3>
9062
9063
9064 <p>
9065 Moves elements from table <code>a1</code> to table <code>a2</code>,
9066 performing the equivalent to the following
9067 multiple assignment:
9068 <code>a2[t],&middot;&middot;&middot; = a1[f],&middot;&middot;&middot;,a1[e]</code>.
9069 The default for <code>a2</code> is <code>a1</code>.
9070 The destination range can overlap with the source range.
9071 The number of elements to be moved must fit in a Lua integer.
9072
9073
9074 <p>
9075 Returns the destination table <code>a2</code>.
9076
9077
9078
9079
9080 <p>
9081 <hr><h3><a name="pdf-table.pack"><code>table.pack (&middot;&middot;&middot;)</code></a></h3>
9082
9083
9084 <p>
9085 Returns a new table with all parameters stored into keys 1, 2, etc.
9086 and with a field "<code>n</code>" with the total number of parameters.
9087 Note that the resulting table may not be a sequence.
9088
9089
9090
9091
9092 <p>
9093 <hr><h3><a name="pdf-table.remove"><code>table.remove (list [, pos])</code></a></h3>
9094
9095
9096 <p>
9097 Removes from <code>list</code> the element at position <code>pos</code>,
9098 returning the value of the removed element.
9099 When <code>pos</code> is an integer between 1 and <code>#list</code>,
9100 it shifts down the elements
9101 <code>list[pos+1], list[pos+2], &middot;&middot;&middot;, list[#list]</code>
9102 and erases element <code>list[#list]</code>;
9103 The index <code>pos</code> can also be 0 when <code>#list</code> is 0,
9104 or <code>#list + 1</code>;
9105 in those cases, the function erases the element <code>list[pos]</code>.
9106
9107
9108 <p>
9109 The default value for <code>pos</code> is <code>#list</code>,
9110 so that a call <code>table.remove(l)</code> removes the last element
9111 of list <code>l</code>.
9112
9113
9114
9115
9116 <p>
9117 <hr><h3><a name="pdf-table.sort"><code>table.sort (list [, comp])</code></a></h3>
9118
9119
9120 <p>
9121 Sorts list elements in a given order, <em>in-place</em>,
9122 from <code>list[1]</code> to <code>list[#list]</code>.
9123 If <code>comp</code> is given,
9124 then it must be a function that receives two list elements
9125 and returns true when the first element must come
9126 before the second in the final order
9127 (so that, after the sort,
9128 <code>i &lt; j</code> implies <code>not comp(list[j],list[i])</code>).
9129 If <code>comp</code> is not given,
9130 then the standard Lua operator <code>&lt;</code> is used instead.
9131
9132
9133 <p>
9134 Note that the <code>comp</code> function must define
9135 a strict partial order over the elements in the list;
9136 that is, it must be asymmetric and transitive.
9137 Otherwise, no valid sort may be possible.
9138
9139
9140 <p>
9141 The sort algorithm is not stable:
9142 elements considered equal by the given order
9143 may have their relative positions changed by the sort.
9144
9145
9146
9147
9148 <p>
9149 <hr><h3><a name="pdf-table.unpack"><code>table.unpack (list [, i [, j]])</code></a></h3>
9150
9151
9152 <p>
9153 Returns the elements from the given list.
9154 This function is equivalent to
9155
9156 <pre>
9157      return list[i], list[i+1], &middot;&middot;&middot;, list[j]
9158 </pre><p>
9159 By default, <code>i</code> is&nbsp;1 and <code>j</code> is <code>#list</code>.
9160
9161
9162
9163
9164
9165
9166
9167 <h2>6.7 &ndash; <a name="6.7">Mathematical Functions</a></h2>
9168
9169 <p>
9170 This library provides basic mathematical functions.
9171 It provides all its functions and constants inside the table <a name="pdf-math"><code>math</code></a>.
9172 Functions with the annotation "<code>integer/float</code>" give
9173 integer results for integer arguments
9174 and float results for float (or mixed) arguments.
9175 Rounding functions
9176 (<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>)
9177 return an integer when the result fits in the range of an integer,
9178 or a float otherwise.
9179
9180
9181 <p>
9182 <hr><h3><a name="pdf-math.abs"><code>math.abs (x)</code></a></h3>
9183
9184
9185 <p>
9186 Returns the absolute value of <code>x</code>. (integer/float)
9187
9188
9189
9190
9191 <p>
9192 <hr><h3><a name="pdf-math.acos"><code>math.acos (x)</code></a></h3>
9193
9194
9195 <p>
9196 Returns the arc cosine of <code>x</code> (in radians).
9197
9198
9199
9200
9201 <p>
9202 <hr><h3><a name="pdf-math.asin"><code>math.asin (x)</code></a></h3>
9203
9204
9205 <p>
9206 Returns the arc sine of <code>x</code> (in radians).
9207
9208
9209
9210
9211 <p>
9212 <hr><h3><a name="pdf-math.atan"><code>math.atan (y [, x])</code></a></h3>
9213
9214
9215 <p>
9216
9217 Returns the arc tangent of <code>y/x</code> (in radians),
9218 but uses the signs of both parameters to find the
9219 quadrant of the result.
9220 (It also handles correctly the case of <code>x</code> being zero.)
9221
9222
9223 <p>
9224 The default value for <code>x</code> is 1,
9225 so that the call <code>math.atan(y)</code>
9226 returns the arc tangent of <code>y</code>.
9227
9228
9229
9230
9231 <p>
9232 <hr><h3><a name="pdf-math.ceil"><code>math.ceil (x)</code></a></h3>
9233
9234
9235 <p>
9236 Returns the smallest integral value larger than or equal to <code>x</code>.
9237
9238
9239
9240
9241 <p>
9242 <hr><h3><a name="pdf-math.cos"><code>math.cos (x)</code></a></h3>
9243
9244
9245 <p>
9246 Returns the cosine of <code>x</code> (assumed to be in radians).
9247
9248
9249
9250
9251 <p>
9252 <hr><h3><a name="pdf-math.deg"><code>math.deg (x)</code></a></h3>
9253
9254
9255 <p>
9256 Converts the angle <code>x</code> from radians to degrees.
9257
9258
9259
9260
9261 <p>
9262 <hr><h3><a name="pdf-math.exp"><code>math.exp (x)</code></a></h3>
9263
9264
9265 <p>
9266 Returns the value <em>e<sup>x</sup></em>
9267 (where <code>e</code> is the base of natural logarithms).
9268
9269
9270
9271
9272 <p>
9273 <hr><h3><a name="pdf-math.floor"><code>math.floor (x)</code></a></h3>
9274
9275
9276 <p>
9277 Returns the largest integral value smaller than or equal to <code>x</code>.
9278
9279
9280
9281
9282 <p>
9283 <hr><h3><a name="pdf-math.fmod"><code>math.fmod (x, y)</code></a></h3>
9284
9285
9286 <p>
9287 Returns the remainder of the division of <code>x</code> by <code>y</code>
9288 that rounds the quotient towards zero. (integer/float)
9289
9290
9291
9292
9293 <p>
9294 <hr><h3><a name="pdf-math.huge"><code>math.huge</code></a></h3>
9295
9296
9297 <p>
9298 The float value <code>HUGE_VAL</code>,
9299 a value larger than any other numeric value.
9300
9301
9302
9303
9304 <p>
9305 <hr><h3><a name="pdf-math.log"><code>math.log (x [, base])</code></a></h3>
9306
9307
9308 <p>
9309 Returns the logarithm of <code>x</code> in the given base.
9310 The default for <code>base</code> is <em>e</em>
9311 (so that the function returns the natural logarithm of <code>x</code>).
9312
9313
9314
9315
9316 <p>
9317 <hr><h3><a name="pdf-math.max"><code>math.max (x, &middot;&middot;&middot;)</code></a></h3>
9318
9319
9320 <p>
9321 Returns the argument with the maximum value,
9322 according to the Lua operator <code>&lt;</code>. (integer/float)
9323
9324
9325
9326
9327 <p>
9328 <hr><h3><a name="pdf-math.maxinteger"><code>math.maxinteger</code></a></h3>
9329 An integer with the maximum value for an integer.
9330
9331
9332
9333
9334 <p>
9335 <hr><h3><a name="pdf-math.min"><code>math.min (x, &middot;&middot;&middot;)</code></a></h3>
9336
9337
9338 <p>
9339 Returns the argument with the minimum value,
9340 according to the Lua operator <code>&lt;</code>. (integer/float)
9341
9342
9343
9344
9345 <p>
9346 <hr><h3><a name="pdf-math.mininteger"><code>math.mininteger</code></a></h3>
9347 An integer with the minimum value for an integer.
9348
9349
9350
9351
9352 <p>
9353 <hr><h3><a name="pdf-math.modf"><code>math.modf (x)</code></a></h3>
9354
9355
9356 <p>
9357 Returns the integral part of <code>x</code> and the fractional part of <code>x</code>.
9358 Its second result is always a float.
9359
9360
9361
9362
9363 <p>
9364 <hr><h3><a name="pdf-math.pi"><code>math.pi</code></a></h3>
9365
9366
9367 <p>
9368 The value of <em>&pi;</em>.
9369
9370
9371
9372
9373 <p>
9374 <hr><h3><a name="pdf-math.rad"><code>math.rad (x)</code></a></h3>
9375
9376
9377 <p>
9378 Converts the angle <code>x</code> from degrees to radians.
9379
9380
9381
9382
9383 <p>
9384 <hr><h3><a name="pdf-math.random"><code>math.random ([m [, n]])</code></a></h3>
9385
9386
9387 <p>
9388 When called without arguments,
9389 returns a pseudo-random float with uniform distribution
9390 in the range  <em>[0,1)</em>.
9391 When called with two integers <code>m</code> and <code>n</code>,
9392 <code>math.random</code> returns a pseudo-random integer
9393 with uniform distribution in the range <em>[m, n]</em>.
9394 (The value <em>n-m</em> cannot be negative and must fit in a Lua integer.)
9395 The call <code>math.random(n)</code> is equivalent to <code>math.random(1,n)</code>.
9396
9397
9398 <p>
9399 This function is an interface to the underling
9400 pseudo-random generator function provided by C.
9401
9402
9403
9404
9405 <p>
9406 <hr><h3><a name="pdf-math.randomseed"><code>math.randomseed (x)</code></a></h3>
9407
9408
9409 <p>
9410 Sets <code>x</code> as the "seed"
9411 for the pseudo-random generator:
9412 equal seeds produce equal sequences of numbers.
9413
9414
9415
9416
9417 <p>
9418 <hr><h3><a name="pdf-math.sin"><code>math.sin (x)</code></a></h3>
9419
9420
9421 <p>
9422 Returns the sine of <code>x</code> (assumed to be in radians).
9423
9424
9425
9426
9427 <p>
9428 <hr><h3><a name="pdf-math.sqrt"><code>math.sqrt (x)</code></a></h3>
9429
9430
9431 <p>
9432 Returns the square root of <code>x</code>.
9433 (You can also use the expression <code>x^0.5</code> to compute this value.)
9434
9435
9436
9437
9438 <p>
9439 <hr><h3><a name="pdf-math.tan"><code>math.tan (x)</code></a></h3>
9440
9441
9442 <p>
9443 Returns the tangent of <code>x</code> (assumed to be in radians).
9444
9445
9446
9447
9448 <p>
9449 <hr><h3><a name="pdf-math.tointeger"><code>math.tointeger (x)</code></a></h3>
9450
9451
9452 <p>
9453 If the value <code>x</code> is convertible to an integer,
9454 returns that integer.
9455 Otherwise, returns <b>nil</b>.
9456
9457
9458
9459
9460 <p>
9461 <hr><h3><a name="pdf-math.type"><code>math.type (x)</code></a></h3>
9462
9463
9464 <p>
9465 Returns "<code>integer</code>" if <code>x</code> is an integer,
9466 "<code>float</code>" if it is a float,
9467 or <b>nil</b> if <code>x</code> is not a number.
9468
9469
9470
9471
9472 <p>
9473 <hr><h3><a name="pdf-math.ult"><code>math.ult (m, n)</code></a></h3>
9474
9475
9476 <p>
9477 Returns a boolean,
9478 true if and only if integer <code>m</code> is below integer <code>n</code> when
9479 they are compared as unsigned integers.
9480
9481
9482
9483
9484
9485
9486
9487 <h2>6.8 &ndash; <a name="6.8">Input and Output Facilities</a></h2>
9488
9489 <p>
9490 The I/O library provides two different styles for file manipulation.
9491 The first one uses implicit file handles;
9492 that is, there are operations to set a default input file and a
9493 default output file,
9494 and all input/output operations are over these default files.
9495 The second style uses explicit file handles.
9496
9497
9498 <p>
9499 When using implicit file handles,
9500 all operations are supplied by table <a name="pdf-io"><code>io</code></a>.
9501 When using explicit file handles,
9502 the operation <a href="#pdf-io.open"><code>io.open</code></a> returns a file handle
9503 and then all operations are supplied as methods of the file handle.
9504
9505
9506 <p>
9507 The table <code>io</code> also provides
9508 three predefined file handles with their usual meanings from C:
9509 <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>.
9510 The I/O library never closes these files.
9511
9512
9513 <p>
9514 Unless otherwise stated,
9515 all I/O functions return <b>nil</b> on failure
9516 (plus an error message as a second result and
9517 a system-dependent error code as a third result)
9518 and some value different from <b>nil</b> on success.
9519 On non-POSIX systems,
9520 the computation of the error message and error code
9521 in case of errors
9522 may be not thread safe,
9523 because they rely on the global C variable <code>errno</code>.
9524
9525
9526 <p>
9527 <hr><h3><a name="pdf-io.close"><code>io.close ([file])</code></a></h3>
9528
9529
9530 <p>
9531 Equivalent to <code>file:close()</code>.
9532 Without a <code>file</code>, closes the default output file.
9533
9534
9535
9536
9537 <p>
9538 <hr><h3><a name="pdf-io.flush"><code>io.flush ()</code></a></h3>
9539
9540
9541 <p>
9542 Equivalent to <code>io.output():flush()</code>.
9543
9544
9545
9546
9547 <p>
9548 <hr><h3><a name="pdf-io.input"><code>io.input ([file])</code></a></h3>
9549
9550
9551 <p>
9552 When called with a file name, it opens the named file (in text mode),
9553 and sets its handle as the default input file.
9554 When called with a file handle,
9555 it simply sets this file handle as the default input file.
9556 When called without parameters,
9557 it returns the current default input file.
9558
9559
9560 <p>
9561 In case of errors this function raises the error,
9562 instead of returning an error code.
9563
9564
9565
9566
9567 <p>
9568 <hr><h3><a name="pdf-io.lines"><code>io.lines ([filename, &middot;&middot;&middot;])</code></a></h3>
9569
9570
9571 <p>
9572 Opens the given file name in read mode
9573 and returns an iterator function that
9574 works like <code>file:lines(&middot;&middot;&middot;)</code> over the opened file.
9575 When the iterator function detects the end of file,
9576 it returns no values (to finish the loop) and automatically closes the file.
9577
9578
9579 <p>
9580 The call <code>io.lines()</code> (with no file name) is equivalent
9581 to <code>io.input():lines("*l")</code>;
9582 that is, it iterates over the lines of the default input file.
9583 In this case it does not close the file when the loop ends.
9584
9585
9586 <p>
9587 In case of errors this function raises the error,
9588 instead of returning an error code.
9589
9590
9591
9592
9593 <p>
9594 <hr><h3><a name="pdf-io.open"><code>io.open (filename [, mode])</code></a></h3>
9595
9596
9597 <p>
9598 This function opens a file,
9599 in the mode specified in the string <code>mode</code>.
9600 In case of success,
9601 it returns a new file handle.
9602
9603
9604 <p>
9605 The <code>mode</code> string can be any of the following:
9606
9607 <ul>
9608 <li><b>"<code>r</code>": </b> read mode (the default);</li>
9609 <li><b>"<code>w</code>": </b> write mode;</li>
9610 <li><b>"<code>a</code>": </b> append mode;</li>
9611 <li><b>"<code>r+</code>": </b> update mode, all previous data is preserved;</li>
9612 <li><b>"<code>w+</code>": </b> update mode, all previous data is erased;</li>
9613 <li><b>"<code>a+</code>": </b> append update mode, previous data is preserved,
9614   writing is only allowed at the end of file.</li>
9615 </ul><p>
9616 The <code>mode</code> string can also have a '<code>b</code>' at the end,
9617 which is needed in some systems to open the file in binary mode.
9618
9619
9620
9621
9622 <p>
9623 <hr><h3><a name="pdf-io.output"><code>io.output ([file])</code></a></h3>
9624
9625
9626 <p>
9627 Similar to <a href="#pdf-io.input"><code>io.input</code></a>, but operates over the default output file.
9628
9629
9630
9631
9632 <p>
9633 <hr><h3><a name="pdf-io.popen"><code>io.popen (prog [, mode])</code></a></h3>
9634
9635
9636 <p>
9637 This function is system dependent and is not available
9638 on all platforms.
9639
9640
9641 <p>
9642 Starts program <code>prog</code> in a separated process and returns
9643 a file handle that you can use to read data from this program
9644 (if <code>mode</code> is <code>"r"</code>, the default)
9645 or to write data to this program
9646 (if <code>mode</code> is <code>"w"</code>).
9647
9648
9649
9650
9651 <p>
9652 <hr><h3><a name="pdf-io.read"><code>io.read (&middot;&middot;&middot;)</code></a></h3>
9653
9654
9655 <p>
9656 Equivalent to <code>io.input():read(&middot;&middot;&middot;)</code>.
9657
9658
9659
9660
9661 <p>
9662 <hr><h3><a name="pdf-io.tmpfile"><code>io.tmpfile ()</code></a></h3>
9663
9664
9665 <p>
9666 In case of success,
9667 returns a handle for a temporary file.
9668 This file is opened in update mode
9669 and it is automatically removed when the program ends.
9670
9671
9672
9673
9674 <p>
9675 <hr><h3><a name="pdf-io.type"><code>io.type (obj)</code></a></h3>
9676
9677
9678 <p>
9679 Checks whether <code>obj</code> is a valid file handle.
9680 Returns the string <code>"file"</code> if <code>obj</code> is an open file handle,
9681 <code>"closed file"</code> if <code>obj</code> is a closed file handle,
9682 or <b>nil</b> if <code>obj</code> is not a file handle.
9683
9684
9685
9686
9687 <p>
9688 <hr><h3><a name="pdf-io.write"><code>io.write (&middot;&middot;&middot;)</code></a></h3>
9689
9690
9691 <p>
9692 Equivalent to <code>io.output():write(&middot;&middot;&middot;)</code>.
9693
9694
9695
9696
9697 <p>
9698 <hr><h3><a name="pdf-file:close"><code>file:close ()</code></a></h3>
9699
9700
9701 <p>
9702 Closes <code>file</code>.
9703 Note that files are automatically closed when
9704 their handles are garbage collected,
9705 but that takes an unpredictable amount of time to happen.
9706
9707
9708 <p>
9709 When closing a file handle created with <a href="#pdf-io.popen"><code>io.popen</code></a>,
9710 <a href="#pdf-file:close"><code>file:close</code></a> returns the same values
9711 returned by <a href="#pdf-os.execute"><code>os.execute</code></a>.
9712
9713
9714
9715
9716 <p>
9717 <hr><h3><a name="pdf-file:flush"><code>file:flush ()</code></a></h3>
9718
9719
9720 <p>
9721 Saves any written data to <code>file</code>.
9722
9723
9724
9725
9726 <p>
9727 <hr><h3><a name="pdf-file:lines"><code>file:lines (&middot;&middot;&middot;)</code></a></h3>
9728
9729
9730 <p>
9731 Returns an iterator function that,
9732 each time it is called,
9733 reads the file according to the given formats.
9734 When no format is given,
9735 uses "<code>l</code>" as a default.
9736 As an example, the construction
9737
9738 <pre>
9739      for c in file:lines(1) do <em>body</em> end
9740 </pre><p>
9741 will iterate over all characters of the file,
9742 starting at the current position.
9743 Unlike <a href="#pdf-io.lines"><code>io.lines</code></a>, this function does not close the file
9744 when the loop ends.
9745
9746
9747 <p>
9748 In case of errors this function raises the error,
9749 instead of returning an error code.
9750
9751
9752
9753
9754 <p>
9755 <hr><h3><a name="pdf-file:read"><code>file:read (&middot;&middot;&middot;)</code></a></h3>
9756
9757
9758 <p>
9759 Reads the file <code>file</code>,
9760 according to the given formats, which specify what to read.
9761 For each format,
9762 the function returns a string or a number with the characters read,
9763 or <b>nil</b> if it cannot read data with the specified format.
9764 (In this latter case,
9765 the function does not read subsequent formats.)
9766 When called without formats,
9767 it uses a default format that reads the next line
9768 (see below).
9769
9770
9771 <p>
9772 The available formats are
9773
9774 <ul>
9775
9776 <li><b>"<code>n</code>": </b>
9777 reads a numeral and returns it as a float or an integer,
9778 following the lexical conventions of Lua.
9779 (The numeral may have leading spaces and a sign.)
9780 This format always reads the longest input sequence that
9781 is a valid prefix for a numeral;
9782 if that prefix does not form a valid numeral
9783 (e.g., an empty string, "<code>0x</code>", or "<code>3.4e-</code>"),
9784 it is discarded and the function returns <b>nil</b>.
9785 </li>
9786
9787 <li><b>"<code>a</code>": </b>
9788 reads the whole file, starting at the current position.
9789 On end of file, it returns the empty string.
9790 </li>
9791
9792 <li><b>"<code>l</code>": </b>
9793 reads the next line skipping the end of line,
9794 returning <b>nil</b> on end of file.
9795 This is the default format.
9796 </li>
9797
9798 <li><b>"<code>L</code>": </b>
9799 reads the next line keeping the end-of-line character (if present),
9800 returning <b>nil</b> on end of file.
9801 </li>
9802
9803 <li><b><em>number</em>: </b>
9804 reads a string with up to this number of bytes,
9805 returning <b>nil</b> on end of file.
9806 If <code>number</code> is zero,
9807 it reads nothing and returns an empty string,
9808 or <b>nil</b> on end of file.
9809 </li>
9810
9811 </ul><p>
9812 The formats "<code>l</code>" and "<code>L</code>" should be used only for text files.
9813
9814
9815
9816
9817 <p>
9818 <hr><h3><a name="pdf-file:seek"><code>file:seek ([whence [, offset]])</code></a></h3>
9819
9820
9821 <p>
9822 Sets and gets the file position,
9823 measured from the beginning of the file,
9824 to the position given by <code>offset</code> plus a base
9825 specified by the string <code>whence</code>, as follows:
9826
9827 <ul>
9828 <li><b>"<code>set</code>": </b> base is position 0 (beginning of the file);</li>
9829 <li><b>"<code>cur</code>": </b> base is current position;</li>
9830 <li><b>"<code>end</code>": </b> base is end of file;</li>
9831 </ul><p>
9832 In case of success, <code>seek</code> returns the final file position,
9833 measured in bytes from the beginning of the file.
9834 If <code>seek</code> fails, it returns <b>nil</b>,
9835 plus a string describing the error.
9836
9837
9838 <p>
9839 The default value for <code>whence</code> is <code>"cur"</code>,
9840 and for <code>offset</code> is 0.
9841 Therefore, the call <code>file:seek()</code> returns the current
9842 file position, without changing it;
9843 the call <code>file:seek("set")</code> sets the position to the
9844 beginning of the file (and returns 0);
9845 and the call <code>file:seek("end")</code> sets the position to the
9846 end of the file, and returns its size.
9847
9848
9849
9850
9851 <p>
9852 <hr><h3><a name="pdf-file:setvbuf"><code>file:setvbuf (mode [, size])</code></a></h3>
9853
9854
9855 <p>
9856 Sets the buffering mode for an output file.
9857 There are three available modes:
9858
9859 <ul>
9860
9861 <li><b>"<code>no</code>": </b>
9862 no buffering; the result of any output operation appears immediately.
9863 </li>
9864
9865 <li><b>"<code>full</code>": </b>
9866 full buffering; output operation is performed only
9867 when the buffer is full or when
9868 you explicitly <code>flush</code> the file (see <a href="#pdf-io.flush"><code>io.flush</code></a>).
9869 </li>
9870
9871 <li><b>"<code>line</code>": </b>
9872 line buffering; output is buffered until a newline is output
9873 or there is any input from some special files
9874 (such as a terminal device).
9875 </li>
9876
9877 </ul><p>
9878 For the last two cases, <code>size</code>
9879 specifies the size of the buffer, in bytes.
9880 The default is an appropriate size.
9881
9882
9883
9884
9885 <p>
9886 <hr><h3><a name="pdf-file:write"><code>file:write (&middot;&middot;&middot;)</code></a></h3>
9887
9888
9889 <p>
9890 Writes the value of each of its arguments to <code>file</code>.
9891 The arguments must be strings or numbers.
9892
9893
9894 <p>
9895 In case of success, this function returns <code>file</code>.
9896 Otherwise it returns <b>nil</b> plus a string describing the error.
9897
9898
9899
9900
9901
9902
9903
9904 <h2>6.9 &ndash; <a name="6.9">Operating System Facilities</a></h2>
9905
9906 <p>
9907 This library is implemented through table <a name="pdf-os"><code>os</code></a>.
9908
9909
9910 <p>
9911 <hr><h3><a name="pdf-os.clock"><code>os.clock ()</code></a></h3>
9912
9913
9914 <p>
9915 Returns an approximation of the amount in seconds of CPU time
9916 used by the program.
9917
9918
9919
9920
9921 <p>
9922 <hr><h3><a name="pdf-os.date"><code>os.date ([format [, time]])</code></a></h3>
9923
9924
9925 <p>
9926 Returns a string or a table containing date and time,
9927 formatted according to the given string <code>format</code>.
9928
9929
9930 <p>
9931 If the <code>time</code> argument is present,
9932 this is the time to be formatted
9933 (see the <a href="#pdf-os.time"><code>os.time</code></a> function for a description of this value).
9934 Otherwise, <code>date</code> formats the current time.
9935
9936
9937 <p>
9938 If <code>format</code> starts with '<code>!</code>',
9939 then the date is formatted in Coordinated Universal Time.
9940 After this optional character,
9941 if <code>format</code> is the string "<code>*t</code>",
9942 then <code>date</code> returns a table with the following fields:
9943 <code>year</code>, <code>month</code> (1&ndash;12), <code>day</code> (1&ndash;31),
9944 <code>hour</code> (0&ndash;23), <code>min</code> (0&ndash;59), <code>sec</code> (0&ndash;61),
9945 <code>wday</code> (weekday, 1&ndash;7, Sunday is&nbsp;1),
9946 <code>yday</code> (day of the year, 1&ndash;366),
9947 and <code>isdst</code> (daylight saving flag, a boolean).
9948 This last field may be absent
9949 if the information is not available.
9950
9951
9952 <p>
9953 If <code>format</code> is not "<code>*t</code>",
9954 then <code>date</code> returns the date as a string,
9955 formatted according to the same rules as the ISO&nbsp;C function <code>strftime</code>.
9956
9957
9958 <p>
9959 When called without arguments,
9960 <code>date</code> returns a reasonable date and time representation that depends on
9961 the host system and on the current locale.
9962 (More specifically, <code>os.date()</code> is equivalent to <code>os.date("%c")</code>.)
9963
9964
9965 <p>
9966 On non-POSIX systems,
9967 this function may be not thread safe
9968 because of its reliance on C&nbsp;function <code>gmtime</code> and C&nbsp;function <code>localtime</code>.
9969
9970
9971
9972
9973 <p>
9974 <hr><h3><a name="pdf-os.difftime"><code>os.difftime (t2, t1)</code></a></h3>
9975
9976
9977 <p>
9978 Returns the difference, in seconds,
9979 from time <code>t1</code> to time <code>t2</code>
9980 (where the times are values returned by <a href="#pdf-os.time"><code>os.time</code></a>).
9981 In POSIX, Windows, and some other systems,
9982 this value is exactly <code>t2</code><em>-</em><code>t1</code>.
9983
9984
9985
9986
9987 <p>
9988 <hr><h3><a name="pdf-os.execute"><code>os.execute ([command])</code></a></h3>
9989
9990
9991 <p>
9992 This function is equivalent to the ISO&nbsp;C function <code>system</code>.
9993 It passes <code>command</code> to be executed by an operating system shell.
9994 Its first result is <b>true</b>
9995 if the command terminated successfully,
9996 or <b>nil</b> otherwise.
9997 After this first result
9998 the function returns a string plus a number,
9999 as follows:
10000
10001 <ul>
10002
10003 <li><b>"<code>exit</code>": </b>
10004 the command terminated normally;
10005 the following number is the exit status of the command.
10006 </li>
10007
10008 <li><b>"<code>signal</code>": </b>
10009 the command was terminated by a signal;
10010 the following number is the signal that terminated the command.
10011 </li>
10012
10013 </ul>
10014
10015 <p>
10016 When called without a <code>command</code>,
10017 <code>os.execute</code> returns a boolean that is true if a shell is available.
10018
10019
10020
10021
10022 <p>
10023 <hr><h3><a name="pdf-os.exit"><code>os.exit ([code [, close]])</code></a></h3>
10024
10025
10026 <p>
10027 Calls the ISO&nbsp;C function <code>exit</code> to terminate the host program.
10028 If <code>code</code> is <b>true</b>,
10029 the returned status is <code>EXIT_SUCCESS</code>;
10030 if <code>code</code> is <b>false</b>,
10031 the returned status is <code>EXIT_FAILURE</code>;
10032 if <code>code</code> is a number,
10033 the returned status is this number.
10034 The default value for <code>code</code> is <b>true</b>.
10035
10036
10037 <p>
10038 If the optional second argument <code>close</code> is true,
10039 closes the Lua state before exiting.
10040
10041
10042
10043
10044 <p>
10045 <hr><h3><a name="pdf-os.getenv"><code>os.getenv (varname)</code></a></h3>
10046
10047
10048 <p>
10049 Returns the value of the process environment variable <code>varname</code>,
10050 or <b>nil</b> if the variable is not defined.
10051
10052
10053
10054
10055 <p>
10056 <hr><h3><a name="pdf-os.remove"><code>os.remove (filename)</code></a></h3>
10057
10058
10059 <p>
10060 Deletes the file (or empty directory, on POSIX systems)
10061 with the given name.
10062 If this function fails, it returns <b>nil</b>,
10063 plus a string describing the error and the error code.
10064 Otherwise, it returns true.
10065
10066
10067
10068
10069 <p>
10070 <hr><h3><a name="pdf-os.rename"><code>os.rename (oldname, newname)</code></a></h3>
10071
10072
10073 <p>
10074 Renames the file or directory named <code>oldname</code> to <code>newname</code>.
10075 If this function fails, it returns <b>nil</b>,
10076 plus a string describing the error and the error code.
10077 Otherwise, it returns true.
10078
10079
10080
10081
10082 <p>
10083 <hr><h3><a name="pdf-os.setlocale"><code>os.setlocale (locale [, category])</code></a></h3>
10084
10085
10086 <p>
10087 Sets the current locale of the program.
10088 <code>locale</code> is a system-dependent string specifying a locale;
10089 <code>category</code> is an optional string describing which category to change:
10090 <code>"all"</code>, <code>"collate"</code>, <code>"ctype"</code>,
10091 <code>"monetary"</code>, <code>"numeric"</code>, or <code>"time"</code>;
10092 the default category is <code>"all"</code>.
10093 The function returns the name of the new locale,
10094 or <b>nil</b> if the request cannot be honored.
10095
10096
10097 <p>
10098 If <code>locale</code> is the empty string,
10099 the current locale is set to an implementation-defined native locale.
10100 If <code>locale</code> is the string "<code>C</code>",
10101 the current locale is set to the standard C locale.
10102
10103
10104 <p>
10105 When called with <b>nil</b> as the first argument,
10106 this function only returns the name of the current locale
10107 for the given category.
10108
10109
10110 <p>
10111 This function may be not thread safe
10112 because of its reliance on C&nbsp;function <code>setlocale</code>.
10113
10114
10115
10116
10117 <p>
10118 <hr><h3><a name="pdf-os.time"><code>os.time ([table])</code></a></h3>
10119
10120
10121 <p>
10122 Returns the current time when called without arguments,
10123 or a time representing the local date and time specified by the given table.
10124 This table must have fields <code>year</code>, <code>month</code>, and <code>day</code>,
10125 and may have fields
10126 <code>hour</code> (default is 12),
10127 <code>min</code> (default is 0),
10128 <code>sec</code> (default is 0),
10129 and <code>isdst</code> (default is <b>nil</b>).
10130 Other fields are ignored.
10131 For a description of these fields, see the <a href="#pdf-os.date"><code>os.date</code></a> function.
10132
10133
10134 <p>
10135 The values in these fields do not need to be inside their valid ranges.
10136 For instance, if <code>sec</code> is -10,
10137 it means -10 seconds from the time specified by the other fields;
10138 if <code>hour</code> is 1000,
10139 it means +1000 hours from the time specified by the other fields.
10140
10141
10142 <p>
10143 The returned value is a number, whose meaning depends on your system.
10144 In POSIX, Windows, and some other systems,
10145 this number counts the number
10146 of seconds since some given start time (the "epoch").
10147 In other systems, the meaning is not specified,
10148 and the number returned by <code>time</code> can be used only as an argument to
10149 <a href="#pdf-os.date"><code>os.date</code></a> and <a href="#pdf-os.difftime"><code>os.difftime</code></a>.
10150
10151
10152
10153
10154 <p>
10155 <hr><h3><a name="pdf-os.tmpname"><code>os.tmpname ()</code></a></h3>
10156
10157
10158 <p>
10159 Returns a string with a file name that can
10160 be used for a temporary file.
10161 The file must be explicitly opened before its use
10162 and explicitly removed when no longer needed.
10163
10164
10165 <p>
10166 On POSIX systems,
10167 this function also creates a file with that name,
10168 to avoid security risks.
10169 (Someone else might create the file with wrong permissions
10170 in the time between getting the name and creating the file.)
10171 You still have to open the file to use it
10172 and to remove it (even if you do not use it).
10173
10174
10175 <p>
10176 When possible,
10177 you may prefer to use <a href="#pdf-io.tmpfile"><code>io.tmpfile</code></a>,
10178 which automatically removes the file when the program ends.
10179
10180
10181
10182
10183
10184
10185
10186 <h2>6.10 &ndash; <a name="6.10">The Debug Library</a></h2>
10187
10188 <p>
10189 This library provides
10190 the functionality of the debug interface (<a href="#4.9">&sect;4.9</a>) to Lua programs.
10191 You should exert care when using this library.
10192 Several of its functions
10193 violate basic assumptions about Lua code
10194 (e.g., that variables local to a function
10195 cannot be accessed from outside;
10196 that userdata metatables cannot be changed by Lua code;
10197 that Lua programs do not crash)
10198 and therefore can compromise otherwise secure code.
10199 Moreover, some functions in this library may be slow.
10200
10201
10202 <p>
10203 All functions in this library are provided
10204 inside the <a name="pdf-debug"><code>debug</code></a> table.
10205 All functions that operate over a thread
10206 have an optional first argument which is the
10207 thread to operate over.
10208 The default is always the current thread.
10209
10210
10211 <p>
10212 <hr><h3><a name="pdf-debug.debug"><code>debug.debug ()</code></a></h3>
10213
10214
10215 <p>
10216 Enters an interactive mode with the user,
10217 running each string that the user enters.
10218 Using simple commands and other debug facilities,
10219 the user can inspect global and local variables,
10220 change their values, evaluate expressions, and so on.
10221 A line containing only the word <code>cont</code> finishes this function,
10222 so that the caller continues its execution.
10223
10224
10225 <p>
10226 Note that commands for <code>debug.debug</code> are not lexically nested
10227 within any function and so have no direct access to local variables.
10228
10229
10230
10231
10232 <p>
10233 <hr><h3><a name="pdf-debug.gethook"><code>debug.gethook ([thread])</code></a></h3>
10234
10235
10236 <p>
10237 Returns the current hook settings of the thread, as three values:
10238 the current hook function, the current hook mask,
10239 and the current hook count
10240 (as set by the <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> function).
10241
10242
10243
10244
10245 <p>
10246 <hr><h3><a name="pdf-debug.getinfo"><code>debug.getinfo ([thread,] f [, what])</code></a></h3>
10247
10248
10249 <p>
10250 Returns a table with information about a function.
10251 You can give the function directly
10252 or you can give a number as the value of <code>f</code>,
10253 which means the function running at level <code>f</code> of the call stack
10254 of the given thread:
10255 level&nbsp;0 is the current function (<code>getinfo</code> itself);
10256 level&nbsp;1 is the function that called <code>getinfo</code>
10257 (except for tail calls, which do not count on the stack);
10258 and so on.
10259 If <code>f</code> is a number larger than the number of active functions,
10260 then <code>getinfo</code> returns <b>nil</b>.
10261
10262
10263 <p>
10264 The returned table can contain all the fields returned by <a href="#lua_getinfo"><code>lua_getinfo</code></a>,
10265 with the string <code>what</code> describing which fields to fill in.
10266 The default for <code>what</code> is to get all information available,
10267 except the table of valid lines.
10268 If present,
10269 the option '<code>f</code>'
10270 adds a field named <code>func</code> with the function itself.
10271 If present,
10272 the option '<code>L</code>'
10273 adds a field named <code>activelines</code> with the table of
10274 valid lines.
10275
10276
10277 <p>
10278 For instance, the expression <code>debug.getinfo(1,"n").name</code> returns
10279 a name for the current function,
10280 if a reasonable name can be found,
10281 and the expression <code>debug.getinfo(print)</code>
10282 returns a table with all available information
10283 about the <a href="#pdf-print"><code>print</code></a> function.
10284
10285
10286
10287
10288 <p>
10289 <hr><h3><a name="pdf-debug.getlocal"><code>debug.getlocal ([thread,] f, local)</code></a></h3>
10290
10291
10292 <p>
10293 This function returns the name and the value of the local variable
10294 with index <code>local</code> of the function at level <code>f</code> of the stack.
10295 This function accesses not only explicit local variables,
10296 but also parameters, temporaries, etc.
10297
10298
10299 <p>
10300 The first parameter or local variable has index&nbsp;1, and so on,
10301 following the order that they are declared in the code,
10302 counting only the variables that are active
10303 in the current scope of the function.
10304 Negative indices refer to vararg parameters;
10305 -1 is the first vararg parameter.
10306 The function returns <b>nil</b> if there is no variable with the given index,
10307 and raises an error when called with a level out of range.
10308 (You can call <a href="#pdf-debug.getinfo"><code>debug.getinfo</code></a> to check whether the level is valid.)
10309
10310
10311 <p>
10312 Variable names starting with '<code>(</code>' (open parenthesis)
10313 represent variables with no known names
10314 (internal variables such as loop control variables,
10315 and variables from chunks saved without debug information).
10316
10317
10318 <p>
10319 The parameter <code>f</code> may also be a function.
10320 In that case, <code>getlocal</code> returns only the name of function parameters.
10321
10322
10323
10324
10325 <p>
10326 <hr><h3><a name="pdf-debug.getmetatable"><code>debug.getmetatable (value)</code></a></h3>
10327
10328
10329 <p>
10330 Returns the metatable of the given <code>value</code>
10331 or <b>nil</b> if it does not have a metatable.
10332
10333
10334
10335
10336 <p>
10337 <hr><h3><a name="pdf-debug.getregistry"><code>debug.getregistry ()</code></a></h3>
10338
10339
10340 <p>
10341 Returns the registry table (see <a href="#4.5">&sect;4.5</a>).
10342
10343
10344
10345
10346 <p>
10347 <hr><h3><a name="pdf-debug.getupvalue"><code>debug.getupvalue (f, up)</code></a></h3>
10348
10349
10350 <p>
10351 This function returns the name and the value of the upvalue
10352 with index <code>up</code> of the function <code>f</code>.
10353 The function returns <b>nil</b> if there is no upvalue with the given index.
10354
10355
10356 <p>
10357 Variable names starting with '<code>(</code>' (open parenthesis)
10358 represent variables with no known names
10359 (variables from chunks saved without debug information).
10360
10361
10362
10363
10364 <p>
10365 <hr><h3><a name="pdf-debug.getuservalue"><code>debug.getuservalue (u)</code></a></h3>
10366
10367
10368 <p>
10369 Returns the Lua value associated to <code>u</code>.
10370 If <code>u</code> is not a full userdata,
10371 returns <b>nil</b>.
10372
10373
10374
10375
10376 <p>
10377 <hr><h3><a name="pdf-debug.sethook"><code>debug.sethook ([thread,] hook, mask [, count])</code></a></h3>
10378
10379
10380 <p>
10381 Sets the given function as a hook.
10382 The string <code>mask</code> and the number <code>count</code> describe
10383 when the hook will be called.
10384 The string mask may have any combination of the following characters,
10385 with the given meaning:
10386
10387 <ul>
10388 <li><b>'<code>c</code>': </b> the hook is called every time Lua calls a function;</li>
10389 <li><b>'<code>r</code>': </b> the hook is called every time Lua returns from a function;</li>
10390 <li><b>'<code>l</code>': </b> the hook is called every time Lua enters a new line of code.</li>
10391 </ul><p>
10392 Moreover,
10393 with a <code>count</code> different from zero,
10394 the hook is called also after every <code>count</code> instructions.
10395
10396
10397 <p>
10398 When called without arguments,
10399 <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> turns off the hook.
10400
10401
10402 <p>
10403 When the hook is called, its first parameter is a string
10404 describing the event that has triggered its call:
10405 <code>"call"</code> (or <code>"tail call"</code>),
10406 <code>"return"</code>,
10407 <code>"line"</code>, and <code>"count"</code>.
10408 For line events,
10409 the hook also gets the new line number as its second parameter.
10410 Inside a hook,
10411 you can call <code>getinfo</code> with level&nbsp;2 to get more information about
10412 the running function
10413 (level&nbsp;0 is the <code>getinfo</code> function,
10414 and level&nbsp;1 is the hook function).
10415
10416
10417
10418
10419 <p>
10420 <hr><h3><a name="pdf-debug.setlocal"><code>debug.setlocal ([thread,] level, local, value)</code></a></h3>
10421
10422
10423 <p>
10424 This function assigns the value <code>value</code> to the local variable
10425 with index <code>local</code> of the function at level <code>level</code> of the stack.
10426 The function returns <b>nil</b> if there is no local
10427 variable with the given index,
10428 and raises an error when called with a <code>level</code> out of range.
10429 (You can call <code>getinfo</code> to check whether the level is valid.)
10430 Otherwise, it returns the name of the local variable.
10431
10432
10433 <p>
10434 See <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for more information about
10435 variable indices and names.
10436
10437
10438
10439
10440 <p>
10441 <hr><h3><a name="pdf-debug.setmetatable"><code>debug.setmetatable (value, table)</code></a></h3>
10442
10443
10444 <p>
10445 Sets the metatable for the given <code>value</code> to the given <code>table</code>
10446 (which can be <b>nil</b>).
10447 Returns <code>value</code>.
10448
10449
10450
10451
10452 <p>
10453 <hr><h3><a name="pdf-debug.setupvalue"><code>debug.setupvalue (f, up, value)</code></a></h3>
10454
10455
10456 <p>
10457 This function assigns the value <code>value</code> to the upvalue
10458 with index <code>up</code> of the function <code>f</code>.
10459 The function returns <b>nil</b> if there is no upvalue
10460 with the given index.
10461 Otherwise, it returns the name of the upvalue.
10462
10463
10464
10465
10466 <p>
10467 <hr><h3><a name="pdf-debug.setuservalue"><code>debug.setuservalue (udata, value)</code></a></h3>
10468
10469
10470 <p>
10471 Sets the given <code>value</code> as
10472 the Lua value associated to the given <code>udata</code>.
10473 <code>udata</code> must be a full userdata.
10474
10475
10476 <p>
10477 Returns <code>udata</code>.
10478
10479
10480
10481
10482 <p>
10483 <hr><h3><a name="pdf-debug.traceback"><code>debug.traceback ([thread,] [message [, level]])</code></a></h3>
10484
10485
10486 <p>
10487 If <code>message</code> is present but is neither a string nor <b>nil</b>,
10488 this function returns <code>message</code> without further processing.
10489 Otherwise,
10490 it returns a string with a traceback of the call stack.
10491 The optional <code>message</code> string is appended
10492 at the beginning of the traceback.
10493 An optional <code>level</code> number tells at which level
10494 to start the traceback
10495 (default is 1, the function calling <code>traceback</code>).
10496
10497
10498
10499
10500 <p>
10501 <hr><h3><a name="pdf-debug.upvalueid"><code>debug.upvalueid (f, n)</code></a></h3>
10502
10503
10504 <p>
10505 Returns a unique identifier (as a light userdata)
10506 for the upvalue numbered <code>n</code>
10507 from the given function.
10508
10509
10510 <p>
10511 These unique identifiers allow a program to check whether different
10512 closures share upvalues.
10513 Lua closures that share an upvalue
10514 (that is, that access a same external local variable)
10515 will return identical ids for those upvalue indices.
10516
10517
10518
10519
10520 <p>
10521 <hr><h3><a name="pdf-debug.upvaluejoin"><code>debug.upvaluejoin (f1, n1, f2, n2)</code></a></h3>
10522
10523
10524 <p>
10525 Make the <code>n1</code>-th upvalue of the Lua closure <code>f1</code>
10526 refer to the <code>n2</code>-th upvalue of the Lua closure <code>f2</code>.
10527
10528
10529
10530
10531
10532
10533
10534 <h1>7 &ndash; <a name="7">Lua Standalone</a></h1>
10535
10536 <p>
10537 Although Lua has been designed as an extension language,
10538 to be embedded in a host C&nbsp;program,
10539 it is also frequently used as a standalone language.
10540 An interpreter for Lua as a standalone language,
10541 called simply <code>lua</code>,
10542 is provided with the standard distribution.
10543 The standalone interpreter includes
10544 all standard libraries, including the debug library.
10545 Its usage is:
10546
10547 <pre>
10548      lua [options] [script [args]]
10549 </pre><p>
10550 The options are:
10551
10552 <ul>
10553 <li><b><code>-e <em>stat</em></code>: </b> executes string <em>stat</em>;</li>
10554 <li><b><code>-l <em>mod</em></code>: </b> "requires" <em>mod</em>;</li>
10555 <li><b><code>-i</code>: </b> enters interactive mode after running <em>script</em>;</li>
10556 <li><b><code>-v</code>: </b> prints version information;</li>
10557 <li><b><code>-E</code>: </b> ignores environment variables;</li>
10558 <li><b><code>--</code>: </b> stops handling options;</li>
10559 <li><b><code>-</code>: </b> executes <code>stdin</code> as a file and stops handling options.</li>
10560 </ul><p>
10561 After handling its options, <code>lua</code> runs the given <em>script</em>.
10562 When called without arguments,
10563 <code>lua</code> behaves as <code>lua -v -i</code>
10564 when the standard input (<code>stdin</code>) is a terminal,
10565 and as <code>lua -</code> otherwise.
10566
10567
10568 <p>
10569 When called without option <code>-E</code>,
10570 the interpreter checks for an environment variable <a name="pdf-LUA_INIT_5_3"><code>LUA_INIT_5_3</code></a>
10571 (or <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a> if the versioned name is not defined)
10572 before running any argument.
10573 If the variable content has the format <code>@<em>filename</em></code>,
10574 then <code>lua</code> executes the file.
10575 Otherwise, <code>lua</code> executes the string itself.
10576
10577
10578 <p>
10579 When called with option <code>-E</code>,
10580 besides ignoring <code>LUA_INIT</code>,
10581 Lua also ignores
10582 the values of <code>LUA_PATH</code> and <code>LUA_CPATH</code>,
10583 setting the values of
10584 <a href="#pdf-package.path"><code>package.path</code></a> and <a href="#pdf-package.cpath"><code>package.cpath</code></a>
10585 with the default paths defined in <code>luaconf.h</code>.
10586
10587
10588 <p>
10589 All options are handled in order, except <code>-i</code> and <code>-E</code>.
10590 For instance, an invocation like
10591
10592 <pre>
10593      $ lua -e'a=1' -e 'print(a)' script.lua
10594 </pre><p>
10595 will first set <code>a</code> to 1, then print the value of <code>a</code>,
10596 and finally run the file <code>script.lua</code> with no arguments.
10597 (Here <code>$</code> is the shell prompt. Your prompt may be different.)
10598
10599
10600 <p>
10601 Before running any code,
10602 <code>lua</code> collects all command-line arguments
10603 in a global table called <code>arg</code>.
10604 The script name goes to index 0,
10605 the first argument after the script name goes to index 1,
10606 and so on.
10607 Any arguments before the script name
10608 (that is, the interpreter name plus its options)
10609 go to negative indices.
10610 For instance, in the call
10611
10612 <pre>
10613      $ lua -la b.lua t1 t2
10614 </pre><p>
10615 the table is like this:
10616
10617 <pre>
10618      arg = { [-2] = "lua", [-1] = "-la",
10619              [0] = "b.lua",
10620              [1] = "t1", [2] = "t2" }
10621 </pre><p>
10622 If there is no script in the call,
10623 the interpreter name goes to index 0,
10624 followed by the other arguments.
10625 For instance, the call
10626
10627 <pre>
10628      $ lua -e "print(arg[1])"
10629 </pre><p>
10630 will print "<code>-e</code>".
10631 If there is a script,
10632 the script is called with parameters
10633 <code>arg[1]</code>, &middot;&middot;&middot;, <code>arg[#arg]</code>.
10634 (Like all chunks in Lua,
10635 the script is compiled as a vararg function.)
10636
10637
10638 <p>
10639 In interactive mode,
10640 Lua repeatedly prompts and waits for a line.
10641 After reading a line,
10642 Lua first try to interpret the line as an expression.
10643 If it succeeds, it prints its value.
10644 Otherwise, it interprets the line as a statement.
10645 If you write an incomplete statement,
10646 the interpreter waits for its completion
10647 by issuing a different prompt.
10648
10649
10650 <p>
10651 If the global variable <a name="pdf-_PROMPT"><code>_PROMPT</code></a> contains a string,
10652 then its value is used as the prompt.
10653 Similarly, if the global variable <a name="pdf-_PROMPT2"><code>_PROMPT2</code></a> contains a string,
10654 its value is used as the secondary prompt
10655 (issued during incomplete statements).
10656
10657
10658 <p>
10659 In case of unprotected errors in the script,
10660 the interpreter reports the error to the standard error stream.
10661 If the error object is not a string but
10662 has a metamethod <code>__tostring</code>,
10663 the interpreter calls this metamethod to produce the final message.
10664 Otherwise, the interpreter converts the error object to a string
10665 and adds a stack traceback to it.
10666
10667
10668 <p>
10669 When finishing normally,
10670 the interpreter closes its main Lua state
10671 (see <a href="#lua_close"><code>lua_close</code></a>).
10672 The script can avoid this step by
10673 calling <a href="#pdf-os.exit"><code>os.exit</code></a> to terminate.
10674
10675
10676 <p>
10677 To allow the use of Lua as a
10678 script interpreter in Unix systems,
10679 the standalone interpreter skips
10680 the first line of a chunk if it starts with <code>#</code>.
10681 Therefore, Lua scripts can be made into executable programs
10682 by using <code>chmod +x</code> and the&nbsp;<code>#!</code> form,
10683 as in
10684
10685 <pre>
10686      #!/usr/local/bin/lua
10687 </pre><p>
10688 (Of course,
10689 the location of the Lua interpreter may be different in your machine.
10690 If <code>lua</code> is in your <code>PATH</code>,
10691 then
10692
10693 <pre>
10694      #!/usr/bin/env lua
10695 </pre><p>
10696 is a more portable solution.)
10697
10698
10699
10700 <h1>8 &ndash; <a name="8">Incompatibilities with the Previous Version</a></h1>
10701
10702 <p>
10703 Here we list the incompatibilities that you may find when moving a program
10704 from Lua&nbsp;5.2 to Lua&nbsp;5.3.
10705 You can avoid some incompatibilities by compiling Lua with
10706 appropriate options (see file <code>luaconf.h</code>).
10707 However,
10708 all these compatibility options will be removed in the future.
10709
10710
10711 <p>
10712 Lua versions can always change the C API in ways that
10713 do not imply source-code changes in a program,
10714 such as the numeric values for constants
10715 or the implementation of functions as macros.
10716 Therefore,
10717 you should not assume that binaries are compatible between
10718 different Lua versions.
10719 Always recompile clients of the Lua API when
10720 using a new version.
10721
10722
10723 <p>
10724 Similarly, Lua versions can always change the internal representation
10725 of precompiled chunks;
10726 precompiled chunks are not compatible between different Lua versions.
10727
10728
10729 <p>
10730 The standard paths in the official distribution may
10731 change between versions.
10732
10733
10734
10735 <h2>8.1 &ndash; <a name="8.1">Changes in the Language</a></h2>
10736 <ul>
10737
10738 <li>
10739 The main difference between Lua&nbsp;5.2 and Lua&nbsp;5.3 is the
10740 introduction of an integer subtype for numbers.
10741 Although this change should not affect "normal" computations,
10742 some computations
10743 (mainly those that involve some kind of overflow)
10744 can give different results.
10745
10746
10747 <p>
10748 You can fix these differences by forcing a number to be a float
10749 (in Lua&nbsp;5.2 all numbers were float),
10750 in particular writing constants with an ending <code>.0</code>
10751 or using <code>x = x + 0.0</code> to convert a variable.
10752 (This recommendation is only for a quick fix
10753 for an occasional incompatibility;
10754 it is not a general guideline for good programming.
10755 For good programming,
10756 use floats where you need floats
10757 and integers where you need integers.)
10758 </li>
10759
10760 <li>
10761 The conversion of a float to a string now adds a <code>.0</code> suffix
10762 to the result if it looks like an integer.
10763 (For instance, the float 2.0 will be printed as <code>2.0</code>,
10764 not as <code>2</code>.)
10765 You should always use an explicit format
10766 when you need a specific format for numbers.
10767
10768
10769 <p>
10770 (Formally this is not an incompatibility,
10771 because Lua does not specify how numbers are formatted as strings,
10772 but some programs assumed a specific format.)
10773 </li>
10774
10775 <li>
10776 The generational mode for the garbage collector was removed.
10777 (It was an experimental feature in Lua&nbsp;5.2.)
10778 </li>
10779
10780 </ul>
10781
10782
10783
10784
10785 <h2>8.2 &ndash; <a name="8.2">Changes in the Libraries</a></h2>
10786 <ul>
10787
10788 <li>
10789 The <code>bit32</code> library has been deprecated.
10790 It is easy to require a compatible external library or,
10791 better yet, to replace its functions with appropriate bitwise operations.
10792 (Keep in mind that <code>bit32</code> operates on 32-bit integers,
10793 while the bitwise operators in Lua&nbsp;5.3 operate on Lua integers,
10794 which by default have 64&nbsp;bits.)
10795 </li>
10796
10797 <li>
10798 The Table library now respects metamethods
10799 for setting and getting elements.
10800 </li>
10801
10802 <li>
10803 The <a href="#pdf-ipairs"><code>ipairs</code></a> iterator now respects metamethods and
10804 its <code>__ipairs</code> metamethod has been deprecated.
10805 </li>
10806
10807 <li>
10808 Option names in <a href="#pdf-io.read"><code>io.read</code></a> do not have a starting '<code>*</code>' anymore.
10809 For compatibility, Lua will continue to accept (and ignore) this character.
10810 </li>
10811
10812 <li>
10813 The following functions were deprecated in the mathematical library:
10814 <code>atan2</code>, <code>cosh</code>, <code>sinh</code>, <code>tanh</code>, <code>pow</code>,
10815 <code>frexp</code>, and <code>ldexp</code>.
10816 You can replace <code>math.pow(x,y)</code> with <code>x^y</code>;
10817 you can replace <code>math.atan2</code> with <code>math.atan</code>,
10818 which now accepts one or two parameters;
10819 you can replace <code>math.ldexp(x,exp)</code> with <code>x * 2.0^exp</code>.
10820 For the other operations,
10821 you can either use an external library or
10822 implement them in Lua.
10823 </li>
10824
10825 <li>
10826 The searcher for C loaders used by <a href="#pdf-require"><code>require</code></a>
10827 changed the way it handles versioned names.
10828 Now, the version should come after the module name
10829 (as is usual in most other tools).
10830 For compatibility, that searcher still tries the old format
10831 if it cannot find an open function according to the new style.
10832 (Lua&nbsp;5.2 already worked that way,
10833 but it did not document the change.)
10834 </li>
10835
10836 <li>
10837 The call <code>collectgarbage("count")</code> now returns only one result.
10838 (You can compute that second result from the fractional part
10839 of the first result.)
10840 </li>
10841
10842 </ul>
10843
10844
10845
10846
10847 <h2>8.3 &ndash; <a name="8.3">Changes in the API</a></h2>
10848
10849
10850 <ul>
10851
10852 <li>
10853 Continuation functions now receive as parameters what they needed
10854 to get through <code>lua_getctx</code>,
10855 so <code>lua_getctx</code> has been removed.
10856 Adapt your code accordingly.
10857 </li>
10858
10859 <li>
10860 Function <a href="#lua_dump"><code>lua_dump</code></a> has an extra parameter, <code>strip</code>.
10861 Use 0 as the value of this parameter to get the old behavior.
10862 </li>
10863
10864 <li>
10865 Functions to inject/project unsigned integers
10866 (<code>lua_pushunsigned</code>, <code>lua_tounsigned</code>, <code>lua_tounsignedx</code>,
10867 <code>luaL_checkunsigned</code>, <code>luaL_optunsigned</code>)
10868 were deprecated.
10869 Use their signed equivalents with a type cast.
10870 </li>
10871
10872 <li>
10873 Macros to project non-default integer types
10874 (<code>luaL_checkint</code>, <code>luaL_optint</code>, <code>luaL_checklong</code>, <code>luaL_optlong</code>)
10875 were deprecated.
10876 Use their equivalent over <a href="#lua_Integer"><code>lua_Integer</code></a> with a type cast
10877 (or, when possible, use <a href="#lua_Integer"><code>lua_Integer</code></a> in your code).
10878 </li>
10879
10880 </ul>
10881
10882
10883
10884
10885 <h1>9 &ndash; <a name="9">The Complete Syntax of Lua</a></h1>
10886
10887 <p>
10888 Here is the complete syntax of Lua in extended BNF.
10889 As usual in extended BNF,
10890 {A} means 0 or more As,
10891 and [A] means an optional A.
10892 (For operator precedences, see <a href="#3.4.8">&sect;3.4.8</a>;
10893 for a description of the terminals
10894 Name, Numeral,
10895 and LiteralString, see <a href="#3.1">&sect;3.1</a>.)
10896
10897
10898
10899
10900 <pre>
10901
10902         chunk ::= block
10903
10904         block ::= {stat} [retstat]
10905
10906         stat ::=  &lsquo;<b>;</b>&rsquo; |
10907                  varlist &lsquo;<b>=</b>&rsquo; explist |
10908                  functioncall |
10909                  label |
10910                  <b>break</b> |
10911                  <b>goto</b> Name |
10912                  <b>do</b> block <b>end</b> |
10913                  <b>while</b> exp <b>do</b> block <b>end</b> |
10914                  <b>repeat</b> block <b>until</b> exp |
10915                  <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> |
10916                  <b>for</b> Name &lsquo;<b>=</b>&rsquo; exp &lsquo;<b>,</b>&rsquo; exp [&lsquo;<b>,</b>&rsquo; exp] <b>do</b> block <b>end</b> |
10917                  <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> |
10918                  <b>function</b> funcname funcbody |
10919                  <b>local</b> <b>function</b> Name funcbody |
10920                  <b>local</b> namelist [&lsquo;<b>=</b>&rsquo; explist]
10921
10922         retstat ::= <b>return</b> [explist] [&lsquo;<b>;</b>&rsquo;]
10923
10924         label ::= &lsquo;<b>::</b>&rsquo; Name &lsquo;<b>::</b>&rsquo;
10925
10926         funcname ::= Name {&lsquo;<b>.</b>&rsquo; Name} [&lsquo;<b>:</b>&rsquo; Name]
10927
10928         varlist ::= var {&lsquo;<b>,</b>&rsquo; var}
10929
10930         var ::=  Name | prefixexp &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo; | prefixexp &lsquo;<b>.</b>&rsquo; Name
10931
10932         namelist ::= Name {&lsquo;<b>,</b>&rsquo; Name}
10933
10934         explist ::= exp {&lsquo;<b>,</b>&rsquo; exp}
10935
10936         exp ::=  <b>nil</b> | <b>false</b> | <b>true</b> | Numeral | LiteralString | &lsquo;<b>...</b>&rsquo; | functiondef |
10937                  prefixexp | tableconstructor | exp binop exp | unop exp
10938
10939         prefixexp ::= var | functioncall | &lsquo;<b>(</b>&rsquo; exp &lsquo;<b>)</b>&rsquo;
10940
10941         functioncall ::=  prefixexp args | prefixexp &lsquo;<b>:</b>&rsquo; Name args
10942
10943         args ::=  &lsquo;<b>(</b>&rsquo; [explist] &lsquo;<b>)</b>&rsquo; | tableconstructor | LiteralString
10944
10945         functiondef ::= <b>function</b> funcbody
10946
10947         funcbody ::= &lsquo;<b>(</b>&rsquo; [parlist] &lsquo;<b>)</b>&rsquo; block <b>end</b>
10948
10949         parlist ::= namelist [&lsquo;<b>,</b>&rsquo; &lsquo;<b>...</b>&rsquo;] | &lsquo;<b>...</b>&rsquo;
10950
10951         tableconstructor ::= &lsquo;<b>{</b>&rsquo; [fieldlist] &lsquo;<b>}</b>&rsquo;
10952
10953         fieldlist ::= field {fieldsep field} [fieldsep]
10954
10955         field ::= &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo; &lsquo;<b>=</b>&rsquo; exp | Name &lsquo;<b>=</b>&rsquo; exp | exp
10956
10957         fieldsep ::= &lsquo;<b>,</b>&rsquo; | &lsquo;<b>;</b>&rsquo;
10958
10959         binop ::=  &lsquo;<b>+</b>&rsquo; | &lsquo;<b>-</b>&rsquo; | &lsquo;<b>*</b>&rsquo; | &lsquo;<b>/</b>&rsquo; | &lsquo;<b>//</b>&rsquo; | &lsquo;<b>^</b>&rsquo; | &lsquo;<b>%</b>&rsquo; |
10960                  &lsquo;<b>&amp;</b>&rsquo; | &lsquo;<b>~</b>&rsquo; | &lsquo;<b>|</b>&rsquo; | &lsquo;<b>&gt;&gt;</b>&rsquo; | &lsquo;<b>&lt;&lt;</b>&rsquo; | &lsquo;<b>..</b>&rsquo; |
10961                  &lsquo;<b>&lt;</b>&rsquo; | &lsquo;<b>&lt;=</b>&rsquo; | &lsquo;<b>&gt;</b>&rsquo; | &lsquo;<b>&gt;=</b>&rsquo; | &lsquo;<b>==</b>&rsquo; | &lsquo;<b>~=</b>&rsquo; |
10962                  <b>and</b> | <b>or</b>
10963
10964         unop ::= &lsquo;<b>-</b>&rsquo; | <b>not</b> | &lsquo;<b>#</b>&rsquo; | &lsquo;<b>~</b>&rsquo;
10965
10966 </pre>
10967
10968 <p>
10969
10970
10971
10972
10973
10974
10975
10976 <P CLASS="footer">
10977 Last update:
10978 Mon Jan  9 13:30:53 BRST 2017
10979 </P>
10980 <!--
10981 Last change: revised for Lua 5.3.4
10982 -->
10983
10984 </body></html>
10985