ceph/src/civetweb/src/third_party/lua-5.3.3/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;2016 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.162 2016/05/30 15:57:03 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, sequences,
 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 We use the term <em>sequence</em> to denote a table where
 230 the set of all positive numeric keys is equal to {1..<em>n</em>}
 231 for some non-negative integer <em>n</em>,
 232 which is called the length of the sequence (see <a href="#3.4.7">&sect;3.4.7</a>).
 233
 234
 235 <p>
 236 Like indices,
 237 the values of table fields can be of any type.
 238 In particular,
 239 because functions are first-class values,
 240 table fields can contain functions.
 241 Thus tables can also carry <em>methods</em> (see <a href="#3.4.11">&sect;3.4.11</a>).
 242
 243
 244 <p>
 245 The indexing of tables follows
 246 the definition of raw equality in the language.
 247 The expressions <code>a[i]</code> and <code>a[j]</code>
 248 denote the same table element
 249 if and only if <code>i</code> and <code>j</code> are raw equal
 250 (that is, equal without metamethods).
 251 In particular, floats with integral values
 252 are equal to their respective integers
 253 (e.g., <code>1.0 == 1</code>).
 254 To avoid ambiguities,
 255 any float with integral value used as a key
 256 is converted to its respective integer.
 257 For instance, if you write <code>a[2.0] = true</code>,
 258 the actual key inserted into the table will be the
 259 integer <code>2</code>.
 260 (On the other hand,
 261 2 and "<code>2</code>" are different Lua values and therefore
 262 denote different table entries.)
 263
 264
 265 <p>
 266 Tables, functions, threads, and (full) userdata values are <em>objects</em>:
 267 variables do not actually <em>contain</em> these values,
 268 only <em>references</em> to them.
 269 Assignment, parameter passing, and function returns
 270 always manipulate references to such values;
 271 these operations do not imply any kind of copy.
 272
 273
 274 <p>
 275 The library function <a href="#pdf-type"><code>type</code></a> returns a string describing the type
 276 of a given value (see <a href="#6.1">&sect;6.1</a>).
 277
 278
 279
 280
 281
 282 <h2>2.2 &ndash; <a name="2.2">Environments and the Global Environment</a></h2>
 283
 284 <p>
 285 As will be discussed in <a href="#3.2">&sect;3.2</a> and <a href="#3.3.3">&sect;3.3.3</a>,
 286 any reference to a free name
 287 (that is, a name not bound to any declaration) <code>var</code>
 288 is syntactically translated to <code>_ENV.var</code>.
 289 Moreover, every chunk is compiled in the scope of
 290 an external local variable named <code>_ENV</code> (see <a href="#3.3.2">&sect;3.3.2</a>),
 291 so <code>_ENV</code> itself is never a free name in a chunk.
 292
 293
 294 <p>
 295 Despite the existence of this external <code>_ENV</code> variable and
 296 the translation of free names,
 297 <code>_ENV</code> is a completely regular name.
 298 In particular,
 299 you can define new variables and parameters with that name.
 300 Each reference to a free name uses the <code>_ENV</code> that is
 301 visible at that point in the program,
 302 following the usual visibility rules of Lua (see <a href="#3.5">&sect;3.5</a>).
 303
 304
 305 <p>
 306 Any table used as the value of <code>_ENV</code> is called an <em>environment</em>.
 307
 308
 309 <p>
 310 Lua keeps a distinguished environment called the <em>global environment</em>.
 311 This value is kept at a special index in the C registry (see <a href="#4.5">&sect;4.5</a>).
 312 In Lua, the global variable <a href="#pdf-_G"><code>_G</code></a> is initialized with this same value.
 313 (<a href="#pdf-_G"><code>_G</code></a> is never used internally.)
 314
 315
 316 <p>
 317 When Lua loads a chunk,
 318 the default value for its <code>_ENV</code> upvalue
 319 is the global environment (see <a href="#pdf-load"><code>load</code></a>).
 320 Therefore, by default,
 321 free names in Lua code refer to entries in the global environment
 322 (and, therefore, they are also called <em>global variables</em>).
 323 Moreover, all standard libraries are loaded in the global environment
 324 and some functions there operate on that environment.
 325 You can use <a href="#pdf-load"><code>load</code></a> (or <a href="#pdf-loadfile"><code>loadfile</code></a>)
 326 to load a chunk with a different environment.
 327 (In C, you have to load the chunk and then change the value
 328 of its first upvalue.)
 329
 330
 331
 332
 333
 334 <h2>2.3 &ndash; <a name="2.3">Error Handling</a></h2>
 335
 336 <p>
 337 Because Lua is an embedded extension language,
 338 all Lua actions start from C&nbsp;code in the host program
 339 calling a function from the Lua library.
 340 (When you use Lua standalone,
 341 the <code>lua</code> application is the host program.)
 342 Whenever an error occurs during
 343 the compilation or execution of a Lua chunk,
 344 control returns to the host,
 345 which can take appropriate measures
 346 (such as printing an error message).
 347
 348
 349 <p>
 350 Lua code can explicitly generate an error by calling the
 351 <a href="#pdf-error"><code>error</code></a> function.
 352 If you need to catch errors in Lua,
 353 you can use <a href="#pdf-pcall"><code>pcall</code></a> or <a href="#pdf-xpcall"><code>xpcall</code></a>
 354 to call a given function in <em>protected mode</em>.
 355
 356
 357 <p>
 358 Whenever there is an error,
 359 an <em>error object</em> (also called an <em>error message</em>)
 360 is propagated with information about the error.
 361 Lua itself only generates errors whose error object is a string,
 362 but programs may generate errors with
 363 any value as the error object.
 364 It is up to the Lua program or its host to handle such error objects.
 365
 366
 367 <p>
 368 When you use <a href="#pdf-xpcall"><code>xpcall</code></a> or <a href="#lua_pcall"><code>lua_pcall</code></a>,
 369 you may give a <em>message handler</em>
 370 to be called in case of errors.
 371 This function is called with the original error object
 372 and returns a new error object.
 373 It is called before the error unwinds the stack,
 374 so that it can gather more information about the error,
 375 for instance by inspecting the stack and creating a stack traceback.
 376 This message handler is still protected by the protected call;
 377 so, an error inside the message handler
 378 will call the message handler again.
 379 If this loop goes on for too long,
 380 Lua breaks it and returns an appropriate message.
 381
 382
 383
 384
 385
 386 <h2>2.4 &ndash; <a name="2.4">Metatables and Metamethods</a></h2>
 387
 388 <p>
 389 Every value in Lua can have a <em>metatable</em>.
 390 This <em>metatable</em> is an ordinary Lua table
 391 that defines the behavior of the original value
 392 under certain special operations.
 393 You can change several aspects of the behavior
 394 of operations over a value by setting specific fields in its metatable.
 395 For instance, when a non-numeric value is the operand of an addition,
 396 Lua checks for a function in the field "<code>__add</code>" of the value's metatable.
 397 If it finds one,
 398 Lua calls this function to perform the addition.
 399
 400
 401 <p>
 402 The key for each event in a metatable is a string
 403 with the event name prefixed by two underscores;
 404 the corresponding values are called <em>metamethods</em>.
 405 In the previous example, the key is "<code>__add</code>"
 406 and the metamethod is the function that performs the addition.
 407
 408
 409 <p>
 410 You can query the metatable of any value
 411 using the <a href="#pdf-getmetatable"><code>getmetatable</code></a> function.
 412 Lua queries metamethods in metatables using a raw access (see <a href="#pdf-rawget"><code>rawget</code></a>).
 413 So, to retrieve the metamethod for event <code>ev</code> in object <code>o</code>,
 414 Lua does the equivalent to the following code:
 415
 416 <pre>
 417      rawget(getmetatable(<em>o</em>) or {}, "__<em>ev</em>")
 418 </pre>
 419
 420 <p>
 421 You can replace the metatable of tables
 422 using the <a href="#pdf-setmetatable"><code>setmetatable</code></a> function.
 423 You cannot change the metatable of other types from Lua code
 424 (except by using the debug library (<a href="#6.10">&sect;6.10</a>));
 425 you should use the C&nbsp;API for that.
 426
 427
 428 <p>
 429 Tables and full userdata have individual metatables
 430 (although multiple tables and userdata can share their metatables).
 431 Values of all other types share one single metatable per type;
 432 that is, there is one single metatable for all numbers,
 433 one for all strings, etc.
 434 By default, a value has no metatable,
 435 but the string library sets a metatable for the string type (see <a href="#6.4">&sect;6.4</a>).
 436
 437
 438 <p>
 439 A metatable controls how an object behaves in
 440 arithmetic operations, bitwise operations,
 441 order comparisons, concatenation, length operation, calls, and indexing.
 442 A metatable also can define a function to be called
 443 when a userdata or a table is garbage collected (<a href="#2.5">&sect;2.5</a>).
 444
 445
 446 <p>
 447 For the unary operators (negation, length, and bitwise NOT),
 448 the metamethod is computed and called with a dummy second operand,
 449 equal to the first one.
 450 This extra operand is only to simplify Lua's internals
 451 (by making these operators behave like a binary operation)
 452 and may be removed in future versions.
 453 (For most uses this extra operand is irrelevant.)
 454
 455
 456 <p>
 457 A detailed list of events controlled by metatables is given next.
 458 Each operation is identified by its corresponding key.
 459
 460
 461
 462 <ul>
 463
 464 <li><b><code>__add</code>: </b>
 465 the addition (<code>+</code>) operation.
 466 If any operand for an addition is not a number
 467 (nor a string coercible to a number),
 468 Lua will try to call a metamethod.
 469 First, Lua will check the first operand (even if it is valid).
 470 If that operand does not define a metamethod for <code>__add</code>,
 471 then Lua will check the second operand.
 472 If Lua can find a metamethod,
 473 it calls the metamethod with the two operands as arguments,
 474 and the result of the call
 475 (adjusted to one value)
 476 is the result of the operation.
 477 Otherwise,
 478 it raises an error.
 479 </li>
 480
 481 <li><b><code>__sub</code>: </b>
 482 the subtraction (<code>-</code>) operation.
 483 Behavior similar to the addition operation.
 484 </li>
 485
 486 <li><b><code>__mul</code>: </b>
 487 the multiplication (<code>*</code>) operation.
 488 Behavior similar to the addition operation.
 489 </li>
 490
 491 <li><b><code>__div</code>: </b>
 492 the division (<code>/</code>) operation.
 493 Behavior similar to the addition operation.
 494 </li>
 495
 496 <li><b><code>__mod</code>: </b>
 497 the modulo (<code>%</code>) operation.
 498 Behavior similar to the addition operation.
 499 </li>
 500
 501 <li><b><code>__pow</code>: </b>
 502 the exponentiation (<code>^</code>) operation.
 503 Behavior similar to the addition operation.
 504 </li>
 505
 506 <li><b><code>__unm</code>: </b>
 507 the negation (unary <code>-</code>) operation.
 508 Behavior similar to the addition operation.
 509 </li>
 510
 511 <li><b><code>__idiv</code>: </b>
 512 the floor division (<code>//</code>) operation.
 513 Behavior similar to the addition operation.
 514 </li>
 515
 516 <li><b><code>__band</code>: </b>
 517 the bitwise AND (<code>&amp;</code>) operation.
 518 Behavior similar to the addition operation,
 519 except that Lua will try a metamethod
 520 if any operand is neither an integer
 521 nor a value coercible to an integer (see <a href="#3.4.3">&sect;3.4.3</a>).
 522 </li>
 523
 524 <li><b><code>__bor</code>: </b>
 525 the bitwise OR (<code>|</code>) operation.
 526 Behavior similar to the bitwise AND operation.
 527 </li>
 528
 529 <li><b><code>__bxor</code>: </b>
 530 the bitwise exclusive OR (binary <code>~</code>) operation.
 531 Behavior similar to the bitwise AND operation.
 532 </li>
 533
 534 <li><b><code>__bnot</code>: </b>
 535 the bitwise NOT (unary <code>~</code>) operation.
 536 Behavior similar to the bitwise AND operation.
 537 </li>
 538
 539 <li><b><code>__shl</code>: </b>
 540 the bitwise left shift (<code>&lt;&lt;</code>) operation.
 541 Behavior similar to the bitwise AND operation.
 542 </li>
 543
 544 <li><b><code>__shr</code>: </b>
 545 the bitwise right shift (<code>&gt;&gt;</code>) operation.
 546 Behavior similar to the bitwise AND operation.
 547 </li>
 548
 549 <li><b><code>__concat</code>: </b>
 550 the concatenation (<code>..</code>) operation.
 551 Behavior similar to the addition operation,
 552 except that Lua will try a metamethod
 553 if any operand is neither a string nor a number
 554 (which is always coercible to a string).
 555 </li>
 556
 557 <li><b><code>__len</code>: </b>
 558 the length (<code>#</code>) operation.
 559 If the object is not a string,
 560 Lua will try its metamethod.
 561 If there is a metamethod,
 562 Lua calls it with the object as argument,
 563 and the result of the call
 564 (always adjusted to one value)
 565 is the result of the operation.
 566 If there is no metamethod but the object is a table,
 567 then Lua uses the table length operation (see <a href="#3.4.7">&sect;3.4.7</a>).
 568 Otherwise, Lua raises an error.
 569 </li>
 570
 571 <li><b><code>__eq</code>: </b>
 572 the equal (<code>==</code>) operation.
 573 Behavior similar to the addition operation,
 574 except that Lua will try a metamethod only when the values
 575 being compared are either both tables or both full userdata
 576 and they are not primitively equal.
 577 The result of the call is always converted to a boolean.
 578 </li>
 579
 580 <li><b><code>__lt</code>: </b>
 581 the less than (<code>&lt;</code>) operation.
 582 Behavior similar to the addition operation,
 583 except that Lua will try a metamethod only when the values
 584 being compared are neither both numbers nor both strings.
 585 The result of the call is always converted to a boolean.
 586 </li>
 587
 588 <li><b><code>__le</code>: </b>
 589 the less equal (<code>&lt;=</code>) operation.
 590 Unlike other operations,
 591 the less-equal operation can use two different events.
 592 First, Lua looks for the <code>__le</code> metamethod in both operands,
 593 like in the less than operation.
 594 If it cannot find such a metamethod,
 595 then it will try the <code>__lt</code> metamethod,
 596 assuming that <code>a &lt;= b</code> is equivalent to <code>not (b &lt; a)</code>.
 597 As with the other comparison operators,
 598 the result is always a boolean.
 599 (This use of the <code>__lt</code> event can be removed in future versions;
 600 it is also slower than a real <code>__le</code> metamethod.)
 601 </li>
 602
 603 <li><b><code>__index</code>: </b>
 604 The indexing access <code>table[key]</code>.
 605 This event happens when <code>table</code> is not a table or
 606 when <code>key</code> is not present in <code>table</code>.
 607 The metamethod is looked up in <code>table</code>.
 608
 609
 610 <p>
 611 Despite the name,
 612 the metamethod for this event can be either a function or a table.
 613 If it is a function,
 614 it is called with <code>table</code> and <code>key</code> as arguments,
 615 and the result of the call
 616 (adjusted to one value)
 617 is the result of the operation.
 618 If it is a table,
 619 the final result is the result of indexing this table with <code>key</code>.
 620 (This indexing is regular, not raw,
 621 and therefore can trigger another metamethod.)
 622 </li>
 623
 624 <li><b><code>__newindex</code>: </b>
 625 The indexing assignment <code>table[key] = value</code>.
 626 Like the index event,
 627 this event happens when <code>table</code> is not a table or
 628 when <code>key</code> is not present in <code>table</code>.
 629 The metamethod is looked up in <code>table</code>.
 630
 631
 632 <p>
 633 Like with indexing,
 634 the metamethod for this event can be either a function or a table.
 635 If it is a function,
 636 it is called with <code>table</code>, <code>key</code>, and <code>value</code> as arguments.
 637 If it is a table,
 638 Lua does an indexing assignment to this table with the same key and value.
 639 (This assignment is regular, not raw,
 640 and therefore can trigger another metamethod.)
 641
 642
 643 <p>
 644 Whenever there is a <code>__newindex</code> metamethod,
 645 Lua does not perform the primitive assignment.
 646 (If necessary,
 647 the metamethod itself can call <a href="#pdf-rawset"><code>rawset</code></a>
 648 to do the assignment.)
 649 </li>
 650
 651 <li><b><code>__call</code>: </b>
 652 The call operation <code>func(args)</code>.
 653 This event happens when Lua tries to call a non-function value
 654 (that is, <code>func</code> is not a function).
 655 The metamethod is looked up in <code>func</code>.
 656 If present,
 657 the metamethod is called with <code>func</code> as its first argument,
 658 followed by the arguments of the original call (<code>args</code>).
 659 All results of the call
 660 are the result of the operation.
 661 (This is the only metamethod that allows multiple results.)
 662 </li>
 663
 664 </ul>
 665
 666 <p>
 667 It is a good practice to add all needed metamethods to a table
 668 before setting it as a metatable of some object.
 669 In particular, the <code>__gc</code> metamethod works only when this order
 670 is followed (see <a href="#2.5.1">&sect;2.5.1</a>).
 671
 672
 673 <p>
 674 Because metatables are regular tables,
 675 they can contain arbitrary fields,
 676 not only the event names defined above.
 677 Some functions in the standard library
 678 (e.g., <a href="#pdf-tostring"><code>tostring</code></a>)
 679 use other fields in metatables for their own purposes.
 680
 681
 682
 683
 684
 685 <h2>2.5 &ndash; <a name="2.5">Garbage Collection</a></h2>
 686
 687 <p>
 688 Lua performs automatic memory management.
 689 This means that
 690 you do not have to worry about allocating memory for new objects
 691 or freeing it when the objects are no longer needed.
 692 Lua manages memory automatically by running
 693 a <em>garbage collector</em> to collect all <em>dead objects</em>
 694 (that is, objects that are no longer accessible from Lua).
 695 All memory used by Lua is subject to automatic management:
 696 strings, tables, userdata, functions, threads, internal structures, etc.
 697
 698
 699 <p>
 700 Lua implements an incremental mark-and-sweep collector.
 701 It uses two numbers to control its garbage-collection cycles:
 702 the <em>garbage-collector pause</em> and
 703 the <em>garbage-collector step multiplier</em>.
 704 Both use percentage points as units
 705 (e.g., a value of 100 means an internal value of 1).
 706
 707
 708 <p>
 709 The garbage-collector pause
 710 controls how long the collector waits before starting a new cycle.
 711 Larger values make the collector less aggressive.
 712 Values smaller than 100 mean the collector will not wait to
 713 start a new cycle.
 714 A value of 200 means that the collector waits for the total memory in use
 715 to double before starting a new cycle.
 716
 717
 718 <p>
 719 The garbage-collector step multiplier
 720 controls the relative speed of the collector relative to
 721 memory allocation.
 722 Larger values make the collector more aggressive but also increase
 723 the size of each incremental step.
 724 You should not use values smaller than 100,
 725 because they make the collector too slow and
 726 can result in the collector never finishing a cycle.
 727 The default is 200,
 728 which means that the collector runs at "twice"
 729 the speed of memory allocation.
 730
 731
 732 <p>
 733 If you set the step multiplier to a very large number
 734 (larger than 10% of the maximum number of
 735 bytes that the program may use),
 736 the collector behaves like a stop-the-world collector.
 737 If you then set the pause to 200,
 738 the collector behaves as in old Lua versions,
 739 doing a complete collection every time Lua doubles its
 740 memory usage.
 741
 742
 743 <p>
 744 You can change these numbers by calling <a href="#lua_gc"><code>lua_gc</code></a> in C
 745 or <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> in Lua.
 746 You can also use these functions to control
 747 the collector directly (e.g., stop and restart it).
 748
 749
 750
 751 <h3>2.5.1 &ndash; <a name="2.5.1">Garbage-Collection Metamethods</a></h3>
 752
 753 <p>
 754 You can set garbage-collector metamethods for tables
 755 and, using the C&nbsp;API,
 756 for full userdata (see <a href="#2.4">&sect;2.4</a>).
 757 These metamethods are also called <em>finalizers</em>.
 758 Finalizers allow you to coordinate Lua's garbage collection
 759 with external resource management
 760 (such as closing files, network or database connections,
 761 or freeing your own memory).
 762
 763
 764 <p>
 765 For an object (table or userdata) to be finalized when collected,
 766 you must <em>mark</em> it for finalization.
 767
 768 You mark an object for finalization when you set its metatable
 769 and the metatable has a field indexed by the string "<code>__gc</code>".
 770 Note that if you set a metatable without a <code>__gc</code> field
 771 and later create that field in the metatable,
 772 the object will not be marked for finalization.
 773
 774
 775 <p>
 776 When a marked object becomes garbage,
 777 it is not collected immediately by the garbage collector.
 778 Instead, Lua puts it in a list.
 779 After the collection,
 780 Lua goes through that list.
 781 For each object in the list,
 782 it checks the object's <code>__gc</code> metamethod:
 783 If it is a function,
 784 Lua calls it with the object as its single argument;
 785 if the metamethod is not a function,
 786 Lua simply ignores it.
 787
 788
 789 <p>
 790 At the end of each garbage-collection cycle,
 791 the finalizers for objects are called in
 792 the reverse order that the objects were marked for finalization,
 793 among those collected in that cycle;
 794 that is, the first finalizer to be called is the one associated
 795 with the object marked last in the program.
 796 The execution of each finalizer may occur at any point during
 797 the execution of the regular code.
 798
 799
 800 <p>
 801 Because the object being collected must still be used by the finalizer,
 802 that object (and other objects accessible only through it)
 803 must be <em>resurrected</em> by Lua.
 804 Usually, this resurrection is transient,
 805 and the object memory is freed in the next garbage-collection cycle.
 806 However, if the finalizer stores the object in some global place
 807 (e.g., a global variable),
 808 then the resurrection is permanent.
 809 Moreover, if the finalizer marks a finalizing object for finalization again,
 810 its finalizer will be called again in the next cycle where the
 811 object is unreachable.
 812 In any case,
 813 the object memory is freed only in a GC cycle where
 814 the object is unreachable and not marked for finalization.
 815
 816
 817 <p>
 818 When you close a state (see <a href="#lua_close"><code>lua_close</code></a>),
 819 Lua calls the finalizers of all objects marked for finalization,
 820 following the reverse order that they were marked.
 821 If any finalizer marks objects for collection during that phase,
 822 these marks have no effect.
 823
 824
 825
 826
 827
 828 <h3>2.5.2 &ndash; <a name="2.5.2">Weak Tables</a></h3>
 829
 830 <p>
 831 A <em>weak table</em> is a table whose elements are
 832 <em>weak references</em>.
 833 A weak reference is ignored by the garbage collector.
 834 In other words,
 835 if the only references to an object are weak references,
 836 then the garbage collector will collect that object.
 837
 838
 839 <p>
 840 A weak table can have weak keys, weak values, or both.
 841 A table with weak values allows the collection of its values,
 842 but prevents the collection of its keys.
 843 A table with both weak keys and weak values allows the collection of
 844 both keys and values.
 845 In any case, if either the key or the value is collected,
 846 the whole pair is removed from the table.
 847 The weakness of a table is controlled by the
 848 <code>__mode</code> field of its metatable.
 849 If the <code>__mode</code> field is a string containing the character&nbsp;'<code>k</code>',
 850 the keys in the table are weak.
 851 If <code>__mode</code> contains '<code>v</code>',
 852 the values in the table are weak.
 853
 854
 855 <p>
 856 A table with weak keys and strong values
 857 is also called an <em>ephemeron table</em>.
 858 In an ephemeron table,
 859 a value is considered reachable only if its key is reachable.
 860 In particular,
 861 if the only reference to a key comes through its value,
 862 the pair is removed.
 863
 864
 865 <p>
 866 Any change in the weakness of a table may take effect only
 867 at the next collect cycle.
 868 In particular, if you change the weakness to a stronger mode,
 869 Lua may still collect some items from that table
 870 before the change takes effect.
 871
 872
 873 <p>
 874 Only objects that have an explicit construction
 875 are removed from weak tables.
 876 Values, such as numbers and light C functions,
 877 are not subject to garbage collection,
 878 and therefore are not removed from weak tables
 879 (unless their associated values are collected).
 880 Although strings are subject to garbage collection,
 881 they do not have an explicit construction,
 882 and therefore are not removed from weak tables.
 883
 884
 885 <p>
 886 Resurrected objects
 887 (that is, objects being finalized
 888 and objects accessible only through objects being finalized)
 889 have a special behavior in weak tables.
 890 They are removed from weak values before running their finalizers,
 891 but are removed from weak keys only in the next collection
 892 after running their finalizers, when such objects are actually freed.
 893 This behavior allows the finalizer to access properties
 894 associated with the object through weak tables.
 895
 896
 897 <p>
 898 If a weak table is among the resurrected objects in a collection cycle,
 899 it may not be properly cleared until the next cycle.
 900
 901
 902
 903
 904
 905
 906
 907 <h2>2.6 &ndash; <a name="2.6">Coroutines</a></h2>
 908
 909 <p>
 910 Lua supports coroutines,
 911 also called <em>collaborative multithreading</em>.
 912 A coroutine in Lua represents an independent thread of execution.
 913 Unlike threads in multithread systems, however,
 914 a coroutine only suspends its execution by explicitly calling
 915 a yield function.
 916
 917
 918 <p>
 919 You create a coroutine by calling <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>.
 920 Its sole argument is a function
 921 that is the main function of the coroutine.
 922 The <code>create</code> function only creates a new coroutine and
 923 returns a handle to it (an object of type <em>thread</em>);
 924 it does not start the coroutine.
 925
 926
 927 <p>
 928 You execute a coroutine by calling <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>.
 929 When you first call <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>,
 930 passing as its first argument
 931 a thread returned by <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>,
 932 the coroutine starts its execution by
 933 calling its main function.
 934 Extra arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> are passed
 935 as arguments to that function.
 936 After the coroutine starts running,
 937 it runs until it terminates or <em>yields</em>.
 938
 939
 940 <p>
 941 A coroutine can terminate its execution in two ways:
 942 normally, when its main function returns
 943 (explicitly or implicitly, after the last instruction);
 944 and abnormally, if there is an unprotected error.
 945 In case of normal termination,
 946 <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>true</b>,
 947 plus any values returned by the coroutine main function.
 948 In case of errors, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>false</b>
 949 plus an error object.
 950
 951
 952 <p>
 953 A coroutine yields by calling <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>.
 954 When a coroutine yields,
 955 the corresponding <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns immediately,
 956 even if the yield happens inside nested function calls
 957 (that is, not in the main function,
 958 but in a function directly or indirectly called by the main function).
 959 In the case of a yield, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> also returns <b>true</b>,
 960 plus any values passed to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>.
 961 The next time you resume the same coroutine,
 962 it continues its execution from the point where it yielded,
 963 with the call to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a> returning any extra
 964 arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>.
 965
 966
 967 <p>
 968 Like <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>,
 969 the <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> function also creates a coroutine,
 970 but instead of returning the coroutine itself,
 971 it returns a function that, when called, resumes the coroutine.
 972 Any arguments passed to this function
 973 go as extra arguments to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>.
 974 <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>,
 975 except the first one (the boolean error code).
 976 Unlike <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>,
 977 <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> does not catch errors;
 978 any error is propagated to the caller.
 979
 980
 981 <p>
 982 As an example of how coroutines work,
 983 consider the following code:
 984
 985 <pre>
 986      function foo (a)
 987        print("foo", a)
 988        return coroutine.yield(2*a)
 989      end
 990
 991      co = coroutine.create(function (a,b)
 992            print("co-body", a, b)
 993            local r = foo(a+1)
 994            print("co-body", r)
 995            local r, s = coroutine.yield(a+b, a-b)
 996            print("co-body", r, s)
 997            return b, "end"
 998      end)
 999
1000      print("main", coroutine.resume(co, 1, 10))
1001      print("main", coroutine.resume(co, "r"))
1002      print("main", coroutine.resume(co, "x", "y"))
1003      print("main", coroutine.resume(co, "x", "y"))
1004 </pre><p>
1005 When you run it, it produces the following output:
1006
1007 <pre>
1008      co-body 1       10
1009      foo     2
1010      main    true    4
1011      co-body r
1012      main    true    11      -9
1013      co-body x       y
1014      main    true    10      end
1015      main    false   cannot resume dead coroutine
1016 </pre>
1017
1018 <p>
1019 You can also create and manipulate coroutines through the C API:
1020 see functions <a href="#lua_newthread"><code>lua_newthread</code></a>, <a href="#lua_resume"><code>lua_resume</code></a>,
1021 and <a href="#lua_yield"><code>lua_yield</code></a>.
1022
1023
1024
1025
1026
1027 <h1>3 &ndash; <a name="3">The Language</a></h1>
1028
1029 <p>
1030 This section describes the lexis, the syntax, and the semantics of Lua.
1031 In other words,
1032 this section describes
1033 which tokens are valid,
1034 how they can be combined,
1035 and what their combinations mean.
1036
1037
1038 <p>
1039 Language constructs will be explained using the usual extended BNF notation,
1040 in which
1041 {<em>a</em>}&nbsp;means&nbsp;0 or more <em>a</em>'s, and
1042 [<em>a</em>]&nbsp;means an optional <em>a</em>.
1043 Non-terminals are shown like non-terminal,
1044 keywords are shown like <b>kword</b>,
1045 and other terminal symbols are shown like &lsquo;<b>=</b>&rsquo;.
1046 The complete syntax of Lua can be found in <a href="#9">&sect;9</a>
1047 at the end of this manual.
1048
1049
1050
1051 <h2>3.1 &ndash; <a name="3.1">Lexical Conventions</a></h2>
1052
1053 <p>
1054 Lua is a free-form language.
1055 It ignores spaces (including new lines) and comments
1056 between lexical elements (tokens),
1057 except as delimiters between names and keywords.
1058
1059
1060 <p>
1061 <em>Names</em>
1062 (also called <em>identifiers</em>)
1063 in Lua can be any string of letters,
1064 digits, and underscores,
1065 not beginning with a digit and
1066 not being a reserved word.
1067 Identifiers are used to name variables, table fields, and labels.
1068
1069
1070 <p>
1071 The following <em>keywords</em> are reserved
1072 and cannot be used as names:
1073
1074
1075 <pre>
1076      and       break     do        else      elseif    end
1077      false     for       function  goto      if        in
1078      local     nil       not       or        repeat    return
1079      then      true      until     while
1080 </pre>
1081
1082 <p>
1083 Lua is a case-sensitive language:
1084 <code>and</code> is a reserved word, but <code>And</code> and <code>AND</code>
1085 are two different, valid names.
1086 As a convention,
1087 programs should avoid creating
1088 names that start with an underscore followed by
1089 one or more uppercase letters (such as <a href="#pdf-_VERSION"><code>_VERSION</code></a>).
1090
1091
1092 <p>
1093 The following strings denote other tokens:
1094
1095 <pre>
1096      +     -     *     /     %     ^     #
1097      &amp;     ~     |     &lt;&lt;    &gt;&gt;    //
1098      ==    ~=    &lt;=    &gt;=    &lt;     &gt;     =
1099      (     )     {     }     [     ]     ::
1100      ;     :     ,     .     ..    ...
1101 </pre>
1102
1103 <p>
1104 <em>Literal strings</em>
1105 can be delimited by matching single or double quotes,
1106 and can contain the following C-like escape sequences:
1107 '<code>\a</code>' (bell),
1108 '<code>\b</code>' (backspace),
1109 '<code>\f</code>' (form feed),
1110 '<code>\n</code>' (newline),
1111 '<code>\r</code>' (carriage return),
1112 '<code>\t</code>' (horizontal tab),
1113 '<code>\v</code>' (vertical tab),
1114 '<code>\\</code>' (backslash),
1115 '<code>\"</code>' (quotation mark [double quote]),
1116 and '<code>\'</code>' (apostrophe [single quote]).
1117 A backslash followed by a real newline
1118 results in a newline in the string.
1119 The escape sequence '<code>\z</code>' skips the following span
1120 of white-space characters,
1121 including line breaks;
1122 it is particularly useful to break and indent a long literal string
1123 into multiple lines without adding the newlines and spaces
1124 into the string contents.
1125
1126
1127 <p>
1128 Strings in Lua can contain any 8-bit value, including embedded zeros,
1129 which can be specified as '<code>\0</code>'.
1130 More generally,
1131 we can specify any byte in a literal string by its numeric value.
1132 This can be done
1133 with the escape sequence <code>\x<em>XX</em></code>,
1134 where <em>XX</em> is a sequence of exactly two hexadecimal digits,
1135 or with the escape sequence <code>\<em>ddd</em></code>,
1136 where <em>ddd</em> is a sequence of up to three decimal digits.
1137 (Note that if a decimal escape sequence is to be followed by a digit,
1138 it must be expressed using exactly three digits.)
1139
1140
1141 <p>
1142 The UTF-8 encoding of a Unicode character
1143 can be inserted in a literal string with
1144 the escape sequence <code>\u{<em>XXX</em>}</code>
1145 (note the mandatory enclosing brackets),
1146 where <em>XXX</em> is a sequence of one or more hexadecimal digits
1147 representing the character code point.
1148
1149
1150 <p>
1151 Literal strings can also be defined using a long format
1152 enclosed by <em>long brackets</em>.
1153 We define an <em>opening long bracket of level <em>n</em></em> as an opening
1154 square bracket followed by <em>n</em> equal signs followed by another
1155 opening square bracket.
1156 So, an opening long bracket of level&nbsp;0 is written as <code>[[</code>,
1157 an opening long bracket of level&nbsp;1 is written as <code>[=[</code>,
1158 and so on.
1159 A <em>closing long bracket</em> is defined similarly;
1160 for instance,
1161 a closing long bracket of level&nbsp;4 is written as  <code>]====]</code>.
1162 A <em>long literal</em> starts with an opening long bracket of any level and
1163 ends at the first closing long bracket of the same level.
1164 It can contain any text except a closing bracket of the same level.
1165 Literals in this bracketed form can run for several lines,
1166 do not interpret any escape sequences,
1167 and ignore long brackets of any other level.
1168 Any kind of end-of-line sequence
1169 (carriage return, newline, carriage return followed by newline,
1170 or newline followed by carriage return)
1171 is converted to a simple newline.
1172
1173
1174 <p>
1175 Any byte in a literal string not
1176 explicitly affected by the previous rules represents itself.
1177 However, Lua opens files for parsing in text mode,
1178 and the system file functions may have problems with
1179 some control characters.
1180 So, it is safer to represent
1181 non-text data as a quoted literal with
1182 explicit escape sequences for the non-text characters.
1183
1184
1185 <p>
1186 For convenience,
1187 when the opening long bracket is immediately followed by a newline,
1188 the newline is not included in the string.
1189 As an example, in a system using ASCII
1190 (in which '<code>a</code>' is coded as&nbsp;97,
1191 newline is coded as&nbsp;10, and '<code>1</code>' is coded as&nbsp;49),
1192 the five literal strings below denote the same string:
1193
1194 <pre>
1195      a = 'alo\n123"'
1196      a = "alo\n123\""
1197      a = '\97lo\10\04923"'
1198      a = [[alo
1199      123"]]
1200      a = [==[
1201      alo
1202      123"]==]
1203 </pre>
1204
1205 <p>
1206 A <em>numeric constant</em> (or <em>numeral</em>)
1207 can be written with an optional fractional part
1208 and an optional decimal exponent,
1209 marked by a letter '<code>e</code>' or '<code>E</code>'.
1210 Lua also accepts hexadecimal constants,
1211 which start with <code>0x</code> or <code>0X</code>.
1212 Hexadecimal constants also accept an optional fractional part
1213 plus an optional binary exponent,
1214 marked by a letter '<code>p</code>' or '<code>P</code>'.
1215 A numeric constant with a radix point or an exponent
1216 denotes a float;
1217 otherwise,
1218 if its value fits in an integer,
1219 it denotes an integer.
1220 Examples of valid integer constants are
1221
1222 <pre>
1223      3   345   0xff   0xBEBADA
1224 </pre><p>
1225 Examples of valid float constants are
1226
1227 <pre>
1228      3.0     3.1416     314.16e-2     0.31416E1     34e1
1229      0x0.1E  0xA23p-4   0X1.921FB54442D18P+1
1230 </pre>
1231
1232 <p>
1233 A <em>comment</em> starts with a double hyphen (<code>--</code>)
1234 anywhere outside a string.
1235 If the text immediately after <code>--</code> is not an opening long bracket,
1236 the comment is a <em>short comment</em>,
1237 which runs until the end of the line.
1238 Otherwise, it is a <em>long comment</em>,
1239 which runs until the corresponding closing long bracket.
1240 Long comments are frequently used to disable code temporarily.
1241
1242
1243
1244
1245
1246 <h2>3.2 &ndash; <a name="3.2">Variables</a></h2>
1247
1248 <p>
1249 Variables are places that store values.
1250 There are three kinds of variables in Lua:
1251 global variables, local variables, and table fields.
1252
1253
1254 <p>
1255 A single name can denote a global variable or a local variable
1256 (or a function's formal parameter,
1257 which is a particular kind of local variable):
1258
1259 <pre>
1260         var ::= Name
1261 </pre><p>
1262 Name denotes identifiers, as defined in <a href="#3.1">&sect;3.1</a>.
1263
1264
1265 <p>
1266 Any variable name is assumed to be global unless explicitly declared
1267 as a local (see <a href="#3.3.7">&sect;3.3.7</a>).
1268 Local variables are <em>lexically scoped</em>:
1269 local variables can be freely accessed by functions
1270 defined inside their scope (see <a href="#3.5">&sect;3.5</a>).
1271
1272
1273 <p>
1274 Before the first assignment to a variable, its value is <b>nil</b>.
1275
1276
1277 <p>
1278 Square brackets are used to index a table:
1279
1280 <pre>
1281         var ::= prefixexp &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo;
1282 </pre><p>
1283 The meaning of accesses to table fields can be changed via metatables.
1284 An access to an indexed variable <code>t[i]</code> is equivalent to
1285 a call <code>gettable_event(t,i)</code>.
1286 (See <a href="#2.4">&sect;2.4</a> for a complete description of the
1287 <code>gettable_event</code> function.
1288 This function is not defined or callable in Lua.
1289 We use it here only for explanatory purposes.)
1290
1291
1292 <p>
1293 The syntax <code>var.Name</code> is just syntactic sugar for
1294 <code>var["Name"]</code>:
1295
1296 <pre>
1297         var ::= prefixexp &lsquo;<b>.</b>&rsquo; Name
1298 </pre>
1299
1300 <p>
1301 An access to a global variable <code>x</code>
1302 is equivalent to <code>_ENV.x</code>.
1303 Due to the way that chunks are compiled,
1304 <code>_ENV</code> is never a global name (see <a href="#2.2">&sect;2.2</a>).
1305
1306
1307
1308
1309
1310 <h2>3.3 &ndash; <a name="3.3">Statements</a></h2>
1311
1312 <p>
1313 Lua supports an almost conventional set of statements,
1314 similar to those in Pascal or C.
1315 This set includes
1316 assignments, control structures, function calls,
1317 and variable declarations.
1318
1319
1320
1321 <h3>3.3.1 &ndash; <a name="3.3.1">Blocks</a></h3>
1322
1323 <p>
1324 A block is a list of statements,
1325 which are executed sequentially:
1326
1327 <pre>
1328         block ::= {stat}
1329 </pre><p>
1330 Lua has <em>empty statements</em>
1331 that allow you to separate statements with semicolons,
1332 start a block with a semicolon
1333 or write two semicolons in sequence:
1334
1335 <pre>
1336         stat ::= &lsquo;<b>;</b>&rsquo;
1337 </pre>
1338
1339 <p>
1340 Function calls and assignments
1341 can start with an open parenthesis.
1342 This possibility leads to an ambiguity in Lua's grammar.
1343 Consider the following fragment:
1344
1345 <pre>
1346      a = b + c
1347      (print or io.write)('done')
1348 </pre><p>
1349 The grammar could see it in two ways:
1350
1351 <pre>
1352      a = b + c(print or io.write)('done')
1353
1354      a = b + c; (print or io.write)('done')
1355 </pre><p>
1356 The current parser always sees such constructions
1357 in the first way,
1358 interpreting the open parenthesis
1359 as the start of the arguments to a call.
1360 To avoid this ambiguity,
1361 it is a good practice to always precede with a semicolon
1362 statements that start with a parenthesis:
1363
1364 <pre>
1365      ;(print or io.write)('done')
1366 </pre>
1367
1368 <p>
1369 A block can be explicitly delimited to produce a single statement:
1370
1371 <pre>
1372         stat ::= <b>do</b> block <b>end</b>
1373 </pre><p>
1374 Explicit blocks are useful
1375 to control the scope of variable declarations.
1376 Explicit blocks are also sometimes used to
1377 add a <b>return</b> statement in the middle
1378 of another block (see <a href="#3.3.4">&sect;3.3.4</a>).
1379
1380
1381
1382
1383
1384 <h3>3.3.2 &ndash; <a name="3.3.2">Chunks</a></h3>
1385
1386 <p>
1387 The unit of compilation of Lua is called a <em>chunk</em>.
1388 Syntactically,
1389 a chunk is simply a block:
1390
1391 <pre>
1392         chunk ::= block
1393 </pre>
1394
1395 <p>
1396 Lua handles a chunk as the body of an anonymous function
1397 with a variable number of arguments
1398 (see <a href="#3.4.11">&sect;3.4.11</a>).
1399 As such, chunks can define local variables,
1400 receive arguments, and return values.
1401 Moreover, such anonymous function is compiled as in the
1402 scope of an external local variable called <code>_ENV</code> (see <a href="#2.2">&sect;2.2</a>).
1403 The resulting function always has <code>_ENV</code> as its only upvalue,
1404 even if it does not use that variable.
1405
1406
1407 <p>
1408 A chunk can be stored in a file or in a string inside the host program.
1409 To execute a chunk,
1410 Lua first <em>loads</em> it,
1411 precompiling the chunk's code into instructions for a virtual machine,
1412 and then Lua executes the compiled code
1413 with an interpreter for the virtual machine.
1414
1415
1416 <p>
1417 Chunks can also be precompiled into binary form;
1418 see program <code>luac</code> and function <a href="#pdf-string.dump"><code>string.dump</code></a> for details.
1419 Programs in source and compiled forms are interchangeable;
1420 Lua automatically detects the file type and acts accordingly (see <a href="#pdf-load"><code>load</code></a>).
1421
1422
1423
1424
1425
1426 <h3>3.3.3 &ndash; <a name="3.3.3">Assignment</a></h3>
1427
1428 <p>
1429 Lua allows multiple assignments.
1430 Therefore, the syntax for assignment
1431 defines a list of variables on the left side
1432 and a list of expressions on the right side.
1433 The elements in both lists are separated by commas:
1434
1435 <pre>
1436         stat ::= varlist &lsquo;<b>=</b>&rsquo; explist
1437         varlist ::= var {&lsquo;<b>,</b>&rsquo; var}
1438         explist ::= exp {&lsquo;<b>,</b>&rsquo; exp}
1439 </pre><p>
1440 Expressions are discussed in <a href="#3.4">&sect;3.4</a>.
1441
1442
1443 <p>
1444 Before the assignment,
1445 the list of values is <em>adjusted</em> to the length of
1446 the list of variables.
1447 If there are more values than needed,
1448 the excess values are thrown away.
1449 If there are fewer values than needed,
1450 the list is extended with as many  <b>nil</b>'s as needed.
1451 If the list of expressions ends with a function call,
1452 then all values returned by that call enter the list of values,
1453 before the adjustment
1454 (except when the call is enclosed in parentheses; see <a href="#3.4">&sect;3.4</a>).
1455
1456
1457 <p>
1458 The assignment statement first evaluates all its expressions
1459 and only then the assignments are performed.
1460 Thus the code
1461
1462 <pre>
1463      i = 3
1464      i, a[i] = i+1, 20
1465 </pre><p>
1466 sets <code>a[3]</code> to 20, without affecting <code>a[4]</code>
1467 because the <code>i</code> in <code>a[i]</code> is evaluated (to 3)
1468 before it is assigned&nbsp;4.
1469 Similarly, the line
1470
1471 <pre>
1472      x, y = y, x
1473 </pre><p>
1474 exchanges the values of <code>x</code> and <code>y</code>,
1475 and
1476
1477 <pre>
1478      x, y, z = y, z, x
1479 </pre><p>
1480 cyclically permutes the values of <code>x</code>, <code>y</code>, and <code>z</code>.
1481
1482
1483 <p>
1484 The meaning of assignments to global variables
1485 and table fields can be changed via metatables.
1486 An assignment to an indexed variable <code>t[i] = val</code> is equivalent to
1487 <code>settable_event(t,i,val)</code>.
1488 (See <a href="#2.4">&sect;2.4</a> for a complete description of the
1489 <code>settable_event</code> function.
1490 This function is not defined or callable in Lua.
1491 We use it here only for explanatory purposes.)
1492
1493
1494 <p>
1495 An assignment to a global name <code>x = val</code>
1496 is equivalent to the assignment
1497 <code>_ENV.x = val</code> (see <a href="#2.2">&sect;2.2</a>).
1498
1499
1500
1501
1502
1503 <h3>3.3.4 &ndash; <a name="3.3.4">Control Structures</a></h3><p>
1504 The control structures
1505 <b>if</b>, <b>while</b>, and <b>repeat</b> have the usual meaning and
1506 familiar syntax:
1507
1508
1509
1510
1511 <pre>
1512         stat ::= <b>while</b> exp <b>do</b> block <b>end</b>
1513         stat ::= <b>repeat</b> block <b>until</b> exp
1514         stat ::= <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b>
1515 </pre><p>
1516 Lua also has a <b>for</b> statement, in two flavors (see <a href="#3.3.5">&sect;3.3.5</a>).
1517
1518
1519 <p>
1520 The condition expression of a
1521 control structure can return any value.
1522 Both <b>false</b> and <b>nil</b> are considered false.
1523 All values different from <b>nil</b> and <b>false</b> are considered true
1524 (in particular, the number 0 and the empty string are also true).
1525
1526
1527 <p>
1528 In the <b>repeat</b>&ndash;<b>until</b> loop,
1529 the inner block does not end at the <b>until</b> keyword,
1530 but only after the condition.
1531 So, the condition can refer to local variables
1532 declared inside the loop block.
1533
1534
1535 <p>
1536 The <b>goto</b> statement transfers the program control to a label.
1537 For syntactical reasons,
1538 labels in Lua are considered statements too:
1539
1540
1541
1542 <pre>
1543         stat ::= <b>goto</b> Name
1544         stat ::= label
1545         label ::= &lsquo;<b>::</b>&rsquo; Name &lsquo;<b>::</b>&rsquo;
1546 </pre>
1547
1548 <p>
1549 A label is visible in the entire block where it is defined,
1550 except
1551 inside nested blocks where a label with the same name is defined and
1552 inside nested functions.
1553 A goto may jump to any visible label as long as it does not
1554 enter into the scope of a local variable.
1555
1556
1557 <p>
1558 Labels and empty statements are called <em>void statements</em>,
1559 as they perform no actions.
1560
1561
1562 <p>
1563 The <b>break</b> statement terminates the execution of a
1564 <b>while</b>, <b>repeat</b>, or <b>for</b> loop,
1565 skipping to the next statement after the loop:
1566
1567
1568 <pre>
1569         stat ::= <b>break</b>
1570 </pre><p>
1571 A <b>break</b> ends the innermost enclosing loop.
1572
1573
1574 <p>
1575 The <b>return</b> statement is used to return values
1576 from a function or a chunk
1577 (which is an anonymous function).
1578
1579 Functions can return more than one value,
1580 so the syntax for the <b>return</b> statement is
1581
1582 <pre>
1583         stat ::= <b>return</b> [explist] [&lsquo;<b>;</b>&rsquo;]
1584 </pre>
1585
1586 <p>
1587 The <b>return</b> statement can only be written
1588 as the last statement of a block.
1589 If it is really necessary to <b>return</b> in the middle of a block,
1590 then an explicit inner block can be used,
1591 as in the idiom <code>do return end</code>,
1592 because now <b>return</b> is the last statement in its (inner) block.
1593
1594
1595
1596
1597
1598 <h3>3.3.5 &ndash; <a name="3.3.5">For Statement</a></h3>
1599
1600 <p>
1601
1602 The <b>for</b> statement has two forms:
1603 one numerical and one generic.
1604
1605
1606 <p>
1607 The numerical <b>for</b> loop repeats a block of code while a
1608 control variable runs through an arithmetic progression.
1609 It has the following syntax:
1610
1611 <pre>
1612         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>
1613 </pre><p>
1614 The <em>block</em> is repeated for <em>name</em> starting at the value of
1615 the first <em>exp</em>, until it passes the second <em>exp</em> by steps of the
1616 third <em>exp</em>.
1617 More precisely, a <b>for</b> statement like
1618
1619 <pre>
1620      for v = <em>e1</em>, <em>e2</em>, <em>e3</em> do <em>block</em> end
1621 </pre><p>
1622 is equivalent to the code:
1623
1624 <pre>
1625      do
1626        local <em>var</em>, <em>limit</em>, <em>step</em> = tonumber(<em>e1</em>), tonumber(<em>e2</em>), tonumber(<em>e3</em>)
1627        if not (<em>var</em> and <em>limit</em> and <em>step</em>) then error() end
1628        <em>var</em> = <em>var</em> - <em>step</em>
1629        while true do
1630          <em>var</em> = <em>var</em> + <em>step</em>
1631          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
1632            break
1633          end
1634          local v = <em>var</em>
1635          <em>block</em>
1636        end
1637      end
1638 </pre>
1639
1640 <p>
1641 Note the following:
1642
1643 <ul>
1644
1645 <li>
1646 All three control expressions are evaluated only once,
1647 before the loop starts.
1648 They must all result in numbers.
1649 </li>
1650
1651 <li>
1652 <code><em>var</em></code>, <code><em>limit</em></code>, and <code><em>step</em></code> are invisible variables.
1653 The names shown here are for explanatory purposes only.
1654 </li>
1655
1656 <li>
1657 If the third expression (the step) is absent,
1658 then a step of&nbsp;1 is used.
1659 </li>
1660
1661 <li>
1662 You can use <b>break</b> and <b>goto</b> to exit a <b>for</b> loop.
1663 </li>
1664
1665 <li>
1666 The loop variable <code>v</code> is local to the loop body.
1667 If you need its value after the loop,
1668 assign it to another variable before exiting the loop.
1669 </li>
1670
1671 </ul>
1672
1673 <p>
1674 The generic <b>for</b> statement works over functions,
1675 called <em>iterators</em>.
1676 On each iteration, the iterator function is called to produce a new value,
1677 stopping when this new value is <b>nil</b>.
1678 The generic <b>for</b> loop has the following syntax:
1679
1680 <pre>
1681         stat ::= <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b>
1682         namelist ::= Name {&lsquo;<b>,</b>&rsquo; Name}
1683 </pre><p>
1684 A <b>for</b> statement like
1685
1686 <pre>
1687      for <em>var_1</em>, &middot;&middot;&middot;, <em>var_n</em> in <em>explist</em> do <em>block</em> end
1688 </pre><p>
1689 is equivalent to the code:
1690
1691 <pre>
1692      do
1693        local <em>f</em>, <em>s</em>, <em>var</em> = <em>explist</em>
1694        while true do
1695          local <em>var_1</em>, &middot;&middot;&middot;, <em>var_n</em> = <em>f</em>(<em>s</em>, <em>var</em>)
1696          if <em>var_1</em> == nil then break end
1697          <em>var</em> = <em>var_1</em>
1698          <em>block</em>
1699        end
1700      end
1701 </pre><p>
1702 Note the following:
1703
1704 <ul>
1705
1706 <li>
1707 <code><em>explist</em></code> is evaluated only once.
1708 Its results are an <em>iterator</em> function,
1709 a <em>state</em>,
1710 and an initial value for the first <em>iterator variable</em>.
1711 </li>
1712
1713 <li>
1714 <code><em>f</em></code>, <code><em>s</em></code>, and <code><em>var</em></code> are invisible variables.
1715 The names are here for explanatory purposes only.
1716 </li>
1717
1718 <li>
1719 You can use <b>break</b> to exit a <b>for</b> loop.
1720 </li>
1721
1722 <li>
1723 The loop variables <code><em>var_i</em></code> are local to the loop;
1724 you cannot use their values after the <b>for</b> ends.
1725 If you need these values,
1726 then assign them to other variables before breaking or exiting the loop.
1727 </li>
1728
1729 </ul>
1730
1731
1732
1733
1734 <h3>3.3.6 &ndash; <a name="3.3.6">Function Calls as Statements</a></h3><p>
1735 To allow possible side-effects,
1736 function calls can be executed as statements:
1737
1738 <pre>
1739         stat ::= functioncall
1740 </pre><p>
1741 In this case, all returned values are thrown away.
1742 Function calls are explained in <a href="#3.4.10">&sect;3.4.10</a>.
1743
1744
1745
1746
1747
1748 <h3>3.3.7 &ndash; <a name="3.3.7">Local Declarations</a></h3><p>
1749 Local variables can be declared anywhere inside a block.
1750 The declaration can include an initial assignment:
1751
1752 <pre>
1753         stat ::= <b>local</b> namelist [&lsquo;<b>=</b>&rsquo; explist]
1754 </pre><p>
1755 If present, an initial assignment has the same semantics
1756 of a multiple assignment (see <a href="#3.3.3">&sect;3.3.3</a>).
1757 Otherwise, all variables are initialized with <b>nil</b>.
1758
1759
1760 <p>
1761 A chunk is also a block (see <a href="#3.3.2">&sect;3.3.2</a>),
1762 and so local variables can be declared in a chunk outside any explicit block.
1763
1764
1765 <p>
1766 The visibility rules for local variables are explained in <a href="#3.5">&sect;3.5</a>.
1767
1768
1769
1770
1771
1772
1773
1774 <h2>3.4 &ndash; <a name="3.4">Expressions</a></h2>
1775
1776 <p>
1777 The basic expressions in Lua are the following:
1778
1779 <pre>
1780         exp ::= prefixexp
1781         exp ::= <b>nil</b> | <b>false</b> | <b>true</b>
1782         exp ::= Numeral
1783         exp ::= LiteralString
1784         exp ::= functiondef
1785         exp ::= tableconstructor
1786         exp ::= &lsquo;<b>...</b>&rsquo;
1787         exp ::= exp binop exp
1788         exp ::= unop exp
1789         prefixexp ::= var | functioncall | &lsquo;<b>(</b>&rsquo; exp &lsquo;<b>)</b>&rsquo;
1790 </pre>
1791
1792 <p>
1793 Numerals and literal strings are explained in <a href="#3.1">&sect;3.1</a>;
1794 variables are explained in <a href="#3.2">&sect;3.2</a>;
1795 function definitions are explained in <a href="#3.4.11">&sect;3.4.11</a>;
1796 function calls are explained in <a href="#3.4.10">&sect;3.4.10</a>;
1797 table constructors are explained in <a href="#3.4.9">&sect;3.4.9</a>.
1798 Vararg expressions,
1799 denoted by three dots ('<code>...</code>'), can only be used when
1800 directly inside a vararg function;
1801 they are explained in <a href="#3.4.11">&sect;3.4.11</a>.
1802
1803
1804 <p>
1805 Binary operators comprise arithmetic operators (see <a href="#3.4.1">&sect;3.4.1</a>),
1806 bitwise operators (see <a href="#3.4.2">&sect;3.4.2</a>),
1807 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>),
1808 and the concatenation operator (see <a href="#3.4.6">&sect;3.4.6</a>).
1809 Unary operators comprise the unary minus (see <a href="#3.4.1">&sect;3.4.1</a>),
1810 the unary bitwise NOT (see <a href="#3.4.2">&sect;3.4.2</a>),
1811 the unary logical <b>not</b> (see <a href="#3.4.5">&sect;3.4.5</a>),
1812 and the unary <em>length operator</em> (see <a href="#3.4.7">&sect;3.4.7</a>).
1813
1814
1815 <p>
1816 Both function calls and vararg expressions can result in multiple values.
1817 If a function call is used as a statement (see <a href="#3.3.6">&sect;3.3.6</a>),
1818 then its return list is adjusted to zero elements,
1819 thus discarding all returned values.
1820 If an expression is used as the last (or the only) element
1821 of a list of expressions,
1822 then no adjustment is made
1823 (unless the expression is enclosed in parentheses).
1824 In all other contexts,
1825 Lua adjusts the result list to one element,
1826 either discarding all values except the first one
1827 or adding a single <b>nil</b> if there are no values.
1828
1829
1830 <p>
1831 Here are some examples:
1832
1833 <pre>
1834      f()                -- adjusted to 0 results
1835      g(f(), x)          -- f() is adjusted to 1 result
1836      g(x, f())          -- g gets x plus all results from f()
1837      a,b,c = f(), x     -- f() is adjusted to 1 result (c gets nil)
1838      a,b = ...          -- a gets the first vararg parameter, b gets
1839                         -- the second (both a and b can get nil if there
1840                         -- is no corresponding vararg parameter)
1841
1842      a,b,c = x, f()     -- f() is adjusted to 2 results
1843      a,b,c = f()        -- f() is adjusted to 3 results
1844      return f()         -- returns all results from f()
1845      return ...         -- returns all received vararg parameters
1846      return x,y,f()     -- returns x, y, and all results from f()
1847      {f()}              -- creates a list with all results from f()
1848      {...}              -- creates a list with all vararg parameters
1849      {f(), nil}         -- f() is adjusted to 1 result
1850 </pre>
1851
1852 <p>
1853 Any expression enclosed in parentheses always results in only one value.
1854 Thus,
1855 <code>(f(x,y,z))</code> is always a single value,
1856 even if <code>f</code> returns several values.
1857 (The value of <code>(f(x,y,z))</code> is the first value returned by <code>f</code>
1858 or <b>nil</b> if <code>f</code> does not return any values.)
1859
1860
1861
1862 <h3>3.4.1 &ndash; <a name="3.4.1">Arithmetic Operators</a></h3><p>
1863 Lua supports the following arithmetic operators:
1864
1865 <ul>
1866 <li><b><code>+</code>: </b>addition</li>
1867 <li><b><code>-</code>: </b>subtraction</li>
1868 <li><b><code>*</code>: </b>multiplication</li>
1869 <li><b><code>/</code>: </b>float division</li>
1870 <li><b><code>//</code>: </b>floor division</li>
1871 <li><b><code>%</code>: </b>modulo</li>
1872 <li><b><code>^</code>: </b>exponentiation</li>
1873 <li><b><code>-</code>: </b>unary minus</li>
1874 </ul>
1875
1876 <p>
1877 With the exception of exponentiation and float division,
1878 the arithmetic operators work as follows:
1879 If both operands are integers,
1880 the operation is performed over integers and the result is an integer.
1881 Otherwise, if both operands are numbers
1882 or strings that can be converted to
1883 numbers (see <a href="#3.4.3">&sect;3.4.3</a>),
1884 then they are converted to floats,
1885 the operation is performed following the usual rules
1886 for floating-point arithmetic
1887 (usually the IEEE 754 standard),
1888 and the result is a float.
1889
1890
1891 <p>
1892 Exponentiation and float division (<code>/</code>)
1893 always convert their operands to floats
1894 and the result is always a float.
1895 Exponentiation uses the ISO&nbsp;C function <code>pow</code>,
1896 so that it works for non-integer exponents too.
1897
1898
1899 <p>
1900 Floor division (<code>//</code>) is a division
1901 that rounds the quotient towards minus infinity,
1902 that is, the floor of the division of its operands.
1903
1904
1905 <p>
1906 Modulo is defined as the remainder of a division
1907 that rounds the quotient towards minus infinity (floor division).
1908
1909
1910 <p>
1911 In case of overflows in integer arithmetic,
1912 all operations <em>wrap around</em>,
1913 according to the usual rules of two-complement arithmetic.
1914 (In other words,
1915 they return the unique representable integer
1916 that is equal modulo <em>2<sup>64</sup></em> to the mathematical result.)
1917
1918
1919
1920 <h3>3.4.2 &ndash; <a name="3.4.2">Bitwise Operators</a></h3><p>
1921 Lua supports the following bitwise operators:
1922
1923 <ul>
1924 <li><b><code>&amp;</code>: </b>bitwise AND</li>
1925 <li><b><code>&#124;</code>: </b>bitwise OR</li>
1926 <li><b><code>~</code>: </b>bitwise exclusive OR</li>
1927 <li><b><code>&gt;&gt;</code>: </b>right shift</li>
1928 <li><b><code>&lt;&lt;</code>: </b>left shift</li>
1929 <li><b><code>~</code>: </b>unary bitwise NOT</li>
1930 </ul>
1931
1932 <p>
1933 All bitwise operations convert its operands to integers
1934 (see <a href="#3.4.3">&sect;3.4.3</a>),
1935 operate on all bits of those integers,
1936 and result in an integer.
1937
1938
1939 <p>
1940 Both right and left shifts fill the vacant bits with zeros.
1941 Negative displacements shift to the other direction;
1942 displacements with absolute values equal to or higher than
1943 the number of bits in an integer
1944 result in zero (as all bits are shifted out).
1945
1946
1947
1948
1949
1950 <h3>3.4.3 &ndash; <a name="3.4.3">Coercions and Conversions</a></h3><p>
1951 Lua provides some automatic conversions between some
1952 types and representations at run time.
1953 Bitwise operators always convert float operands to integers.
1954 Exponentiation and float division
1955 always convert integer operands to floats.
1956 All other arithmetic operations applied to mixed numbers
1957 (integers and floats) convert the integer operand to a float;
1958 this is called the <em>usual rule</em>.
1959 The C API also converts both integers to floats and
1960 floats to integers, as needed.
1961 Moreover, string concatenation accepts numbers as arguments,
1962 besides strings.
1963
1964
1965 <p>
1966 Lua also converts strings to numbers,
1967 whenever a number is expected.
1968
1969
1970 <p>
1971 In a conversion from integer to float,
1972 if the integer value has an exact representation as a float,
1973 that is the result.
1974 Otherwise,
1975 the conversion gets the nearest higher or
1976 the nearest lower representable value.
1977 This kind of conversion never fails.
1978
1979
1980 <p>
1981 The conversion from float to integer
1982 checks whether the float has an exact representation as an integer
1983 (that is, the float has an integral value and
1984 it is in the range of integer representation).
1985 If it does, that representation is the result.
1986 Otherwise, the conversion fails.
1987
1988
1989 <p>
1990 The conversion from strings to numbers goes as follows:
1991 First, the string is converted to an integer or a float,
1992 following its syntax and the rules of the Lua lexer.
1993 (The string may have also leading and trailing spaces and a sign.)
1994 Then, the resulting number (float or integer)
1995 is converted to the type (float or integer) required by the context
1996 (e.g., the operation that forced the conversion).
1997
1998
1999 <p>
2000 All conversions from strings to numbers
2001 accept both a dot and the current locale mark
2002 as the radix character.
2003 (The Lua lexer, however, accepts only a dot.)
2004
2005
2006 <p>
2007 The conversion from numbers to strings uses a
2008 non-specified human-readable format.
2009 For complete control over how numbers are converted to strings,
2010 use the <code>format</code> function from the string library
2011 (see <a href="#pdf-string.format"><code>string.format</code></a>).
2012
2013
2014
2015
2016
2017 <h3>3.4.4 &ndash; <a name="3.4.4">Relational Operators</a></h3><p>
2018 Lua supports the following relational operators:
2019
2020 <ul>
2021 <li><b><code>==</code>: </b>equality</li>
2022 <li><b><code>~=</code>: </b>inequality</li>
2023 <li><b><code>&lt;</code>: </b>less than</li>
2024 <li><b><code>&gt;</code>: </b>greater than</li>
2025 <li><b><code>&lt;=</code>: </b>less or equal</li>
2026 <li><b><code>&gt;=</code>: </b>greater or equal</li>
2027 </ul><p>
2028 These operators always result in <b>false</b> or <b>true</b>.
2029
2030
2031 <p>
2032 Equality (<code>==</code>) first compares the type of its operands.
2033 If the types are different, then the result is <b>false</b>.
2034 Otherwise, the values of the operands are compared.
2035 Strings are compared in the obvious way.
2036 Numbers are equal if they denote the same mathematical value.
2037
2038
2039 <p>
2040 Tables, userdata, and threads
2041 are compared by reference:
2042 two objects are considered equal only if they are the same object.
2043 Every time you create a new object
2044 (a table, userdata, or thread),
2045 this new object is different from any previously existing object.
2046 Closures with the same reference are always equal.
2047 Closures with any detectable difference
2048 (different behavior, different definition) are always different.
2049
2050
2051 <p>
2052 You can change the way that Lua compares tables and userdata
2053 by using the "eq" metamethod (see <a href="#2.4">&sect;2.4</a>).
2054
2055
2056 <p>
2057 Equality comparisons do not convert strings to numbers
2058 or vice versa.
2059 Thus, <code>"0"==0</code> evaluates to <b>false</b>,
2060 and <code>t[0]</code> and <code>t["0"]</code> denote different
2061 entries in a table.
2062
2063
2064 <p>
2065 The operator <code>~=</code> is exactly the negation of equality (<code>==</code>).
2066
2067
2068 <p>
2069 The order operators work as follows.
2070 If both arguments are numbers,
2071 then they are compared according to their mathematical values
2072 (regardless of their subtypes).
2073 Otherwise, if both arguments are strings,
2074 then their values are compared according to the current locale.
2075 Otherwise, Lua tries to call the "lt" or the "le"
2076 metamethod (see <a href="#2.4">&sect;2.4</a>).
2077 A comparison <code>a &gt; b</code> is translated to <code>b &lt; a</code>
2078 and <code>a &gt;= b</code> is translated to <code>b &lt;= a</code>.
2079
2080
2081 <p>
2082 Following the IEEE 754 standard,
2083 NaN is considered neither smaller than,
2084 nor equal to, nor greater than any value (including itself).
2085
2086
2087
2088
2089
2090 <h3>3.4.5 &ndash; <a name="3.4.5">Logical Operators</a></h3><p>
2091 The logical operators in Lua are
2092 <b>and</b>, <b>or</b>, and <b>not</b>.
2093 Like the control structures (see <a href="#3.3.4">&sect;3.3.4</a>),
2094 all logical operators consider both <b>false</b> and <b>nil</b> as false
2095 and anything else as true.
2096
2097
2098 <p>
2099 The negation operator <b>not</b> always returns <b>false</b> or <b>true</b>.
2100 The conjunction operator <b>and</b> returns its first argument
2101 if this value is <b>false</b> or <b>nil</b>;
2102 otherwise, <b>and</b> returns its second argument.
2103 The disjunction operator <b>or</b> returns its first argument
2104 if this value is different from <b>nil</b> and <b>false</b>;
2105 otherwise, <b>or</b> returns its second argument.
2106 Both <b>and</b> and <b>or</b> use short-circuit evaluation;
2107 that is,
2108 the second operand is evaluated only if necessary.
2109 Here are some examples:
2110
2111 <pre>
2112      10 or 20            --&gt; 10
2113      10 or error()       --&gt; 10
2114      nil or "a"          --&gt; "a"
2115      nil and 10          --&gt; nil
2116      false and error()   --&gt; false
2117      false and nil       --&gt; false
2118      false or nil        --&gt; nil
2119      10 and 20           --&gt; 20
2120 </pre><p>
2121 (In this manual,
2122 <code>--&gt;</code> indicates the result of the preceding expression.)
2123
2124
2125
2126
2127
2128 <h3>3.4.6 &ndash; <a name="3.4.6">Concatenation</a></h3><p>
2129 The string concatenation operator in Lua is
2130 denoted by two dots ('<code>..</code>').
2131 If both operands are strings or numbers, then they are converted to
2132 strings according to the rules described in <a href="#3.4.3">&sect;3.4.3</a>.
2133 Otherwise, the <code>__concat</code> metamethod is called (see <a href="#2.4">&sect;2.4</a>).
2134
2135
2136
2137
2138
2139 <h3>3.4.7 &ndash; <a name="3.4.7">The Length Operator</a></h3>
2140
2141 <p>
2142 The length operator is denoted by the unary prefix operator <code>#</code>.
2143 The length of a string is its number of bytes
2144 (that is, the usual meaning of string length when each
2145 character is one byte).
2146
2147
2148 <p>
2149 A program can modify the behavior of the length operator for
2150 any value but strings through the <code>__len</code> metamethod (see <a href="#2.4">&sect;2.4</a>).
2151
2152
2153 <p>
2154 Unless a <code>__len</code> metamethod is given,
2155 the length of a table <code>t</code> is only defined if the
2156 table is a <em>sequence</em>,
2157 that is,
2158 the set of its positive numeric keys is equal to <em>{1..n}</em>
2159 for some non-negative integer <em>n</em>.
2160 In that case, <em>n</em> is its length.
2161 Note that a table like
2162
2163 <pre>
2164      {10, 20, nil, 40}
2165 </pre><p>
2166 is not a sequence, because it has the key <code>4</code>
2167 but does not have the key <code>3</code>.
2168 (So, there is no <em>n</em> such that the set <em>{1..n}</em> is equal
2169 to the set of positive numeric keys of that table.)
2170 Note, however, that non-numeric keys do not interfere
2171 with whether a table is a sequence.
2172
2173
2174
2175
2176
2177 <h3>3.4.8 &ndash; <a name="3.4.8">Precedence</a></h3><p>
2178 Operator precedence in Lua follows the table below,
2179 from lower to higher priority:
2180
2181 <pre>
2182      or
2183      and
2184      &lt;     &gt;     &lt;=    &gt;=    ~=    ==
2185      |
2186      ~
2187      &amp;
2188      &lt;&lt;    &gt;&gt;
2189      ..
2190      +     -
2191      *     /     //    %
2192      unary operators (not   #     -     ~)
2193      ^
2194 </pre><p>
2195 As usual,
2196 you can use parentheses to change the precedences of an expression.
2197 The concatenation ('<code>..</code>') and exponentiation ('<code>^</code>')
2198 operators are right associative.
2199 All other binary operators are left associative.
2200
2201
2202
2203
2204
2205 <h3>3.4.9 &ndash; <a name="3.4.9">Table Constructors</a></h3><p>
2206 Table constructors are expressions that create tables.
2207 Every time a constructor is evaluated, a new table is created.
2208 A constructor can be used to create an empty table
2209 or to create a table and initialize some of its fields.
2210 The general syntax for constructors is
2211
2212 <pre>
2213         tableconstructor ::= &lsquo;<b>{</b>&rsquo; [fieldlist] &lsquo;<b>}</b>&rsquo;
2214         fieldlist ::= field {fieldsep field} [fieldsep]
2215         field ::= &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo; &lsquo;<b>=</b>&rsquo; exp | Name &lsquo;<b>=</b>&rsquo; exp | exp
2216         fieldsep ::= &lsquo;<b>,</b>&rsquo; | &lsquo;<b>;</b>&rsquo;
2217 </pre>
2218
2219 <p>
2220 Each field of the form <code>[exp1] = exp2</code> adds to the new table an entry
2221 with key <code>exp1</code> and value <code>exp2</code>.
2222 A field of the form <code>name = exp</code> is equivalent to
2223 <code>["name"] = exp</code>.
2224 Finally, fields of the form <code>exp</code> are equivalent to
2225 <code>[i] = exp</code>, where <code>i</code> are consecutive integers
2226 starting with 1.
2227 Fields in the other formats do not affect this counting.
2228 For example,
2229
2230 <pre>
2231      a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 }
2232 </pre><p>
2233 is equivalent to
2234
2235 <pre>
2236      do
2237        local t = {}
2238        t[f(1)] = g
2239        t[1] = "x"         -- 1st exp
2240        t[2] = "y"         -- 2nd exp
2241        t.x = 1            -- t["x"] = 1
2242        t[3] = f(x)        -- 3rd exp
2243        t[30] = 23
2244        t[4] = 45          -- 4th exp
2245        a = t
2246      end
2247 </pre>
2248
2249 <p>
2250 The order of the assignments in a constructor is undefined.
2251 (This order would be relevant only when there are repeated keys.)
2252
2253
2254 <p>
2255 If the last field in the list has the form <code>exp</code>
2256 and the expression is a function call or a vararg expression,
2257 then all values returned by this expression enter the list consecutively
2258 (see <a href="#3.4.10">&sect;3.4.10</a>).
2259
2260
2261 <p>
2262 The field list can have an optional trailing separator,
2263 as a convenience for machine-generated code.
2264
2265
2266
2267
2268
2269 <h3>3.4.10 &ndash; <a name="3.4.10">Function Calls</a></h3><p>
2270 A function call in Lua has the following syntax:
2271
2272 <pre>
2273         functioncall ::= prefixexp args
2274 </pre><p>
2275 In a function call,
2276 first prefixexp and args are evaluated.
2277 If the value of prefixexp has type <em>function</em>,
2278 then this function is called
2279 with the given arguments.
2280 Otherwise, the prefixexp "call" metamethod is called,
2281 having as first parameter the value of prefixexp,
2282 followed by the original call arguments
2283 (see <a href="#2.4">&sect;2.4</a>).
2284
2285
2286 <p>
2287 The form
2288
2289 <pre>
2290         functioncall ::= prefixexp &lsquo;<b>:</b>&rsquo; Name args
2291 </pre><p>
2292 can be used to call "methods".
2293 A call <code>v:name(<em>args</em>)</code>
2294 is syntactic sugar for <code>v.name(v,<em>args</em>)</code>,
2295 except that <code>v</code> is evaluated only once.
2296
2297
2298 <p>
2299 Arguments have the following syntax:
2300
2301 <pre>
2302         args ::= &lsquo;<b>(</b>&rsquo; [explist] &lsquo;<b>)</b>&rsquo;
2303         args ::= tableconstructor
2304         args ::= LiteralString
2305 </pre><p>
2306 All argument expressions are evaluated before the call.
2307 A call of the form <code>f{<em>fields</em>}</code> is
2308 syntactic sugar for <code>f({<em>fields</em>})</code>;
2309 that is, the argument list is a single new table.
2310 A call of the form <code>f'<em>string</em>'</code>
2311 (or <code>f"<em>string</em>"</code> or <code>f[[<em>string</em>]]</code>)
2312 is syntactic sugar for <code>f('<em>string</em>')</code>;
2313 that is, the argument list is a single literal string.
2314
2315
2316 <p>
2317 A call of the form <code>return <em>functioncall</em></code> is called
2318 a <em>tail call</em>.
2319 Lua implements <em>proper tail calls</em>
2320 (or <em>proper tail recursion</em>):
2321 in a tail call,
2322 the called function reuses the stack entry of the calling function.
2323 Therefore, there is no limit on the number of nested tail calls that
2324 a program can execute.
2325 However, a tail call erases any debug information about the
2326 calling function.
2327 Note that a tail call only happens with a particular syntax,
2328 where the <b>return</b> has one single function call as argument;
2329 this syntax makes the calling function return exactly
2330 the returns of the called function.
2331 So, none of the following examples are tail calls:
2332
2333 <pre>
2334      return (f(x))        -- results adjusted to 1
2335      return 2 * f(x)
2336      return x, f(x)       -- additional results
2337      f(x); return         -- results discarded
2338      return x or f(x)     -- results adjusted to 1
2339 </pre>
2340
2341
2342
2343
2344 <h3>3.4.11 &ndash; <a name="3.4.11">Function Definitions</a></h3>
2345
2346 <p>
2347 The syntax for function definition is
2348
2349 <pre>
2350         functiondef ::= <b>function</b> funcbody
2351         funcbody ::= &lsquo;<b>(</b>&rsquo; [parlist] &lsquo;<b>)</b>&rsquo; block <b>end</b>
2352 </pre>
2353
2354 <p>
2355 The following syntactic sugar simplifies function definitions:
2356
2357 <pre>
2358         stat ::= <b>function</b> funcname funcbody
2359         stat ::= <b>local</b> <b>function</b> Name funcbody
2360         funcname ::= Name {&lsquo;<b>.</b>&rsquo; Name} [&lsquo;<b>:</b>&rsquo; Name]
2361 </pre><p>
2362 The statement
2363
2364 <pre>
2365      function f () <em>body</em> end
2366 </pre><p>
2367 translates to
2368
2369 <pre>
2370      f = function () <em>body</em> end
2371 </pre><p>
2372 The statement
2373
2374 <pre>
2375      function t.a.b.c.f () <em>body</em> end
2376 </pre><p>
2377 translates to
2378
2379 <pre>
2380      t.a.b.c.f = function () <em>body</em> end
2381 </pre><p>
2382 The statement
2383
2384 <pre>
2385      local function f () <em>body</em> end
2386 </pre><p>
2387 translates to
2388
2389 <pre>
2390      local f; f = function () <em>body</em> end
2391 </pre><p>
2392 not to
2393
2394 <pre>
2395      local f = function () <em>body</em> end
2396 </pre><p>
2397 (This only makes a difference when the body of the function
2398 contains references to <code>f</code>.)
2399
2400
2401 <p>
2402 A function definition is an executable expression,
2403 whose value has type <em>function</em>.
2404 When Lua precompiles a chunk,
2405 all its function bodies are precompiled too.
2406 Then, whenever Lua executes the function definition,
2407 the function is <em>instantiated</em> (or <em>closed</em>).
2408 This function instance (or <em>closure</em>)
2409 is the final value of the expression.
2410
2411
2412 <p>
2413 Parameters act as local variables that are
2414 initialized with the argument values:
2415
2416 <pre>
2417         parlist ::= namelist [&lsquo;<b>,</b>&rsquo; &lsquo;<b>...</b>&rsquo;] | &lsquo;<b>...</b>&rsquo;
2418 </pre><p>
2419 When a function is called,
2420 the list of arguments is adjusted to
2421 the length of the list of parameters,
2422 unless the function is a <em>vararg function</em>,
2423 which is indicated by three dots ('<code>...</code>')
2424 at the end of its parameter list.
2425 A vararg function does not adjust its argument list;
2426 instead, it collects all extra arguments and supplies them
2427 to the function through a <em>vararg expression</em>,
2428 which is also written as three dots.
2429 The value of this expression is a list of all actual extra arguments,
2430 similar to a function with multiple results.
2431 If a vararg expression is used inside another expression
2432 or in the middle of a list of expressions,
2433 then its return list is adjusted to one element.
2434 If the expression is used as the last element of a list of expressions,
2435 then no adjustment is made
2436 (unless that last expression is enclosed in parentheses).
2437
2438
2439 <p>
2440 As an example, consider the following definitions:
2441
2442 <pre>
2443      function f(a, b) end
2444      function g(a, b, ...) end
2445      function r() return 1,2,3 end
2446 </pre><p>
2447 Then, we have the following mapping from arguments to parameters and
2448 to the vararg expression:
2449
2450 <pre>
2451      CALL            PARAMETERS
2452
2453      f(3)             a=3, b=nil
2454      f(3, 4)          a=3, b=4
2455      f(3, 4, 5)       a=3, b=4
2456      f(r(), 10)       a=1, b=10
2457      f(r())           a=1, b=2
2458
2459      g(3)             a=3, b=nil, ... --&gt;  (nothing)
2460      g(3, 4)          a=3, b=4,   ... --&gt;  (nothing)
2461      g(3, 4, 5, 8)    a=3, b=4,   ... --&gt;  5  8
2462      g(5, r())        a=5, b=1,   ... --&gt;  2  3
2463 </pre>
2464
2465 <p>
2466 Results are returned using the <b>return</b> statement (see <a href="#3.3.4">&sect;3.3.4</a>).
2467 If control reaches the end of a function
2468 without encountering a <b>return</b> statement,
2469 then the function returns with no results.
2470
2471
2472 <p>
2473
2474 There is a system-dependent limit on the number of values
2475 that a function may return.
2476 This limit is guaranteed to be larger than 1000.
2477
2478
2479 <p>
2480 The <em>colon</em> syntax
2481 is used for defining <em>methods</em>,
2482 that is, functions that have an implicit extra parameter <code>self</code>.
2483 Thus, the statement
2484
2485 <pre>
2486      function t.a.b.c:f (<em>params</em>) <em>body</em> end
2487 </pre><p>
2488 is syntactic sugar for
2489
2490 <pre>
2491      t.a.b.c.f = function (self, <em>params</em>) <em>body</em> end
2492 </pre>
2493
2494
2495
2496
2497
2498
2499 <h2>3.5 &ndash; <a name="3.5">Visibility Rules</a></h2>
2500
2501 <p>
2502
2503 Lua is a lexically scoped language.
2504 The scope of a local variable begins at the first statement after
2505 its declaration and lasts until the last non-void statement
2506 of the innermost block that includes the declaration.
2507 Consider the following example:
2508
2509 <pre>
2510      x = 10                -- global variable
2511      do                    -- new block
2512        local x = x         -- new 'x', with value 10
2513        print(x)            --&gt; 10
2514        x = x+1
2515        do                  -- another block
2516          local x = x+1     -- another 'x'
2517          print(x)          --&gt; 12
2518        end
2519        print(x)            --&gt; 11
2520      end
2521      print(x)              --&gt; 10  (the global one)
2522 </pre>
2523
2524 <p>
2525 Notice that, in a declaration like <code>local x = x</code>,
2526 the new <code>x</code> being declared is not in scope yet,
2527 and so the second <code>x</code> refers to the outside variable.
2528
2529
2530 <p>
2531 Because of the lexical scoping rules,
2532 local variables can be freely accessed by functions
2533 defined inside their scope.
2534 A local variable used by an inner function is called
2535 an <em>upvalue</em>, or <em>external local variable</em>,
2536 inside the inner function.
2537
2538
2539 <p>
2540 Notice that each execution of a <b>local</b> statement
2541 defines new local variables.
2542 Consider the following example:
2543
2544 <pre>
2545      a = {}
2546      local x = 20
2547      for i=1,10 do
2548        local y = 0
2549        a[i] = function () y=y+1; return x+y end
2550      end
2551 </pre><p>
2552 The loop creates ten closures
2553 (that is, ten instances of the anonymous function).
2554 Each of these closures uses a different <code>y</code> variable,
2555 while all of them share the same <code>x</code>.
2556
2557
2558
2559
2560
2561 <h1>4 &ndash; <a name="4">The Application Program Interface</a></h1>
2562
2563 <p>
2564
2565 This section describes the C&nbsp;API for Lua, that is,
2566 the set of C&nbsp;functions available to the host program to communicate
2567 with Lua.
2568 All API functions and related types and constants
2569 are declared in the header file <a name="pdf-lua.h"><code>lua.h</code></a>.
2570
2571
2572 <p>
2573 Even when we use the term "function",
2574 any facility in the API may be provided as a macro instead.
2575 Except where stated otherwise,
2576 all such macros use each of their arguments exactly once
2577 (except for the first argument, which is always a Lua state),
2578 and so do not generate any hidden side-effects.
2579
2580
2581 <p>
2582 As in most C&nbsp;libraries,
2583 the Lua API functions do not check their arguments for validity or consistency.
2584 However, you can change this behavior by compiling Lua
2585 with the macro <a name="pdf-LUA_USE_APICHECK"><code>LUA_USE_APICHECK</code></a> defined.
2586
2587
2588
2589 <h2>4.1 &ndash; <a name="4.1">The Stack</a></h2>
2590
2591 <p>
2592 Lua uses a <em>virtual stack</em> to pass values to and from C.
2593 Each element in this stack represents a Lua value
2594 (<b>nil</b>, number, string, etc.).
2595
2596
2597 <p>
2598 Whenever Lua calls C, the called function gets a new stack,
2599 which is independent of previous stacks and of stacks of
2600 C&nbsp;functions that are still active.
2601 This stack initially contains any arguments to the C&nbsp;function
2602 and it is where the C&nbsp;function pushes its results
2603 to be returned to the caller (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>).
2604
2605
2606 <p>
2607 For convenience,
2608 most query operations in the API do not follow a strict stack discipline.
2609 Instead, they can refer to any element in the stack
2610 by using an <em>index</em>:
2611 A positive index represents an absolute stack position
2612 (starting at&nbsp;1);
2613 a negative index represents an offset relative to the top of the stack.
2614 More specifically, if the stack has <em>n</em> elements,
2615 then index&nbsp;1 represents the first element
2616 (that is, the element that was pushed onto the stack first)
2617 and
2618 index&nbsp;<em>n</em> represents the last element;
2619 index&nbsp;-1 also represents the last element
2620 (that is, the element at the&nbsp;top)
2621 and index <em>-n</em> represents the first element.
2622
2623
2624
2625
2626
2627 <h2>4.2 &ndash; <a name="4.2">Stack Size</a></h2>
2628
2629 <p>
2630 When you interact with the Lua API,
2631 you are responsible for ensuring consistency.
2632 In particular,
2633 <em>you are responsible for controlling stack overflow</em>.
2634 You can use the function <a href="#lua_checkstack"><code>lua_checkstack</code></a>
2635 to ensure that the stack has enough space for pushing new elements.
2636
2637
2638 <p>
2639 Whenever Lua calls C,
2640 it ensures that the stack has space for
2641 at least <a name="pdf-LUA_MINSTACK"><code>LUA_MINSTACK</code></a> extra slots.
2642 <code>LUA_MINSTACK</code> is defined as 20,
2643 so that usually you do not have to worry about stack space
2644 unless your code has loops pushing elements onto the stack.
2645
2646
2647 <p>
2648 When you call a Lua function
2649 without a fixed number of results (see <a href="#lua_call"><code>lua_call</code></a>),
2650 Lua ensures that the stack has enough space for all results,
2651 but it does not ensure any extra space.
2652 So, before pushing anything in the stack after such a call
2653 you should use <a href="#lua_checkstack"><code>lua_checkstack</code></a>.
2654
2655
2656
2657
2658
2659 <h2>4.3 &ndash; <a name="4.3">Valid and Acceptable Indices</a></h2>
2660
2661 <p>
2662 Any function in the API that receives stack indices
2663 works only with <em>valid indices</em> or <em>acceptable indices</em>.
2664
2665
2666 <p>
2667 A <em>valid index</em> is an index that refers to a
2668 position that stores a modifiable Lua value.
2669 It comprises stack indices between&nbsp;1 and the stack top
2670 (<code>1 &le; abs(index) &le; top</code>)
2671
2672 plus <em>pseudo-indices</em>,
2673 which represent some positions that are accessible to C&nbsp;code
2674 but that are not in the stack.
2675 Pseudo-indices are used to access the registry (see <a href="#4.5">&sect;4.5</a>)
2676 and the upvalues of a C&nbsp;function (see <a href="#4.4">&sect;4.4</a>).
2677
2678
2679 <p>
2680 Functions that do not need a specific mutable position,
2681 but only a value (e.g., query functions),
2682 can be called with acceptable indices.
2683 An <em>acceptable index</em> can be any valid index,
2684 but it also can be any positive index after the stack top
2685 within the space allocated for the stack,
2686 that is, indices up to the stack size.
2687 (Note that 0 is never an acceptable index.)
2688 Except when noted otherwise,
2689 functions in the API work with acceptable indices.
2690
2691
2692 <p>
2693 Acceptable indices serve to avoid extra tests
2694 against the stack top when querying the stack.
2695 For instance, a C&nbsp;function can query its third argument
2696 without the need to first check whether there is a third argument,
2697 that is, without the need to check whether 3 is a valid index.
2698
2699
2700 <p>
2701 For functions that can be called with acceptable indices,
2702 any non-valid index is treated as if it
2703 contains a value of a virtual type <a name="pdf-LUA_TNONE"><code>LUA_TNONE</code></a>,
2704 which behaves like a nil value.
2705
2706
2707
2708
2709
2710 <h2>4.4 &ndash; <a name="4.4">C Closures</a></h2>
2711
2712 <p>
2713 When a C&nbsp;function is created,
2714 it is possible to associate some values with it,
2715 thus creating a <em>C&nbsp;closure</em>
2716 (see <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>);
2717 these values are called <em>upvalues</em> and are
2718 accessible to the function whenever it is called.
2719
2720
2721 <p>
2722 Whenever a C&nbsp;function is called,
2723 its upvalues are located at specific pseudo-indices.
2724 These pseudo-indices are produced by the macro
2725 <a href="#lua_upvalueindex"><code>lua_upvalueindex</code></a>.
2726 The first upvalue associated with a function is at index
2727 <code>lua_upvalueindex(1)</code>, and so on.
2728 Any access to <code>lua_upvalueindex(<em>n</em>)</code>,
2729 where <em>n</em> is greater than the number of upvalues of the
2730 current function
2731 (but not greater than 256,
2732 which is one plus the maximum number of upvalues in a closure),
2733 produces an acceptable but invalid index.
2734
2735
2736
2737
2738
2739 <h2>4.5 &ndash; <a name="4.5">Registry</a></h2>
2740
2741 <p>
2742 Lua provides a <em>registry</em>,
2743 a predefined table that can be used by any C&nbsp;code to
2744 store whatever Lua values it needs to store.
2745 The registry table is always located at pseudo-index
2746 <a name="pdf-LUA_REGISTRYINDEX"><code>LUA_REGISTRYINDEX</code></a>.
2747 Any C&nbsp;library can store data into this table,
2748 but it must take care to choose keys
2749 that are different from those used
2750 by other libraries, to avoid collisions.
2751 Typically, you should use as key a string containing your library name,
2752 or a light userdata with the address of a C&nbsp;object in your code,
2753 or any Lua object created by your code.
2754 As with variable names,
2755 string keys starting with an underscore followed by
2756 uppercase letters are reserved for Lua.
2757
2758
2759 <p>
2760 The integer keys in the registry are used
2761 by the reference mechanism (see <a href="#luaL_ref"><code>luaL_ref</code></a>)
2762 and by some predefined values.
2763 Therefore, integer keys must not be used for other purposes.
2764
2765
2766 <p>
2767 When you create a new Lua state,
2768 its registry comes with some predefined values.
2769 These predefined values are indexed with integer keys
2770 defined as constants in <code>lua.h</code>.
2771 The following constants are defined:
2772
2773 <ul>
2774 <li><b><a name="pdf-LUA_RIDX_MAINTHREAD"><code>LUA_RIDX_MAINTHREAD</code></a>: </b> At this index the registry has
2775 the main thread of the state.
2776 (The main thread is the one created together with the state.)
2777 </li>
2778
2779 <li><b><a name="pdf-LUA_RIDX_GLOBALS"><code>LUA_RIDX_GLOBALS</code></a>: </b> At this index the registry has
2780 the global environment.
2781 </li>
2782 </ul>
2783
2784
2785
2786
2787 <h2>4.6 &ndash; <a name="4.6">Error Handling in C</a></h2>
2788
2789 <p>
2790 Internally, Lua uses the C <code>longjmp</code> facility to handle errors.
2791 (Lua will use exceptions if you compile it as C++;
2792 search for <code>LUAI_THROW</code> in the source code for details.)
2793 When Lua faces any error
2794 (such as a memory allocation error, type errors, syntax errors,
2795 and runtime errors)
2796 it <em>raises</em> an error;
2797 that is, it does a long jump.
2798 A <em>protected environment</em> uses <code>setjmp</code>
2799 to set a recovery point;
2800 any error jumps to the most recent active recovery point.
2801
2802
2803 <p>
2804 If an error happens outside any protected environment,
2805 Lua calls a <em>panic function</em> (see <a href="#lua_atpanic"><code>lua_atpanic</code></a>)
2806 and then calls <code>abort</code>,
2807 thus exiting the host application.
2808 Your panic function can avoid this exit by
2809 never returning
2810 (e.g., doing a long jump to your own recovery point outside Lua).
2811
2812
2813 <p>
2814 The panic function runs as if it were a message handler (see <a href="#2.3">&sect;2.3</a>);
2815 in particular, the error object is at the top of the stack.
2816 However, there is no guarantee about stack space.
2817 To push anything on the stack,
2818 the panic function must first check the available space (see <a href="#4.2">&sect;4.2</a>).
2819
2820
2821 <p>
2822 Most functions in the API can raise an error,
2823 for instance due to a memory allocation error.
2824 The documentation for each function indicates whether
2825 it can raise errors.
2826
2827
2828 <p>
2829 Inside a C&nbsp;function you can raise an error by calling <a href="#lua_error"><code>lua_error</code></a>.
2830
2831
2832
2833
2834
2835 <h2>4.7 &ndash; <a name="4.7">Handling Yields in C</a></h2>
2836
2837 <p>
2838 Internally, Lua uses the C <code>longjmp</code> facility to yield a coroutine.
2839 Therefore, if a C function <code>foo</code> calls an API function
2840 and this API function yields
2841 (directly or indirectly by calling another function that yields),
2842 Lua cannot return to <code>foo</code> any more,
2843 because the <code>longjmp</code> removes its frame from the C stack.
2844
2845
2846 <p>
2847 To avoid this kind of problem,
2848 Lua raises an error whenever it tries to yield across an API call,
2849 except for three functions:
2850 <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>.
2851 All those functions receive a <em>continuation function</em>
2852 (as a parameter named <code>k</code>) to continue execution after a yield.
2853
2854
2855 <p>
2856 We need to set some terminology to explain continuations.
2857 We have a C function called from Lua which we will call
2858 the <em>original function</em>.
2859 This original function then calls one of those three functions in the C API,
2860 which we will call the <em>callee function</em>,
2861 that then yields the current thread.
2862 (This can happen when the callee function is <a href="#lua_yieldk"><code>lua_yieldk</code></a>,
2863 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>
2864 and the function called by them yields.)
2865
2866
2867 <p>
2868 Suppose the running thread yields while executing the callee function.
2869 After the thread resumes,
2870 it eventually will finish running the callee function.
2871 However,
2872 the callee function cannot return to the original function,
2873 because its frame in the C stack was destroyed by the yield.
2874 Instead, Lua calls a <em>continuation function</em>,
2875 which was given as an argument to the callee function.
2876 As the name implies,
2877 the continuation function should continue the task
2878 of the original function.
2879
2880
2881 <p>
2882 As an illustration, consider the following function:
2883
2884 <pre>
2885      int original_function (lua_State *L) {
2886        ...     /* code 1 */
2887        status = lua_pcall(L, n, m, h);  /* calls Lua */
2888        ...     /* code 2 */
2889      }
2890 </pre><p>
2891 Now we want to allow
2892 the Lua code being run by <a href="#lua_pcall"><code>lua_pcall</code></a> to yield.
2893 First, we can rewrite our function like here:
2894
2895 <pre>
2896      int k (lua_State *L, int status, lua_KContext ctx) {
2897        ...  /* code 2 */
2898      }
2899
2900      int original_function (lua_State *L) {
2901        ...     /* code 1 */
2902        return k(L, lua_pcall(L, n, m, h), ctx);
2903      }
2904 </pre><p>
2905 In the above code,
2906 the new function <code>k</code> is a
2907 <em>continuation function</em> (with type <a href="#lua_KFunction"><code>lua_KFunction</code></a>),
2908 which should do all the work that the original function
2909 was doing after calling <a href="#lua_pcall"><code>lua_pcall</code></a>.
2910 Now, we must inform Lua that it must call <code>k</code> if the Lua code
2911 being executed by <a href="#lua_pcall"><code>lua_pcall</code></a> gets interrupted in some way
2912 (errors or yielding),
2913 so we rewrite the code as here,
2914 replacing <a href="#lua_pcall"><code>lua_pcall</code></a> by <a href="#lua_pcallk"><code>lua_pcallk</code></a>:
2915
2916 <pre>
2917      int original_function (lua_State *L) {
2918        ...     /* code 1 */
2919        return k(L, lua_pcallk(L, n, m, h, ctx2, k), ctx1);
2920      }
2921 </pre><p>
2922 Note the external, explicit call to the continuation:
2923 Lua will call the continuation only if needed, that is,
2924 in case of errors or resuming after a yield.
2925 If the called function returns normally without ever yielding,
2926 <a href="#lua_pcallk"><code>lua_pcallk</code></a> (and <a href="#lua_callk"><code>lua_callk</code></a>) will also return normally.
2927 (Of course, instead of calling the continuation in that case,
2928 you can do the equivalent work directly inside the original function.)
2929
2930
2931 <p>
2932 Besides the Lua state,
2933 the continuation function has two other parameters:
2934 the final status of the call plus the context value (<code>ctx</code>) that
2935 was passed originally to <a href="#lua_pcallk"><code>lua_pcallk</code></a>.
2936 (Lua does not use this context value;
2937 it only passes this value from the original function to the
2938 continuation function.)
2939 For <a href="#lua_pcallk"><code>lua_pcallk</code></a>,
2940 the status is the same value that would be returned by <a href="#lua_pcallk"><code>lua_pcallk</code></a>,
2941 except that it is <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when being executed after a yield
2942 (instead of <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>).
2943 For <a href="#lua_yieldk"><code>lua_yieldk</code></a> and <a href="#lua_callk"><code>lua_callk</code></a>,
2944 the status is always <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when Lua calls the continuation.
2945 (For these two functions,
2946 Lua will not call the continuation in case of errors,
2947 because they do not handle errors.)
2948 Similarly, when using <a href="#lua_callk"><code>lua_callk</code></a>,
2949 you should call the continuation function
2950 with <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> as the status.
2951 (For <a href="#lua_yieldk"><code>lua_yieldk</code></a>, there is not much point in calling
2952 directly the continuation function,
2953 because <a href="#lua_yieldk"><code>lua_yieldk</code></a> usually does not return.)
2954
2955
2956 <p>
2957 Lua treats the continuation function as if it were the original function.
2958 The continuation function receives the same Lua stack
2959 from the original function,
2960 in the same state it would be if the callee function had returned.
2961 (For instance,
2962 after a <a href="#lua_callk"><code>lua_callk</code></a> the function and its arguments are
2963 removed from the stack and replaced by the results from the call.)
2964 It also has the same upvalues.
2965 Whatever it returns is handled by Lua as if it were the return
2966 of the original function.
2967
2968
2969
2970
2971
2972 <h2>4.8 &ndash; <a name="4.8">Functions and Types</a></h2>
2973
2974 <p>
2975 Here we list all functions and types from the C&nbsp;API in
2976 alphabetical order.
2977 Each function has an indicator like this:
2978 <span class="apii">[-o, +p, <em>x</em>]</span>
2979
2980
2981 <p>
2982 The first field, <code>o</code>,
2983 is how many elements the function pops from the stack.
2984 The second field, <code>p</code>,
2985 is how many elements the function pushes onto the stack.
2986 (Any function always pushes its results after popping its arguments.)
2987 A field in the form <code>x|y</code> means the function can push (or pop)
2988 <code>x</code> or <code>y</code> elements,
2989 depending on the situation;
2990 an interrogation mark '<code>?</code>' means that
2991 we cannot know how many elements the function pops/pushes
2992 by looking only at its arguments
2993 (e.g., they may depend on what is on the stack).
2994 The third field, <code>x</code>,
2995 tells whether the function may raise errors:
2996 '<code>-</code>' means the function never raises any error;
2997 '<code>m</code>' means the function may raise out-of-memory errors
2998 and errors running a <code>__gc</code> metamethod;
2999 '<code>e</code>' means the function may raise any errors
3000 (it can run arbitrary Lua code,
3001 either directly or through metamethods);
3002 '<code>v</code>' means the function may raise an error on purpose.
3003
3004
3005
3006 <hr><h3><a name="lua_absindex"><code>lua_absindex</code></a></h3><p>
3007 <span class="apii">[-0, +0, &ndash;]</span>
3008 <pre>int lua_absindex (lua_State *L, int idx);</pre>
3009
3010 <p>
3011 Converts the acceptable index <code>idx</code>
3012 into an equivalent absolute index
3013 (that is, one that does not depend on the stack top).
3014
3015
3016
3017
3018
3019 <hr><h3><a name="lua_Alloc"><code>lua_Alloc</code></a></h3>
3020 <pre>typedef void * (*lua_Alloc) (void *ud,
3021                              void *ptr,
3022                              size_t osize,
3023                              size_t nsize);</pre>
3024
3025 <p>
3026 The type of the memory-allocation function used by Lua states.
3027 The allocator function must provide a
3028 functionality similar to <code>realloc</code>,
3029 but not exactly the same.
3030 Its arguments are
3031 <code>ud</code>, an opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>;
3032 <code>ptr</code>, a pointer to the block being allocated/reallocated/freed;
3033 <code>osize</code>, the original size of the block or some code about what
3034 is being allocated;
3035 and <code>nsize</code>, the new size of the block.
3036
3037
3038 <p>
3039 When <code>ptr</code> is not <code>NULL</code>,
3040 <code>osize</code> is the size of the block pointed by <code>ptr</code>,
3041 that is, the size given when it was allocated or reallocated.
3042
3043
3044 <p>
3045 When <code>ptr</code> is <code>NULL</code>,
3046 <code>osize</code> encodes the kind of object that Lua is allocating.
3047 <code>osize</code> is any of
3048 <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>,
3049 <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)
3050 Lua is creating a new object of that type.
3051 When <code>osize</code> is some other value,
3052 Lua is allocating memory for something else.
3053
3054
3055 <p>
3056 Lua assumes the following behavior from the allocator function:
3057
3058
3059 <p>
3060 When <code>nsize</code> is zero,
3061 the allocator must behave like <code>free</code>
3062 and return <code>NULL</code>.
3063
3064
3065 <p>
3066 When <code>nsize</code> is not zero,
3067 the allocator must behave like <code>realloc</code>.
3068 The allocator returns <code>NULL</code>
3069 if and only if it cannot fulfill the request.
3070 Lua assumes that the allocator never fails when
3071 <code>osize &gt;= nsize</code>.
3072
3073
3074 <p>
3075 Here is a simple implementation for the allocator function.
3076 It is used in the auxiliary library by <a href="#luaL_newstate"><code>luaL_newstate</code></a>.
3077
3078 <pre>
3079      static void *l_alloc (void *ud, void *ptr, size_t osize,
3080                                                 size_t nsize) {
3081        (void)ud;  (void)osize;  /* not used */
3082        if (nsize == 0) {
3083          free(ptr);
3084          return NULL;
3085        }
3086        else
3087          return realloc(ptr, nsize);
3088      }
3089 </pre><p>
3090 Note that Standard&nbsp;C ensures
3091 that <code>free(NULL)</code> has no effect and that
3092 <code>realloc(NULL,size)</code> is equivalent to <code>malloc(size)</code>.
3093 This code assumes that <code>realloc</code> does not fail when shrinking a block.
3094 (Although Standard&nbsp;C does not ensure this behavior,
3095 it seems to be a safe assumption.)
3096
3097
3098
3099
3100
3101 <hr><h3><a name="lua_arith"><code>lua_arith</code></a></h3><p>
3102 <span class="apii">[-(2|1), +1, <em>e</em>]</span>
3103 <pre>void lua_arith (lua_State *L, int op);</pre>
3104
3105 <p>
3106 Performs an arithmetic or bitwise operation over the two values
3107 (or one, in the case of negations)
3108 at the top of the stack,
3109 with the value at the top being the second operand,
3110 pops these values, and pushes the result of the operation.
3111 The function follows the semantics of the corresponding Lua operator
3112 (that is, it may call metamethods).
3113
3114
3115 <p>
3116 The value of <code>op</code> must be one of the following constants:
3117
3118 <ul>
3119
3120 <li><b><a name="pdf-LUA_OPADD"><code>LUA_OPADD</code></a>: </b> performs addition (<code>+</code>)</li>
3121 <li><b><a name="pdf-LUA_OPSUB"><code>LUA_OPSUB</code></a>: </b> performs subtraction (<code>-</code>)</li>
3122 <li><b><a name="pdf-LUA_OPMUL"><code>LUA_OPMUL</code></a>: </b> performs multiplication (<code>*</code>)</li>
3123 <li><b><a name="pdf-LUA_OPDIV"><code>LUA_OPDIV</code></a>: </b> performs float division (<code>/</code>)</li>
3124 <li><b><a name="pdf-LUA_OPIDIV"><code>LUA_OPIDIV</code></a>: </b> performs floor division (<code>//</code>)</li>
3125 <li><b><a name="pdf-LUA_OPMOD"><code>LUA_OPMOD</code></a>: </b> performs modulo (<code>%</code>)</li>
3126 <li><b><a name="pdf-LUA_OPPOW"><code>LUA_OPPOW</code></a>: </b> performs exponentiation (<code>^</code>)</li>
3127 <li><b><a name="pdf-LUA_OPUNM"><code>LUA_OPUNM</code></a>: </b> performs mathematical negation (unary <code>-</code>)</li>
3128 <li><b><a name="pdf-LUA_OPBNOT"><code>LUA_OPBNOT</code></a>: </b> performs bitwise NOT (<code>~</code>)</li>
3129 <li><b><a name="pdf-LUA_OPBAND"><code>LUA_OPBAND</code></a>: </b> performs bitwise AND (<code>&amp;</code>)</li>
3130 <li><b><a name="pdf-LUA_OPBOR"><code>LUA_OPBOR</code></a>: </b> performs bitwise OR (<code>|</code>)</li>
3131 <li><b><a name="pdf-LUA_OPBXOR"><code>LUA_OPBXOR</code></a>: </b> performs bitwise exclusive OR (<code>~</code>)</li>
3132 <li><b><a name="pdf-LUA_OPSHL"><code>LUA_OPSHL</code></a>: </b> performs left shift (<code>&lt;&lt;</code>)</li>
3133 <li><b><a name="pdf-LUA_OPSHR"><code>LUA_OPSHR</code></a>: </b> performs right shift (<code>&gt;&gt;</code>)</li>
3134
3135 </ul>
3136
3137
3138
3139
3140 <hr><h3><a name="lua_atpanic"><code>lua_atpanic</code></a></h3><p>
3141 <span class="apii">[-0, +0, &ndash;]</span>
3142 <pre>lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);</pre>
3143
3144 <p>
3145 Sets a new panic function and returns the old one (see <a href="#4.6">&sect;4.6</a>).
3146
3147
3148
3149
3150
3151 <hr><h3><a name="lua_call"><code>lua_call</code></a></h3><p>
3152 <span class="apii">[-(nargs+1), +nresults, <em>e</em>]</span>
3153 <pre>void lua_call (lua_State *L, int nargs, int nresults);</pre>
3154
3155 <p>
3156 Calls a function.
3157
3158
3159 <p>
3160 To call a function you must use the following protocol:
3161 first, the function to be called is pushed onto the stack;
3162 then, the arguments to the function are pushed
3163 in direct order;
3164 that is, the first argument is pushed first.
3165 Finally you call <a href="#lua_call"><code>lua_call</code></a>;
3166 <code>nargs</code> is the number of arguments that you pushed onto the stack.
3167 All arguments and the function value are popped from the stack
3168 when the function is called.
3169 The function results are pushed onto the stack when the function returns.
3170 The number of results is adjusted to <code>nresults</code>,
3171 unless <code>nresults</code> is <a name="pdf-LUA_MULTRET"><code>LUA_MULTRET</code></a>.
3172 In this case, all results from the function are pushed.
3173 Lua takes care that the returned values fit into the stack space,
3174 but it does not ensure any extra space in the stack.
3175 The function results are pushed onto the stack in direct order
3176 (the first result is pushed first),
3177 so that after the call the last result is on the top of the stack.
3178
3179
3180 <p>
3181 Any error inside the called function is propagated upwards
3182 (with a <code>longjmp</code>).
3183
3184
3185 <p>
3186 The following example shows how the host program can do the
3187 equivalent to this Lua code:
3188
3189 <pre>
3190      a = f("how", t.x, 14)
3191 </pre><p>
3192 Here it is in&nbsp;C:
3193
3194 <pre>
3195      lua_getglobal(L, "f");                  /* function to be called */
3196      lua_pushliteral(L, "how");                       /* 1st argument */
3197      lua_getglobal(L, "t");                    /* table to be indexed */
3198      lua_getfield(L, -1, "x");        /* push result of t.x (2nd arg) */
3199      lua_remove(L, -2);                  /* remove 't' from the stack */
3200      lua_pushinteger(L, 14);                          /* 3rd argument */
3201      lua_call(L, 3, 1);     /* call 'f' with 3 arguments and 1 result */
3202      lua_setglobal(L, "a");                         /* set global 'a' */
3203 </pre><p>
3204 Note that the code above is <em>balanced</em>:
3205 at its end, the stack is back to its original configuration.
3206 This is considered good programming practice.
3207
3208
3209
3210
3211
3212 <hr><h3><a name="lua_callk"><code>lua_callk</code></a></h3><p>
3213 <span class="apii">[-(nargs + 1), +nresults, <em>e</em>]</span>
3214 <pre>void lua_callk (lua_State *L,
3215                 int nargs,
3216                 int nresults,
3217                 lua_KContext ctx,
3218                 lua_KFunction k);</pre>
3219
3220 <p>
3221 This function behaves exactly like <a href="#lua_call"><code>lua_call</code></a>,
3222 but allows the called function to yield (see <a href="#4.7">&sect;4.7</a>).
3223
3224
3225
3226
3227
3228 <hr><h3><a name="lua_CFunction"><code>lua_CFunction</code></a></h3>
3229 <pre>typedef int (*lua_CFunction) (lua_State *L);</pre>
3230
3231 <p>
3232 Type for C&nbsp;functions.
3233
3234
3235 <p>
3236 In order to communicate properly with Lua,
3237 a C&nbsp;function must use the following protocol,
3238 which defines the way parameters and results are passed:
3239 a C&nbsp;function receives its arguments from Lua in its stack
3240 in direct order (the first argument is pushed first).
3241 So, when the function starts,
3242 <code>lua_gettop(L)</code> returns the number of arguments received by the function.
3243 The first argument (if any) is at index 1
3244 and its last argument is at index <code>lua_gettop(L)</code>.
3245 To return values to Lua, a C&nbsp;function just pushes them onto the stack,
3246 in direct order (the first result is pushed first),
3247 and returns the number of results.
3248 Any other value in the stack below the results will be properly
3249 discarded by Lua.
3250 Like a Lua function, a C&nbsp;function called by Lua can also return
3251 many results.
3252
3253
3254 <p>
3255 As an example, the following function receives a variable number
3256 of numeric arguments and returns their average and their sum:
3257
3258 <pre>
3259      static int foo (lua_State *L) {
3260        int n = lua_gettop(L);    /* number of arguments */
3261        lua_Number sum = 0.0;
3262        int i;
3263        for (i = 1; i &lt;= n; i++) {
3264          if (!lua_isnumber(L, i)) {
3265            lua_pushliteral(L, "incorrect argument");
3266            lua_error(L);
3267          }
3268          sum += lua_tonumber(L, i);
3269        }
3270        lua_pushnumber(L, sum/n);        /* first result */
3271        lua_pushnumber(L, sum);         /* second result */
3272        return 2;                   /* number of results */
3273      }
3274 </pre>
3275
3276
3277
3278
3279 <hr><h3><a name="lua_checkstack"><code>lua_checkstack</code></a></h3><p>
3280 <span class="apii">[-0, +0, &ndash;]</span>
3281 <pre>int lua_checkstack (lua_State *L, int n);</pre>
3282
3283 <p>
3284 Ensures that the stack has space for at least <code>n</code> extra slots
3285 (that is, that you can safely push up to <code>n</code> values into it).
3286 It returns false if it cannot fulfill the request,
3287 either because it would cause the stack
3288 to be larger than a fixed maximum size
3289 (typically at least several thousand elements) or
3290 because it cannot allocate memory for the extra space.
3291 This function never shrinks the stack;
3292 if the stack already has space for the extra slots,
3293 it is left unchanged.
3294
3295
3296
3297
3298
3299 <hr><h3><a name="lua_close"><code>lua_close</code></a></h3><p>
3300 <span class="apii">[-0, +0, &ndash;]</span>
3301 <pre>void lua_close (lua_State *L);</pre>
3302
3303 <p>
3304 Destroys all objects in the given Lua state
3305 (calling the corresponding garbage-collection metamethods, if any)
3306 and frees all dynamic memory used by this state.
3307 On several platforms, you may not need to call this function,
3308 because all resources are naturally released when the host program ends.
3309 On the other hand, long-running programs that create multiple states,
3310 such as daemons or web servers,
3311 will probably need to close states as soon as they are not needed.
3312
3313
3314
3315
3316
3317 <hr><h3><a name="lua_compare"><code>lua_compare</code></a></h3><p>
3318 <span class="apii">[-0, +0, <em>e</em>]</span>
3319 <pre>int lua_compare (lua_State *L, int index1, int index2, int op);</pre>
3320
3321 <p>
3322 Compares two Lua values.
3323 Returns 1 if the value at index <code>index1</code> satisfies <code>op</code>
3324 when compared with the value at index <code>index2</code>,
3325 following the semantics of the corresponding Lua operator
3326 (that is, it may call metamethods).
3327 Otherwise returns&nbsp;0.
3328 Also returns&nbsp;0 if any of the indices is not valid.
3329
3330
3331 <p>
3332 The value of <code>op</code> must be one of the following constants:
3333
3334 <ul>
3335
3336 <li><b><a name="pdf-LUA_OPEQ"><code>LUA_OPEQ</code></a>: </b> compares for equality (<code>==</code>)</li>
3337 <li><b><a name="pdf-LUA_OPLT"><code>LUA_OPLT</code></a>: </b> compares for less than (<code>&lt;</code>)</li>
3338 <li><b><a name="pdf-LUA_OPLE"><code>LUA_OPLE</code></a>: </b> compares for less or equal (<code>&lt;=</code>)</li>
3339
3340 </ul>
3341
3342
3343
3344
3345 <hr><h3><a name="lua_concat"><code>lua_concat</code></a></h3><p>
3346 <span class="apii">[-n, +1, <em>e</em>]</span>
3347 <pre>void lua_concat (lua_State *L, int n);</pre>
3348
3349 <p>
3350 Concatenates the <code>n</code> values at the top of the stack,
3351 pops them, and leaves the result at the top.
3352 If <code>n</code>&nbsp;is&nbsp;1, the result is the single value on the stack
3353 (that is, the function does nothing);
3354 if <code>n</code> is 0, the result is the empty string.
3355 Concatenation is performed following the usual semantics of Lua
3356 (see <a href="#3.4.6">&sect;3.4.6</a>).
3357
3358
3359
3360
3361
3362 <hr><h3><a name="lua_copy"><code>lua_copy</code></a></h3><p>
3363 <span class="apii">[-0, +0, &ndash;]</span>
3364 <pre>void lua_copy (lua_State *L, int fromidx, int toidx);</pre>
3365
3366 <p>
3367 Copies the element at index <code>fromidx</code>
3368 into the valid index <code>toidx</code>,
3369 replacing the value at that position.
3370 Values at other positions are not affected.
3371
3372
3373
3374
3375
3376 <hr><h3><a name="lua_createtable"><code>lua_createtable</code></a></h3><p>
3377 <span class="apii">[-0, +1, <em>m</em>]</span>
3378 <pre>void lua_createtable (lua_State *L, int narr, int nrec);</pre>
3379
3380 <p>
3381 Creates a new empty table and pushes it onto the stack.
3382 Parameter <code>narr</code> is a hint for how many elements the table
3383 will have as a sequence;
3384 parameter <code>nrec</code> is a hint for how many other elements
3385 the table will have.
3386 Lua may use these hints to preallocate memory for the new table.
3387 This preallocation is useful for performance when you know in advance
3388 how many elements the table will have.
3389 Otherwise you can use the function <a href="#lua_newtable"><code>lua_newtable</code></a>.
3390
3391
3392
3393
3394
3395 <hr><h3><a name="lua_dump"><code>lua_dump</code></a></h3><p>
3396 <span class="apii">[-0, +0, &ndash;]</span>
3397 <pre>int lua_dump (lua_State *L,
3398                         lua_Writer writer,
3399                         void *data,
3400                         int strip);</pre>
3401
3402 <p>
3403 Dumps a function as a binary chunk.
3404 Receives a Lua function on the top of the stack
3405 and produces a binary chunk that,
3406 if loaded again,
3407 results in a function equivalent to the one dumped.
3408 As it produces parts of the chunk,
3409 <a href="#lua_dump"><code>lua_dump</code></a> calls function <code>writer</code> (see <a href="#lua_Writer"><code>lua_Writer</code></a>)
3410 with the given <code>data</code>
3411 to write them.
3412
3413
3414 <p>
3415 If <code>strip</code> is true,
3416 the binary representation may not include all debug information
3417 about the function,
3418 to save space.
3419
3420
3421 <p>
3422 The value returned is the error code returned by the last
3423 call to the writer;
3424 0&nbsp;means no errors.
3425
3426
3427 <p>
3428 This function does not pop the Lua function from the stack.
3429
3430
3431
3432
3433
3434 <hr><h3><a name="lua_error"><code>lua_error</code></a></h3><p>
3435 <span class="apii">[-1, +0, <em>v</em>]</span>
3436 <pre>int lua_error (lua_State *L);</pre>
3437
3438 <p>
3439 Generates a Lua error,
3440 using the value at the top of the stack as the error object.
3441 This function does a long jump,
3442 and therefore never returns
3443 (see <a href="#luaL_error"><code>luaL_error</code></a>).
3444
3445
3446
3447
3448
3449 <hr><h3><a name="lua_gc"><code>lua_gc</code></a></h3><p>
3450 <span class="apii">[-0, +0, <em>m</em>]</span>
3451 <pre>int lua_gc (lua_State *L, int what, int data);</pre>
3452
3453 <p>
3454 Controls the garbage collector.
3455
3456
3457 <p>
3458 This function performs several tasks,
3459 according to the value of the parameter <code>what</code>:
3460
3461 <ul>
3462
3463 <li><b><code>LUA_GCSTOP</code>: </b>
3464 stops the garbage collector.
3465 </li>
3466
3467 <li><b><code>LUA_GCRESTART</code>: </b>
3468 restarts the garbage collector.
3469 </li>
3470
3471 <li><b><code>LUA_GCCOLLECT</code>: </b>
3472 performs a full garbage-collection cycle.
3473 </li>
3474
3475 <li><b><code>LUA_GCCOUNT</code>: </b>
3476 returns the current amount of memory (in Kbytes) in use by Lua.
3477 </li>
3478
3479 <li><b><code>LUA_GCCOUNTB</code>: </b>
3480 returns the remainder of dividing the current amount of bytes of
3481 memory in use by Lua by 1024.
3482 </li>
3483
3484 <li><b><code>LUA_GCSTEP</code>: </b>
3485 performs an incremental step of garbage collection.
3486 </li>
3487
3488 <li><b><code>LUA_GCSETPAUSE</code>: </b>
3489 sets <code>data</code> as the new value
3490 for the <em>pause</em> of the collector (see <a href="#2.5">&sect;2.5</a>)
3491 and returns the previous value of the pause.
3492 </li>
3493
3494 <li><b><code>LUA_GCSETSTEPMUL</code>: </b>
3495 sets <code>data</code> as the new value for the <em>step multiplier</em> of
3496 the collector (see <a href="#2.5">&sect;2.5</a>)
3497 and returns the previous value of the step multiplier.
3498 </li>
3499
3500 <li><b><code>LUA_GCISRUNNING</code>: </b>
3501 returns a boolean that tells whether the collector is running
3502 (i.e., not stopped).
3503 </li>
3504
3505 </ul>
3506
3507 <p>
3508 For more details about these options,
3509 see <a href="#pdf-collectgarbage"><code>collectgarbage</code></a>.
3510
3511
3512
3513
3514
3515 <hr><h3><a name="lua_getallocf"><code>lua_getallocf</code></a></h3><p>
3516 <span class="apii">[-0, +0, &ndash;]</span>
3517 <pre>lua_Alloc lua_getallocf (lua_State *L, void **ud);</pre>
3518
3519 <p>
3520 Returns the memory-allocation function of a given state.
3521 If <code>ud</code> is not <code>NULL</code>, Lua stores in <code>*ud</code> the
3522 opaque pointer given when the memory-allocator function was set.
3523
3524
3525
3526
3527
3528 <hr><h3><a name="lua_getfield"><code>lua_getfield</code></a></h3><p>
3529 <span class="apii">[-0, +1, <em>e</em>]</span>
3530 <pre>int lua_getfield (lua_State *L, int index, const char *k);</pre>
3531
3532 <p>
3533 Pushes onto the stack the value <code>t[k]</code>,
3534 where <code>t</code> is the value at the given index.
3535 As in Lua, this function may trigger a metamethod
3536 for the "index" event (see <a href="#2.4">&sect;2.4</a>).
3537
3538
3539 <p>
3540 Returns the type of the pushed value.
3541
3542
3543
3544
3545
3546 <hr><h3><a name="lua_getextraspace"><code>lua_getextraspace</code></a></h3><p>
3547 <span class="apii">[-0, +0, &ndash;]</span>
3548 <pre>void *lua_getextraspace (lua_State *L);</pre>
3549
3550 <p>
3551 Returns a pointer to a raw memory area associated with the
3552 given Lua state.
3553 The application can use this area for any purpose;
3554 Lua does not use it for anything.
3555
3556
3557 <p>
3558 Each new thread has this area initialized with a copy
3559 of the area of the main thread.
3560
3561
3562 <p>
3563 By default, this area has the size of a pointer to void,
3564 but you can recompile Lua with a different size for this area.
3565 (See <code>LUA_EXTRASPACE</code> in <code>luaconf.h</code>.)
3566
3567
3568
3569
3570
3571 <hr><h3><a name="lua_getglobal"><code>lua_getglobal</code></a></h3><p>
3572 <span class="apii">[-0, +1, <em>e</em>]</span>
3573 <pre>int lua_getglobal (lua_State *L, const char *name);</pre>
3574
3575 <p>
3576 Pushes onto the stack the value of the global <code>name</code>.
3577 Returns the type of that value.
3578
3579
3580
3581
3582
3583 <hr><h3><a name="lua_geti"><code>lua_geti</code></a></h3><p>
3584 <span class="apii">[-0, +1, <em>e</em>]</span>
3585 <pre>int lua_geti (lua_State *L, int index, lua_Integer i);</pre>
3586
3587 <p>
3588 Pushes onto the stack the value <code>t[i]</code>,
3589 where <code>t</code> is the value at the given index.
3590 As in Lua, this function may trigger a metamethod
3591 for the "index" event (see <a href="#2.4">&sect;2.4</a>).
3592
3593
3594 <p>
3595 Returns the type of the pushed value.
3596
3597
3598
3599
3600
3601 <hr><h3><a name="lua_getmetatable"><code>lua_getmetatable</code></a></h3><p>
3602 <span class="apii">[-0, +(0|1), &ndash;]</span>
3603 <pre>int lua_getmetatable (lua_State *L, int index);</pre>
3604
3605 <p>
3606 If the value at the given index has a metatable,
3607 the function pushes that metatable onto the stack and returns&nbsp;1.
3608 Otherwise,
3609 the function returns&nbsp;0 and pushes nothing on the stack.
3610
3611
3612
3613
3614
3615 <hr><h3><a name="lua_gettable"><code>lua_gettable</code></a></h3><p>
3616 <span class="apii">[-1, +1, <em>e</em>]</span>
3617 <pre>int lua_gettable (lua_State *L, int index);</pre>
3618
3619 <p>
3620 Pushes onto the stack the value <code>t[k]</code>,
3621 where <code>t</code> is the value at the given index
3622 and <code>k</code> is the value at the top of the stack.
3623
3624
3625 <p>
3626 This function pops the key from the stack,
3627 pushing the resulting value in its place.
3628 As in Lua, this function may trigger a metamethod
3629 for the "index" event (see <a href="#2.4">&sect;2.4</a>).
3630
3631
3632 <p>
3633 Returns the type of the pushed value.
3634
3635
3636
3637
3638
3639 <hr><h3><a name="lua_gettop"><code>lua_gettop</code></a></h3><p>
3640 <span class="apii">[-0, +0, &ndash;]</span>
3641 <pre>int lua_gettop (lua_State *L);</pre>
3642
3643 <p>
3644 Returns the index of the top element in the stack.
3645 Because indices start at&nbsp;1,
3646 this result is equal to the number of elements in the stack;
3647 in particular, 0&nbsp;means an empty stack.
3648
3649
3650
3651
3652
3653 <hr><h3><a name="lua_getuservalue"><code>lua_getuservalue</code></a></h3><p>
3654 <span class="apii">[-0, +1, &ndash;]</span>
3655 <pre>int lua_getuservalue (lua_State *L, int index);</pre>
3656
3657 <p>
3658 Pushes onto the stack the Lua value associated with the userdata
3659 at the given index.
3660
3661
3662 <p>
3663 Returns the type of the pushed value.
3664
3665
3666
3667
3668
3669 <hr><h3><a name="lua_insert"><code>lua_insert</code></a></h3><p>
3670 <span class="apii">[-1, +1, &ndash;]</span>
3671 <pre>void lua_insert (lua_State *L, int index);</pre>
3672
3673 <p>
3674 Moves the top element into the given valid index,
3675 shifting up the elements above this index to open space.
3676 This function cannot be called with a pseudo-index,
3677 because a pseudo-index is not an actual stack position.
3678
3679
3680
3681
3682
3683 <hr><h3><a name="lua_Integer"><code>lua_Integer</code></a></h3>
3684 <pre>typedef ... lua_Integer;</pre>
3685
3686 <p>
3687 The type of integers in Lua.
3688
3689
3690 <p>
3691 By default this type is <code>long long</code>,
3692 (usually a 64-bit two-complement integer),
3693 but that can be changed to <code>long</code> or <code>int</code>
3694 (usually a 32-bit two-complement integer).
3695 (See <code>LUA_INT_TYPE</code> in <code>luaconf.h</code>.)
3696
3697
3698 <p>
3699 Lua also defines the constants
3700 <a name="pdf-LUA_MININTEGER"><code>LUA_MININTEGER</code></a> and <a name="pdf-LUA_MAXINTEGER"><code>LUA_MAXINTEGER</code></a>,
3701 with the minimum and the maximum values that fit in this type.
3702
3703
3704
3705
3706
3707 <hr><h3><a name="lua_isboolean"><code>lua_isboolean</code></a></h3><p>
3708 <span class="apii">[-0, +0, &ndash;]</span>
3709 <pre>int lua_isboolean (lua_State *L, int index);</pre>
3710
3711 <p>
3712 Returns 1 if the value at the given index is a boolean,
3713 and 0&nbsp;otherwise.
3714
3715
3716
3717
3718
3719 <hr><h3><a name="lua_iscfunction"><code>lua_iscfunction</code></a></h3><p>
3720 <span class="apii">[-0, +0, &ndash;]</span>
3721 <pre>int lua_iscfunction (lua_State *L, int index);</pre>
3722
3723 <p>
3724 Returns 1 if the value at the given index is a C&nbsp;function,
3725 and 0&nbsp;otherwise.
3726
3727
3728
3729
3730
3731 <hr><h3><a name="lua_isfunction"><code>lua_isfunction</code></a></h3><p>
3732 <span class="apii">[-0, +0, &ndash;]</span>
3733 <pre>int lua_isfunction (lua_State *L, int index);</pre>
3734
3735 <p>
3736 Returns 1 if the value at the given index is a function
3737 (either C or Lua), and 0&nbsp;otherwise.
3738
3739
3740
3741
3742
3743 <hr><h3><a name="lua_isinteger"><code>lua_isinteger</code></a></h3><p>
3744 <span class="apii">[-0, +0, &ndash;]</span>
3745 <pre>int lua_isinteger (lua_State *L, int index);</pre>
3746
3747 <p>
3748 Returns 1 if the value at the given index is an integer
3749 (that is, the value is a number and is represented as an integer),
3750 and 0&nbsp;otherwise.
3751
3752
3753
3754
3755
3756 <hr><h3><a name="lua_islightuserdata"><code>lua_islightuserdata</code></a></h3><p>
3757 <span class="apii">[-0, +0, &ndash;]</span>
3758 <pre>int lua_islightuserdata (lua_State *L, int index);</pre>
3759
3760 <p>
3761 Returns 1 if the value at the given index is a light userdata,
3762 and 0&nbsp;otherwise.
3763
3764
3765
3766
3767
3768 <hr><h3><a name="lua_isnil"><code>lua_isnil</code></a></h3><p>
3769 <span class="apii">[-0, +0, &ndash;]</span>
3770 <pre>int lua_isnil (lua_State *L, int index);</pre>
3771
3772 <p>
3773 Returns 1 if the value at the given index is <b>nil</b>,
3774 and 0&nbsp;otherwise.
3775
3776
3777
3778
3779
3780 <hr><h3><a name="lua_isnone"><code>lua_isnone</code></a></h3><p>
3781 <span class="apii">[-0, +0, &ndash;]</span>
3782 <pre>int lua_isnone (lua_State *L, int index);</pre>
3783
3784 <p>
3785 Returns 1 if the given index is not valid,
3786 and 0&nbsp;otherwise.
3787
3788
3789
3790
3791
3792 <hr><h3><a name="lua_isnoneornil"><code>lua_isnoneornil</code></a></h3><p>
3793 <span class="apii">[-0, +0, &ndash;]</span>
3794 <pre>int lua_isnoneornil (lua_State *L, int index);</pre>
3795
3796 <p>
3797 Returns 1 if the given index is not valid
3798 or if the value at this index is <b>nil</b>,
3799 and 0&nbsp;otherwise.
3800
3801
3802
3803
3804
3805 <hr><h3><a name="lua_isnumber"><code>lua_isnumber</code></a></h3><p>
3806 <span class="apii">[-0, +0, &ndash;]</span>
3807 <pre>int lua_isnumber (lua_State *L, int index);</pre>
3808
3809 <p>
3810 Returns 1 if the value at the given index is a number
3811 or a string convertible to a number,
3812 and 0&nbsp;otherwise.
3813
3814
3815
3816
3817
3818 <hr><h3><a name="lua_isstring"><code>lua_isstring</code></a></h3><p>
3819 <span class="apii">[-0, +0, &ndash;]</span>
3820 <pre>int lua_isstring (lua_State *L, int index);</pre>
3821
3822 <p>
3823 Returns 1 if the value at the given index is a string
3824 or a number (which is always convertible to a string),
3825 and 0&nbsp;otherwise.
3826
3827
3828
3829
3830
3831 <hr><h3><a name="lua_istable"><code>lua_istable</code></a></h3><p>
3832 <span class="apii">[-0, +0, &ndash;]</span>
3833 <pre>int lua_istable (lua_State *L, int index);</pre>
3834
3835 <p>
3836 Returns 1 if the value at the given index is a table,
3837 and 0&nbsp;otherwise.
3838
3839
3840
3841
3842
3843 <hr><h3><a name="lua_isthread"><code>lua_isthread</code></a></h3><p>
3844 <span class="apii">[-0, +0, &ndash;]</span>
3845 <pre>int lua_isthread (lua_State *L, int index);</pre>
3846
3847 <p>
3848 Returns 1 if the value at the given index is a thread,
3849 and 0&nbsp;otherwise.
3850
3851
3852
3853
3854
3855 <hr><h3><a name="lua_isuserdata"><code>lua_isuserdata</code></a></h3><p>
3856 <span class="apii">[-0, +0, &ndash;]</span>
3857 <pre>int lua_isuserdata (lua_State *L, int index);</pre>
3858
3859 <p>
3860 Returns 1 if the value at the given index is a userdata
3861 (either full or light), and 0&nbsp;otherwise.
3862
3863
3864
3865
3866
3867 <hr><h3><a name="lua_isyieldable"><code>lua_isyieldable</code></a></h3><p>
3868 <span class="apii">[-0, +0, &ndash;]</span>
3869 <pre>int lua_isyieldable (lua_State *L);</pre>
3870
3871 <p>
3872 Returns 1 if the given coroutine can yield,
3873 and 0&nbsp;otherwise.
3874
3875
3876
3877
3878
3879 <hr><h3><a name="lua_KContext"><code>lua_KContext</code></a></h3>
3880 <pre>typedef ... lua_KContext;</pre>
3881
3882 <p>
3883 The type for continuation-function contexts.
3884 It must be a numeric type.
3885 This type is defined as <code>intptr_t</code>
3886 when <code>intptr_t</code> is available,
3887 so that it can store pointers too.
3888 Otherwise, it is defined as <code>ptrdiff_t</code>.
3889
3890
3891
3892
3893
3894 <hr><h3><a name="lua_KFunction"><code>lua_KFunction</code></a></h3>
3895 <pre>typedef int (*lua_KFunction) (lua_State *L, int status, lua_KContext ctx);</pre>
3896
3897 <p>
3898 Type for continuation functions (see <a href="#4.7">&sect;4.7</a>).
3899
3900
3901
3902
3903
3904 <hr><h3><a name="lua_len"><code>lua_len</code></a></h3><p>
3905 <span class="apii">[-0, +1, <em>e</em>]</span>
3906 <pre>void lua_len (lua_State *L, int index);</pre>
3907
3908 <p>
3909 Returns the length of the value at the given index.
3910 It is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">&sect;3.4.7</a>) and
3911 may trigger a metamethod for the "length" event (see <a href="#2.4">&sect;2.4</a>).
3912 The result is pushed on the stack.
3913
3914
3915
3916
3917
3918 <hr><h3><a name="lua_load"><code>lua_load</code></a></h3><p>
3919 <span class="apii">[-0, +1, &ndash;]</span>
3920 <pre>int lua_load (lua_State *L,
3921               lua_Reader reader,
3922               void *data,
3923               const char *chunkname,
3924               const char *mode);</pre>
3925
3926 <p>
3927 Loads a Lua chunk without running it.
3928 If there are no errors,
3929 <code>lua_load</code> pushes the compiled chunk as a Lua
3930 function on top of the stack.
3931 Otherwise, it pushes an error message.
3932
3933
3934 <p>
3935 The return values of <code>lua_load</code> are:
3936
3937 <ul>
3938
3939 <li><b><a href="#pdf-LUA_OK"><code>LUA_OK</code></a>: </b> no errors;</li>
3940
3941 <li><b><a name="pdf-LUA_ERRSYNTAX"><code>LUA_ERRSYNTAX</code></a>: </b>
3942 syntax error during precompilation;</li>
3943
3944 <li><b><a href="#pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>: </b>
3945 memory allocation (out-of-memory) error;</li>
3946
3947 <li><b><a href="#pdf-LUA_ERRGCMM"><code>LUA_ERRGCMM</code></a>: </b>
3948 error while running a <code>__gc</code> metamethod.
3949 (This error has no relation with the chunk being loaded.
3950 It is generated by the garbage collector.)
3951 </li>
3952
3953 </ul>
3954
3955 <p>
3956 The <code>lua_load</code> function uses a user-supplied <code>reader</code> function
3957 to read the chunk (see <a href="#lua_Reader"><code>lua_Reader</code></a>).
3958 The <code>data</code> argument is an opaque value passed to the reader function.
3959
3960
3961 <p>
3962 The <code>chunkname</code> argument gives a name to the chunk,
3963 which is used for error messages and in debug information (see <a href="#4.9">&sect;4.9</a>).
3964
3965
3966 <p>
3967 <code>lua_load</code> automatically detects whether the chunk is text or binary
3968 and loads it accordingly (see program <code>luac</code>).
3969 The string <code>mode</code> works as in function <a href="#pdf-load"><code>load</code></a>,
3970 with the addition that
3971 a <code>NULL</code> value is equivalent to the string "<code>bt</code>".
3972
3973
3974 <p>
3975 <code>lua_load</code> uses the stack internally,
3976 so the reader function must always leave the stack
3977 unmodified when returning.
3978
3979
3980 <p>
3981 If the resulting function has upvalues,
3982 its first upvalue is set to the value of the global environment
3983 stored at index <code>LUA_RIDX_GLOBALS</code> in the registry (see <a href="#4.5">&sect;4.5</a>).
3984 When loading main chunks,
3985 this upvalue will be the <code>_ENV</code> variable (see <a href="#2.2">&sect;2.2</a>).
3986 Other upvalues are initialized with <b>nil</b>.
3987
3988
3989
3990
3991
3992 <hr><h3><a name="lua_newstate"><code>lua_newstate</code></a></h3><p>
3993 <span class="apii">[-0, +0, &ndash;]</span>
3994 <pre>lua_State *lua_newstate (lua_Alloc f, void *ud);</pre>
3995
3996 <p>
3997 Creates a new thread running in a new, independent state.
3998 Returns <code>NULL</code> if it cannot create the thread or the state
3999 (due to lack of memory).
4000 The argument <code>f</code> is the allocator function;
4001 Lua does all memory allocation for this state through this function.
4002 The second argument, <code>ud</code>, is an opaque pointer that Lua
4003 passes to the allocator in every call.
4004
4005
4006
4007
4008
4009 <hr><h3><a name="lua_newtable"><code>lua_newtable</code></a></h3><p>
4010 <span class="apii">[-0, +1, <em>m</em>]</span>
4011 <pre>void lua_newtable (lua_State *L);</pre>
4012
4013 <p>
4014 Creates a new empty table and pushes it onto the stack.
4015 It is equivalent to <code>lua_createtable(L, 0, 0)</code>.
4016
4017
4018
4019
4020
4021 <hr><h3><a name="lua_newthread"><code>lua_newthread</code></a></h3><p>
4022 <span class="apii">[-0, +1, <em>m</em>]</span>
4023 <pre>lua_State *lua_newthread (lua_State *L);</pre>
4024
4025 <p>
4026 Creates a new thread, pushes it on the stack,
4027 and returns a pointer to a <a href="#lua_State"><code>lua_State</code></a> that represents this new thread.
4028 The new thread returned by this function shares with the original thread
4029 its global environment,
4030 but has an independent execution stack.
4031
4032
4033 <p>
4034 There is no explicit function to close or to destroy a thread.
4035 Threads are subject to garbage collection,
4036 like any Lua object.
4037
4038
4039
4040
4041
4042 <hr><h3><a name="lua_newuserdata"><code>lua_newuserdata</code></a></h3><p>
4043 <span class="apii">[-0, +1, <em>m</em>]</span>
4044 <pre>void *lua_newuserdata (lua_State *L, size_t size);</pre>
4045
4046 <p>
4047 This function allocates a new block of memory with the given size,
4048 pushes onto the stack a new full userdata with the block address,
4049 and returns this address.
4050 The host program can freely use this memory.
4051
4052
4053
4054
4055
4056 <hr><h3><a name="lua_next"><code>lua_next</code></a></h3><p>
4057 <span class="apii">[-1, +(2|0), <em>e</em>]</span>
4058 <pre>int lua_next (lua_State *L, int index);</pre>
4059
4060 <p>
4061 Pops a key from the stack,
4062 and pushes a key&ndash;value pair from the table at the given index
4063 (the "next" pair after the given key).
4064 If there are no more elements in the table,
4065 then <a href="#lua_next"><code>lua_next</code></a> returns 0 (and pushes nothing).
4066
4067
4068 <p>
4069 A typical traversal looks like this:
4070
4071 <pre>
4072      /* table is in the stack at index 't' */
4073      lua_pushnil(L);  /* first key */
4074      while (lua_next(L, t) != 0) {
4075        /* uses 'key' (at index -2) and 'value' (at index -1) */
4076        printf("%s - %s\n",
4077               lua_typename(L, lua_type(L, -2)),
4078               lua_typename(L, lua_type(L, -1)));
4079        /* removes 'value'; keeps 'key' for next iteration */
4080        lua_pop(L, 1);
4081      }
4082 </pre>
4083
4084 <p>
4085 While traversing a table,
4086 do not call <a href="#lua_tolstring"><code>lua_tolstring</code></a> directly on a key,
4087 unless you know that the key is actually a string.
4088 Recall that <a href="#lua_tolstring"><code>lua_tolstring</code></a> may change
4089 the value at the given index;
4090 this confuses the next call to <a href="#lua_next"><code>lua_next</code></a>.
4091
4092
4093 <p>
4094 See function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying
4095 the table during its traversal.
4096
4097
4098
4099
4100
4101 <hr><h3><a name="lua_Number"><code>lua_Number</code></a></h3>
4102 <pre>typedef ... lua_Number;</pre>
4103
4104 <p>
4105 The type of floats in Lua.
4106
4107
4108 <p>
4109 By default this type is double,
4110 but that can be changed to a single float or a long double.
4111 (See <code>LUA_FLOAT_TYPE</code> in <code>luaconf.h</code>.)
4112
4113
4114
4115
4116
4117 <hr><h3><a name="lua_numbertointeger"><code>lua_numbertointeger</code></a></h3>
4118 <pre>int lua_numbertointeger (lua_Number n, lua_Integer *p);</pre>
4119
4120 <p>
4121 Converts a Lua float to a Lua integer.
4122 This macro assumes that <code>n</code> has an integral value.
4123 If that value is within the range of Lua integers,
4124 it is converted to an integer and assigned to <code>*p</code>.
4125 The macro results in a boolean indicating whether the
4126 conversion was successful.
4127 (Note that this range test can be tricky to do
4128 correctly without this macro,
4129 due to roundings.)
4130
4131
4132 <p>
4133 This macro may evaluate its arguments more than once.
4134
4135
4136
4137
4138
4139 <hr><h3><a name="lua_pcall"><code>lua_pcall</code></a></h3><p>
4140 <span class="apii">[-(nargs + 1), +(nresults|1), &ndash;]</span>
4141 <pre>int lua_pcall (lua_State *L, int nargs, int nresults, int msgh);</pre>
4142
4143 <p>
4144 Calls a function in protected mode.
4145
4146
4147 <p>
4148 Both <code>nargs</code> and <code>nresults</code> have the same meaning as
4149 in <a href="#lua_call"><code>lua_call</code></a>.
4150 If there are no errors during the call,
4151 <a href="#lua_pcall"><code>lua_pcall</code></a> behaves exactly like <a href="#lua_call"><code>lua_call</code></a>.
4152 However, if there is any error,
4153 <a href="#lua_pcall"><code>lua_pcall</code></a> catches it,
4154 pushes a single value on the stack (the error object),
4155 and returns an error code.
4156 Like <a href="#lua_call"><code>lua_call</code></a>,
4157 <a href="#lua_pcall"><code>lua_pcall</code></a> always removes the function
4158 and its arguments from the stack.
4159
4160
4161 <p>
4162 If <code>msgh</code> is 0,
4163 then the error object returned on the stack
4164 is exactly the original error object.
4165 Otherwise, <code>msgh</code> is the stack index of a
4166 <em>message handler</em>.
4167 (This index cannot be a pseudo-index.)
4168 In case of runtime errors,
4169 this function will be called with the error object
4170 and its return value will be the object
4171 returned on the stack by <a href="#lua_pcall"><code>lua_pcall</code></a>.
4172
4173
4174 <p>
4175 Typically, the message handler is used to add more debug
4176 information to the error object, such as a stack traceback.
4177 Such information cannot be gathered after the return of <a href="#lua_pcall"><code>lua_pcall</code></a>,
4178 since by then the stack has unwound.
4179
4180
4181 <p>
4182 The <a href="#lua_pcall"><code>lua_pcall</code></a> function returns one of the following constants
4183 (defined in <code>lua.h</code>):
4184
4185 <ul>
4186
4187 <li><b><a name="pdf-LUA_OK"><code>LUA_OK</code></a> (0): </b>
4188 success.</li>
4189
4190 <li><b><a name="pdf-LUA_ERRRUN"><code>LUA_ERRRUN</code></a>: </b>
4191 a runtime error.
4192 </li>
4193
4194 <li><b><a name="pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>: </b>
4195 memory allocation error.
4196 For such errors, Lua does not call the message handler.
4197 </li>
4198
4199 <li><b><a name="pdf-LUA_ERRERR"><code>LUA_ERRERR</code></a>: </b>
4200 error while running the message handler.
4201 </li>
4202
4203 <li><b><a name="pdf-LUA_ERRGCMM"><code>LUA_ERRGCMM</code></a>: </b>
4204 error while running a <code>__gc</code> metamethod.
4205 (This error typically has no relation with the function being called.)
4206 </li>
4207
4208 </ul>
4209
4210
4211
4212
4213 <hr><h3><a name="lua_pcallk"><code>lua_pcallk</code></a></h3><p>
4214 <span class="apii">[-(nargs + 1), +(nresults|1), &ndash;]</span>
4215 <pre>int lua_pcallk (lua_State *L,
4216                 int nargs,
4217                 int nresults,
4218                 int msgh,
4219                 lua_KContext ctx,
4220                 lua_KFunction k);</pre>
4221
4222 <p>
4223 This function behaves exactly like <a href="#lua_pcall"><code>lua_pcall</code></a>,
4224 but allows the called function to yield (see <a href="#4.7">&sect;4.7</a>).
4225
4226
4227
4228
4229
4230 <hr><h3><a name="lua_pop"><code>lua_pop</code></a></h3><p>
4231 <span class="apii">[-n, +0, &ndash;]</span>
4232 <pre>void lua_pop (lua_State *L, int n);</pre>
4233
4234 <p>
4235 Pops <code>n</code> elements from the stack.
4236
4237
4238
4239
4240
4241 <hr><h3><a name="lua_pushboolean"><code>lua_pushboolean</code></a></h3><p>
4242 <span class="apii">[-0, +1, &ndash;]</span>
4243 <pre>void lua_pushboolean (lua_State *L, int b);</pre>
4244
4245 <p>
4246 Pushes a boolean value with value <code>b</code> onto the stack.
4247
4248
4249
4250
4251
4252 <hr><h3><a name="lua_pushcclosure"><code>lua_pushcclosure</code></a></h3><p>
4253 <span class="apii">[-n, +1, <em>m</em>]</span>
4254 <pre>void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);</pre>
4255
4256 <p>
4257 Pushes a new C&nbsp;closure onto the stack.
4258
4259
4260 <p>
4261 When a C&nbsp;function is created,
4262 it is possible to associate some values with it,
4263 thus creating a C&nbsp;closure (see <a href="#4.4">&sect;4.4</a>);
4264 these values are then accessible to the function whenever it is called.
4265 To associate values with a C&nbsp;function,
4266 first these values must be pushed onto the stack
4267 (when there are multiple values, the first value is pushed first).
4268 Then <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>
4269 is called to create and push the C&nbsp;function onto the stack,
4270 with the argument <code>n</code> telling how many values will be
4271 associated with the function.
4272 <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> also pops these values from the stack.
4273
4274
4275 <p>
4276 The maximum value for <code>n</code> is 255.
4277
4278
4279 <p>
4280 When <code>n</code> is zero,
4281 this function creates a <em>light C function</em>,
4282 which is just a pointer to the C&nbsp;function.
4283 In that case, it never raises a memory error.
4284
4285
4286
4287
4288
4289 <hr><h3><a name="lua_pushcfunction"><code>lua_pushcfunction</code></a></h3><p>
4290 <span class="apii">[-0, +1, &ndash;]</span>
4291 <pre>void lua_pushcfunction (lua_State *L, lua_CFunction f);</pre>
4292
4293 <p>
4294 Pushes a C&nbsp;function onto the stack.
4295 This function receives a pointer to a C function
4296 and pushes onto the stack a Lua value of type <code>function</code> that,
4297 when called, invokes the corresponding C&nbsp;function.
4298
4299
4300 <p>
4301 Any function to be callable by Lua must
4302 follow the correct protocol to receive its parameters
4303 and return its results (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>).
4304
4305
4306
4307
4308
4309 <hr><h3><a name="lua_pushfstring"><code>lua_pushfstring</code></a></h3><p>
4310 <span class="apii">[-0, +1, <em>e</em>]</span>
4311 <pre>const char *lua_pushfstring (lua_State *L, const char *fmt, ...);</pre>
4312
4313 <p>
4314 Pushes onto the stack a formatted string
4315 and returns a pointer to this string.
4316 It is similar to the ISO&nbsp;C function <code>sprintf</code>,
4317 but has some important differences:
4318
4319 <ul>
4320
4321 <li>
4322 You do not have to allocate space for the result:
4323 the result is a Lua string and Lua takes care of memory allocation
4324 (and deallocation, through garbage collection).
4325 </li>
4326
4327 <li>
4328 The conversion specifiers are quite restricted.
4329 There are no flags, widths, or precisions.
4330 The conversion specifiers can only be
4331 '<code>%%</code>' (inserts the character '<code>%</code>'),
4332 '<code>%s</code>' (inserts a zero-terminated string, with no size restrictions),
4333 '<code>%f</code>' (inserts a <a href="#lua_Number"><code>lua_Number</code></a>),
4334 '<code>%I</code>' (inserts a <a href="#lua_Integer"><code>lua_Integer</code></a>),
4335 '<code>%p</code>' (inserts a pointer as a hexadecimal numeral),
4336 '<code>%d</code>' (inserts an <code>int</code>),
4337 '<code>%c</code>' (inserts an <code>int</code> as a one-byte character), and
4338 '<code>%U</code>' (inserts a <code>long int</code> as a UTF-8 byte sequence).
4339 </li>
4340
4341 </ul>
4342
4343 <p>
4344 Unlike other push functions,
4345 this function checks for the stack space it needs,
4346 including the slot for its result.
4347
4348
4349
4350
4351
4352 <hr><h3><a name="lua_pushglobaltable"><code>lua_pushglobaltable</code></a></h3><p>
4353 <span class="apii">[-0, +1, &ndash;]</span>
4354 <pre>void lua_pushglobaltable (lua_State *L);</pre>
4355
4356 <p>
4357 Pushes the global environment onto the stack.
4358
4359
4360
4361
4362
4363 <hr><h3><a name="lua_pushinteger"><code>lua_pushinteger</code></a></h3><p>
4364 <span class="apii">[-0, +1, &ndash;]</span>
4365 <pre>void lua_pushinteger (lua_State *L, lua_Integer n);</pre>
4366
4367 <p>
4368 Pushes an integer with value <code>n</code> onto the stack.
4369
4370
4371
4372
4373
4374 <hr><h3><a name="lua_pushlightuserdata"><code>lua_pushlightuserdata</code></a></h3><p>
4375 <span class="apii">[-0, +1, &ndash;]</span>
4376 <pre>void lua_pushlightuserdata (lua_State *L, void *p);</pre>
4377
4378 <p>
4379 Pushes a light userdata onto the stack.
4380
4381
4382 <p>
4383 Userdata represent C&nbsp;values in Lua.
4384 A <em>light userdata</em> represents a pointer, a <code>void*</code>.
4385 It is a value (like a number):
4386 you do not create it, it has no individual metatable,
4387 and it is not collected (as it was never created).
4388 A light userdata is equal to "any"
4389 light userdata with the same C&nbsp;address.
4390
4391
4392
4393
4394
4395 <hr><h3><a name="lua_pushliteral"><code>lua_pushliteral</code></a></h3><p>
4396 <span class="apii">[-0, +1, <em>m</em>]</span>
4397 <pre>const char *lua_pushliteral (lua_State *L, const char *s);</pre>
4398
4399 <p>
4400 This macro is equivalent to <a href="#lua_pushstring"><code>lua_pushstring</code></a>,
4401 but should be used only when <code>s</code> is a literal string.
4402
4403
4404
4405
4406
4407 <hr><h3><a name="lua_pushlstring"><code>lua_pushlstring</code></a></h3><p>
4408 <span class="apii">[-0, +1, <em>m</em>]</span>
4409 <pre>const char *lua_pushlstring (lua_State *L, const char *s, size_t len);</pre>
4410
4411 <p>
4412 Pushes the string pointed to by <code>s</code> with size <code>len</code>
4413 onto the stack.
4414 Lua makes (or reuses) an internal copy of the given string,
4415 so the memory at <code>s</code> can be freed or reused immediately after
4416 the function returns.
4417 The string can contain any binary data,
4418 including embedded zeros.
4419
4420
4421 <p>
4422 Returns a pointer to the internal copy of the string.
4423
4424
4425
4426
4427
4428 <hr><h3><a name="lua_pushnil"><code>lua_pushnil</code></a></h3><p>
4429 <span class="apii">[-0, +1, &ndash;]</span>
4430 <pre>void lua_pushnil (lua_State *L);</pre>
4431
4432 <p>
4433 Pushes a nil value onto the stack.
4434
4435
4436
4437
4438
4439 <hr><h3><a name="lua_pushnumber"><code>lua_pushnumber</code></a></h3><p>
4440 <span class="apii">[-0, +1, &ndash;]</span>
4441 <pre>void lua_pushnumber (lua_State *L, lua_Number n);</pre>
4442
4443 <p>
4444 Pushes a float with value <code>n</code> onto the stack.
4445
4446
4447
4448
4449
4450 <hr><h3><a name="lua_pushstring"><code>lua_pushstring</code></a></h3><p>
4451 <span class="apii">[-0, +1, <em>m</em>]</span>
4452 <pre>const char *lua_pushstring (lua_State *L, const char *s);</pre>
4453
4454 <p>
4455 Pushes the zero-terminated string pointed to by <code>s</code>
4456 onto the stack.
4457 Lua makes (or reuses) an internal copy of the given string,
4458 so the memory at <code>s</code> can be freed or reused immediately after
4459 the function returns.
4460
4461
4462 <p>
4463 Returns a pointer to the internal copy of the string.
4464
4465
4466 <p>
4467 If <code>s</code> is <code>NULL</code>, pushes <b>nil</b> and returns <code>NULL</code>.
4468
4469
4470
4471
4472
4473 <hr><h3><a name="lua_pushthread"><code>lua_pushthread</code></a></h3><p>
4474 <span class="apii">[-0, +1, &ndash;]</span>
4475 <pre>int lua_pushthread (lua_State *L);</pre>
4476
4477 <p>
4478 Pushes the thread represented by <code>L</code> onto the stack.
4479 Returns 1 if this thread is the main thread of its state.
4480
4481
4482
4483
4484
4485 <hr><h3><a name="lua_pushvalue"><code>lua_pushvalue</code></a></h3><p>
4486 <span class="apii">[-0, +1, &ndash;]</span>
4487 <pre>void lua_pushvalue (lua_State *L, int index);</pre>
4488
4489 <p>
4490 Pushes a copy of the element at the given index
4491 onto the stack.
4492
4493
4494
4495
4496
4497 <hr><h3><a name="lua_pushvfstring"><code>lua_pushvfstring</code></a></h3><p>
4498 <span class="apii">[-0, +1, <em>m</em>]</span>
4499 <pre>const char *lua_pushvfstring (lua_State *L,
4500                               const char *fmt,
4501                               va_list argp);</pre>
4502
4503 <p>
4504 Equivalent to <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>, except that it receives a <code>va_list</code>
4505 instead of a variable number of arguments.
4506
4507
4508
4509
4510
4511 <hr><h3><a name="lua_rawequal"><code>lua_rawequal</code></a></h3><p>
4512 <span class="apii">[-0, +0, &ndash;]</span>
4513 <pre>int lua_rawequal (lua_State *L, int index1, int index2);</pre>
4514
4515 <p>
4516 Returns 1 if the two values in indices <code>index1</code> and
4517 <code>index2</code> are primitively equal
4518 (that is, without calling the <code>__eq</code> metamethod).
4519 Otherwise returns&nbsp;0.
4520 Also returns&nbsp;0 if any of the indices are not valid.
4521
4522
4523
4524
4525
4526 <hr><h3><a name="lua_rawget"><code>lua_rawget</code></a></h3><p>
4527 <span class="apii">[-1, +1, &ndash;]</span>
4528 <pre>int lua_rawget (lua_State *L, int index);</pre>
4529
4530 <p>
4531 Similar to <a href="#lua_gettable"><code>lua_gettable</code></a>, but does a raw access
4532 (i.e., without metamethods).
4533
4534
4535
4536
4537
4538 <hr><h3><a name="lua_rawgeti"><code>lua_rawgeti</code></a></h3><p>
4539 <span class="apii">[-0, +1, &ndash;]</span>
4540 <pre>int lua_rawgeti (lua_State *L, int index, lua_Integer n);</pre>
4541
4542 <p>
4543 Pushes onto the stack the value <code>t[n]</code>,
4544 where <code>t</code> is the table at the given index.
4545 The access is raw,
4546 that is, it does not invoke the <code>__index</code> metamethod.
4547
4548
4549 <p>
4550 Returns the type of the pushed value.
4551
4552
4553
4554
4555
4556 <hr><h3><a name="lua_rawgetp"><code>lua_rawgetp</code></a></h3><p>
4557 <span class="apii">[-0, +1, &ndash;]</span>
4558 <pre>int lua_rawgetp (lua_State *L, int index, const void *p);</pre>
4559
4560 <p>
4561 Pushes onto the stack the value <code>t[k]</code>,
4562 where <code>t</code> is the table at the given index and
4563 <code>k</code> is the pointer <code>p</code> represented as a light userdata.
4564 The access is raw;
4565 that is, it does not invoke the <code>__index</code> metamethod.
4566
4567
4568 <p>
4569 Returns the type of the pushed value.
4570
4571
4572
4573
4574
4575 <hr><h3><a name="lua_rawlen"><code>lua_rawlen</code></a></h3><p>
4576 <span class="apii">[-0, +0, &ndash;]</span>
4577 <pre>size_t lua_rawlen (lua_State *L, int index);</pre>
4578
4579 <p>
4580 Returns the raw "length" of the value at the given index:
4581 for strings, this is the string length;
4582 for tables, this is the result of the length operator ('<code>#</code>')
4583 with no metamethods;
4584 for userdata, this is the size of the block of memory allocated
4585 for the userdata;
4586 for other values, it is&nbsp;0.
4587
4588
4589
4590
4591
4592 <hr><h3><a name="lua_rawset"><code>lua_rawset</code></a></h3><p>
4593 <span class="apii">[-2, +0, <em>m</em>]</span>
4594 <pre>void lua_rawset (lua_State *L, int index);</pre>
4595
4596 <p>
4597 Similar to <a href="#lua_settable"><code>lua_settable</code></a>, but does a raw assignment
4598 (i.e., without metamethods).
4599
4600
4601
4602
4603
4604 <hr><h3><a name="lua_rawseti"><code>lua_rawseti</code></a></h3><p>
4605 <span class="apii">[-1, +0, <em>m</em>]</span>
4606 <pre>void lua_rawseti (lua_State *L, int index, lua_Integer i);</pre>
4607
4608 <p>
4609 Does the equivalent of <code>t[i] = v</code>,
4610 where <code>t</code> is the table at the given index
4611 and <code>v</code> is the value at the top of the stack.
4612
4613
4614 <p>
4615 This function pops the value from the stack.
4616 The assignment is raw,
4617 that is, it does not invoke the <code>__newindex</code> metamethod.
4618
4619
4620
4621
4622
4623 <hr><h3><a name="lua_rawsetp"><code>lua_rawsetp</code></a></h3><p>
4624 <span class="apii">[-1, +0, <em>m</em>]</span>
4625 <pre>void lua_rawsetp (lua_State *L, int index, const void *p);</pre>
4626
4627 <p>
4628 Does the equivalent of <code>t[p] = v</code>,
4629 where <code>t</code> is the table at the given index,
4630 <code>p</code> is encoded as a light userdata,
4631 and <code>v</code> is the value at the top of the stack.
4632
4633
4634 <p>
4635 This function pops the value from the stack.
4636 The assignment is raw,
4637 that is, it does not invoke <code>__newindex</code> metamethod.
4638
4639
4640
4641
4642
4643 <hr><h3><a name="lua_Reader"><code>lua_Reader</code></a></h3>
4644 <pre>typedef const char * (*lua_Reader) (lua_State *L,
4645                                     void *data,
4646                                     size_t *size);</pre>
4647
4648 <p>
4649 The reader function used by <a href="#lua_load"><code>lua_load</code></a>.
4650 Every time it needs another piece of the chunk,
4651 <a href="#lua_load"><code>lua_load</code></a> calls the reader,
4652 passing along its <code>data</code> parameter.
4653 The reader must return a pointer to a block of memory
4654 with a new piece of the chunk
4655 and set <code>size</code> to the block size.
4656 The block must exist until the reader function is called again.
4657 To signal the end of the chunk,
4658 the reader must return <code>NULL</code> or set <code>size</code> to zero.
4659 The reader function may return pieces of any size greater than zero.
4660
4661
4662
4663
4664
4665 <hr><h3><a name="lua_register"><code>lua_register</code></a></h3><p>
4666 <span class="apii">[-0, +0, <em>e</em>]</span>
4667 <pre>void lua_register (lua_State *L, const char *name, lua_CFunction f);</pre>
4668
4669 <p>
4670 Sets the C function <code>f</code> as the new value of global <code>name</code>.
4671 It is defined as a macro:
4672
4673 <pre>
4674      #define lua_register(L,n,f) \
4675             (lua_pushcfunction(L, f), lua_setglobal(L, n))
4676 </pre>
4677
4678
4679
4680
4681 <hr><h3><a name="lua_remove"><code>lua_remove</code></a></h3><p>
4682 <span class="apii">[-1, +0, &ndash;]</span>
4683 <pre>void lua_remove (lua_State *L, int index);</pre>
4684
4685 <p>
4686 Removes the element at the given valid index,
4687 shifting down the elements above this index to fill the gap.
4688 This function cannot be called with a pseudo-index,
4689 because a pseudo-index is not an actual stack position.
4690
4691
4692
4693
4694
4695 <hr><h3><a name="lua_replace"><code>lua_replace</code></a></h3><p>
4696 <span class="apii">[-1, +0, &ndash;]</span>
4697 <pre>void lua_replace (lua_State *L, int index);</pre>
4698
4699 <p>
4700 Moves the top element into the given valid index
4701 without shifting any element
4702 (therefore replacing the value at that given index),
4703 and then pops the top element.
4704
4705
4706
4707
4708
4709 <hr><h3><a name="lua_resume"><code>lua_resume</code></a></h3><p>
4710 <span class="apii">[-?, +?, &ndash;]</span>
4711 <pre>int lua_resume (lua_State *L, lua_State *from, int nargs);</pre>
4712
4713 <p>
4714 Starts and resumes a coroutine in the given thread <code>L</code>.
4715
4716
4717 <p>
4718 To start a coroutine,
4719 you push onto the thread stack the main function plus any arguments;
4720 then you call <a href="#lua_resume"><code>lua_resume</code></a>,
4721 with <code>nargs</code> being the number of arguments.
4722 This call returns when the coroutine suspends or finishes its execution.
4723 When it returns, the stack contains all values passed to <a href="#lua_yield"><code>lua_yield</code></a>,
4724 or all values returned by the body function.
4725 <a href="#lua_resume"><code>lua_resume</code></a> returns
4726 <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the coroutine yields,
4727 <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> if the coroutine finishes its execution
4728 without errors,
4729 or an error code in case of errors (see <a href="#lua_pcall"><code>lua_pcall</code></a>).
4730
4731
4732 <p>
4733 In case of errors,
4734 the stack is not unwound,
4735 so you can use the debug API over it.
4736 The error object is on the top of the stack.
4737
4738
4739 <p>
4740 To resume a coroutine,
4741 you remove any results from the last <a href="#lua_yield"><code>lua_yield</code></a>,
4742 put on its stack only the values to
4743 be passed as results from <code>yield</code>,
4744 and then call <a href="#lua_resume"><code>lua_resume</code></a>.
4745
4746
4747 <p>
4748 The parameter <code>from</code> represents the coroutine that is resuming <code>L</code>.
4749 If there is no such coroutine,
4750 this parameter can be <code>NULL</code>.
4751
4752
4753
4754
4755
4756 <hr><h3><a name="lua_rotate"><code>lua_rotate</code></a></h3><p>
4757 <span class="apii">[-0, +0, &ndash;]</span>
4758 <pre>void lua_rotate (lua_State *L, int idx, int n);</pre>
4759
4760 <p>
4761 Rotates the stack elements between the valid index <code>idx</code>
4762 and the top of the stack.
4763 The elements are rotated <code>n</code> positions in the direction of the top,
4764 for a positive <code>n</code>,
4765 or <code>-n</code> positions in the direction of the bottom,
4766 for a negative <code>n</code>.
4767 The absolute value of <code>n</code> must not be greater than the size
4768 of the slice being rotated.
4769 This function cannot be called with a pseudo-index,
4770 because a pseudo-index is not an actual stack position.
4771
4772
4773
4774
4775
4776 <hr><h3><a name="lua_setallocf"><code>lua_setallocf</code></a></h3><p>
4777 <span class="apii">[-0, +0, &ndash;]</span>
4778 <pre>void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);</pre>
4779
4780 <p>
4781 Changes the allocator function of a given state to <code>f</code>
4782 with user data <code>ud</code>.
4783
4784
4785
4786
4787
4788 <hr><h3><a name="lua_setfield"><code>lua_setfield</code></a></h3><p>
4789 <span class="apii">[-1, +0, <em>e</em>]</span>
4790 <pre>void lua_setfield (lua_State *L, int index, const char *k);</pre>
4791
4792 <p>
4793 Does the equivalent to <code>t[k] = v</code>,
4794 where <code>t</code> is the value at the given index
4795 and <code>v</code> is the value at the top of the stack.
4796
4797
4798 <p>
4799 This function pops the value from the stack.
4800 As in Lua, this function may trigger a metamethod
4801 for the "newindex" event (see <a href="#2.4">&sect;2.4</a>).
4802
4803
4804
4805
4806
4807 <hr><h3><a name="lua_setglobal"><code>lua_setglobal</code></a></h3><p>
4808 <span class="apii">[-1, +0, <em>e</em>]</span>
4809 <pre>void lua_setglobal (lua_State *L, const char *name);</pre>
4810
4811 <p>
4812 Pops a value from the stack and
4813 sets it as the new value of global <code>name</code>.
4814
4815
4816
4817
4818
4819 <hr><h3><a name="lua_seti"><code>lua_seti</code></a></h3><p>
4820 <span class="apii">[-1, +0, <em>e</em>]</span>
4821 <pre>void lua_seti (lua_State *L, int index, lua_Integer n);</pre>
4822
4823 <p>
4824 Does the equivalent to <code>t[n] = v</code>,
4825 where <code>t</code> is the value at the given index
4826 and <code>v</code> is the value at the top of the stack.
4827
4828
4829 <p>
4830 This function pops the value from the stack.
4831 As in Lua, this function may trigger a metamethod
4832 for the "newindex" event (see <a href="#2.4">&sect;2.4</a>).
4833
4834
4835
4836
4837
4838 <hr><h3><a name="lua_setmetatable"><code>lua_setmetatable</code></a></h3><p>
4839 <span class="apii">[-1, +0, &ndash;]</span>
4840 <pre>void lua_setmetatable (lua_State *L, int index);</pre>
4841
4842 <p>
4843 Pops a table from the stack and
4844 sets it as the new metatable for the value at the given index.
4845
4846
4847
4848
4849
4850 <hr><h3><a name="lua_settable"><code>lua_settable</code></a></h3><p>
4851 <span class="apii">[-2, +0, <em>e</em>]</span>
4852 <pre>void lua_settable (lua_State *L, int index);</pre>
4853
4854 <p>
4855 Does the equivalent to <code>t[k] = v</code>,
4856 where <code>t</code> is the value at the given index,
4857 <code>v</code> is the value at the top of the stack,
4858 and <code>k</code> is the value just below the top.
4859
4860
4861 <p>
4862 This function pops both the key and the value from the stack.
4863 As in Lua, this function may trigger a metamethod
4864 for the "newindex" event (see <a href="#2.4">&sect;2.4</a>).
4865
4866
4867
4868
4869
4870 <hr><h3><a name="lua_settop"><code>lua_settop</code></a></h3><p>
4871 <span class="apii">[-?, +?, &ndash;]</span>
4872 <pre>void lua_settop (lua_State *L, int index);</pre>
4873
4874 <p>
4875 Accepts any index, or&nbsp;0,
4876 and sets the stack top to this index.
4877 If the new top is larger than the old one,
4878 then the new elements are filled with <b>nil</b>.
4879 If <code>index</code> is&nbsp;0, then all stack elements are removed.
4880
4881
4882
4883
4884
4885 <hr><h3><a name="lua_setuservalue"><code>lua_setuservalue</code></a></h3><p>
4886 <span class="apii">[-1, +0, &ndash;]</span>
4887 <pre>void lua_setuservalue (lua_State *L, int index);</pre>
4888
4889 <p>
4890 Pops a value from the stack and sets it as
4891 the new value associated to the userdata at the given index.
4892
4893
4894
4895
4896
4897 <hr><h3><a name="lua_State"><code>lua_State</code></a></h3>
4898 <pre>typedef struct lua_State lua_State;</pre>
4899
4900 <p>
4901 An opaque structure that points to a thread and indirectly
4902 (through the thread) to the whole state of a Lua interpreter.
4903 The Lua library is fully reentrant:
4904 it has no global variables.
4905 All information about a state is accessible through this structure.
4906
4907
4908 <p>
4909 A pointer to this structure must be passed as the first argument to
4910 every function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>,
4911 which creates a Lua state from scratch.
4912
4913
4914
4915
4916
4917 <hr><h3><a name="lua_status"><code>lua_status</code></a></h3><p>
4918 <span class="apii">[-0, +0, &ndash;]</span>
4919 <pre>int lua_status (lua_State *L);</pre>
4920
4921 <p>
4922 Returns the status of the thread <code>L</code>.
4923
4924
4925 <p>
4926 The status can be 0 (<a href="#pdf-LUA_OK"><code>LUA_OK</code></a>) for a normal thread,
4927 an error code if the thread finished the execution
4928 of a <a href="#lua_resume"><code>lua_resume</code></a> with an error,
4929 or <a name="pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the thread is suspended.
4930
4931
4932 <p>
4933 You can only call functions in threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>.
4934 You can resume threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>
4935 (to start a new coroutine) or <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a>
4936 (to resume a coroutine).
4937
4938
4939
4940
4941
4942 <hr><h3><a name="lua_stringtonumber"><code>lua_stringtonumber</code></a></h3><p>
4943 <span class="apii">[-0, +1, &ndash;]</span>
4944 <pre>size_t lua_stringtonumber (lua_State *L, const char *s);</pre>
4945
4946 <p>
4947 Converts the zero-terminated string <code>s</code> to a number,
4948 pushes that number into the stack,
4949 and returns the total size of the string,
4950 that is, its length plus one.
4951 The conversion can result in an integer or a float,
4952 according to the lexical conventions of Lua (see <a href="#3.1">&sect;3.1</a>).
4953 The string may have leading and trailing spaces and a sign.
4954 If the string is not a valid numeral,
4955 returns 0 and pushes nothing.
4956 (Note that the result can be used as a boolean,
4957 true if the conversion succeeds.)
4958
4959
4960
4961
4962
4963 <hr><h3><a name="lua_toboolean"><code>lua_toboolean</code></a></h3><p>
4964 <span class="apii">[-0, +0, &ndash;]</span>
4965 <pre>int lua_toboolean (lua_State *L, int index);</pre>
4966
4967 <p>
4968 Converts the Lua value at the given index to a C&nbsp;boolean
4969 value (0&nbsp;or&nbsp;1).
4970 Like all tests in Lua,
4971 <a href="#lua_toboolean"><code>lua_toboolean</code></a> returns true for any Lua value
4972 different from <b>false</b> and <b>nil</b>;
4973 otherwise it returns false.
4974 (If you want to accept only actual boolean values,
4975 use <a href="#lua_isboolean"><code>lua_isboolean</code></a> to test the value's type.)
4976
4977
4978
4979
4980
4981 <hr><h3><a name="lua_tocfunction"><code>lua_tocfunction</code></a></h3><p>
4982 <span class="apii">[-0, +0, &ndash;]</span>
4983 <pre>lua_CFunction lua_tocfunction (lua_State *L, int index);</pre>
4984
4985 <p>
4986 Converts a value at the given index to a C&nbsp;function.
4987 That value must be a C&nbsp;function;
4988 otherwise, returns <code>NULL</code>.
4989
4990
4991
4992
4993
4994 <hr><h3><a name="lua_tointeger"><code>lua_tointeger</code></a></h3><p>
4995 <span class="apii">[-0, +0, &ndash;]</span>
4996 <pre>lua_Integer lua_tointeger (lua_State *L, int index);</pre>
4997
4998 <p>
4999 Equivalent to <a href="#lua_tointegerx"><code>lua_tointegerx</code></a> with <code>isnum</code> equal to <code>NULL</code>.
5000
5001
5002
5003
5004
5005 <hr><h3><a name="lua_tointegerx"><code>lua_tointegerx</code></a></h3><p>
5006 <span class="apii">[-0, +0, &ndash;]</span>
5007 <pre>lua_Integer lua_tointegerx (lua_State *L, int index, int *isnum);</pre>
5008
5009 <p>
5010 Converts the Lua value at the given index
5011 to the signed integral type <a href="#lua_Integer"><code>lua_Integer</code></a>.
5012 The Lua value must be an integer,
5013 or a number or string convertible to an integer (see <a href="#3.4.3">&sect;3.4.3</a>);
5014 otherwise, <code>lua_tointegerx</code> returns&nbsp;0.
5015
5016
5017 <p>
5018 If <code>isnum</code> is not <code>NULL</code>,
5019 its referent is assigned a boolean value that
5020 indicates whether the operation succeeded.
5021
5022
5023
5024
5025
5026 <hr><h3><a name="lua_tolstring"><code>lua_tolstring</code></a></h3><p>
5027 <span class="apii">[-0, +0, <em>m</em>]</span>
5028 <pre>const char *lua_tolstring (lua_State *L, int index, size_t *len);</pre>
5029
5030 <p>
5031 Converts the Lua value at the given index to a C&nbsp;string.
5032 If <code>len</code> is not <code>NULL</code>,
5033 it sets <code>*len</code> with the string length.
5034 The Lua value must be a string or a number;
5035 otherwise, the function returns <code>NULL</code>.
5036 If the value is a number,
5037 then <code>lua_tolstring</code> also
5038 <em>changes the actual value in the stack to a string</em>.
5039 (This change confuses <a href="#lua_next"><code>lua_next</code></a>
5040 when <code>lua_tolstring</code> is applied to keys during a table traversal.)
5041
5042
5043 <p>
5044 <code>lua_tolstring</code> returns a pointer
5045 to a string inside the Lua state.
5046 This string always has a zero ('<code>\0</code>')
5047 after its last character (as in&nbsp;C),
5048 but can contain other zeros in its body.
5049
5050
5051 <p>
5052 Because Lua has garbage collection,
5053 there is no guarantee that the pointer returned by <code>lua_tolstring</code>
5054 will be valid after the corresponding Lua value is removed from the stack.
5055
5056
5057
5058
5059
5060 <hr><h3><a name="lua_tonumber"><code>lua_tonumber</code></a></h3><p>
5061 <span class="apii">[-0, +0, &ndash;]</span>
5062 <pre>lua_Number lua_tonumber (lua_State *L, int index);</pre>
5063
5064 <p>
5065 Equivalent to <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> with <code>isnum</code> equal to <code>NULL</code>.
5066
5067
5068
5069
5070
5071 <hr><h3><a name="lua_tonumberx"><code>lua_tonumberx</code></a></h3><p>
5072 <span class="apii">[-0, +0, &ndash;]</span>
5073 <pre>lua_Number lua_tonumberx (lua_State *L, int index, int *isnum);</pre>
5074
5075 <p>
5076 Converts the Lua value at the given index
5077 to the C&nbsp;type <a href="#lua_Number"><code>lua_Number</code></a> (see <a href="#lua_Number"><code>lua_Number</code></a>).
5078 The Lua value must be a number or a string convertible to a number
5079 (see <a href="#3.4.3">&sect;3.4.3</a>);
5080 otherwise, <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> returns&nbsp;0.
5081
5082
5083 <p>
5084 If <code>isnum</code> is not <code>NULL</code>,
5085 its referent is assigned a boolean value that
5086 indicates whether the operation succeeded.
5087
5088
5089
5090
5091
5092 <hr><h3><a name="lua_topointer"><code>lua_topointer</code></a></h3><p>
5093 <span class="apii">[-0, +0, &ndash;]</span>
5094 <pre>const void *lua_topointer (lua_State *L, int index);</pre>
5095
5096 <p>
5097 Converts the value at the given index to a generic
5098 C&nbsp;pointer (<code>void*</code>).
5099 The value can be a userdata, a table, a thread, or a function;
5100 otherwise, <code>lua_topointer</code> returns <code>NULL</code>.
5101 Different objects will give different pointers.
5102 There is no way to convert the pointer back to its original value.
5103
5104
5105 <p>
5106 Typically this function is used only for hashing and debug information.
5107
5108
5109
5110
5111
5112 <hr><h3><a name="lua_tostring"><code>lua_tostring</code></a></h3><p>
5113 <span class="apii">[-0, +0, <em>m</em>]</span>
5114 <pre>const char *lua_tostring (lua_State *L, int index);</pre>
5115
5116 <p>
5117 Equivalent to <a href="#lua_tolstring"><code>lua_tolstring</code></a> with <code>len</code> equal to <code>NULL</code>.
5118
5119
5120
5121
5122
5123 <hr><h3><a name="lua_tothread"><code>lua_tothread</code></a></h3><p>
5124 <span class="apii">[-0, +0, &ndash;]</span>
5125 <pre>lua_State *lua_tothread (lua_State *L, int index);</pre>
5126
5127 <p>
5128 Converts the value at the given index to a Lua thread
5129 (represented as <code>lua_State*</code>).
5130 This value must be a thread;
5131 otherwise, the function returns <code>NULL</code>.
5132
5133
5134
5135
5136
5137 <hr><h3><a name="lua_touserdata"><code>lua_touserdata</code></a></h3><p>
5138 <span class="apii">[-0, +0, &ndash;]</span>
5139 <pre>void *lua_touserdata (lua_State *L, int index);</pre>
5140
5141 <p>
5142 If the value at the given index is a full userdata,
5143 returns its block address.
5144 If the value is a light userdata,
5145 returns its pointer.
5146 Otherwise, returns <code>NULL</code>.
5147
5148
5149
5150
5151
5152 <hr><h3><a name="lua_type"><code>lua_type</code></a></h3><p>
5153 <span class="apii">[-0, +0, &ndash;]</span>
5154 <pre>int lua_type (lua_State *L, int index);</pre>
5155
5156 <p>
5157 Returns the type of the value in the given valid index,
5158 or <code>LUA_TNONE</code> for a non-valid (but acceptable) index.
5159 The types returned by <a href="#lua_type"><code>lua_type</code></a> are coded by the following constants
5160 defined in <code>lua.h</code>:
5161 <a name="pdf-LUA_TNIL"><code>LUA_TNIL</code></a> (0),
5162 <a name="pdf-LUA_TNUMBER"><code>LUA_TNUMBER</code></a>,
5163 <a name="pdf-LUA_TBOOLEAN"><code>LUA_TBOOLEAN</code></a>,
5164 <a name="pdf-LUA_TSTRING"><code>LUA_TSTRING</code></a>,
5165 <a name="pdf-LUA_TTABLE"><code>LUA_TTABLE</code></a>,
5166 <a name="pdf-LUA_TFUNCTION"><code>LUA_TFUNCTION</code></a>,
5167 <a name="pdf-LUA_TUSERDATA"><code>LUA_TUSERDATA</code></a>,
5168 <a name="pdf-LUA_TTHREAD"><code>LUA_TTHREAD</code></a>,
5169 and
5170 <a name="pdf-LUA_TLIGHTUSERDATA"><code>LUA_TLIGHTUSERDATA</code></a>.
5171
5172
5173
5174
5175
5176 <hr><h3><a name="lua_typename"><code>lua_typename</code></a></h3><p>
5177 <span class="apii">[-0, +0, &ndash;]</span>
5178 <pre>const char *lua_typename (lua_State *L, int tp);</pre>
5179
5180 <p>
5181 Returns the name of the type encoded by the value <code>tp</code>,
5182 which must be one the values returned by <a href="#lua_type"><code>lua_type</code></a>.
5183
5184
5185
5186
5187
5188 <hr><h3><a name="lua_Unsigned"><code>lua_Unsigned</code></a></h3>
5189 <pre>typedef ... lua_Unsigned;</pre>
5190
5191 <p>
5192 The unsigned version of <a href="#lua_Integer"><code>lua_Integer</code></a>.
5193
5194
5195
5196
5197
5198 <hr><h3><a name="lua_upvalueindex"><code>lua_upvalueindex</code></a></h3><p>
5199 <span class="apii">[-0, +0, &ndash;]</span>
5200 <pre>int lua_upvalueindex (int i);</pre>
5201
5202 <p>
5203 Returns the pseudo-index that represents the <code>i</code>-th upvalue of
5204 the running function (see <a href="#4.4">&sect;4.4</a>).
5205
5206
5207
5208
5209
5210 <hr><h3><a name="lua_version"><code>lua_version</code></a></h3><p>
5211 <span class="apii">[-0, +0, &ndash;]</span>
5212 <pre>const lua_Number *lua_version (lua_State *L);</pre>
5213
5214 <p>
5215 Returns the address of the version number
5216 (a C static variable)
5217 stored in the Lua core.
5218 When called with a valid <a href="#lua_State"><code>lua_State</code></a>,
5219 returns the address of the version used to create that state.
5220 When called with <code>NULL</code>,
5221 returns the address of the version running the call.
5222
5223
5224
5225
5226
5227 <hr><h3><a name="lua_Writer"><code>lua_Writer</code></a></h3>
5228 <pre>typedef int (*lua_Writer) (lua_State *L,
5229                            const void* p,
5230                            size_t sz,
5231                            void* ud);</pre>
5232
5233 <p>
5234 The type of the writer function used by <a href="#lua_dump"><code>lua_dump</code></a>.
5235 Every time it produces another piece of chunk,
5236 <a href="#lua_dump"><code>lua_dump</code></a> calls the writer,
5237 passing along the buffer to be written (<code>p</code>),
5238 its size (<code>sz</code>),
5239 and the <code>data</code> parameter supplied to <a href="#lua_dump"><code>lua_dump</code></a>.
5240
5241
5242 <p>
5243 The writer returns an error code:
5244 0&nbsp;means no errors;
5245 any other value means an error and stops <a href="#lua_dump"><code>lua_dump</code></a> from
5246 calling the writer again.
5247
5248
5249
5250
5251
5252 <hr><h3><a name="lua_xmove"><code>lua_xmove</code></a></h3><p>
5253 <span class="apii">[-?, +?, &ndash;]</span>
5254 <pre>void lua_xmove (lua_State *from, lua_State *to, int n);</pre>
5255
5256 <p>
5257 Exchange values between different threads of the same state.
5258
5259
5260 <p>
5261 This function pops <code>n</code> values from the stack <code>from</code>,
5262 and pushes them onto the stack <code>to</code>.
5263
5264
5265
5266
5267
5268 <hr><h3><a name="lua_yield"><code>lua_yield</code></a></h3><p>
5269 <span class="apii">[-?, +?, <em>e</em>]</span>
5270 <pre>int lua_yield (lua_State *L, int nresults);</pre>
5271
5272 <p>
5273 This function is equivalent to <a href="#lua_yieldk"><code>lua_yieldk</code></a>,
5274 but it has no continuation (see <a href="#4.7">&sect;4.7</a>).
5275 Therefore, when the thread resumes,
5276 it continues the function that called
5277 the function calling <code>lua_yield</code>.
5278
5279
5280
5281
5282
5283 <hr><h3><a name="lua_yieldk"><code>lua_yieldk</code></a></h3><p>
5284 <span class="apii">[-?, +?, <em>e</em>]</span>
5285 <pre>int lua_yieldk (lua_State *L,
5286                 int nresults,
5287                 lua_KContext ctx,
5288                 lua_KFunction k);</pre>
5289
5290 <p>
5291 Yields a coroutine (thread).
5292
5293
5294 <p>
5295 When a C&nbsp;function calls <a href="#lua_yieldk"><code>lua_yieldk</code></a>,
5296 the running coroutine suspends its execution,
5297 and the call to <a href="#lua_resume"><code>lua_resume</code></a> that started this coroutine returns.
5298 The parameter <code>nresults</code> is the number of values from the stack
5299 that will be passed as results to <a href="#lua_resume"><code>lua_resume</code></a>.
5300
5301
5302 <p>
5303 When the coroutine is resumed again,
5304 Lua calls the given continuation function <code>k</code> to continue
5305 the execution of the C function that yielded (see <a href="#4.7">&sect;4.7</a>).
5306 This continuation function receives the same stack
5307 from the previous function,
5308 with the <code>n</code> results removed and
5309 replaced by the arguments passed to <a href="#lua_resume"><code>lua_resume</code></a>.
5310 Moreover,
5311 the continuation function receives the value <code>ctx</code>
5312 that was passed to <a href="#lua_yieldk"><code>lua_yieldk</code></a>.
5313
5314
5315 <p>
5316 Usually, this function does not return;
5317 when the coroutine eventually resumes,
5318 it continues executing the continuation function.
5319 However, there is one special case,
5320 which is when this function is called
5321 from inside a line or a count hook (see <a href="#4.9">&sect;4.9</a>).
5322 In that case, <code>lua_yieldk</code> should be called with no continuation
5323 (probably in the form of <a href="#lua_yield"><code>lua_yield</code></a>) and no results,
5324 and the hook should return immediately after the call.
5325 Lua will yield and,
5326 when the coroutine resumes again,
5327 it will continue the normal execution
5328 of the (Lua) function that triggered the hook.
5329
5330
5331 <p>
5332 This function can raise an error if it is called from a thread
5333 with a pending C call with no continuation function,
5334 or it is called from a thread that is not running inside a resume
5335 (e.g., the main thread).
5336
5337
5338
5339
5340
5341
5342
5343 <h2>4.9 &ndash; <a name="4.9">The Debug Interface</a></h2>
5344
5345 <p>
5346 Lua has no built-in debugging facilities.
5347 Instead, it offers a special interface
5348 by means of functions and <em>hooks</em>.
5349 This interface allows the construction of different
5350 kinds of debuggers, profilers, and other tools
5351 that need "inside information" from the interpreter.
5352
5353
5354
5355 <hr><h3><a name="lua_Debug"><code>lua_Debug</code></a></h3>
5356 <pre>typedef struct lua_Debug {
5357   int event;
5358   const char *name;           /* (n) */
5359   const char *namewhat;       /* (n) */
5360   const char *what;           /* (S) */
5361   const char *source;         /* (S) */
5362   int currentline;            /* (l) */
5363   int linedefined;            /* (S) */
5364   int lastlinedefined;        /* (S) */
5365   unsigned char nups;         /* (u) number of upvalues */
5366   unsigned char nparams;      /* (u) number of parameters */
5367   char isvararg;              /* (u) */
5368   char istailcall;            /* (t) */
5369   char short_src[LUA_IDSIZE]; /* (S) */
5370   /* private part */
5371   <em>other fields</em>
5372 } lua_Debug;</pre>
5373
5374 <p>
5375 A structure used to carry different pieces of
5376 information about a function or an activation record.
5377 <a href="#lua_getstack"><code>lua_getstack</code></a> fills only the private part
5378 of this structure, for later use.
5379 To fill the other fields of <a href="#lua_Debug"><code>lua_Debug</code></a> with useful information,
5380 call <a href="#lua_getinfo"><code>lua_getinfo</code></a>.
5381
5382
5383 <p>
5384 The fields of <a href="#lua_Debug"><code>lua_Debug</code></a> have the following meaning:
5385
5386 <ul>
5387
5388 <li><b><code>source</code>: </b>
5389 the name of the chunk that created the function.
5390 If <code>source</code> starts with a '<code>@</code>',
5391 it means that the function was defined in a file where
5392 the file name follows the '<code>@</code>'.
5393 If <code>source</code> starts with a '<code>=</code>',
5394 the remainder of its contents describe the source in a user-dependent manner.
5395 Otherwise,
5396 the function was defined in a string where
5397 <code>source</code> is that string.
5398 </li>
5399
5400 <li><b><code>short_src</code>: </b>
5401 a "printable" version of <code>source</code>, to be used in error messages.
5402 </li>
5403
5404 <li><b><code>linedefined</code>: </b>
5405 the line number where the definition of the function starts.
5406 </li>
5407
5408 <li><b><code>lastlinedefined</code>: </b>
5409 the line number where the definition of the function ends.
5410 </li>
5411
5412 <li><b><code>what</code>: </b>
5413 the string <code>"Lua"</code> if the function is a Lua function,
5414 <code>"C"</code> if it is a C&nbsp;function,
5415 <code>"main"</code> if it is the main part of a chunk.
5416 </li>
5417
5418 <li><b><code>currentline</code>: </b>
5419 the current line where the given function is executing.
5420 When no line information is available,
5421 <code>currentline</code> is set to -1.
5422 </li>
5423
5424 <li><b><code>name</code>: </b>
5425 a reasonable name for the given function.
5426 Because functions in Lua are first-class values,
5427 they do not have a fixed name:
5428 some functions can be the value of multiple global variables,
5429 while others can be stored only in a table field.
5430 The <code>lua_getinfo</code> function checks how the function was
5431 called to find a suitable name.
5432 If it cannot find a name,
5433 then <code>name</code> is set to <code>NULL</code>.
5434 </li>
5435
5436 <li><b><code>namewhat</code>: </b>
5437 explains the <code>name</code> field.
5438 The value of <code>namewhat</code> can be
5439 <code>"global"</code>, <code>"local"</code>, <code>"method"</code>,
5440 <code>"field"</code>, <code>"upvalue"</code>, or <code>""</code> (the empty string),
5441 according to how the function was called.
5442 (Lua uses the empty string when no other option seems to apply.)
5443 </li>
5444
5445 <li><b><code>istailcall</code>: </b>
5446 true if this function invocation was called by a tail call.
5447 In this case, the caller of this level is not in the stack.
5448 </li>
5449
5450 <li><b><code>nups</code>: </b>
5451 the number of upvalues of the function.
5452 </li>
5453
5454 <li><b><code>nparams</code>: </b>
5455 the number of fixed parameters of the function
5456 (always 0&nbsp;for C&nbsp;functions).
5457 </li>
5458
5459 <li><b><code>isvararg</code>: </b>
5460 true if the function is a vararg function
5461 (always true for C&nbsp;functions).
5462 </li>
5463
5464 </ul>
5465
5466
5467
5468
5469 <hr><h3><a name="lua_gethook"><code>lua_gethook</code></a></h3><p>
5470 <span class="apii">[-0, +0, &ndash;]</span>
5471 <pre>lua_Hook lua_gethook (lua_State *L);</pre>
5472
5473 <p>
5474 Returns the current hook function.
5475
5476
5477
5478
5479
5480 <hr><h3><a name="lua_gethookcount"><code>lua_gethookcount</code></a></h3><p>
5481 <span class="apii">[-0, +0, &ndash;]</span>
5482 <pre>int lua_gethookcount (lua_State *L);</pre>
5483
5484 <p>
5485 Returns the current hook count.
5486
5487
5488
5489
5490
5491 <hr><h3><a name="lua_gethookmask"><code>lua_gethookmask</code></a></h3><p>
5492 <span class="apii">[-0, +0, &ndash;]</span>
5493 <pre>int lua_gethookmask (lua_State *L);</pre>
5494
5495 <p>
5496 Returns the current hook mask.
5497
5498
5499
5500
5501
5502 <hr><h3><a name="lua_getinfo"><code>lua_getinfo</code></a></h3><p>
5503 <span class="apii">[-(0|1), +(0|1|2), <em>e</em>]</span>
5504 <pre>int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar);</pre>
5505
5506 <p>
5507 Gets information about a specific function or function invocation.
5508
5509
5510 <p>
5511 To get information about a function invocation,
5512 the parameter <code>ar</code> must be a valid activation record that was
5513 filled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or
5514 given as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>).
5515
5516
5517 <p>
5518 To get information about a function you push it onto the stack
5519 and start the <code>what</code> string with the character '<code>&gt;</code>'.
5520 (In that case,
5521 <code>lua_getinfo</code> pops the function from the top of the stack.)
5522 For instance, to know in which line a function <code>f</code> was defined,
5523 you can write the following code:
5524
5525 <pre>
5526      lua_Debug ar;
5527      lua_getglobal(L, "f");  /* get global 'f' */
5528      lua_getinfo(L, "&gt;S", &amp;ar);
5529      printf("%d\n", ar.linedefined);
5530 </pre>
5531
5532 <p>
5533 Each character in the string <code>what</code>
5534 selects some fields of the structure <code>ar</code> to be filled or
5535 a value to be pushed on the stack:
5536
5537 <ul>
5538
5539 <li><b>'<code>n</code>': </b> fills in the field <code>name</code> and <code>namewhat</code>;
5540 </li>
5541
5542 <li><b>'<code>S</code>': </b>
5543 fills in the fields <code>source</code>, <code>short_src</code>,
5544 <code>linedefined</code>, <code>lastlinedefined</code>, and <code>what</code>;
5545 </li>
5546
5547 <li><b>'<code>l</code>': </b> fills in the field <code>currentline</code>;
5548 </li>
5549
5550 <li><b>'<code>t</code>': </b> fills in the field <code>istailcall</code>;
5551 </li>
5552
5553 <li><b>'<code>u</code>': </b> fills in the fields
5554 <code>nups</code>, <code>nparams</code>, and <code>isvararg</code>;
5555 </li>
5556
5557 <li><b>'<code>f</code>': </b>
5558 pushes onto the stack the function that is
5559 running at the given level;
5560 </li>
5561
5562 <li><b>'<code>L</code>': </b>
5563 pushes onto the stack a table whose indices are the
5564 numbers of the lines that are valid on the function.
5565 (A <em>valid line</em> is a line with some associated code,
5566 that is, a line where you can put a break point.
5567 Non-valid lines include empty lines and comments.)
5568
5569
5570 <p>
5571 If this option is given together with option '<code>f</code>',
5572 its table is pushed after the function.
5573 </li>
5574
5575 </ul>
5576
5577 <p>
5578 This function returns 0 on error
5579 (for instance, an invalid option in <code>what</code>).
5580
5581
5582
5583
5584
5585 <hr><h3><a name="lua_getlocal"><code>lua_getlocal</code></a></h3><p>
5586 <span class="apii">[-0, +(0|1), &ndash;]</span>
5587 <pre>const char *lua_getlocal (lua_State *L, const lua_Debug *ar, int n);</pre>
5588
5589 <p>
5590 Gets information about a local variable of
5591 a given activation record or a given function.
5592
5593
5594 <p>
5595 In the first case,
5596 the parameter <code>ar</code> must be a valid activation record that was
5597 filled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or
5598 given as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>).
5599 The index <code>n</code> selects which local variable to inspect;
5600 see <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for details about variable indices
5601 and names.
5602
5603
5604 <p>
5605 <a href="#lua_getlocal"><code>lua_getlocal</code></a> pushes the variable's value onto the stack
5606 and returns its name.
5607
5608
5609 <p>
5610 In the second case, <code>ar</code> must be <code>NULL</code> and the function
5611 to be inspected must be at the top of the stack.
5612 In this case, only parameters of Lua functions are visible
5613 (as there is no information about what variables are active)
5614 and no values are pushed onto the stack.
5615
5616
5617 <p>
5618 Returns <code>NULL</code> (and pushes nothing)
5619 when the index is greater than
5620 the number of active local variables.
5621
5622
5623
5624
5625
5626 <hr><h3><a name="lua_getstack"><code>lua_getstack</code></a></h3><p>
5627 <span class="apii">[-0, +0, &ndash;]</span>
5628 <pre>int lua_getstack (lua_State *L, int level, lua_Debug *ar);</pre>
5629
5630 <p>
5631 Gets information about the interpreter runtime stack.
5632
5633
5634 <p>
5635 This function fills parts of a <a href="#lua_Debug"><code>lua_Debug</code></a> structure with
5636 an identification of the <em>activation record</em>
5637 of the function executing at a given level.
5638 Level&nbsp;0 is the current running function,
5639 whereas level <em>n+1</em> is the function that has called level <em>n</em>
5640 (except for tail calls, which do not count on the stack).
5641 When there are no errors, <a href="#lua_getstack"><code>lua_getstack</code></a> returns 1;
5642 when called with a level greater than the stack depth,
5643 it returns 0.
5644
5645
5646
5647
5648
5649 <hr><h3><a name="lua_getupvalue"><code>lua_getupvalue</code></a></h3><p>
5650 <span class="apii">[-0, +(0|1), &ndash;]</span>
5651 <pre>const char *lua_getupvalue (lua_State *L, int funcindex, int n);</pre>
5652
5653 <p>
5654 Gets information about the <code>n</code>-th upvalue
5655 of the closure at index <code>funcindex</code>.
5656 It pushes the upvalue's value onto the stack
5657 and returns its name.
5658 Returns <code>NULL</code> (and pushes nothing)
5659 when the index <code>n</code> is greater than the number of upvalues.
5660
5661
5662 <p>
5663 For C&nbsp;functions, this function uses the empty string <code>""</code>
5664 as a name for all upvalues.
5665 (For Lua functions,
5666 upvalues are the external local variables that the function uses,
5667 and that are consequently included in its closure.)
5668
5669
5670 <p>
5671 Upvalues have no particular order,
5672 as they are active through the whole function.
5673 They are numbered in an arbitrary order.
5674
5675
5676
5677
5678
5679 <hr><h3><a name="lua_Hook"><code>lua_Hook</code></a></h3>
5680 <pre>typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar);</pre>
5681
5682 <p>
5683 Type for debugging hook functions.
5684
5685
5686 <p>
5687 Whenever a hook is called, its <code>ar</code> argument has its field
5688 <code>event</code> set to the specific event that triggered the hook.
5689 Lua identifies these events with the following constants:
5690 <a name="pdf-LUA_HOOKCALL"><code>LUA_HOOKCALL</code></a>, <a name="pdf-LUA_HOOKRET"><code>LUA_HOOKRET</code></a>,
5691 <a name="pdf-LUA_HOOKTAILCALL"><code>LUA_HOOKTAILCALL</code></a>, <a name="pdf-LUA_HOOKLINE"><code>LUA_HOOKLINE</code></a>,
5692 and <a name="pdf-LUA_HOOKCOUNT"><code>LUA_HOOKCOUNT</code></a>.
5693 Moreover, for line events, the field <code>currentline</code> is also set.
5694 To get the value of any other field in <code>ar</code>,
5695 the hook must call <a href="#lua_getinfo"><code>lua_getinfo</code></a>.
5696
5697
5698 <p>
5699 For call events, <code>event</code> can be <code>LUA_HOOKCALL</code>,
5700 the normal value, or <code>LUA_HOOKTAILCALL</code>, for a tail call;
5701 in this case, there will be no corresponding return event.
5702
5703
5704 <p>
5705 While Lua is running a hook, it disables other calls to hooks.
5706 Therefore, if a hook calls back Lua to execute a function or a chunk,
5707 this execution occurs without any calls to hooks.
5708
5709
5710 <p>
5711 Hook functions cannot have continuations,
5712 that is, they cannot call <a href="#lua_yieldk"><code>lua_yieldk</code></a>,
5713 <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>.
5714
5715
5716 <p>
5717 Hook functions can yield under the following conditions:
5718 Only count and line events can yield;
5719 to yield, a hook function must finish its execution
5720 calling <a href="#lua_yield"><code>lua_yield</code></a> with <code>nresults</code> equal to zero
5721 (that is, with no values).
5722
5723
5724
5725
5726
5727 <hr><h3><a name="lua_sethook"><code>lua_sethook</code></a></h3><p>
5728 <span class="apii">[-0, +0, &ndash;]</span>
5729 <pre>void lua_sethook (lua_State *L, lua_Hook f, int mask, int count);</pre>
5730
5731 <p>
5732 Sets the debugging hook function.
5733
5734
5735 <p>
5736 Argument <code>f</code> is the hook function.
5737 <code>mask</code> specifies on which events the hook will be called:
5738 it is formed by a bitwise OR of the constants
5739 <a name="pdf-LUA_MASKCALL"><code>LUA_MASKCALL</code></a>,
5740 <a name="pdf-LUA_MASKRET"><code>LUA_MASKRET</code></a>,
5741 <a name="pdf-LUA_MASKLINE"><code>LUA_MASKLINE</code></a>,
5742 and <a name="pdf-LUA_MASKCOUNT"><code>LUA_MASKCOUNT</code></a>.
5743 The <code>count</code> argument is only meaningful when the mask
5744 includes <code>LUA_MASKCOUNT</code>.
5745 For each event, the hook is called as explained below:
5746
5747 <ul>
5748
5749 <li><b>The call hook: </b> is called when the interpreter calls a function.
5750 The hook is called just after Lua enters the new function,
5751 before the function gets its arguments.
5752 </li>
5753
5754 <li><b>The return hook: </b> is called when the interpreter returns from a function.
5755 The hook is called just before Lua leaves the function.
5756 There is no standard way to access the values
5757 to be returned by the function.
5758 </li>
5759
5760 <li><b>The line hook: </b> is called when the interpreter is about to
5761 start the execution of a new line of code,
5762 or when it jumps back in the code (even to the same line).
5763 (This event only happens while Lua is executing a Lua function.)
5764 </li>
5765
5766 <li><b>The count hook: </b> is called after the interpreter executes every
5767 <code>count</code> instructions.
5768 (This event only happens while Lua is executing a Lua function.)
5769 </li>
5770
5771 </ul>
5772
5773 <p>
5774 A hook is disabled by setting <code>mask</code> to zero.
5775
5776
5777
5778
5779
5780 <hr><h3><a name="lua_setlocal"><code>lua_setlocal</code></a></h3><p>
5781 <span class="apii">[-(0|1), +0, &ndash;]</span>
5782 <pre>const char *lua_setlocal (lua_State *L, const lua_Debug *ar, int n);</pre>
5783
5784 <p>
5785 Sets the value of a local variable of a given activation record.
5786 It assigns the value at the top of the stack
5787 to the variable and returns its name.
5788 It also pops the value from the stack.
5789
5790
5791 <p>
5792 Returns <code>NULL</code> (and pops nothing)
5793 when the index is greater than
5794 the number of active local variables.
5795
5796
5797 <p>
5798 Parameters <code>ar</code> and <code>n</code> are as in function <a href="#lua_getlocal"><code>lua_getlocal</code></a>.
5799
5800
5801
5802
5803
5804 <hr><h3><a name="lua_setupvalue"><code>lua_setupvalue</code></a></h3><p>
5805 <span class="apii">[-(0|1), +0, &ndash;]</span>
5806 <pre>const char *lua_setupvalue (lua_State *L, int funcindex, int n);</pre>
5807
5808 <p>
5809 Sets the value of a closure's upvalue.
5810 It assigns the value at the top of the stack
5811 to the upvalue and returns its name.
5812 It also pops the value from the stack.
5813
5814
5815 <p>
5816 Returns <code>NULL</code> (and pops nothing)
5817 when the index <code>n</code> is greater than the number of upvalues.
5818
5819
5820 <p>
5821 Parameters <code>funcindex</code> and <code>n</code> are as in function <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>.
5822
5823
5824
5825
5826
5827 <hr><h3><a name="lua_upvalueid"><code>lua_upvalueid</code></a></h3><p>
5828 <span class="apii">[-0, +0, &ndash;]</span>
5829 <pre>void *lua_upvalueid (lua_State *L, int funcindex, int n);</pre>
5830
5831 <p>
5832 Returns a unique identifier for the upvalue numbered <code>n</code>
5833 from the closure at index <code>funcindex</code>.
5834
5835
5836 <p>
5837 These unique identifiers allow a program to check whether different
5838 closures share upvalues.
5839 Lua closures that share an upvalue
5840 (that is, that access a same external local variable)
5841 will return identical ids for those upvalue indices.
5842
5843
5844 <p>
5845 Parameters <code>funcindex</code> and <code>n</code> are as in function <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>,
5846 but <code>n</code> cannot be greater than the number of upvalues.
5847
5848
5849
5850
5851
5852 <hr><h3><a name="lua_upvaluejoin"><code>lua_upvaluejoin</code></a></h3><p>
5853 <span class="apii">[-0, +0, &ndash;]</span>
5854 <pre>void lua_upvaluejoin (lua_State *L, int funcindex1, int n1,
5855                                     int funcindex2, int n2);</pre>
5856
5857 <p>
5858 Make the <code>n1</code>-th upvalue of the Lua closure at index <code>funcindex1</code>
5859 refer to the <code>n2</code>-th upvalue of the Lua closure at index <code>funcindex2</code>.
5860
5861
5862
5863
5864
5865
5866
5867 <h1>5 &ndash; <a name="5">The Auxiliary Library</a></h1>
5868
5869 <p>
5870
5871 The <em>auxiliary library</em> provides several convenient functions
5872 to interface C with Lua.
5873 While the basic API provides the primitive functions for all
5874 interactions between C and Lua,
5875 the auxiliary library provides higher-level functions for some
5876 common tasks.
5877
5878
5879 <p>
5880 All functions and types from the auxiliary library
5881 are defined in header file <code>lauxlib.h</code> and
5882 have a prefix <code>luaL_</code>.
5883
5884
5885 <p>
5886 All functions in the auxiliary library are built on
5887 top of the basic API,
5888 and so they provide nothing that cannot be done with that API.
5889 Nevertheless, the use of the auxiliary library ensures
5890 more consistency to your code.
5891
5892
5893 <p>
5894 Several functions in the auxiliary library use internally some
5895 extra stack slots.
5896 When a function in the auxiliary library uses less than five slots,
5897 it does not check the stack size;
5898 it simply assumes that there are enough slots.
5899
5900
5901 <p>
5902 Several functions in the auxiliary library are used to
5903 check C&nbsp;function arguments.
5904 Because the error message is formatted for arguments
5905 (e.g., "<code>bad argument #1</code>"),
5906 you should not use these functions for other stack values.
5907
5908
5909 <p>
5910 Functions called <code>luaL_check*</code>
5911 always raise an error if the check is not satisfied.
5912
5913
5914
5915 <h2>5.1 &ndash; <a name="5.1">Functions and Types</a></h2>
5916
5917 <p>
5918 Here we list all functions and types from the auxiliary library
5919 in alphabetical order.
5920
5921
5922
5923 <hr><h3><a name="luaL_addchar"><code>luaL_addchar</code></a></h3><p>
5924 <span class="apii">[-?, +?, <em>m</em>]</span>
5925 <pre>void luaL_addchar (luaL_Buffer *B, char c);</pre>
5926
5927 <p>
5928 Adds the byte <code>c</code> to the buffer <code>B</code>
5929 (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
5930
5931
5932
5933
5934
5935 <hr><h3><a name="luaL_addlstring"><code>luaL_addlstring</code></a></h3><p>
5936 <span class="apii">[-?, +?, <em>m</em>]</span>
5937 <pre>void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l);</pre>
5938
5939 <p>
5940 Adds the string pointed to by <code>s</code> with length <code>l</code> to
5941 the buffer <code>B</code>
5942 (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
5943 The string can contain embedded zeros.
5944
5945
5946
5947
5948
5949 <hr><h3><a name="luaL_addsize"><code>luaL_addsize</code></a></h3><p>
5950 <span class="apii">[-?, +?, &ndash;]</span>
5951 <pre>void luaL_addsize (luaL_Buffer *B, size_t n);</pre>
5952
5953 <p>
5954 Adds to the buffer <code>B</code> (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>)
5955 a string of length <code>n</code> previously copied to the
5956 buffer area (see <a href="#luaL_prepbuffer"><code>luaL_prepbuffer</code></a>).
5957
5958
5959
5960
5961
5962 <hr><h3><a name="luaL_addstring"><code>luaL_addstring</code></a></h3><p>
5963 <span class="apii">[-?, +?, <em>m</em>]</span>
5964 <pre>void luaL_addstring (luaL_Buffer *B, const char *s);</pre>
5965
5966 <p>
5967 Adds the zero-terminated string pointed to by <code>s</code>
5968 to the buffer <code>B</code>
5969 (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
5970
5971
5972
5973
5974
5975 <hr><h3><a name="luaL_addvalue"><code>luaL_addvalue</code></a></h3><p>
5976 <span class="apii">[-1, +?, <em>m</em>]</span>
5977 <pre>void luaL_addvalue (luaL_Buffer *B);</pre>
5978
5979 <p>
5980 Adds the value at the top of the stack
5981 to the buffer <code>B</code>
5982 (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
5983 Pops the value.
5984
5985
5986 <p>
5987 This is the only function on string buffers that can (and must)
5988 be called with an extra element on the stack,
5989 which is the value to be added to the buffer.
5990
5991
5992
5993
5994
5995 <hr><h3><a name="luaL_argcheck"><code>luaL_argcheck</code></a></h3><p>
5996 <span class="apii">[-0, +0, <em>v</em>]</span>
5997 <pre>void luaL_argcheck (lua_State *L,
5998                     int cond,
5999                     int arg,
6000                     const char *extramsg);</pre>
6001
6002 <p>
6003 Checks whether <code>cond</code> is true.
6004 If it is not, raises an error with a standard message (see <a href="#luaL_argerror"><code>luaL_argerror</code></a>).
6005
6006
6007
6008
6009
6010 <hr><h3><a name="luaL_argerror"><code>luaL_argerror</code></a></h3><p>
6011 <span class="apii">[-0, +0, <em>v</em>]</span>
6012 <pre>int luaL_argerror (lua_State *L, int arg, const char *extramsg);</pre>
6013
6014 <p>
6015 Raises an error reporting a problem with argument <code>arg</code>
6016 of the C function that called it,
6017 using a standard message
6018 that includes <code>extramsg</code> as a comment:
6019
6020 <pre>
6021      bad argument #<em>arg</em> to '<em>funcname</em>' (<em>extramsg</em>)
6022 </pre><p>
6023 This function never returns.
6024
6025
6026
6027
6028
6029 <hr><h3><a name="luaL_Buffer"><code>luaL_Buffer</code></a></h3>
6030 <pre>typedef struct luaL_Buffer luaL_Buffer;</pre>
6031
6032 <p>
6033 Type for a <em>string buffer</em>.
6034
6035
6036 <p>
6037 A string buffer allows C&nbsp;code to build Lua strings piecemeal.
6038 Its pattern of use is as follows:
6039
6040 <ul>
6041
6042 <li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li>
6043
6044 <li>Then initialize it with a call <code>luaL_buffinit(L, &amp;b)</code>.</li>
6045
6046 <li>
6047 Then add string pieces to the buffer calling any of
6048 the <code>luaL_add*</code> functions.
6049 </li>
6050
6051 <li>
6052 Finish by calling <code>luaL_pushresult(&amp;b)</code>.
6053 This call leaves the final string on the top of the stack.
6054 </li>
6055
6056 </ul>
6057
6058 <p>
6059 If you know beforehand the total size of the resulting string,
6060 you can use the buffer like this:
6061
6062 <ul>
6063
6064 <li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li>
6065
6066 <li>Then initialize it and preallocate a space of
6067 size <code>sz</code> with a call <code>luaL_buffinitsize(L, &amp;b, sz)</code>.</li>
6068
6069 <li>Then copy the string into that space.</li>
6070
6071 <li>
6072 Finish by calling <code>luaL_pushresultsize(&amp;b, sz)</code>,
6073 where <code>sz</code> is the total size of the resulting string
6074 copied into that space.
6075 </li>
6076
6077 </ul>
6078
6079 <p>
6080 During its normal operation,
6081 a string buffer uses a variable number of stack slots.
6082 So, while using a buffer, you cannot assume that you know where
6083 the top of the stack is.
6084 You can use the stack between successive calls to buffer operations
6085 as long as that use is balanced;
6086 that is,
6087 when you call a buffer operation,
6088 the stack is at the same level
6089 it was immediately after the previous buffer operation.
6090 (The only exception to this rule is <a href="#luaL_addvalue"><code>luaL_addvalue</code></a>.)
6091 After calling <a href="#luaL_pushresult"><code>luaL_pushresult</code></a> the stack is back to its
6092 level when the buffer was initialized,
6093 plus the final string on its top.
6094
6095
6096
6097
6098
6099 <hr><h3><a name="luaL_buffinit"><code>luaL_buffinit</code></a></h3><p>
6100 <span class="apii">[-0, +0, &ndash;]</span>
6101 <pre>void luaL_buffinit (lua_State *L, luaL_Buffer *B);</pre>
6102
6103 <p>
6104 Initializes a buffer <code>B</code>.
6105 This function does not allocate any space;
6106 the buffer must be declared as a variable
6107 (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
6108
6109
6110
6111
6112
6113 <hr><h3><a name="luaL_buffinitsize"><code>luaL_buffinitsize</code></a></h3><p>
6114 <span class="apii">[-?, +?, <em>m</em>]</span>
6115 <pre>char *luaL_buffinitsize (lua_State *L, luaL_Buffer *B, size_t sz);</pre>
6116
6117 <p>
6118 Equivalent to the sequence
6119 <a href="#luaL_buffinit"><code>luaL_buffinit</code></a>, <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a>.
6120
6121
6122
6123
6124
6125 <hr><h3><a name="luaL_callmeta"><code>luaL_callmeta</code></a></h3><p>
6126 <span class="apii">[-0, +(0|1), <em>e</em>]</span>
6127 <pre>int luaL_callmeta (lua_State *L, int obj, const char *e);</pre>
6128
6129 <p>
6130 Calls a metamethod.
6131
6132
6133 <p>
6134 If the object at index <code>obj</code> has a metatable and this
6135 metatable has a field <code>e</code>,
6136 this function calls this field passing the object as its only argument.
6137 In this case this function returns true and pushes onto the
6138 stack the value returned by the call.
6139 If there is no metatable or no metamethod,
6140 this function returns false (without pushing any value on the stack).
6141
6142
6143
6144
6145
6146 <hr><h3><a name="luaL_checkany"><code>luaL_checkany</code></a></h3><p>
6147 <span class="apii">[-0, +0, <em>v</em>]</span>
6148 <pre>void luaL_checkany (lua_State *L, int arg);</pre>
6149
6150 <p>
6151 Checks whether the function has an argument
6152 of any type (including <b>nil</b>) at position <code>arg</code>.
6153
6154
6155
6156
6157
6158 <hr><h3><a name="luaL_checkinteger"><code>luaL_checkinteger</code></a></h3><p>
6159 <span class="apii">[-0, +0, <em>v</em>]</span>
6160 <pre>lua_Integer luaL_checkinteger (lua_State *L, int arg);</pre>
6161
6162 <p>
6163 Checks whether the function argument <code>arg</code> is an integer
6164 (or can be converted to an integer)
6165 and returns this integer cast to a <a href="#lua_Integer"><code>lua_Integer</code></a>.
6166
6167
6168
6169
6170
6171 <hr><h3><a name="luaL_checklstring"><code>luaL_checklstring</code></a></h3><p>
6172 <span class="apii">[-0, +0, <em>v</em>]</span>
6173 <pre>const char *luaL_checklstring (lua_State *L, int arg, size_t *l);</pre>
6174
6175 <p>
6176 Checks whether the function argument <code>arg</code> is a string
6177 and returns this string;
6178 if <code>l</code> is not <code>NULL</code> fills <code>*l</code>
6179 with the string's length.
6180
6181
6182 <p>
6183 This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result,
6184 so all conversions and caveats of that function apply here.
6185
6186
6187
6188
6189
6190 <hr><h3><a name="luaL_checknumber"><code>luaL_checknumber</code></a></h3><p>
6191 <span class="apii">[-0, +0, <em>v</em>]</span>
6192 <pre>lua_Number luaL_checknumber (lua_State *L, int arg);</pre>
6193
6194 <p>
6195 Checks whether the function argument <code>arg</code> is a number
6196 and returns this number.
6197
6198
6199
6200
6201
6202 <hr><h3><a name="luaL_checkoption"><code>luaL_checkoption</code></a></h3><p>
6203 <span class="apii">[-0, +0, <em>v</em>]</span>
6204 <pre>int luaL_checkoption (lua_State *L,
6205                       int arg,
6206                       const char *def,
6207                       const char *const lst[]);</pre>
6208
6209 <p>
6210 Checks whether the function argument <code>arg</code> is a string and
6211 searches for this string in the array <code>lst</code>
6212 (which must be NULL-terminated).
6213 Returns the index in the array where the string was found.
6214 Raises an error if the argument is not a string or
6215 if the string cannot be found.
6216
6217
6218 <p>
6219 If <code>def</code> is not <code>NULL</code>,
6220 the function uses <code>def</code> as a default value when
6221 there is no argument <code>arg</code> or when this argument is <b>nil</b>.
6222
6223
6224 <p>
6225 This is a useful function for mapping strings to C&nbsp;enums.
6226 (The usual convention in Lua libraries is
6227 to use strings instead of numbers to select options.)
6228
6229
6230
6231
6232
6233 <hr><h3><a name="luaL_checkstack"><code>luaL_checkstack</code></a></h3><p>
6234 <span class="apii">[-0, +0, <em>v</em>]</span>
6235 <pre>void luaL_checkstack (lua_State *L, int sz, const char *msg);</pre>
6236
6237 <p>
6238 Grows the stack size to <code>top + sz</code> elements,
6239 raising an error if the stack cannot grow to that size.
6240 <code>msg</code> is an additional text to go into the error message
6241 (or <code>NULL</code> for no additional text).
6242
6243
6244
6245
6246
6247 <hr><h3><a name="luaL_checkstring"><code>luaL_checkstring</code></a></h3><p>
6248 <span class="apii">[-0, +0, <em>v</em>]</span>
6249 <pre>const char *luaL_checkstring (lua_State *L, int arg);</pre>
6250
6251 <p>
6252 Checks whether the function argument <code>arg</code> is a string
6253 and returns this string.
6254
6255
6256 <p>
6257 This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result,
6258 so all conversions and caveats of that function apply here.
6259
6260
6261
6262
6263
6264 <hr><h3><a name="luaL_checktype"><code>luaL_checktype</code></a></h3><p>
6265 <span class="apii">[-0, +0, <em>v</em>]</span>
6266 <pre>void luaL_checktype (lua_State *L, int arg, int t);</pre>
6267
6268 <p>
6269 Checks whether the function argument <code>arg</code> has type <code>t</code>.
6270 See <a href="#lua_type"><code>lua_type</code></a> for the encoding of types for <code>t</code>.
6271
6272
6273
6274
6275
6276 <hr><h3><a name="luaL_checkudata"><code>luaL_checkudata</code></a></h3><p>
6277 <span class="apii">[-0, +0, <em>v</em>]</span>
6278 <pre>void *luaL_checkudata (lua_State *L, int arg, const char *tname);</pre>
6279
6280 <p>
6281 Checks whether the function argument <code>arg</code> is a userdata
6282 of the type <code>tname</code> (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>) and
6283 returns the userdata address (see <a href="#lua_touserdata"><code>lua_touserdata</code></a>).
6284
6285
6286
6287
6288
6289 <hr><h3><a name="luaL_checkversion"><code>luaL_checkversion</code></a></h3><p>
6290 <span class="apii">[-0, +0, <em>v</em>]</span>
6291 <pre>void luaL_checkversion (lua_State *L);</pre>
6292
6293 <p>
6294 Checks whether the core running the call,
6295 the core that created the Lua state,
6296 and the code making the call are all using the same version of Lua.
6297 Also checks whether the core running the call
6298 and the core that created the Lua state
6299 are using the same address space.
6300
6301
6302
6303
6304
6305 <hr><h3><a name="luaL_dofile"><code>luaL_dofile</code></a></h3><p>
6306 <span class="apii">[-0, +?, <em>e</em>]</span>
6307 <pre>int luaL_dofile (lua_State *L, const char *filename);</pre>
6308
6309 <p>
6310 Loads and runs the given file.
6311 It is defined as the following macro:
6312
6313 <pre>
6314      (luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0))
6315 </pre><p>
6316 It returns false if there are no errors
6317 or true in case of errors.
6318
6319
6320
6321
6322
6323 <hr><h3><a name="luaL_dostring"><code>luaL_dostring</code></a></h3><p>
6324 <span class="apii">[-0, +?, &ndash;]</span>
6325 <pre>int luaL_dostring (lua_State *L, const char *str);</pre>
6326
6327 <p>
6328 Loads and runs the given string.
6329 It is defined as the following macro:
6330
6331 <pre>
6332      (luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0))
6333 </pre><p>
6334 It returns false if there are no errors
6335 or true in case of errors.
6336
6337
6338
6339
6340
6341 <hr><h3><a name="luaL_error"><code>luaL_error</code></a></h3><p>
6342 <span class="apii">[-0, +0, <em>v</em>]</span>
6343 <pre>int luaL_error (lua_State *L, const char *fmt, ...);</pre>
6344
6345 <p>
6346 Raises an error.
6347 The error message format is given by <code>fmt</code>
6348 plus any extra arguments,
6349 following the same rules of <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>.
6350 It also adds at the beginning of the message the file name and
6351 the line number where the error occurred,
6352 if this information is available.
6353
6354
6355 <p>
6356 This function never returns,
6357 but it is an idiom to use it in C&nbsp;functions
6358 as <code>return luaL_error(<em>args</em>)</code>.
6359
6360
6361
6362
6363
6364 <hr><h3><a name="luaL_execresult"><code>luaL_execresult</code></a></h3><p>
6365 <span class="apii">[-0, +3, <em>m</em>]</span>
6366 <pre>int luaL_execresult (lua_State *L, int stat);</pre>
6367
6368 <p>
6369 This function produces the return values for
6370 process-related functions in the standard library
6371 (<a href="#pdf-os.execute"><code>os.execute</code></a> and <a href="#pdf-io.close"><code>io.close</code></a>).
6372
6373
6374
6375
6376
6377 <hr><h3><a name="luaL_fileresult"><code>luaL_fileresult</code></a></h3><p>
6378 <span class="apii">[-0, +(1|3), <em>m</em>]</span>
6379 <pre>int luaL_fileresult (lua_State *L, int stat, const char *fname);</pre>
6380
6381 <p>
6382 This function produces the return values for
6383 file-related functions in the standard library
6384 (<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.).
6385
6386
6387
6388
6389
6390 <hr><h3><a name="luaL_getmetafield"><code>luaL_getmetafield</code></a></h3><p>
6391 <span class="apii">[-0, +(0|1), <em>m</em>]</span>
6392 <pre>int luaL_getmetafield (lua_State *L, int obj, const char *e);</pre>
6393
6394 <p>
6395 Pushes onto the stack the field <code>e</code> from the metatable
6396 of the object at index <code>obj</code> and returns the type of pushed value.
6397 If the object does not have a metatable,
6398 or if the metatable does not have this field,
6399 pushes nothing and returns <code>LUA_TNIL</code>.
6400
6401
6402
6403
6404
6405 <hr><h3><a name="luaL_getmetatable"><code>luaL_getmetatable</code></a></h3><p>
6406 <span class="apii">[-0, +1, <em>m</em>]</span>
6407 <pre>int luaL_getmetatable (lua_State *L, const char *tname);</pre>
6408
6409 <p>
6410 Pushes onto the stack the metatable associated with name <code>tname</code>
6411 in the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>)
6412 (<b>nil</b> if there is no metatable associated with that name).
6413 Returns the type of the pushed value.
6414
6415
6416
6417
6418
6419 <hr><h3><a name="luaL_getsubtable"><code>luaL_getsubtable</code></a></h3><p>
6420 <span class="apii">[-0, +1, <em>e</em>]</span>
6421 <pre>int luaL_getsubtable (lua_State *L, int idx, const char *fname);</pre>
6422
6423 <p>
6424 Ensures that the value <code>t[fname]</code>,
6425 where <code>t</code> is the value at index <code>idx</code>,
6426 is a table,
6427 and pushes that table onto the stack.
6428 Returns true if it finds a previous table there
6429 and false if it creates a new table.
6430
6431
6432
6433
6434
6435 <hr><h3><a name="luaL_gsub"><code>luaL_gsub</code></a></h3><p>
6436 <span class="apii">[-0, +1, <em>m</em>]</span>
6437 <pre>const char *luaL_gsub (lua_State *L,
6438                        const char *s,
6439                        const char *p,
6440                        const char *r);</pre>
6441
6442 <p>
6443 Creates a copy of string <code>s</code> by replacing
6444 any occurrence of the string <code>p</code>
6445 with the string <code>r</code>.
6446 Pushes the resulting string on the stack and returns it.
6447
6448
6449
6450
6451
6452 <hr><h3><a name="luaL_len"><code>luaL_len</code></a></h3><p>
6453 <span class="apii">[-0, +0, <em>e</em>]</span>
6454 <pre>lua_Integer luaL_len (lua_State *L, int index);</pre>
6455
6456 <p>
6457 Returns the "length" of the value at the given index
6458 as a number;
6459 it is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">&sect;3.4.7</a>).
6460 Raises an error if the result of the operation is not an integer.
6461 (This case only can happen through metamethods.)
6462
6463
6464
6465
6466
6467 <hr><h3><a name="luaL_loadbuffer"><code>luaL_loadbuffer</code></a></h3><p>
6468 <span class="apii">[-0, +1, &ndash;]</span>
6469 <pre>int luaL_loadbuffer (lua_State *L,
6470                      const char *buff,
6471                      size_t sz,
6472                      const char *name);</pre>
6473
6474 <p>
6475 Equivalent to <a href="#luaL_loadbufferx"><code>luaL_loadbufferx</code></a> with <code>mode</code> equal to <code>NULL</code>.
6476
6477
6478
6479
6480
6481 <hr><h3><a name="luaL_loadbufferx"><code>luaL_loadbufferx</code></a></h3><p>
6482 <span class="apii">[-0, +1, &ndash;]</span>
6483 <pre>int luaL_loadbufferx (lua_State *L,
6484                       const char *buff,
6485                       size_t sz,
6486                       const char *name,
6487                       const char *mode);</pre>
6488
6489 <p>
6490 Loads a buffer as a Lua chunk.
6491 This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the
6492 buffer pointed to by <code>buff</code> with size <code>sz</code>.
6493
6494
6495 <p>
6496 This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>.
6497 <code>name</code> is the chunk name,
6498 used for debug information and error messages.
6499 The string <code>mode</code> works as in function <a href="#lua_load"><code>lua_load</code></a>.
6500
6501
6502
6503
6504
6505 <hr><h3><a name="luaL_loadfile"><code>luaL_loadfile</code></a></h3><p>
6506 <span class="apii">[-0, +1, <em>m</em>]</span>
6507 <pre>int luaL_loadfile (lua_State *L, const char *filename);</pre>
6508
6509 <p>
6510 Equivalent to <a href="#luaL_loadfilex"><code>luaL_loadfilex</code></a> with <code>mode</code> equal to <code>NULL</code>.
6511
6512
6513
6514
6515
6516 <hr><h3><a name="luaL_loadfilex"><code>luaL_loadfilex</code></a></h3><p>
6517 <span class="apii">[-0, +1, <em>m</em>]</span>
6518 <pre>int luaL_loadfilex (lua_State *L, const char *filename,
6519                                             const char *mode);</pre>
6520
6521 <p>
6522 Loads a file as a Lua chunk.
6523 This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the file
6524 named <code>filename</code>.
6525 If <code>filename</code> is <code>NULL</code>,
6526 then it loads from the standard input.
6527 The first line in the file is ignored if it starts with a <code>#</code>.
6528
6529
6530 <p>
6531 The string <code>mode</code> works as in function <a href="#lua_load"><code>lua_load</code></a>.
6532
6533
6534 <p>
6535 This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>,
6536 but it has an extra error code <a name="pdf-LUA_ERRFILE"><code>LUA_ERRFILE</code></a>
6537 if it cannot open/read the file or the file has a wrong mode.
6538
6539
6540 <p>
6541 As <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk;
6542 it does not run it.
6543
6544
6545
6546
6547
6548 <hr><h3><a name="luaL_loadstring"><code>luaL_loadstring</code></a></h3><p>
6549 <span class="apii">[-0, +1, &ndash;]</span>
6550 <pre>int luaL_loadstring (lua_State *L, const char *s);</pre>
6551
6552 <p>
6553 Loads a string as a Lua chunk.
6554 This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in
6555 the zero-terminated string <code>s</code>.
6556
6557
6558 <p>
6559 This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>.
6560
6561
6562 <p>
6563 Also as <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk;
6564 it does not run it.
6565
6566
6567
6568
6569
6570 <hr><h3><a name="luaL_newlib"><code>luaL_newlib</code></a></h3><p>
6571 <span class="apii">[-0, +1, <em>m</em>]</span>
6572 <pre>void luaL_newlib (lua_State *L, const luaL_Reg l[]);</pre>
6573
6574 <p>
6575 Creates a new table and registers there
6576 the functions in list <code>l</code>.
6577
6578
6579 <p>
6580 It is implemented as the following macro:
6581
6582 <pre>
6583      (luaL_newlibtable(L,l), luaL_setfuncs(L,l,0))
6584 </pre><p>
6585 The array <code>l</code> must be the actual array,
6586 not a pointer to it.
6587
6588
6589
6590
6591
6592 <hr><h3><a name="luaL_newlibtable"><code>luaL_newlibtable</code></a></h3><p>
6593 <span class="apii">[-0, +1, <em>m</em>]</span>
6594 <pre>void luaL_newlibtable (lua_State *L, const luaL_Reg l[]);</pre>
6595
6596 <p>
6597 Creates a new table with a size optimized
6598 to store all entries in the array <code>l</code>
6599 (but does not actually store them).
6600 It is intended to be used in conjunction with <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a>
6601 (see <a href="#luaL_newlib"><code>luaL_newlib</code></a>).
6602
6603
6604 <p>
6605 It is implemented as a macro.
6606 The array <code>l</code> must be the actual array,
6607 not a pointer to it.
6608
6609
6610
6611
6612
6613 <hr><h3><a name="luaL_newmetatable"><code>luaL_newmetatable</code></a></h3><p>
6614 <span class="apii">[-0, +1, <em>m</em>]</span>
6615 <pre>int luaL_newmetatable (lua_State *L, const char *tname);</pre>
6616
6617 <p>
6618 If the registry already has the key <code>tname</code>,
6619 returns 0.
6620 Otherwise,
6621 creates a new table to be used as a metatable for userdata,
6622 adds to this new table the pair <code>__name = tname</code>,
6623 adds to the registry the pair <code>[tname] = new table</code>,
6624 and returns 1.
6625 (The entry <code>__name</code> is used by some error-reporting functions.)
6626
6627
6628 <p>
6629 In both cases pushes onto the stack the final value associated
6630 with <code>tname</code> in the registry.
6631
6632
6633
6634
6635
6636 <hr><h3><a name="luaL_newstate"><code>luaL_newstate</code></a></h3><p>
6637 <span class="apii">[-0, +0, &ndash;]</span>
6638 <pre>lua_State *luaL_newstate (void);</pre>
6639
6640 <p>
6641 Creates a new Lua state.
6642 It calls <a href="#lua_newstate"><code>lua_newstate</code></a> with an
6643 allocator based on the standard&nbsp;C <code>realloc</code> function
6644 and then sets a panic function (see <a href="#4.6">&sect;4.6</a>) that prints
6645 an error message to the standard error output in case of fatal
6646 errors.
6647
6648
6649 <p>
6650 Returns the new state,
6651 or <code>NULL</code> if there is a memory allocation error.
6652
6653
6654
6655
6656
6657 <hr><h3><a name="luaL_openlibs"><code>luaL_openlibs</code></a></h3><p>
6658 <span class="apii">[-0, +0, <em>e</em>]</span>
6659 <pre>void luaL_openlibs (lua_State *L);</pre>
6660
6661 <p>
6662 Opens all standard Lua libraries into the given state.
6663
6664
6665
6666
6667
6668 <hr><h3><a name="luaL_opt"><code>luaL_opt</code></a></h3><p>
6669 <span class="apii">[-0, +0, <em>e</em>]</span>
6670 <pre>T luaL_opt (L, func, arg, dflt);</pre>
6671
6672 <p>
6673 This macro is defined as follows:
6674
6675 <pre>
6676      (lua_isnoneornil(L,(arg)) ? (dflt) : func(L,(arg)))
6677 </pre><p>
6678 In words, if the argument <code>arg</code> is nil or absent,
6679 the macro results in the default <code>dflt</code>.
6680 Otherwise, it results in the result of calling <code>func</code>
6681 with the state <code>L</code> and the argument index <code>arg</code> as
6682 parameters.
6683 Note that it evaluates the expression <code>dflt</code> only if needed.
6684
6685
6686
6687
6688
6689 <hr><h3><a name="luaL_optinteger"><code>luaL_optinteger</code></a></h3><p>
6690 <span class="apii">[-0, +0, <em>v</em>]</span>
6691 <pre>lua_Integer luaL_optinteger (lua_State *L,
6692                              int arg,
6693                              lua_Integer d);</pre>
6694
6695 <p>
6696 If the function argument <code>arg</code> is an integer
6697 (or convertible to an integer),
6698 returns this integer.
6699 If this argument is absent or is <b>nil</b>,
6700 returns <code>d</code>.
6701 Otherwise, raises an error.
6702
6703
6704
6705
6706
6707 <hr><h3><a name="luaL_optlstring"><code>luaL_optlstring</code></a></h3><p>
6708 <span class="apii">[-0, +0, <em>v</em>]</span>
6709 <pre>const char *luaL_optlstring (lua_State *L,
6710                              int arg,
6711                              const char *d,
6712                              size_t *l);</pre>
6713
6714 <p>
6715 If the function argument <code>arg</code> is a string,
6716 returns this string.
6717 If this argument is absent or is <b>nil</b>,
6718 returns <code>d</code>.
6719 Otherwise, raises an error.
6720
6721
6722 <p>
6723 If <code>l</code> is not <code>NULL</code>,
6724 fills the position <code>*l</code> with the result's length.
6725 If the result is <code>NULL</code>
6726 (only possible when returning <code>d</code> and <code>d == NULL</code>),
6727 its length is considered zero.
6728
6729
6730
6731
6732
6733 <hr><h3><a name="luaL_optnumber"><code>luaL_optnumber</code></a></h3><p>
6734 <span class="apii">[-0, +0, <em>v</em>]</span>
6735 <pre>lua_Number luaL_optnumber (lua_State *L, int arg, lua_Number d);</pre>
6736
6737 <p>
6738 If the function argument <code>arg</code> is a number,
6739 returns this number.
6740 If this argument is absent or is <b>nil</b>,
6741 returns <code>d</code>.
6742 Otherwise, raises an error.
6743
6744
6745
6746
6747
6748 <hr><h3><a name="luaL_optstring"><code>luaL_optstring</code></a></h3><p>
6749 <span class="apii">[-0, +0, <em>v</em>]</span>
6750 <pre>const char *luaL_optstring (lua_State *L,
6751                             int arg,
6752                             const char *d);</pre>
6753
6754 <p>
6755 If the function argument <code>arg</code> is a string,
6756 returns this string.
6757 If this argument is absent or is <b>nil</b>,
6758 returns <code>d</code>.
6759 Otherwise, raises an error.
6760
6761
6762
6763
6764
6765 <hr><h3><a name="luaL_prepbuffer"><code>luaL_prepbuffer</code></a></h3><p>
6766 <span class="apii">[-?, +?, <em>m</em>]</span>
6767 <pre>char *luaL_prepbuffer (luaL_Buffer *B);</pre>
6768
6769 <p>
6770 Equivalent to <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a>
6771 with the predefined size <a name="pdf-LUAL_BUFFERSIZE"><code>LUAL_BUFFERSIZE</code></a>.
6772
6773
6774
6775
6776
6777 <hr><h3><a name="luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a></h3><p>
6778 <span class="apii">[-?, +?, <em>m</em>]</span>
6779 <pre>char *luaL_prepbuffsize (luaL_Buffer *B, size_t sz);</pre>
6780
6781 <p>
6782 Returns an address to a space of size <code>sz</code>
6783 where you can copy a string to be added to buffer <code>B</code>
6784 (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
6785 After copying the string into this space you must call
6786 <a href="#luaL_addsize"><code>luaL_addsize</code></a> with the size of the string to actually add
6787 it to the buffer.
6788
6789
6790
6791
6792
6793 <hr><h3><a name="luaL_pushresult"><code>luaL_pushresult</code></a></h3><p>
6794 <span class="apii">[-?, +1, <em>m</em>]</span>
6795 <pre>void luaL_pushresult (luaL_Buffer *B);</pre>
6796
6797 <p>
6798 Finishes the use of buffer <code>B</code> leaving the final string on
6799 the top of the stack.
6800
6801
6802
6803
6804
6805 <hr><h3><a name="luaL_pushresultsize"><code>luaL_pushresultsize</code></a></h3><p>
6806 <span class="apii">[-?, +1, <em>m</em>]</span>
6807 <pre>void luaL_pushresultsize (luaL_Buffer *B, size_t sz);</pre>
6808
6809 <p>
6810 Equivalent to the sequence <a href="#luaL_addsize"><code>luaL_addsize</code></a>, <a href="#luaL_pushresult"><code>luaL_pushresult</code></a>.
6811
6812
6813
6814
6815
6816 <hr><h3><a name="luaL_ref"><code>luaL_ref</code></a></h3><p>
6817 <span class="apii">[-1, +0, <em>m</em>]</span>
6818 <pre>int luaL_ref (lua_State *L, int t);</pre>
6819
6820 <p>
6821 Creates and returns a <em>reference</em>,
6822 in the table at index <code>t</code>,
6823 for the object at the top of the stack (and pops the object).
6824
6825
6826 <p>
6827 A reference is a unique integer key.
6828 As long as you do not manually add integer keys into table <code>t</code>,
6829 <a href="#luaL_ref"><code>luaL_ref</code></a> ensures the uniqueness of the key it returns.
6830 You can retrieve an object referred by reference <code>r</code>
6831 by calling <code>lua_rawgeti(L, t, r)</code>.
6832 Function <a href="#luaL_unref"><code>luaL_unref</code></a> frees a reference and its associated object.
6833
6834
6835 <p>
6836 If the object at the top of the stack is <b>nil</b>,
6837 <a href="#luaL_ref"><code>luaL_ref</code></a> returns the constant <a name="pdf-LUA_REFNIL"><code>LUA_REFNIL</code></a>.
6838 The constant <a name="pdf-LUA_NOREF"><code>LUA_NOREF</code></a> is guaranteed to be different
6839 from any reference returned by <a href="#luaL_ref"><code>luaL_ref</code></a>.
6840
6841
6842
6843
6844
6845 <hr><h3><a name="luaL_Reg"><code>luaL_Reg</code></a></h3>
6846 <pre>typedef struct luaL_Reg {
6847   const char *name;
6848   lua_CFunction func;
6849 } luaL_Reg;</pre>
6850
6851 <p>
6852 Type for arrays of functions to be registered by
6853 <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a>.
6854 <code>name</code> is the function name and <code>func</code> is a pointer to
6855 the function.
6856 Any array of <a href="#luaL_Reg"><code>luaL_Reg</code></a> must end with a sentinel entry
6857 in which both <code>name</code> and <code>func</code> are <code>NULL</code>.
6858
6859
6860
6861
6862
6863 <hr><h3><a name="luaL_requiref"><code>luaL_requiref</code></a></h3><p>
6864 <span class="apii">[-0, +1, <em>e</em>]</span>
6865 <pre>void luaL_requiref (lua_State *L, const char *modname,
6866                     lua_CFunction openf, int glb);</pre>
6867
6868 <p>
6869 If <code>modname</code> is not already present in <a href="#pdf-package.loaded"><code>package.loaded</code></a>,
6870 calls function <code>openf</code> with string <code>modname</code> as an argument
6871 and sets the call result in <code>package.loaded[modname]</code>,
6872 as if that function has been called through <a href="#pdf-require"><code>require</code></a>.
6873
6874
6875 <p>
6876 If <code>glb</code> is true,
6877 also stores the module into global <code>modname</code>.
6878
6879
6880 <p>
6881 Leaves a copy of the module on the stack.
6882
6883
6884
6885
6886
6887 <hr><h3><a name="luaL_setfuncs"><code>luaL_setfuncs</code></a></h3><p>
6888 <span class="apii">[-nup, +0, <em>m</em>]</span>
6889 <pre>void luaL_setfuncs (lua_State *L, const luaL_Reg *l, int nup);</pre>
6890
6891 <p>
6892 Registers all functions in the array <code>l</code>
6893 (see <a href="#luaL_Reg"><code>luaL_Reg</code></a>) into the table on the top of the stack
6894 (below optional upvalues, see next).
6895
6896
6897 <p>
6898 When <code>nup</code> is not zero,
6899 all functions are created sharing <code>nup</code> upvalues,
6900 which must be previously pushed on the stack
6901 on top of the library table.
6902 These values are popped from the stack after the registration.
6903
6904
6905
6906
6907
6908 <hr><h3><a name="luaL_setmetatable"><code>luaL_setmetatable</code></a></h3><p>
6909 <span class="apii">[-0, +0, &ndash;]</span>
6910 <pre>void luaL_setmetatable (lua_State *L, const char *tname);</pre>
6911
6912 <p>
6913 Sets the metatable of the object at the top of the stack
6914 as the metatable associated with name <code>tname</code>
6915 in the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>).
6916
6917
6918
6919
6920
6921 <hr><h3><a name="luaL_Stream"><code>luaL_Stream</code></a></h3>
6922 <pre>typedef struct luaL_Stream {
6923   FILE *f;
6924   lua_CFunction closef;
6925 } luaL_Stream;</pre>
6926
6927 <p>
6928 The standard representation for file handles,
6929 which is used by the standard I/O library.
6930
6931
6932 <p>
6933 A file handle is implemented as a full userdata,
6934 with a metatable called <code>LUA_FILEHANDLE</code>
6935 (where <code>LUA_FILEHANDLE</code> is a macro with the actual metatable's name).
6936 The metatable is created by the I/O library
6937 (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>).
6938
6939
6940 <p>
6941 This userdata must start with the structure <code>luaL_Stream</code>;
6942 it can contain other data after this initial structure.
6943 Field <code>f</code> points to the corresponding C stream
6944 (or it can be <code>NULL</code> to indicate an incompletely created handle).
6945 Field <code>closef</code> points to a Lua function
6946 that will be called to close the stream
6947 when the handle is closed or collected;
6948 this function receives the file handle as its sole argument and
6949 must return either <b>true</b> (in case of success)
6950 or <b>nil</b> plus an error message (in case of error).
6951 Once Lua calls this field,
6952 it changes the field value to <code>NULL</code>
6953 to signal that the handle is closed.
6954
6955
6956
6957
6958
6959 <hr><h3><a name="luaL_testudata"><code>luaL_testudata</code></a></h3><p>
6960 <span class="apii">[-0, +0, <em>m</em>]</span>
6961 <pre>void *luaL_testudata (lua_State *L, int arg, const char *tname);</pre>
6962
6963 <p>
6964 This function works like <a href="#luaL_checkudata"><code>luaL_checkudata</code></a>,
6965 except that, when the test fails,
6966 it returns <code>NULL</code> instead of raising an error.
6967
6968
6969
6970
6971
6972 <hr><h3><a name="luaL_tolstring"><code>luaL_tolstring</code></a></h3><p>
6973 <span class="apii">[-0, +1, <em>e</em>]</span>
6974 <pre>const char *luaL_tolstring (lua_State *L, int idx, size_t *len);</pre>
6975
6976 <p>
6977 Converts any Lua value at the given index to a C&nbsp;string
6978 in a reasonable format.
6979 The resulting string is pushed onto the stack and also
6980 returned by the function.
6981 If <code>len</code> is not <code>NULL</code>,
6982 the function also sets <code>*len</code> with the string length.
6983
6984
6985 <p>
6986 If the value has a metatable with a <code>__tostring</code> field,
6987 then <code>luaL_tolstring</code> calls the corresponding metamethod
6988 with the value as argument,
6989 and uses the result of the call as its result.
6990
6991
6992
6993
6994
6995 <hr><h3><a name="luaL_traceback"><code>luaL_traceback</code></a></h3><p>
6996 <span class="apii">[-0, +1, <em>m</em>]</span>
6997 <pre>void luaL_traceback (lua_State *L, lua_State *L1, const char *msg,
6998                      int level);</pre>
6999
7000 <p>
7001 Creates and pushes a traceback of the stack <code>L1</code>.
7002 If <code>msg</code> is not <code>NULL</code> it is appended
7003 at the beginning of the traceback.
7004 The <code>level</code> parameter tells at which level
7005 to start the traceback.
7006
7007
7008
7009
7010
7011 <hr><h3><a name="luaL_typename"><code>luaL_typename</code></a></h3><p>
7012 <span class="apii">[-0, +0, &ndash;]</span>
7013 <pre>const char *luaL_typename (lua_State *L, int index);</pre>
7014
7015 <p>
7016 Returns the name of the type of the value at the given index.
7017
7018
7019
7020
7021
7022 <hr><h3><a name="luaL_unref"><code>luaL_unref</code></a></h3><p>
7023 <span class="apii">[-0, +0, &ndash;]</span>
7024 <pre>void luaL_unref (lua_State *L, int t, int ref);</pre>
7025
7026 <p>
7027 Releases reference <code>ref</code> from the table at index <code>t</code>
7028 (see <a href="#luaL_ref"><code>luaL_ref</code></a>).
7029 The entry is removed from the table,
7030 so that the referred object can be collected.
7031 The reference <code>ref</code> is also freed to be used again.
7032
7033
7034 <p>
7035 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>,
7036 <a href="#luaL_unref"><code>luaL_unref</code></a> does nothing.
7037
7038
7039
7040
7041
7042 <hr><h3><a name="luaL_where"><code>luaL_where</code></a></h3><p>
7043 <span class="apii">[-0, +1, <em>m</em>]</span>
7044 <pre>void luaL_where (lua_State *L, int lvl);</pre>
7045
7046 <p>
7047 Pushes onto the stack a string identifying the current position
7048 of the control at level <code>lvl</code> in the call stack.
7049 Typically this string has the following format:
7050
7051 <pre>
7052      <em>chunkname</em>:<em>currentline</em>:
7053 </pre><p>
7054 Level&nbsp;0 is the running function,
7055 level&nbsp;1 is the function that called the running function,
7056 etc.
7057
7058
7059 <p>
7060 This function is used to build a prefix for error messages.
7061
7062
7063
7064
7065
7066
7067
7068 <h1>6 &ndash; <a name="6">Standard Libraries</a></h1>
7069
7070 <p>
7071 The standard Lua libraries provide useful functions
7072 that are implemented directly through the C&nbsp;API.
7073 Some of these functions provide essential services to the language
7074 (e.g., <a href="#pdf-type"><code>type</code></a> and <a href="#pdf-getmetatable"><code>getmetatable</code></a>);
7075 others provide access to "outside" services (e.g., I/O);
7076 and others could be implemented in Lua itself,
7077 but are quite useful or have critical performance requirements that
7078 deserve an implementation in C (e.g., <a href="#pdf-table.sort"><code>table.sort</code></a>).
7079
7080
7081 <p>
7082 All libraries are implemented through the official C&nbsp;API
7083 and are provided as separate C&nbsp;modules.
7084 Currently, Lua has the following standard libraries:
7085
7086 <ul>
7087
7088 <li>basic library (<a href="#6.1">&sect;6.1</a>);</li>
7089
7090 <li>coroutine library (<a href="#6.2">&sect;6.2</a>);</li>
7091
7092 <li>package library (<a href="#6.3">&sect;6.3</a>);</li>
7093
7094 <li>string manipulation (<a href="#6.4">&sect;6.4</a>);</li>
7095
7096 <li>basic UTF-8 support (<a href="#6.5">&sect;6.5</a>);</li>
7097
7098 <li>table manipulation (<a href="#6.6">&sect;6.6</a>);</li>
7099
7100 <li>mathematical functions (<a href="#6.7">&sect;6.7</a>) (sin, log, etc.);</li>
7101
7102 <li>input and output (<a href="#6.8">&sect;6.8</a>);</li>
7103
7104 <li>operating system facilities (<a href="#6.9">&sect;6.9</a>);</li>
7105
7106 <li>debug facilities (<a href="#6.10">&sect;6.10</a>).</li>
7107
7108 </ul><p>
7109 Except for the basic and the package libraries,
7110 each library provides all its functions as fields of a global table
7111 or as methods of its objects.
7112
7113
7114 <p>
7115 To have access to these libraries,
7116 the C&nbsp;host program should call the <a href="#luaL_openlibs"><code>luaL_openlibs</code></a> function,
7117 which opens all standard libraries.
7118 Alternatively,
7119 the host program can open them individually by using
7120 <a href="#luaL_requiref"><code>luaL_requiref</code></a> to call
7121 <a name="pdf-luaopen_base"><code>luaopen_base</code></a> (for the basic library),
7122 <a name="pdf-luaopen_package"><code>luaopen_package</code></a> (for the package library),
7123 <a name="pdf-luaopen_coroutine"><code>luaopen_coroutine</code></a> (for the coroutine library),
7124 <a name="pdf-luaopen_string"><code>luaopen_string</code></a> (for the string library),
7125 <a name="pdf-luaopen_utf8"><code>luaopen_utf8</code></a> (for the UTF8 library),
7126 <a name="pdf-luaopen_table"><code>luaopen_table</code></a> (for the table library),
7127 <a name="pdf-luaopen_math"><code>luaopen_math</code></a> (for the mathematical library),
7128 <a name="pdf-luaopen_io"><code>luaopen_io</code></a> (for the I/O library),
7129 <a name="pdf-luaopen_os"><code>luaopen_os</code></a> (for the operating system library),
7130 and <a name="pdf-luaopen_debug"><code>luaopen_debug</code></a> (for the debug library).
7131 These functions are declared in <a name="pdf-lualib.h"><code>lualib.h</code></a>.
7132
7133
7134
7135 <h2>6.1 &ndash; <a name="6.1">Basic Functions</a></h2>
7136
7137 <p>
7138 The basic library provides core functions to Lua.
7139 If you do not include this library in your application,
7140 you should check carefully whether you need to provide
7141 implementations for some of its facilities.
7142
7143
7144 <p>
7145 <hr><h3><a name="pdf-assert"><code>assert (v [, message])</code></a></h3>
7146
7147
7148 <p>
7149 Calls <a href="#pdf-error"><code>error</code></a> if
7150 the value of its argument <code>v</code> is false (i.e., <b>nil</b> or <b>false</b>);
7151 otherwise, returns all its arguments.
7152 In case of error,
7153 <code>message</code> is the error object;
7154 when absent, it defaults to "<code>assertion failed!</code>"
7155
7156
7157
7158
7159 <p>
7160 <hr><h3><a name="pdf-collectgarbage"><code>collectgarbage ([opt [, arg]])</code></a></h3>
7161
7162
7163 <p>
7164 This function is a generic interface to the garbage collector.
7165 It performs different functions according to its first argument, <code>opt</code>:
7166
7167 <ul>
7168
7169 <li><b>"<code>collect</code>": </b>
7170 performs a full garbage-collection cycle.
7171 This is the default option.
7172 </li>
7173
7174 <li><b>"<code>stop</code>": </b>
7175 stops automatic execution of the garbage collector.
7176 The collector will run only when explicitly invoked,
7177 until a call to restart it.
7178 </li>
7179
7180 <li><b>"<code>restart</code>": </b>
7181 restarts automatic execution of the garbage collector.
7182 </li>
7183
7184 <li><b>"<code>count</code>": </b>
7185 returns the total memory in use by Lua in Kbytes.
7186 The value has a fractional part,
7187 so that it multiplied by 1024
7188 gives the exact number of bytes in use by Lua
7189 (except for overflows).
7190 </li>
7191
7192 <li><b>"<code>step</code>": </b>
7193 performs a garbage-collection step.
7194 The step "size" is controlled by <code>arg</code>.
7195 With a zero value,
7196 the collector will perform one basic (indivisible) step.
7197 For non-zero values,
7198 the collector will perform as if that amount of memory
7199 (in KBytes) had been allocated by Lua.
7200 Returns <b>true</b> if the step finished a collection cycle.
7201 </li>
7202
7203 <li><b>"<code>setpause</code>": </b>
7204 sets <code>arg</code> as the new value for the <em>pause</em> of
7205 the collector (see <a href="#2.5">&sect;2.5</a>).
7206 Returns the previous value for <em>pause</em>.
7207 </li>
7208
7209 <li><b>"<code>setstepmul</code>": </b>
7210 sets <code>arg</code> as the new value for the <em>step multiplier</em> of
7211 the collector (see <a href="#2.5">&sect;2.5</a>).
7212 Returns the previous value for <em>step</em>.
7213 </li>
7214
7215 <li><b>"<code>isrunning</code>": </b>
7216 returns a boolean that tells whether the collector is running
7217 (i.e., not stopped).
7218 </li>
7219
7220 </ul>
7221
7222
7223
7224 <p>
7225 <hr><h3><a name="pdf-dofile"><code>dofile ([filename])</code></a></h3>
7226 Opens the named file and executes its contents as a Lua chunk.
7227 When called without arguments,
7228 <code>dofile</code> executes the contents of the standard input (<code>stdin</code>).
7229 Returns all values returned by the chunk.
7230 In case of errors, <code>dofile</code> propagates the error
7231 to its caller (that is, <code>dofile</code> does not run in protected mode).
7232
7233
7234
7235
7236 <p>
7237 <hr><h3><a name="pdf-error"><code>error (message [, level])</code></a></h3>
7238 Terminates the last protected function called
7239 and returns <code>message</code> as the error object.
7240 Function <code>error</code> never returns.
7241
7242
7243 <p>
7244 Usually, <code>error</code> adds some information about the error position
7245 at the beginning of the message, if the message is a string.
7246 The <code>level</code> argument specifies how to get the error position.
7247 With level&nbsp;1 (the default), the error position is where the
7248 <code>error</code> function was called.
7249 Level&nbsp;2 points the error to where the function
7250 that called <code>error</code> was called; and so on.
7251 Passing a level&nbsp;0 avoids the addition of error position information
7252 to the message.
7253
7254
7255
7256
7257 <p>
7258 <hr><h3><a name="pdf-_G"><code>_G</code></a></h3>
7259 A global variable (not a function) that
7260 holds the global environment (see <a href="#2.2">&sect;2.2</a>).
7261 Lua itself does not use this variable;
7262 changing its value does not affect any environment,
7263 nor vice versa.
7264
7265
7266
7267
7268 <p>
7269 <hr><h3><a name="pdf-getmetatable"><code>getmetatable (object)</code></a></h3>
7270
7271
7272 <p>
7273 If <code>object</code> does not have a metatable, returns <b>nil</b>.
7274 Otherwise,
7275 if the object's metatable has a <code>__metatable</code> field,
7276 returns the associated value.
7277 Otherwise, returns the metatable of the given object.
7278
7279
7280
7281
7282 <p>
7283 <hr><h3><a name="pdf-ipairs"><code>ipairs (t)</code></a></h3>
7284
7285
7286 <p>
7287 Returns three values (an iterator function, the table <code>t</code>, and 0)
7288 so that the construction
7289
7290 <pre>
7291      for i,v in ipairs(t) do <em>body</em> end
7292 </pre><p>
7293 will iterate over the key&ndash;value pairs
7294 (<code>1,t[1]</code>), (<code>2,t[2]</code>), ...,
7295 up to the first nil value.
7296
7297
7298
7299
7300 <p>
7301 <hr><h3><a name="pdf-load"><code>load (chunk [, chunkname [, mode [, env]]])</code></a></h3>
7302
7303
7304 <p>
7305 Loads a chunk.
7306
7307
7308 <p>
7309 If <code>chunk</code> is a string, the chunk is this string.
7310 If <code>chunk</code> is a function,
7311 <code>load</code> calls it repeatedly to get the chunk pieces.
7312 Each call to <code>chunk</code> must return a string that concatenates
7313 with previous results.
7314 A return of an empty string, <b>nil</b>, or no value signals the end of the chunk.
7315
7316
7317 <p>
7318 If there are no syntactic errors,
7319 returns the compiled chunk as a function;
7320 otherwise, returns <b>nil</b> plus the error message.
7321
7322
7323 <p>
7324 If the resulting function has upvalues,
7325 the first upvalue is set to the value of <code>env</code>,
7326 if that parameter is given,
7327 or to the value of the global environment.
7328 Other upvalues are initialized with <b>nil</b>.
7329 (When you load a main chunk,
7330 the resulting function will always have exactly one upvalue,
7331 the <code>_ENV</code> variable (see <a href="#2.2">&sect;2.2</a>).
7332 However,
7333 when you load a binary chunk created from a function (see <a href="#pdf-string.dump"><code>string.dump</code></a>),
7334 the resulting function can have an arbitrary number of upvalues.)
7335 All upvalues are fresh, that is,
7336 they are not shared with any other function.
7337
7338
7339 <p>
7340 <code>chunkname</code> is used as the name of the chunk for error messages
7341 and debug information (see <a href="#4.9">&sect;4.9</a>).
7342 When absent,
7343 it defaults to <code>chunk</code>, if <code>chunk</code> is a string,
7344 or to "<code>=(load)</code>" otherwise.
7345
7346
7347 <p>
7348 The string <code>mode</code> controls whether the chunk can be text or binary
7349 (that is, a precompiled chunk).
7350 It may be the string "<code>b</code>" (only binary chunks),
7351 "<code>t</code>" (only text chunks),
7352 or "<code>bt</code>" (both binary and text).
7353 The default is "<code>bt</code>".
7354
7355
7356 <p>
7357 Lua does not check the consistency of binary chunks.
7358 Maliciously crafted binary chunks can crash
7359 the interpreter.
7360
7361
7362
7363
7364 <p>
7365 <hr><h3><a name="pdf-loadfile"><code>loadfile ([filename [, mode [, env]]])</code></a></h3>
7366
7367
7368 <p>
7369 Similar to <a href="#pdf-load"><code>load</code></a>,
7370 but gets the chunk from file <code>filename</code>
7371 or from the standard input,
7372 if no file name is given.
7373
7374
7375
7376
7377 <p>
7378 <hr><h3><a name="pdf-next"><code>next (table [, index])</code></a></h3>
7379
7380
7381 <p>
7382 Allows a program to traverse all fields of a table.
7383 Its first argument is a table and its second argument
7384 is an index in this table.
7385 <code>next</code> returns the next index of the table
7386 and its associated value.
7387 When called with <b>nil</b> as its second argument,
7388 <code>next</code> returns an initial index
7389 and its associated value.
7390 When called with the last index,
7391 or with <b>nil</b> in an empty table,
7392 <code>next</code> returns <b>nil</b>.
7393 If the second argument is absent, then it is interpreted as <b>nil</b>.
7394 In particular,
7395 you can use <code>next(t)</code> to check whether a table is empty.
7396
7397
7398 <p>
7399 The order in which the indices are enumerated is not specified,
7400 <em>even for numeric indices</em>.
7401 (To traverse a table in numerical order,
7402 use a numerical <b>for</b>.)
7403
7404
7405 <p>
7406 The behavior of <code>next</code> is undefined if,
7407 during the traversal,
7408 you assign any value to a non-existent field in the table.
7409 You may however modify existing fields.
7410 In particular, you may clear existing fields.
7411
7412
7413
7414
7415 <p>
7416 <hr><h3><a name="pdf-pairs"><code>pairs (t)</code></a></h3>
7417
7418
7419 <p>
7420 If <code>t</code> has a metamethod <code>__pairs</code>,
7421 calls it with <code>t</code> as argument and returns the first three
7422 results from the call.
7423
7424
7425 <p>
7426 Otherwise,
7427 returns three values: the <a href="#pdf-next"><code>next</code></a> function, the table <code>t</code>, and <b>nil</b>,
7428 so that the construction
7429
7430 <pre>
7431      for k,v in pairs(t) do <em>body</em> end
7432 </pre><p>
7433 will iterate over all key&ndash;value pairs of table <code>t</code>.
7434
7435
7436 <p>
7437 See function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying
7438 the table during its traversal.
7439
7440
7441
7442
7443 <p>
7444 <hr><h3><a name="pdf-pcall"><code>pcall (f [, arg1, &middot;&middot;&middot;])</code></a></h3>
7445
7446
7447 <p>
7448 Calls function <code>f</code> with
7449 the given arguments in <em>protected mode</em>.
7450 This means that any error inside&nbsp;<code>f</code> is not propagated;
7451 instead, <code>pcall</code> catches the error
7452 and returns a status code.
7453 Its first result is the status code (a boolean),
7454 which is true if the call succeeds without errors.
7455 In such case, <code>pcall</code> also returns all results from the call,
7456 after this first result.
7457 In case of any error, <code>pcall</code> returns <b>false</b> plus the error message.
7458
7459
7460
7461
7462 <p>
7463 <hr><h3><a name="pdf-print"><code>print (&middot;&middot;&middot;)</code></a></h3>
7464 Receives any number of arguments
7465 and prints their values to <code>stdout</code>,
7466 using the <a href="#pdf-tostring"><code>tostring</code></a> function to convert each argument to a string.
7467 <code>print</code> is not intended for formatted output,
7468 but only as a quick way to show a value,
7469 for instance for debugging.
7470 For complete control over the output,
7471 use <a href="#pdf-string.format"><code>string.format</code></a> and <a href="#pdf-io.write"><code>io.write</code></a>.
7472
7473
7474
7475
7476 <p>
7477 <hr><h3><a name="pdf-rawequal"><code>rawequal (v1, v2)</code></a></h3>
7478 Checks whether <code>v1</code> is equal to <code>v2</code>,
7479 without invoking the <code>__eq</code> metamethod.
7480 Returns a boolean.
7481
7482
7483
7484
7485 <p>
7486 <hr><h3><a name="pdf-rawget"><code>rawget (table, index)</code></a></h3>
7487 Gets the real value of <code>table[index]</code>,
7488 without invoking the <code>__index</code> metamethod.
7489 <code>table</code> must be a table;
7490 <code>index</code> may be any value.
7491
7492
7493
7494
7495 <p>
7496 <hr><h3><a name="pdf-rawlen"><code>rawlen (v)</code></a></h3>
7497 Returns the length of the object <code>v</code>,
7498 which must be a table or a string,
7499 without invoking the <code>__len</code> metamethod.
7500 Returns an integer.
7501
7502
7503
7504
7505 <p>
7506 <hr><h3><a name="pdf-rawset"><code>rawset (table, index, value)</code></a></h3>
7507 Sets the real value of <code>table[index]</code> to <code>value</code>,
7508 without invoking the <code>__newindex</code> metamethod.
7509 <code>table</code> must be a table,
7510 <code>index</code> any value different from <b>nil</b> and NaN,
7511 and <code>value</code> any Lua value.
7512
7513
7514 <p>
7515 This function returns <code>table</code>.
7516
7517
7518
7519
7520 <p>
7521 <hr><h3><a name="pdf-select"><code>select (index, &middot;&middot;&middot;)</code></a></h3>
7522
7523
7524 <p>
7525 If <code>index</code> is a number,
7526 returns all arguments after argument number <code>index</code>;
7527 a negative number indexes from the end (-1 is the last argument).
7528 Otherwise, <code>index</code> must be the string <code>"#"</code>,
7529 and <code>select</code> returns the total number of extra arguments it received.
7530
7531
7532
7533
7534 <p>
7535 <hr><h3><a name="pdf-setmetatable"><code>setmetatable (table, metatable)</code></a></h3>
7536
7537
7538 <p>
7539 Sets the metatable for the given table.
7540 (To change the metatable of other types from Lua code,
7541 you must use the debug library (<a href="#6.10">&sect;6.10</a>).)
7542 If <code>metatable</code> is <b>nil</b>,
7543 removes the metatable of the given table.
7544 If the original metatable has a <code>__metatable</code> field,
7545 raises an error.
7546
7547
7548 <p>
7549 This function returns <code>table</code>.
7550
7551
7552
7553
7554 <p>
7555 <hr><h3><a name="pdf-tonumber"><code>tonumber (e [, base])</code></a></h3>
7556
7557
7558 <p>
7559 When called with no <code>base</code>,
7560 <code>tonumber</code> tries to convert its argument to a number.
7561 If the argument is already a number or
7562 a string convertible to a number,
7563 then <code>tonumber</code> returns this number;
7564 otherwise, it returns <b>nil</b>.
7565
7566
7567 <p>
7568 The conversion of strings can result in integers or floats,
7569 according to the lexical conventions of Lua (see <a href="#3.1">&sect;3.1</a>).
7570 (The string may have leading and trailing spaces and a sign.)
7571
7572
7573 <p>
7574 When called with <code>base</code>,
7575 then <code>e</code> must be a string to be interpreted as
7576 an integer numeral in that base.
7577 The base may be any integer between 2 and 36, inclusive.
7578 In bases above&nbsp;10, the letter '<code>A</code>' (in either upper or lower case)
7579 represents&nbsp;10, '<code>B</code>' represents&nbsp;11, and so forth,
7580 with '<code>Z</code>' representing 35.
7581 If the string <code>e</code> is not a valid numeral in the given base,
7582 the function returns <b>nil</b>.
7583
7584
7585
7586
7587 <p>
7588 <hr><h3><a name="pdf-tostring"><code>tostring (v)</code></a></h3>
7589 Receives a value of any type and
7590 converts it to a string in a human-readable format.
7591 (For complete control of how numbers are converted,
7592 use <a href="#pdf-string.format"><code>string.format</code></a>.)
7593
7594
7595 <p>
7596 If the metatable of <code>v</code> has a <code>__tostring</code> field,
7597 then <code>tostring</code> calls the corresponding value
7598 with <code>v</code> as argument,
7599 and uses the result of the call as its result.
7600
7601
7602
7603
7604 <p>
7605 <hr><h3><a name="pdf-type"><code>type (v)</code></a></h3>
7606 Returns the type of its only argument, coded as a string.
7607 The possible results of this function are
7608 "<code>nil</code>" (a string, not the value <b>nil</b>),
7609 "<code>number</code>",
7610 "<code>string</code>",
7611 "<code>boolean</code>",
7612 "<code>table</code>",
7613 "<code>function</code>",
7614 "<code>thread</code>",
7615 and "<code>userdata</code>".
7616
7617
7618
7619
7620 <p>
7621 <hr><h3><a name="pdf-_VERSION"><code>_VERSION</code></a></h3>
7622
7623
7624 <p>
7625 A global variable (not a function) that
7626 holds a string containing the running Lua version.
7627 The current value of this variable is "<code>Lua 5.3</code>".
7628
7629
7630
7631
7632 <p>
7633 <hr><h3><a name="pdf-xpcall"><code>xpcall (f, msgh [, arg1, &middot;&middot;&middot;])</code></a></h3>
7634
7635
7636 <p>
7637 This function is similar to <a href="#pdf-pcall"><code>pcall</code></a>,
7638 except that it sets a new message handler <code>msgh</code>.
7639
7640
7641
7642
7643
7644
7645
7646 <h2>6.2 &ndash; <a name="6.2">Coroutine Manipulation</a></h2>
7647
7648 <p>
7649 This library comprises the operations to manipulate coroutines,
7650 which come inside the table <a name="pdf-coroutine"><code>coroutine</code></a>.
7651 See <a href="#2.6">&sect;2.6</a> for a general description of coroutines.
7652
7653
7654 <p>
7655 <hr><h3><a name="pdf-coroutine.create"><code>coroutine.create (f)</code></a></h3>
7656
7657
7658 <p>
7659 Creates a new coroutine, with body <code>f</code>.
7660 <code>f</code> must be a function.
7661 Returns this new coroutine,
7662 an object with type <code>"thread"</code>.
7663
7664
7665
7666
7667 <p>
7668 <hr><h3><a name="pdf-coroutine.isyieldable"><code>coroutine.isyieldable ()</code></a></h3>
7669
7670
7671 <p>
7672 Returns true when the running coroutine can yield.
7673
7674
7675 <p>
7676 A running coroutine is yieldable if it is not the main thread and
7677 it is not inside a non-yieldable C function.
7678
7679
7680
7681
7682 <p>
7683 <hr><h3><a name="pdf-coroutine.resume"><code>coroutine.resume (co [, val1, &middot;&middot;&middot;])</code></a></h3>
7684
7685
7686 <p>
7687 Starts or continues the execution of coroutine <code>co</code>.
7688 The first time you resume a coroutine,
7689 it starts running its body.
7690 The values <code>val1</code>, ... are passed
7691 as the arguments to the body function.
7692 If the coroutine has yielded,
7693 <code>resume</code> restarts it;
7694 the values <code>val1</code>, ... are passed
7695 as the results from the yield.
7696
7697
7698 <p>
7699 If the coroutine runs without any errors,
7700 <code>resume</code> returns <b>true</b> plus any values passed to <code>yield</code>
7701 (when the coroutine yields) or any values returned by the body function
7702 (when the coroutine terminates).
7703 If there is any error,
7704 <code>resume</code> returns <b>false</b> plus the error message.
7705
7706
7707
7708
7709 <p>
7710 <hr><h3><a name="pdf-coroutine.running"><code>coroutine.running ()</code></a></h3>
7711
7712
7713 <p>
7714 Returns the running coroutine plus a boolean,
7715 true when the running coroutine is the main one.
7716
7717
7718
7719
7720 <p>
7721 <hr><h3><a name="pdf-coroutine.status"><code>coroutine.status (co)</code></a></h3>
7722
7723
7724 <p>
7725 Returns the status of coroutine <code>co</code>, as a string:
7726 <code>"running"</code>,
7727 if the coroutine is running (that is, it called <code>status</code>);
7728 <code>"suspended"</code>, if the coroutine is suspended in a call to <code>yield</code>,
7729 or if it has not started running yet;
7730 <code>"normal"</code> if the coroutine is active but not running
7731 (that is, it has resumed another coroutine);
7732 and <code>"dead"</code> if the coroutine has finished its body function,
7733 or if it has stopped with an error.
7734
7735
7736
7737
7738 <p>
7739 <hr><h3><a name="pdf-coroutine.wrap"><code>coroutine.wrap (f)</code></a></h3>
7740
7741
7742 <p>
7743 Creates a new coroutine, with body <code>f</code>.
7744 <code>f</code> must be a function.
7745 Returns a function that resumes the coroutine each time it is called.
7746 Any arguments passed to the function behave as the
7747 extra arguments to <code>resume</code>.
7748 Returns the same values returned by <code>resume</code>,
7749 except the first boolean.
7750 In case of error, propagates the error.
7751
7752
7753
7754
7755 <p>
7756 <hr><h3><a name="pdf-coroutine.yield"><code>coroutine.yield (&middot;&middot;&middot;)</code></a></h3>
7757
7758
7759 <p>
7760 Suspends the execution of the calling coroutine.
7761 Any arguments to <code>yield</code> are passed as extra results to <code>resume</code>.
7762
7763
7764
7765
7766
7767
7768
7769 <h2>6.3 &ndash; <a name="6.3">Modules</a></h2>
7770
7771 <p>
7772 The package library provides basic
7773 facilities for loading modules in Lua.
7774 It exports one function directly in the global environment:
7775 <a href="#pdf-require"><code>require</code></a>.
7776 Everything else is exported in a table <a name="pdf-package"><code>package</code></a>.
7777
7778
7779 <p>
7780 <hr><h3><a name="pdf-require"><code>require (modname)</code></a></h3>
7781
7782
7783 <p>
7784 Loads the given module.
7785 The function starts by looking into the <a href="#pdf-package.loaded"><code>package.loaded</code></a> table
7786 to determine whether <code>modname</code> is already loaded.
7787 If it is, then <code>require</code> returns the value stored
7788 at <code>package.loaded[modname]</code>.
7789 Otherwise, it tries to find a <em>loader</em> for the module.
7790
7791
7792 <p>
7793 To find a loader,
7794 <code>require</code> is guided by the <a href="#pdf-package.searchers"><code>package.searchers</code></a> sequence.
7795 By changing this sequence,
7796 we can change how <code>require</code> looks for a module.
7797 The following explanation is based on the default configuration
7798 for <a href="#pdf-package.searchers"><code>package.searchers</code></a>.
7799
7800
7801 <p>
7802 First <code>require</code> queries <code>package.preload[modname]</code>.
7803 If it has a value,
7804 this value (which must be a function) is the loader.
7805 Otherwise <code>require</code> searches for a Lua loader using the
7806 path stored in <a href="#pdf-package.path"><code>package.path</code></a>.
7807 If that also fails, it searches for a C&nbsp;loader using the
7808 path stored in <a href="#pdf-package.cpath"><code>package.cpath</code></a>.
7809 If that also fails,
7810 it tries an <em>all-in-one</em> loader (see <a href="#pdf-package.searchers"><code>package.searchers</code></a>).
7811
7812
7813 <p>
7814 Once a loader is found,
7815 <code>require</code> calls the loader with two arguments:
7816 <code>modname</code> and an extra value dependent on how it got the loader.
7817 (If the loader came from a file,
7818 this extra value is the file name.)
7819 If the loader returns any non-nil value,
7820 <code>require</code> assigns the returned value to <code>package.loaded[modname]</code>.
7821 If the loader does not return a non-nil value and
7822 has not assigned any value to <code>package.loaded[modname]</code>,
7823 then <code>require</code> assigns <b>true</b> to this entry.
7824 In any case, <code>require</code> returns the
7825 final value of <code>package.loaded[modname]</code>.
7826
7827
7828 <p>
7829 If there is any error loading or running the module,
7830 or if it cannot find any loader for the module,
7831 then <code>require</code> raises an error.
7832
7833
7834
7835
7836 <p>
7837 <hr><h3><a name="pdf-package.config"><code>package.config</code></a></h3>
7838
7839
7840 <p>
7841 A string describing some compile-time configurations for packages.
7842 This string is a sequence of lines:
7843
7844 <ul>
7845
7846 <li>The first line is the directory separator string.
7847 Default is '<code>\</code>' for Windows and '<code>/</code>' for all other systems.</li>
7848
7849 <li>The second line is the character that separates templates in a path.
7850 Default is '<code>;</code>'.</li>
7851
7852 <li>The third line is the string that marks the
7853 substitution points in a template.
7854 Default is '<code>?</code>'.</li>
7855
7856 <li>The fourth line is a string that, in a path in Windows,
7857 is replaced by the executable's directory.
7858 Default is '<code>!</code>'.</li>
7859
7860 <li>The fifth line is a mark to ignore all text after it
7861 when building the <code>luaopen_</code> function name.
7862 Default is '<code>-</code>'.</li>
7863
7864 </ul>
7865
7866
7867
7868 <p>
7869 <hr><h3><a name="pdf-package.cpath"><code>package.cpath</code></a></h3>
7870
7871
7872 <p>
7873 The path used by <a href="#pdf-require"><code>require</code></a> to search for a C&nbsp;loader.
7874
7875
7876 <p>
7877 Lua initializes the C&nbsp;path <a href="#pdf-package.cpath"><code>package.cpath</code></a> in the same way
7878 it initializes the Lua path <a href="#pdf-package.path"><code>package.path</code></a>,
7879 using the environment variable <a name="pdf-LUA_CPATH_5_3"><code>LUA_CPATH_5_3</code></a>
7880 or the environment variable <a name="pdf-LUA_CPATH"><code>LUA_CPATH</code></a>
7881 or a default path defined in <code>luaconf.h</code>.
7882
7883
7884
7885
7886 <p>
7887 <hr><h3><a name="pdf-package.loaded"><code>package.loaded</code></a></h3>
7888
7889
7890 <p>
7891 A table used by <a href="#pdf-require"><code>require</code></a> to control which
7892 modules are already loaded.
7893 When you require a module <code>modname</code> and
7894 <code>package.loaded[modname]</code> is not false,
7895 <a href="#pdf-require"><code>require</code></a> simply returns the value stored there.
7896
7897
7898 <p>
7899 This variable is only a reference to the real table;
7900 assignments to this variable do not change the
7901 table used by <a href="#pdf-require"><code>require</code></a>.
7902
7903
7904
7905
7906 <p>
7907 <hr><h3><a name="pdf-package.loadlib"><code>package.loadlib (libname, funcname)</code></a></h3>
7908
7909
7910 <p>
7911 Dynamically links the host program with the C&nbsp;library <code>libname</code>.
7912
7913
7914 <p>
7915 If <code>funcname</code> is "<code>*</code>",
7916 then it only links with the library,
7917 making the symbols exported by the library
7918 available to other dynamically linked libraries.
7919 Otherwise,
7920 it looks for a function <code>funcname</code> inside the library
7921 and returns this function as a C&nbsp;function.
7922 So, <code>funcname</code> must follow the <a href="#lua_CFunction"><code>lua_CFunction</code></a> prototype
7923 (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>).
7924
7925
7926 <p>
7927 This is a low-level function.
7928 It completely bypasses the package and module system.
7929 Unlike <a href="#pdf-require"><code>require</code></a>,
7930 it does not perform any path searching and
7931 does not automatically adds extensions.
7932 <code>libname</code> must be the complete file name of the C&nbsp;library,
7933 including if necessary a path and an extension.
7934 <code>funcname</code> must be the exact name exported by the C&nbsp;library
7935 (which may depend on the C&nbsp;compiler and linker used).
7936
7937
7938 <p>
7939 This function is not supported by Standard&nbsp;C.
7940 As such, it is only available on some platforms
7941 (Windows, Linux, Mac OS X, Solaris, BSD,
7942 plus other Unix systems that support the <code>dlfcn</code> standard).
7943
7944
7945
7946
7947 <p>
7948 <hr><h3><a name="pdf-package.path"><code>package.path</code></a></h3>
7949
7950
7951 <p>
7952 The path used by <a href="#pdf-require"><code>require</code></a> to search for a Lua loader.
7953
7954
7955 <p>
7956 At start-up, Lua initializes this variable with
7957 the value of the environment variable <a name="pdf-LUA_PATH_5_3"><code>LUA_PATH_5_3</code></a> or
7958 the environment variable <a name="pdf-LUA_PATH"><code>LUA_PATH</code></a> or
7959 with a default path defined in <code>luaconf.h</code>,
7960 if those environment variables are not defined.
7961 Any "<code>;;</code>" in the value of the environment variable
7962 is replaced by the default path.
7963
7964
7965
7966
7967 <p>
7968 <hr><h3><a name="pdf-package.preload"><code>package.preload</code></a></h3>
7969
7970
7971 <p>
7972 A table to store loaders for specific modules
7973 (see <a href="#pdf-require"><code>require</code></a>).
7974
7975
7976 <p>
7977 This variable is only a reference to the real table;
7978 assignments to this variable do not change the
7979 table used by <a href="#pdf-require"><code>require</code></a>.
7980
7981
7982
7983
7984 <p>
7985 <hr><h3><a name="pdf-package.searchers"><code>package.searchers</code></a></h3>
7986
7987
7988 <p>
7989 A table used by <a href="#pdf-require"><code>require</code></a> to control how to load modules.
7990
7991
7992 <p>
7993 Each entry in this table is a <em>searcher function</em>.
7994 When looking for a module,
7995 <a href="#pdf-require"><code>require</code></a> calls each of these searchers in ascending order,
7996 with the module name (the argument given to <a href="#pdf-require"><code>require</code></a>) as its
7997 sole parameter.
7998 The function can return another function (the module <em>loader</em>)
7999 plus an extra value that will be passed to that loader,
8000 or a string explaining why it did not find that module
8001 (or <b>nil</b> if it has nothing to say).
8002
8003
8004 <p>
8005 Lua initializes this table with four searcher functions.
8006
8007
8008 <p>
8009 The first searcher simply looks for a loader in the
8010 <a href="#pdf-package.preload"><code>package.preload</code></a> table.
8011
8012
8013 <p>
8014 The second searcher looks for a loader as a Lua library,
8015 using the path stored at <a href="#pdf-package.path"><code>package.path</code></a>.
8016 The search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>.
8017
8018
8019 <p>
8020 The third searcher looks for a loader as a C&nbsp;library,
8021 using the path given by the variable <a href="#pdf-package.cpath"><code>package.cpath</code></a>.
8022 Again,
8023 the search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>.
8024 For instance,
8025 if the C&nbsp;path is the string
8026
8027 <pre>
8028      "./?.so;./?.dll;/usr/local/?/init.so"
8029 </pre><p>
8030 the searcher for module <code>foo</code>
8031 will try to open the files <code>./foo.so</code>, <code>./foo.dll</code>,
8032 and <code>/usr/local/foo/init.so</code>, in that order.
8033 Once it finds a C&nbsp;library,
8034 this searcher first uses a dynamic link facility to link the
8035 application with the library.
8036 Then it tries to find a C&nbsp;function inside the library to
8037 be used as the loader.
8038 The name of this C&nbsp;function is the string "<code>luaopen_</code>"
8039 concatenated with a copy of the module name where each dot
8040 is replaced by an underscore.
8041 Moreover, if the module name has a hyphen,
8042 its suffix after (and including) the first hyphen is removed.
8043 For instance, if the module name is <code>a.b.c-v2.1</code>,
8044 the function name will be <code>luaopen_a_b_c</code>.
8045
8046
8047 <p>
8048 The fourth searcher tries an <em>all-in-one loader</em>.
8049 It searches the C&nbsp;path for a library for
8050 the root name of the given module.
8051 For instance, when requiring <code>a.b.c</code>,
8052 it will search for a C&nbsp;library for <code>a</code>.
8053 If found, it looks into it for an open function for
8054 the submodule;
8055 in our example, that would be <code>luaopen_a_b_c</code>.
8056 With this facility, a package can pack several C&nbsp;submodules
8057 into one single library,
8058 with each submodule keeping its original open function.
8059
8060
8061 <p>
8062 All searchers except the first one (preload) return as the extra value
8063 the file name where the module was found,
8064 as returned by <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>.
8065 The first searcher returns no extra value.
8066
8067
8068
8069
8070 <p>
8071 <hr><h3><a name="pdf-package.searchpath"><code>package.searchpath (name, path [, sep [, rep]])</code></a></h3>
8072
8073
8074 <p>
8075 Searches for the given <code>name</code> in the given <code>path</code>.
8076
8077
8078 <p>
8079 A path is a string containing a sequence of
8080 <em>templates</em> separated by semicolons.
8081 For each template,
8082 the function replaces each interrogation mark (if any)
8083 in the template with a copy of <code>name</code>
8084 wherein all occurrences of <code>sep</code>
8085 (a dot, by default)
8086 were replaced by <code>rep</code>
8087 (the system's directory separator, by default),
8088 and then tries to open the resulting file name.
8089
8090
8091 <p>
8092 For instance, if the path is the string
8093
8094 <pre>
8095      "./?.lua;./?.lc;/usr/local/?/init.lua"
8096 </pre><p>
8097 the search for the name <code>foo.a</code>
8098 will try to open the files
8099 <code>./foo/a.lua</code>, <code>./foo/a.lc</code>, and
8100 <code>/usr/local/foo/a/init.lua</code>, in that order.
8101
8102
8103 <p>
8104 Returns the resulting name of the first file that it can
8105 open in read mode (after closing the file),
8106 or <b>nil</b> plus an error message if none succeeds.
8107 (This error message lists all file names it tried to open.)
8108
8109
8110
8111
8112
8113
8114
8115 <h2>6.4 &ndash; <a name="6.4">String Manipulation</a></h2>
8116
8117 <p>
8118 This library provides generic functions for string manipulation,
8119 such as finding and extracting substrings, and pattern matching.
8120 When indexing a string in Lua, the first character is at position&nbsp;1
8121 (not at&nbsp;0, as in C).
8122 Indices are allowed to be negative and are interpreted as indexing backwards,
8123 from the end of the string.
8124 Thus, the last character is at position -1, and so on.
8125
8126
8127 <p>
8128 The string library provides all its functions inside the table
8129 <a name="pdf-string"><code>string</code></a>.
8130 It also sets a metatable for strings
8131 where the <code>__index</code> field points to the <code>string</code> table.
8132 Therefore, you can use the string functions in object-oriented style.
8133 For instance, <code>string.byte(s,i)</code>
8134 can be written as <code>s:byte(i)</code>.
8135
8136
8137 <p>
8138 The string library assumes one-byte character encodings.
8139
8140
8141 <p>
8142 <hr><h3><a name="pdf-string.byte"><code>string.byte (s [, i [, j]])</code></a></h3>
8143 Returns the internal numeric codes of the characters <code>s[i]</code>,
8144 <code>s[i+1]</code>, ..., <code>s[j]</code>.
8145 The default value for <code>i</code> is&nbsp;1;
8146 the default value for <code>j</code> is&nbsp;<code>i</code>.
8147 These indices are corrected
8148 following the same rules of function <a href="#pdf-string.sub"><code>string.sub</code></a>.
8149
8150
8151 <p>
8152 Numeric codes are not necessarily portable across platforms.
8153
8154
8155
8156
8157 <p>
8158 <hr><h3><a name="pdf-string.char"><code>string.char (&middot;&middot;&middot;)</code></a></h3>
8159 Receives zero or more integers.
8160 Returns a string with length equal to the number of arguments,
8161 in which each character has the internal numeric code equal
8162 to its corresponding argument.
8163
8164
8165 <p>
8166 Numeric codes are not necessarily portable across platforms.
8167
8168
8169
8170
8171 <p>
8172 <hr><h3><a name="pdf-string.dump"><code>string.dump (function [, strip])</code></a></h3>
8173
8174
8175 <p>
8176 Returns a string containing a binary representation
8177 (a <em>binary chunk</em>)
8178 of the given function,
8179 so that a later <a href="#pdf-load"><code>load</code></a> on this string returns
8180 a copy of the function (but with new upvalues).
8181 If <code>strip</code> is a true value,
8182 the binary representation may not include all debug information
8183 about the function,
8184 to save space.
8185
8186
8187 <p>
8188 Functions with upvalues have only their number of upvalues saved.
8189 When (re)loaded,
8190 those upvalues receive fresh instances containing <b>nil</b>.
8191 (You can use the debug library to serialize
8192 and reload the upvalues of a function
8193 in a way adequate to your needs.)
8194
8195
8196
8197
8198 <p>
8199 <hr><h3><a name="pdf-string.find"><code>string.find (s, pattern [, init [, plain]])</code></a></h3>
8200
8201
8202 <p>
8203 Looks for the first match of
8204 <code>pattern</code> (see <a href="#6.4.1">&sect;6.4.1</a>) in the string <code>s</code>.
8205 If it finds a match, then <code>find</code> returns the indices of&nbsp;<code>s</code>
8206 where this occurrence starts and ends;
8207 otherwise, it returns <b>nil</b>.
8208 A third, optional numeric argument <code>init</code> specifies
8209 where to start the search;
8210 its default value is&nbsp;1 and can be negative.
8211 A value of <b>true</b> as a fourth, optional argument <code>plain</code>
8212 turns off the pattern matching facilities,
8213 so the function does a plain "find substring" operation,
8214 with no characters in <code>pattern</code> being considered magic.
8215 Note that if <code>plain</code> is given, then <code>init</code> must be given as well.
8216
8217
8218 <p>
8219 If the pattern has captures,
8220 then in a successful match
8221 the captured values are also returned,
8222 after the two indices.
8223
8224
8225
8226
8227 <p>
8228 <hr><h3><a name="pdf-string.format"><code>string.format (formatstring, &middot;&middot;&middot;)</code></a></h3>
8229
8230
8231 <p>
8232 Returns a formatted version of its variable number of arguments
8233 following the description given in its first argument (which must be a string).
8234 The format string follows the same rules as the ISO&nbsp;C function <code>sprintf</code>.
8235 The only differences are that the options/modifiers
8236 <code>*</code>, <code>h</code>, <code>L</code>, <code>l</code>, <code>n</code>,
8237 and <code>p</code> are not supported
8238 and that there is an extra option, <code>q</code>.
8239
8240
8241 <p>
8242 The <code>q</code> option formats a string between double quotes,
8243 using escape sequences when necessary to ensure that
8244 it can safely be read back by the Lua interpreter.
8245 For instance, the call
8246
8247 <pre>
8248      string.format('%q', 'a string with "quotes" and \n new line')
8249 </pre><p>
8250 may produce the string:
8251
8252 <pre>
8253      "a string with \"quotes\" and \
8254       new line"
8255 </pre>
8256
8257 <p>
8258 Options
8259 <code>A</code>, <code>a</code>, <code>E</code>, <code>e</code>, <code>f</code>,
8260 <code>G</code>, and <code>g</code> all expect a number as argument.
8261 Options <code>c</code>, <code>d</code>,
8262 <code>i</code>, <code>o</code>, <code>u</code>, <code>X</code>, and <code>x</code>
8263 expect an integer.
8264 When Lua is compiled with a C89 compiler,
8265 options <code>A</code> and <code>a</code> (hexadecimal floats)
8266 do not support any modifier (flags, width, length).
8267
8268
8269 <p>
8270 Option <code>s</code> expects a string;
8271 if its argument is not a string,
8272 it is converted to one following the same rules of <a href="#pdf-tostring"><code>tostring</code></a>.
8273 If the option has any modifier (flags, width, length),
8274 the string argument should not contain embedded zeros.
8275
8276
8277
8278
8279 <p>
8280 <hr><h3><a name="pdf-string.gmatch"><code>string.gmatch (s, pattern)</code></a></h3>
8281 Returns an iterator function that,
8282 each time it is called,
8283 returns the next captures from <code>pattern</code> (see <a href="#6.4.1">&sect;6.4.1</a>)
8284 over the string <code>s</code>.
8285 If <code>pattern</code> specifies no captures,
8286 then the whole match is produced in each call.
8287
8288
8289 <p>
8290 As an example, the following loop
8291 will iterate over all the words from string <code>s</code>,
8292 printing one per line:
8293
8294 <pre>
8295      s = "hello world from Lua"
8296      for w in string.gmatch(s, "%a+") do
8297        print(w)
8298      end
8299 </pre><p>
8300 The next example collects all pairs <code>key=value</code> from the
8301 given string into a table:
8302
8303 <pre>
8304      t = {}
8305      s = "from=world, to=Lua"
8306      for k, v in string.gmatch(s, "(%w+)=(%w+)") do
8307        t[k] = v
8308      end
8309 </pre>
8310
8311 <p>
8312 For this function, a caret '<code>^</code>' at the start of a pattern does not
8313 work as an anchor, as this would prevent the iteration.
8314
8315
8316
8317
8318 <p>
8319 <hr><h3><a name="pdf-string.gsub"><code>string.gsub (s, pattern, repl [, n])</code></a></h3>
8320 Returns a copy of <code>s</code>
8321 in which all (or the first <code>n</code>, if given)
8322 occurrences of the <code>pattern</code> (see <a href="#6.4.1">&sect;6.4.1</a>) have been
8323 replaced by a replacement string specified by <code>repl</code>,
8324 which can be a string, a table, or a function.
8325 <code>gsub</code> also returns, as its second value,
8326 the total number of matches that occurred.
8327 The name <code>gsub</code> comes from <em>Global SUBstitution</em>.
8328
8329
8330 <p>
8331 If <code>repl</code> is a string, then its value is used for replacement.
8332 The character&nbsp;<code>%</code> works as an escape character:
8333 any sequence in <code>repl</code> of the form <code>%<em>d</em></code>,
8334 with <em>d</em> between 1 and 9,
8335 stands for the value of the <em>d</em>-th captured substring.
8336 The sequence <code>%0</code> stands for the whole match.
8337 The sequence <code>%%</code> stands for a single&nbsp;<code>%</code>.
8338
8339
8340 <p>
8341 If <code>repl</code> is a table, then the table is queried for every match,
8342 using the first capture as the key.
8343
8344
8345 <p>
8346 If <code>repl</code> is a function, then this function is called every time a
8347 match occurs, with all captured substrings passed as arguments,
8348 in order.
8349
8350
8351 <p>
8352 In any case,
8353 if the pattern specifies no captures,
8354 then it behaves as if the whole pattern was inside a capture.
8355
8356
8357 <p>
8358 If the value returned by the table query or by the function call
8359 is a string or a number,
8360 then it is used as the replacement string;
8361 otherwise, if it is <b>false</b> or <b>nil</b>,
8362 then there is no replacement
8363 (that is, the original match is kept in the string).
8364
8365
8366 <p>
8367 Here are some examples:
8368
8369 <pre>
8370      x = string.gsub("hello world", "(%w+)", "%1 %1")
8371      --&gt; x="hello hello world world"
8372
8373      x = string.gsub("hello world", "%w+", "%0 %0", 1)
8374      --&gt; x="hello hello world"
8375
8376      x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1")
8377      --&gt; x="world hello Lua from"
8378
8379      x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv)
8380      --&gt; x="home = /home/roberto, user = roberto"
8381
8382      x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s)
8383            return load(s)()
8384          end)
8385      --&gt; x="4+5 = 9"
8386
8387      local t = {name="lua", version="5.3"}
8388      x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t)
8389      --&gt; x="lua-5.3.tar.gz"
8390 </pre>
8391
8392
8393
8394 <p>
8395 <hr><h3><a name="pdf-string.len"><code>string.len (s)</code></a></h3>
8396 Receives a string and returns its length.
8397 The empty string <code>""</code> has length 0.
8398 Embedded zeros are counted,
8399 so <code>"a\000bc\000"</code> has length 5.
8400
8401
8402
8403
8404 <p>
8405 <hr><h3><a name="pdf-string.lower"><code>string.lower (s)</code></a></h3>
8406 Receives a string and returns a copy of this string with all
8407 uppercase letters changed to lowercase.
8408 All other characters are left unchanged.
8409 The definition of what an uppercase letter is depends on the current locale.
8410
8411
8412
8413
8414 <p>
8415 <hr><h3><a name="pdf-string.match"><code>string.match (s, pattern [, init])</code></a></h3>
8416 Looks for the first <em>match</em> of
8417 <code>pattern</code> (see <a href="#6.4.1">&sect;6.4.1</a>) in the string <code>s</code>.
8418 If it finds one, then <code>match</code> returns
8419 the captures from the pattern;
8420 otherwise it returns <b>nil</b>.
8421 If <code>pattern</code> specifies no captures,
8422 then the whole match is returned.
8423 A third, optional numeric argument <code>init</code> specifies
8424 where to start the search;
8425 its default value is&nbsp;1 and can be negative.
8426
8427
8428
8429
8430 <p>
8431 <hr><h3><a name="pdf-string.pack"><code>string.pack (fmt, v1, v2, &middot;&middot;&middot;)</code></a></h3>
8432
8433
8434 <p>
8435 Returns a binary string containing the values <code>v1</code>, <code>v2</code>, etc.
8436 packed (that is, serialized in binary form)
8437 according to the format string <code>fmt</code> (see <a href="#6.4.2">&sect;6.4.2</a>).
8438
8439
8440
8441
8442 <p>
8443 <hr><h3><a name="pdf-string.packsize"><code>string.packsize (fmt)</code></a></h3>
8444
8445
8446 <p>
8447 Returns the size of a string resulting from <a href="#pdf-string.pack"><code>string.pack</code></a>
8448 with the given format.
8449 The format string cannot have the variable-length options
8450 '<code>s</code>' or '<code>z</code>' (see <a href="#6.4.2">&sect;6.4.2</a>).
8451
8452
8453
8454
8455 <p>
8456 <hr><h3><a name="pdf-string.rep"><code>string.rep (s, n [, sep])</code></a></h3>
8457 Returns a string that is the concatenation of <code>n</code> copies of
8458 the string <code>s</code> separated by the string <code>sep</code>.
8459 The default value for <code>sep</code> is the empty string
8460 (that is, no separator).
8461 Returns the empty string if <code>n</code> is not positive.
8462
8463
8464 <p>
8465 (Note that it is very easy to exhaust the memory of your machine
8466 with a single call to this function.)
8467
8468
8469
8470
8471 <p>
8472 <hr><h3><a name="pdf-string.reverse"><code>string.reverse (s)</code></a></h3>
8473 Returns a string that is the string <code>s</code> reversed.
8474
8475
8476
8477
8478 <p>
8479 <hr><h3><a name="pdf-string.sub"><code>string.sub (s, i [, j])</code></a></h3>
8480 Returns the substring of <code>s</code> that
8481 starts at <code>i</code>  and continues until <code>j</code>;
8482 <code>i</code> and <code>j</code> can be negative.
8483 If <code>j</code> is absent, then it is assumed to be equal to -1
8484 (which is the same as the string length).
8485 In particular,
8486 the call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code>
8487 with length <code>j</code>,
8488 and <code>string.sub(s, -i)</code> returns a suffix of <code>s</code>
8489 with length <code>i</code>.
8490
8491
8492 <p>
8493 If, after the translation of negative indices,
8494 <code>i</code> is less than 1,
8495 it is corrected to 1.
8496 If <code>j</code> is greater than the string length,
8497 it is corrected to that length.
8498 If, after these corrections,
8499 <code>i</code> is greater than <code>j</code>,
8500 the function returns the empty string.
8501
8502
8503
8504
8505 <p>
8506 <hr><h3><a name="pdf-string.unpack"><code>string.unpack (fmt, s [, pos])</code></a></h3>
8507
8508
8509 <p>
8510 Returns the values packed in string <code>s</code> (see <a href="#pdf-string.pack"><code>string.pack</code></a>)
8511 according to the format string <code>fmt</code> (see <a href="#6.4.2">&sect;6.4.2</a>).
8512 An optional <code>pos</code> marks where
8513 to start reading in <code>s</code> (default is 1).
8514 After the read values,
8515 this function also returns the index of the first unread byte in <code>s</code>.
8516
8517
8518
8519
8520 <p>
8521 <hr><h3><a name="pdf-string.upper"><code>string.upper (s)</code></a></h3>
8522 Receives a string and returns a copy of this string with all
8523 lowercase letters changed to uppercase.
8524 All other characters are left unchanged.
8525 The definition of what a lowercase letter is depends on the current locale.
8526
8527
8528
8529
8530
8531 <h3>6.4.1 &ndash; <a name="6.4.1">Patterns</a></h3>
8532
8533 <p>
8534 Patterns in Lua are described by regular strings,
8535 which are interpreted as patterns by the pattern-matching functions
8536 <a href="#pdf-string.find"><code>string.find</code></a>,
8537 <a href="#pdf-string.gmatch"><code>string.gmatch</code></a>,
8538 <a href="#pdf-string.gsub"><code>string.gsub</code></a>,
8539 and <a href="#pdf-string.match"><code>string.match</code></a>.
8540 This section describes the syntax and the meaning
8541 (that is, what they match) of these strings.
8542
8543
8544
8545 <h4>Character Class:</h4><p>
8546 A <em>character class</em> is used to represent a set of characters.
8547 The following combinations are allowed in describing a character class:
8548
8549 <ul>
8550
8551 <li><b><em>x</em>: </b>
8552 (where <em>x</em> is not one of the <em>magic characters</em>
8553 <code>^$()%.[]*+-?</code>)
8554 represents the character <em>x</em> itself.
8555 </li>
8556
8557 <li><b><code>.</code>: </b> (a dot) represents all characters.</li>
8558
8559 <li><b><code>%a</code>: </b> represents all letters.</li>
8560
8561 <li><b><code>%c</code>: </b> represents all control characters.</li>
8562
8563 <li><b><code>%d</code>: </b> represents all digits.</li>
8564
8565 <li><b><code>%g</code>: </b> represents all printable characters except space.</li>
8566
8567 <li><b><code>%l</code>: </b> represents all lowercase letters.</li>
8568
8569 <li><b><code>%p</code>: </b> represents all punctuation characters.</li>
8570
8571 <li><b><code>%s</code>: </b> represents all space characters.</li>
8572
8573 <li><b><code>%u</code>: </b> represents all uppercase letters.</li>
8574
8575 <li><b><code>%w</code>: </b> represents all alphanumeric characters.</li>
8576
8577 <li><b><code>%x</code>: </b> represents all hexadecimal digits.</li>
8578
8579 <li><b><code>%<em>x</em></code>: </b> (where <em>x</em> is any non-alphanumeric character)
8580 represents the character <em>x</em>.
8581 This is the standard way to escape the magic characters.
8582 Any non-alphanumeric character
8583 (including all punctuation characters, even the non-magical)
8584 can be preceded by a '<code>%</code>'
8585 when used to represent itself in a pattern.
8586 </li>
8587
8588 <li><b><code>[<em>set</em>]</code>: </b>
8589 represents the class which is the union of all
8590 characters in <em>set</em>.
8591 A range of characters can be specified by
8592 separating the end characters of the range,
8593 in ascending order, with a '<code>-</code>'.
8594 All classes <code>%</code><em>x</em> described above can also be used as
8595 components in <em>set</em>.
8596 All other characters in <em>set</em> represent themselves.
8597 For example, <code>[%w_]</code> (or <code>[_%w]</code>)
8598 represents all alphanumeric characters plus the underscore,
8599 <code>[0-7]</code> represents the octal digits,
8600 and <code>[0-7%l%-]</code> represents the octal digits plus
8601 the lowercase letters plus the '<code>-</code>' character.
8602
8603
8604 <p>
8605 You can put a closing square bracket in a set
8606 by positioning it as the first character in the set.
8607 You can put an hyphen in a set
8608 by positioning it as the first or the last character in the set.
8609 (You can also use an escape for both cases.)
8610
8611
8612 <p>
8613 The interaction between ranges and classes is not defined.
8614 Therefore, patterns like <code>[%a-z]</code> or <code>[a-%%]</code>
8615 have no meaning.
8616 </li>
8617
8618 <li><b><code>[^<em>set</em>]</code>: </b>
8619 represents the complement of <em>set</em>,
8620 where <em>set</em> is interpreted as above.
8621 </li>
8622
8623 </ul><p>
8624 For all classes represented by single letters (<code>%a</code>, <code>%c</code>, etc.),
8625 the corresponding uppercase letter represents the complement of the class.
8626 For instance, <code>%S</code> represents all non-space characters.
8627
8628
8629 <p>
8630 The definitions of letter, space, and other character groups
8631 depend on the current locale.
8632 In particular, the class <code>[a-z]</code> may not be equivalent to <code>%l</code>.
8633
8634
8635
8636
8637
8638 <h4>Pattern Item:</h4><p>
8639 A <em>pattern item</em> can be
8640
8641 <ul>
8642
8643 <li>
8644 a single character class,
8645 which matches any single character in the class;
8646 </li>
8647
8648 <li>
8649 a single character class followed by '<code>*</code>',
8650 which matches zero or more repetitions of characters in the class.
8651 These repetition items will always match the longest possible sequence;
8652 </li>
8653
8654 <li>
8655 a single character class followed by '<code>+</code>',
8656 which matches one or more repetitions of characters in the class.
8657 These repetition items will always match the longest possible sequence;
8658 </li>
8659
8660 <li>
8661 a single character class followed by '<code>-</code>',
8662 which also matches zero or more repetitions of characters in the class.
8663 Unlike '<code>*</code>',
8664 these repetition items will always match the shortest possible sequence;
8665 </li>
8666
8667 <li>
8668 a single character class followed by '<code>?</code>',
8669 which matches zero or one occurrence of a character in the class.
8670 It always matches one occurrence if possible;
8671 </li>
8672
8673 <li>
8674 <code>%<em>n</em></code>, for <em>n</em> between 1 and 9;
8675 such item matches a substring equal to the <em>n</em>-th captured string
8676 (see below);
8677 </li>
8678
8679 <li>
8680 <code>%b<em>xy</em></code>, where <em>x</em> and <em>y</em> are two distinct characters;
8681 such item matches strings that start with&nbsp;<em>x</em>, end with&nbsp;<em>y</em>,
8682 and where the <em>x</em> and <em>y</em> are <em>balanced</em>.
8683 This means that, if one reads the string from left to right,
8684 counting <em>+1</em> for an <em>x</em> and <em>-1</em> for a <em>y</em>,
8685 the ending <em>y</em> is the first <em>y</em> where the count reaches 0.
8686 For instance, the item <code>%b()</code> matches expressions with
8687 balanced parentheses.
8688 </li>
8689
8690 <li>
8691 <code>%f[<em>set</em>]</code>, a <em>frontier pattern</em>;
8692 such item matches an empty string at any position such that
8693 the next character belongs to <em>set</em>
8694 and the previous character does not belong to <em>set</em>.
8695 The set <em>set</em> is interpreted as previously described.
8696 The beginning and the end of the subject are handled as if
8697 they were the character '<code>\0</code>'.
8698 </li>
8699
8700 </ul>
8701
8702
8703
8704
8705 <h4>Pattern:</h4><p>
8706 A <em>pattern</em> is a sequence of pattern items.
8707 A caret '<code>^</code>' at the beginning of a pattern anchors the match at the
8708 beginning of the subject string.
8709 A '<code>$</code>' at the end of a pattern anchors the match at the
8710 end of the subject string.
8711 At other positions,
8712 '<code>^</code>' and '<code>$</code>' have no special meaning and represent themselves.
8713
8714
8715
8716
8717
8718 <h4>Captures:</h4><p>
8719 A pattern can contain sub-patterns enclosed in parentheses;
8720 they describe <em>captures</em>.
8721 When a match succeeds, the substrings of the subject string
8722 that match captures are stored (<em>captured</em>) for future use.
8723 Captures are numbered according to their left parentheses.
8724 For instance, in the pattern <code>"(a*(.)%w(%s*))"</code>,
8725 the part of the string matching <code>"a*(.)%w(%s*)"</code> is
8726 stored as the first capture (and therefore has number&nbsp;1);
8727 the character matching "<code>.</code>" is captured with number&nbsp;2,
8728 and the part matching "<code>%s*</code>" has number&nbsp;3.
8729
8730
8731 <p>
8732 As a special case, the empty capture <code>()</code> captures
8733 the current string position (a number).
8734 For instance, if we apply the pattern <code>"()aa()"</code> on the
8735 string <code>"flaaap"</code>, there will be two captures: 3&nbsp;and&nbsp;5.
8736
8737
8738
8739
8740
8741
8742
8743 <h3>6.4.2 &ndash; <a name="6.4.2">Format Strings for Pack and Unpack</a></h3>
8744
8745 <p>
8746 The first argument to <a href="#pdf-string.pack"><code>string.pack</code></a>,
8747 <a href="#pdf-string.packsize"><code>string.packsize</code></a>, and <a href="#pdf-string.unpack"><code>string.unpack</code></a>
8748 is a format string,
8749 which describes the layout of the structure being created or read.
8750
8751
8752 <p>
8753 A format string is a sequence of conversion options.
8754 The conversion options are as follows:
8755
8756 <ul>
8757 <li><b><code>&lt;</code>: </b>sets little endian</li>
8758 <li><b><code>&gt;</code>: </b>sets big endian</li>
8759 <li><b><code>=</code>: </b>sets native endian</li>
8760 <li><b><code>![<em>n</em>]</code>: </b>sets maximum alignment to <code>n</code>
8761 (default is native alignment)</li>
8762 <li><b><code>b</code>: </b>a signed byte (<code>char</code>)</li>
8763 <li><b><code>B</code>: </b>an unsigned byte (<code>char</code>)</li>
8764 <li><b><code>h</code>: </b>a signed <code>short</code> (native size)</li>
8765 <li><b><code>H</code>: </b>an unsigned <code>short</code> (native size)</li>
8766 <li><b><code>l</code>: </b>a signed <code>long</code> (native size)</li>
8767 <li><b><code>L</code>: </b>an unsigned <code>long</code> (native size)</li>
8768 <li><b><code>j</code>: </b>a <code>lua_Integer</code></li>
8769 <li><b><code>J</code>: </b>a <code>lua_Unsigned</code></li>
8770 <li><b><code>T</code>: </b>a <code>size_t</code> (native size)</li>
8771 <li><b><code>i[<em>n</em>]</code>: </b>a signed <code>int</code> with <code>n</code> bytes
8772 (default is native size)</li>
8773 <li><b><code>I[<em>n</em>]</code>: </b>an unsigned <code>int</code> with <code>n</code> bytes
8774 (default is native size)</li>
8775 <li><b><code>f</code>: </b>a <code>float</code> (native size)</li>
8776 <li><b><code>d</code>: </b>a <code>double</code> (native size)</li>
8777 <li><b><code>n</code>: </b>a <code>lua_Number</code></li>
8778 <li><b><code>c<em>n</em></code>: </b>a fixed-sized string with <code>n</code> bytes</li>
8779 <li><b><code>z</code>: </b>a zero-terminated string</li>
8780 <li><b><code>s[<em>n</em>]</code>: </b>a string preceded by its length
8781 coded as an unsigned integer with <code>n</code> bytes
8782 (default is a <code>size_t</code>)</li>
8783 <li><b><code>x</code>: </b>one byte of padding</li>
8784 <li><b><code>X<em>op</em></code>: </b>an empty item that aligns
8785 according to option <code>op</code>
8786 (which is otherwise ignored)</li>
8787 <li><b>'<code> </code>': </b>(empty space) ignored</li>
8788 </ul><p>
8789 (A "<code>[<em>n</em>]</code>" means an optional integral numeral.)
8790 Except for padding, spaces, and configurations
8791 (options "<code>xX &lt;=&gt;!</code>"),
8792 each option corresponds to an argument (in <a href="#pdf-string.pack"><code>string.pack</code></a>)
8793 or a result (in <a href="#pdf-string.unpack"><code>string.unpack</code></a>).
8794
8795
8796 <p>
8797 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>",
8798 <code>n</code> can be any integer between 1 and 16.
8799 All integral options check overflows;
8800 <a href="#pdf-string.pack"><code>string.pack</code></a> checks whether the given value fits in the given size;
8801 <a href="#pdf-string.unpack"><code>string.unpack</code></a> checks whether the read value fits in a Lua integer.
8802
8803
8804 <p>
8805 Any format string starts as if prefixed by "<code>!1=</code>",
8806 that is,
8807 with maximum alignment of 1 (no alignment)
8808 and native endianness.
8809
8810
8811 <p>
8812 Alignment works as follows:
8813 For each option,
8814 the format gets extra padding until the data starts
8815 at an offset that is a multiple of the minimum between the
8816 option size and the maximum alignment;
8817 this minimum must be a power of 2.
8818 Options "<code>c</code>" and "<code>z</code>" are not aligned;
8819 option "<code>s</code>" follows the alignment of its starting integer.
8820
8821
8822 <p>
8823 All padding is filled with zeros by <a href="#pdf-string.pack"><code>string.pack</code></a>
8824 (and ignored by <a href="#pdf-string.unpack"><code>string.unpack</code></a>).
8825
8826
8827
8828
8829
8830
8831
8832 <h2>6.5 &ndash; <a name="6.5">UTF-8 Support</a></h2>
8833
8834 <p>
8835 This library provides basic support for UTF-8 encoding.
8836 It provides all its functions inside the table <a name="pdf-utf8"><code>utf8</code></a>.
8837 This library does not provide any support for Unicode other
8838 than the handling of the encoding.
8839 Any operation that needs the meaning of a character,
8840 such as character classification, is outside its scope.
8841
8842
8843 <p>
8844 Unless stated otherwise,
8845 all functions that expect a byte position as a parameter
8846 assume that the given position is either the start of a byte sequence
8847 or one plus the length of the subject string.
8848 As in the string library,
8849 negative indices count from the end of the string.
8850
8851
8852 <p>
8853 <hr><h3><a name="pdf-utf8.char"><code>utf8.char (&middot;&middot;&middot;)</code></a></h3>
8854 Receives zero or more integers,
8855 converts each one to its corresponding UTF-8 byte sequence
8856 and returns a string with the concatenation of all these sequences.
8857
8858
8859
8860
8861 <p>
8862 <hr><h3><a name="pdf-utf8.charpattern"><code>utf8.charpattern</code></a></h3>
8863 The pattern (a string, not a function) "<code>[\0-\x7F\xC2-\xF4][\x80-\xBF]*</code>"
8864 (see <a href="#6.4.1">&sect;6.4.1</a>),
8865 which matches exactly one UTF-8 byte sequence,
8866 assuming that the subject is a valid UTF-8 string.
8867
8868
8869
8870
8871 <p>
8872 <hr><h3><a name="pdf-utf8.codes"><code>utf8.codes (s)</code></a></h3>
8873
8874
8875 <p>
8876 Returns values so that the construction
8877
8878 <pre>
8879      for p, c in utf8.codes(s) do <em>body</em> end
8880 </pre><p>
8881 will iterate over all characters in string <code>s</code>,
8882 with <code>p</code> being the position (in bytes) and <code>c</code> the code point
8883 of each character.
8884 It raises an error if it meets any invalid byte sequence.
8885
8886
8887
8888
8889 <p>
8890 <hr><h3><a name="pdf-utf8.codepoint"><code>utf8.codepoint (s [, i [, j]])</code></a></h3>
8891 Returns the codepoints (as integers) from all characters in <code>s</code>
8892 that start between byte position <code>i</code> and <code>j</code> (both included).
8893 The default for <code>i</code> is 1 and for <code>j</code> is <code>i</code>.
8894 It raises an error if it meets any invalid byte sequence.
8895
8896
8897
8898
8899 <p>
8900 <hr><h3><a name="pdf-utf8.len"><code>utf8.len (s [, i [, j]])</code></a></h3>
8901 Returns the number of UTF-8 characters in string <code>s</code>
8902 that start between positions <code>i</code> and <code>j</code> (both inclusive).
8903 The default for <code>i</code> is 1 and for <code>j</code> is -1.
8904 If it finds any invalid byte sequence,
8905 returns a false value plus the position of the first invalid byte.
8906
8907
8908
8909
8910 <p>
8911 <hr><h3><a name="pdf-utf8.offset"><code>utf8.offset (s, n [, i])</code></a></h3>
8912 Returns the position (in bytes) where the encoding of the
8913 <code>n</code>-th character of <code>s</code>
8914 (counting from position <code>i</code>) starts.
8915 A negative <code>n</code> gets characters before position <code>i</code>.
8916 The default for <code>i</code> is 1 when <code>n</code> is non-negative
8917 and <code>#s + 1</code> otherwise,
8918 so that <code>utf8.offset(s, -n)</code> gets the offset of the
8919 <code>n</code>-th character from the end of the string.
8920 If the specified character is neither in the subject
8921 nor right after its end,
8922 the function returns <b>nil</b>.
8923
8924
8925 <p>
8926 As a special case,
8927 when <code>n</code> is 0 the function returns the start of the encoding
8928 of the character that contains the <code>i</code>-th byte of <code>s</code>.
8929
8930
8931 <p>
8932 This function assumes that <code>s</code> is a valid UTF-8 string.
8933
8934
8935
8936
8937
8938
8939
8940 <h2>6.6 &ndash; <a name="6.6">Table Manipulation</a></h2>
8941
8942 <p>
8943 This library provides generic functions for table manipulation.
8944 It provides all its functions inside the table <a name="pdf-table"><code>table</code></a>.
8945
8946
8947 <p>
8948 Remember that, whenever an operation needs the length of a table,
8949 the table must be a proper sequence
8950 or have a <code>__len</code> metamethod (see <a href="#3.4.7">&sect;3.4.7</a>).
8951 All functions ignore non-numeric keys
8952 in the tables given as arguments.
8953
8954
8955 <p>
8956 <hr><h3><a name="pdf-table.concat"><code>table.concat (list [, sep [, i [, j]]])</code></a></h3>
8957
8958
8959 <p>
8960 Given a list where all elements are strings or numbers,
8961 returns the string <code>list[i]..sep..list[i+1] &middot;&middot;&middot; sep..list[j]</code>.
8962 The default value for <code>sep</code> is the empty string,
8963 the default for <code>i</code> is 1,
8964 and the default for <code>j</code> is <code>#list</code>.
8965 If <code>i</code> is greater than <code>j</code>, returns the empty string.
8966
8967
8968
8969
8970 <p>
8971 <hr><h3><a name="pdf-table.insert"><code>table.insert (list, [pos,] value)</code></a></h3>
8972
8973
8974 <p>
8975 Inserts element <code>value</code> at position <code>pos</code> in <code>list</code>,
8976 shifting up the elements
8977 <code>list[pos], list[pos+1], &middot;&middot;&middot;, list[#list]</code>.
8978 The default value for <code>pos</code> is <code>#list+1</code>,
8979 so that a call <code>table.insert(t,x)</code> inserts <code>x</code> at the end
8980 of list <code>t</code>.
8981
8982
8983
8984
8985 <p>
8986 <hr><h3><a name="pdf-table.move"><code>table.move (a1, f, e, t [,a2])</code></a></h3>
8987
8988
8989 <p>
8990 Moves elements from table <code>a1</code> to table <code>a2</code>,
8991 performing the equivalent to the following
8992 multiple assignment:
8993 <code>a2[t],&middot;&middot;&middot; = a1[f],&middot;&middot;&middot;,a1[e]</code>.
8994 The default for <code>a2</code> is <code>a1</code>.
8995 The destination range can overlap with the source range.
8996 The number of elements to be moved must fit in a Lua integer.
8997
8998
8999 <p>
9000 Returns the destination table <code>a2</code>.
9001
9002
9003
9004
9005 <p>
9006 <hr><h3><a name="pdf-table.pack"><code>table.pack (&middot;&middot;&middot;)</code></a></h3>
9007
9008
9009 <p>
9010 Returns a new table with all parameters stored into keys 1, 2, etc.
9011 and with a field "<code>n</code>" with the total number of parameters.
9012 Note that the resulting table may not be a sequence.
9013
9014
9015
9016
9017 <p>
9018 <hr><h3><a name="pdf-table.remove"><code>table.remove (list [, pos])</code></a></h3>
9019
9020
9021 <p>
9022 Removes from <code>list</code> the element at position <code>pos</code>,
9023 returning the value of the removed element.
9024 When <code>pos</code> is an integer between 1 and <code>#list</code>,
9025 it shifts down the elements
9026 <code>list[pos+1], list[pos+2], &middot;&middot;&middot;, list[#list]</code>
9027 and erases element <code>list[#list]</code>;
9028 The index <code>pos</code> can also be 0 when <code>#list</code> is 0,
9029 or <code>#list + 1</code>;
9030 in those cases, the function erases the element <code>list[pos]</code>.
9031
9032
9033 <p>
9034 The default value for <code>pos</code> is <code>#list</code>,
9035 so that a call <code>table.remove(l)</code> removes the last element
9036 of list <code>l</code>.
9037
9038
9039
9040
9041 <p>
9042 <hr><h3><a name="pdf-table.sort"><code>table.sort (list [, comp])</code></a></h3>
9043
9044
9045 <p>
9046 Sorts list elements in a given order, <em>in-place</em>,
9047 from <code>list[1]</code> to <code>list[#list]</code>.
9048 If <code>comp</code> is given,
9049 then it must be a function that receives two list elements
9050 and returns true when the first element must come
9051 before the second in the final order
9052 (so that, after the sort,
9053 <code>i &lt; j</code> implies <code>not comp(list[j],list[i])</code>).
9054 If <code>comp</code> is not given,
9055 then the standard Lua operator <code>&lt;</code> is used instead.
9056
9057
9058 <p>
9059 Note that the <code>comp</code> function must define
9060 a strict partial order over the elements in the list;
9061 that is, it must be asymmetric and transitive.
9062 Otherwise, no valid sort may be possible.
9063
9064
9065 <p>
9066 The sort algorithm is not stable;
9067 that is, elements not comparable by the given order
9068 (e.g., equal elements)
9069 may have their relative positions changed by the sort.
9070
9071
9072
9073
9074 <p>
9075 <hr><h3><a name="pdf-table.unpack"><code>table.unpack (list [, i [, j]])</code></a></h3>
9076
9077
9078 <p>
9079 Returns the elements from the given list.
9080 This function is equivalent to
9081
9082 <pre>
9083      return list[i], list[i+1], &middot;&middot;&middot;, list[j]
9084 </pre><p>
9085 By default, <code>i</code> is&nbsp;1 and <code>j</code> is <code>#list</code>.
9086
9087
9088
9089
9090
9091
9092
9093 <h2>6.7 &ndash; <a name="6.7">Mathematical Functions</a></h2>
9094
9095 <p>
9096 This library provides basic mathematical functions.
9097 It provides all its functions and constants inside the table <a name="pdf-math"><code>math</code></a>.
9098 Functions with the annotation "<code>integer/float</code>" give
9099 integer results for integer arguments
9100 and float results for float (or mixed) arguments.
9101 Rounding functions
9102 (<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>)
9103 return an integer when the result fits in the range of an integer,
9104 or a float otherwise.
9105
9106
9107 <p>
9108 <hr><h3><a name="pdf-math.abs"><code>math.abs (x)</code></a></h3>
9109
9110
9111 <p>
9112 Returns the absolute value of <code>x</code>. (integer/float)
9113
9114
9115
9116
9117 <p>
9118 <hr><h3><a name="pdf-math.acos"><code>math.acos (x)</code></a></h3>
9119
9120
9121 <p>
9122 Returns the arc cosine of <code>x</code> (in radians).
9123
9124
9125
9126
9127 <p>
9128 <hr><h3><a name="pdf-math.asin"><code>math.asin (x)</code></a></h3>
9129
9130
9131 <p>
9132 Returns the arc sine of <code>x</code> (in radians).
9133
9134
9135
9136
9137 <p>
9138 <hr><h3><a name="pdf-math.atan"><code>math.atan (y [, x])</code></a></h3>
9139
9140
9141 <p>
9142
9143 Returns the arc tangent of <code>y/x</code> (in radians),
9144 but uses the signs of both parameters to find the
9145 quadrant of the result.
9146 (It also handles correctly the case of <code>x</code> being zero.)
9147
9148
9149 <p>
9150 The default value for <code>x</code> is 1,
9151 so that the call <code>math.atan(y)</code>
9152 returns the arc tangent of <code>y</code>.
9153
9154
9155
9156
9157 <p>
9158 <hr><h3><a name="pdf-math.ceil"><code>math.ceil (x)</code></a></h3>
9159
9160
9161 <p>
9162 Returns the smallest integral value larger than or equal to <code>x</code>.
9163
9164
9165
9166
9167 <p>
9168 <hr><h3><a name="pdf-math.cos"><code>math.cos (x)</code></a></h3>
9169
9170
9171 <p>
9172 Returns the cosine of <code>x</code> (assumed to be in radians).
9173
9174
9175
9176
9177 <p>
9178 <hr><h3><a name="pdf-math.deg"><code>math.deg (x)</code></a></h3>
9179
9180
9181 <p>
9182 Converts the angle <code>x</code> from radians to degrees.
9183
9184
9185
9186
9187 <p>
9188 <hr><h3><a name="pdf-math.exp"><code>math.exp (x)</code></a></h3>
9189
9190
9191 <p>
9192 Returns the value <em>e<sup>x</sup></em>
9193 (where <code>e</code> is the base of natural logarithms).
9194
9195
9196
9197
9198 <p>
9199 <hr><h3><a name="pdf-math.floor"><code>math.floor (x)</code></a></h3>
9200
9201
9202 <p>
9203 Returns the largest integral value smaller than or equal to <code>x</code>.
9204
9205
9206
9207
9208 <p>
9209 <hr><h3><a name="pdf-math.fmod"><code>math.fmod (x, y)</code></a></h3>
9210
9211
9212 <p>
9213 Returns the remainder of the division of <code>x</code> by <code>y</code>
9214 that rounds the quotient towards zero. (integer/float)
9215
9216
9217
9218
9219 <p>
9220 <hr><h3><a name="pdf-math.huge"><code>math.huge</code></a></h3>
9221
9222
9223 <p>
9224 The float value <code>HUGE_VAL</code>,
9225 a value larger than any other numeric value.
9226
9227
9228
9229
9230 <p>
9231 <hr><h3><a name="pdf-math.log"><code>math.log (x [, base])</code></a></h3>
9232
9233
9234 <p>
9235 Returns the logarithm of <code>x</code> in the given base.
9236 The default for <code>base</code> is <em>e</em>
9237 (so that the function returns the natural logarithm of <code>x</code>).
9238
9239
9240
9241
9242 <p>
9243 <hr><h3><a name="pdf-math.max"><code>math.max (x, &middot;&middot;&middot;)</code></a></h3>
9244
9245
9246 <p>
9247 Returns the argument with the maximum value,
9248 according to the Lua operator <code>&lt;</code>. (integer/float)
9249
9250
9251
9252
9253 <p>
9254 <hr><h3><a name="pdf-math.maxinteger"><code>math.maxinteger</code></a></h3>
9255 An integer with the maximum value for an integer.
9256
9257
9258
9259
9260 <p>
9261 <hr><h3><a name="pdf-math.min"><code>math.min (x, &middot;&middot;&middot;)</code></a></h3>
9262
9263
9264 <p>
9265 Returns the argument with the minimum value,
9266 according to the Lua operator <code>&lt;</code>. (integer/float)
9267
9268
9269
9270
9271 <p>
9272 <hr><h3><a name="pdf-math.mininteger"><code>math.mininteger</code></a></h3>
9273 An integer with the minimum value for an integer.
9274
9275
9276
9277
9278 <p>
9279 <hr><h3><a name="pdf-math.modf"><code>math.modf (x)</code></a></h3>
9280
9281
9282 <p>
9283 Returns the integral part of <code>x</code> and the fractional part of <code>x</code>.
9284 Its second result is always a float.
9285
9286
9287
9288
9289 <p>
9290 <hr><h3><a name="pdf-math.pi"><code>math.pi</code></a></h3>
9291
9292
9293 <p>
9294 The value of <em>&pi;</em>.
9295
9296
9297
9298
9299 <p>
9300 <hr><h3><a name="pdf-math.rad"><code>math.rad (x)</code></a></h3>
9301
9302
9303 <p>
9304 Converts the angle <code>x</code> from degrees to radians.
9305
9306
9307
9308
9309 <p>
9310 <hr><h3><a name="pdf-math.random"><code>math.random ([m [, n]])</code></a></h3>
9311
9312
9313 <p>
9314 When called without arguments,
9315 returns a pseudo-random float with uniform distribution
9316 in the range  <em>[0,1)</em>.
9317 When called with two integers <code>m</code> and <code>n</code>,
9318 <code>math.random</code> returns a pseudo-random integer
9319 with uniform distribution in the range <em>[m, n]</em>.
9320 (The value <em>n-m</em> cannot be negative and must fit in a Lua integer.)
9321 The call <code>math.random(n)</code> is equivalent to <code>math.random(1,n)</code>.
9322
9323
9324 <p>
9325 This function is an interface to the underling
9326 pseudo-random generator function provided by C.
9327
9328
9329
9330
9331 <p>
9332 <hr><h3><a name="pdf-math.randomseed"><code>math.randomseed (x)</code></a></h3>
9333
9334
9335 <p>
9336 Sets <code>x</code> as the "seed"
9337 for the pseudo-random generator:
9338 equal seeds produce equal sequences of numbers.
9339
9340
9341
9342
9343 <p>
9344 <hr><h3><a name="pdf-math.sin"><code>math.sin (x)</code></a></h3>
9345
9346
9347 <p>
9348 Returns the sine of <code>x</code> (assumed to be in radians).
9349
9350
9351
9352
9353 <p>
9354 <hr><h3><a name="pdf-math.sqrt"><code>math.sqrt (x)</code></a></h3>
9355
9356
9357 <p>
9358 Returns the square root of <code>x</code>.
9359 (You can also use the expression <code>x^0.5</code> to compute this value.)
9360
9361
9362
9363
9364 <p>
9365 <hr><h3><a name="pdf-math.tan"><code>math.tan (x)</code></a></h3>
9366
9367
9368 <p>
9369 Returns the tangent of <code>x</code> (assumed to be in radians).
9370
9371
9372
9373
9374 <p>
9375 <hr><h3><a name="pdf-math.tointeger"><code>math.tointeger (x)</code></a></h3>
9376
9377
9378 <p>
9379 If the value <code>x</code> is convertible to an integer,
9380 returns that integer.
9381 Otherwise, returns <b>nil</b>.
9382
9383
9384
9385
9386 <p>
9387 <hr><h3><a name="pdf-math.type"><code>math.type (x)</code></a></h3>
9388
9389
9390 <p>
9391 Returns "<code>integer</code>" if <code>x</code> is an integer,
9392 "<code>float</code>" if it is a float,
9393 or <b>nil</b> if <code>x</code> is not a number.
9394
9395
9396
9397
9398 <p>
9399 <hr><h3><a name="pdf-math.ult"><code>math.ult (m, n)</code></a></h3>
9400
9401
9402 <p>
9403 Returns a boolean,
9404 true if integer <code>m</code> is below integer <code>n</code> when
9405 they are compared as unsigned integers.
9406
9407
9408
9409
9410
9411
9412
9413 <h2>6.8 &ndash; <a name="6.8">Input and Output Facilities</a></h2>
9414
9415 <p>
9416 The I/O library provides two different styles for file manipulation.
9417 The first one uses implicit file handles;
9418 that is, there are operations to set a default input file and a
9419 default output file,
9420 and all input/output operations are over these default files.
9421 The second style uses explicit file handles.
9422
9423
9424 <p>
9425 When using implicit file handles,
9426 all operations are supplied by table <a name="pdf-io"><code>io</code></a>.
9427 When using explicit file handles,
9428 the operation <a href="#pdf-io.open"><code>io.open</code></a> returns a file handle
9429 and then all operations are supplied as methods of the file handle.
9430
9431
9432 <p>
9433 The table <code>io</code> also provides
9434 three predefined file handles with their usual meanings from C:
9435 <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>.
9436 The I/O library never closes these files.
9437
9438
9439 <p>
9440 Unless otherwise stated,
9441 all I/O functions return <b>nil</b> on failure
9442 (plus an error message as a second result and
9443 a system-dependent error code as a third result)
9444 and some value different from <b>nil</b> on success.
9445 On non-POSIX systems,
9446 the computation of the error message and error code
9447 in case of errors
9448 may be not thread safe,
9449 because they rely on the global C variable <code>errno</code>.
9450
9451
9452 <p>
9453 <hr><h3><a name="pdf-io.close"><code>io.close ([file])</code></a></h3>
9454
9455
9456 <p>
9457 Equivalent to <code>file:close()</code>.
9458 Without a <code>file</code>, closes the default output file.
9459
9460
9461
9462
9463 <p>
9464 <hr><h3><a name="pdf-io.flush"><code>io.flush ()</code></a></h3>
9465
9466
9467 <p>
9468 Equivalent to <code>io.output():flush()</code>.
9469
9470
9471
9472
9473 <p>
9474 <hr><h3><a name="pdf-io.input"><code>io.input ([file])</code></a></h3>
9475
9476
9477 <p>
9478 When called with a file name, it opens the named file (in text mode),
9479 and sets its handle as the default input file.
9480 When called with a file handle,
9481 it simply sets this file handle as the default input file.
9482 When called without parameters,
9483 it returns the current default input file.
9484
9485
9486 <p>
9487 In case of errors this function raises the error,
9488 instead of returning an error code.
9489
9490
9491
9492
9493 <p>
9494 <hr><h3><a name="pdf-io.lines"><code>io.lines ([filename, &middot;&middot;&middot;])</code></a></h3>
9495
9496
9497 <p>
9498 Opens the given file name in read mode
9499 and returns an iterator function that
9500 works like <code>file:lines(&middot;&middot;&middot;)</code> over the opened file.
9501 When the iterator function detects the end of file,
9502 it returns no values (to finish the loop) and automatically closes the file.
9503
9504
9505 <p>
9506 The call <code>io.lines()</code> (with no file name) is equivalent
9507 to <code>io.input():lines("*l")</code>;
9508 that is, it iterates over the lines of the default input file.
9509 In this case it does not close the file when the loop ends.
9510
9511
9512 <p>
9513 In case of errors this function raises the error,
9514 instead of returning an error code.
9515
9516
9517
9518
9519 <p>
9520 <hr><h3><a name="pdf-io.open"><code>io.open (filename [, mode])</code></a></h3>
9521
9522
9523 <p>
9524 This function opens a file,
9525 in the mode specified in the string <code>mode</code>.
9526 In case of success,
9527 it returns a new file handle.
9528
9529
9530 <p>
9531 The <code>mode</code> string can be any of the following:
9532
9533 <ul>
9534 <li><b>"<code>r</code>": </b> read mode (the default);</li>
9535 <li><b>"<code>w</code>": </b> write mode;</li>
9536 <li><b>"<code>a</code>": </b> append mode;</li>
9537 <li><b>"<code>r+</code>": </b> update mode, all previous data is preserved;</li>
9538 <li><b>"<code>w+</code>": </b> update mode, all previous data is erased;</li>
9539 <li><b>"<code>a+</code>": </b> append update mode, previous data is preserved,
9540   writing is only allowed at the end of file.</li>
9541 </ul><p>
9542 The <code>mode</code> string can also have a '<code>b</code>' at the end,
9543 which is needed in some systems to open the file in binary mode.
9544
9545
9546
9547
9548 <p>
9549 <hr><h3><a name="pdf-io.output"><code>io.output ([file])</code></a></h3>
9550
9551
9552 <p>
9553 Similar to <a href="#pdf-io.input"><code>io.input</code></a>, but operates over the default output file.
9554
9555
9556
9557
9558 <p>
9559 <hr><h3><a name="pdf-io.popen"><code>io.popen (prog [, mode])</code></a></h3>
9560
9561
9562 <p>
9563 This function is system dependent and is not available
9564 on all platforms.
9565
9566
9567 <p>
9568 Starts program <code>prog</code> in a separated process and returns
9569 a file handle that you can use to read data from this program
9570 (if <code>mode</code> is <code>"r"</code>, the default)
9571 or to write data to this program
9572 (if <code>mode</code> is <code>"w"</code>).
9573
9574
9575
9576
9577 <p>
9578 <hr><h3><a name="pdf-io.read"><code>io.read (&middot;&middot;&middot;)</code></a></h3>
9579
9580
9581 <p>
9582 Equivalent to <code>io.input():read(&middot;&middot;&middot;)</code>.
9583
9584
9585
9586
9587 <p>
9588 <hr><h3><a name="pdf-io.tmpfile"><code>io.tmpfile ()</code></a></h3>
9589
9590
9591 <p>
9592 In case of success,
9593 returns a handle for a temporary file.
9594 This file is opened in update mode
9595 and it is automatically removed when the program ends.
9596
9597
9598
9599
9600 <p>
9601 <hr><h3><a name="pdf-io.type"><code>io.type (obj)</code></a></h3>
9602
9603
9604 <p>
9605 Checks whether <code>obj</code> is a valid file handle.
9606 Returns the string <code>"file"</code> if <code>obj</code> is an open file handle,
9607 <code>"closed file"</code> if <code>obj</code> is a closed file handle,
9608 or <b>nil</b> if <code>obj</code> is not a file handle.
9609
9610
9611
9612
9613 <p>
9614 <hr><h3><a name="pdf-io.write"><code>io.write (&middot;&middot;&middot;)</code></a></h3>
9615
9616
9617 <p>
9618 Equivalent to <code>io.output():write(&middot;&middot;&middot;)</code>.
9619
9620
9621
9622
9623 <p>
9624 <hr><h3><a name="pdf-file:close"><code>file:close ()</code></a></h3>
9625
9626
9627 <p>
9628 Closes <code>file</code>.
9629 Note that files are automatically closed when
9630 their handles are garbage collected,
9631 but that takes an unpredictable amount of time to happen.
9632
9633
9634 <p>
9635 When closing a file handle created with <a href="#pdf-io.popen"><code>io.popen</code></a>,
9636 <a href="#pdf-file:close"><code>file:close</code></a> returns the same values
9637 returned by <a href="#pdf-os.execute"><code>os.execute</code></a>.
9638
9639
9640
9641
9642 <p>
9643 <hr><h3><a name="pdf-file:flush"><code>file:flush ()</code></a></h3>
9644
9645
9646 <p>
9647 Saves any written data to <code>file</code>.
9648
9649
9650
9651
9652 <p>
9653 <hr><h3><a name="pdf-file:lines"><code>file:lines (&middot;&middot;&middot;)</code></a></h3>
9654
9655
9656 <p>
9657 Returns an iterator function that,
9658 each time it is called,
9659 reads the file according to the given formats.
9660 When no format is given,
9661 uses "<code>l</code>" as a default.
9662 As an example, the construction
9663
9664 <pre>
9665      for c in file:lines(1) do <em>body</em> end
9666 </pre><p>
9667 will iterate over all characters of the file,
9668 starting at the current position.
9669 Unlike <a href="#pdf-io.lines"><code>io.lines</code></a>, this function does not close the file
9670 when the loop ends.
9671
9672
9673 <p>
9674 In case of errors this function raises the error,
9675 instead of returning an error code.
9676
9677
9678
9679
9680 <p>
9681 <hr><h3><a name="pdf-file:read"><code>file:read (&middot;&middot;&middot;)</code></a></h3>
9682
9683
9684 <p>
9685 Reads the file <code>file</code>,
9686 according to the given formats, which specify what to read.
9687 For each format,
9688 the function returns a string or a number with the characters read,
9689 or <b>nil</b> if it cannot read data with the specified format.
9690 (In this latter case,
9691 the function does not read subsequent formats.)
9692 When called without formats,
9693 it uses a default format that reads the next line
9694 (see below).
9695
9696
9697 <p>
9698 The available formats are
9699
9700 <ul>
9701
9702 <li><b>"<code>n</code>": </b>
9703 reads a numeral and returns it as a float or an integer,
9704 following the lexical conventions of Lua.
9705 (The numeral may have leading spaces and a sign.)
9706 This format always reads the longest input sequence that
9707 is a valid prefix for a numeral;
9708 if that prefix does not form a valid numeral
9709 (e.g., an empty string, "<code>0x</code>", or "<code>3.4e-</code>"),
9710 it is discarded and the function returns <b>nil</b>.
9711 </li>
9712
9713 <li><b>"<code>a</code>": </b>
9714 reads the whole file, starting at the current position.
9715 On end of file, it returns the empty string.
9716 </li>
9717
9718 <li><b>"<code>l</code>": </b>
9719 reads the next line skipping the end of line,
9720 returning <b>nil</b> on end of file.
9721 This is the default format.
9722 </li>
9723
9724 <li><b>"<code>L</code>": </b>
9725 reads the next line keeping the end-of-line character (if present),
9726 returning <b>nil</b> on end of file.
9727 </li>
9728
9729 <li><b><em>number</em>: </b>
9730 reads a string with up to this number of bytes,
9731 returning <b>nil</b> on end of file.
9732 If <code>number</code> is zero,
9733 it reads nothing and returns an empty string,
9734 or <b>nil</b> on end of file.
9735 </li>
9736
9737 </ul><p>
9738 The formats "<code>l</code>" and "<code>L</code>" should be used only for text files.
9739
9740
9741
9742
9743 <p>
9744 <hr><h3><a name="pdf-file:seek"><code>file:seek ([whence [, offset]])</code></a></h3>
9745
9746
9747 <p>
9748 Sets and gets the file position,
9749 measured from the beginning of the file,
9750 to the position given by <code>offset</code> plus a base
9751 specified by the string <code>whence</code>, as follows:
9752
9753 <ul>
9754 <li><b>"<code>set</code>": </b> base is position 0 (beginning of the file);</li>
9755 <li><b>"<code>cur</code>": </b> base is current position;</li>
9756 <li><b>"<code>end</code>": </b> base is end of file;</li>
9757 </ul><p>
9758 In case of success, <code>seek</code> returns the final file position,
9759 measured in bytes from the beginning of the file.
9760 If <code>seek</code> fails, it returns <b>nil</b>,
9761 plus a string describing the error.
9762
9763
9764 <p>
9765 The default value for <code>whence</code> is <code>"cur"</code>,
9766 and for <code>offset</code> is 0.
9767 Therefore, the call <code>file:seek()</code> returns the current
9768 file position, without changing it;
9769 the call <code>file:seek("set")</code> sets the position to the
9770 beginning of the file (and returns 0);
9771 and the call <code>file:seek("end")</code> sets the position to the
9772 end of the file, and returns its size.
9773
9774
9775
9776
9777 <p>
9778 <hr><h3><a name="pdf-file:setvbuf"><code>file:setvbuf (mode [, size])</code></a></h3>
9779
9780
9781 <p>
9782 Sets the buffering mode for an output file.
9783 There are three available modes:
9784
9785 <ul>
9786
9787 <li><b>"<code>no</code>": </b>
9788 no buffering; the result of any output operation appears immediately.
9789 </li>
9790
9791 <li><b>"<code>full</code>": </b>
9792 full buffering; output operation is performed only
9793 when the buffer is full or when
9794 you explicitly <code>flush</code> the file (see <a href="#pdf-io.flush"><code>io.flush</code></a>).
9795 </li>
9796
9797 <li><b>"<code>line</code>": </b>
9798 line buffering; output is buffered until a newline is output
9799 or there is any input from some special files
9800 (such as a terminal device).
9801 </li>
9802
9803 </ul><p>
9804 For the last two cases, <code>size</code>
9805 specifies the size of the buffer, in bytes.
9806 The default is an appropriate size.
9807
9808
9809
9810
9811 <p>
9812 <hr><h3><a name="pdf-file:write"><code>file:write (&middot;&middot;&middot;)</code></a></h3>
9813
9814
9815 <p>
9816 Writes the value of each of its arguments to <code>file</code>.
9817 The arguments must be strings or numbers.
9818
9819
9820 <p>
9821 In case of success, this function returns <code>file</code>.
9822 Otherwise it returns <b>nil</b> plus a string describing the error.
9823
9824
9825
9826
9827
9828
9829
9830 <h2>6.9 &ndash; <a name="6.9">Operating System Facilities</a></h2>
9831
9832 <p>
9833 This library is implemented through table <a name="pdf-os"><code>os</code></a>.
9834
9835
9836 <p>
9837 <hr><h3><a name="pdf-os.clock"><code>os.clock ()</code></a></h3>
9838
9839
9840 <p>
9841 Returns an approximation of the amount in seconds of CPU time
9842 used by the program.
9843
9844
9845
9846
9847 <p>
9848 <hr><h3><a name="pdf-os.date"><code>os.date ([format [, time]])</code></a></h3>
9849
9850
9851 <p>
9852 Returns a string or a table containing date and time,
9853 formatted according to the given string <code>format</code>.
9854
9855
9856 <p>
9857 If the <code>time</code> argument is present,
9858 this is the time to be formatted
9859 (see the <a href="#pdf-os.time"><code>os.time</code></a> function for a description of this value).
9860 Otherwise, <code>date</code> formats the current time.
9861
9862
9863 <p>
9864 If <code>format</code> starts with '<code>!</code>',
9865 then the date is formatted in Coordinated Universal Time.
9866 After this optional character,
9867 if <code>format</code> is the string "<code>*t</code>",
9868 then <code>date</code> returns a table with the following fields:
9869 <code>year</code>, <code>month</code> (1&ndash;12), <code>day</code> (1&ndash;31),
9870 <code>hour</code> (0&ndash;23), <code>min</code> (0&ndash;59), <code>sec</code> (0&ndash;61),
9871 <code>wday</code> (weekday, 1&ndash;7, Sunday is&nbsp;1),
9872 <code>yday</code> (day of the year, 1&ndash;366),
9873 and <code>isdst</code> (daylight saving flag, a boolean).
9874 This last field may be absent
9875 if the information is not available.
9876
9877
9878 <p>
9879 If <code>format</code> is not "<code>*t</code>",
9880 then <code>date</code> returns the date as a string,
9881 formatted according to the same rules as the ISO&nbsp;C function <code>strftime</code>.
9882
9883
9884 <p>
9885 When called without arguments,
9886 <code>date</code> returns a reasonable date and time representation that depends on
9887 the host system and on the current locale.
9888 (More specifically, <code>os.date()</code> is equivalent to <code>os.date("%c")</code>.)
9889
9890
9891 <p>
9892 On non-POSIX systems,
9893 this function may be not thread safe
9894 because of its reliance on C&nbsp;function <code>gmtime</code> and C&nbsp;function <code>localtime</code>.
9895
9896
9897
9898
9899 <p>
9900 <hr><h3><a name="pdf-os.difftime"><code>os.difftime (t2, t1)</code></a></h3>
9901
9902
9903 <p>
9904 Returns the difference, in seconds,
9905 from time <code>t1</code> to time <code>t2</code>
9906 (where the times are values returned by <a href="#pdf-os.time"><code>os.time</code></a>).
9907 In POSIX, Windows, and some other systems,
9908 this value is exactly <code>t2</code><em>-</em><code>t1</code>.
9909
9910
9911
9912
9913 <p>
9914 <hr><h3><a name="pdf-os.execute"><code>os.execute ([command])</code></a></h3>
9915
9916
9917 <p>
9918 This function is equivalent to the ISO&nbsp;C function <code>system</code>.
9919 It passes <code>command</code> to be executed by an operating system shell.
9920 Its first result is <b>true</b>
9921 if the command terminated successfully,
9922 or <b>nil</b> otherwise.
9923 After this first result
9924 the function returns a string plus a number,
9925 as follows:
9926
9927 <ul>
9928
9929 <li><b>"<code>exit</code>": </b>
9930 the command terminated normally;
9931 the following number is the exit status of the command.
9932 </li>
9933
9934 <li><b>"<code>signal</code>": </b>
9935 the command was terminated by a signal;
9936 the following number is the signal that terminated the command.
9937 </li>
9938
9939 </ul>
9940
9941 <p>
9942 When called without a <code>command</code>,
9943 <code>os.execute</code> returns a boolean that is true if a shell is available.
9944
9945
9946
9947
9948 <p>
9949 <hr><h3><a name="pdf-os.exit"><code>os.exit ([code [, close]])</code></a></h3>
9950
9951
9952 <p>
9953 Calls the ISO&nbsp;C function <code>exit</code> to terminate the host program.
9954 If <code>code</code> is <b>true</b>,
9955 the returned status is <code>EXIT_SUCCESS</code>;
9956 if <code>code</code> is <b>false</b>,
9957 the returned status is <code>EXIT_FAILURE</code>;
9958 if <code>code</code> is a number,
9959 the returned status is this number.
9960 The default value for <code>code</code> is <b>true</b>.
9961
9962
9963 <p>
9964 If the optional second argument <code>close</code> is true,
9965 closes the Lua state before exiting.
9966
9967
9968
9969
9970 <p>
9971 <hr><h3><a name="pdf-os.getenv"><code>os.getenv (varname)</code></a></h3>
9972
9973
9974 <p>
9975 Returns the value of the process environment variable <code>varname</code>,
9976 or <b>nil</b> if the variable is not defined.
9977
9978
9979
9980
9981 <p>
9982 <hr><h3><a name="pdf-os.remove"><code>os.remove (filename)</code></a></h3>
9983
9984
9985 <p>
9986 Deletes the file (or empty directory, on POSIX systems)
9987 with the given name.
9988 If this function fails, it returns <b>nil</b>,
9989 plus a string describing the error and the error code.
9990
9991
9992
9993
9994 <p>
9995 <hr><h3><a name="pdf-os.rename"><code>os.rename (oldname, newname)</code></a></h3>
9996
9997
9998 <p>
9999 Renames file or directory named <code>oldname</code> to <code>newname</code>.
10000 If this function fails, it returns <b>nil</b>,
10001 plus a string describing the error and the error code.
10002
10003
10004
10005
10006 <p>
10007 <hr><h3><a name="pdf-os.setlocale"><code>os.setlocale (locale [, category])</code></a></h3>
10008
10009
10010 <p>
10011 Sets the current locale of the program.
10012 <code>locale</code> is a system-dependent string specifying a locale;
10013 <code>category</code> is an optional string describing which category to change:
10014 <code>"all"</code>, <code>"collate"</code>, <code>"ctype"</code>,
10015 <code>"monetary"</code>, <code>"numeric"</code>, or <code>"time"</code>;
10016 the default category is <code>"all"</code>.
10017 The function returns the name of the new locale,
10018 or <b>nil</b> if the request cannot be honored.
10019
10020
10021 <p>
10022 If <code>locale</code> is the empty string,
10023 the current locale is set to an implementation-defined native locale.
10024 If <code>locale</code> is the string "<code>C</code>",
10025 the current locale is set to the standard C locale.
10026
10027
10028 <p>
10029 When called with <b>nil</b> as the first argument,
10030 this function only returns the name of the current locale
10031 for the given category.
10032
10033
10034 <p>
10035 This function may be not thread safe
10036 because of its reliance on C&nbsp;function <code>setlocale</code>.
10037
10038
10039
10040
10041 <p>
10042 <hr><h3><a name="pdf-os.time"><code>os.time ([table])</code></a></h3>
10043
10044
10045 <p>
10046 Returns the current time when called without arguments,
10047 or a time representing the local date and time specified by the given table.
10048 This table must have fields <code>year</code>, <code>month</code>, and <code>day</code>,
10049 and may have fields
10050 <code>hour</code> (default is 12),
10051 <code>min</code> (default is 0),
10052 <code>sec</code> (default is 0),
10053 and <code>isdst</code> (default is <b>nil</b>).
10054 Other fields are ignored.
10055 For a description of these fields, see the <a href="#pdf-os.date"><code>os.date</code></a> function.
10056
10057
10058 <p>
10059 The values in these fields do not need to be inside their valid ranges.
10060 For instance, if <code>sec</code> is -10,
10061 it means -10 seconds from the time specified by the other fields;
10062 if <code>hour</code> is 1000,
10063 it means +1000 hours from the time specified by the other fields.
10064
10065
10066 <p>
10067 The returned value is a number, whose meaning depends on your system.
10068 In POSIX, Windows, and some other systems,
10069 this number counts the number
10070 of seconds since some given start time (the "epoch").
10071 In other systems, the meaning is not specified,
10072 and the number returned by <code>time</code> can be used only as an argument to
10073 <a href="#pdf-os.date"><code>os.date</code></a> and <a href="#pdf-os.difftime"><code>os.difftime</code></a>.
10074
10075
10076
10077
10078 <p>
10079 <hr><h3><a name="pdf-os.tmpname"><code>os.tmpname ()</code></a></h3>
10080
10081
10082 <p>
10083 Returns a string with a file name that can
10084 be used for a temporary file.
10085 The file must be explicitly opened before its use
10086 and explicitly removed when no longer needed.
10087
10088
10089 <p>
10090 On POSIX systems,
10091 this function also creates a file with that name,
10092 to avoid security risks.
10093 (Someone else might create the file with wrong permissions
10094 in the time between getting the name and creating the file.)
10095 You still have to open the file to use it
10096 and to remove it (even if you do not use it).
10097
10098
10099 <p>
10100 When possible,
10101 you may prefer to use <a href="#pdf-io.tmpfile"><code>io.tmpfile</code></a>,
10102 which automatically removes the file when the program ends.
10103
10104
10105
10106
10107
10108
10109
10110 <h2>6.10 &ndash; <a name="6.10">The Debug Library</a></h2>
10111
10112 <p>
10113 This library provides
10114 the functionality of the debug interface (<a href="#4.9">&sect;4.9</a>) to Lua programs.
10115 You should exert care when using this library.
10116 Several of its functions
10117 violate basic assumptions about Lua code
10118 (e.g., that variables local to a function
10119 cannot be accessed from outside;
10120 that userdata metatables cannot be changed by Lua code;
10121 that Lua programs do not crash)
10122 and therefore can compromise otherwise secure code.
10123 Moreover, some functions in this library may be slow.
10124
10125
10126 <p>
10127 All functions in this library are provided
10128 inside the <a name="pdf-debug"><code>debug</code></a> table.
10129 All functions that operate over a thread
10130 have an optional first argument which is the
10131 thread to operate over.
10132 The default is always the current thread.
10133
10134
10135 <p>
10136 <hr><h3><a name="pdf-debug.debug"><code>debug.debug ()</code></a></h3>
10137
10138
10139 <p>
10140 Enters an interactive mode with the user,
10141 running each string that the user enters.
10142 Using simple commands and other debug facilities,
10143 the user can inspect global and local variables,
10144 change their values, evaluate expressions, and so on.
10145 A line containing only the word <code>cont</code> finishes this function,
10146 so that the caller continues its execution.
10147
10148
10149 <p>
10150 Note that commands for <code>debug.debug</code> are not lexically nested
10151 within any function and so have no direct access to local variables.
10152
10153
10154
10155
10156 <p>
10157 <hr><h3><a name="pdf-debug.gethook"><code>debug.gethook ([thread])</code></a></h3>
10158
10159
10160 <p>
10161 Returns the current hook settings of the thread, as three values:
10162 the current hook function, the current hook mask,
10163 and the current hook count
10164 (as set by the <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> function).
10165
10166
10167
10168
10169 <p>
10170 <hr><h3><a name="pdf-debug.getinfo"><code>debug.getinfo ([thread,] f [, what])</code></a></h3>
10171
10172
10173 <p>
10174 Returns a table with information about a function.
10175 You can give the function directly
10176 or you can give a number as the value of <code>f</code>,
10177 which means the function running at level <code>f</code> of the call stack
10178 of the given thread:
10179 level&nbsp;0 is the current function (<code>getinfo</code> itself);
10180 level&nbsp;1 is the function that called <code>getinfo</code>
10181 (except for tail calls, which do not count on the stack);
10182 and so on.
10183 If <code>f</code> is a number larger than the number of active functions,
10184 then <code>getinfo</code> returns <b>nil</b>.
10185
10186
10187 <p>
10188 The returned table can contain all the fields returned by <a href="#lua_getinfo"><code>lua_getinfo</code></a>,
10189 with the string <code>what</code> describing which fields to fill in.
10190 The default for <code>what</code> is to get all information available,
10191 except the table of valid lines.
10192 If present,
10193 the option '<code>f</code>'
10194 adds a field named <code>func</code> with the function itself.
10195 If present,
10196 the option '<code>L</code>'
10197 adds a field named <code>activelines</code> with the table of
10198 valid lines.
10199
10200
10201 <p>
10202 For instance, the expression <code>debug.getinfo(1,"n").name</code> returns
10203 a name for the current function,
10204 if a reasonable name can be found,
10205 and the expression <code>debug.getinfo(print)</code>
10206 returns a table with all available information
10207 about the <a href="#pdf-print"><code>print</code></a> function.
10208
10209
10210
10211
10212 <p>
10213 <hr><h3><a name="pdf-debug.getlocal"><code>debug.getlocal ([thread,] f, local)</code></a></h3>
10214
10215
10216 <p>
10217 This function returns the name and the value of the local variable
10218 with index <code>local</code> of the function at level <code>f</code> of the stack.
10219 This function accesses not only explicit local variables,
10220 but also parameters, temporaries, etc.
10221
10222
10223 <p>
10224 The first parameter or local variable has index&nbsp;1, and so on,
10225 following the order that they are declared in the code,
10226 counting only the variables that are active
10227 in the current scope of the function.
10228 Negative indices refer to vararg parameters;
10229 -1 is the first vararg parameter.
10230 The function returns <b>nil</b> if there is no variable with the given index,
10231 and raises an error when called with a level out of range.
10232 (You can call <a href="#pdf-debug.getinfo"><code>debug.getinfo</code></a> to check whether the level is valid.)
10233
10234
10235 <p>
10236 Variable names starting with '<code>(</code>' (open parenthesis)
10237 represent variables with no known names
10238 (internal variables such as loop control variables,
10239 and variables from chunks saved without debug information).
10240
10241
10242 <p>
10243 The parameter <code>f</code> may also be a function.
10244 In that case, <code>getlocal</code> returns only the name of function parameters.
10245
10246
10247
10248
10249 <p>
10250 <hr><h3><a name="pdf-debug.getmetatable"><code>debug.getmetatable (value)</code></a></h3>
10251
10252
10253 <p>
10254 Returns the metatable of the given <code>value</code>
10255 or <b>nil</b> if it does not have a metatable.
10256
10257
10258
10259
10260 <p>
10261 <hr><h3><a name="pdf-debug.getregistry"><code>debug.getregistry ()</code></a></h3>
10262
10263
10264 <p>
10265 Returns the registry table (see <a href="#4.5">&sect;4.5</a>).
10266
10267
10268
10269
10270 <p>
10271 <hr><h3><a name="pdf-debug.getupvalue"><code>debug.getupvalue (f, up)</code></a></h3>
10272
10273
10274 <p>
10275 This function returns the name and the value of the upvalue
10276 with index <code>up</code> of the function <code>f</code>.
10277 The function returns <b>nil</b> if there is no upvalue with the given index.
10278
10279
10280 <p>
10281 Variable names starting with '<code>(</code>' (open parenthesis)
10282 represent variables with no known names
10283 (variables from chunks saved without debug information).
10284
10285
10286
10287
10288 <p>
10289 <hr><h3><a name="pdf-debug.getuservalue"><code>debug.getuservalue (u)</code></a></h3>
10290
10291
10292 <p>
10293 Returns the Lua value associated to <code>u</code>.
10294 If <code>u</code> is not a userdata,
10295 returns <b>nil</b>.
10296
10297
10298
10299
10300 <p>
10301 <hr><h3><a name="pdf-debug.sethook"><code>debug.sethook ([thread,] hook, mask [, count])</code></a></h3>
10302
10303
10304 <p>
10305 Sets the given function as a hook.
10306 The string <code>mask</code> and the number <code>count</code> describe
10307 when the hook will be called.
10308 The string mask may have any combination of the following characters,
10309 with the given meaning:
10310
10311 <ul>
10312 <li><b>'<code>c</code>': </b> the hook is called every time Lua calls a function;</li>
10313 <li><b>'<code>r</code>': </b> the hook is called every time Lua returns from a function;</li>
10314 <li><b>'<code>l</code>': </b> the hook is called every time Lua enters a new line of code.</li>
10315 </ul><p>
10316 Moreover,
10317 with a <code>count</code> different from zero,
10318 the hook is called also after every <code>count</code> instructions.
10319
10320
10321 <p>
10322 When called without arguments,
10323 <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> turns off the hook.
10324
10325
10326 <p>
10327 When the hook is called, its first parameter is a string
10328 describing the event that has triggered its call:
10329 <code>"call"</code> (or <code>"tail call"</code>),
10330 <code>"return"</code>,
10331 <code>"line"</code>, and <code>"count"</code>.
10332 For line events,
10333 the hook also gets the new line number as its second parameter.
10334 Inside a hook,
10335 you can call <code>getinfo</code> with level&nbsp;2 to get more information about
10336 the running function
10337 (level&nbsp;0 is the <code>getinfo</code> function,
10338 and level&nbsp;1 is the hook function).
10339
10340
10341
10342
10343 <p>
10344 <hr><h3><a name="pdf-debug.setlocal"><code>debug.setlocal ([thread,] level, local, value)</code></a></h3>
10345
10346
10347 <p>
10348 This function assigns the value <code>value</code> to the local variable
10349 with index <code>local</code> of the function at level <code>level</code> of the stack.
10350 The function returns <b>nil</b> if there is no local
10351 variable with the given index,
10352 and raises an error when called with a <code>level</code> out of range.
10353 (You can call <code>getinfo</code> to check whether the level is valid.)
10354 Otherwise, it returns the name of the local variable.
10355
10356
10357 <p>
10358 See <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for more information about
10359 variable indices and names.
10360
10361
10362
10363
10364 <p>
10365 <hr><h3><a name="pdf-debug.setmetatable"><code>debug.setmetatable (value, table)</code></a></h3>
10366
10367
10368 <p>
10369 Sets the metatable for the given <code>value</code> to the given <code>table</code>
10370 (which can be <b>nil</b>).
10371 Returns <code>value</code>.
10372
10373
10374
10375
10376 <p>
10377 <hr><h3><a name="pdf-debug.setupvalue"><code>debug.setupvalue (f, up, value)</code></a></h3>
10378
10379
10380 <p>
10381 This function assigns the value <code>value</code> to the upvalue
10382 with index <code>up</code> of the function <code>f</code>.
10383 The function returns <b>nil</b> if there is no upvalue
10384 with the given index.
10385 Otherwise, it returns the name of the upvalue.
10386
10387
10388
10389
10390 <p>
10391 <hr><h3><a name="pdf-debug.setuservalue"><code>debug.setuservalue (udata, value)</code></a></h3>
10392
10393
10394 <p>
10395 Sets the given <code>value</code> as
10396 the Lua value associated to the given <code>udata</code>.
10397 <code>udata</code> must be a full userdata.
10398
10399
10400 <p>
10401 Returns <code>udata</code>.
10402
10403
10404
10405
10406 <p>
10407 <hr><h3><a name="pdf-debug.traceback"><code>debug.traceback ([thread,] [message [, level]])</code></a></h3>
10408
10409
10410 <p>
10411 If <code>message</code> is present but is neither a string nor <b>nil</b>,
10412 this function returns <code>message</code> without further processing.
10413 Otherwise,
10414 it returns a string with a traceback of the call stack.
10415 The optional <code>message</code> string is appended
10416 at the beginning of the traceback.
10417 An optional <code>level</code> number tells at which level
10418 to start the traceback
10419 (default is 1, the function calling <code>traceback</code>).
10420
10421
10422
10423
10424 <p>
10425 <hr><h3><a name="pdf-debug.upvalueid"><code>debug.upvalueid (f, n)</code></a></h3>
10426
10427
10428 <p>
10429 Returns a unique identifier (as a light userdata)
10430 for the upvalue numbered <code>n</code>
10431 from the given function.
10432
10433
10434 <p>
10435 These unique identifiers allow a program to check whether different
10436 closures share upvalues.
10437 Lua closures that share an upvalue
10438 (that is, that access a same external local variable)
10439 will return identical ids for those upvalue indices.
10440
10441
10442
10443
10444 <p>
10445 <hr><h3><a name="pdf-debug.upvaluejoin"><code>debug.upvaluejoin (f1, n1, f2, n2)</code></a></h3>
10446
10447
10448 <p>
10449 Make the <code>n1</code>-th upvalue of the Lua closure <code>f1</code>
10450 refer to the <code>n2</code>-th upvalue of the Lua closure <code>f2</code>.
10451
10452
10453
10454
10455
10456
10457
10458 <h1>7 &ndash; <a name="7">Lua Standalone</a></h1>
10459
10460 <p>
10461 Although Lua has been designed as an extension language,
10462 to be embedded in a host C&nbsp;program,
10463 it is also frequently used as a standalone language.
10464 An interpreter for Lua as a standalone language,
10465 called simply <code>lua</code>,
10466 is provided with the standard distribution.
10467 The standalone interpreter includes
10468 all standard libraries, including the debug library.
10469 Its usage is:
10470
10471 <pre>
10472      lua [options] [script [args]]
10473 </pre><p>
10474 The options are:
10475
10476 <ul>
10477 <li><b><code>-e <em>stat</em></code>: </b> executes string <em>stat</em>;</li>
10478 <li><b><code>-l <em>mod</em></code>: </b> "requires" <em>mod</em>;</li>
10479 <li><b><code>-i</code>: </b> enters interactive mode after running <em>script</em>;</li>
10480 <li><b><code>-v</code>: </b> prints version information;</li>
10481 <li><b><code>-E</code>: </b> ignores environment variables;</li>
10482 <li><b><code>--</code>: </b> stops handling options;</li>
10483 <li><b><code>-</code>: </b> executes <code>stdin</code> as a file and stops handling options.</li>
10484 </ul><p>
10485 After handling its options, <code>lua</code> runs the given <em>script</em>.
10486 When called without arguments,
10487 <code>lua</code> behaves as <code>lua -v -i</code>
10488 when the standard input (<code>stdin</code>) is a terminal,
10489 and as <code>lua -</code> otherwise.
10490
10491
10492 <p>
10493 When called without option <code>-E</code>,
10494 the interpreter checks for an environment variable <a name="pdf-LUA_INIT_5_3"><code>LUA_INIT_5_3</code></a>
10495 (or <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a> if the versioned name is not defined)
10496 before running any argument.
10497 If the variable content has the format <code>@<em>filename</em></code>,
10498 then <code>lua</code> executes the file.
10499 Otherwise, <code>lua</code> executes the string itself.
10500
10501
10502 <p>
10503 When called with option <code>-E</code>,
10504 besides ignoring <code>LUA_INIT</code>,
10505 Lua also ignores
10506 the values of <code>LUA_PATH</code> and <code>LUA_CPATH</code>,
10507 setting the values of
10508 <a href="#pdf-package.path"><code>package.path</code></a> and <a href="#pdf-package.cpath"><code>package.cpath</code></a>
10509 with the default paths defined in <code>luaconf.h</code>.
10510
10511
10512 <p>
10513 All options are handled in order, except <code>-i</code> and <code>-E</code>.
10514 For instance, an invocation like
10515
10516 <pre>
10517      $ lua -e'a=1' -e 'print(a)' script.lua
10518 </pre><p>
10519 will first set <code>a</code> to 1, then print the value of <code>a</code>,
10520 and finally run the file <code>script.lua</code> with no arguments.
10521 (Here <code>$</code> is the shell prompt. Your prompt may be different.)
10522
10523
10524 <p>
10525 Before running any code,
10526 <code>lua</code> collects all command-line arguments
10527 in a global table called <code>arg</code>.
10528 The script name goes to index 0,
10529 the first argument after the script name goes to index 1,
10530 and so on.
10531 Any arguments before the script name
10532 (that is, the interpreter name plus its options)
10533 go to negative indices.
10534 For instance, in the call
10535
10536 <pre>
10537      $ lua -la b.lua t1 t2
10538 </pre><p>
10539 the table is like this:
10540
10541 <pre>
10542      arg = { [-2] = "lua", [-1] = "-la",
10543              [0] = "b.lua",
10544              [1] = "t1", [2] = "t2" }
10545 </pre><p>
10546 If there is no script in the call,
10547 the interpreter name goes to index 0,
10548 followed by the other arguments.
10549 For instance, the call
10550
10551 <pre>
10552      $ lua -e "print(arg[1])"
10553 </pre><p>
10554 will print "<code>-e</code>".
10555 If there is a script,
10556 the script is called with parameters
10557 <code>arg[1]</code>, &middot;&middot;&middot;, <code>arg[#arg]</code>.
10558 (Like all chunks in Lua,
10559 the script is compiled as a vararg function.)
10560
10561
10562 <p>
10563 In interactive mode,
10564 Lua repeatedly prompts and waits for a line.
10565 After reading a line,
10566 Lua first try to interpret the line as an expression.
10567 If it succeeds, it prints its value.
10568 Otherwise, it interprets the line as a statement.
10569 If you write an incomplete statement,
10570 the interpreter waits for its completion
10571 by issuing a different prompt.
10572
10573
10574 <p>
10575 If the global variable <a name="pdf-_PROMPT"><code>_PROMPT</code></a> contains a string,
10576 then its value is used as the prompt.
10577 Similarly, if the global variable <a name="pdf-_PROMPT2"><code>_PROMPT2</code></a> contains a string,
10578 its value is used as the secondary prompt
10579 (issued during incomplete statements).
10580
10581
10582 <p>
10583 In case of unprotected errors in the script,
10584 the interpreter reports the error to the standard error stream.
10585 If the error object is not a string but
10586 has a metamethod <code>__tostring</code>,
10587 the interpreter calls this metamethod to produce the final message.
10588 Otherwise, the interpreter converts the error object to a string
10589 and adds a stack traceback to it.
10590
10591
10592 <p>
10593 When finishing normally,
10594 the interpreter closes its main Lua state
10595 (see <a href="#lua_close"><code>lua_close</code></a>).
10596 The script can avoid this step by
10597 calling <a href="#pdf-os.exit"><code>os.exit</code></a> to terminate.
10598
10599
10600 <p>
10601 To allow the use of Lua as a
10602 script interpreter in Unix systems,
10603 the standalone interpreter skips
10604 the first line of a chunk if it starts with <code>#</code>.
10605 Therefore, Lua scripts can be made into executable programs
10606 by using <code>chmod +x</code> and the&nbsp;<code>#!</code> form,
10607 as in
10608
10609 <pre>
10610      #!/usr/local/bin/lua
10611 </pre><p>
10612 (Of course,
10613 the location of the Lua interpreter may be different in your machine.
10614 If <code>lua</code> is in your <code>PATH</code>,
10615 then
10616
10617 <pre>
10618      #!/usr/bin/env lua
10619 </pre><p>
10620 is a more portable solution.)
10621
10622
10623
10624 <h1>8 &ndash; <a name="8">Incompatibilities with the Previous Version</a></h1>
10625
10626 <p>
10627 Here we list the incompatibilities that you may find when moving a program
10628 from Lua&nbsp;5.2 to Lua&nbsp;5.3.
10629 You can avoid some incompatibilities by compiling Lua with
10630 appropriate options (see file <code>luaconf.h</code>).
10631 However,
10632 all these compatibility options will be removed in the future.
10633
10634
10635 <p>
10636 Lua versions can always change the C API in ways that
10637 do not imply source-code changes in a program,
10638 such as the numeric values for constants
10639 or the implementation of functions as macros.
10640 Therefore,
10641 you should not assume that binaries are compatible between
10642 different Lua versions.
10643 Always recompile clients of the Lua API when
10644 using a new version.
10645
10646
10647 <p>
10648 Similarly, Lua versions can always change the internal representation
10649 of precompiled chunks;
10650 precompiled chunks are not compatible between different Lua versions.
10651
10652
10653 <p>
10654 The standard paths in the official distribution may
10655 change between versions.
10656
10657
10658
10659 <h2>8.1 &ndash; <a name="8.1">Changes in the Language</a></h2>
10660 <ul>
10661
10662 <li>
10663 The main difference between Lua&nbsp;5.2 and Lua&nbsp;5.3 is the
10664 introduction of an integer subtype for numbers.
10665 Although this change should not affect "normal" computations,
10666 some computations
10667 (mainly those that involve some kind of overflow)
10668 can give different results.
10669
10670
10671 <p>
10672 You can fix these differences by forcing a number to be a float
10673 (in Lua&nbsp;5.2 all numbers were float),
10674 in particular writing constants with an ending <code>.0</code>
10675 or using <code>x = x + 0.0</code> to convert a variable.
10676 (This recommendation is only for a quick fix
10677 for an occasional incompatibility;
10678 it is not a general guideline for good programming.
10679 For good programming,
10680 use floats where you need floats
10681 and integers where you need integers.)
10682 </li>
10683
10684 <li>
10685 The conversion of a float to a string now adds a <code>.0</code> suffix
10686 to the result if it looks like an integer.
10687 (For instance, the float 2.0 will be printed as <code>2.0</code>,
10688 not as <code>2</code>.)
10689 You should always use an explicit format
10690 when you need a specific format for numbers.
10691
10692
10693 <p>
10694 (Formally this is not an incompatibility,
10695 because Lua does not specify how numbers are formatted as strings,
10696 but some programs assumed a specific format.)
10697 </li>
10698
10699 <li>
10700 The generational mode for the garbage collector was removed.
10701 (It was an experimental feature in Lua&nbsp;5.2.)
10702 </li>
10703
10704 </ul>
10705
10706
10707
10708
10709 <h2>8.2 &ndash; <a name="8.2">Changes in the Libraries</a></h2>
10710 <ul>
10711
10712 <li>
10713 The <code>bit32</code> library has been deprecated.
10714 It is easy to require a compatible external library or,
10715 better yet, to replace its functions with appropriate bitwise operations.
10716 (Keep in mind that <code>bit32</code> operates on 32-bit integers,
10717 while the bitwise operators in Lua&nbsp;5.3 operate on Lua integers,
10718 which by default have 64&nbsp;bits.)
10719 </li>
10720
10721 <li>
10722 The Table library now respects metamethods
10723 for setting and getting elements.
10724 </li>
10725
10726 <li>
10727 The <a href="#pdf-ipairs"><code>ipairs</code></a> iterator now respects metamethods and
10728 its <code>__ipairs</code> metamethod has been deprecated.
10729 </li>
10730
10731 <li>
10732 Option names in <a href="#pdf-io.read"><code>io.read</code></a> do not have a starting '<code>*</code>' anymore.
10733 For compatibility, Lua will continue to accept (and ignore) this character.
10734 </li>
10735
10736 <li>
10737 The following functions were deprecated in the mathematical library:
10738 <code>atan2</code>, <code>cosh</code>, <code>sinh</code>, <code>tanh</code>, <code>pow</code>,
10739 <code>frexp</code>, and <code>ldexp</code>.
10740 You can replace <code>math.pow(x,y)</code> with <code>x^y</code>;
10741 you can replace <code>math.atan2</code> with <code>math.atan</code>,
10742 which now accepts one or two parameters;
10743 you can replace <code>math.ldexp(x,exp)</code> with <code>x * 2.0^exp</code>.
10744 For the other operations,
10745 you can either use an external library or
10746 implement them in Lua.
10747 </li>
10748
10749 <li>
10750 The searcher for C loaders used by <a href="#pdf-require"><code>require</code></a>
10751 changed the way it handles versioned names.
10752 Now, the version should come after the module name
10753 (as is usual in most other tools).
10754 For compatibility, that searcher still tries the old format
10755 if it cannot find an open function according to the new style.
10756 (Lua&nbsp;5.2 already worked that way,
10757 but it did not document the change.)
10758 </li>
10759
10760 <li>
10761 The call <code>collectgarbage("count")</code> now returns only one result.
10762 (You can compute that second result from the fractional part
10763 of the first result.)
10764 </li>
10765
10766 </ul>
10767
10768
10769
10770
10771 <h2>8.3 &ndash; <a name="8.3">Changes in the API</a></h2>
10772
10773
10774 <ul>
10775
10776 <li>
10777 Continuation functions now receive as parameters what they needed
10778 to get through <code>lua_getctx</code>,
10779 so <code>lua_getctx</code> has been removed.
10780 Adapt your code accordingly.
10781 </li>
10782
10783 <li>
10784 Function <a href="#lua_dump"><code>lua_dump</code></a> has an extra parameter, <code>strip</code>.
10785 Use 0 as the value of this parameter to get the old behavior.
10786 </li>
10787
10788 <li>
10789 Functions to inject/project unsigned integers
10790 (<code>lua_pushunsigned</code>, <code>lua_tounsigned</code>, <code>lua_tounsignedx</code>,
10791 <code>luaL_checkunsigned</code>, <code>luaL_optunsigned</code>)
10792 were deprecated.
10793 Use their signed equivalents with a type cast.
10794 </li>
10795
10796 <li>
10797 Macros to project non-default integer types
10798 (<code>luaL_checkint</code>, <code>luaL_optint</code>, <code>luaL_checklong</code>, <code>luaL_optlong</code>)
10799 were deprecated.
10800 Use their equivalent over <a href="#lua_Integer"><code>lua_Integer</code></a> with a type cast
10801 (or, when possible, use <a href="#lua_Integer"><code>lua_Integer</code></a> in your code).
10802 </li>
10803
10804 </ul>
10805
10806
10807
10808
10809 <h1>9 &ndash; <a name="9">The Complete Syntax of Lua</a></h1>
10810
10811 <p>
10812 Here is the complete syntax of Lua in extended BNF.
10813 As usual in extended BNF,
10814 {A} means 0 or more As,
10815 and [A] means an optional A.
10816 (For operator precedences, see <a href="#3.4.8">&sect;3.4.8</a>;
10817 for a description of the terminals
10818 Name, Numeral,
10819 and LiteralString, see <a href="#3.1">&sect;3.1</a>.)
10820
10821
10822
10823
10824 <pre>
10825
10826         chunk ::= block
10827
10828         block ::= {stat} [retstat]
10829
10830         stat ::=  &lsquo;<b>;</b>&rsquo; |
10831                  varlist &lsquo;<b>=</b>&rsquo; explist |
10832                  functioncall |
10833                  label |
10834                  <b>break</b> |
10835                  <b>goto</b> Name |
10836                  <b>do</b> block <b>end</b> |
10837                  <b>while</b> exp <b>do</b> block <b>end</b> |
10838                  <b>repeat</b> block <b>until</b> exp |
10839                  <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> |
10840                  <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> |
10841                  <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> |
10842                  <b>function</b> funcname funcbody |
10843                  <b>local</b> <b>function</b> Name funcbody |
10844                  <b>local</b> namelist [&lsquo;<b>=</b>&rsquo; explist]
10845
10846         retstat ::= <b>return</b> [explist] [&lsquo;<b>;</b>&rsquo;]
10847
10848         label ::= &lsquo;<b>::</b>&rsquo; Name &lsquo;<b>::</b>&rsquo;
10849
10850         funcname ::= Name {&lsquo;<b>.</b>&rsquo; Name} [&lsquo;<b>:</b>&rsquo; Name]
10851
10852         varlist ::= var {&lsquo;<b>,</b>&rsquo; var}
10853
10854         var ::=  Name | prefixexp &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo; | prefixexp &lsquo;<b>.</b>&rsquo; Name
10855
10856         namelist ::= Name {&lsquo;<b>,</b>&rsquo; Name}
10857
10858         explist ::= exp {&lsquo;<b>,</b>&rsquo; exp}
10859
10860         exp ::=  <b>nil</b> | <b>false</b> | <b>true</b> | Numeral | LiteralString | &lsquo;<b>...</b>&rsquo; | functiondef |
10861                  prefixexp | tableconstructor | exp binop exp | unop exp
10862
10863         prefixexp ::= var | functioncall | &lsquo;<b>(</b>&rsquo; exp &lsquo;<b>)</b>&rsquo;
10864
10865         functioncall ::=  prefixexp args | prefixexp &lsquo;<b>:</b>&rsquo; Name args
10866
10867         args ::=  &lsquo;<b>(</b>&rsquo; [explist] &lsquo;<b>)</b>&rsquo; | tableconstructor | LiteralString
10868
10869         functiondef ::= <b>function</b> funcbody
10870
10871         funcbody ::= &lsquo;<b>(</b>&rsquo; [parlist] &lsquo;<b>)</b>&rsquo; block <b>end</b>
10872
10873         parlist ::= namelist [&lsquo;<b>,</b>&rsquo; &lsquo;<b>...</b>&rsquo;] | &lsquo;<b>...</b>&rsquo;
10874
10875         tableconstructor ::= &lsquo;<b>{</b>&rsquo; [fieldlist] &lsquo;<b>}</b>&rsquo;
10876
10877         fieldlist ::= field {fieldsep field} [fieldsep]
10878
10879         field ::= &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo; &lsquo;<b>=</b>&rsquo; exp | Name &lsquo;<b>=</b>&rsquo; exp | exp
10880
10881         fieldsep ::= &lsquo;<b>,</b>&rsquo; | &lsquo;<b>;</b>&rsquo;
10882
10883         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; |
10884                  &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; |
10885                  &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; |
10886                  <b>and</b> | <b>or</b>
10887
10888         unop ::= &lsquo;<b>-</b>&rsquo; | <b>not</b> | &lsquo;<b>#</b>&rsquo; | &lsquo;<b>~</b>&rsquo;
10889
10890 </pre>
10891
10892 <p>
10893
10894
10895
10896
10897
10898
10899
10900
10901 <P CLASS="footer">
10902 Last update:
10903 Mon May 30 13:11:08 BRT 2016
10904 </P>
10905 <!--
10906 Last change: revised for Lua 5.3.3
10907 -->
10908
10909 </body></html>
10910