Home | History | Annotate | Line # | Download | only in doc
      1   1.1  mbalmer <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
      2   1.4  mbalmer <HTML>
      3   1.4  mbalmer <HEAD>
      4   1.9   nikita <TITLE>Lua 5.4 Reference Manual</TITLE>
      5   1.4  mbalmer <LINK REL="stylesheet" TYPE="text/css" HREF="lua.css">
      6   1.4  mbalmer <LINK REL="stylesheet" TYPE="text/css" HREF="manual.css">
      7   1.1  mbalmer <META HTTP-EQUIV="content-type" CONTENT="text/html; charset=iso-8859-1">
      8   1.4  mbalmer </HEAD>
      9   1.1  mbalmer 
     10   1.4  mbalmer <BODY>
     11   1.1  mbalmer 
     12   1.4  mbalmer <H1>
     13   1.4  mbalmer <A HREF="http://www.lua.org/"><IMG SRC="logo.gif" ALT="Lua"></A>
     14   1.9   nikita Lua 5.4 Reference Manual
     15   1.4  mbalmer </H1>
     16   1.1  mbalmer 
     17   1.4  mbalmer <P>
     18   1.1  mbalmer by Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes
     19   1.4  mbalmer 
     20   1.4  mbalmer <P>
     21   1.4  mbalmer <SMALL>
     22  1.10   nikita Copyright &copy; 2020&ndash;2023 Lua.org, PUC-Rio.
     23   1.1  mbalmer Freely available under the terms of the
     24   1.2    lneto <a href="http://www.lua.org/license.html">Lua license</a>.
     25   1.4  mbalmer </SMALL>
     26   1.1  mbalmer 
     27   1.4  mbalmer <DIV CLASS="menubar">
     28   1.4  mbalmer <A HREF="contents.html#contents">contents</A>
     29   1.4  mbalmer &middot;
     30   1.4  mbalmer <A HREF="contents.html#index">index</A>
     31   1.1  mbalmer &middot;
     32   1.4  mbalmer <A HREF="http://www.lua.org/manual/">other versions</A>
     33   1.4  mbalmer </DIV>
     34   1.1  mbalmer 
     35   1.1  mbalmer <!-- ====================================================================== -->
     36   1.1  mbalmer <p>
     37   1.1  mbalmer 
     38   1.9   nikita <!-- Id: manual.of  -->
     39   1.1  mbalmer 
     40   1.1  mbalmer 
     41   1.1  mbalmer 
     42   1.1  mbalmer 
     43   1.2    lneto <h1>1 &ndash; <a name="1">Introduction</a></h1>
     44   1.1  mbalmer 
     45   1.1  mbalmer <p>
     46   1.6  salazar Lua is a powerful, efficient, lightweight, embeddable scripting language.
     47   1.6  salazar It supports procedural programming,
     48   1.6  salazar object-oriented programming, functional programming,
     49   1.6  salazar data-driven programming, and data description.
     50   1.6  salazar 
     51   1.6  salazar 
     52   1.6  salazar <p>
     53   1.6  salazar Lua combines simple procedural syntax with powerful data description
     54   1.6  salazar constructs based on associative arrays and extensible semantics.
     55   1.6  salazar Lua is dynamically typed,
     56   1.6  salazar runs by interpreting bytecode with a register-based
     57   1.6  salazar virtual machine,
     58   1.6  salazar and has automatic memory management with
     59   1.9   nikita a generational garbage collection,
     60   1.6  salazar making it ideal for configuration, scripting,
     61   1.6  salazar and rapid prototyping.
     62   1.6  salazar 
     63   1.6  salazar 
     64   1.6  salazar <p>
     65   1.2    lneto Lua is implemented as a library, written in <em>clean C</em>,
     66  1.10   nikita the common subset of standard&nbsp;C and C++.
     67   1.6  salazar The Lua distribution includes a host program called <code>lua</code>,
     68   1.6  salazar which uses the Lua library to offer a complete,
     69   1.6  salazar standalone Lua interpreter,
     70   1.6  salazar for interactive or batch use.
     71   1.6  salazar Lua is intended to be used both as a powerful, lightweight,
     72   1.6  salazar embeddable scripting language for any program that needs one,
     73   1.6  salazar and as a powerful but lightweight and efficient stand-alone language.
     74   1.1  mbalmer 
     75   1.1  mbalmer 
     76   1.1  mbalmer <p>
     77   1.3    lneto As an extension language, Lua has no notion of a "main" program:
     78   1.6  salazar it works <em>embedded</em> in a host client,
     79   1.1  mbalmer called the <em>embedding program</em> or simply the <em>host</em>.
     80   1.6  salazar (Frequently, this host is the stand-alone <code>lua</code> program.)
     81   1.2    lneto The host program can invoke functions to execute a piece of Lua code,
     82   1.1  mbalmer can write and read Lua variables,
     83   1.1  mbalmer and can register C&nbsp;functions to be called by Lua code.
     84   1.1  mbalmer Through the use of C&nbsp;functions, Lua can be augmented to cope with
     85   1.1  mbalmer a wide range of different domains,
     86   1.1  mbalmer thus creating customized programming languages sharing a syntactical framework.
     87   1.1  mbalmer 
     88   1.1  mbalmer 
     89   1.1  mbalmer <p>
     90   1.1  mbalmer Lua is free software,
     91   1.1  mbalmer and is provided as usual with no guarantees,
     92   1.1  mbalmer as stated in its license.
     93   1.1  mbalmer The implementation described in this manual is available
     94   1.1  mbalmer at Lua's official web site, <code>www.lua.org</code>.
     95   1.1  mbalmer 
     96   1.1  mbalmer 
     97   1.1  mbalmer <p>
     98   1.1  mbalmer Like any other reference manual,
     99   1.1  mbalmer this document is dry in places.
    100   1.1  mbalmer For a discussion of the decisions behind the design of Lua,
    101   1.1  mbalmer see the technical papers available at Lua's web site.
    102   1.1  mbalmer For a detailed introduction to programming in Lua,
    103   1.2    lneto see Roberto's book, <em>Programming in Lua</em>.
    104   1.1  mbalmer 
    105   1.1  mbalmer 
    106   1.1  mbalmer 
    107   1.2    lneto <h1>2 &ndash; <a name="2">Basic Concepts</a></h1>
    108   1.1  mbalmer 
    109   1.9   nikita 
    110   1.9   nikita 
    111   1.1  mbalmer <p>
    112   1.2    lneto This section describes the basic concepts of the language.
    113   1.1  mbalmer 
    114   1.1  mbalmer 
    115   1.1  mbalmer 
    116   1.9   nikita 
    117   1.9   nikita 
    118   1.2    lneto <h2>2.1 &ndash; <a name="2.1">Values and Types</a></h2>
    119   1.1  mbalmer 
    120   1.1  mbalmer <p>
    121   1.9   nikita Lua is a dynamically typed language.
    122   1.1  mbalmer This means that
    123   1.1  mbalmer variables do not have types; only values do.
    124   1.1  mbalmer There are no type definitions in the language.
    125   1.1  mbalmer All values carry their own type.
    126   1.1  mbalmer 
    127   1.1  mbalmer 
    128   1.1  mbalmer <p>
    129   1.9   nikita All values in Lua are first-class values.
    130   1.1  mbalmer This means that all values can be stored in variables,
    131   1.1  mbalmer passed as arguments to other functions, and returned as results.
    132   1.1  mbalmer 
    133   1.1  mbalmer 
    134   1.1  mbalmer <p>
    135   1.1  mbalmer There are eight basic types in Lua:
    136   1.1  mbalmer <em>nil</em>, <em>boolean</em>, <em>number</em>,
    137   1.1  mbalmer <em>string</em>, <em>function</em>, <em>userdata</em>,
    138   1.1  mbalmer <em>thread</em>, and <em>table</em>.
    139   1.4  mbalmer The type <em>nil</em> has one single value, <b>nil</b>,
    140   1.1  mbalmer whose main property is to be different from any other value;
    141   1.9   nikita it often represents the absence of a useful value.
    142   1.4  mbalmer The type <em>boolean</em> has two values, <b>false</b> and <b>true</b>.
    143   1.1  mbalmer Both <b>nil</b> and <b>false</b> make a condition false;
    144   1.9   nikita they are collectively called <em>false values</em>.
    145   1.9   nikita Any other value makes a condition true.
    146   1.9   nikita Despite its name,
    147   1.9   nikita <b>false</b> is frequently used as an alternative to <b>nil</b>,
    148   1.9   nikita with the key difference that <b>false</b> behaves
    149   1.9   nikita like a regular value in a table,
    150   1.9   nikita while a <b>nil</b> in a table represents an absent key.
    151   1.9   nikita 
    152   1.9   nikita 
    153   1.9   nikita <p>
    154   1.4  mbalmer The type <em>number</em> represents both
    155   1.9   nikita integer numbers and real (floating-point) numbers,
    156   1.9   nikita using two subtypes: <em>integer</em> and <em>float</em>.
    157   1.9   nikita Standard Lua uses 64-bit integers and double-precision (64-bit) floats,
    158   1.9   nikita but you can also compile Lua so that it
    159   1.9   nikita uses 32-bit integers and/or single-precision (32-bit) floats.
    160   1.9   nikita The option with 32 bits for both integers and floats
    161   1.9   nikita is particularly attractive
    162   1.9   nikita for small machines and embedded systems.
    163   1.9   nikita (See macro <code>LUA_32BITS</code> in file <code>luaconf.h</code>.)
    164   1.9   nikita 
    165   1.1  mbalmer 
    166   1.9   nikita <p>
    167   1.9   nikita Unless stated otherwise,
    168   1.9   nikita any overflow when manipulating integer values <em>wrap around</em>,
    169   1.9   nikita according to the usual rules of two-complement arithmetic.
    170   1.9   nikita (In other words,
    171   1.9   nikita the actual result is the unique representable integer
    172   1.9   nikita that is equal modulo <em>2<sup>n</sup></em> to the mathematical result,
    173   1.9   nikita where <em>n</em> is the number of bits of the integer type.)
    174   1.2    lneto 
    175   1.2    lneto 
    176   1.2    lneto <p>
    177   1.9   nikita Lua has explicit rules about when each subtype is used,
    178   1.2    lneto but it also converts between them automatically as needed (see <a href="#3.4.3">&sect;3.4.3</a>).
    179   1.2    lneto Therefore,
    180   1.3    lneto the programmer may choose to mostly ignore the difference
    181   1.2    lneto between integers and floats
    182   1.3    lneto or to assume complete control over the representation of each number.
    183   1.9   nikita 
    184   1.9   nikita 
    185   1.9   nikita <p>
    186   1.9   nikita The type <em>string</em> represents immutable sequences of bytes.
    187   1.9   nikita 
    188   1.9   nikita Lua is 8-bit clean:
    189   1.9   nikita strings can contain any 8-bit value,
    190   1.9   nikita including embedded zeros ('<code>\0</code>').
    191   1.9   nikita Lua is also encoding-agnostic;
    192   1.9   nikita it makes no assumptions about the contents of a string.
    193   1.9   nikita The length of any string in Lua must fit in a Lua integer.
    194   1.1  mbalmer 
    195   1.1  mbalmer 
    196   1.1  mbalmer <p>
    197   1.1  mbalmer Lua can call (and manipulate) functions written in Lua and
    198   1.3    lneto functions written in C (see <a href="#3.4.10">&sect;3.4.10</a>).
    199   1.3    lneto Both are represented by the type <em>function</em>.
    200   1.1  mbalmer 
    201   1.1  mbalmer 
    202   1.1  mbalmer <p>
    203   1.1  mbalmer The type <em>userdata</em> is provided to allow arbitrary C&nbsp;data to
    204   1.1  mbalmer be stored in Lua variables.
    205   1.3    lneto A userdata value represents a block of raw memory.
    206   1.2    lneto There are two kinds of userdata:
    207   1.3    lneto <em>full userdata</em>,
    208   1.3    lneto which is an object with a block of memory managed by Lua,
    209   1.3    lneto and <em>light userdata</em>,
    210   1.3    lneto which is simply a C&nbsp;pointer value.
    211   1.2    lneto Userdata has no predefined operations in Lua,
    212   1.1  mbalmer except assignment and identity test.
    213   1.2    lneto By using <em>metatables</em>,
    214   1.2    lneto the programmer can define operations for full userdata values
    215   1.2    lneto (see <a href="#2.4">&sect;2.4</a>).
    216   1.1  mbalmer Userdata values cannot be created or modified in Lua,
    217   1.1  mbalmer only through the C&nbsp;API.
    218   1.9   nikita This guarantees the integrity of data owned by
    219   1.9   nikita the host program and C&nbsp;libraries.
    220   1.1  mbalmer 
    221   1.1  mbalmer 
    222   1.1  mbalmer <p>
    223   1.1  mbalmer The type <em>thread</em> represents independent threads of execution
    224   1.2    lneto and it is used to implement coroutines (see <a href="#2.6">&sect;2.6</a>).
    225   1.3    lneto Lua threads are not related to operating-system threads.
    226   1.1  mbalmer Lua supports coroutines on all systems,
    227   1.3    lneto even those that do not support threads natively.
    228   1.1  mbalmer 
    229   1.1  mbalmer 
    230   1.1  mbalmer <p>
    231   1.1  mbalmer The type <em>table</em> implements associative arrays,
    232   1.8    alnsn that is, arrays that can have as indices not only numbers,
    233   1.8    alnsn but any Lua value except <b>nil</b> and NaN.
    234   1.9   nikita (<em>Not a Number</em> is a special floating-point value
    235   1.9   nikita used by the IEEE 754 standard to represent
    236   1.9   nikita undefined numerical results, such as <code>0/0</code>.)
    237   1.1  mbalmer Tables can be <em>heterogeneous</em>;
    238   1.1  mbalmer that is, they can contain values of all types (except <b>nil</b>).
    239   1.9   nikita Any key associated to the value <b>nil</b> is not considered part of the table.
    240   1.2    lneto Conversely, any key that is not part of a table has
    241   1.2    lneto an associated value <b>nil</b>.
    242   1.2    lneto 
    243   1.2    lneto 
    244   1.2    lneto <p>
    245   1.3    lneto Tables are the sole data-structuring mechanism in Lua;
    246   1.7  mbalmer they can be used to represent ordinary arrays, lists,
    247   1.1  mbalmer symbol tables, sets, records, graphs, trees, etc.
    248   1.1  mbalmer To represent records, Lua uses the field name as an index.
    249   1.1  mbalmer The language supports this representation by
    250   1.1  mbalmer providing <code>a.name</code> as syntactic sugar for <code>a["name"]</code>.
    251   1.1  mbalmer There are several convenient ways to create tables in Lua
    252   1.2    lneto (see <a href="#3.4.9">&sect;3.4.9</a>).
    253   1.2    lneto 
    254   1.2    lneto 
    255   1.2    lneto <p>
    256   1.1  mbalmer Like indices,
    257   1.2    lneto the values of table fields can be of any type.
    258   1.1  mbalmer In particular,
    259   1.1  mbalmer because functions are first-class values,
    260   1.1  mbalmer table fields can contain functions.
    261   1.2    lneto Thus tables can also carry <em>methods</em> (see <a href="#3.4.11">&sect;3.4.11</a>).
    262   1.2    lneto 
    263   1.2    lneto 
    264   1.2    lneto <p>
    265   1.2    lneto The indexing of tables follows
    266   1.2    lneto the definition of raw equality in the language.
    267   1.2    lneto The expressions <code>a[i]</code> and <code>a[j]</code>
    268   1.2    lneto denote the same table element
    269   1.2    lneto if and only if <code>i</code> and <code>j</code> are raw equal
    270   1.2    lneto (that is, equal without metamethods).
    271   1.2    lneto In particular, floats with integral values
    272   1.2    lneto are equal to their respective integers
    273   1.2    lneto (e.g., <code>1.0 == 1</code>).
    274   1.2    lneto To avoid ambiguities,
    275   1.9   nikita any float used as a key that is equal to an integer
    276   1.9   nikita is converted to that integer.
    277   1.2    lneto For instance, if you write <code>a[2.0] = true</code>,
    278   1.9   nikita the actual key inserted into the table will be the integer <code>2</code>.
    279   1.1  mbalmer 
    280   1.1  mbalmer 
    281   1.1  mbalmer <p>
    282   1.1  mbalmer Tables, functions, threads, and (full) userdata values are <em>objects</em>:
    283   1.1  mbalmer variables do not actually <em>contain</em> these values,
    284   1.1  mbalmer only <em>references</em> to them.
    285   1.1  mbalmer Assignment, parameter passing, and function returns
    286   1.1  mbalmer always manipulate references to such values;
    287   1.1  mbalmer these operations do not imply any kind of copy.
    288   1.1  mbalmer 
    289   1.1  mbalmer 
    290   1.1  mbalmer <p>
    291   1.1  mbalmer The library function <a href="#pdf-type"><code>type</code></a> returns a string describing the type
    292   1.9   nikita of a given value (see <a href="#pdf-type"><code>type</code></a>).
    293   1.2    lneto 
    294   1.1  mbalmer 
    295   1.1  mbalmer 
    296   1.1  mbalmer 
    297   1.2    lneto 
    298   1.2    lneto <h2>2.2 &ndash; <a name="2.2">Environments and the Global Environment</a></h2>
    299   1.1  mbalmer 
    300   1.1  mbalmer <p>
    301   1.9   nikita As we will discuss further in <a href="#3.2">&sect;3.2</a> and <a href="#3.3.3">&sect;3.3.3</a>,
    302   1.3    lneto any reference to a free name
    303   1.3    lneto (that is, a name not bound to any declaration) <code>var</code>
    304   1.3    lneto is syntactically translated to <code>_ENV.var</code>.
    305   1.2    lneto Moreover, every chunk is compiled in the scope of
    306   1.3    lneto an external local variable named <code>_ENV</code> (see <a href="#3.3.2">&sect;3.3.2</a>),
    307   1.3    lneto so <code>_ENV</code> itself is never a free name in a chunk.
    308   1.1  mbalmer 
    309   1.1  mbalmer 
    310   1.2    lneto <p>
    311   1.2    lneto Despite the existence of this external <code>_ENV</code> variable and
    312   1.3    lneto the translation of free names,
    313   1.2    lneto <code>_ENV</code> is a completely regular name.
    314   1.2    lneto In particular,
    315   1.2    lneto you can define new variables and parameters with that name.
    316   1.3    lneto Each reference to a free name uses the <code>_ENV</code> that is
    317   1.2    lneto visible at that point in the program,
    318   1.2    lneto following the usual visibility rules of Lua (see <a href="#3.5">&sect;3.5</a>).
    319   1.1  mbalmer 
    320   1.1  mbalmer 
    321   1.2    lneto <p>
    322   1.2    lneto Any table used as the value of <code>_ENV</code> is called an <em>environment</em>.
    323   1.1  mbalmer 
    324   1.1  mbalmer 
    325   1.2    lneto <p>
    326   1.2    lneto Lua keeps a distinguished environment called the <em>global environment</em>.
    327   1.9   nikita This value is kept at a special index in the C registry (see <a href="#4.3">&sect;4.3</a>).
    328   1.3    lneto In Lua, the global variable <a href="#pdf-_G"><code>_G</code></a> is initialized with this same value.
    329   1.9   nikita (<a href="#pdf-_G"><code>_G</code></a> is never used internally,
    330   1.9   nikita so changing its value will affect only your own code.)
    331   1.1  mbalmer 
    332   1.1  mbalmer 
    333   1.1  mbalmer <p>
    334   1.3    lneto When Lua loads a chunk,
    335   1.9   nikita the default value for its <code>_ENV</code> variable
    336   1.3    lneto is the global environment (see <a href="#pdf-load"><code>load</code></a>).
    337   1.2    lneto Therefore, by default,
    338   1.3    lneto free names in Lua code refer to entries in the global environment
    339   1.9   nikita and, therefore, they are also called <em>global variables</em>.
    340   1.2    lneto Moreover, all standard libraries are loaded in the global environment
    341   1.3    lneto and some functions there operate on that environment.
    342   1.2    lneto You can use <a href="#pdf-load"><code>load</code></a> (or <a href="#pdf-loadfile"><code>loadfile</code></a>)
    343   1.2    lneto to load a chunk with a different environment.
    344   1.2    lneto (In C, you have to load the chunk and then change the value
    345   1.9   nikita of its first upvalue; see <a href="#lua_setupvalue"><code>lua_setupvalue</code></a>.)
    346   1.1  mbalmer 
    347   1.1  mbalmer 
    348   1.1  mbalmer 
    349   1.1  mbalmer 
    350   1.1  mbalmer 
    351   1.2    lneto <h2>2.3 &ndash; <a name="2.3">Error Handling</a></h2>
    352   1.1  mbalmer 
    353   1.1  mbalmer <p>
    354   1.9   nikita Several operations in Lua can <em>raise</em> an error.
    355   1.9   nikita An error interrupts the normal flow of the program,
    356   1.9   nikita which can continue by <em>catching</em> the error.
    357   1.9   nikita 
    358   1.9   nikita 
    359   1.9   nikita <p>
    360   1.9   nikita Lua code can explicitly raise an error by calling the
    361   1.9   nikita <a href="#pdf-error"><code>error</code></a> function.
    362   1.9   nikita (This function never returns.)
    363   1.9   nikita 
    364   1.9   nikita 
    365   1.9   nikita <p>
    366   1.9   nikita To catch errors in Lua,
    367   1.9   nikita you can do a <em>protected call</em>,
    368   1.9   nikita using <a href="#pdf-pcall"><code>pcall</code></a> (or <a href="#pdf-xpcall"><code>xpcall</code></a>).
    369   1.9   nikita The function <a href="#pdf-pcall"><code>pcall</code></a> calls a given function in <em>protected mode</em>.
    370   1.9   nikita Any error while running the function stops its execution,
    371   1.9   nikita and control returns immediately to <code>pcall</code>,
    372   1.9   nikita which returns a status code.
    373   1.9   nikita 
    374   1.9   nikita 
    375   1.9   nikita <p>
    376   1.2    lneto Because Lua is an embedded extension language,
    377   1.9   nikita Lua code starts running by a call
    378   1.9   nikita from C&nbsp;code in the host program.
    379   1.3    lneto (When you use Lua standalone,
    380   1.3    lneto the <code>lua</code> application is the host program.)
    381   1.9   nikita Usually, this call is protected;
    382   1.9   nikita so, when an otherwise unprotected error occurs during
    383   1.2    lneto the compilation or execution of a Lua chunk,
    384   1.2    lneto control returns to the host,
    385   1.9   nikita which can take appropriate measures,
    386   1.9   nikita such as printing an error message.
    387   1.1  mbalmer 
    388   1.1  mbalmer 
    389   1.1  mbalmer <p>
    390   1.2    lneto Whenever there is an error,
    391   1.9   nikita an <em>error object</em>
    392   1.2    lneto is propagated with information about the error.
    393   1.3    lneto Lua itself only generates errors whose error object is a string,
    394   1.2    lneto but programs may generate errors with
    395   1.3    lneto any value as the error object.
    396   1.3    lneto It is up to the Lua program or its host to handle such error objects.
    397   1.9   nikita For historical reasons,
    398   1.9   nikita an error object is often called an <em>error message</em>,
    399   1.9   nikita even though it does not have to be a string.
    400   1.1  mbalmer 
    401   1.1  mbalmer 
    402   1.1  mbalmer <p>
    403   1.9   nikita When you use <a href="#pdf-xpcall"><code>xpcall</code></a> (or <a href="#lua_pcall"><code>lua_pcall</code></a>, in C)
    404   1.2    lneto you may give a <em>message handler</em>
    405   1.2    lneto to be called in case of errors.
    406   1.6  salazar This function is called with the original error object
    407   1.6  salazar and returns a new error object.
    408   1.2    lneto It is called before the error unwinds the stack,
    409   1.2    lneto so that it can gather more information about the error,
    410   1.2    lneto for instance by inspecting the stack and creating a stack traceback.
    411   1.2    lneto This message handler is still protected by the protected call;
    412   1.2    lneto so, an error inside the message handler
    413   1.2    lneto will call the message handler again.
    414   1.3    lneto If this loop goes on for too long,
    415   1.3    lneto Lua breaks it and returns an appropriate message.
    416   1.9   nikita The message handler is called only for regular runtime errors.
    417   1.7  mbalmer It is not called for memory-allocation errors
    418   1.9   nikita nor for errors while running finalizers or other message handlers.
    419   1.9   nikita 
    420   1.9   nikita 
    421   1.9   nikita <p>
    422   1.9   nikita Lua also offers a system of <em>warnings</em> (see <a href="#pdf-warn"><code>warn</code></a>).
    423   1.9   nikita Unlike errors, warnings do not interfere
    424   1.9   nikita in any way with program execution.
    425   1.9   nikita They typically only generate a message to the user,
    426   1.9   nikita although this behavior can be adapted from C (see <a href="#lua_setwarnf"><code>lua_setwarnf</code></a>).
    427   1.1  mbalmer 
    428   1.1  mbalmer 
    429   1.1  mbalmer 
    430   1.1  mbalmer 
    431   1.1  mbalmer 
    432   1.2    lneto <h2>2.4 &ndash; <a name="2.4">Metatables and Metamethods</a></h2>
    433   1.1  mbalmer 
    434   1.2    lneto <p>
    435   1.2    lneto Every value in Lua can have a <em>metatable</em>.
    436   1.2    lneto This <em>metatable</em> is an ordinary Lua table
    437   1.2    lneto that defines the behavior of the original value
    438   1.9   nikita under certain events.
    439   1.2    lneto You can change several aspects of the behavior
    440   1.9   nikita of a value by setting specific fields in its metatable.
    441   1.2    lneto For instance, when a non-numeric value is the operand of an addition,
    442   1.9   nikita Lua checks for a function in the field <code>__add</code> of the value's metatable.
    443   1.2    lneto If it finds one,
    444   1.2    lneto Lua calls this function to perform the addition.
    445   1.1  mbalmer 
    446   1.1  mbalmer 
    447   1.1  mbalmer <p>
    448   1.6  salazar The key for each event in a metatable is a string
    449   1.6  salazar with the event name prefixed by two underscores;
    450   1.9   nikita the corresponding value is called a <em>metavalue</em>.
    451   1.9   nikita For most events, the metavalue must be a function,
    452   1.9   nikita which is then called a <em>metamethod</em>.
    453   1.9   nikita In the previous example, the key is the string "<code>__add</code>"
    454   1.2    lneto and the metamethod is the function that performs the addition.
    455   1.8    alnsn Unless stated otherwise,
    456   1.9   nikita a metamethod may in fact be any callable value,
    457   1.9   nikita which is either a function or a value with a <code>__call</code> metamethod.
    458   1.1  mbalmer 
    459   1.1  mbalmer 
    460   1.2    lneto <p>
    461   1.2    lneto You can query the metatable of any value
    462   1.2    lneto using the <a href="#pdf-getmetatable"><code>getmetatable</code></a> function.
    463   1.6  salazar Lua queries metamethods in metatables using a raw access (see <a href="#pdf-rawget"><code>rawget</code></a>).
    464   1.1  mbalmer 
    465   1.1  mbalmer 
    466   1.1  mbalmer <p>
    467   1.2    lneto You can replace the metatable of tables
    468   1.2    lneto using the <a href="#pdf-setmetatable"><code>setmetatable</code></a> function.
    469   1.9   nikita You cannot change the metatable of other types from Lua code,
    470   1.9   nikita except by using the debug library (<a href="#6.10">&sect;6.10</a>).
    471   1.1  mbalmer 
    472   1.1  mbalmer 
    473   1.1  mbalmer <p>
    474   1.9   nikita Tables and full userdata have individual metatables,
    475   1.9   nikita although multiple tables and userdata can share their metatables.
    476   1.2    lneto Values of all other types share one single metatable per type;
    477   1.2    lneto that is, there is one single metatable for all numbers,
    478   1.2    lneto one for all strings, etc.
    479   1.2    lneto By default, a value has no metatable,
    480   1.2    lneto but the string library sets a metatable for the string type (see <a href="#6.4">&sect;6.4</a>).
    481   1.1  mbalmer 
    482   1.1  mbalmer 
    483   1.1  mbalmer <p>
    484   1.9   nikita A detailed list of operations controlled by metatables is given next.
    485   1.9   nikita Each event is identified by its corresponding key.
    486   1.9   nikita By convention, all metatable keys used by Lua are composed by
    487   1.9   nikita two underscores followed by lowercase Latin letters.
    488   1.6  salazar 
    489   1.6  salazar 
    490   1.1  mbalmer 
    491   1.2    lneto <ul>
    492   1.1  mbalmer 
    493   1.6  salazar <li><b><code>__add</code>: </b>
    494   1.6  salazar the addition (<code>+</code>) operation.
    495   1.9   nikita If any operand for an addition is not a number,
    496   1.2    lneto Lua will try to call a metamethod.
    497   1.9   nikita It starts by checking the first operand (even if it is a number);
    498   1.9   nikita if that operand does not define a metamethod for <code>__add</code>,
    499   1.2    lneto then Lua will check the second operand.
    500   1.3    lneto If Lua can find a metamethod,
    501   1.2    lneto it calls the metamethod with the two operands as arguments,
    502   1.2    lneto and the result of the call
    503   1.2    lneto (adjusted to one value)
    504   1.2    lneto is the result of the operation.
    505   1.9   nikita Otherwise, if no metamethod is found,
    506   1.9   nikita Lua raises an error.
    507   1.2    lneto </li>
    508   1.1  mbalmer 
    509   1.6  salazar <li><b><code>__sub</code>: </b>
    510   1.6  salazar the subtraction (<code>-</code>) operation.
    511   1.6  salazar Behavior similar to the addition operation.
    512   1.2    lneto </li>
    513   1.1  mbalmer 
    514   1.6  salazar <li><b><code>__mul</code>: </b>
    515   1.6  salazar the multiplication (<code>*</code>) operation.
    516   1.6  salazar Behavior similar to the addition operation.
    517   1.2    lneto </li>
    518   1.1  mbalmer 
    519   1.6  salazar <li><b><code>__div</code>: </b>
    520   1.6  salazar the division (<code>/</code>) operation.
    521   1.6  salazar Behavior similar to the addition operation.
    522   1.2    lneto </li>
    523   1.1  mbalmer 
    524   1.6  salazar <li><b><code>__mod</code>: </b>
    525   1.6  salazar the modulo (<code>%</code>) operation.
    526   1.6  salazar Behavior similar to the addition operation.
    527   1.2    lneto </li>
    528   1.1  mbalmer 
    529   1.6  salazar <li><b><code>__pow</code>: </b>
    530   1.6  salazar the exponentiation (<code>^</code>) operation.
    531   1.6  salazar Behavior similar to the addition operation.
    532   1.2    lneto </li>
    533   1.1  mbalmer 
    534   1.6  salazar <li><b><code>__unm</code>: </b>
    535   1.6  salazar the negation (unary <code>-</code>) operation.
    536   1.6  salazar Behavior similar to the addition operation.
    537   1.2    lneto </li>
    538   1.1  mbalmer 
    539   1.6  salazar <li><b><code>__idiv</code>: </b>
    540   1.6  salazar the floor division (<code>//</code>) operation.
    541   1.6  salazar Behavior similar to the addition operation.
    542   1.2    lneto </li>
    543   1.1  mbalmer 
    544   1.6  salazar <li><b><code>__band</code>: </b>
    545   1.6  salazar the bitwise AND (<code>&amp;</code>) operation.
    546   1.6  salazar Behavior similar to the addition operation,
    547   1.3    lneto except that Lua will try a metamethod
    548   1.4  mbalmer if any operand is neither an integer
    549   1.9   nikita nor a float coercible to an integer (see <a href="#3.4.3">&sect;3.4.3</a>).
    550   1.2    lneto </li>
    551   1.1  mbalmer 
    552   1.6  salazar <li><b><code>__bor</code>: </b>
    553   1.6  salazar the bitwise OR (<code>|</code>) operation.
    554   1.6  salazar Behavior similar to the bitwise AND operation.
    555   1.2    lneto </li>
    556   1.1  mbalmer 
    557   1.6  salazar <li><b><code>__bxor</code>: </b>
    558   1.6  salazar the bitwise exclusive OR (binary <code>~</code>) operation.
    559   1.6  salazar Behavior similar to the bitwise AND operation.
    560   1.2    lneto </li>
    561   1.1  mbalmer 
    562   1.6  salazar <li><b><code>__bnot</code>: </b>
    563   1.6  salazar the bitwise NOT (unary <code>~</code>) operation.
    564   1.6  salazar Behavior similar to the bitwise AND operation.
    565   1.2    lneto </li>
    566   1.1  mbalmer 
    567   1.6  salazar <li><b><code>__shl</code>: </b>
    568   1.6  salazar the bitwise left shift (<code>&lt;&lt;</code>) operation.
    569   1.6  salazar Behavior similar to the bitwise AND operation.
    570   1.2    lneto </li>
    571   1.1  mbalmer 
    572   1.6  salazar <li><b><code>__shr</code>: </b>
    573   1.6  salazar the bitwise right shift (<code>&gt;&gt;</code>) operation.
    574   1.6  salazar Behavior similar to the bitwise AND operation.
    575   1.2    lneto </li>
    576   1.1  mbalmer 
    577   1.6  salazar <li><b><code>__concat</code>: </b>
    578   1.6  salazar the concatenation (<code>..</code>) operation.
    579   1.6  salazar Behavior similar to the addition operation,
    580   1.2    lneto except that Lua will try a metamethod
    581   1.4  mbalmer if any operand is neither a string nor a number
    582   1.2    lneto (which is always coercible to a string).
    583   1.2    lneto </li>
    584   1.2    lneto 
    585   1.6  salazar <li><b><code>__len</code>: </b>
    586   1.6  salazar the length (<code>#</code>) operation.
    587   1.2    lneto If the object is not a string,
    588   1.2    lneto Lua will try its metamethod.
    589   1.2    lneto If there is a metamethod,
    590   1.2    lneto Lua calls it with the object as argument,
    591   1.2    lneto and the result of the call
    592   1.2    lneto (always adjusted to one value)
    593   1.2    lneto is the result of the operation.
    594   1.2    lneto If there is no metamethod but the object is a table,
    595   1.2    lneto then Lua uses the table length operation (see <a href="#3.4.7">&sect;3.4.7</a>).
    596   1.2    lneto Otherwise, Lua raises an error.
    597   1.2    lneto </li>
    598   1.1  mbalmer 
    599   1.6  salazar <li><b><code>__eq</code>: </b>
    600   1.6  salazar the equal (<code>==</code>) operation.
    601   1.6  salazar Behavior similar to the addition operation,
    602   1.2    lneto except that Lua will try a metamethod only when the values
    603   1.2    lneto being compared are either both tables or both full userdata
    604   1.2    lneto and they are not primitively equal.
    605   1.2    lneto The result of the call is always converted to a boolean.
    606   1.2    lneto </li>
    607   1.1  mbalmer 
    608   1.6  salazar <li><b><code>__lt</code>: </b>
    609   1.6  salazar the less than (<code>&lt;</code>) operation.
    610   1.6  salazar Behavior similar to the addition operation,
    611   1.2    lneto except that Lua will try a metamethod only when the values
    612   1.2    lneto being compared are neither both numbers nor both strings.
    613   1.9   nikita Moreover, the result of the call is always converted to a boolean.
    614   1.2    lneto </li>
    615   1.2    lneto 
    616   1.6  salazar <li><b><code>__le</code>: </b>
    617   1.6  salazar the less equal (<code>&lt;=</code>) operation.
    618   1.9   nikita Behavior similar to the less than operation.
    619   1.2    lneto </li>
    620   1.1  mbalmer 
    621   1.6  salazar <li><b><code>__index</code>: </b>
    622   1.8    alnsn The indexing access operation <code>table[key]</code>.
    623   1.2    lneto This event happens when <code>table</code> is not a table or
    624   1.2    lneto when <code>key</code> is not present in <code>table</code>.
    625   1.9   nikita The metavalue is looked up in the metatable of <code>table</code>.
    626   1.1  mbalmer 
    627   1.1  mbalmer 
    628   1.1  mbalmer <p>
    629   1.9   nikita The metavalue for this event can be either a function, a table,
    630   1.9   nikita or any value with an <code>__index</code> metavalue.
    631   1.2    lneto If it is a function,
    632   1.6  salazar it is called with <code>table</code> and <code>key</code> as arguments,
    633   1.6  salazar and the result of the call
    634   1.6  salazar (adjusted to one value)
    635   1.6  salazar is the result of the operation.
    636   1.9   nikita Otherwise,
    637   1.9   nikita the final result is the result of indexing this metavalue with <code>key</code>.
    638   1.9   nikita This indexing is regular, not raw,
    639   1.9   nikita and therefore can trigger another <code>__index</code> metavalue.
    640   1.2    lneto </li>
    641   1.2    lneto 
    642   1.6  salazar <li><b><code>__newindex</code>: </b>
    643   1.2    lneto The indexing assignment <code>table[key] = value</code>.
    644   1.2    lneto Like the index event,
    645   1.2    lneto this event happens when <code>table</code> is not a table or
    646   1.2    lneto when <code>key</code> is not present in <code>table</code>.
    647   1.9   nikita The metavalue is looked up in the metatable of <code>table</code>.
    648   1.1  mbalmer 
    649   1.1  mbalmer 
    650   1.1  mbalmer <p>
    651   1.3    lneto Like with indexing,
    652   1.9   nikita the metavalue for this event can be either a function, a table,
    653   1.9   nikita or any value with an <code>__newindex</code> metavalue.
    654   1.2    lneto If it is a function,
    655   1.2    lneto it is called with <code>table</code>, <code>key</code>, and <code>value</code> as arguments.
    656   1.9   nikita Otherwise,
    657   1.9   nikita Lua repeats the indexing assignment over this metavalue
    658   1.9   nikita with the same key and value.
    659   1.9   nikita This assignment is regular, not raw,
    660   1.9   nikita and therefore can trigger another <code>__newindex</code> metavalue.
    661   1.1  mbalmer 
    662   1.1  mbalmer 
    663   1.2    lneto <p>
    664   1.9   nikita Whenever a <code>__newindex</code> metavalue is invoked,
    665   1.2    lneto Lua does not perform the primitive assignment.
    666   1.9   nikita If needed,
    667   1.2    lneto the metamethod itself can call <a href="#pdf-rawset"><code>rawset</code></a>
    668   1.9   nikita to do the assignment.
    669   1.2    lneto </li>
    670   1.1  mbalmer 
    671   1.6  salazar <li><b><code>__call</code>: </b>
    672   1.2    lneto The call operation <code>func(args)</code>.
    673   1.2    lneto This event happens when Lua tries to call a non-function value
    674   1.2    lneto (that is, <code>func</code> is not a function).
    675   1.2    lneto The metamethod is looked up in <code>func</code>.
    676   1.2    lneto If present,
    677   1.2    lneto the metamethod is called with <code>func</code> as its first argument,
    678   1.2    lneto followed by the arguments of the original call (<code>args</code>).
    679   1.6  salazar All results of the call
    680   1.9   nikita are the results of the operation.
    681   1.9   nikita This is the only metamethod that allows multiple results.
    682   1.2    lneto </li>
    683   1.1  mbalmer 
    684   1.2    lneto </ul>
    685   1.1  mbalmer 
    686   1.4  mbalmer <p>
    687   1.9   nikita In addition to the previous list,
    688   1.9   nikita the interpreter also respects the following keys in metatables:
    689   1.9   nikita <code>__gc</code> (see <a href="#2.5.3">&sect;2.5.3</a>),
    690   1.9   nikita <code>__close</code> (see <a href="#3.3.8">&sect;3.3.8</a>),
    691   1.9   nikita <code>__mode</code> (see <a href="#2.5.4">&sect;2.5.4</a>),
    692   1.9   nikita and <code>__name</code>.
    693   1.9   nikita (The entry <code>__name</code>,
    694   1.9   nikita when it contains a string,
    695   1.9   nikita may be used by <a href="#pdf-tostring"><code>tostring</code></a> and in error messages.)
    696   1.9   nikita 
    697   1.9   nikita 
    698   1.9   nikita <p>
    699   1.9   nikita For the unary operators (negation, length, and bitwise NOT),
    700   1.9   nikita the metamethod is computed and called with a dummy second operand,
    701   1.9   nikita equal to the first one.
    702   1.9   nikita This extra operand is only to simplify Lua's internals
    703   1.9   nikita (by making these operators behave like a binary operation)
    704   1.9   nikita and may be removed in future versions.
    705   1.9   nikita For most uses this extra operand is irrelevant.
    706   1.4  mbalmer 
    707   1.4  mbalmer 
    708   1.6  salazar <p>
    709   1.6  salazar Because metatables are regular tables,
    710   1.6  salazar they can contain arbitrary fields,
    711   1.6  salazar not only the event names defined above.
    712   1.6  salazar Some functions in the standard library
    713   1.6  salazar (e.g., <a href="#pdf-tostring"><code>tostring</code></a>)
    714   1.6  salazar use other fields in metatables for their own purposes.
    715   1.6  salazar 
    716   1.6  salazar 
    717   1.9   nikita <p>
    718   1.9   nikita It is a good practice to add all needed metamethods to a table
    719   1.9   nikita before setting it as a metatable of some object.
    720   1.9   nikita In particular, the <code>__gc</code> metamethod works only when this order
    721   1.9   nikita is followed (see <a href="#2.5.3">&sect;2.5.3</a>).
    722   1.9   nikita It is also a good practice to set the metatable of an object
    723   1.9   nikita right after its creation.
    724   1.9   nikita 
    725   1.9   nikita 
    726   1.1  mbalmer 
    727   1.1  mbalmer 
    728   1.1  mbalmer 
    729   1.2    lneto <h2>2.5 &ndash; <a name="2.5">Garbage Collection</a></h2>
    730   1.1  mbalmer 
    731   1.9   nikita 
    732   1.9   nikita 
    733   1.1  mbalmer <p>
    734   1.2    lneto Lua performs automatic memory management.
    735   1.2    lneto This means that
    736   1.3    lneto you do not have to worry about allocating memory for new objects
    737   1.3    lneto or freeing it when the objects are no longer needed.
    738   1.2    lneto Lua manages memory automatically by running
    739   1.9   nikita a <em>garbage collector</em> to collect all <em>dead</em> objects.
    740   1.2    lneto All memory used by Lua is subject to automatic management:
    741   1.2    lneto strings, tables, userdata, functions, threads, internal structures, etc.
    742   1.1  mbalmer 
    743   1.2    lneto 
    744   1.2    lneto <p>
    745   1.9   nikita An object is considered <em>dead</em>
    746   1.9   nikita as soon as the collector can be sure the object
    747   1.9   nikita will not be accessed again in the normal execution of the program.
    748   1.9   nikita ("Normal execution" here excludes finalizers,
    749   1.9   nikita which can resurrect dead objects (see <a href="#2.5.3">&sect;2.5.3</a>),
    750   1.9   nikita and excludes also operations using the debug library.)
    751   1.9   nikita Note that the time when the collector can be sure that an object
    752   1.9   nikita is dead may not coincide with the programmer's expectations.
    753   1.9   nikita The only guarantees are that Lua will not collect an object
    754   1.9   nikita that may still be accessed in the normal execution of the program,
    755   1.9   nikita and it will eventually collect an object
    756   1.9   nikita that is inaccessible from Lua.
    757   1.9   nikita (Here,
    758   1.9   nikita <em>inaccessible from Lua</em> means that neither a variable nor
    759   1.9   nikita another live object refer to the object.)
    760   1.9   nikita Because Lua has no knowledge about C&nbsp;code,
    761   1.9   nikita it never collects objects accessible through the registry (see <a href="#4.3">&sect;4.3</a>),
    762   1.9   nikita which includes the global environment (see <a href="#2.2">&sect;2.2</a>).
    763   1.9   nikita 
    764   1.9   nikita 
    765   1.9   nikita <p>
    766   1.9   nikita The garbage collector (GC) in Lua can work in two modes:
    767   1.9   nikita incremental and generational.
    768   1.9   nikita 
    769   1.9   nikita 
    770   1.9   nikita <p>
    771   1.9   nikita The default GC mode with the default parameters
    772   1.9   nikita are adequate for most uses.
    773   1.9   nikita However, programs that waste a large proportion of their time
    774   1.9   nikita allocating and freeing memory can benefit from other settings.
    775   1.9   nikita Keep in mind that the GC behavior is non-portable
    776   1.9   nikita both across platforms and across different Lua releases;
    777   1.9   nikita therefore, optimal settings are also non-portable.
    778   1.9   nikita 
    779   1.9   nikita 
    780   1.9   nikita <p>
    781   1.9   nikita You can change the GC mode and parameters by calling
    782   1.9   nikita <a href="#lua_gc"><code>lua_gc</code></a> in&nbsp;C
    783   1.9   nikita or <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> in Lua.
    784   1.9   nikita You can also use these functions to control
    785   1.9   nikita the collector directly (e.g., to stop and restart it).
    786   1.9   nikita 
    787   1.9   nikita 
    788   1.9   nikita 
    789   1.9   nikita 
    790   1.9   nikita 
    791   1.9   nikita <h3>2.5.1 &ndash; <a name="2.5.1">Incremental Garbage Collection</a></h3>
    792   1.9   nikita 
    793   1.9   nikita <p>
    794   1.9   nikita In incremental mode,
    795   1.9   nikita each GC cycle performs a mark-and-sweep collection in small steps
    796   1.9   nikita interleaved with the program's execution.
    797   1.9   nikita In this mode,
    798   1.9   nikita the collector uses three numbers to control its garbage-collection cycles:
    799   1.9   nikita the <em>garbage-collector pause</em>,
    800   1.9   nikita the <em>garbage-collector step multiplier</em>,
    801   1.9   nikita and the <em>garbage-collector step size</em>.
    802   1.1  mbalmer 
    803   1.1  mbalmer 
    804   1.1  mbalmer <p>
    805   1.2    lneto The garbage-collector pause
    806   1.2    lneto controls how long the collector waits before starting a new cycle.
    807   1.9   nikita The collector starts a new cycle when the use of memory
    808   1.9   nikita hits <em>n%</em> of the use after the previous collection.
    809   1.2    lneto Larger values make the collector less aggressive.
    810   1.9   nikita Values equal to or less than 100 mean the collector will not wait to
    811   1.2    lneto start a new cycle.
    812   1.2    lneto A value of 200 means that the collector waits for the total memory in use
    813   1.2    lneto to double before starting a new cycle.
    814   1.9   nikita The default value is 200; the maximum value is 1000.
    815   1.2    lneto 
    816   1.1  mbalmer 
    817   1.2    lneto <p>
    818   1.2    lneto The garbage-collector step multiplier
    819   1.9   nikita controls the speed of the collector relative to
    820   1.9   nikita memory allocation,
    821   1.9   nikita that is,
    822   1.9   nikita how many elements it marks or sweeps for each
    823   1.9   nikita kilobyte of memory allocated.
    824   1.2    lneto Larger values make the collector more aggressive but also increase
    825   1.2    lneto the size of each incremental step.
    826   1.9   nikita You should not use values less than 100,
    827   1.3    lneto because they make the collector too slow and
    828   1.2    lneto can result in the collector never finishing a cycle.
    829   1.9   nikita The default value is 100;  the maximum value is 1000.
    830   1.9   nikita 
    831   1.9   nikita 
    832   1.9   nikita <p>
    833   1.9   nikita The garbage-collector step size controls the
    834   1.9   nikita size of each incremental step,
    835   1.9   nikita specifically how many bytes the interpreter allocates
    836   1.9   nikita before performing a step.
    837   1.9   nikita This parameter is logarithmic:
    838   1.9   nikita A value of <em>n</em> means the interpreter will allocate <em>2<sup>n</sup></em>
    839   1.9   nikita bytes between steps and perform equivalent work during the step.
    840   1.9   nikita A large value (e.g., 60) makes the collector a stop-the-world
    841   1.9   nikita (non-incremental) collector.
    842   1.9   nikita The default value is 13,
    843   1.9   nikita which means steps of approximately 8&nbsp;Kbytes.
    844   1.9   nikita 
    845   1.9   nikita 
    846   1.9   nikita 
    847   1.9   nikita 
    848   1.1  mbalmer 
    849   1.9   nikita <h3>2.5.2 &ndash; <a name="2.5.2">Generational Garbage Collection</a></h3>
    850   1.1  mbalmer 
    851   1.2    lneto <p>
    852   1.9   nikita In generational mode,
    853   1.9   nikita the collector does frequent <em>minor</em> collections,
    854   1.9   nikita which traverses only objects recently created.
    855   1.9   nikita If after a minor collection the use of memory is still above a limit,
    856   1.9   nikita the collector does a stop-the-world <em>major</em> collection,
    857   1.9   nikita which traverses all objects.
    858   1.9   nikita The generational mode uses two parameters:
    859   1.9   nikita the <em>minor multiplier</em> and the <em>the major multiplier</em>.
    860   1.1  mbalmer 
    861   1.1  mbalmer 
    862   1.2    lneto <p>
    863   1.9   nikita The minor multiplier controls the frequency of minor collections.
    864   1.9   nikita For a minor multiplier <em>x</em>,
    865   1.9   nikita a new minor collection will be done when memory
    866   1.9   nikita grows <em>x%</em> larger than the memory in use after the previous major
    867   1.9   nikita collection.
    868   1.9   nikita For instance, for a multiplier of 20,
    869   1.9   nikita the collector will do a minor collection when the use of memory
    870   1.9   nikita gets 20% larger than the use after the previous major collection.
    871   1.9   nikita The default value is 20; the maximum value is 200.
    872   1.9   nikita 
    873   1.9   nikita 
    874   1.9   nikita <p>
    875   1.9   nikita The major multiplier controls the frequency of major collections.
    876   1.9   nikita For a major multiplier <em>x</em>,
    877   1.9   nikita a new major collection will be done when memory
    878   1.9   nikita grows <em>x%</em> larger than the memory in use after the previous major
    879   1.9   nikita collection.
    880   1.9   nikita For instance, for a multiplier of 100,
    881   1.9   nikita the collector will do a major collection when the use of memory
    882   1.9   nikita gets larger than twice the use after the previous collection.
    883   1.9   nikita The default value is 100; the maximum value is 1000.
    884   1.9   nikita 
    885   1.9   nikita 
    886   1.1  mbalmer 
    887   1.1  mbalmer 
    888   1.1  mbalmer 
    889   1.9   nikita <h3>2.5.3 &ndash; <a name="2.5.3">Garbage-Collection Metamethods</a></h3>
    890   1.1  mbalmer 
    891   1.2    lneto <p>
    892   1.2    lneto You can set garbage-collector metamethods for tables
    893   1.2    lneto and, using the C&nbsp;API,
    894   1.2    lneto for full userdata (see <a href="#2.4">&sect;2.4</a>).
    895   1.9   nikita These metamethods, called <em>finalizers</em>,
    896   1.9   nikita are called when the garbage collector detects that the
    897   1.9   nikita corresponding table or userdata is dead.
    898   1.2    lneto Finalizers allow you to coordinate Lua's garbage collection
    899   1.9   nikita with external resource management such as closing files,
    900   1.9   nikita network or database connections,
    901   1.9   nikita or freeing your own memory.
    902   1.1  mbalmer 
    903   1.1  mbalmer 
    904   1.1  mbalmer <p>
    905   1.2    lneto For an object (table or userdata) to be finalized when collected,
    906   1.2    lneto you must <em>mark</em> it for finalization.
    907   1.1  mbalmer 
    908   1.2    lneto You mark an object for finalization when you set its metatable
    909   1.9   nikita and the metatable has a <code>__gc</code> metamethod.
    910   1.2    lneto Note that if you set a metatable without a <code>__gc</code> field
    911   1.2    lneto and later create that field in the metatable,
    912   1.2    lneto the object will not be marked for finalization.
    913   1.1  mbalmer 
    914   1.1  mbalmer 
    915   1.2    lneto <p>
    916   1.9   nikita When a marked object becomes dead,
    917   1.2    lneto it is not collected immediately by the garbage collector.
    918   1.2    lneto Instead, Lua puts it in a list.
    919   1.2    lneto After the collection,
    920   1.3    lneto Lua goes through that list.
    921   1.3    lneto For each object in the list,
    922   1.3    lneto it checks the object's <code>__gc</code> metamethod:
    923   1.9   nikita If it is present,
    924   1.9   nikita Lua calls it with the object as its single argument.
    925   1.1  mbalmer 
    926   1.1  mbalmer 
    927   1.2    lneto <p>
    928   1.2    lneto At the end of each garbage-collection cycle,
    929   1.9   nikita the finalizers are called in
    930   1.3    lneto the reverse order that the objects were marked for finalization,
    931   1.2    lneto among those collected in that cycle;
    932   1.2    lneto that is, the first finalizer to be called is the one associated
    933   1.2    lneto with the object marked last in the program.
    934   1.2    lneto The execution of each finalizer may occur at any point during
    935   1.2    lneto the execution of the regular code.
    936   1.1  mbalmer 
    937   1.1  mbalmer 
    938   1.2    lneto <p>
    939   1.2    lneto Because the object being collected must still be used by the finalizer,
    940   1.3    lneto that object (and other objects accessible only through it)
    941   1.2    lneto must be <em>resurrected</em> by Lua.
    942   1.2    lneto Usually, this resurrection is transient,
    943   1.2    lneto and the object memory is freed in the next garbage-collection cycle.
    944   1.2    lneto However, if the finalizer stores the object in some global place
    945   1.2    lneto (e.g., a global variable),
    946   1.3    lneto then the resurrection is permanent.
    947   1.2    lneto Moreover, if the finalizer marks a finalizing object for finalization again,
    948   1.2    lneto its finalizer will be called again in the next cycle where the
    949   1.9   nikita object is dead.
    950   1.2    lneto In any case,
    951   1.4  mbalmer the object memory is freed only in a GC cycle where
    952   1.9   nikita the object is dead and not marked for finalization.
    953   1.1  mbalmer 
    954   1.1  mbalmer 
    955   1.2    lneto <p>
    956   1.2    lneto When you close a state (see <a href="#lua_close"><code>lua_close</code></a>),
    957   1.2    lneto Lua calls the finalizers of all objects marked for finalization,
    958   1.2    lneto following the reverse order that they were marked.
    959   1.2    lneto If any finalizer marks objects for collection during that phase,
    960   1.2    lneto these marks have no effect.
    961   1.1  mbalmer 
    962   1.1  mbalmer 
    963   1.9   nikita <p>
    964   1.9   nikita Finalizers cannot yield nor run the garbage collector.
    965   1.9   nikita Because they can run in unpredictable times,
    966   1.9   nikita it is good practice to restrict each finalizer
    967   1.9   nikita to the minimum necessary to properly release
    968   1.9   nikita its associated resource.
    969   1.1  mbalmer 
    970   1.1  mbalmer 
    971   1.9   nikita <p>
    972   1.9   nikita Any error while running a finalizer generates a warning;
    973   1.9   nikita the error is not propagated.
    974   1.9   nikita 
    975   1.1  mbalmer 
    976   1.9   nikita 
    977   1.9   nikita 
    978   1.9   nikita 
    979   1.9   nikita <h3>2.5.4 &ndash; <a name="2.5.4">Weak Tables</a></h3>
    980   1.2    lneto 
    981   1.2    lneto <p>
    982   1.2    lneto A <em>weak table</em> is a table whose elements are
    983   1.2    lneto <em>weak references</em>.
    984   1.2    lneto A weak reference is ignored by the garbage collector.
    985   1.2    lneto In other words,
    986   1.2    lneto if the only references to an object are weak references,
    987   1.2    lneto then the garbage collector will collect that object.
    988   1.2    lneto 
    989   1.2    lneto 
    990   1.2    lneto <p>
    991   1.2    lneto A weak table can have weak keys, weak values, or both.
    992   1.4  mbalmer A table with weak values allows the collection of its values,
    993   1.4  mbalmer but prevents the collection of its keys.
    994   1.2    lneto A table with both weak keys and weak values allows the collection of
    995   1.2    lneto both keys and values.
    996   1.2    lneto In any case, if either the key or the value is collected,
    997   1.2    lneto the whole pair is removed from the table.
    998   1.2    lneto The weakness of a table is controlled by the
    999   1.2    lneto <code>__mode</code> field of its metatable.
   1000   1.9   nikita This metavalue, if present, must be one of the following strings:
   1001   1.9   nikita "<code>k</code>", for a table with weak keys;
   1002   1.9   nikita "<code>v</code>", for a table with weak values;
   1003   1.9   nikita or "<code>kv</code>", for a table with both weak keys and values.
   1004   1.1  mbalmer 
   1005   1.1  mbalmer 
   1006   1.2    lneto <p>
   1007   1.2    lneto A table with weak keys and strong values
   1008   1.2    lneto is also called an <em>ephemeron table</em>.
   1009   1.2    lneto In an ephemeron table,
   1010   1.2    lneto a value is considered reachable only if its key is reachable.
   1011   1.2    lneto In particular,
   1012   1.2    lneto if the only reference to a key comes through its value,
   1013   1.2    lneto the pair is removed.
   1014   1.1  mbalmer 
   1015   1.1  mbalmer 
   1016   1.2    lneto <p>
   1017   1.2    lneto Any change in the weakness of a table may take effect only
   1018   1.2    lneto at the next collect cycle.
   1019   1.2    lneto In particular, if you change the weakness to a stronger mode,
   1020   1.2    lneto Lua may still collect some items from that table
   1021   1.2    lneto before the change takes effect.
   1022   1.1  mbalmer 
   1023   1.1  mbalmer 
   1024   1.2    lneto <p>
   1025   1.2    lneto Only objects that have an explicit construction
   1026   1.2    lneto are removed from weak tables.
   1027   1.7  mbalmer Values, such as numbers and light C&nbsp;functions,
   1028   1.2    lneto are not subject to garbage collection,
   1029   1.2    lneto and therefore are not removed from weak tables
   1030   1.3    lneto (unless their associated values are collected).
   1031   1.2    lneto Although strings are subject to garbage collection,
   1032   1.9   nikita they do not have an explicit construction and
   1033   1.9   nikita their equality is by value;
   1034   1.9   nikita they behave more like values than like objects.
   1035   1.9   nikita Therefore, they are not removed from weak tables.
   1036   1.1  mbalmer 
   1037   1.1  mbalmer 
   1038   1.1  mbalmer <p>
   1039   1.2    lneto Resurrected objects
   1040   1.2    lneto (that is, objects being finalized
   1041   1.2    lneto and objects accessible only through objects being finalized)
   1042   1.2    lneto have a special behavior in weak tables.
   1043   1.2    lneto They are removed from weak values before running their finalizers,
   1044   1.2    lneto but are removed from weak keys only in the next collection
   1045   1.2    lneto after running their finalizers, when such objects are actually freed.
   1046   1.2    lneto This behavior allows the finalizer to access properties
   1047   1.2    lneto associated with the object through weak tables.
   1048   1.1  mbalmer 
   1049   1.1  mbalmer 
   1050   1.1  mbalmer <p>
   1051   1.2    lneto If a weak table is among the resurrected objects in a collection cycle,
   1052   1.2    lneto it may not be properly cleared until the next cycle.
   1053   1.1  mbalmer 
   1054   1.1  mbalmer 
   1055   1.1  mbalmer 
   1056   1.1  mbalmer 
   1057   1.1  mbalmer 
   1058   1.1  mbalmer 
   1059   1.1  mbalmer 
   1060   1.2    lneto <h2>2.6 &ndash; <a name="2.6">Coroutines</a></h2>
   1061   1.1  mbalmer 
   1062   1.1  mbalmer <p>
   1063   1.2    lneto Lua supports coroutines,
   1064   1.2    lneto also called <em>collaborative multithreading</em>.
   1065   1.2    lneto A coroutine in Lua represents an independent thread of execution.
   1066   1.2    lneto Unlike threads in multithread systems, however,
   1067   1.2    lneto a coroutine only suspends its execution by explicitly calling
   1068   1.2    lneto a yield function.
   1069   1.1  mbalmer 
   1070   1.1  mbalmer 
   1071   1.1  mbalmer <p>
   1072   1.2    lneto You create a coroutine by calling <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>.
   1073   1.2    lneto Its sole argument is a function
   1074   1.2    lneto that is the main function of the coroutine.
   1075   1.2    lneto The <code>create</code> function only creates a new coroutine and
   1076   1.2    lneto returns a handle to it (an object of type <em>thread</em>);
   1077   1.2    lneto it does not start the coroutine.
   1078   1.1  mbalmer 
   1079   1.1  mbalmer 
   1080   1.1  mbalmer <p>
   1081   1.2    lneto You execute a coroutine by calling <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>.
   1082   1.2    lneto When you first call <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>,
   1083   1.2    lneto passing as its first argument
   1084   1.2    lneto a thread returned by <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>,
   1085   1.4  mbalmer the coroutine starts its execution by
   1086   1.4  mbalmer calling its main function.
   1087   1.3    lneto Extra arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> are passed
   1088   1.4  mbalmer as arguments to that function.
   1089   1.2    lneto After the coroutine starts running,
   1090   1.2    lneto it runs until it terminates or <em>yields</em>.
   1091   1.1  mbalmer 
   1092   1.1  mbalmer 
   1093   1.1  mbalmer <p>
   1094   1.2    lneto A coroutine can terminate its execution in two ways:
   1095   1.2    lneto normally, when its main function returns
   1096   1.2    lneto (explicitly or implicitly, after the last instruction);
   1097   1.2    lneto and abnormally, if there is an unprotected error.
   1098   1.3    lneto In case of normal termination,
   1099   1.3    lneto <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>true</b>,
   1100   1.2    lneto plus any values returned by the coroutine main function.
   1101   1.2    lneto In case of errors, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>false</b>
   1102   1.9   nikita plus the error object.
   1103   1.9   nikita In this case, the coroutine does not unwind its stack,
   1104   1.9   nikita so that it is possible to inspect it after the error
   1105   1.9   nikita with the debug API.
   1106   1.1  mbalmer 
   1107   1.1  mbalmer 
   1108   1.1  mbalmer <p>
   1109   1.2    lneto A coroutine yields by calling <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>.
   1110   1.2    lneto When a coroutine yields,
   1111   1.2    lneto the corresponding <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns immediately,
   1112   1.2    lneto even if the yield happens inside nested function calls
   1113   1.2    lneto (that is, not in the main function,
   1114   1.2    lneto but in a function directly or indirectly called by the main function).
   1115   1.2    lneto In the case of a yield, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> also returns <b>true</b>,
   1116   1.2    lneto plus any values passed to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>.
   1117   1.2    lneto The next time you resume the same coroutine,
   1118   1.2    lneto it continues its execution from the point where it yielded,
   1119   1.2    lneto with the call to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a> returning any extra
   1120   1.2    lneto arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>.
   1121   1.1  mbalmer 
   1122   1.1  mbalmer 
   1123   1.1  mbalmer <p>
   1124   1.2    lneto Like <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>,
   1125   1.2    lneto the <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> function also creates a coroutine,
   1126   1.2    lneto but instead of returning the coroutine itself,
   1127   1.2    lneto it returns a function that, when called, resumes the coroutine.
   1128   1.2    lneto Any arguments passed to this function
   1129   1.2    lneto go as extra arguments to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>.
   1130   1.2    lneto <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> returns all the values returned by <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>,
   1131   1.2    lneto except the first one (the boolean error code).
   1132   1.2    lneto Unlike <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>,
   1133   1.9   nikita the function created by <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a>
   1134   1.9   nikita propagates any error to the caller.
   1135   1.9   nikita In this case,
   1136   1.9   nikita the function also closes the coroutine (see <a href="#pdf-coroutine.close"><code>coroutine.close</code></a>).
   1137   1.1  mbalmer 
   1138   1.1  mbalmer 
   1139   1.2    lneto <p>
   1140   1.2    lneto As an example of how coroutines work,
   1141   1.2    lneto consider the following code:
   1142   1.1  mbalmer 
   1143   1.1  mbalmer <pre>
   1144   1.2    lneto      function foo (a)
   1145   1.2    lneto        print("foo", a)
   1146   1.2    lneto        return coroutine.yield(2*a)
   1147   1.2    lneto      end
   1148   1.2    lneto      
   1149   1.2    lneto      co = coroutine.create(function (a,b)
   1150   1.2    lneto            print("co-body", a, b)
   1151   1.2    lneto            local r = foo(a+1)
   1152   1.2    lneto            print("co-body", r)
   1153   1.2    lneto            local r, s = coroutine.yield(a+b, a-b)
   1154   1.2    lneto            print("co-body", r, s)
   1155   1.2    lneto            return b, "end"
   1156   1.2    lneto      end)
   1157   1.2    lneto      
   1158   1.2    lneto      print("main", coroutine.resume(co, 1, 10))
   1159   1.2    lneto      print("main", coroutine.resume(co, "r"))
   1160   1.2    lneto      print("main", coroutine.resume(co, "x", "y"))
   1161   1.2    lneto      print("main", coroutine.resume(co, "x", "y"))
   1162   1.1  mbalmer </pre><p>
   1163   1.2    lneto When you run it, it produces the following output:
   1164   1.1  mbalmer 
   1165   1.2    lneto <pre>
   1166   1.2    lneto      co-body 1       10
   1167   1.2    lneto      foo     2
   1168   1.2    lneto      main    true    4
   1169   1.2    lneto      co-body r
   1170   1.2    lneto      main    true    11      -9
   1171   1.2    lneto      co-body x       y
   1172   1.2    lneto      main    true    10      end
   1173   1.2    lneto      main    false   cannot resume dead coroutine
   1174   1.2    lneto </pre>
   1175   1.1  mbalmer 
   1176   1.2    lneto <p>
   1177   1.2    lneto You can also create and manipulate coroutines through the C API:
   1178   1.2    lneto see functions <a href="#lua_newthread"><code>lua_newthread</code></a>, <a href="#lua_resume"><code>lua_resume</code></a>,
   1179   1.2    lneto and <a href="#lua_yield"><code>lua_yield</code></a>.
   1180   1.1  mbalmer 
   1181   1.1  mbalmer 
   1182   1.1  mbalmer 
   1183   1.1  mbalmer 
   1184   1.1  mbalmer 
   1185   1.2    lneto <h1>3 &ndash; <a name="3">The Language</a></h1>
   1186   1.1  mbalmer 
   1187   1.9   nikita 
   1188   1.9   nikita 
   1189   1.1  mbalmer <p>
   1190   1.2    lneto This section describes the lexis, the syntax, and the semantics of Lua.
   1191   1.2    lneto In other words,
   1192   1.2    lneto this section describes
   1193   1.2    lneto which tokens are valid,
   1194   1.2    lneto how they can be combined,
   1195   1.2    lneto and what their combinations mean.
   1196   1.1  mbalmer 
   1197   1.1  mbalmer 
   1198   1.1  mbalmer <p>
   1199   1.2    lneto Language constructs will be explained using the usual extended BNF notation,
   1200   1.2    lneto in which
   1201   1.2    lneto {<em>a</em>}&nbsp;means&nbsp;0 or more <em>a</em>'s, and
   1202   1.2    lneto [<em>a</em>]&nbsp;means an optional <em>a</em>.
   1203   1.2    lneto Non-terminals are shown like non-terminal,
   1204   1.2    lneto keywords are shown like <b>kword</b>,
   1205   1.2    lneto and other terminal symbols are shown like &lsquo;<b>=</b>&rsquo;.
   1206   1.2    lneto The complete syntax of Lua can be found in <a href="#9">&sect;9</a>
   1207   1.2    lneto at the end of this manual.
   1208   1.1  mbalmer 
   1209   1.1  mbalmer 
   1210   1.1  mbalmer 
   1211   1.9   nikita 
   1212   1.9   nikita 
   1213   1.2    lneto <h2>3.1 &ndash; <a name="3.1">Lexical Conventions</a></h2>
   1214   1.1  mbalmer 
   1215   1.1  mbalmer <p>
   1216   1.2    lneto Lua is a free-form language.
   1217   1.9   nikita It ignores spaces and comments between lexical elements (tokens),
   1218   1.9   nikita except as delimiters between two tokens.
   1219   1.9   nikita In source code,
   1220   1.9   nikita Lua recognizes as spaces the standard ASCII whitespace
   1221   1.9   nikita characters space, form feed, newline,
   1222   1.9   nikita carriage return, horizontal tab, and vertical tab.
   1223   1.1  mbalmer 
   1224   1.1  mbalmer 
   1225   1.1  mbalmer <p>
   1226   1.2    lneto <em>Names</em>
   1227   1.2    lneto (also called <em>identifiers</em>)
   1228   1.9   nikita in Lua can be any string of Latin letters,
   1229   1.9   nikita Arabic-Indic digits, and underscores,
   1230   1.5    lneto not beginning with a digit and
   1231   1.5    lneto not being a reserved word.
   1232   1.2    lneto Identifiers are used to name variables, table fields, and labels.
   1233   1.1  mbalmer 
   1234   1.1  mbalmer 
   1235   1.2    lneto <p>
   1236   1.2    lneto The following <em>keywords</em> are reserved
   1237   1.2    lneto and cannot be used as names:
   1238   1.1  mbalmer 
   1239   1.1  mbalmer 
   1240   1.2    lneto <pre>
   1241   1.2    lneto      and       break     do        else      elseif    end
   1242   1.2    lneto      false     for       function  goto      if        in
   1243   1.2    lneto      local     nil       not       or        repeat    return
   1244   1.2    lneto      then      true      until     while
   1245   1.2    lneto </pre>
   1246   1.1  mbalmer 
   1247   1.2    lneto <p>
   1248   1.2    lneto Lua is a case-sensitive language:
   1249   1.2    lneto <code>and</code> is a reserved word, but <code>And</code> and <code>AND</code>
   1250   1.2    lneto are two different, valid names.
   1251   1.2    lneto As a convention,
   1252   1.7  mbalmer programs should avoid creating
   1253   1.2    lneto names that start with an underscore followed by
   1254   1.2    lneto one or more uppercase letters (such as <a href="#pdf-_VERSION"><code>_VERSION</code></a>).
   1255   1.1  mbalmer 
   1256   1.1  mbalmer 
   1257   1.1  mbalmer <p>
   1258   1.2    lneto The following strings denote other tokens:
   1259   1.1  mbalmer 
   1260   1.1  mbalmer <pre>
   1261   1.2    lneto      +     -     *     /     %     ^     #
   1262   1.2    lneto      &amp;     ~     |     &lt;&lt;    &gt;&gt;    //
   1263   1.2    lneto      ==    ~=    &lt;=    &gt;=    &lt;     &gt;     =
   1264   1.2    lneto      (     )     {     }     [     ]     ::
   1265   1.2    lneto      ;     :     ,     .     ..    ...
   1266   1.2    lneto </pre>
   1267   1.1  mbalmer 
   1268   1.1  mbalmer <p>
   1269   1.7  mbalmer A <em>short literal string</em>
   1270   1.2    lneto can be delimited by matching single or double quotes,
   1271   1.2    lneto and can contain the following C-like escape sequences:
   1272   1.2    lneto '<code>\a</code>' (bell),
   1273   1.2    lneto '<code>\b</code>' (backspace),
   1274   1.2    lneto '<code>\f</code>' (form feed),
   1275   1.2    lneto '<code>\n</code>' (newline),
   1276   1.2    lneto '<code>\r</code>' (carriage return),
   1277   1.2    lneto '<code>\t</code>' (horizontal tab),
   1278   1.2    lneto '<code>\v</code>' (vertical tab),
   1279   1.2    lneto '<code>\\</code>' (backslash),
   1280   1.2    lneto '<code>\"</code>' (quotation mark [double quote]),
   1281   1.2    lneto and '<code>\'</code>' (apostrophe [single quote]).
   1282   1.7  mbalmer A backslash followed by a line break
   1283   1.2    lneto results in a newline in the string.
   1284   1.2    lneto The escape sequence '<code>\z</code>' skips the following span
   1285   1.9   nikita of whitespace characters,
   1286   1.2    lneto including line breaks;
   1287   1.2    lneto it is particularly useful to break and indent a long literal string
   1288   1.2    lneto into multiple lines without adding the newlines and spaces
   1289   1.2    lneto into the string contents.
   1290   1.7  mbalmer A short literal string cannot contain unescaped line breaks
   1291   1.7  mbalmer nor escapes not forming a valid escape sequence.
   1292   1.1  mbalmer 
   1293   1.1  mbalmer 
   1294   1.1  mbalmer <p>
   1295   1.9   nikita We can specify any byte in a short literal string,
   1296   1.9   nikita including embedded zeros,
   1297   1.9   nikita by its numeric value.
   1298   1.3    lneto This can be done
   1299   1.3    lneto with the escape sequence <code>\x<em>XX</em></code>,
   1300   1.2    lneto where <em>XX</em> is a sequence of exactly two hexadecimal digits,
   1301   1.2    lneto or with the escape sequence <code>\<em>ddd</em></code>,
   1302   1.2    lneto where <em>ddd</em> is a sequence of up to three decimal digits.
   1303   1.3    lneto (Note that if a decimal escape sequence is to be followed by a digit,
   1304   1.2    lneto it must be expressed using exactly three digits.)
   1305   1.1  mbalmer 
   1306   1.1  mbalmer 
   1307   1.2    lneto <p>
   1308   1.2    lneto The UTF-8 encoding of a Unicode character
   1309   1.2    lneto can be inserted in a literal string with
   1310   1.2    lneto the escape sequence <code>\u{<em>XXX</em>}</code>
   1311   1.9   nikita (with mandatory enclosing braces),
   1312   1.2    lneto where <em>XXX</em> is a sequence of one or more hexadecimal digits
   1313   1.2    lneto representing the character code point.
   1314   1.9   nikita This code point can be any value less than <em>2<sup>31</sup></em>.
   1315   1.9   nikita (Lua uses the original UTF-8 specification here,
   1316   1.9   nikita which is not restricted to valid Unicode code points.)
   1317   1.1  mbalmer 
   1318   1.1  mbalmer 
   1319   1.2    lneto <p>
   1320   1.2    lneto Literal strings can also be defined using a long format
   1321   1.2    lneto enclosed by <em>long brackets</em>.
   1322   1.2    lneto We define an <em>opening long bracket of level <em>n</em></em> as an opening
   1323   1.2    lneto square bracket followed by <em>n</em> equal signs followed by another
   1324   1.2    lneto opening square bracket.
   1325   1.2    lneto So, an opening long bracket of level&nbsp;0 is written as <code>[[</code>, 
   1326   1.2    lneto an opening long bracket of level&nbsp;1 is written as <code>[=[</code>, 
   1327   1.2    lneto and so on.
   1328   1.2    lneto A <em>closing long bracket</em> is defined similarly;
   1329   1.2    lneto for instance,
   1330   1.2    lneto a closing long bracket of level&nbsp;4 is written as  <code>]====]</code>.
   1331   1.2    lneto A <em>long literal</em> starts with an opening long bracket of any level and
   1332   1.2    lneto ends at the first closing long bracket of the same level.
   1333   1.3    lneto It can contain any text except a closing bracket of the same level.
   1334   1.2    lneto Literals in this bracketed form can run for several lines,
   1335   1.2    lneto do not interpret any escape sequences,
   1336   1.2    lneto and ignore long brackets of any other level.
   1337   1.2    lneto Any kind of end-of-line sequence
   1338   1.2    lneto (carriage return, newline, carriage return followed by newline,
   1339   1.2    lneto or newline followed by carriage return)
   1340   1.2    lneto is converted to a simple newline.
   1341   1.9   nikita When the opening long bracket is immediately followed by a newline,
   1342   1.9   nikita the newline is not included in the string.
   1343   1.1  mbalmer 
   1344   1.1  mbalmer 
   1345   1.2    lneto <p>
   1346   1.2    lneto As an example, in a system using ASCII
   1347   1.2    lneto (in which '<code>a</code>' is coded as&nbsp;97,
   1348   1.2    lneto newline is coded as&nbsp;10, and '<code>1</code>' is coded as&nbsp;49),
   1349   1.2    lneto the five literal strings below denote the same string:
   1350   1.1  mbalmer 
   1351   1.1  mbalmer <pre>
   1352   1.2    lneto      a = 'alo\n123"'
   1353   1.2    lneto      a = "alo\n123\""
   1354   1.2    lneto      a = '\97lo\10\04923"'
   1355   1.2    lneto      a = [[alo
   1356   1.2    lneto      123"]]
   1357   1.2    lneto      a = [==[
   1358   1.2    lneto      alo
   1359   1.2    lneto      123"]==]
   1360   1.1  mbalmer </pre>
   1361   1.1  mbalmer 
   1362   1.1  mbalmer <p>
   1363   1.7  mbalmer Any byte in a literal string not
   1364   1.7  mbalmer explicitly affected by the previous rules represents itself.
   1365   1.7  mbalmer However, Lua opens files for parsing in text mode,
   1366   1.9   nikita and the system's file functions may have problems with
   1367   1.7  mbalmer some control characters.
   1368   1.7  mbalmer So, it is safer to represent
   1369   1.9   nikita binary data as a quoted literal with
   1370   1.7  mbalmer explicit escape sequences for the non-text characters.
   1371   1.7  mbalmer 
   1372   1.7  mbalmer 
   1373   1.7  mbalmer <p>
   1374   1.4  mbalmer A <em>numeric constant</em> (or <em>numeral</em>)
   1375   1.3    lneto can be written with an optional fractional part
   1376   1.2    lneto and an optional decimal exponent,
   1377   1.2    lneto marked by a letter '<code>e</code>' or '<code>E</code>'.
   1378   1.2    lneto Lua also accepts hexadecimal constants,
   1379   1.2    lneto which start with <code>0x</code> or <code>0X</code>.
   1380   1.2    lneto Hexadecimal constants also accept an optional fractional part
   1381   1.2    lneto plus an optional binary exponent,
   1382  1.10   nikita marked by a letter '<code>p</code>' or '<code>P</code>' and written in decimal.
   1383  1.10   nikita (For instance, <code>0x1.fp10</code> denotes 1984,
   1384  1.10   nikita which is <em>0x1f / 16</em> multiplied by <em>2<sup>10</sup></em>.)
   1385   1.9   nikita 
   1386   1.9   nikita 
   1387   1.9   nikita <p>
   1388   1.7  mbalmer A numeric constant with a radix point or an exponent
   1389   1.2    lneto denotes a float;
   1390   1.6  salazar otherwise,
   1391   1.9   nikita if its value fits in an integer or it is a hexadecimal constant,
   1392   1.9   nikita it denotes an integer;
   1393   1.9   nikita otherwise (that is, a decimal integer numeral that overflows),
   1394   1.9   nikita it denotes a float.
   1395   1.9   nikita Hexadecimal numerals with neither a radix point nor an exponent
   1396   1.9   nikita always denote an integer value;
   1397   1.9   nikita if the value overflows, it <em>wraps around</em>
   1398   1.9   nikita to fit into a valid integer.
   1399   1.9   nikita 
   1400   1.9   nikita 
   1401   1.9   nikita <p>
   1402   1.2    lneto Examples of valid integer constants are
   1403   1.1  mbalmer 
   1404   1.1  mbalmer <pre>
   1405   1.2    lneto      3   345   0xff   0xBEBADA
   1406   1.1  mbalmer </pre><p>
   1407   1.2    lneto Examples of valid float constants are
   1408   1.1  mbalmer 
   1409   1.1  mbalmer <pre>
   1410   1.2    lneto      3.0     3.1416     314.16e-2     0.31416E1     34e1
   1411   1.2    lneto      0x0.1E  0xA23p-4   0X1.921FB54442D18P+1
   1412   1.1  mbalmer </pre>
   1413   1.1  mbalmer 
   1414   1.1  mbalmer <p>
   1415   1.2    lneto A <em>comment</em> starts with a double hyphen (<code>--</code>)
   1416   1.2    lneto anywhere outside a string.
   1417   1.2    lneto If the text immediately after <code>--</code> is not an opening long bracket,
   1418   1.2    lneto the comment is a <em>short comment</em>,
   1419   1.2    lneto which runs until the end of the line.
   1420   1.2    lneto Otherwise, it is a <em>long comment</em>,
   1421   1.2    lneto which runs until the corresponding closing long bracket.
   1422   1.2    lneto 
   1423   1.1  mbalmer 
   1424   1.1  mbalmer 
   1425   1.1  mbalmer 
   1426   1.1  mbalmer 
   1427   1.2    lneto <h2>3.2 &ndash; <a name="3.2">Variables</a></h2>
   1428   1.1  mbalmer 
   1429   1.2    lneto <p>
   1430   1.2    lneto Variables are places that store values.
   1431   1.2    lneto There are three kinds of variables in Lua:
   1432   1.2    lneto global variables, local variables, and table fields.
   1433   1.1  mbalmer 
   1434   1.1  mbalmer 
   1435   1.2    lneto <p>
   1436   1.2    lneto A single name can denote a global variable or a local variable
   1437   1.2    lneto (or a function's formal parameter,
   1438   1.2    lneto which is a particular kind of local variable):
   1439   1.1  mbalmer 
   1440   1.1  mbalmer <pre>
   1441   1.2    lneto 	var ::= Name
   1442   1.1  mbalmer </pre><p>
   1443   1.9   nikita Name denotes identifiers (see <a href="#3.1">&sect;3.1</a>).
   1444   1.1  mbalmer 
   1445   1.1  mbalmer 
   1446   1.1  mbalmer <p>
   1447   1.2    lneto Any variable name is assumed to be global unless explicitly declared
   1448   1.2    lneto as a local (see <a href="#3.3.7">&sect;3.3.7</a>).
   1449   1.2    lneto Local variables are <em>lexically scoped</em>:
   1450   1.2    lneto local variables can be freely accessed by functions
   1451   1.2    lneto defined inside their scope (see <a href="#3.5">&sect;3.5</a>).
   1452   1.2    lneto 
   1453   1.1  mbalmer 
   1454   1.2    lneto <p>
   1455   1.2    lneto Before the first assignment to a variable, its value is <b>nil</b>.
   1456   1.1  mbalmer 
   1457   1.1  mbalmer 
   1458   1.1  mbalmer <p>
   1459   1.2    lneto Square brackets are used to index a table:
   1460   1.1  mbalmer 
   1461   1.1  mbalmer <pre>
   1462   1.2    lneto 	var ::= prefixexp &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo;
   1463   1.1  mbalmer </pre><p>
   1464   1.8    alnsn The meaning of accesses to table fields can be changed via metatables
   1465   1.8    alnsn (see <a href="#2.4">&sect;2.4</a>).
   1466   1.1  mbalmer 
   1467   1.1  mbalmer 
   1468   1.1  mbalmer <p>
   1469   1.2    lneto The syntax <code>var.Name</code> is just syntactic sugar for
   1470   1.2    lneto <code>var["Name"]</code>:
   1471   1.1  mbalmer 
   1472   1.1  mbalmer <pre>
   1473   1.2    lneto 	var ::= prefixexp &lsquo;<b>.</b>&rsquo; Name
   1474   1.2    lneto </pre>
   1475   1.1  mbalmer 
   1476   1.1  mbalmer <p>
   1477   1.2    lneto An access to a global variable <code>x</code>
   1478   1.2    lneto is equivalent to <code>_ENV.x</code>.
   1479   1.2    lneto Due to the way that chunks are compiled,
   1480   1.9   nikita the variable <code>_ENV</code> itself is never global (see <a href="#2.2">&sect;2.2</a>).
   1481   1.1  mbalmer 
   1482   1.1  mbalmer 
   1483   1.1  mbalmer 
   1484   1.1  mbalmer 
   1485   1.1  mbalmer 
   1486   1.2    lneto <h2>3.3 &ndash; <a name="3.3">Statements</a></h2>
   1487   1.1  mbalmer 
   1488   1.9   nikita 
   1489   1.9   nikita 
   1490   1.1  mbalmer <p>
   1491   1.2    lneto Lua supports an almost conventional set of statements,
   1492   1.9   nikita similar to those in other conventional languages.
   1493   1.2    lneto This set includes
   1494   1.9   nikita blocks, assignments, control structures, function calls,
   1495   1.2    lneto and variable declarations.
   1496   1.2    lneto 
   1497   1.2    lneto 
   1498   1.1  mbalmer 
   1499   1.9   nikita 
   1500   1.9   nikita 
   1501   1.2    lneto <h3>3.3.1 &ndash; <a name="3.3.1">Blocks</a></h3>
   1502   1.1  mbalmer 
   1503   1.1  mbalmer <p>
   1504   1.2    lneto A block is a list of statements,
   1505   1.2    lneto which are executed sequentially:
   1506   1.1  mbalmer 
   1507   1.1  mbalmer <pre>
   1508   1.2    lneto 	block ::= {stat}
   1509   1.1  mbalmer </pre><p>
   1510   1.2    lneto Lua has <em>empty statements</em>
   1511   1.2    lneto that allow you to separate statements with semicolons,
   1512   1.2    lneto start a block with a semicolon
   1513   1.2    lneto or write two semicolons in sequence:
   1514   1.1  mbalmer 
   1515   1.1  mbalmer <pre>
   1516   1.2    lneto 	stat ::= &lsquo;<b>;</b>&rsquo;
   1517   1.2    lneto </pre>
   1518   1.2    lneto 
   1519   1.2    lneto <p>
   1520   1.9   nikita Both function calls and assignments
   1521   1.2    lneto can start with an open parenthesis.
   1522   1.2    lneto This possibility leads to an ambiguity in Lua's grammar.
   1523   1.2    lneto Consider the following fragment:
   1524   1.1  mbalmer 
   1525   1.1  mbalmer <pre>
   1526   1.2    lneto      a = b + c
   1527   1.2    lneto      (print or io.write)('done')
   1528   1.1  mbalmer </pre><p>
   1529   1.9   nikita The grammar could see this fragment in two ways:
   1530   1.1  mbalmer 
   1531   1.1  mbalmer <pre>
   1532   1.2    lneto      a = b + c(print or io.write)('done')
   1533   1.2    lneto      
   1534   1.2    lneto      a = b + c; (print or io.write)('done')
   1535   1.1  mbalmer </pre><p>
   1536   1.2    lneto The current parser always sees such constructions
   1537   1.2    lneto in the first way,
   1538   1.2    lneto interpreting the open parenthesis
   1539   1.2    lneto as the start of the arguments to a call.
   1540   1.2    lneto To avoid this ambiguity,
   1541   1.2    lneto it is a good practice to always precede with a semicolon
   1542   1.2    lneto statements that start with a parenthesis:
   1543   1.1  mbalmer 
   1544   1.1  mbalmer <pre>
   1545   1.2    lneto      ;(print or io.write)('done')
   1546   1.2    lneto </pre>
   1547   1.2    lneto 
   1548   1.2    lneto <p>
   1549   1.2    lneto A block can be explicitly delimited to produce a single statement:
   1550   1.1  mbalmer 
   1551   1.1  mbalmer <pre>
   1552   1.2    lneto 	stat ::= <b>do</b> block <b>end</b>
   1553   1.1  mbalmer </pre><p>
   1554   1.2    lneto Explicit blocks are useful
   1555   1.2    lneto to control the scope of variable declarations.
   1556   1.2    lneto Explicit blocks are also sometimes used to
   1557   1.2    lneto add a <b>return</b> statement in the middle
   1558   1.2    lneto of another block (see <a href="#3.3.4">&sect;3.3.4</a>).
   1559   1.2    lneto 
   1560   1.2    lneto 
   1561   1.2    lneto 
   1562   1.2    lneto 
   1563   1.2    lneto 
   1564   1.2    lneto <h3>3.3.2 &ndash; <a name="3.3.2">Chunks</a></h3>
   1565   1.2    lneto 
   1566   1.2    lneto <p>
   1567   1.2    lneto The unit of compilation of Lua is called a <em>chunk</em>.
   1568   1.2    lneto Syntactically,
   1569   1.2    lneto a chunk is simply a block:
   1570   1.1  mbalmer 
   1571   1.1  mbalmer <pre>
   1572   1.2    lneto 	chunk ::= block
   1573   1.2    lneto </pre>
   1574   1.1  mbalmer 
   1575   1.2    lneto <p>
   1576   1.2    lneto Lua handles a chunk as the body of an anonymous function
   1577   1.2    lneto with a variable number of arguments
   1578   1.2    lneto (see <a href="#3.4.11">&sect;3.4.11</a>).
   1579   1.2    lneto As such, chunks can define local variables,
   1580   1.2    lneto receive arguments, and return values.
   1581   1.2    lneto Moreover, such anonymous function is compiled as in the
   1582   1.2    lneto scope of an external local variable called <code>_ENV</code> (see <a href="#2.2">&sect;2.2</a>).
   1583   1.9   nikita The resulting function always has <code>_ENV</code> as its only external variable,
   1584   1.2    lneto even if it does not use that variable.
   1585   1.1  mbalmer 
   1586   1.1  mbalmer 
   1587   1.1  mbalmer <p>
   1588   1.2    lneto A chunk can be stored in a file or in a string inside the host program.
   1589   1.2    lneto To execute a chunk,
   1590   1.3    lneto Lua first <em>loads</em> it,
   1591   1.3    lneto precompiling the chunk's code into instructions for a virtual machine,
   1592   1.3    lneto and then Lua executes the compiled code
   1593   1.2    lneto with an interpreter for the virtual machine.
   1594   1.1  mbalmer 
   1595   1.1  mbalmer 
   1596   1.1  mbalmer <p>
   1597   1.2    lneto Chunks can also be precompiled into binary form;
   1598   1.9   nikita see the program <code>luac</code> and the function <a href="#pdf-string.dump"><code>string.dump</code></a> for details.
   1599   1.2    lneto Programs in source and compiled forms are interchangeable;
   1600   1.2    lneto Lua automatically detects the file type and acts accordingly (see <a href="#pdf-load"><code>load</code></a>).
   1601   1.2    lneto 
   1602   1.2    lneto 
   1603   1.2    lneto 
   1604   1.1  mbalmer 
   1605   1.1  mbalmer 
   1606   1.2    lneto <h3>3.3.3 &ndash; <a name="3.3.3">Assignment</a></h3>
   1607   1.1  mbalmer 
   1608   1.1  mbalmer <p>
   1609   1.2    lneto Lua allows multiple assignments.
   1610   1.2    lneto Therefore, the syntax for assignment
   1611   1.2    lneto defines a list of variables on the left side
   1612   1.2    lneto and a list of expressions on the right side.
   1613   1.2    lneto The elements in both lists are separated by commas:
   1614   1.1  mbalmer 
   1615   1.1  mbalmer <pre>
   1616   1.2    lneto 	stat ::= varlist &lsquo;<b>=</b>&rsquo; explist
   1617   1.2    lneto 	varlist ::= var {&lsquo;<b>,</b>&rsquo; var}
   1618   1.2    lneto 	explist ::= exp {&lsquo;<b>,</b>&rsquo; exp}
   1619   1.1  mbalmer </pre><p>
   1620   1.2    lneto Expressions are discussed in <a href="#3.4">&sect;3.4</a>.
   1621   1.1  mbalmer 
   1622   1.1  mbalmer 
   1623   1.1  mbalmer <p>
   1624   1.2    lneto Before the assignment,
   1625   1.2    lneto the list of values is <em>adjusted</em> to the length of
   1626  1.10   nikita the list of variables (see <a href="#3.4.12">&sect;3.4.12</a>).
   1627   1.1  mbalmer 
   1628   1.1  mbalmer 
   1629   1.1  mbalmer <p>
   1630   1.9   nikita If a variable is both assigned and read
   1631   1.9   nikita inside a multiple assignment,
   1632  1.10   nikita Lua ensures that all reads get the value of the variable
   1633   1.9   nikita before the assignment.
   1634   1.2    lneto Thus the code
   1635   1.1  mbalmer 
   1636   1.1  mbalmer <pre>
   1637   1.2    lneto      i = 3
   1638   1.2    lneto      i, a[i] = i+1, 20
   1639   1.1  mbalmer </pre><p>
   1640   1.2    lneto sets <code>a[3]</code> to 20, without affecting <code>a[4]</code>
   1641   1.2    lneto because the <code>i</code> in <code>a[i]</code> is evaluated (to 3)
   1642   1.2    lneto before it is assigned&nbsp;4.
   1643   1.2    lneto Similarly, the line
   1644   1.1  mbalmer 
   1645   1.1  mbalmer <pre>
   1646   1.2    lneto      x, y = y, x
   1647   1.2    lneto </pre><p>
   1648   1.2    lneto exchanges the values of <code>x</code> and <code>y</code>,
   1649   1.2    lneto and
   1650   1.1  mbalmer 
   1651   1.2    lneto <pre>
   1652   1.2    lneto      x, y, z = y, z, x
   1653   1.2    lneto </pre><p>
   1654   1.2    lneto cyclically permutes the values of <code>x</code>, <code>y</code>, and <code>z</code>.
   1655   1.1  mbalmer 
   1656   1.1  mbalmer 
   1657   1.2    lneto <p>
   1658   1.9   nikita Note that this guarantee covers only accesses
   1659   1.9   nikita syntactically inside the assignment statement.
   1660   1.9   nikita If a function or a metamethod called during the assignment
   1661   1.9   nikita changes the value of a variable,
   1662   1.9   nikita Lua gives no guarantees about the order of that access.
   1663   1.9   nikita 
   1664   1.9   nikita 
   1665   1.9   nikita <p>
   1666   1.8    alnsn An assignment to a global name <code>x = val</code>
   1667   1.8    alnsn is equivalent to the assignment
   1668   1.8    alnsn <code>_ENV.x = val</code> (see <a href="#2.2">&sect;2.2</a>).
   1669   1.1  mbalmer 
   1670   1.1  mbalmer 
   1671   1.2    lneto <p>
   1672   1.8    alnsn The meaning of assignments to table fields and
   1673   1.8    alnsn global variables (which are actually table fields, too)
   1674   1.8    alnsn can be changed via metatables (see <a href="#2.4">&sect;2.4</a>).
   1675   1.1  mbalmer 
   1676   1.1  mbalmer 
   1677   1.1  mbalmer 
   1678   1.1  mbalmer 
   1679   1.1  mbalmer 
   1680   1.2    lneto <h3>3.3.4 &ndash; <a name="3.3.4">Control Structures</a></h3><p>
   1681   1.2    lneto The control structures
   1682   1.2    lneto <b>if</b>, <b>while</b>, and <b>repeat</b> have the usual meaning and
   1683   1.2    lneto familiar syntax:
   1684   1.1  mbalmer 
   1685   1.1  mbalmer 
   1686   1.1  mbalmer 
   1687   1.1  mbalmer 
   1688   1.1  mbalmer <pre>
   1689   1.2    lneto 	stat ::= <b>while</b> exp <b>do</b> block <b>end</b>
   1690   1.2    lneto 	stat ::= <b>repeat</b> block <b>until</b> exp
   1691   1.2    lneto 	stat ::= <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b>
   1692   1.1  mbalmer </pre><p>
   1693   1.2    lneto Lua also has a <b>for</b> statement, in two flavors (see <a href="#3.3.5">&sect;3.3.5</a>).
   1694   1.1  mbalmer 
   1695   1.1  mbalmer 
   1696   1.2    lneto <p>
   1697   1.2    lneto The condition expression of a
   1698   1.2    lneto control structure can return any value.
   1699   1.9   nikita Both <b>false</b> and <b>nil</b> test false.
   1700   1.9   nikita All values different from <b>nil</b> and <b>false</b> test true.
   1701   1.9   nikita In particular, the number 0 and the empty string also test true.
   1702   1.1  mbalmer 
   1703   1.1  mbalmer 
   1704   1.1  mbalmer <p>
   1705   1.2    lneto In the <b>repeat</b>&ndash;<b>until</b> loop,
   1706   1.2    lneto the inner block does not end at the <b>until</b> keyword,
   1707   1.2    lneto but only after the condition.
   1708   1.2    lneto So, the condition can refer to local variables
   1709   1.2    lneto declared inside the loop block.
   1710   1.1  mbalmer 
   1711   1.1  mbalmer 
   1712   1.1  mbalmer <p>
   1713   1.2    lneto The <b>goto</b> statement transfers the program control to a label.
   1714   1.2    lneto For syntactical reasons,
   1715   1.2    lneto labels in Lua are considered statements too:
   1716   1.1  mbalmer 
   1717   1.1  mbalmer 
   1718   1.1  mbalmer 
   1719   1.2    lneto <pre>
   1720   1.2    lneto 	stat ::= <b>goto</b> Name
   1721   1.2    lneto 	stat ::= label
   1722   1.2    lneto 	label ::= &lsquo;<b>::</b>&rsquo; Name &lsquo;<b>::</b>&rsquo;
   1723   1.2    lneto </pre>
   1724   1.1  mbalmer 
   1725   1.1  mbalmer <p>
   1726   1.2    lneto A label is visible in the entire block where it is defined,
   1727   1.9   nikita except inside nested functions.
   1728   1.2    lneto A goto may jump to any visible label as long as it does not
   1729   1.2    lneto enter into the scope of a local variable.
   1730   1.9   nikita A label should not be declared
   1731   1.9   nikita where a label with the same name is visible,
   1732   1.9   nikita even if this other label has been declared in an enclosing block.
   1733   1.1  mbalmer 
   1734   1.1  mbalmer 
   1735   1.1  mbalmer <p>
   1736   1.2    lneto The <b>break</b> statement terminates the execution of a
   1737   1.2    lneto <b>while</b>, <b>repeat</b>, or <b>for</b> loop,
   1738   1.2    lneto skipping to the next statement after the loop:
   1739   1.1  mbalmer 
   1740   1.1  mbalmer 
   1741   1.2    lneto <pre>
   1742   1.2    lneto 	stat ::= <b>break</b>
   1743   1.2    lneto </pre><p>
   1744   1.2    lneto A <b>break</b> ends the innermost enclosing loop.
   1745   1.1  mbalmer 
   1746   1.1  mbalmer 
   1747   1.1  mbalmer <p>
   1748   1.2    lneto The <b>return</b> statement is used to return values
   1749   1.3    lneto from a function or a chunk
   1750   1.9   nikita (which is handled as an anonymous function).
   1751   1.1  mbalmer 
   1752   1.2    lneto Functions can return more than one value,
   1753   1.2    lneto so the syntax for the <b>return</b> statement is
   1754   1.1  mbalmer 
   1755   1.2    lneto <pre>
   1756   1.2    lneto 	stat ::= <b>return</b> [explist] [&lsquo;<b>;</b>&rsquo;]
   1757   1.2    lneto </pre>
   1758   1.1  mbalmer 
   1759   1.1  mbalmer <p>
   1760   1.2    lneto The <b>return</b> statement can only be written
   1761   1.2    lneto as the last statement of a block.
   1762   1.9   nikita If it is necessary to <b>return</b> in the middle of a block,
   1763   1.2    lneto then an explicit inner block can be used,
   1764   1.2    lneto as in the idiom <code>do return end</code>,
   1765   1.2    lneto because now <b>return</b> is the last statement in its (inner) block.
   1766   1.1  mbalmer 
   1767   1.1  mbalmer 
   1768   1.1  mbalmer 
   1769   1.1  mbalmer 
   1770   1.1  mbalmer 
   1771   1.2    lneto <h3>3.3.5 &ndash; <a name="3.3.5">For Statement</a></h3>
   1772   1.1  mbalmer 
   1773   1.2    lneto <p>
   1774   1.1  mbalmer 
   1775   1.2    lneto The <b>for</b> statement has two forms:
   1776   1.4  mbalmer one numerical and one generic.
   1777   1.1  mbalmer 
   1778   1.1  mbalmer 
   1779   1.9   nikita 
   1780   1.9   nikita <h4>The numerical <b>for</b> loop</h4>
   1781   1.9   nikita 
   1782   1.2    lneto <p>
   1783   1.4  mbalmer The numerical <b>for</b> loop repeats a block of code while a
   1784   1.9   nikita control variable goes through an arithmetic progression.
   1785   1.2    lneto It has the following syntax:
   1786   1.1  mbalmer 
   1787   1.2    lneto <pre>
   1788   1.2    lneto 	stat ::= <b>for</b> Name &lsquo;<b>=</b>&rsquo; exp &lsquo;<b>,</b>&rsquo; exp [&lsquo;<b>,</b>&rsquo; exp] <b>do</b> block <b>end</b>
   1789   1.2    lneto </pre><p>
   1790   1.9   nikita The given identifier (Name) defines the control variable,
   1791   1.9   nikita which is a new variable local to the loop body (<em>block</em>).
   1792   1.1  mbalmer 
   1793   1.1  mbalmer 
   1794   1.9   nikita <p>
   1795   1.9   nikita The loop starts by evaluating once the three control expressions.
   1796   1.9   nikita Their values are called respectively
   1797   1.9   nikita the <em>initial value</em>, the <em>limit</em>, and the <em>step</em>.
   1798   1.9   nikita If the step is absent, it defaults to&nbsp;1.
   1799   1.9   nikita 
   1800   1.2    lneto 
   1801   1.2    lneto <p>
   1802   1.9   nikita If both the initial value and the step are integers,
   1803   1.9   nikita the loop is done with integers;
   1804   1.9   nikita note that the limit may not be an integer.
   1805   1.9   nikita Otherwise, the three values are converted to
   1806   1.9   nikita floats and the loop is done with floats.
   1807   1.9   nikita Beware of floating-point accuracy in this case.
   1808   1.1  mbalmer 
   1809   1.1  mbalmer 
   1810   1.9   nikita <p>
   1811   1.9   nikita After that initialization,
   1812   1.9   nikita the loop body is repeated with the value of the control variable
   1813   1.9   nikita going through an arithmetic progression,
   1814   1.9   nikita starting at the initial value,
   1815   1.9   nikita with a common difference given by the step.
   1816   1.9   nikita A negative step makes a decreasing sequence;
   1817   1.9   nikita a step equal to zero raises an error.
   1818   1.9   nikita The loop continues while the value is less than
   1819   1.9   nikita or equal to the limit
   1820   1.9   nikita (greater than or equal to for a negative step).
   1821   1.9   nikita If the initial value is already greater than the limit
   1822   1.9   nikita (or less than, if the step is negative),
   1823   1.9   nikita the body is not executed.
   1824   1.1  mbalmer 
   1825   1.1  mbalmer 
   1826   1.9   nikita <p>
   1827   1.9   nikita For integer loops,
   1828   1.9   nikita the control variable never wraps around;
   1829   1.9   nikita instead, the loop ends in case of an overflow.
   1830   1.1  mbalmer 
   1831   1.1  mbalmer 
   1832   1.9   nikita <p>
   1833   1.9   nikita You should not change the value of the control variable
   1834   1.9   nikita during the loop.
   1835   1.2    lneto If you need its value after the loop,
   1836   1.2    lneto assign it to another variable before exiting the loop.
   1837   1.1  mbalmer 
   1838   1.9   nikita 
   1839   1.9   nikita 
   1840   1.9   nikita 
   1841   1.9   nikita 
   1842   1.9   nikita <h4>The generic <b>for</b> loop</h4>
   1843   1.1  mbalmer 
   1844   1.2    lneto <p>
   1845   1.2    lneto The generic <b>for</b> statement works over functions,
   1846   1.2    lneto called <em>iterators</em>.
   1847   1.2    lneto On each iteration, the iterator function is called to produce a new value,
   1848   1.2    lneto stopping when this new value is <b>nil</b>.
   1849   1.2    lneto The generic <b>for</b> loop has the following syntax:
   1850   1.1  mbalmer 
   1851   1.2    lneto <pre>
   1852   1.2    lneto 	stat ::= <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b>
   1853   1.2    lneto 	namelist ::= Name {&lsquo;<b>,</b>&rsquo; Name}
   1854   1.2    lneto </pre><p>
   1855   1.2    lneto A <b>for</b> statement like
   1856   1.1  mbalmer 
   1857   1.2    lneto <pre>
   1858   1.9   nikita      for <em>var_1</em>, &middot;&middot;&middot;, <em>var_n</em> in <em>explist</em> do <em>body</em> end
   1859   1.2    lneto </pre><p>
   1860   1.9   nikita works as follows.
   1861   1.9   nikita 
   1862   1.1  mbalmer 
   1863   1.9   nikita <p>
   1864   1.9   nikita The names <em>var_i</em> declare loop variables local to the loop body.
   1865   1.9   nikita The first of these variables is the <em>control variable</em>.
   1866   1.2    lneto 
   1867   1.2    lneto 
   1868   1.9   nikita <p>
   1869   1.9   nikita The loop starts by evaluating <em>explist</em>
   1870   1.9   nikita to produce four values:
   1871   1.9   nikita an <em>iterator function</em>,
   1872   1.2    lneto a <em>state</em>,
   1873   1.9   nikita an initial value for the control variable,
   1874   1.9   nikita and a <em>closing value</em>.
   1875   1.9   nikita 
   1876   1.9   nikita 
   1877   1.9   nikita <p>
   1878   1.9   nikita Then, at each iteration,
   1879   1.9   nikita Lua calls the iterator function with two arguments:
   1880   1.9   nikita the state and the control variable.
   1881   1.9   nikita The results from this call are then assigned to the loop variables,
   1882   1.9   nikita following the rules of multiple assignments (see <a href="#3.3.3">&sect;3.3.3</a>).
   1883   1.9   nikita If the control variable becomes <b>nil</b>,
   1884   1.9   nikita the loop terminates.
   1885   1.9   nikita Otherwise, the body is executed and the loop goes
   1886   1.9   nikita to the next iteration.
   1887   1.9   nikita 
   1888   1.9   nikita 
   1889   1.9   nikita <p>
   1890   1.9   nikita The closing value behaves like a
   1891   1.9   nikita to-be-closed variable (see <a href="#3.3.8">&sect;3.3.8</a>),
   1892   1.9   nikita which can be used to release resources when the loop ends.
   1893   1.9   nikita Otherwise, it does not interfere with the loop.
   1894   1.9   nikita 
   1895   1.1  mbalmer 
   1896   1.9   nikita <p>
   1897   1.9   nikita You should not change the value of the control variable
   1898   1.9   nikita during the loop.
   1899   1.1  mbalmer 
   1900   1.1  mbalmer 
   1901   1.1  mbalmer 
   1902   1.2    lneto 
   1903   1.2    lneto 
   1904   1.1  mbalmer 
   1905   1.1  mbalmer 
   1906   1.2    lneto <h3>3.3.6 &ndash; <a name="3.3.6">Function Calls as Statements</a></h3><p>
   1907   1.2    lneto To allow possible side-effects,
   1908   1.2    lneto function calls can be executed as statements:
   1909   1.2    lneto 
   1910   1.1  mbalmer <pre>
   1911   1.2    lneto 	stat ::= functioncall
   1912   1.1  mbalmer </pre><p>
   1913   1.2    lneto In this case, all returned values are thrown away.
   1914   1.2    lneto Function calls are explained in <a href="#3.4.10">&sect;3.4.10</a>.
   1915   1.2    lneto 
   1916   1.2    lneto 
   1917   1.2    lneto 
   1918   1.1  mbalmer 
   1919   1.1  mbalmer 
   1920   1.2    lneto <h3>3.3.7 &ndash; <a name="3.3.7">Local Declarations</a></h3><p>
   1921   1.2    lneto Local variables can be declared anywhere inside a block.
   1922   1.9   nikita The declaration can include an initialization:
   1923   1.1  mbalmer 
   1924   1.1  mbalmer <pre>
   1925   1.9   nikita 	stat ::= <b>local</b> attnamelist [&lsquo;<b>=</b>&rsquo; explist]
   1926   1.9   nikita 	attnamelist ::=  Name attrib {&lsquo;<b>,</b>&rsquo; Name attrib}
   1927   1.1  mbalmer </pre><p>
   1928   1.2    lneto If present, an initial assignment has the same semantics
   1929   1.2    lneto of a multiple assignment (see <a href="#3.3.3">&sect;3.3.3</a>).
   1930   1.2    lneto Otherwise, all variables are initialized with <b>nil</b>.
   1931   1.2    lneto 
   1932   1.2    lneto 
   1933   1.2    lneto <p>
   1934   1.9   nikita Each variable name may be postfixed by an attribute
   1935   1.9   nikita (a name between angle brackets):
   1936   1.9   nikita 
   1937   1.9   nikita <pre>
   1938   1.9   nikita 	attrib ::= [&lsquo;<b>&lt;</b>&rsquo; Name &lsquo;<b>&gt;</b>&rsquo;]
   1939   1.9   nikita </pre><p>
   1940   1.9   nikita There are two possible attributes:
   1941   1.9   nikita <code>const</code>, which declares a constant variable,
   1942   1.9   nikita that is, a variable that cannot be assigned to
   1943   1.9   nikita after its initialization;
   1944   1.9   nikita and <code>close</code>, which declares a to-be-closed variable (see <a href="#3.3.8">&sect;3.3.8</a>).
   1945   1.9   nikita A list of variables can contain at most one to-be-closed variable.
   1946   1.9   nikita 
   1947   1.9   nikita 
   1948   1.9   nikita <p>
   1949   1.2    lneto A chunk is also a block (see <a href="#3.3.2">&sect;3.3.2</a>),
   1950   1.2    lneto and so local variables can be declared in a chunk outside any explicit block.
   1951   1.1  mbalmer 
   1952   1.1  mbalmer 
   1953   1.2    lneto <p>
   1954   1.2    lneto The visibility rules for local variables are explained in <a href="#3.5">&sect;3.5</a>.
   1955   1.2    lneto 
   1956   1.1  mbalmer 
   1957   1.1  mbalmer 
   1958   1.1  mbalmer 
   1959   1.1  mbalmer 
   1960   1.9   nikita <h3>3.3.8 &ndash; <a name="3.3.8">To-be-closed Variables</a></h3>
   1961   1.9   nikita 
   1962   1.9   nikita <p>
   1963   1.9   nikita A to-be-closed variable behaves like a constant local variable,
   1964   1.9   nikita except that its value is <em>closed</em> whenever the variable
   1965   1.9   nikita goes out of scope, including normal block termination,
   1966   1.9   nikita exiting its block by <b>break</b>/<b>goto</b>/<b>return</b>,
   1967   1.9   nikita or exiting by an error.
   1968   1.9   nikita 
   1969   1.9   nikita 
   1970   1.9   nikita <p>
   1971   1.9   nikita Here, to <em>close</em> a value means
   1972   1.9   nikita to call its <code>__close</code> metamethod.
   1973   1.9   nikita When calling the metamethod,
   1974   1.9   nikita the value itself is passed as the first argument
   1975   1.9   nikita and the error object that caused the exit (if any)
   1976   1.9   nikita is passed as a second argument;
   1977   1.9   nikita if there was no error, the second argument is <b>nil</b>.
   1978   1.9   nikita 
   1979   1.9   nikita 
   1980   1.9   nikita <p>
   1981   1.9   nikita The value assigned to a to-be-closed variable
   1982   1.9   nikita must have a <code>__close</code> metamethod
   1983   1.9   nikita or be a false value.
   1984   1.9   nikita (<b>nil</b> and <b>false</b> are ignored as to-be-closed values.)
   1985   1.9   nikita 
   1986   1.9   nikita 
   1987   1.9   nikita <p>
   1988   1.9   nikita If several to-be-closed variables go out of scope at the same event,
   1989   1.9   nikita they are closed in the reverse order that they were declared.
   1990   1.9   nikita 
   1991   1.9   nikita 
   1992   1.9   nikita <p>
   1993   1.9   nikita If there is any error while running a closing method,
   1994   1.9   nikita that error is handled like an error in the regular code
   1995   1.9   nikita where the variable was defined.
   1996   1.9   nikita After an error,
   1997   1.9   nikita the other pending closing methods will still be called.
   1998   1.9   nikita 
   1999   1.9   nikita 
   2000   1.9   nikita <p>
   2001   1.9   nikita If a coroutine yields and is never resumed again,
   2002   1.9   nikita some variables may never go out of scope,
   2003   1.9   nikita and therefore they will never be closed.
   2004   1.9   nikita (These variables are the ones created inside the coroutine
   2005   1.9   nikita and in scope at the point where the coroutine yielded.)
   2006   1.9   nikita Similarly, if a coroutine ends with an error,
   2007   1.9   nikita it does not unwind its stack,
   2008   1.9   nikita so it does not close any variable.
   2009   1.9   nikita In both cases,
   2010   1.9   nikita you can either use finalizers
   2011   1.9   nikita or call <a href="#pdf-coroutine.close"><code>coroutine.close</code></a> to close the variables.
   2012   1.9   nikita However, if the coroutine was created
   2013   1.9   nikita through <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a>,
   2014   1.9   nikita then its corresponding function will close the coroutine
   2015   1.9   nikita in case of errors.
   2016   1.9   nikita 
   2017   1.9   nikita 
   2018   1.9   nikita 
   2019   1.9   nikita 
   2020   1.9   nikita 
   2021   1.1  mbalmer 
   2022   1.1  mbalmer 
   2023   1.2    lneto <h2>3.4 &ndash; <a name="3.4">Expressions</a></h2>
   2024   1.1  mbalmer 
   2025   1.9   nikita 
   2026   1.9   nikita 
   2027   1.2    lneto <p>
   2028   1.2    lneto The basic expressions in Lua are the following:
   2029   1.1  mbalmer 
   2030   1.1  mbalmer <pre>
   2031   1.2    lneto 	exp ::= prefixexp
   2032   1.2    lneto 	exp ::= <b>nil</b> | <b>false</b> | <b>true</b>
   2033   1.3    lneto 	exp ::= Numeral
   2034   1.3    lneto 	exp ::= LiteralString
   2035   1.2    lneto 	exp ::= functiondef
   2036   1.2    lneto 	exp ::= tableconstructor
   2037   1.2    lneto 	exp ::= &lsquo;<b>...</b>&rsquo;
   2038   1.2    lneto 	exp ::= exp binop exp
   2039   1.2    lneto 	exp ::= unop exp
   2040   1.2    lneto 	prefixexp ::= var | functioncall | &lsquo;<b>(</b>&rsquo; exp &lsquo;<b>)</b>&rsquo;
   2041   1.2    lneto </pre>
   2042   1.2    lneto 
   2043   1.2    lneto <p>
   2044   1.3    lneto Numerals and literal strings are explained in <a href="#3.1">&sect;3.1</a>;
   2045   1.2    lneto variables are explained in <a href="#3.2">&sect;3.2</a>;
   2046   1.2    lneto function definitions are explained in <a href="#3.4.11">&sect;3.4.11</a>;
   2047   1.2    lneto function calls are explained in <a href="#3.4.10">&sect;3.4.10</a>;
   2048   1.2    lneto table constructors are explained in <a href="#3.4.9">&sect;3.4.9</a>.
   2049   1.2    lneto Vararg expressions,
   2050   1.2    lneto denoted by three dots ('<code>...</code>'), can only be used when
   2051  1.10   nikita directly inside a variadic function;
   2052   1.2    lneto they are explained in <a href="#3.4.11">&sect;3.4.11</a>.
   2053   1.2    lneto 
   2054   1.1  mbalmer 
   2055   1.2    lneto <p>
   2056   1.2    lneto Binary operators comprise arithmetic operators (see <a href="#3.4.1">&sect;3.4.1</a>),
   2057   1.2    lneto bitwise operators (see <a href="#3.4.2">&sect;3.4.2</a>),
   2058   1.2    lneto 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>),
   2059   1.2    lneto and the concatenation operator (see <a href="#3.4.6">&sect;3.4.6</a>).
   2060   1.2    lneto Unary operators comprise the unary minus (see <a href="#3.4.1">&sect;3.4.1</a>),
   2061   1.6  salazar the unary bitwise NOT (see <a href="#3.4.2">&sect;3.4.2</a>),
   2062   1.3    lneto the unary logical <b>not</b> (see <a href="#3.4.5">&sect;3.4.5</a>),
   2063   1.2    lneto and the unary <em>length operator</em> (see <a href="#3.4.7">&sect;3.4.7</a>).
   2064   1.1  mbalmer 
   2065   1.1  mbalmer 
   2066   1.1  mbalmer 
   2067   1.9   nikita 
   2068   1.9   nikita 
   2069   1.2    lneto <h3>3.4.1 &ndash; <a name="3.4.1">Arithmetic Operators</a></h3><p>
   2070   1.2    lneto Lua supports the following arithmetic operators:
   2071   1.1  mbalmer 
   2072   1.3    lneto <ul>
   2073   1.3    lneto <li><b><code>+</code>: </b>addition</li>
   2074   1.3    lneto <li><b><code>-</code>: </b>subtraction</li>
   2075   1.3    lneto <li><b><code>*</code>: </b>multiplication</li>
   2076   1.3    lneto <li><b><code>/</code>: </b>float division</li>
   2077   1.3    lneto <li><b><code>//</code>: </b>floor division</li>
   2078   1.3    lneto <li><b><code>%</code>: </b>modulo</li>
   2079   1.3    lneto <li><b><code>^</code>: </b>exponentiation</li>
   2080   1.3    lneto <li><b><code>-</code>: </b>unary minus</li>
   2081   1.3    lneto </ul>
   2082   1.1  mbalmer 
   2083   1.2    lneto <p>
   2084   1.3    lneto With the exception of exponentiation and float division,
   2085   1.2    lneto the arithmetic operators work as follows:
   2086   1.2    lneto If both operands are integers,
   2087   1.2    lneto the operation is performed over integers and the result is an integer.
   2088   1.9   nikita Otherwise, if both operands are numbers,
   2089   1.2    lneto then they are converted to floats,
   2090   1.9   nikita the operation is performed following the machine's rules
   2091   1.2    lneto for floating-point arithmetic
   2092   1.2    lneto (usually the IEEE 754 standard),
   2093   1.2    lneto and the result is a float.
   2094   1.9   nikita (The string library coerces strings to numbers in
   2095   1.9   nikita arithmetic operations; see <a href="#3.4.3">&sect;3.4.3</a> for details.)
   2096   1.1  mbalmer 
   2097   1.1  mbalmer 
   2098   1.1  mbalmer <p>
   2099   1.3    lneto Exponentiation and float division (<code>/</code>)
   2100   1.2    lneto always convert their operands to floats
   2101   1.2    lneto and the result is always a float.
   2102   1.3    lneto Exponentiation uses the ISO&nbsp;C function <code>pow</code>,
   2103   1.2    lneto so that it works for non-integer exponents too.
   2104   1.1  mbalmer 
   2105   1.1  mbalmer 
   2106   1.1  mbalmer <p>
   2107   1.7  mbalmer Floor division (<code>//</code>) is a division
   2108   1.4  mbalmer that rounds the quotient towards minus infinity,
   2109   1.9   nikita resulting in the floor of the division of its operands.
   2110   1.1  mbalmer 
   2111   1.1  mbalmer 
   2112   1.1  mbalmer <p>
   2113   1.2    lneto Modulo is defined as the remainder of a division
   2114   1.4  mbalmer that rounds the quotient towards minus infinity (floor division).
   2115   1.1  mbalmer 
   2116   1.1  mbalmer 
   2117   1.1  mbalmer <p>
   2118   1.2    lneto In case of overflows in integer arithmetic,
   2119   1.9   nikita all operations <em>wrap around</em>.
   2120   1.2    lneto 
   2121   1.2    lneto 
   2122   1.2    lneto 
   2123   1.2    lneto <h3>3.4.2 &ndash; <a name="3.4.2">Bitwise Operators</a></h3><p>
   2124   1.2    lneto Lua supports the following bitwise operators:
   2125   1.1  mbalmer 
   2126   1.3    lneto <ul>
   2127   1.6  salazar <li><b><code>&amp;</code>: </b>bitwise AND</li>
   2128   1.6  salazar <li><b><code>&#124;</code>: </b>bitwise OR</li>
   2129   1.6  salazar <li><b><code>~</code>: </b>bitwise exclusive OR</li>
   2130   1.3    lneto <li><b><code>&gt;&gt;</code>: </b>right shift</li>
   2131   1.3    lneto <li><b><code>&lt;&lt;</code>: </b>left shift</li>
   2132   1.6  salazar <li><b><code>~</code>: </b>unary bitwise NOT</li>
   2133   1.3    lneto </ul>
   2134   1.1  mbalmer 
   2135   1.1  mbalmer <p>
   2136   1.2    lneto All bitwise operations convert its operands to integers
   2137   1.2    lneto (see <a href="#3.4.3">&sect;3.4.3</a>),
   2138   1.2    lneto operate on all bits of those integers,
   2139   1.2    lneto and result in an integer.
   2140   1.1  mbalmer 
   2141   1.1  mbalmer 
   2142   1.1  mbalmer <p>
   2143   1.2    lneto Both right and left shifts fill the vacant bits with zeros.
   2144   1.2    lneto Negative displacements shift to the other direction;
   2145   1.2    lneto displacements with absolute values equal to or higher than
   2146   1.2    lneto the number of bits in an integer
   2147   1.3    lneto result in zero (as all bits are shifted out).
   2148   1.2    lneto 
   2149   1.2    lneto 
   2150   1.2    lneto 
   2151   1.2    lneto 
   2152   1.2    lneto 
   2153   1.2    lneto <h3>3.4.3 &ndash; <a name="3.4.3">Coercions and Conversions</a></h3><p>
   2154   1.2    lneto Lua provides some automatic conversions between some
   2155   1.2    lneto types and representations at run time.
   2156   1.3    lneto Bitwise operators always convert float operands to integers.
   2157   1.3    lneto Exponentiation and float division
   2158   1.3    lneto always convert integer operands to floats.
   2159   1.3    lneto All other arithmetic operations applied to mixed numbers
   2160   1.9   nikita (integers and floats) convert the integer operand to a float.
   2161   1.2    lneto The C API also converts both integers to floats and
   2162   1.2    lneto floats to integers, as needed.
   2163   1.2    lneto Moreover, string concatenation accepts numbers as arguments,
   2164   1.7  mbalmer besides strings.
   2165   1.1  mbalmer 
   2166   1.1  mbalmer 
   2167   1.1  mbalmer <p>
   2168   1.2    lneto In a conversion from integer to float,
   2169   1.2    lneto if the integer value has an exact representation as a float,
   2170   1.2    lneto that is the result.
   2171   1.2    lneto Otherwise,
   2172   1.3    lneto the conversion gets the nearest higher or
   2173   1.3    lneto the nearest lower representable value.
   2174   1.2    lneto This kind of conversion never fails.
   2175   1.1  mbalmer 
   2176   1.1  mbalmer 
   2177   1.2    lneto <p>
   2178   1.2    lneto The conversion from float to integer
   2179   1.3    lneto checks whether the float has an exact representation as an integer
   2180   1.3    lneto (that is, the float has an integral value and
   2181   1.3    lneto it is in the range of integer representation).
   2182   1.3    lneto If it does, that representation is the result.
   2183   1.2    lneto Otherwise, the conversion fails.
   2184   1.1  mbalmer 
   2185   1.1  mbalmer 
   2186   1.1  mbalmer <p>
   2187   1.9   nikita Several places in Lua coerce strings to numbers when necessary.
   2188   1.9   nikita In particular,
   2189   1.9   nikita the string library sets metamethods that try to coerce
   2190   1.9   nikita strings to numbers in all arithmetic operations.
   2191   1.9   nikita If the conversion fails,
   2192   1.9   nikita the library calls the metamethod of the other operand
   2193   1.9   nikita (if present) or it raises an error.
   2194   1.9   nikita Note that bitwise operators do not do this coercion.
   2195   1.9   nikita 
   2196   1.9   nikita 
   2197   1.9   nikita <p>
   2198  1.10   nikita It is always a good practice not to rely on the
   2199  1.10   nikita implicit coercions from strings to numbers,
   2200  1.10   nikita as they are not always applied;
   2201   1.9   nikita in particular, <code>"1"==1</code> is false and <code>"1"&lt;1</code> raises an error
   2202   1.9   nikita (see <a href="#3.4.4">&sect;3.4.4</a>).
   2203   1.9   nikita These coercions exist mainly for compatibility and may be removed
   2204   1.9   nikita in future versions of the language.
   2205   1.1  mbalmer 
   2206   1.1  mbalmer 
   2207   1.1  mbalmer <p>
   2208   1.9   nikita A string is converted to an integer or a float
   2209   1.9   nikita following its syntax and the rules of the Lua lexer.
   2210   1.9   nikita The string may have also leading and trailing whitespaces and a sign.
   2211   1.7  mbalmer All conversions from strings to numbers
   2212   1.6  salazar accept both a dot and the current locale mark
   2213   1.6  salazar as the radix character.
   2214   1.6  salazar (The Lua lexer, however, accepts only a dot.)
   2215   1.9   nikita If the string is not a valid numeral,
   2216   1.9   nikita the conversion fails.
   2217   1.9   nikita If necessary, the result of this first step is then converted
   2218   1.9   nikita to a specific number subtype following the previous rules
   2219   1.9   nikita for conversions between floats and integers.
   2220   1.6  salazar 
   2221   1.6  salazar 
   2222   1.6  salazar <p>
   2223   1.3    lneto The conversion from numbers to strings uses a
   2224   1.3    lneto non-specified human-readable format.
   2225   1.9   nikita To convert numbers to strings in any specific way,
   2226   1.9   nikita use the function <a href="#pdf-string.format"><code>string.format</code></a>.
   2227   1.2    lneto 
   2228   1.2    lneto 
   2229   1.2    lneto 
   2230   1.2    lneto 
   2231   1.2    lneto 
   2232   1.2    lneto <h3>3.4.4 &ndash; <a name="3.4.4">Relational Operators</a></h3><p>
   2233   1.2    lneto Lua supports the following relational operators:
   2234   1.3    lneto 
   2235   1.3    lneto <ul>
   2236   1.3    lneto <li><b><code>==</code>: </b>equality</li>
   2237   1.3    lneto <li><b><code>~=</code>: </b>inequality</li>
   2238   1.3    lneto <li><b><code>&lt;</code>: </b>less than</li>
   2239   1.3    lneto <li><b><code>&gt;</code>: </b>greater than</li>
   2240   1.3    lneto <li><b><code>&lt;=</code>: </b>less or equal</li>
   2241   1.3    lneto <li><b><code>&gt;=</code>: </b>greater or equal</li>
   2242   1.3    lneto </ul><p>
   2243   1.2    lneto These operators always result in <b>false</b> or <b>true</b>.
   2244   1.1  mbalmer 
   2245   1.1  mbalmer 
   2246   1.1  mbalmer <p>
   2247   1.2    lneto Equality (<code>==</code>) first compares the type of its operands.
   2248   1.2    lneto If the types are different, then the result is <b>false</b>.
   2249   1.2    lneto Otherwise, the values of the operands are compared.
   2250   1.9   nikita Strings are equal if they have the same byte content.
   2251   1.4  mbalmer Numbers are equal if they denote the same mathematical value.
   2252   1.1  mbalmer 
   2253   1.1  mbalmer 
   2254   1.1  mbalmer <p>
   2255   1.2    lneto Tables, userdata, and threads
   2256   1.2    lneto are compared by reference:
   2257   1.2    lneto two objects are considered equal only if they are the same object.
   2258   1.2    lneto Every time you create a new object
   2259   1.9   nikita (a table, a userdata, or a thread),
   2260   1.2    lneto this new object is different from any previously existing object.
   2261   1.9   nikita A function is always equal to itself.
   2262   1.9   nikita Functions with any detectable difference
   2263   1.2    lneto (different behavior, different definition) are always different.
   2264   1.9   nikita Functions created at different times but with no detectable differences
   2265   1.8    alnsn may be classified as equal or not
   2266   1.8    alnsn (depending on internal caching details).
   2267   1.1  mbalmer 
   2268   1.1  mbalmer 
   2269   1.1  mbalmer <p>
   2270   1.2    lneto You can change the way that Lua compares tables and userdata
   2271   1.9   nikita by using the <code>__eq</code> metamethod (see <a href="#2.4">&sect;2.4</a>).
   2272   1.1  mbalmer 
   2273   1.1  mbalmer 
   2274   1.2    lneto <p>
   2275   1.3    lneto Equality comparisons do not convert strings to numbers
   2276   1.2    lneto or vice versa.
   2277   1.2    lneto Thus, <code>"0"==0</code> evaluates to <b>false</b>,
   2278   1.2    lneto and <code>t[0]</code> and <code>t["0"]</code> denote different
   2279   1.2    lneto entries in a table.
   2280   1.1  mbalmer 
   2281   1.1  mbalmer 
   2282   1.1  mbalmer <p>
   2283   1.2    lneto The operator <code>~=</code> is exactly the negation of equality (<code>==</code>).
   2284   1.1  mbalmer 
   2285   1.1  mbalmer 
   2286   1.2    lneto <p>
   2287   1.2    lneto The order operators work as follows.
   2288   1.2    lneto If both arguments are numbers,
   2289   1.9   nikita then they are compared according to their mathematical values,
   2290   1.9   nikita regardless of their subtypes.
   2291   1.2    lneto Otherwise, if both arguments are strings,
   2292   1.2    lneto then their values are compared according to the current locale.
   2293   1.9   nikita Otherwise, Lua tries to call the <code>__lt</code> or the <code>__le</code>
   2294   1.2    lneto metamethod (see <a href="#2.4">&sect;2.4</a>).
   2295   1.2    lneto A comparison <code>a &gt; b</code> is translated to <code>b &lt; a</code>
   2296   1.2    lneto and <code>a &gt;= b</code> is translated to <code>b &lt;= a</code>.
   2297   1.2    lneto 
   2298   1.2    lneto 
   2299   1.4  mbalmer <p>
   2300   1.4  mbalmer Following the IEEE 754 standard,
   2301   1.9   nikita the special value NaN is considered neither less than,
   2302   1.9   nikita nor equal to, nor greater than any value, including itself.
   2303   1.4  mbalmer 
   2304   1.4  mbalmer 
   2305   1.2    lneto 
   2306   1.2    lneto 
   2307   1.2    lneto 
   2308   1.2    lneto <h3>3.4.5 &ndash; <a name="3.4.5">Logical Operators</a></h3><p>
   2309   1.2    lneto The logical operators in Lua are
   2310   1.2    lneto <b>and</b>, <b>or</b>, and <b>not</b>.
   2311   1.2    lneto Like the control structures (see <a href="#3.3.4">&sect;3.3.4</a>),
   2312   1.2    lneto all logical operators consider both <b>false</b> and <b>nil</b> as false
   2313   1.2    lneto and anything else as true.
   2314   1.2    lneto 
   2315   1.2    lneto 
   2316   1.2    lneto <p>
   2317   1.2    lneto The negation operator <b>not</b> always returns <b>false</b> or <b>true</b>.
   2318   1.2    lneto The conjunction operator <b>and</b> returns its first argument
   2319   1.2    lneto if this value is <b>false</b> or <b>nil</b>;
   2320   1.2    lneto otherwise, <b>and</b> returns its second argument.
   2321   1.2    lneto The disjunction operator <b>or</b> returns its first argument
   2322   1.2    lneto if this value is different from <b>nil</b> and <b>false</b>;
   2323   1.2    lneto otherwise, <b>or</b> returns its second argument.
   2324   1.2    lneto Both <b>and</b> and <b>or</b> use short-circuit evaluation;
   2325   1.2    lneto that is,
   2326   1.2    lneto the second operand is evaluated only if necessary.
   2327   1.2    lneto Here are some examples:
   2328   1.2    lneto 
   2329   1.2    lneto <pre>
   2330   1.2    lneto      10 or 20            --&gt; 10
   2331   1.2    lneto      10 or error()       --&gt; 10
   2332   1.2    lneto      nil or "a"          --&gt; "a"
   2333   1.2    lneto      nil and 10          --&gt; nil
   2334   1.2    lneto      false and error()   --&gt; false
   2335   1.2    lneto      false and nil       --&gt; false
   2336   1.2    lneto      false or nil        --&gt; nil
   2337   1.2    lneto      10 and 20           --&gt; 20
   2338   1.9   nikita </pre>
   2339   1.2    lneto 
   2340   1.2    lneto 
   2341   1.2    lneto 
   2342   1.2    lneto 
   2343   1.2    lneto <h3>3.4.6 &ndash; <a name="3.4.6">Concatenation</a></h3><p>
   2344   1.2    lneto The string concatenation operator in Lua is
   2345   1.2    lneto denoted by two dots ('<code>..</code>').
   2346   1.9   nikita If both operands are strings or numbers,
   2347   1.9   nikita then the numbers are converted to strings
   2348   1.9   nikita in a non-specified format (see <a href="#3.4.3">&sect;3.4.3</a>).
   2349   1.2    lneto Otherwise, the <code>__concat</code> metamethod is called (see <a href="#2.4">&sect;2.4</a>).
   2350   1.2    lneto 
   2351   1.2    lneto 
   2352   1.2    lneto 
   2353   1.2    lneto 
   2354   1.2    lneto 
   2355   1.2    lneto <h3>3.4.7 &ndash; <a name="3.4.7">The Length Operator</a></h3>
   2356   1.2    lneto 
   2357   1.2    lneto <p>
   2358   1.2    lneto The length operator is denoted by the unary prefix operator <code>#</code>.
   2359   1.7  mbalmer 
   2360   1.7  mbalmer 
   2361   1.7  mbalmer <p>
   2362   1.9   nikita The length of a string is its number of bytes.
   2363   1.9   nikita (That is the usual meaning of string length when each
   2364   1.9   nikita character is one byte.)
   2365   1.2    lneto 
   2366   1.2    lneto 
   2367   1.2    lneto <p>
   2368   1.7  mbalmer The length operator applied on a table
   2369   1.7  mbalmer returns a border in that table.
   2370   1.9   nikita A <em>border</em> in a table <code>t</code> is any non-negative integer
   2371   1.7  mbalmer that satisfies the following condition:
   2372   1.7  mbalmer 
   2373   1.7  mbalmer <pre>
   2374   1.9   nikita      (border == 0 or t[border] ~= nil) and
   2375   1.9   nikita      (t[border + 1] == nil or border == math.maxinteger)
   2376   1.7  mbalmer </pre><p>
   2377   1.7  mbalmer In words,
   2378   1.9   nikita a border is any positive integer index present in the table
   2379   1.9   nikita that is followed by an absent index,
   2380   1.9   nikita plus two limit cases:
   2381   1.9   nikita zero, when index 1 is absent;
   2382   1.9   nikita and the maximum value for an integer, when that index is present.
   2383   1.9   nikita Note that keys that are not positive integers
   2384   1.9   nikita do not interfere with borders.
   2385   1.7  mbalmer 
   2386   1.7  mbalmer 
   2387   1.7  mbalmer <p>
   2388   1.7  mbalmer A table with exactly one border is called a <em>sequence</em>.
   2389   1.7  mbalmer For instance, the table <code>{10, 20, 30, 40, 50}</code> is a sequence,
   2390   1.7  mbalmer as it has only one border (5).
   2391   1.7  mbalmer The table <code>{10, 20, 30, nil, 50}</code> has two borders (3 and 5),
   2392   1.7  mbalmer and therefore it is not a sequence.
   2393   1.9   nikita (The <b>nil</b> at index 4 is called a <em>hole</em>.)
   2394   1.7  mbalmer The table <code>{nil, 20, 30, nil, nil, 60, nil}</code>
   2395   1.7  mbalmer has three borders (0, 3, and 6),
   2396   1.7  mbalmer so it is not a sequence, too.
   2397   1.7  mbalmer The table <code>{}</code> is a sequence with border 0.
   2398   1.7  mbalmer 
   2399   1.7  mbalmer 
   2400   1.7  mbalmer <p>
   2401   1.7  mbalmer When <code>t</code> is a sequence,
   2402   1.7  mbalmer <code>#t</code> returns its only border,
   2403   1.7  mbalmer which corresponds to the intuitive notion of the length of the sequence.
   2404   1.7  mbalmer When <code>t</code> is not a sequence,
   2405   1.7  mbalmer <code>#t</code> can return any of its borders.
   2406   1.7  mbalmer (The exact one depends on details of
   2407   1.7  mbalmer the internal representation of the table,
   2408   1.7  mbalmer which in turn can depend on how the table was populated and
   2409   1.7  mbalmer the memory addresses of its non-numeric keys.)
   2410   1.2    lneto 
   2411   1.2    lneto 
   2412   1.2    lneto <p>
   2413   1.7  mbalmer The computation of the length of a table
   2414   1.7  mbalmer has a guaranteed worst time of <em>O(log n)</em>,
   2415   1.9   nikita where <em>n</em> is the largest integer key in the table.
   2416   1.7  mbalmer 
   2417   1.2    lneto 
   2418   1.7  mbalmer <p>
   2419   1.7  mbalmer A program can modify the behavior of the length operator for
   2420   1.7  mbalmer any value but strings through the <code>__len</code> metamethod (see <a href="#2.4">&sect;2.4</a>).
   2421   1.2    lneto 
   2422   1.2    lneto 
   2423   1.2    lneto 
   2424   1.2    lneto 
   2425   1.2    lneto 
   2426   1.2    lneto <h3>3.4.8 &ndash; <a name="3.4.8">Precedence</a></h3><p>
   2427   1.2    lneto Operator precedence in Lua follows the table below,
   2428   1.2    lneto from lower to higher priority:
   2429   1.2    lneto 
   2430   1.2    lneto <pre>
   2431   1.2    lneto      or
   2432   1.2    lneto      and
   2433   1.2    lneto      &lt;     &gt;     &lt;=    &gt;=    ~=    ==
   2434   1.2    lneto      |
   2435   1.2    lneto      ~
   2436   1.2    lneto      &amp;
   2437   1.2    lneto      &lt;&lt;    &gt;&gt;
   2438   1.2    lneto      ..
   2439   1.2    lneto      +     -
   2440   1.2    lneto      *     /     //    %
   2441   1.2    lneto      unary operators (not   #     -     ~)
   2442   1.2    lneto      ^
   2443   1.2    lneto </pre><p>
   2444   1.2    lneto As usual,
   2445   1.2    lneto you can use parentheses to change the precedences of an expression.
   2446   1.2    lneto The concatenation ('<code>..</code>') and exponentiation ('<code>^</code>')
   2447   1.2    lneto operators are right associative.
   2448   1.2    lneto All other binary operators are left associative.
   2449   1.2    lneto 
   2450   1.2    lneto 
   2451   1.2    lneto 
   2452   1.2    lneto 
   2453   1.2    lneto 
   2454   1.2    lneto <h3>3.4.9 &ndash; <a name="3.4.9">Table Constructors</a></h3><p>
   2455   1.2    lneto Table constructors are expressions that create tables.
   2456   1.2    lneto Every time a constructor is evaluated, a new table is created.
   2457   1.2    lneto A constructor can be used to create an empty table
   2458   1.2    lneto or to create a table and initialize some of its fields.
   2459   1.2    lneto The general syntax for constructors is
   2460   1.2    lneto 
   2461   1.2    lneto <pre>
   2462   1.2    lneto 	tableconstructor ::= &lsquo;<b>{</b>&rsquo; [fieldlist] &lsquo;<b>}</b>&rsquo;
   2463   1.2    lneto 	fieldlist ::= field {fieldsep field} [fieldsep]
   2464   1.2    lneto 	field ::= &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo; &lsquo;<b>=</b>&rsquo; exp | Name &lsquo;<b>=</b>&rsquo; exp | exp
   2465   1.2    lneto 	fieldsep ::= &lsquo;<b>,</b>&rsquo; | &lsquo;<b>;</b>&rsquo;
   2466   1.2    lneto </pre>
   2467   1.2    lneto 
   2468   1.2    lneto <p>
   2469   1.2    lneto Each field of the form <code>[exp1] = exp2</code> adds to the new table an entry
   2470   1.2    lneto with key <code>exp1</code> and value <code>exp2</code>.
   2471   1.2    lneto A field of the form <code>name = exp</code> is equivalent to
   2472   1.2    lneto <code>["name"] = exp</code>.
   2473   1.9   nikita Fields of the form <code>exp</code> are equivalent to
   2474   1.3    lneto <code>[i] = exp</code>, where <code>i</code> are consecutive integers
   2475   1.9   nikita starting with 1;
   2476   1.9   nikita fields in the other formats do not affect this counting.
   2477   1.2    lneto For example,
   2478   1.2    lneto 
   2479   1.2    lneto <pre>
   2480   1.2    lneto      a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 }
   2481   1.2    lneto </pre><p>
   2482   1.2    lneto is equivalent to
   2483   1.2    lneto 
   2484   1.2    lneto <pre>
   2485   1.2    lneto      do
   2486   1.2    lneto        local t = {}
   2487   1.2    lneto        t[f(1)] = g
   2488   1.2    lneto        t[1] = "x"         -- 1st exp
   2489   1.2    lneto        t[2] = "y"         -- 2nd exp
   2490   1.2    lneto        t.x = 1            -- t["x"] = 1
   2491   1.2    lneto        t[3] = f(x)        -- 3rd exp
   2492   1.2    lneto        t[30] = 23
   2493   1.2    lneto        t[4] = 45          -- 4th exp
   2494   1.2    lneto        a = t
   2495   1.2    lneto      end
   2496   1.2    lneto </pre>
   2497   1.2    lneto 
   2498   1.2    lneto <p>
   2499   1.3    lneto The order of the assignments in a constructor is undefined.
   2500   1.3    lneto (This order would be relevant only when there are repeated keys.)
   2501   1.3    lneto 
   2502   1.3    lneto 
   2503   1.3    lneto <p>
   2504   1.2    lneto If the last field in the list has the form <code>exp</code>
   2505  1.10   nikita and the expression is a multires expression,
   2506   1.2    lneto then all values returned by this expression enter the list consecutively
   2507  1.10   nikita (see <a href="#3.4.12">&sect;3.4.12</a>).
   2508   1.2    lneto 
   2509   1.2    lneto 
   2510   1.2    lneto <p>
   2511   1.2    lneto The field list can have an optional trailing separator,
   2512   1.2    lneto as a convenience for machine-generated code.
   2513   1.2    lneto 
   2514   1.2    lneto 
   2515   1.2    lneto 
   2516   1.2    lneto 
   2517   1.2    lneto 
   2518   1.2    lneto <h3>3.4.10 &ndash; <a name="3.4.10">Function Calls</a></h3><p>
   2519   1.2    lneto A function call in Lua has the following syntax:
   2520   1.2    lneto 
   2521   1.2    lneto <pre>
   2522   1.2    lneto 	functioncall ::= prefixexp args
   2523   1.2    lneto </pre><p>
   2524   1.2    lneto In a function call,
   2525   1.2    lneto first prefixexp and args are evaluated.
   2526   1.2    lneto If the value of prefixexp has type <em>function</em>,
   2527   1.2    lneto then this function is called
   2528   1.2    lneto with the given arguments.
   2529   1.9   nikita Otherwise, if present,
   2530   1.9   nikita the prefixexp <code>__call</code> metamethod is called:
   2531   1.9   nikita its first argument is the value of prefixexp,
   2532   1.2    lneto followed by the original call arguments
   2533   1.2    lneto (see <a href="#2.4">&sect;2.4</a>).
   2534   1.2    lneto 
   2535   1.2    lneto 
   2536   1.2    lneto <p>
   2537   1.2    lneto The form
   2538   1.2    lneto 
   2539   1.2    lneto <pre>
   2540   1.2    lneto 	functioncall ::= prefixexp &lsquo;<b>:</b>&rsquo; Name args
   2541   1.2    lneto </pre><p>
   2542   1.9   nikita can be used to emulate methods.
   2543   1.2    lneto A call <code>v:name(<em>args</em>)</code>
   2544   1.2    lneto is syntactic sugar for <code>v.name(v,<em>args</em>)</code>,
   2545   1.2    lneto except that <code>v</code> is evaluated only once.
   2546   1.2    lneto 
   2547   1.2    lneto 
   2548   1.2    lneto <p>
   2549   1.2    lneto Arguments have the following syntax:
   2550   1.2    lneto 
   2551   1.2    lneto <pre>
   2552   1.2    lneto 	args ::= &lsquo;<b>(</b>&rsquo; [explist] &lsquo;<b>)</b>&rsquo;
   2553   1.2    lneto 	args ::= tableconstructor
   2554   1.3    lneto 	args ::= LiteralString
   2555   1.2    lneto </pre><p>
   2556   1.2    lneto All argument expressions are evaluated before the call.
   2557   1.2    lneto A call of the form <code>f{<em>fields</em>}</code> is
   2558   1.2    lneto syntactic sugar for <code>f({<em>fields</em>})</code>;
   2559   1.2    lneto that is, the argument list is a single new table.
   2560   1.2    lneto A call of the form <code>f'<em>string</em>'</code>
   2561   1.2    lneto (or <code>f"<em>string</em>"</code> or <code>f[[<em>string</em>]]</code>)
   2562   1.2    lneto is syntactic sugar for <code>f('<em>string</em>')</code>;
   2563   1.2    lneto that is, the argument list is a single literal string.
   2564   1.2    lneto 
   2565   1.2    lneto 
   2566   1.2    lneto <p>
   2567   1.9   nikita A call of the form <code>return <em>functioncall</em></code> not in the
   2568   1.9   nikita scope of a to-be-closed variable is called a <em>tail call</em>.
   2569   1.2    lneto Lua implements <em>proper tail calls</em>
   2570   1.2    lneto (or <em>proper tail recursion</em>):
   2571  1.10   nikita In a tail call,
   2572   1.2    lneto the called function reuses the stack entry of the calling function.
   2573   1.2    lneto Therefore, there is no limit on the number of nested tail calls that
   2574   1.2    lneto a program can execute.
   2575   1.2    lneto However, a tail call erases any debug information about the
   2576   1.2    lneto calling function.
   2577   1.2    lneto Note that a tail call only happens with a particular syntax,
   2578   1.9   nikita where the <b>return</b> has one single function call as argument,
   2579   1.9   nikita and it is outside the scope of any to-be-closed variable.
   2580   1.9   nikita This syntax makes the calling function return exactly
   2581   1.9   nikita the returns of the called function,
   2582   1.9   nikita without any intervening action.
   2583   1.2    lneto So, none of the following examples are tail calls:
   2584   1.2    lneto 
   2585   1.2    lneto <pre>
   2586   1.2    lneto      return (f(x))        -- results adjusted to 1
   2587   1.9   nikita      return 2 * f(x)      -- result multiplied by 2
   2588   1.2    lneto      return x, f(x)       -- additional results
   2589   1.2    lneto      f(x); return         -- results discarded
   2590   1.2    lneto      return x or f(x)     -- results adjusted to 1
   2591   1.2    lneto </pre>
   2592   1.2    lneto 
   2593   1.2    lneto 
   2594   1.2    lneto 
   2595   1.2    lneto 
   2596   1.2    lneto <h3>3.4.11 &ndash; <a name="3.4.11">Function Definitions</a></h3>
   2597   1.2    lneto 
   2598   1.2    lneto <p>
   2599   1.2    lneto The syntax for function definition is
   2600   1.2    lneto 
   2601   1.2    lneto <pre>
   2602   1.2    lneto 	functiondef ::= <b>function</b> funcbody
   2603   1.2    lneto 	funcbody ::= &lsquo;<b>(</b>&rsquo; [parlist] &lsquo;<b>)</b>&rsquo; block <b>end</b>
   2604   1.2    lneto </pre>
   2605   1.2    lneto 
   2606   1.2    lneto <p>
   2607   1.2    lneto The following syntactic sugar simplifies function definitions:
   2608   1.2    lneto 
   2609   1.2    lneto <pre>
   2610   1.2    lneto 	stat ::= <b>function</b> funcname funcbody
   2611   1.2    lneto 	stat ::= <b>local</b> <b>function</b> Name funcbody
   2612   1.2    lneto 	funcname ::= Name {&lsquo;<b>.</b>&rsquo; Name} [&lsquo;<b>:</b>&rsquo; Name]
   2613   1.2    lneto </pre><p>
   2614   1.2    lneto The statement
   2615   1.2    lneto 
   2616   1.2    lneto <pre>
   2617   1.2    lneto      function f () <em>body</em> end
   2618   1.2    lneto </pre><p>
   2619   1.2    lneto translates to
   2620   1.2    lneto 
   2621   1.2    lneto <pre>
   2622   1.2    lneto      f = function () <em>body</em> end
   2623   1.2    lneto </pre><p>
   2624   1.2    lneto The statement
   2625   1.2    lneto 
   2626   1.2    lneto <pre>
   2627   1.2    lneto      function t.a.b.c.f () <em>body</em> end
   2628   1.2    lneto </pre><p>
   2629   1.2    lneto translates to
   2630   1.2    lneto 
   2631   1.2    lneto <pre>
   2632   1.2    lneto      t.a.b.c.f = function () <em>body</em> end
   2633   1.2    lneto </pre><p>
   2634   1.2    lneto The statement
   2635   1.2    lneto 
   2636   1.2    lneto <pre>
   2637   1.2    lneto      local function f () <em>body</em> end
   2638   1.2    lneto </pre><p>
   2639   1.2    lneto translates to
   2640   1.2    lneto 
   2641   1.2    lneto <pre>
   2642   1.2    lneto      local f; f = function () <em>body</em> end
   2643   1.2    lneto </pre><p>
   2644   1.2    lneto not to
   2645   1.2    lneto 
   2646   1.2    lneto <pre>
   2647   1.2    lneto      local f = function () <em>body</em> end
   2648   1.2    lneto </pre><p>
   2649   1.2    lneto (This only makes a difference when the body of the function
   2650   1.2    lneto contains references to <code>f</code>.)
   2651   1.2    lneto 
   2652   1.2    lneto 
   2653   1.2    lneto <p>
   2654   1.2    lneto A function definition is an executable expression,
   2655   1.2    lneto whose value has type <em>function</em>.
   2656   1.2    lneto When Lua precompiles a chunk,
   2657   1.9   nikita all its function bodies are precompiled too,
   2658   1.9   nikita but they are not created yet.
   2659   1.2    lneto Then, whenever Lua executes the function definition,
   2660   1.2    lneto the function is <em>instantiated</em> (or <em>closed</em>).
   2661   1.9   nikita This function instance, or <em>closure</em>,
   2662   1.2    lneto is the final value of the expression.
   2663   1.2    lneto 
   2664   1.2    lneto 
   2665   1.2    lneto <p>
   2666   1.2    lneto Parameters act as local variables that are
   2667   1.2    lneto initialized with the argument values:
   2668   1.2    lneto 
   2669   1.2    lneto <pre>
   2670   1.2    lneto 	parlist ::= namelist [&lsquo;<b>,</b>&rsquo; &lsquo;<b>...</b>&rsquo;] | &lsquo;<b>...</b>&rsquo;
   2671   1.2    lneto </pre><p>
   2672   1.9   nikita When a Lua function is called,
   2673   1.9   nikita it adjusts its list of arguments to
   2674  1.10   nikita the length of its list of parameters (see <a href="#3.4.12">&sect;3.4.12</a>),
   2675  1.10   nikita unless the function is a <em>variadic function</em>,
   2676   1.2    lneto which is indicated by three dots ('<code>...</code>')
   2677   1.2    lneto at the end of its parameter list.
   2678  1.10   nikita A variadic function does not adjust its argument list;
   2679   1.2    lneto instead, it collects all extra arguments and supplies them
   2680   1.2    lneto to the function through a <em>vararg expression</em>,
   2681   1.2    lneto which is also written as three dots.
   2682   1.2    lneto The value of this expression is a list of all actual extra arguments,
   2683  1.10   nikita similar to a function with multiple results (see <a href="#3.4.12">&sect;3.4.12</a>).
   2684   1.2    lneto 
   2685   1.2    lneto 
   2686   1.2    lneto <p>
   2687   1.2    lneto As an example, consider the following definitions:
   2688   1.2    lneto 
   2689   1.2    lneto <pre>
   2690   1.2    lneto      function f(a, b) end
   2691   1.2    lneto      function g(a, b, ...) end
   2692   1.2    lneto      function r() return 1,2,3 end
   2693   1.2    lneto </pre><p>
   2694   1.2    lneto Then, we have the following mapping from arguments to parameters and
   2695   1.2    lneto to the vararg expression:
   2696   1.1  mbalmer 
   2697   1.1  mbalmer <pre>
   2698   1.9   nikita      CALL             PARAMETERS
   2699   1.2    lneto      
   2700   1.2    lneto      f(3)             a=3, b=nil
   2701   1.2    lneto      f(3, 4)          a=3, b=4
   2702   1.2    lneto      f(3, 4, 5)       a=3, b=4
   2703   1.2    lneto      f(r(), 10)       a=1, b=10
   2704   1.2    lneto      f(r())           a=1, b=2
   2705   1.2    lneto      
   2706   1.2    lneto      g(3)             a=3, b=nil, ... --&gt;  (nothing)
   2707   1.2    lneto      g(3, 4)          a=3, b=4,   ... --&gt;  (nothing)
   2708   1.2    lneto      g(3, 4, 5, 8)    a=3, b=4,   ... --&gt;  5  8
   2709   1.2    lneto      g(5, r())        a=5, b=1,   ... --&gt;  2  3
   2710   1.1  mbalmer </pre>
   2711   1.1  mbalmer 
   2712   1.1  mbalmer <p>
   2713   1.2    lneto Results are returned using the <b>return</b> statement (see <a href="#3.3.4">&sect;3.3.4</a>).
   2714   1.2    lneto If control reaches the end of a function
   2715   1.2    lneto without encountering a <b>return</b> statement,
   2716   1.2    lneto then the function returns with no results.
   2717   1.1  mbalmer 
   2718   1.1  mbalmer 
   2719   1.1  mbalmer <p>
   2720   1.1  mbalmer 
   2721   1.2    lneto There is a system-dependent limit on the number of values
   2722   1.2    lneto that a function may return.
   2723   1.9   nikita This limit is guaranteed to be greater than 1000.
   2724   1.1  mbalmer 
   2725   1.1  mbalmer 
   2726   1.1  mbalmer <p>
   2727   1.2    lneto The <em>colon</em> syntax
   2728   1.9   nikita is used to emulate <em>methods</em>,
   2729   1.9   nikita adding an implicit extra parameter <code>self</code> to the function.
   2730   1.2    lneto Thus, the statement
   2731   1.1  mbalmer 
   2732   1.2    lneto <pre>
   2733   1.2    lneto      function t.a.b.c:f (<em>params</em>) <em>body</em> end
   2734   1.2    lneto </pre><p>
   2735   1.2    lneto is syntactic sugar for
   2736   1.1  mbalmer 
   2737   1.2    lneto <pre>
   2738   1.2    lneto      t.a.b.c.f = function (self, <em>params</em>) <em>body</em> end
   2739   1.2    lneto </pre>
   2740   1.1  mbalmer 
   2741   1.1  mbalmer 
   2742   1.1  mbalmer 
   2743   1.1  mbalmer 
   2744  1.10   nikita <h3>3.4.12 &ndash; <a name="3.4.12">Lists of expressions, multiple results,
   2745  1.10   nikita and adjustment</a></h3>
   2746  1.10   nikita 
   2747  1.10   nikita <p>
   2748  1.10   nikita Both function calls and vararg expressions can result in multiple values.
   2749  1.10   nikita These expressions are called <em>multires expressions</em>.
   2750  1.10   nikita 
   2751  1.10   nikita 
   2752  1.10   nikita <p>
   2753  1.10   nikita When a multires expression is used as the last element
   2754  1.10   nikita of a list of expressions,
   2755  1.10   nikita all results from the expression are added to the
   2756  1.10   nikita list of values produced by the list of expressions.
   2757  1.10   nikita Note that a single expression
   2758  1.10   nikita in a place that expects a list of expressions
   2759  1.10   nikita is the last expression in that (singleton) list.
   2760  1.10   nikita 
   2761  1.10   nikita 
   2762  1.10   nikita <p>
   2763  1.10   nikita These are the places where Lua expects a list of expressions:
   2764  1.10   nikita 
   2765  1.10   nikita <ul>
   2766  1.10   nikita 
   2767  1.10   nikita <li>A <b>return</b> statement,
   2768  1.10   nikita for instance <code>return e1, e2, e3</code> (see <a href="#3.3.4">&sect;3.3.4</a>).</li>
   2769  1.10   nikita 
   2770  1.10   nikita <li>A table constructor,
   2771  1.10   nikita for instance <code>{e1, e2, e3}</code> (see <a href="#3.4.9">&sect;3.4.9</a>).</li>
   2772  1.10   nikita 
   2773  1.10   nikita <li>The arguments of a function call,
   2774  1.10   nikita for instance <code>foo(e1, e2, e3)</code> (see <a href="#3.4.10">&sect;3.4.10</a>).</li>
   2775  1.10   nikita 
   2776  1.10   nikita <li>A multiple assignment,
   2777  1.10   nikita for instance <code>a , b, c = e1, e2, e3</code> (see <a href="#3.3.3">&sect;3.3.3</a>).</li>
   2778  1.10   nikita 
   2779  1.10   nikita <li>A local declaration,
   2780  1.10   nikita for instance <code>local a , b, c = e1, e2, e3</code> (see <a href="#3.3.7">&sect;3.3.7</a>).</li>
   2781  1.10   nikita 
   2782  1.10   nikita <li>The initial values in a generic <b>for</b> loop,
   2783  1.10   nikita for instance <code>for k in e1, e2, e3 do ... end</code> (see <a href="#3.3.5">&sect;3.3.5</a>).</li>
   2784  1.10   nikita 
   2785  1.10   nikita </ul><p>
   2786  1.10   nikita In the last four cases,
   2787  1.10   nikita the list of values from the list of expressions
   2788  1.10   nikita must be <em>adjusted</em> to a specific length:
   2789  1.10   nikita the number of parameters in a call to a non-variadic function
   2790  1.10   nikita (see <a href="#3.4.11">&sect;3.4.11</a>),
   2791  1.10   nikita the number of variables in a multiple assignment or
   2792  1.10   nikita a local declaration,
   2793  1.10   nikita and exactly four values for a generic <b>for</b> loop.
   2794  1.10   nikita The <em>adjustment</em> follows these rules:
   2795  1.10   nikita If there are more values than needed,
   2796  1.10   nikita the extra values are thrown away;
   2797  1.10   nikita if there are fewer values than needed,
   2798  1.10   nikita the list is extended with <b>nil</b>'s.
   2799  1.10   nikita When the list of expressions ends with a multires expression,
   2800  1.10   nikita all results from that expression enter the list of values
   2801  1.10   nikita before the adjustment.
   2802  1.10   nikita 
   2803  1.10   nikita 
   2804  1.10   nikita <p>
   2805  1.10   nikita When a multires expression is used
   2806  1.10   nikita in a list of expressions without being the last element,
   2807  1.10   nikita or in a place where the syntax expects a single expression,
   2808  1.10   nikita Lua adjusts the result list of that expression to one element.
   2809  1.10   nikita As a particular case,
   2810  1.10   nikita the syntax expects a single expression inside a parenthesized expression;
   2811  1.10   nikita therefore, adding parentheses around a multires expression
   2812  1.10   nikita forces it to produce exactly one result.
   2813  1.10   nikita 
   2814  1.10   nikita 
   2815  1.10   nikita <p>
   2816  1.10   nikita We seldom need to use a vararg expression in a place
   2817  1.10   nikita where the syntax expects a single expression.
   2818  1.10   nikita (Usually it is simpler to add a regular parameter before
   2819  1.10   nikita the variadic part and use that parameter.)
   2820  1.10   nikita When there is such a need,
   2821  1.10   nikita we recommend assigning the vararg expression
   2822  1.10   nikita to a single variable and using that variable
   2823  1.10   nikita in its place.
   2824  1.10   nikita 
   2825  1.10   nikita 
   2826  1.10   nikita <p>
   2827  1.10   nikita Here are some examples of uses of mutlres expressions.
   2828  1.10   nikita In all cases, when the construction needs
   2829  1.10   nikita "the n-th result" and there is no such result,
   2830  1.10   nikita it uses a <b>nil</b>.
   2831  1.10   nikita 
   2832  1.10   nikita <pre>
   2833  1.10   nikita      print(x, f())      -- prints x and all results from f().
   2834  1.10   nikita      print(x, (f()))    -- prints x and the first result from f().
   2835  1.10   nikita      print(f(), x)      -- prints the first result from f() and x.
   2836  1.10   nikita      print(1 + f())     -- prints 1 added to the first result from f().
   2837  1.10   nikita      local x = ...      -- x gets the first vararg argument.
   2838  1.10   nikita      x,y = ...          -- x gets the first vararg argument,
   2839  1.10   nikita                         -- y gets the second vararg argument.
   2840  1.10   nikita      x,y,z = w, f()     -- x gets w, y gets the first result from f(),
   2841  1.10   nikita                         -- z gets the second result from f().
   2842  1.10   nikita      x,y,z = f()        -- x gets the first result from f(),
   2843  1.10   nikita                         -- y gets the second result from f(),
   2844  1.10   nikita                         -- z gets the third result from f().
   2845  1.10   nikita      x,y,z = f(), g()   -- x gets the first result from f(),
   2846  1.10   nikita                         -- y gets the first result from g(),
   2847  1.10   nikita                         -- z gets the second result from g().
   2848  1.10   nikita      x,y,z = (f())      -- x gets the first result from f(), y and z get nil.
   2849  1.10   nikita      return f()         -- returns all results from f().
   2850  1.10   nikita      return x, ...      -- returns x and all received vararg arguments.
   2851  1.10   nikita      return x,y,f()     -- returns x, y, and all results from f().
   2852  1.10   nikita      {f()}              -- creates a list with all results from f().
   2853  1.10   nikita      {...}              -- creates a list with all vararg arguments.
   2854  1.10   nikita      {f(), 5}           -- creates a list with the first result from f() and 5.
   2855  1.10   nikita </pre>
   2856  1.10   nikita 
   2857  1.10   nikita 
   2858  1.10   nikita 
   2859  1.10   nikita 
   2860   1.1  mbalmer 
   2861   1.1  mbalmer 
   2862   1.2    lneto <h2>3.5 &ndash; <a name="3.5">Visibility Rules</a></h2>
   2863   1.1  mbalmer 
   2864   1.1  mbalmer <p>
   2865   1.1  mbalmer 
   2866   1.2    lneto Lua is a lexically scoped language.
   2867   1.2    lneto The scope of a local variable begins at the first statement after
   2868   1.2    lneto its declaration and lasts until the last non-void statement
   2869   1.2    lneto of the innermost block that includes the declaration.
   2870  1.10   nikita (<em>Void statements</em> are labels and empty statements.)
   2871   1.2    lneto Consider the following example:
   2872   1.1  mbalmer 
   2873   1.2    lneto <pre>
   2874   1.2    lneto      x = 10                -- global variable
   2875   1.2    lneto      do                    -- new block
   2876   1.2    lneto        local x = x         -- new 'x', with value 10
   2877   1.2    lneto        print(x)            --&gt; 10
   2878   1.2    lneto        x = x+1
   2879   1.2    lneto        do                  -- another block
   2880   1.2    lneto          local x = x+1     -- another 'x'
   2881   1.2    lneto          print(x)          --&gt; 12
   2882   1.2    lneto        end
   2883   1.2    lneto        print(x)            --&gt; 11
   2884   1.2    lneto      end
   2885   1.2    lneto      print(x)              --&gt; 10  (the global one)
   2886   1.2    lneto </pre>
   2887   1.1  mbalmer 
   2888   1.1  mbalmer <p>
   2889   1.2    lneto Notice that, in a declaration like <code>local x = x</code>,
   2890   1.2    lneto the new <code>x</code> being declared is not in scope yet,
   2891   1.2    lneto and so the second <code>x</code> refers to the outside variable.
   2892   1.1  mbalmer 
   2893   1.1  mbalmer 
   2894   1.1  mbalmer <p>
   2895   1.2    lneto Because of the lexical scoping rules,
   2896   1.2    lneto local variables can be freely accessed by functions
   2897   1.2    lneto defined inside their scope.
   2898   1.9   nikita A local variable used by an inner function is called an <em>upvalue</em>
   2899   1.9   nikita (or <em>external local variable</em>, or simply <em>external variable</em>)
   2900   1.2    lneto inside the inner function.
   2901   1.1  mbalmer 
   2902   1.1  mbalmer 
   2903   1.1  mbalmer <p>
   2904   1.2    lneto Notice that each execution of a <b>local</b> statement
   2905   1.2    lneto defines new local variables.
   2906   1.2    lneto Consider the following example:
   2907   1.1  mbalmer 
   2908   1.1  mbalmer <pre>
   2909   1.2    lneto      a = {}
   2910   1.2    lneto      local x = 20
   2911   1.9   nikita      for i = 1, 10 do
   2912   1.2    lneto        local y = 0
   2913   1.9   nikita        a[i] = function () y = y + 1; return x + y end
   2914   1.1  mbalmer      end
   2915   1.1  mbalmer </pre><p>
   2916   1.2    lneto The loop creates ten closures
   2917   1.2    lneto (that is, ten instances of the anonymous function).
   2918   1.2    lneto Each of these closures uses a different <code>y</code> variable,
   2919   1.2    lneto while all of them share the same <code>x</code>.
   2920   1.1  mbalmer 
   2921   1.1  mbalmer 
   2922   1.1  mbalmer 
   2923   1.1  mbalmer 
   2924   1.1  mbalmer 
   2925   1.2    lneto <h1>4 &ndash; <a name="4">The Application Program Interface</a></h1>
   2926   1.1  mbalmer 
   2927   1.9   nikita 
   2928   1.9   nikita 
   2929   1.1  mbalmer <p>
   2930   1.1  mbalmer 
   2931   1.1  mbalmer This section describes the C&nbsp;API for Lua, that is,
   2932   1.1  mbalmer the set of C&nbsp;functions available to the host program to communicate
   2933   1.1  mbalmer with Lua.
   2934   1.1  mbalmer All API functions and related types and constants
   2935   1.1  mbalmer are declared in the header file <a name="pdf-lua.h"><code>lua.h</code></a>.
   2936   1.1  mbalmer 
   2937   1.1  mbalmer 
   2938   1.1  mbalmer <p>
   2939   1.1  mbalmer Even when we use the term "function",
   2940   1.1  mbalmer any facility in the API may be provided as a macro instead.
   2941   1.2    lneto Except where stated otherwise,
   2942   1.2    lneto all such macros use each of their arguments exactly once
   2943   1.1  mbalmer (except for the first argument, which is always a Lua state),
   2944   1.1  mbalmer and so do not generate any hidden side-effects.
   2945   1.1  mbalmer 
   2946   1.1  mbalmer 
   2947   1.1  mbalmer <p>
   2948   1.1  mbalmer As in most C&nbsp;libraries,
   2949   1.9   nikita the Lua API functions do not check their arguments
   2950   1.9   nikita for validity or consistency.
   2951   1.1  mbalmer However, you can change this behavior by compiling Lua
   2952   1.2    lneto with the macro <a name="pdf-LUA_USE_APICHECK"><code>LUA_USE_APICHECK</code></a> defined.
   2953   1.1  mbalmer 
   2954   1.1  mbalmer 
   2955   1.7  mbalmer <p>
   2956   1.7  mbalmer The Lua library is fully reentrant:
   2957   1.7  mbalmer it has no global variables.
   2958   1.7  mbalmer It keeps all information it needs in a dynamic structure,
   2959   1.7  mbalmer called the <em>Lua state</em>.
   2960   1.7  mbalmer 
   2961   1.7  mbalmer 
   2962   1.7  mbalmer <p>
   2963   1.7  mbalmer Each Lua state has one or more threads,
   2964   1.7  mbalmer which correspond to independent, cooperative lines of execution.
   2965   1.7  mbalmer The type <a href="#lua_State"><code>lua_State</code></a> (despite its name) refers to a thread.
   2966   1.7  mbalmer (Indirectly, through the thread, it also refers to the
   2967   1.7  mbalmer Lua state associated to the thread.)
   2968   1.7  mbalmer 
   2969   1.7  mbalmer 
   2970   1.7  mbalmer <p>
   2971   1.7  mbalmer A pointer to a thread must be passed as the first argument to
   2972   1.7  mbalmer every function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>,
   2973   1.7  mbalmer which creates a Lua state from scratch and returns a pointer
   2974   1.7  mbalmer to the <em>main thread</em> in the new state.
   2975   1.7  mbalmer 
   2976   1.7  mbalmer 
   2977   1.1  mbalmer 
   2978   1.9   nikita 
   2979   1.9   nikita 
   2980   1.2    lneto <h2>4.1 &ndash; <a name="4.1">The Stack</a></h2>
   2981   1.1  mbalmer 
   2982   1.9   nikita 
   2983   1.9   nikita 
   2984   1.1  mbalmer <p>
   2985   1.1  mbalmer Lua uses a <em>virtual stack</em> to pass values to and from C.
   2986   1.1  mbalmer Each element in this stack represents a Lua value
   2987   1.1  mbalmer (<b>nil</b>, number, string, etc.).
   2988   1.7  mbalmer Functions in the API can access this stack through the
   2989   1.7  mbalmer Lua state parameter that they receive.
   2990   1.1  mbalmer 
   2991   1.1  mbalmer 
   2992   1.1  mbalmer <p>
   2993   1.1  mbalmer Whenever Lua calls C, the called function gets a new stack,
   2994   1.1  mbalmer which is independent of previous stacks and of stacks of
   2995   1.1  mbalmer C&nbsp;functions that are still active.
   2996   1.1  mbalmer This stack initially contains any arguments to the C&nbsp;function
   2997   1.7  mbalmer and it is where the C&nbsp;function can store temporary
   2998   1.7  mbalmer Lua values and must push its results
   2999   1.1  mbalmer to be returned to the caller (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>).
   3000   1.1  mbalmer 
   3001   1.1  mbalmer 
   3002   1.1  mbalmer <p>
   3003   1.1  mbalmer For convenience,
   3004   1.1  mbalmer most query operations in the API do not follow a strict stack discipline.
   3005   1.1  mbalmer Instead, they can refer to any element in the stack
   3006   1.1  mbalmer by using an <em>index</em>:
   3007   1.9   nikita A positive index represents an absolute stack position,
   3008   1.9   nikita starting at&nbsp;1 as the bottom of the stack;
   3009   1.2    lneto a negative index represents an offset relative to the top of the stack.
   3010   1.1  mbalmer More specifically, if the stack has <em>n</em> elements,
   3011   1.1  mbalmer then index&nbsp;1 represents the first element
   3012   1.1  mbalmer (that is, the element that was pushed onto the stack first)
   3013   1.1  mbalmer and
   3014   1.1  mbalmer index&nbsp;<em>n</em> represents the last element;
   3015   1.1  mbalmer index&nbsp;-1 also represents the last element
   3016   1.1  mbalmer (that is, the element at the&nbsp;top)
   3017   1.1  mbalmer and index <em>-n</em> represents the first element.
   3018   1.1  mbalmer 
   3019   1.1  mbalmer 
   3020   1.1  mbalmer 
   3021   1.1  mbalmer 
   3022   1.1  mbalmer 
   3023   1.9   nikita <h3>4.1.1 &ndash; <a name="4.1.1">Stack Size</a></h3>
   3024   1.1  mbalmer 
   3025   1.1  mbalmer <p>
   3026   1.2    lneto When you interact with the Lua API,
   3027   1.1  mbalmer you are responsible for ensuring consistency.
   3028   1.1  mbalmer In particular,
   3029   1.1  mbalmer <em>you are responsible for controlling stack overflow</em>.
   3030   1.9   nikita When you call any API function,
   3031   1.9   nikita you must ensure the stack has enough room to accommodate the results.
   3032   1.9   nikita 
   3033   1.9   nikita 
   3034   1.9   nikita <p>
   3035   1.9   nikita There is one exception to the above rule:
   3036   1.9   nikita When you call a Lua function
   3037   1.9   nikita without a fixed number of results (see <a href="#lua_call"><code>lua_call</code></a>),
   3038   1.9   nikita Lua ensures that the stack has enough space for all results.
   3039   1.9   nikita However, it does not ensure any extra space.
   3040   1.9   nikita So, before pushing anything on the stack after such a call
   3041   1.9   nikita you should use <a href="#lua_checkstack"><code>lua_checkstack</code></a>.
   3042   1.1  mbalmer 
   3043   1.1  mbalmer 
   3044   1.1  mbalmer <p>
   3045   1.1  mbalmer Whenever Lua calls C,
   3046   1.3    lneto it ensures that the stack has space for
   3047   1.9   nikita at least <a name="pdf-LUA_MINSTACK"><code>LUA_MINSTACK</code></a> extra elements;
   3048   1.9   nikita that is, you can safely push up to <code>LUA_MINSTACK</code> values into it.
   3049   1.1  mbalmer <code>LUA_MINSTACK</code> is defined as 20,
   3050   1.1  mbalmer so that usually you do not have to worry about stack space
   3051   1.1  mbalmer unless your code has loops pushing elements onto the stack.
   3052   1.9   nikita Whenever necessary,
   3053   1.9   nikita you can use the function <a href="#lua_checkstack"><code>lua_checkstack</code></a>
   3054   1.9   nikita to ensure that the stack has enough space for pushing new elements.
   3055   1.2    lneto 
   3056   1.2    lneto 
   3057   1.2    lneto 
   3058   1.2    lneto 
   3059   1.1  mbalmer 
   3060   1.9   nikita <h3>4.1.2 &ndash; <a name="4.1.2">Valid and Acceptable Indices</a></h3>
   3061   1.1  mbalmer 
   3062   1.2    lneto <p>
   3063   1.2    lneto Any function in the API that receives stack indices
   3064   1.2    lneto works only with <em>valid indices</em> or <em>acceptable indices</em>.
   3065   1.1  mbalmer 
   3066   1.1  mbalmer 
   3067   1.2    lneto <p>
   3068   1.2    lneto A <em>valid index</em> is an index that refers to a
   3069   1.4  mbalmer position that stores a modifiable Lua value.
   3070   1.4  mbalmer It comprises stack indices between&nbsp;1 and the stack top
   3071   1.4  mbalmer (<code>1 &le; abs(index) &le; top</code>)
   3072   1.4  mbalmer 
   3073   1.4  mbalmer plus <em>pseudo-indices</em>,
   3074   1.4  mbalmer which represent some positions that are accessible to C&nbsp;code
   3075   1.4  mbalmer but that are not in the stack.
   3076   1.9   nikita Pseudo-indices are used to access the registry (see <a href="#4.3">&sect;4.3</a>)
   3077   1.9   nikita and the upvalues of a C&nbsp;function (see <a href="#4.2">&sect;4.2</a>).
   3078   1.2    lneto 
   3079   1.2    lneto 
   3080   1.2    lneto <p>
   3081   1.4  mbalmer Functions that do not need a specific mutable position,
   3082   1.4  mbalmer but only a value (e.g., query functions),
   3083   1.2    lneto can be called with acceptable indices.
   3084   1.2    lneto An <em>acceptable index</em> can be any valid index,
   3085   1.2    lneto but it also can be any positive index after the stack top
   3086   1.2    lneto within the space allocated for the stack,
   3087   1.2    lneto that is, indices up to the stack size.
   3088   1.2    lneto (Note that 0 is never an acceptable index.)
   3089   1.9   nikita Indices to upvalues (see <a href="#4.2">&sect;4.2</a>) greater than the real number
   3090   1.9   nikita of upvalues in the current C&nbsp;function are also acceptable (but invalid).
   3091   1.2    lneto Except when noted otherwise,
   3092   1.2    lneto functions in the API work with acceptable indices.
   3093   1.1  mbalmer 
   3094   1.1  mbalmer 
   3095   1.1  mbalmer <p>
   3096   1.2    lneto Acceptable indices serve to avoid extra tests
   3097   1.2    lneto against the stack top when querying the stack.
   3098   1.2    lneto For instance, a C&nbsp;function can query its third argument
   3099   1.9   nikita without the need to check whether there is a third argument,
   3100   1.2    lneto that is, without the need to check whether 3 is a valid index.
   3101   1.1  mbalmer 
   3102   1.1  mbalmer 
   3103   1.1  mbalmer <p>
   3104   1.2    lneto For functions that can be called with acceptable indices,
   3105   1.2    lneto any non-valid index is treated as if it
   3106   1.2    lneto contains a value of a virtual type <a name="pdf-LUA_TNONE"><code>LUA_TNONE</code></a>,
   3107   1.2    lneto which behaves like a nil value.
   3108   1.1  mbalmer 
   3109   1.1  mbalmer 
   3110   1.1  mbalmer 
   3111   1.1  mbalmer 
   3112   1.1  mbalmer 
   3113   1.9   nikita <h3>4.1.3 &ndash; <a name="4.1.3">Pointers to strings</a></h3>
   3114   1.9   nikita 
   3115   1.9   nikita <p>
   3116   1.9   nikita Several functions in the API return pointers (<code>const char*</code>)
   3117   1.9   nikita to Lua strings in the stack.
   3118   1.9   nikita (See <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>, <a href="#lua_pushlstring"><code>lua_pushlstring</code></a>,
   3119   1.9   nikita <a href="#lua_pushstring"><code>lua_pushstring</code></a>, and <a href="#lua_tolstring"><code>lua_tolstring</code></a>.
   3120   1.9   nikita See also <a href="#luaL_checklstring"><code>luaL_checklstring</code></a>, <a href="#luaL_checkstring"><code>luaL_checkstring</code></a>,
   3121   1.9   nikita and <a href="#luaL_tolstring"><code>luaL_tolstring</code></a> in the auxiliary library.)
   3122   1.9   nikita 
   3123   1.9   nikita 
   3124   1.9   nikita <p>
   3125   1.9   nikita In general,
   3126   1.9   nikita Lua's garbage collection can free or move internal memory
   3127   1.9   nikita and then invalidate pointers to internal strings.
   3128   1.9   nikita To allow a safe use of these pointers,
   3129  1.10   nikita the API guarantees that any pointer to a string in a stack index
   3130   1.9   nikita is valid while the string value at that index is not removed from the stack.
   3131   1.9   nikita (It can be moved to another index, though.)
   3132   1.9   nikita When the index is a pseudo-index (referring to an upvalue),
   3133   1.9   nikita the pointer is valid while the corresponding call is active and
   3134   1.9   nikita the corresponding upvalue is not modified.
   3135   1.9   nikita 
   3136   1.9   nikita 
   3137   1.9   nikita <p>
   3138   1.9   nikita Some functions in the debug interface
   3139   1.9   nikita also return pointers to strings,
   3140   1.9   nikita namely <a href="#lua_getlocal"><code>lua_getlocal</code></a>, <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>,
   3141   1.9   nikita <a href="#lua_setlocal"><code>lua_setlocal</code></a>, and <a href="#lua_setupvalue"><code>lua_setupvalue</code></a>.
   3142   1.9   nikita For these functions, the pointer is guaranteed to
   3143   1.9   nikita be valid while the caller function is active and
   3144   1.9   nikita the given closure (if one was given) is in the stack.
   3145   1.9   nikita 
   3146   1.9   nikita 
   3147   1.9   nikita <p>
   3148   1.9   nikita Except for these guarantees,
   3149   1.9   nikita the garbage collector is free to invalidate
   3150   1.9   nikita any pointer to internal strings.
   3151   1.9   nikita 
   3152   1.9   nikita 
   3153   1.9   nikita 
   3154   1.9   nikita 
   3155   1.9   nikita 
   3156   1.9   nikita 
   3157   1.9   nikita 
   3158   1.9   nikita <h2>4.2 &ndash; <a name="4.2">C Closures</a></h2>
   3159   1.1  mbalmer 
   3160   1.1  mbalmer <p>
   3161   1.1  mbalmer When a C&nbsp;function is created,
   3162   1.1  mbalmer it is possible to associate some values with it,
   3163   1.2    lneto thus creating a <em>C&nbsp;closure</em>
   3164   1.2    lneto (see <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>);
   3165   1.1  mbalmer these values are called <em>upvalues</em> and are
   3166   1.2    lneto accessible to the function whenever it is called.
   3167   1.1  mbalmer 
   3168   1.1  mbalmer 
   3169   1.1  mbalmer <p>
   3170   1.1  mbalmer Whenever a C&nbsp;function is called,
   3171   1.1  mbalmer its upvalues are located at specific pseudo-indices.
   3172   1.1  mbalmer These pseudo-indices are produced by the macro
   3173   1.2    lneto <a href="#lua_upvalueindex"><code>lua_upvalueindex</code></a>.
   3174   1.4  mbalmer The first upvalue associated with a function is at index
   3175   1.1  mbalmer <code>lua_upvalueindex(1)</code>, and so on.
   3176   1.1  mbalmer Any access to <code>lua_upvalueindex(<em>n</em>)</code>,
   3177   1.1  mbalmer where <em>n</em> is greater than the number of upvalues of the
   3178   1.5    lneto current function
   3179   1.5    lneto (but not greater than 256,
   3180   1.5    lneto which is one plus the maximum number of upvalues in a closure),
   3181   1.2    lneto produces an acceptable but invalid index.
   3182   1.1  mbalmer 
   3183   1.1  mbalmer 
   3184   1.9   nikita <p>
   3185   1.9   nikita A C&nbsp;closure can also change the values
   3186   1.9   nikita of its corresponding upvalues.
   3187   1.9   nikita 
   3188   1.1  mbalmer 
   3189   1.1  mbalmer 
   3190   1.1  mbalmer 
   3191   1.9   nikita 
   3192   1.9   nikita <h2>4.3 &ndash; <a name="4.3">Registry</a></h2>
   3193   1.1  mbalmer 
   3194   1.1  mbalmer <p>
   3195   1.1  mbalmer Lua provides a <em>registry</em>,
   3196   1.2    lneto a predefined table that can be used by any C&nbsp;code to
   3197   1.2    lneto store whatever Lua values it needs to store.
   3198   1.9   nikita The registry table is always accessible at pseudo-index
   3199   1.4  mbalmer <a name="pdf-LUA_REGISTRYINDEX"><code>LUA_REGISTRYINDEX</code></a>.
   3200   1.1  mbalmer Any C&nbsp;library can store data into this table,
   3201   1.2    lneto but it must take care to choose keys
   3202   1.2    lneto that are different from those used
   3203   1.1  mbalmer by other libraries, to avoid collisions.
   3204   1.2    lneto Typically, you should use as key a string containing your library name,
   3205   1.2    lneto or a light userdata with the address of a C&nbsp;object in your code,
   3206   1.2    lneto or any Lua object created by your code.
   3207   1.3    lneto As with variable names,
   3208   1.2    lneto string keys starting with an underscore followed by
   3209   1.2    lneto uppercase letters are reserved for Lua.
   3210   1.1  mbalmer 
   3211   1.1  mbalmer 
   3212   1.1  mbalmer <p>
   3213   1.3    lneto The integer keys in the registry are used
   3214   1.3    lneto by the reference mechanism (see <a href="#luaL_ref"><code>luaL_ref</code></a>)
   3215   1.2    lneto and by some predefined values.
   3216   1.9   nikita Therefore, integer keys in the registry
   3217   1.9   nikita must not be used for other purposes.
   3218   1.2    lneto 
   3219   1.1  mbalmer 
   3220   1.2    lneto <p>
   3221   1.2    lneto When you create a new Lua state,
   3222   1.2    lneto its registry comes with some predefined values.
   3223   1.2    lneto These predefined values are indexed with integer keys
   3224   1.2    lneto defined as constants in <code>lua.h</code>.
   3225   1.2    lneto The following constants are defined:
   3226   1.2    lneto 
   3227   1.2    lneto <ul>
   3228   1.2    lneto <li><b><a name="pdf-LUA_RIDX_MAINTHREAD"><code>LUA_RIDX_MAINTHREAD</code></a>: </b> At this index the registry has
   3229   1.2    lneto the main thread of the state.
   3230   1.2    lneto (The main thread is the one created together with the state.)
   3231   1.2    lneto </li>
   3232   1.1  mbalmer 
   3233   1.2    lneto <li><b><a name="pdf-LUA_RIDX_GLOBALS"><code>LUA_RIDX_GLOBALS</code></a>: </b> At this index the registry has
   3234   1.2    lneto the global environment.
   3235   1.2    lneto </li>
   3236   1.2    lneto </ul>
   3237   1.1  mbalmer 
   3238   1.1  mbalmer 
   3239   1.1  mbalmer 
   3240   1.2    lneto 
   3241   1.9   nikita <h2>4.4 &ndash; <a name="4.4">Error Handling in C</a></h2>
   3242   1.9   nikita 
   3243   1.9   nikita 
   3244   1.1  mbalmer 
   3245   1.1  mbalmer <p>
   3246   1.1  mbalmer Internally, Lua uses the C <code>longjmp</code> facility to handle errors.
   3247   1.3    lneto (Lua will use exceptions if you compile it as C++;
   3248   1.3    lneto search for <code>LUAI_THROW</code> in the source code for details.)
   3249   1.9   nikita When Lua faces any error,
   3250   1.9   nikita such as a memory allocation error or a type error,
   3251   1.1  mbalmer it <em>raises</em> an error;
   3252   1.1  mbalmer that is, it does a long jump.
   3253   1.1  mbalmer A <em>protected environment</em> uses <code>setjmp</code>
   3254   1.2    lneto to set a recovery point;
   3255   1.2    lneto any error jumps to the most recent active recovery point.
   3256   1.2    lneto 
   3257   1.2    lneto 
   3258   1.2    lneto <p>
   3259   1.9   nikita Inside a C&nbsp;function you can raise an error explicitly
   3260   1.9   nikita by calling <a href="#lua_error"><code>lua_error</code></a>.
   3261   1.7  mbalmer 
   3262   1.7  mbalmer 
   3263   1.7  mbalmer <p>
   3264   1.7  mbalmer Most functions in the API can raise an error,
   3265   1.7  mbalmer for instance due to a memory allocation error.
   3266   1.7  mbalmer The documentation for each function indicates whether
   3267   1.7  mbalmer it can raise errors.
   3268   1.7  mbalmer 
   3269   1.7  mbalmer 
   3270   1.7  mbalmer <p>
   3271   1.2    lneto If an error happens outside any protected environment,
   3272   1.2    lneto Lua calls a <em>panic function</em> (see <a href="#lua_atpanic"><code>lua_atpanic</code></a>)
   3273   1.2    lneto and then calls <code>abort</code>,
   3274   1.2    lneto thus exiting the host application.
   3275   1.2    lneto Your panic function can avoid this exit by
   3276   1.2    lneto never returning
   3277   1.2    lneto (e.g., doing a long jump to your own recovery point outside Lua).
   3278   1.2    lneto 
   3279   1.2    lneto 
   3280   1.2    lneto <p>
   3281   1.7  mbalmer The panic function,
   3282   1.7  mbalmer as its name implies,
   3283   1.7  mbalmer is a mechanism of last resort.
   3284   1.7  mbalmer Programs should avoid it.
   3285   1.7  mbalmer As a general rule,
   3286   1.7  mbalmer when a C&nbsp;function is called by Lua with a Lua state,
   3287   1.7  mbalmer it can do whatever it wants on that Lua state,
   3288   1.7  mbalmer as it should be already protected.
   3289   1.7  mbalmer However,
   3290   1.7  mbalmer when C code operates on other Lua states
   3291   1.9   nikita (e.g., a Lua-state argument to the function,
   3292   1.7  mbalmer a Lua state stored in the registry, or
   3293   1.7  mbalmer the result of <a href="#lua_newthread"><code>lua_newthread</code></a>),
   3294   1.7  mbalmer it should use them only in API calls that cannot raise errors.
   3295   1.7  mbalmer 
   3296   1.7  mbalmer 
   3297   1.7  mbalmer <p>
   3298   1.2    lneto The panic function runs as if it were a message handler (see <a href="#2.3">&sect;2.3</a>);
   3299   1.9   nikita in particular, the error object is on the top of the stack.
   3300   1.3    lneto However, there is no guarantee about stack space.
   3301   1.2    lneto To push anything on the stack,
   3302   1.9   nikita the panic function must first check the available space (see <a href="#4.1.1">&sect;4.1.1</a>).
   3303   1.9   nikita 
   3304   1.9   nikita 
   3305   1.9   nikita 
   3306   1.9   nikita 
   3307   1.9   nikita 
   3308   1.9   nikita <h3>4.4.1 &ndash; <a name="4.4.1">Status Codes</a></h3>
   3309   1.9   nikita 
   3310   1.9   nikita <p>
   3311   1.9   nikita Several functions that report errors in the API use the following
   3312   1.9   nikita status codes to indicate different kinds of errors or other conditions:
   3313   1.9   nikita 
   3314   1.9   nikita <ul>
   3315   1.9   nikita 
   3316   1.9   nikita <li><b><a name="pdf-LUA_OK"><code>LUA_OK</code></a> (0): </b> no errors.</li>
   3317   1.9   nikita 
   3318   1.9   nikita <li><b><a name="pdf-LUA_ERRRUN"><code>LUA_ERRRUN</code></a>: </b> a runtime error.</li>
   3319   1.9   nikita 
   3320   1.9   nikita <li><b><a name="pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>: </b>
   3321   1.9   nikita memory allocation error.
   3322   1.9   nikita For such errors, Lua does not call the message handler.
   3323   1.9   nikita </li>
   3324   1.9   nikita 
   3325   1.9   nikita <li><b><a name="pdf-LUA_ERRERR"><code>LUA_ERRERR</code></a>: </b> error while running the message handler.</li>
   3326   1.9   nikita 
   3327   1.9   nikita <li><b><a name="pdf-LUA_ERRSYNTAX"><code>LUA_ERRSYNTAX</code></a>: </b> syntax error during precompilation.</li>
   3328   1.9   nikita 
   3329   1.9   nikita <li><b><a name="pdf-LUA_YIELD"><code>LUA_YIELD</code></a>: </b> the thread (coroutine) yields.</li>
   3330   1.9   nikita 
   3331   1.9   nikita <li><b><a name="pdf-LUA_ERRFILE"><code>LUA_ERRFILE</code></a>: </b> a file-related error;
   3332   1.9   nikita e.g., it cannot open or read the file.</li>
   3333   1.9   nikita 
   3334   1.9   nikita </ul><p>
   3335   1.9   nikita These constants are defined in the header file <code>lua.h</code>.
   3336   1.9   nikita 
   3337   1.9   nikita 
   3338   1.1  mbalmer 
   3339   1.1  mbalmer 
   3340   1.2    lneto 
   3341   1.2    lneto 
   3342   1.2    lneto 
   3343   1.9   nikita <h2>4.5 &ndash; <a name="4.5">Handling Yields in C</a></h2>
   3344   1.2    lneto 
   3345   1.2    lneto <p>
   3346   1.2    lneto Internally, Lua uses the C <code>longjmp</code> facility to yield a coroutine.
   3347   1.7  mbalmer Therefore, if a C&nbsp;function <code>foo</code> calls an API function
   3348   1.2    lneto and this API function yields
   3349   1.2    lneto (directly or indirectly by calling another function that yields),
   3350   1.2    lneto Lua cannot return to <code>foo</code> any more,
   3351   1.9   nikita because the <code>longjmp</code> removes its frame from the C&nbsp;stack.
   3352   1.2    lneto 
   3353   1.2    lneto 
   3354   1.2    lneto <p>
   3355   1.2    lneto To avoid this kind of problem,
   3356   1.2    lneto Lua raises an error whenever it tries to yield across an API call,
   3357   1.2    lneto except for three functions:
   3358   1.2    lneto <a href="#lua_yieldk"><code>lua_yieldk</code></a>, <a href="#lua_callk"><code>lua_callk</code></a>, and <a href="#lua_pcallk"><code>lua_pcallk</code></a>.
   3359   1.2    lneto All those functions receive a <em>continuation function</em>
   3360   1.3    lneto (as a parameter named <code>k</code>) to continue execution after a yield.
   3361   1.2    lneto 
   3362   1.2    lneto 
   3363   1.2    lneto <p>
   3364   1.2    lneto We need to set some terminology to explain continuations.
   3365   1.7  mbalmer We have a C&nbsp;function called from Lua which we will call
   3366   1.2    lneto the <em>original function</em>.
   3367   1.2    lneto This original function then calls one of those three functions in the C API,
   3368   1.2    lneto which we will call the <em>callee function</em>,
   3369   1.2    lneto that then yields the current thread.
   3370   1.9   nikita This can happen when the callee function is <a href="#lua_yieldk"><code>lua_yieldk</code></a>,
   3371   1.2    lneto or when the callee function is either <a href="#lua_callk"><code>lua_callk</code></a> or <a href="#lua_pcallk"><code>lua_pcallk</code></a>
   3372   1.9   nikita and the function called by them yields.
   3373   1.2    lneto 
   3374   1.2    lneto 
   3375   1.2    lneto <p>
   3376   1.2    lneto Suppose the running thread yields while executing the callee function.
   3377   1.2    lneto After the thread resumes,
   3378   1.2    lneto it eventually will finish running the callee function.
   3379   1.2    lneto However,
   3380   1.2    lneto the callee function cannot return to the original function,
   3381   1.9   nikita because its frame in the C&nbsp;stack was destroyed by the yield.
   3382   1.2    lneto Instead, Lua calls a <em>continuation function</em>,
   3383   1.2    lneto which was given as an argument to the callee function.
   3384   1.2    lneto As the name implies,
   3385   1.2    lneto the continuation function should continue the task
   3386   1.2    lneto of the original function.
   3387   1.2    lneto 
   3388   1.2    lneto 
   3389   1.2    lneto <p>
   3390   1.2    lneto As an illustration, consider the following function:
   3391   1.2    lneto 
   3392   1.2    lneto <pre>
   3393   1.2    lneto      int original_function (lua_State *L) {
   3394   1.2    lneto        ...     /* code 1 */
   3395   1.2    lneto        status = lua_pcall(L, n, m, h);  /* calls Lua */
   3396   1.2    lneto        ...     /* code 2 */
   3397   1.2    lneto      }
   3398   1.2    lneto </pre><p>
   3399   1.2    lneto Now we want to allow
   3400   1.3    lneto the Lua code being run by <a href="#lua_pcall"><code>lua_pcall</code></a> to yield.
   3401   1.2    lneto First, we can rewrite our function like here:
   3402   1.2    lneto 
   3403   1.2    lneto <pre>
   3404   1.3    lneto      int k (lua_State *L, int status, lua_KContext ctx) {
   3405   1.2    lneto        ...  /* code 2 */
   3406   1.2    lneto      }
   3407   1.2    lneto      
   3408   1.2    lneto      int original_function (lua_State *L) {
   3409   1.2    lneto        ...     /* code 1 */
   3410   1.2    lneto        return k(L, lua_pcall(L, n, m, h), ctx);
   3411   1.2    lneto      }
   3412   1.2    lneto </pre><p>
   3413   1.2    lneto In the above code,
   3414   1.2    lneto the new function <code>k</code> is a
   3415   1.2    lneto <em>continuation function</em> (with type <a href="#lua_KFunction"><code>lua_KFunction</code></a>),
   3416   1.2    lneto which should do all the work that the original function
   3417   1.2    lneto was doing after calling <a href="#lua_pcall"><code>lua_pcall</code></a>.
   3418   1.2    lneto Now, we must inform Lua that it must call <code>k</code> if the Lua code
   3419   1.3    lneto being executed by <a href="#lua_pcall"><code>lua_pcall</code></a> gets interrupted in some way
   3420   1.2    lneto (errors or yielding),
   3421   1.2    lneto so we rewrite the code as here,
   3422   1.2    lneto replacing <a href="#lua_pcall"><code>lua_pcall</code></a> by <a href="#lua_pcallk"><code>lua_pcallk</code></a>:
   3423   1.2    lneto 
   3424   1.2    lneto <pre>
   3425   1.2    lneto      int original_function (lua_State *L) {
   3426   1.2    lneto        ...     /* code 1 */
   3427   1.2    lneto        return k(L, lua_pcallk(L, n, m, h, ctx2, k), ctx1);
   3428   1.2    lneto      }
   3429   1.3    lneto </pre><p>
   3430   1.3    lneto Note the external, explicit call to the continuation:
   3431   1.3    lneto Lua will call the continuation only if needed, that is,
   3432   1.3    lneto in case of errors or resuming after a yield.
   3433   1.3    lneto If the called function returns normally without ever yielding,
   3434   1.3    lneto <a href="#lua_pcallk"><code>lua_pcallk</code></a> (and <a href="#lua_callk"><code>lua_callk</code></a>) will also return normally.
   3435   1.3    lneto (Of course, instead of calling the continuation in that case,
   3436   1.3    lneto you can do the equivalent work directly inside the original function.)
   3437   1.3    lneto 
   3438   1.2    lneto 
   3439   1.2    lneto <p>
   3440   1.2    lneto Besides the Lua state,
   3441   1.2    lneto the continuation function has two other parameters:
   3442   1.9   nikita the final status of the call and the context value (<code>ctx</code>) that
   3443   1.2    lneto was passed originally to <a href="#lua_pcallk"><code>lua_pcallk</code></a>.
   3444   1.9   nikita Lua does not use this context value;
   3445   1.2    lneto it only passes this value from the original function to the
   3446   1.9   nikita continuation function.
   3447   1.2    lneto For <a href="#lua_pcallk"><code>lua_pcallk</code></a>,
   3448   1.2    lneto the status is the same value that would be returned by <a href="#lua_pcallk"><code>lua_pcallk</code></a>,
   3449   1.3    lneto except that it is <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when being executed after a yield
   3450   1.2    lneto (instead of <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>).
   3451   1.2    lneto For <a href="#lua_yieldk"><code>lua_yieldk</code></a> and <a href="#lua_callk"><code>lua_callk</code></a>,
   3452   1.2    lneto the status is always <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when Lua calls the continuation.
   3453   1.2    lneto (For these two functions,
   3454   1.2    lneto Lua will not call the continuation in case of errors,
   3455   1.2    lneto because they do not handle errors.)
   3456   1.3    lneto Similarly, when using <a href="#lua_callk"><code>lua_callk</code></a>,
   3457   1.3    lneto you should call the continuation function
   3458   1.3    lneto with <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> as the status.
   3459   1.3    lneto (For <a href="#lua_yieldk"><code>lua_yieldk</code></a>, there is not much point in calling
   3460   1.3    lneto directly the continuation function,
   3461   1.3    lneto because <a href="#lua_yieldk"><code>lua_yieldk</code></a> usually does not return.)
   3462   1.1  mbalmer 
   3463   1.1  mbalmer 
   3464   1.1  mbalmer <p>
   3465   1.2    lneto Lua treats the continuation function as if it were the original function.
   3466   1.2    lneto The continuation function receives the same Lua stack
   3467   1.2    lneto from the original function,
   3468   1.2    lneto in the same state it would be if the callee function had returned.
   3469   1.2    lneto (For instance,
   3470   1.2    lneto after a <a href="#lua_callk"><code>lua_callk</code></a> the function and its arguments are
   3471   1.2    lneto removed from the stack and replaced by the results from the call.)
   3472   1.2    lneto It also has the same upvalues.
   3473   1.2    lneto Whatever it returns is handled by Lua as if it were the return
   3474   1.2    lneto of the original function.
   3475   1.1  mbalmer 
   3476   1.1  mbalmer 
   3477   1.1  mbalmer 
   3478   1.1  mbalmer 
   3479   1.1  mbalmer 
   3480   1.9   nikita <h2>4.6 &ndash; <a name="4.6">Functions and Types</a></h2>
   3481   1.1  mbalmer 
   3482   1.1  mbalmer <p>
   3483   1.1  mbalmer Here we list all functions and types from the C&nbsp;API in
   3484   1.1  mbalmer alphabetical order.
   3485   1.1  mbalmer Each function has an indicator like this:
   3486   1.1  mbalmer <span class="apii">[-o, +p, <em>x</em>]</span>
   3487   1.1  mbalmer 
   3488   1.1  mbalmer 
   3489   1.1  mbalmer <p>
   3490   1.1  mbalmer The first field, <code>o</code>,
   3491   1.1  mbalmer is how many elements the function pops from the stack.
   3492   1.1  mbalmer The second field, <code>p</code>,
   3493   1.1  mbalmer is how many elements the function pushes onto the stack.
   3494   1.1  mbalmer (Any function always pushes its results after popping its arguments.)
   3495   1.1  mbalmer A field in the form <code>x|y</code> means the function can push (or pop)
   3496   1.1  mbalmer <code>x</code> or <code>y</code> elements,
   3497   1.1  mbalmer depending on the situation;
   3498   1.1  mbalmer an interrogation mark '<code>?</code>' means that
   3499   1.1  mbalmer we cannot know how many elements the function pops/pushes
   3500   1.9   nikita by looking only at its arguments.
   3501   1.9   nikita (For instance, they may depend on what is in the stack.)
   3502   1.1  mbalmer The third field, <code>x</code>,
   3503   1.2    lneto tells whether the function may raise errors:
   3504   1.2    lneto '<code>-</code>' means the function never raises any error;
   3505   1.9   nikita '<code>m</code>' means the function may raise only out-of-memory errors;
   3506   1.9   nikita '<code>v</code>' means the function may raise the errors explained in the text;
   3507   1.9   nikita '<code>e</code>' means the function can run arbitrary Lua code,
   3508   1.9   nikita either directly or through metamethods,
   3509   1.9   nikita and therefore may raise any errors.
   3510   1.2    lneto 
   3511   1.2    lneto 
   3512   1.2    lneto 
   3513   1.2    lneto <hr><h3><a name="lua_absindex"><code>lua_absindex</code></a></h3><p>
   3514   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   3515   1.2    lneto <pre>int lua_absindex (lua_State *L, int idx);</pre>
   3516   1.2    lneto 
   3517   1.2    lneto <p>
   3518   1.4  mbalmer Converts the acceptable index <code>idx</code>
   3519   1.4  mbalmer into an equivalent absolute index
   3520   1.9   nikita (that is, one that does not depend on the stack size).
   3521   1.2    lneto 
   3522   1.2    lneto 
   3523   1.1  mbalmer 
   3524   1.1  mbalmer 
   3525   1.1  mbalmer 
   3526   1.1  mbalmer <hr><h3><a name="lua_Alloc"><code>lua_Alloc</code></a></h3>
   3527   1.1  mbalmer <pre>typedef void * (*lua_Alloc) (void *ud,
   3528   1.1  mbalmer                              void *ptr,
   3529   1.1  mbalmer                              size_t osize,
   3530   1.1  mbalmer                              size_t nsize);</pre>
   3531   1.1  mbalmer 
   3532   1.1  mbalmer <p>
   3533   1.1  mbalmer The type of the memory-allocation function used by Lua states.
   3534   1.1  mbalmer The allocator function must provide a
   3535   1.1  mbalmer functionality similar to <code>realloc</code>,
   3536   1.1  mbalmer but not exactly the same.
   3537   1.1  mbalmer Its arguments are
   3538   1.1  mbalmer <code>ud</code>, an opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>;
   3539   1.1  mbalmer <code>ptr</code>, a pointer to the block being allocated/reallocated/freed;
   3540   1.2    lneto <code>osize</code>, the original size of the block or some code about what
   3541   1.2    lneto is being allocated;
   3542   1.3    lneto and <code>nsize</code>, the new size of the block.
   3543   1.2    lneto 
   3544   1.2    lneto 
   3545   1.2    lneto <p>
   3546   1.2    lneto When <code>ptr</code> is not <code>NULL</code>,
   3547   1.2    lneto <code>osize</code> is the size of the block pointed by <code>ptr</code>,
   3548   1.2    lneto that is, the size given when it was allocated or reallocated.
   3549   1.2    lneto 
   3550   1.2    lneto 
   3551   1.2    lneto <p>
   3552   1.2    lneto When <code>ptr</code> is <code>NULL</code>,
   3553   1.2    lneto <code>osize</code> encodes the kind of object that Lua is allocating.
   3554   1.2    lneto <code>osize</code> is any of
   3555   1.2    lneto <a href="#pdf-LUA_TSTRING"><code>LUA_TSTRING</code></a>, <a href="#pdf-LUA_TTABLE"><code>LUA_TTABLE</code></a>, <a href="#pdf-LUA_TFUNCTION"><code>LUA_TFUNCTION</code></a>,
   3556   1.2    lneto <a href="#pdf-LUA_TUSERDATA"><code>LUA_TUSERDATA</code></a>, or <a href="#pdf-LUA_TTHREAD"><code>LUA_TTHREAD</code></a> when (and only when)
   3557   1.2    lneto Lua is creating a new object of that type.
   3558   1.2    lneto When <code>osize</code> is some other value,
   3559   1.2    lneto Lua is allocating memory for something else.
   3560   1.2    lneto 
   3561   1.2    lneto 
   3562   1.2    lneto <p>
   3563   1.2    lneto Lua assumes the following behavior from the allocator function:
   3564   1.2    lneto 
   3565   1.2    lneto 
   3566   1.2    lneto <p>
   3567   1.2    lneto When <code>nsize</code> is zero,
   3568   1.2    lneto the allocator must behave like <code>free</code>
   3569   1.9   nikita and then return <code>NULL</code>.
   3570   1.2    lneto 
   3571   1.2    lneto 
   3572   1.2    lneto <p>
   3573   1.2    lneto When <code>nsize</code> is not zero,
   3574   1.2    lneto the allocator must behave like <code>realloc</code>.
   3575   1.9   nikita In particular, the allocator returns <code>NULL</code>
   3576   1.2    lneto if and only if it cannot fulfill the request.
   3577   1.1  mbalmer 
   3578   1.1  mbalmer 
   3579   1.1  mbalmer <p>
   3580   1.1  mbalmer Here is a simple implementation for the allocator function.
   3581   1.1  mbalmer It is used in the auxiliary library by <a href="#luaL_newstate"><code>luaL_newstate</code></a>.
   3582   1.1  mbalmer 
   3583   1.1  mbalmer <pre>
   3584   1.1  mbalmer      static void *l_alloc (void *ud, void *ptr, size_t osize,
   3585   1.1  mbalmer                                                 size_t nsize) {
   3586   1.1  mbalmer        (void)ud;  (void)osize;  /* not used */
   3587   1.1  mbalmer        if (nsize == 0) {
   3588   1.1  mbalmer          free(ptr);
   3589   1.1  mbalmer          return NULL;
   3590   1.1  mbalmer        }
   3591   1.1  mbalmer        else
   3592   1.1  mbalmer          return realloc(ptr, nsize);
   3593   1.1  mbalmer      }
   3594   1.1  mbalmer </pre><p>
   3595  1.10   nikita Note that ISO&nbsp;C ensures
   3596   1.1  mbalmer that <code>free(NULL)</code> has no effect and that
   3597   1.3    lneto <code>realloc(NULL,size)</code> is equivalent to <code>malloc(size)</code>.
   3598   1.1  mbalmer 
   3599   1.1  mbalmer 
   3600   1.1  mbalmer 
   3601   1.1  mbalmer 
   3602   1.1  mbalmer 
   3603   1.2    lneto <hr><h3><a name="lua_arith"><code>lua_arith</code></a></h3><p>
   3604   1.2    lneto <span class="apii">[-(2|1), +1, <em>e</em>]</span>
   3605   1.2    lneto <pre>void lua_arith (lua_State *L, int op);</pre>
   3606   1.1  mbalmer 
   3607   1.1  mbalmer <p>
   3608   1.2    lneto Performs an arithmetic or bitwise operation over the two values
   3609   1.2    lneto (or one, in the case of negations)
   3610   1.2    lneto at the top of the stack,
   3611   1.9   nikita with the value on the top being the second operand,
   3612   1.2    lneto pops these values, and pushes the result of the operation.
   3613   1.2    lneto The function follows the semantics of the corresponding Lua operator
   3614   1.2    lneto (that is, it may call metamethods).
   3615   1.1  mbalmer 
   3616   1.1  mbalmer 
   3617   1.1  mbalmer <p>
   3618   1.2    lneto The value of <code>op</code> must be one of the following constants:
   3619   1.2    lneto 
   3620   1.2    lneto <ul>
   3621   1.2    lneto 
   3622   1.2    lneto <li><b><a name="pdf-LUA_OPADD"><code>LUA_OPADD</code></a>: </b> performs addition (<code>+</code>)</li>
   3623   1.2    lneto <li><b><a name="pdf-LUA_OPSUB"><code>LUA_OPSUB</code></a>: </b> performs subtraction (<code>-</code>)</li>
   3624   1.2    lneto <li><b><a name="pdf-LUA_OPMUL"><code>LUA_OPMUL</code></a>: </b> performs multiplication (<code>*</code>)</li>
   3625   1.2    lneto <li><b><a name="pdf-LUA_OPDIV"><code>LUA_OPDIV</code></a>: </b> performs float division (<code>/</code>)</li>
   3626   1.3    lneto <li><b><a name="pdf-LUA_OPIDIV"><code>LUA_OPIDIV</code></a>: </b> performs floor division (<code>//</code>)</li>
   3627   1.2    lneto <li><b><a name="pdf-LUA_OPMOD"><code>LUA_OPMOD</code></a>: </b> performs modulo (<code>%</code>)</li>
   3628   1.2    lneto <li><b><a name="pdf-LUA_OPPOW"><code>LUA_OPPOW</code></a>: </b> performs exponentiation (<code>^</code>)</li>
   3629   1.2    lneto <li><b><a name="pdf-LUA_OPUNM"><code>LUA_OPUNM</code></a>: </b> performs mathematical negation (unary <code>-</code>)</li>
   3630   1.6  salazar <li><b><a name="pdf-LUA_OPBNOT"><code>LUA_OPBNOT</code></a>: </b> performs bitwise NOT (<code>~</code>)</li>
   3631   1.6  salazar <li><b><a name="pdf-LUA_OPBAND"><code>LUA_OPBAND</code></a>: </b> performs bitwise AND (<code>&amp;</code>)</li>
   3632   1.6  salazar <li><b><a name="pdf-LUA_OPBOR"><code>LUA_OPBOR</code></a>: </b> performs bitwise OR (<code>|</code>)</li>
   3633   1.6  salazar <li><b><a name="pdf-LUA_OPBXOR"><code>LUA_OPBXOR</code></a>: </b> performs bitwise exclusive OR (<code>~</code>)</li>
   3634   1.2    lneto <li><b><a name="pdf-LUA_OPSHL"><code>LUA_OPSHL</code></a>: </b> performs left shift (<code>&lt;&lt;</code>)</li>
   3635   1.2    lneto <li><b><a name="pdf-LUA_OPSHR"><code>LUA_OPSHR</code></a>: </b> performs right shift (<code>&gt;&gt;</code>)</li>
   3636   1.2    lneto 
   3637   1.2    lneto </ul>
   3638   1.2    lneto 
   3639   1.2    lneto 
   3640   1.2    lneto 
   3641   1.1  mbalmer 
   3642   1.2    lneto <hr><h3><a name="lua_atpanic"><code>lua_atpanic</code></a></h3><p>
   3643   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   3644   1.2    lneto <pre>lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);</pre>
   3645   1.1  mbalmer 
   3646   1.1  mbalmer <p>
   3647   1.9   nikita Sets a new panic function and returns the old one (see <a href="#4.4">&sect;4.4</a>).
   3648   1.1  mbalmer 
   3649   1.1  mbalmer 
   3650   1.1  mbalmer 
   3651   1.1  mbalmer 
   3652   1.1  mbalmer 
   3653   1.1  mbalmer <hr><h3><a name="lua_call"><code>lua_call</code></a></h3><p>
   3654   1.2    lneto <span class="apii">[-(nargs+1), +nresults, <em>e</em>]</span>
   3655   1.1  mbalmer <pre>void lua_call (lua_State *L, int nargs, int nresults);</pre>
   3656   1.1  mbalmer 
   3657   1.1  mbalmer <p>
   3658   1.1  mbalmer Calls a function.
   3659   1.9   nikita Like regular Lua calls,
   3660   1.9   nikita <code>lua_call</code> respects the <code>__call</code> metamethod.
   3661   1.9   nikita So, here the word "function"
   3662   1.9   nikita means any callable value.
   3663   1.1  mbalmer 
   3664   1.1  mbalmer 
   3665   1.1  mbalmer <p>
   3666   1.9   nikita To do a call you must use the following protocol:
   3667   1.1  mbalmer first, the function to be called is pushed onto the stack;
   3668   1.9   nikita then, the arguments to the call are pushed
   3669   1.1  mbalmer in direct order;
   3670   1.1  mbalmer that is, the first argument is pushed first.
   3671   1.1  mbalmer Finally you call <a href="#lua_call"><code>lua_call</code></a>;
   3672   1.1  mbalmer <code>nargs</code> is the number of arguments that you pushed onto the stack.
   3673   1.9   nikita When the function returns,
   3674   1.9   nikita all arguments and the function value are popped
   3675   1.9   nikita and the call results are pushed onto the stack.
   3676   1.1  mbalmer The number of results is adjusted to <code>nresults</code>,
   3677   1.1  mbalmer unless <code>nresults</code> is <a name="pdf-LUA_MULTRET"><code>LUA_MULTRET</code></a>.
   3678   1.7  mbalmer In this case, all results from the function are pushed;
   3679   1.5    lneto Lua takes care that the returned values fit into the stack space,
   3680   1.5    lneto but it does not ensure any extra space in the stack.
   3681   1.1  mbalmer The function results are pushed onto the stack in direct order
   3682   1.1  mbalmer (the first result is pushed first),
   3683   1.1  mbalmer so that after the call the last result is on the top of the stack.
   3684   1.1  mbalmer 
   3685   1.1  mbalmer 
   3686   1.1  mbalmer <p>
   3687   1.9   nikita Any error while calling and running the function is propagated upwards
   3688   1.1  mbalmer (with a <code>longjmp</code>).
   3689   1.1  mbalmer 
   3690   1.1  mbalmer 
   3691   1.1  mbalmer <p>
   3692   1.1  mbalmer The following example shows how the host program can do the
   3693   1.1  mbalmer equivalent to this Lua code:
   3694   1.1  mbalmer 
   3695   1.1  mbalmer <pre>
   3696   1.1  mbalmer      a = f("how", t.x, 14)
   3697   1.1  mbalmer </pre><p>
   3698   1.1  mbalmer Here it is in&nbsp;C:
   3699   1.1  mbalmer 
   3700   1.1  mbalmer <pre>
   3701   1.2    lneto      lua_getglobal(L, "f");                  /* function to be called */
   3702   1.3    lneto      lua_pushliteral(L, "how");                       /* 1st argument */
   3703   1.2    lneto      lua_getglobal(L, "t");                    /* table to be indexed */
   3704   1.1  mbalmer      lua_getfield(L, -1, "x");        /* push result of t.x (2nd arg) */
   3705   1.1  mbalmer      lua_remove(L, -2);                  /* remove 't' from the stack */
   3706   1.1  mbalmer      lua_pushinteger(L, 14);                          /* 3rd argument */
   3707   1.1  mbalmer      lua_call(L, 3, 1);     /* call 'f' with 3 arguments and 1 result */
   3708   1.2    lneto      lua_setglobal(L, "a");                         /* set global 'a' */
   3709   1.1  mbalmer </pre><p>
   3710   1.3    lneto Note that the code above is <em>balanced</em>:
   3711   1.1  mbalmer at its end, the stack is back to its original configuration.
   3712   1.1  mbalmer This is considered good programming practice.
   3713   1.1  mbalmer 
   3714   1.1  mbalmer 
   3715   1.1  mbalmer 
   3716   1.1  mbalmer 
   3717   1.1  mbalmer 
   3718   1.2    lneto <hr><h3><a name="lua_callk"><code>lua_callk</code></a></h3><p>
   3719   1.2    lneto <span class="apii">[-(nargs + 1), +nresults, <em>e</em>]</span>
   3720   1.3    lneto <pre>void lua_callk (lua_State *L,
   3721   1.3    lneto                 int nargs,
   3722   1.3    lneto                 int nresults,
   3723   1.3    lneto                 lua_KContext ctx,
   3724   1.2    lneto                 lua_KFunction k);</pre>
   3725   1.2    lneto 
   3726   1.2    lneto <p>
   3727   1.2    lneto This function behaves exactly like <a href="#lua_call"><code>lua_call</code></a>,
   3728   1.9   nikita but allows the called function to yield (see <a href="#4.5">&sect;4.5</a>).
   3729   1.2    lneto 
   3730   1.2    lneto 
   3731   1.2    lneto 
   3732   1.2    lneto 
   3733   1.2    lneto 
   3734   1.1  mbalmer <hr><h3><a name="lua_CFunction"><code>lua_CFunction</code></a></h3>
   3735   1.1  mbalmer <pre>typedef int (*lua_CFunction) (lua_State *L);</pre>
   3736   1.1  mbalmer 
   3737   1.1  mbalmer <p>
   3738   1.1  mbalmer Type for C&nbsp;functions.
   3739   1.1  mbalmer 
   3740   1.1  mbalmer 
   3741   1.1  mbalmer <p>
   3742   1.1  mbalmer In order to communicate properly with Lua,
   3743   1.1  mbalmer a C&nbsp;function must use the following protocol,
   3744   1.1  mbalmer which defines the way parameters and results are passed:
   3745   1.1  mbalmer a C&nbsp;function receives its arguments from Lua in its stack
   3746   1.1  mbalmer in direct order (the first argument is pushed first).
   3747   1.1  mbalmer So, when the function starts,
   3748   1.1  mbalmer <code>lua_gettop(L)</code> returns the number of arguments received by the function.
   3749   1.1  mbalmer The first argument (if any) is at index 1
   3750   1.1  mbalmer and its last argument is at index <code>lua_gettop(L)</code>.
   3751   1.1  mbalmer To return values to Lua, a C&nbsp;function just pushes them onto the stack,
   3752   1.1  mbalmer in direct order (the first result is pushed first),
   3753   1.9   nikita and returns in C the number of results.
   3754   1.1  mbalmer Any other value in the stack below the results will be properly
   3755   1.1  mbalmer discarded by Lua.
   3756   1.1  mbalmer Like a Lua function, a C&nbsp;function called by Lua can also return
   3757   1.1  mbalmer many results.
   3758   1.1  mbalmer 
   3759   1.1  mbalmer 
   3760   1.1  mbalmer <p>
   3761   1.1  mbalmer As an example, the following function receives a variable number
   3762   1.4  mbalmer of numeric arguments and returns their average and their sum:
   3763   1.1  mbalmer 
   3764   1.1  mbalmer <pre>
   3765   1.1  mbalmer      static int foo (lua_State *L) {
   3766   1.1  mbalmer        int n = lua_gettop(L);    /* number of arguments */
   3767   1.3    lneto        lua_Number sum = 0.0;
   3768   1.1  mbalmer        int i;
   3769   1.1  mbalmer        for (i = 1; i &lt;= n; i++) {
   3770   1.1  mbalmer          if (!lua_isnumber(L, i)) {
   3771   1.3    lneto            lua_pushliteral(L, "incorrect argument");
   3772   1.1  mbalmer            lua_error(L);
   3773   1.1  mbalmer          }
   3774   1.1  mbalmer          sum += lua_tonumber(L, i);
   3775   1.1  mbalmer        }
   3776   1.1  mbalmer        lua_pushnumber(L, sum/n);        /* first result */
   3777   1.1  mbalmer        lua_pushnumber(L, sum);         /* second result */
   3778   1.1  mbalmer        return 2;                   /* number of results */
   3779   1.1  mbalmer      }
   3780   1.1  mbalmer </pre>
   3781   1.1  mbalmer 
   3782   1.1  mbalmer 
   3783   1.1  mbalmer 
   3784   1.1  mbalmer 
   3785   1.1  mbalmer <hr><h3><a name="lua_checkstack"><code>lua_checkstack</code></a></h3><p>
   3786   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   3787   1.3    lneto <pre>int lua_checkstack (lua_State *L, int n);</pre>
   3788   1.1  mbalmer 
   3789   1.1  mbalmer <p>
   3790   1.9   nikita Ensures that the stack has space for at least <code>n</code> extra elements,
   3791   1.9   nikita that is, that you can safely push up to <code>n</code> values into it.
   3792   1.2    lneto It returns false if it cannot fulfill the request,
   3793   1.3    lneto either because it would cause the stack
   3794   1.9   nikita to be greater than a fixed maximum size
   3795   1.3    lneto (typically at least several thousand elements) or
   3796   1.3    lneto because it cannot allocate memory for the extra space.
   3797   1.1  mbalmer This function never shrinks the stack;
   3798   1.9   nikita if the stack already has space for the extra elements,
   3799   1.1  mbalmer it is left unchanged.
   3800   1.1  mbalmer 
   3801   1.1  mbalmer 
   3802   1.1  mbalmer 
   3803   1.1  mbalmer 
   3804   1.1  mbalmer 
   3805   1.1  mbalmer <hr><h3><a name="lua_close"><code>lua_close</code></a></h3><p>
   3806   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   3807   1.1  mbalmer <pre>void lua_close (lua_State *L);</pre>
   3808   1.1  mbalmer 
   3809   1.1  mbalmer <p>
   3810   1.9   nikita Close all active to-be-closed variables in the main thread,
   3811   1.9   nikita release all objects in the given Lua state
   3812   1.9   nikita (calling the corresponding garbage-collection metamethods, if any),
   3813   1.1  mbalmer and frees all dynamic memory used by this state.
   3814   1.9   nikita 
   3815   1.9   nikita 
   3816   1.9   nikita <p>
   3817   1.9   nikita On several platforms, you may not need to call this function,
   3818   1.1  mbalmer because all resources are naturally released when the host program ends.
   3819   1.2    lneto On the other hand, long-running programs that create multiple states,
   3820   1.2    lneto such as daemons or web servers,
   3821   1.3    lneto will probably need to close states as soon as they are not needed.
   3822   1.2    lneto 
   3823   1.1  mbalmer 
   3824   1.1  mbalmer 
   3825   1.1  mbalmer 
   3826   1.1  mbalmer 
   3827   1.9   nikita <hr><h3><a name="lua_closeslot"><code>lua_closeslot</code></a></h3><p>
   3828   1.9   nikita <span class="apii">[-0, +0, <em>e</em>]</span>
   3829   1.9   nikita <pre>void lua_closeslot (lua_State *L, int index);</pre>
   3830   1.9   nikita 
   3831   1.9   nikita <p>
   3832   1.9   nikita Close the to-be-closed slot at the given index and set its value to <b>nil</b>.
   3833   1.9   nikita The index must be the last index previously marked to be closed
   3834   1.9   nikita (see <a href="#lua_toclose"><code>lua_toclose</code></a>) that is still active (that is, not closed yet).
   3835   1.9   nikita 
   3836   1.9   nikita 
   3837   1.9   nikita <p>
   3838   1.9   nikita A <code>__close</code> metamethod cannot yield
   3839   1.9   nikita when called through this function.
   3840   1.9   nikita 
   3841   1.9   nikita 
   3842   1.9   nikita <p>
   3843  1.10   nikita (This function was introduced in release&nbsp;5.4.3.)
   3844  1.10   nikita 
   3845  1.10   nikita 
   3846  1.10   nikita 
   3847  1.10   nikita 
   3848  1.10   nikita 
   3849  1.10   nikita <hr><h3><a name="lua_closethread"><code>lua_closethread</code></a></h3><p>
   3850  1.10   nikita <span class="apii">[-0, +?, &ndash;]</span>
   3851  1.10   nikita <pre>int lua_closethread (lua_State *L, lua_State *from);</pre>
   3852  1.10   nikita 
   3853  1.10   nikita <p>
   3854  1.10   nikita Resets a thread, cleaning its call stack and closing all pending
   3855  1.10   nikita to-be-closed variables.
   3856  1.10   nikita Returns a status code:
   3857  1.10   nikita <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> for no errors in the thread
   3858  1.10   nikita (either the original error that stopped the thread or
   3859  1.10   nikita errors in closing methods),
   3860  1.10   nikita or an error status otherwise.
   3861  1.10   nikita In case of error,
   3862  1.10   nikita leaves the error object on the top of the stack.
   3863  1.10   nikita 
   3864  1.10   nikita 
   3865  1.10   nikita <p>
   3866  1.10   nikita The parameter <code>from</code> represents the coroutine that is resetting <code>L</code>.
   3867  1.10   nikita If there is no such coroutine,
   3868  1.10   nikita this parameter can be <code>NULL</code>.
   3869  1.10   nikita 
   3870  1.10   nikita 
   3871  1.10   nikita <p>
   3872  1.10   nikita (This function was introduced in release&nbsp;5.4.6.)
   3873   1.9   nikita 
   3874   1.9   nikita 
   3875   1.9   nikita 
   3876   1.9   nikita 
   3877   1.9   nikita 
   3878   1.2    lneto <hr><h3><a name="lua_compare"><code>lua_compare</code></a></h3><p>
   3879   1.2    lneto <span class="apii">[-0, +0, <em>e</em>]</span>
   3880   1.2    lneto <pre>int lua_compare (lua_State *L, int index1, int index2, int op);</pre>
   3881   1.2    lneto 
   3882   1.2    lneto <p>
   3883   1.2    lneto Compares two Lua values.
   3884   1.2    lneto Returns 1 if the value at index <code>index1</code> satisfies <code>op</code>
   3885   1.2    lneto when compared with the value at index <code>index2</code>,
   3886   1.2    lneto following the semantics of the corresponding Lua operator
   3887   1.2    lneto (that is, it may call metamethods).
   3888   1.2    lneto Otherwise returns&nbsp;0.
   3889   1.3    lneto Also returns&nbsp;0 if any of the indices is not valid.
   3890   1.2    lneto 
   3891   1.2    lneto 
   3892   1.2    lneto <p>
   3893   1.2    lneto The value of <code>op</code> must be one of the following constants:
   3894   1.2    lneto 
   3895   1.2    lneto <ul>
   3896   1.2    lneto 
   3897   1.2    lneto <li><b><a name="pdf-LUA_OPEQ"><code>LUA_OPEQ</code></a>: </b> compares for equality (<code>==</code>)</li>
   3898   1.2    lneto <li><b><a name="pdf-LUA_OPLT"><code>LUA_OPLT</code></a>: </b> compares for less than (<code>&lt;</code>)</li>
   3899   1.2    lneto <li><b><a name="pdf-LUA_OPLE"><code>LUA_OPLE</code></a>: </b> compares for less or equal (<code>&lt;=</code>)</li>
   3900   1.2    lneto 
   3901   1.2    lneto </ul>
   3902   1.2    lneto 
   3903   1.2    lneto 
   3904   1.2    lneto 
   3905   1.1  mbalmer 
   3906   1.1  mbalmer <hr><h3><a name="lua_concat"><code>lua_concat</code></a></h3><p>
   3907   1.1  mbalmer <span class="apii">[-n, +1, <em>e</em>]</span>
   3908   1.1  mbalmer <pre>void lua_concat (lua_State *L, int n);</pre>
   3909   1.1  mbalmer 
   3910   1.1  mbalmer <p>
   3911   1.1  mbalmer Concatenates the <code>n</code> values at the top of the stack,
   3912   1.9   nikita pops them, and leaves the result on the top.
   3913   1.1  mbalmer If <code>n</code>&nbsp;is&nbsp;1, the result is the single value on the stack
   3914   1.1  mbalmer (that is, the function does nothing);
   3915   1.1  mbalmer if <code>n</code> is 0, the result is the empty string.
   3916   1.1  mbalmer Concatenation is performed following the usual semantics of Lua
   3917   1.2    lneto (see <a href="#3.4.6">&sect;3.4.6</a>).
   3918   1.1  mbalmer 
   3919   1.1  mbalmer 
   3920   1.1  mbalmer 
   3921   1.1  mbalmer 
   3922   1.1  mbalmer 
   3923   1.2    lneto <hr><h3><a name="lua_copy"><code>lua_copy</code></a></h3><p>
   3924   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   3925   1.2    lneto <pre>void lua_copy (lua_State *L, int fromidx, int toidx);</pre>
   3926   1.1  mbalmer 
   3927   1.1  mbalmer <p>
   3928   1.3    lneto Copies the element at index <code>fromidx</code>
   3929   1.3    lneto into the valid index <code>toidx</code>,
   3930   1.3    lneto replacing the value at that position.
   3931   1.3    lneto Values at other positions are not affected.
   3932   1.1  mbalmer 
   3933   1.1  mbalmer 
   3934   1.1  mbalmer 
   3935   1.1  mbalmer 
   3936   1.1  mbalmer 
   3937   1.1  mbalmer <hr><h3><a name="lua_createtable"><code>lua_createtable</code></a></h3><p>
   3938   1.5    lneto <span class="apii">[-0, +1, <em>m</em>]</span>
   3939   1.1  mbalmer <pre>void lua_createtable (lua_State *L, int narr, int nrec);</pre>
   3940   1.1  mbalmer 
   3941   1.1  mbalmer <p>
   3942   1.1  mbalmer Creates a new empty table and pushes it onto the stack.
   3943   1.2    lneto Parameter <code>narr</code> is a hint for how many elements the table
   3944   1.2    lneto will have as a sequence;
   3945   1.2    lneto parameter <code>nrec</code> is a hint for how many other elements
   3946   1.1  mbalmer the table will have.
   3947   1.2    lneto Lua may use these hints to preallocate memory for the new table.
   3948   1.9   nikita This preallocation may help performance when you know in advance
   3949   1.2    lneto how many elements the table will have.
   3950   1.1  mbalmer Otherwise you can use the function <a href="#lua_newtable"><code>lua_newtable</code></a>.
   3951   1.1  mbalmer 
   3952   1.1  mbalmer 
   3953   1.1  mbalmer 
   3954   1.1  mbalmer 
   3955   1.1  mbalmer 
   3956   1.1  mbalmer <hr><h3><a name="lua_dump"><code>lua_dump</code></a></h3><p>
   3957   1.5    lneto <span class="apii">[-0, +0, &ndash;]</span>
   3958   1.2    lneto <pre>int lua_dump (lua_State *L,
   3959   1.2    lneto                         lua_Writer writer,
   3960   1.2    lneto                         void *data,
   3961   1.2    lneto                         int strip);</pre>
   3962   1.1  mbalmer 
   3963   1.1  mbalmer <p>
   3964   1.1  mbalmer Dumps a function as a binary chunk.
   3965   1.1  mbalmer Receives a Lua function on the top of the stack
   3966   1.1  mbalmer and produces a binary chunk that,
   3967   1.1  mbalmer if loaded again,
   3968   1.1  mbalmer results in a function equivalent to the one dumped.
   3969   1.1  mbalmer As it produces parts of the chunk,
   3970   1.1  mbalmer <a href="#lua_dump"><code>lua_dump</code></a> calls function <code>writer</code> (see <a href="#lua_Writer"><code>lua_Writer</code></a>)
   3971   1.1  mbalmer with the given <code>data</code>
   3972   1.1  mbalmer to write them.
   3973   1.1  mbalmer 
   3974   1.1  mbalmer 
   3975   1.1  mbalmer <p>
   3976   1.2    lneto If <code>strip</code> is true,
   3977   1.4  mbalmer the binary representation may not include all debug information
   3978   1.4  mbalmer about the function,
   3979   1.4  mbalmer to save space.
   3980   1.2    lneto 
   3981   1.2    lneto 
   3982   1.2    lneto <p>
   3983   1.1  mbalmer The value returned is the error code returned by the last
   3984   1.1  mbalmer call to the writer;
   3985   1.1  mbalmer 0&nbsp;means no errors.
   3986   1.1  mbalmer 
   3987   1.1  mbalmer 
   3988   1.1  mbalmer <p>
   3989   1.1  mbalmer This function does not pop the Lua function from the stack.
   3990   1.1  mbalmer 
   3991   1.1  mbalmer 
   3992   1.1  mbalmer 
   3993   1.1  mbalmer 
   3994   1.1  mbalmer 
   3995   1.1  mbalmer <hr><h3><a name="lua_error"><code>lua_error</code></a></h3><p>
   3996   1.1  mbalmer <span class="apii">[-1, +0, <em>v</em>]</span>
   3997   1.1  mbalmer <pre>int lua_error (lua_State *L);</pre>
   3998   1.1  mbalmer 
   3999   1.1  mbalmer <p>
   4000   1.9   nikita Raises a Lua error,
   4001   1.9   nikita using the value on the top of the stack as the error object.
   4002   1.1  mbalmer This function does a long jump,
   4003   1.2    lneto and therefore never returns
   4004   1.1  mbalmer (see <a href="#luaL_error"><code>luaL_error</code></a>).
   4005   1.1  mbalmer 
   4006   1.1  mbalmer 
   4007   1.1  mbalmer 
   4008   1.1  mbalmer 
   4009   1.1  mbalmer 
   4010   1.1  mbalmer <hr><h3><a name="lua_gc"><code>lua_gc</code></a></h3><p>
   4011   1.9   nikita <span class="apii">[-0, +0, &ndash;]</span>
   4012   1.9   nikita <pre>int lua_gc (lua_State *L, int what, ...);</pre>
   4013   1.1  mbalmer 
   4014   1.1  mbalmer <p>
   4015   1.1  mbalmer Controls the garbage collector.
   4016   1.1  mbalmer 
   4017   1.1  mbalmer 
   4018   1.1  mbalmer <p>
   4019   1.1  mbalmer This function performs several tasks,
   4020   1.9   nikita according to the value of the parameter <code>what</code>.
   4021   1.9   nikita For options that need extra arguments,
   4022   1.9   nikita they are listed after the option.
   4023   1.1  mbalmer 
   4024   1.1  mbalmer <ul>
   4025   1.1  mbalmer 
   4026   1.9   nikita <li><b><code>LUA_GCCOLLECT</code>: </b>
   4027   1.9   nikita Performs a full garbage-collection cycle.
   4028   1.9   nikita </li>
   4029   1.9   nikita 
   4030   1.2    lneto <li><b><code>LUA_GCSTOP</code>: </b>
   4031   1.9   nikita Stops the garbage collector.
   4032   1.1  mbalmer </li>
   4033   1.1  mbalmer 
   4034   1.2    lneto <li><b><code>LUA_GCRESTART</code>: </b>
   4035   1.9   nikita Restarts the garbage collector.
   4036   1.1  mbalmer </li>
   4037   1.1  mbalmer 
   4038   1.2    lneto <li><b><code>LUA_GCCOUNT</code>: </b>
   4039   1.9   nikita Returns the current amount of memory (in Kbytes) in use by Lua.
   4040   1.1  mbalmer </li>
   4041   1.1  mbalmer 
   4042   1.2    lneto <li><b><code>LUA_GCCOUNTB</code>: </b>
   4043   1.9   nikita Returns the remainder of dividing the current amount of bytes of
   4044   1.1  mbalmer memory in use by Lua by 1024.
   4045   1.1  mbalmer </li>
   4046   1.1  mbalmer 
   4047   1.9   nikita <li><b><code>LUA_GCSTEP</code> <code>(int stepsize)</code>: </b>
   4048   1.9   nikita Performs an incremental step of garbage collection,
   4049   1.9   nikita corresponding to the allocation of <code>stepsize</code> Kbytes.
   4050   1.1  mbalmer </li>
   4051   1.1  mbalmer 
   4052   1.9   nikita <li><b><code>LUA_GCISRUNNING</code>: </b>
   4053   1.9   nikita Returns a boolean that tells whether the collector is running
   4054   1.9   nikita (i.e., not stopped).
   4055   1.1  mbalmer </li>
   4056   1.1  mbalmer 
   4057   1.9   nikita <li><b><code>LUA_GCINC</code> (int pause, int stepmul, stepsize): </b>
   4058   1.9   nikita Changes the collector to incremental mode
   4059   1.9   nikita with the given parameters (see <a href="#2.5.1">&sect;2.5.1</a>).
   4060   1.9   nikita Returns the previous mode (<code>LUA_GCGEN</code> or <code>LUA_GCINC</code>).
   4061   1.2    lneto </li>
   4062   1.2    lneto 
   4063   1.9   nikita <li><b><code>LUA_GCGEN</code> (int minormul, int majormul): </b>
   4064   1.9   nikita Changes the collector to generational mode
   4065   1.9   nikita with the given parameters (see <a href="#2.5.2">&sect;2.5.2</a>).
   4066   1.9   nikita Returns the previous mode (<code>LUA_GCGEN</code> or <code>LUA_GCINC</code>).
   4067   1.1  mbalmer </li>
   4068   1.1  mbalmer 
   4069   1.9   nikita </ul><p>
   4070   1.9   nikita For more details about these options,
   4071   1.9   nikita see <a href="#pdf-collectgarbage"><code>collectgarbage</code></a>.
   4072   1.9   nikita 
   4073   1.1  mbalmer 
   4074   1.2    lneto <p>
   4075   1.9   nikita This function should not be called by a finalizer.
   4076   1.2    lneto 
   4077   1.2    lneto 
   4078   1.1  mbalmer 
   4079   1.1  mbalmer 
   4080   1.1  mbalmer 
   4081   1.1  mbalmer <hr><h3><a name="lua_getallocf"><code>lua_getallocf</code></a></h3><p>
   4082   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   4083   1.1  mbalmer <pre>lua_Alloc lua_getallocf (lua_State *L, void **ud);</pre>
   4084   1.1  mbalmer 
   4085   1.1  mbalmer <p>
   4086   1.1  mbalmer Returns the memory-allocation function of a given state.
   4087   1.1  mbalmer If <code>ud</code> is not <code>NULL</code>, Lua stores in <code>*ud</code> the
   4088   1.3    lneto opaque pointer given when the memory-allocator function was set.
   4089   1.1  mbalmer 
   4090   1.1  mbalmer 
   4091   1.1  mbalmer 
   4092   1.1  mbalmer 
   4093   1.1  mbalmer 
   4094   1.1  mbalmer <hr><h3><a name="lua_getfield"><code>lua_getfield</code></a></h3><p>
   4095   1.1  mbalmer <span class="apii">[-0, +1, <em>e</em>]</span>
   4096   1.2    lneto <pre>int lua_getfield (lua_State *L, int index, const char *k);</pre>
   4097   1.1  mbalmer 
   4098   1.1  mbalmer <p>
   4099   1.1  mbalmer Pushes onto the stack the value <code>t[k]</code>,
   4100   1.2    lneto where <code>t</code> is the value at the given index.
   4101   1.1  mbalmer As in Lua, this function may trigger a metamethod
   4102   1.2    lneto for the "index" event (see <a href="#2.4">&sect;2.4</a>).
   4103   1.2    lneto 
   4104   1.2    lneto 
   4105   1.2    lneto <p>
   4106   1.2    lneto Returns the type of the pushed value.
   4107   1.1  mbalmer 
   4108   1.1  mbalmer 
   4109   1.1  mbalmer 
   4110   1.1  mbalmer 
   4111   1.1  mbalmer 
   4112   1.3    lneto <hr><h3><a name="lua_getextraspace"><code>lua_getextraspace</code></a></h3><p>
   4113   1.3    lneto <span class="apii">[-0, +0, &ndash;]</span>
   4114   1.3    lneto <pre>void *lua_getextraspace (lua_State *L);</pre>
   4115   1.3    lneto 
   4116   1.3    lneto <p>
   4117   1.3    lneto Returns a pointer to a raw memory area associated with the
   4118   1.3    lneto given Lua state.
   4119   1.3    lneto The application can use this area for any purpose;
   4120   1.3    lneto Lua does not use it for anything.
   4121   1.3    lneto 
   4122   1.3    lneto 
   4123   1.3    lneto <p>
   4124   1.3    lneto Each new thread has this area initialized with a copy
   4125   1.3    lneto of the area of the main thread.
   4126   1.3    lneto 
   4127   1.3    lneto 
   4128   1.3    lneto <p>
   4129   1.3    lneto By default, this area has the size of a pointer to void,
   4130   1.3    lneto but you can recompile Lua with a different size for this area.
   4131   1.3    lneto (See <code>LUA_EXTRASPACE</code> in <code>luaconf.h</code>.)
   4132   1.3    lneto 
   4133   1.3    lneto 
   4134   1.3    lneto 
   4135   1.3    lneto 
   4136   1.3    lneto 
   4137   1.1  mbalmer <hr><h3><a name="lua_getglobal"><code>lua_getglobal</code></a></h3><p>
   4138   1.1  mbalmer <span class="apii">[-0, +1, <em>e</em>]</span>
   4139   1.2    lneto <pre>int lua_getglobal (lua_State *L, const char *name);</pre>
   4140   1.1  mbalmer 
   4141   1.1  mbalmer <p>
   4142   1.1  mbalmer Pushes onto the stack the value of the global <code>name</code>.
   4143   1.2    lneto Returns the type of that value.
   4144   1.1  mbalmer 
   4145   1.1  mbalmer 
   4146   1.1  mbalmer 
   4147   1.1  mbalmer 
   4148   1.1  mbalmer 
   4149   1.3    lneto <hr><h3><a name="lua_geti"><code>lua_geti</code></a></h3><p>
   4150   1.3    lneto <span class="apii">[-0, +1, <em>e</em>]</span>
   4151   1.3    lneto <pre>int lua_geti (lua_State *L, int index, lua_Integer i);</pre>
   4152   1.3    lneto 
   4153   1.3    lneto <p>
   4154   1.3    lneto Pushes onto the stack the value <code>t[i]</code>,
   4155   1.3    lneto where <code>t</code> is the value at the given index.
   4156   1.3    lneto As in Lua, this function may trigger a metamethod
   4157   1.3    lneto for the "index" event (see <a href="#2.4">&sect;2.4</a>).
   4158   1.3    lneto 
   4159   1.3    lneto 
   4160   1.3    lneto <p>
   4161   1.3    lneto Returns the type of the pushed value.
   4162   1.3    lneto 
   4163   1.3    lneto 
   4164   1.3    lneto 
   4165   1.3    lneto 
   4166   1.3    lneto 
   4167   1.1  mbalmer <hr><h3><a name="lua_getmetatable"><code>lua_getmetatable</code></a></h3><p>
   4168   1.2    lneto <span class="apii">[-0, +(0|1), &ndash;]</span>
   4169   1.1  mbalmer <pre>int lua_getmetatable (lua_State *L, int index);</pre>
   4170   1.1  mbalmer 
   4171   1.1  mbalmer <p>
   4172   1.3    lneto If the value at the given index has a metatable,
   4173   1.3    lneto the function pushes that metatable onto the stack and returns&nbsp;1.
   4174   1.3    lneto Otherwise,
   4175   1.1  mbalmer the function returns&nbsp;0 and pushes nothing on the stack.
   4176   1.1  mbalmer 
   4177   1.1  mbalmer 
   4178   1.1  mbalmer 
   4179   1.1  mbalmer 
   4180   1.1  mbalmer 
   4181   1.1  mbalmer <hr><h3><a name="lua_gettable"><code>lua_gettable</code></a></h3><p>
   4182   1.1  mbalmer <span class="apii">[-1, +1, <em>e</em>]</span>
   4183   1.2    lneto <pre>int lua_gettable (lua_State *L, int index);</pre>
   4184   1.1  mbalmer 
   4185   1.1  mbalmer <p>
   4186   1.1  mbalmer Pushes onto the stack the value <code>t[k]</code>,
   4187   1.2    lneto where <code>t</code> is the value at the given index
   4188   1.9   nikita and <code>k</code> is the value on the top of the stack.
   4189   1.1  mbalmer 
   4190   1.1  mbalmer 
   4191   1.1  mbalmer <p>
   4192   1.3    lneto This function pops the key from the stack,
   4193   1.3    lneto pushing the resulting value in its place.
   4194   1.1  mbalmer As in Lua, this function may trigger a metamethod
   4195   1.2    lneto for the "index" event (see <a href="#2.4">&sect;2.4</a>).
   4196   1.2    lneto 
   4197   1.2    lneto 
   4198   1.2    lneto <p>
   4199   1.2    lneto Returns the type of the pushed value.
   4200   1.1  mbalmer 
   4201   1.1  mbalmer 
   4202   1.1  mbalmer 
   4203   1.1  mbalmer 
   4204   1.1  mbalmer 
   4205   1.1  mbalmer <hr><h3><a name="lua_gettop"><code>lua_gettop</code></a></h3><p>
   4206   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   4207   1.1  mbalmer <pre>int lua_gettop (lua_State *L);</pre>
   4208   1.1  mbalmer 
   4209   1.1  mbalmer <p>
   4210   1.1  mbalmer Returns the index of the top element in the stack.
   4211   1.1  mbalmer Because indices start at&nbsp;1,
   4212   1.3    lneto this result is equal to the number of elements in the stack;
   4213   1.3    lneto in particular, 0&nbsp;means an empty stack.
   4214   1.1  mbalmer 
   4215   1.1  mbalmer 
   4216   1.1  mbalmer 
   4217   1.1  mbalmer 
   4218   1.1  mbalmer 
   4219   1.9   nikita <hr><h3><a name="lua_getiuservalue"><code>lua_getiuservalue</code></a></h3><p>
   4220   1.2    lneto <span class="apii">[-0, +1, &ndash;]</span>
   4221   1.9   nikita <pre>int lua_getiuservalue (lua_State *L, int index, int n);</pre>
   4222   1.2    lneto 
   4223   1.2    lneto <p>
   4224   1.9   nikita Pushes onto the stack the <code>n</code>-th user value associated with the
   4225   1.9   nikita full userdata at the given index and
   4226   1.9   nikita returns the type of the pushed value.
   4227   1.2    lneto 
   4228   1.2    lneto 
   4229   1.2    lneto <p>
   4230   1.9   nikita If the userdata does not have that value,
   4231   1.9   nikita pushes <b>nil</b> and returns <a href="#pdf-LUA_TNONE"><code>LUA_TNONE</code></a>.
   4232   1.2    lneto 
   4233   1.2    lneto 
   4234   1.2    lneto 
   4235   1.2    lneto 
   4236   1.2    lneto 
   4237   1.1  mbalmer <hr><h3><a name="lua_insert"><code>lua_insert</code></a></h3><p>
   4238   1.2    lneto <span class="apii">[-1, +1, &ndash;]</span>
   4239   1.1  mbalmer <pre>void lua_insert (lua_State *L, int index);</pre>
   4240   1.1  mbalmer 
   4241   1.1  mbalmer <p>
   4242   1.1  mbalmer Moves the top element into the given valid index,
   4243   1.1  mbalmer shifting up the elements above this index to open space.
   4244   1.2    lneto This function cannot be called with a pseudo-index,
   4245   1.1  mbalmer because a pseudo-index is not an actual stack position.
   4246   1.1  mbalmer 
   4247   1.1  mbalmer 
   4248   1.1  mbalmer 
   4249   1.1  mbalmer 
   4250   1.1  mbalmer 
   4251   1.1  mbalmer <hr><h3><a name="lua_Integer"><code>lua_Integer</code></a></h3>
   4252   1.2    lneto <pre>typedef ... lua_Integer;</pre>
   4253   1.1  mbalmer 
   4254   1.1  mbalmer <p>
   4255   1.2    lneto The type of integers in Lua.
   4256   1.1  mbalmer 
   4257   1.1  mbalmer 
   4258   1.1  mbalmer <p>
   4259   1.3    lneto By default this type is <code>long long</code>,
   4260   1.2    lneto (usually a 64-bit two-complement integer),
   4261   1.3    lneto but that can be changed to <code>long</code> or <code>int</code>
   4262   1.2    lneto (usually a 32-bit two-complement integer).
   4263   1.4  mbalmer (See <code>LUA_INT_TYPE</code> in <code>luaconf.h</code>.)
   4264   1.2    lneto 
   4265   1.2    lneto 
   4266   1.2    lneto <p>
   4267   1.2    lneto Lua also defines the constants
   4268   1.2    lneto <a name="pdf-LUA_MININTEGER"><code>LUA_MININTEGER</code></a> and <a name="pdf-LUA_MAXINTEGER"><code>LUA_MAXINTEGER</code></a>,
   4269   1.2    lneto with the minimum and the maximum values that fit in this type.
   4270   1.1  mbalmer 
   4271   1.1  mbalmer 
   4272   1.1  mbalmer 
   4273   1.1  mbalmer 
   4274   1.1  mbalmer 
   4275   1.1  mbalmer <hr><h3><a name="lua_isboolean"><code>lua_isboolean</code></a></h3><p>
   4276   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   4277   1.1  mbalmer <pre>int lua_isboolean (lua_State *L, int index);</pre>
   4278   1.1  mbalmer 
   4279   1.1  mbalmer <p>
   4280   1.2    lneto Returns 1 if the value at the given index is a boolean,
   4281   1.1  mbalmer and 0&nbsp;otherwise.
   4282   1.1  mbalmer 
   4283   1.1  mbalmer 
   4284   1.1  mbalmer 
   4285   1.1  mbalmer 
   4286   1.1  mbalmer 
   4287   1.1  mbalmer <hr><h3><a name="lua_iscfunction"><code>lua_iscfunction</code></a></h3><p>
   4288   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   4289   1.1  mbalmer <pre>int lua_iscfunction (lua_State *L, int index);</pre>
   4290   1.1  mbalmer 
   4291   1.1  mbalmer <p>
   4292   1.2    lneto Returns 1 if the value at the given index is a C&nbsp;function,
   4293   1.1  mbalmer and 0&nbsp;otherwise.
   4294   1.1  mbalmer 
   4295   1.1  mbalmer 
   4296   1.1  mbalmer 
   4297   1.1  mbalmer 
   4298   1.1  mbalmer 
   4299   1.1  mbalmer <hr><h3><a name="lua_isfunction"><code>lua_isfunction</code></a></h3><p>
   4300   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   4301   1.1  mbalmer <pre>int lua_isfunction (lua_State *L, int index);</pre>
   4302   1.1  mbalmer 
   4303   1.1  mbalmer <p>
   4304   1.2    lneto Returns 1 if the value at the given index is a function
   4305   1.1  mbalmer (either C or Lua), and 0&nbsp;otherwise.
   4306   1.1  mbalmer 
   4307   1.1  mbalmer 
   4308   1.1  mbalmer 
   4309   1.1  mbalmer 
   4310   1.1  mbalmer 
   4311   1.2    lneto <hr><h3><a name="lua_isinteger"><code>lua_isinteger</code></a></h3><p>
   4312   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   4313   1.2    lneto <pre>int lua_isinteger (lua_State *L, int index);</pre>
   4314   1.2    lneto 
   4315   1.2    lneto <p>
   4316   1.2    lneto Returns 1 if the value at the given index is an integer
   4317   1.2    lneto (that is, the value is a number and is represented as an integer),
   4318   1.2    lneto and 0&nbsp;otherwise.
   4319   1.2    lneto 
   4320   1.2    lneto 
   4321   1.2    lneto 
   4322   1.2    lneto 
   4323   1.2    lneto 
   4324   1.1  mbalmer <hr><h3><a name="lua_islightuserdata"><code>lua_islightuserdata</code></a></h3><p>
   4325   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   4326   1.1  mbalmer <pre>int lua_islightuserdata (lua_State *L, int index);</pre>
   4327   1.1  mbalmer 
   4328   1.1  mbalmer <p>
   4329   1.2    lneto Returns 1 if the value at the given index is a light userdata,
   4330   1.1  mbalmer and 0&nbsp;otherwise.
   4331   1.1  mbalmer 
   4332   1.1  mbalmer 
   4333   1.1  mbalmer 
   4334   1.1  mbalmer 
   4335   1.1  mbalmer 
   4336   1.1  mbalmer <hr><h3><a name="lua_isnil"><code>lua_isnil</code></a></h3><p>
   4337   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   4338   1.1  mbalmer <pre>int lua_isnil (lua_State *L, int index);</pre>
   4339   1.1  mbalmer 
   4340   1.1  mbalmer <p>
   4341   1.2    lneto Returns 1 if the value at the given index is <b>nil</b>,
   4342   1.1  mbalmer and 0&nbsp;otherwise.
   4343   1.1  mbalmer 
   4344   1.1  mbalmer 
   4345   1.1  mbalmer 
   4346   1.1  mbalmer 
   4347   1.1  mbalmer 
   4348   1.1  mbalmer <hr><h3><a name="lua_isnone"><code>lua_isnone</code></a></h3><p>
   4349   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   4350   1.1  mbalmer <pre>int lua_isnone (lua_State *L, int index);</pre>
   4351   1.1  mbalmer 
   4352   1.1  mbalmer <p>
   4353   1.2    lneto Returns 1 if the given index is not valid,
   4354   1.1  mbalmer and 0&nbsp;otherwise.
   4355   1.1  mbalmer 
   4356   1.1  mbalmer 
   4357   1.1  mbalmer 
   4358   1.1  mbalmer 
   4359   1.1  mbalmer 
   4360   1.1  mbalmer <hr><h3><a name="lua_isnoneornil"><code>lua_isnoneornil</code></a></h3><p>
   4361   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   4362   1.1  mbalmer <pre>int lua_isnoneornil (lua_State *L, int index);</pre>
   4363   1.1  mbalmer 
   4364   1.1  mbalmer <p>
   4365   1.2    lneto Returns 1 if the given index is not valid
   4366   1.1  mbalmer or if the value at this index is <b>nil</b>,
   4367   1.1  mbalmer and 0&nbsp;otherwise.
   4368   1.1  mbalmer 
   4369   1.1  mbalmer 
   4370   1.1  mbalmer 
   4371   1.1  mbalmer 
   4372   1.1  mbalmer 
   4373   1.1  mbalmer <hr><h3><a name="lua_isnumber"><code>lua_isnumber</code></a></h3><p>
   4374   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   4375   1.1  mbalmer <pre>int lua_isnumber (lua_State *L, int index);</pre>
   4376   1.1  mbalmer 
   4377   1.1  mbalmer <p>
   4378   1.2    lneto Returns 1 if the value at the given index is a number
   4379   1.1  mbalmer or a string convertible to a number,
   4380   1.1  mbalmer and 0&nbsp;otherwise.
   4381   1.1  mbalmer 
   4382   1.1  mbalmer 
   4383   1.1  mbalmer 
   4384   1.1  mbalmer 
   4385   1.1  mbalmer 
   4386   1.1  mbalmer <hr><h3><a name="lua_isstring"><code>lua_isstring</code></a></h3><p>
   4387   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   4388   1.1  mbalmer <pre>int lua_isstring (lua_State *L, int index);</pre>
   4389   1.1  mbalmer 
   4390   1.1  mbalmer <p>
   4391   1.2    lneto Returns 1 if the value at the given index is a string
   4392   1.1  mbalmer or a number (which is always convertible to a string),
   4393   1.1  mbalmer and 0&nbsp;otherwise.
   4394   1.1  mbalmer 
   4395   1.1  mbalmer 
   4396   1.1  mbalmer 
   4397   1.1  mbalmer 
   4398   1.1  mbalmer 
   4399   1.1  mbalmer <hr><h3><a name="lua_istable"><code>lua_istable</code></a></h3><p>
   4400   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   4401   1.1  mbalmer <pre>int lua_istable (lua_State *L, int index);</pre>
   4402   1.1  mbalmer 
   4403   1.1  mbalmer <p>
   4404   1.2    lneto Returns 1 if the value at the given index is a table,
   4405   1.1  mbalmer and 0&nbsp;otherwise.
   4406   1.1  mbalmer 
   4407   1.1  mbalmer 
   4408   1.1  mbalmer 
   4409   1.1  mbalmer 
   4410   1.1  mbalmer 
   4411   1.1  mbalmer <hr><h3><a name="lua_isthread"><code>lua_isthread</code></a></h3><p>
   4412   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   4413   1.1  mbalmer <pre>int lua_isthread (lua_State *L, int index);</pre>
   4414   1.1  mbalmer 
   4415   1.1  mbalmer <p>
   4416   1.2    lneto Returns 1 if the value at the given index is a thread,
   4417   1.1  mbalmer and 0&nbsp;otherwise.
   4418   1.1  mbalmer 
   4419   1.1  mbalmer 
   4420   1.1  mbalmer 
   4421   1.1  mbalmer 
   4422   1.1  mbalmer 
   4423   1.1  mbalmer <hr><h3><a name="lua_isuserdata"><code>lua_isuserdata</code></a></h3><p>
   4424   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   4425   1.1  mbalmer <pre>int lua_isuserdata (lua_State *L, int index);</pre>
   4426   1.1  mbalmer 
   4427   1.1  mbalmer <p>
   4428   1.2    lneto Returns 1 if the value at the given index is a userdata
   4429   1.1  mbalmer (either full or light), and 0&nbsp;otherwise.
   4430   1.1  mbalmer 
   4431   1.1  mbalmer 
   4432   1.1  mbalmer 
   4433   1.1  mbalmer 
   4434   1.1  mbalmer 
   4435   1.2    lneto <hr><h3><a name="lua_isyieldable"><code>lua_isyieldable</code></a></h3><p>
   4436   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   4437   1.2    lneto <pre>int lua_isyieldable (lua_State *L);</pre>
   4438   1.2    lneto 
   4439   1.2    lneto <p>
   4440   1.2    lneto Returns 1 if the given coroutine can yield,
   4441   1.2    lneto and 0&nbsp;otherwise.
   4442   1.2    lneto 
   4443   1.2    lneto 
   4444   1.2    lneto 
   4445   1.2    lneto 
   4446   1.2    lneto 
   4447   1.3    lneto <hr><h3><a name="lua_KContext"><code>lua_KContext</code></a></h3>
   4448   1.3    lneto <pre>typedef ... lua_KContext;</pre>
   4449   1.3    lneto 
   4450   1.3    lneto <p>
   4451   1.3    lneto The type for continuation-function contexts.
   4452   1.4  mbalmer It must be a numeric type.
   4453   1.3    lneto This type is defined as <code>intptr_t</code>
   4454   1.3    lneto when <code>intptr_t</code> is available,
   4455   1.3    lneto so that it can store pointers too.
   4456   1.3    lneto Otherwise, it is defined as <code>ptrdiff_t</code>.
   4457   1.3    lneto 
   4458   1.3    lneto 
   4459   1.3    lneto 
   4460   1.3    lneto 
   4461   1.3    lneto 
   4462   1.2    lneto <hr><h3><a name="lua_KFunction"><code>lua_KFunction</code></a></h3>
   4463   1.3    lneto <pre>typedef int (*lua_KFunction) (lua_State *L, int status, lua_KContext ctx);</pre>
   4464   1.2    lneto 
   4465   1.2    lneto <p>
   4466   1.9   nikita Type for continuation functions (see <a href="#4.5">&sect;4.5</a>).
   4467   1.2    lneto 
   4468   1.2    lneto 
   4469   1.2    lneto 
   4470   1.2    lneto 
   4471   1.2    lneto 
   4472   1.2    lneto <hr><h3><a name="lua_len"><code>lua_len</code></a></h3><p>
   4473   1.2    lneto <span class="apii">[-0, +1, <em>e</em>]</span>
   4474   1.2    lneto <pre>void lua_len (lua_State *L, int index);</pre>
   4475   1.1  mbalmer 
   4476   1.1  mbalmer <p>
   4477   1.3    lneto Returns the length of the value at the given index.
   4478   1.3    lneto It is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">&sect;3.4.7</a>) and
   4479   1.3    lneto may trigger a metamethod for the "length" event (see <a href="#2.4">&sect;2.4</a>).
   4480   1.2    lneto The result is pushed on the stack.
   4481   1.1  mbalmer 
   4482   1.1  mbalmer 
   4483   1.1  mbalmer 
   4484   1.1  mbalmer 
   4485   1.1  mbalmer 
   4486   1.1  mbalmer <hr><h3><a name="lua_load"><code>lua_load</code></a></h3><p>
   4487   1.2    lneto <span class="apii">[-0, +1, &ndash;]</span>
   4488   1.1  mbalmer <pre>int lua_load (lua_State *L,
   4489   1.1  mbalmer               lua_Reader reader,
   4490   1.1  mbalmer               void *data,
   4491   1.3    lneto               const char *chunkname,
   4492   1.2    lneto               const char *mode);</pre>
   4493   1.1  mbalmer 
   4494   1.1  mbalmer <p>
   4495   1.3    lneto Loads a Lua chunk without running it.
   4496   1.1  mbalmer If there are no errors,
   4497   1.2    lneto <code>lua_load</code> pushes the compiled chunk as a Lua
   4498   1.1  mbalmer function on top of the stack.
   4499   1.1  mbalmer Otherwise, it pushes an error message.
   4500   1.2    lneto 
   4501   1.2    lneto 
   4502   1.2    lneto <p>
   4503   1.2    lneto The <code>lua_load</code> function uses a user-supplied <code>reader</code> function
   4504   1.2    lneto to read the chunk (see <a href="#lua_Reader"><code>lua_Reader</code></a>).
   4505   1.2    lneto The <code>data</code> argument is an opaque value passed to the reader function.
   4506   1.2    lneto 
   4507   1.2    lneto 
   4508   1.2    lneto <p>
   4509   1.3    lneto The <code>chunkname</code> argument gives a name to the chunk,
   4510   1.9   nikita which is used for error messages and in debug information (see <a href="#4.7">&sect;4.7</a>).
   4511   1.1  mbalmer 
   4512   1.1  mbalmer 
   4513   1.1  mbalmer <p>
   4514   1.2    lneto <code>lua_load</code> automatically detects whether the chunk is text or binary
   4515   1.1  mbalmer and loads it accordingly (see program <code>luac</code>).
   4516   1.2    lneto The string <code>mode</code> works as in function <a href="#pdf-load"><code>load</code></a>,
   4517   1.2    lneto with the addition that
   4518   1.2    lneto a <code>NULL</code> value is equivalent to the string "<code>bt</code>".
   4519   1.1  mbalmer 
   4520   1.1  mbalmer 
   4521   1.1  mbalmer <p>
   4522   1.2    lneto <code>lua_load</code> uses the stack internally,
   4523   1.2    lneto so the reader function must always leave the stack
   4524   1.2    lneto unmodified when returning.
   4525   1.1  mbalmer 
   4526   1.1  mbalmer 
   4527   1.1  mbalmer <p>
   4528   1.9   nikita <code>lua_load</code> can return
   4529   1.9   nikita <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>, <a href="#pdf-LUA_ERRSYNTAX"><code>LUA_ERRSYNTAX</code></a>, or <a href="#pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>.
   4530   1.9   nikita The function may also return other values corresponding to
   4531   1.9   nikita errors raised by the read function (see <a href="#4.4.1">&sect;4.4.1</a>).
   4532   1.9   nikita 
   4533   1.9   nikita 
   4534   1.9   nikita <p>
   4535   1.3    lneto If the resulting function has upvalues,
   4536   1.3    lneto its first upvalue is set to the value of the global environment
   4537   1.9   nikita stored at index <code>LUA_RIDX_GLOBALS</code> in the registry (see <a href="#4.3">&sect;4.3</a>).
   4538   1.2    lneto When loading main chunks,
   4539   1.2    lneto this upvalue will be the <code>_ENV</code> variable (see <a href="#2.2">&sect;2.2</a>).
   4540   1.3    lneto Other upvalues are initialized with <b>nil</b>.
   4541   1.1  mbalmer 
   4542   1.1  mbalmer 
   4543   1.1  mbalmer 
   4544   1.1  mbalmer 
   4545   1.1  mbalmer 
   4546   1.1  mbalmer <hr><h3><a name="lua_newstate"><code>lua_newstate</code></a></h3><p>
   4547   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   4548   1.1  mbalmer <pre>lua_State *lua_newstate (lua_Alloc f, void *ud);</pre>
   4549   1.1  mbalmer 
   4550   1.1  mbalmer <p>
   4551   1.9   nikita Creates a new independent state and returns its main thread.
   4552   1.9   nikita Returns <code>NULL</code> if it cannot create the state
   4553   1.1  mbalmer (due to lack of memory).
   4554   1.1  mbalmer The argument <code>f</code> is the allocator function;
   4555   1.9   nikita Lua will do all memory allocation for this state
   4556   1.7  mbalmer through this function (see <a href="#lua_Alloc"><code>lua_Alloc</code></a>).
   4557   1.1  mbalmer The second argument, <code>ud</code>, is an opaque pointer that Lua
   4558   1.2    lneto passes to the allocator in every call.
   4559   1.1  mbalmer 
   4560   1.1  mbalmer 
   4561   1.1  mbalmer 
   4562   1.1  mbalmer 
   4563   1.1  mbalmer 
   4564   1.1  mbalmer <hr><h3><a name="lua_newtable"><code>lua_newtable</code></a></h3><p>
   4565   1.5    lneto <span class="apii">[-0, +1, <em>m</em>]</span>
   4566   1.1  mbalmer <pre>void lua_newtable (lua_State *L);</pre>
   4567   1.1  mbalmer 
   4568   1.1  mbalmer <p>
   4569   1.1  mbalmer Creates a new empty table and pushes it onto the stack.
   4570   1.1  mbalmer It is equivalent to <code>lua_createtable(L, 0, 0)</code>.
   4571   1.1  mbalmer 
   4572   1.1  mbalmer 
   4573   1.1  mbalmer 
   4574   1.1  mbalmer 
   4575   1.1  mbalmer 
   4576   1.1  mbalmer <hr><h3><a name="lua_newthread"><code>lua_newthread</code></a></h3><p>
   4577   1.5    lneto <span class="apii">[-0, +1, <em>m</em>]</span>
   4578   1.1  mbalmer <pre>lua_State *lua_newthread (lua_State *L);</pre>
   4579   1.1  mbalmer 
   4580   1.1  mbalmer <p>
   4581   1.1  mbalmer Creates a new thread, pushes it on the stack,
   4582   1.1  mbalmer and returns a pointer to a <a href="#lua_State"><code>lua_State</code></a> that represents this new thread.
   4583   1.2    lneto The new thread returned by this function shares with the original thread
   4584   1.2    lneto its global environment,
   4585   1.1  mbalmer but has an independent execution stack.
   4586   1.1  mbalmer 
   4587   1.1  mbalmer 
   4588   1.1  mbalmer <p>
   4589   1.1  mbalmer Threads are subject to garbage collection,
   4590   1.1  mbalmer like any Lua object.
   4591   1.1  mbalmer 
   4592   1.1  mbalmer 
   4593   1.1  mbalmer 
   4594   1.1  mbalmer 
   4595   1.1  mbalmer 
   4596   1.9   nikita <hr><h3><a name="lua_newuserdatauv"><code>lua_newuserdatauv</code></a></h3><p>
   4597   1.5    lneto <span class="apii">[-0, +1, <em>m</em>]</span>
   4598   1.9   nikita <pre>void *lua_newuserdatauv (lua_State *L, size_t size, int nuvalue);</pre>
   4599   1.9   nikita 
   4600   1.9   nikita <p>
   4601   1.9   nikita This function creates and pushes on the stack a new full userdata,
   4602   1.9   nikita with <code>nuvalue</code> associated Lua values, called <code>user values</code>,
   4603   1.9   nikita plus an associated block of raw memory with <code>size</code> bytes.
   4604   1.9   nikita (The user values can be set and read with the functions
   4605   1.9   nikita <a href="#lua_setiuservalue"><code>lua_setiuservalue</code></a> and <a href="#lua_getiuservalue"><code>lua_getiuservalue</code></a>.)
   4606   1.9   nikita 
   4607   1.1  mbalmer 
   4608   1.1  mbalmer <p>
   4609   1.9   nikita The function returns the address of the block of memory.
   4610   1.9   nikita Lua ensures that this address is valid as long as
   4611   1.9   nikita the corresponding userdata is alive (see <a href="#2.5">&sect;2.5</a>).
   4612   1.9   nikita Moreover, if the userdata is marked for finalization (see <a href="#2.5.3">&sect;2.5.3</a>),
   4613   1.9   nikita its address is valid at least until the call to its finalizer.
   4614   1.1  mbalmer 
   4615   1.1  mbalmer 
   4616   1.1  mbalmer 
   4617   1.1  mbalmer 
   4618   1.1  mbalmer 
   4619   1.1  mbalmer <hr><h3><a name="lua_next"><code>lua_next</code></a></h3><p>
   4620   1.9   nikita <span class="apii">[-1, +(2|0), <em>v</em>]</span>
   4621   1.1  mbalmer <pre>int lua_next (lua_State *L, int index);</pre>
   4622   1.1  mbalmer 
   4623   1.1  mbalmer <p>
   4624   1.1  mbalmer Pops a key from the stack,
   4625   1.9   nikita and pushes a key&ndash;value pair from the table at the given index,
   4626   1.9   nikita the "next" pair after the given key.
   4627   1.1  mbalmer If there are no more elements in the table,
   4628  1.10   nikita then <a href="#lua_next"><code>lua_next</code></a> returns&nbsp;0 and pushes nothing.
   4629   1.1  mbalmer 
   4630   1.1  mbalmer 
   4631   1.1  mbalmer <p>
   4632   1.9   nikita A typical table traversal looks like this:
   4633   1.1  mbalmer 
   4634   1.1  mbalmer <pre>
   4635   1.1  mbalmer      /* table is in the stack at index 't' */
   4636   1.1  mbalmer      lua_pushnil(L);  /* first key */
   4637   1.1  mbalmer      while (lua_next(L, t) != 0) {
   4638   1.1  mbalmer        /* uses 'key' (at index -2) and 'value' (at index -1) */
   4639   1.1  mbalmer        printf("%s - %s\n",
   4640   1.1  mbalmer               lua_typename(L, lua_type(L, -2)),
   4641   1.1  mbalmer               lua_typename(L, lua_type(L, -1)));
   4642   1.1  mbalmer        /* removes 'value'; keeps 'key' for next iteration */
   4643   1.1  mbalmer        lua_pop(L, 1);
   4644   1.1  mbalmer      }
   4645   1.1  mbalmer </pre>
   4646   1.1  mbalmer 
   4647   1.1  mbalmer <p>
   4648   1.1  mbalmer While traversing a table,
   4649   1.9   nikita avoid calling <a href="#lua_tolstring"><code>lua_tolstring</code></a> directly on a key,
   4650   1.1  mbalmer unless you know that the key is actually a string.
   4651   1.2    lneto Recall that <a href="#lua_tolstring"><code>lua_tolstring</code></a> may change
   4652   1.1  mbalmer the value at the given index;
   4653   1.1  mbalmer this confuses the next call to <a href="#lua_next"><code>lua_next</code></a>.
   4654   1.1  mbalmer 
   4655   1.1  mbalmer 
   4656   1.2    lneto <p>
   4657   1.9   nikita This function may raise an error if the given key
   4658   1.9   nikita is neither <b>nil</b> nor present in the table.
   4659   1.2    lneto See function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying
   4660   1.2    lneto the table during its traversal.
   4661   1.2    lneto 
   4662   1.2    lneto 
   4663   1.1  mbalmer 
   4664   1.1  mbalmer 
   4665   1.1  mbalmer 
   4666   1.1  mbalmer <hr><h3><a name="lua_Number"><code>lua_Number</code></a></h3>
   4667   1.4  mbalmer <pre>typedef ... lua_Number;</pre>
   4668   1.1  mbalmer 
   4669   1.1  mbalmer <p>
   4670   1.2    lneto The type of floats in Lua.
   4671   1.1  mbalmer 
   4672   1.1  mbalmer 
   4673   1.1  mbalmer <p>
   4674   1.2    lneto By default this type is double,
   4675   1.4  mbalmer but that can be changed to a single float or a long double.
   4676   1.4  mbalmer (See <code>LUA_FLOAT_TYPE</code> in <code>luaconf.h</code>.)
   4677   1.2    lneto 
   4678   1.2    lneto 
   4679   1.1  mbalmer 
   4680   1.1  mbalmer 
   4681   1.1  mbalmer 
   4682   1.3    lneto <hr><h3><a name="lua_numbertointeger"><code>lua_numbertointeger</code></a></h3>
   4683   1.3    lneto <pre>int lua_numbertointeger (lua_Number n, lua_Integer *p);</pre>
   4684   1.1  mbalmer 
   4685   1.2    lneto <p>
   4686   1.9   nikita Tries to convert a Lua float to a Lua integer;
   4687   1.9   nikita the float <code>n</code> must have an integral value.
   4688   1.2    lneto If that value is within the range of Lua integers,
   4689   1.2    lneto it is converted to an integer and assigned to <code>*p</code>.
   4690   1.2    lneto The macro results in a boolean indicating whether the
   4691   1.2    lneto conversion was successful.
   4692   1.2    lneto (Note that this range test can be tricky to do
   4693   1.9   nikita correctly without this macro, due to rounding.)
   4694   1.1  mbalmer 
   4695   1.1  mbalmer 
   4696   1.1  mbalmer <p>
   4697   1.2    lneto This macro may evaluate its arguments more than once.
   4698   1.1  mbalmer 
   4699   1.1  mbalmer 
   4700   1.1  mbalmer 
   4701   1.1  mbalmer 
   4702   1.1  mbalmer 
   4703   1.1  mbalmer <hr><h3><a name="lua_pcall"><code>lua_pcall</code></a></h3><p>
   4704   1.2    lneto <span class="apii">[-(nargs + 1), +(nresults|1), &ndash;]</span>
   4705   1.2    lneto <pre>int lua_pcall (lua_State *L, int nargs, int nresults, int msgh);</pre>
   4706   1.1  mbalmer 
   4707   1.1  mbalmer <p>
   4708   1.9   nikita Calls a function (or a callable object) in protected mode.
   4709   1.1  mbalmer 
   4710   1.1  mbalmer 
   4711   1.1  mbalmer <p>
   4712   1.1  mbalmer Both <code>nargs</code> and <code>nresults</code> have the same meaning as
   4713   1.1  mbalmer in <a href="#lua_call"><code>lua_call</code></a>.
   4714   1.1  mbalmer If there are no errors during the call,
   4715   1.1  mbalmer <a href="#lua_pcall"><code>lua_pcall</code></a> behaves exactly like <a href="#lua_call"><code>lua_call</code></a>.
   4716   1.1  mbalmer However, if there is any error,
   4717   1.1  mbalmer <a href="#lua_pcall"><code>lua_pcall</code></a> catches it,
   4718   1.6  salazar pushes a single value on the stack (the error object),
   4719   1.1  mbalmer and returns an error code.
   4720   1.1  mbalmer Like <a href="#lua_call"><code>lua_call</code></a>,
   4721   1.1  mbalmer <a href="#lua_pcall"><code>lua_pcall</code></a> always removes the function
   4722   1.1  mbalmer and its arguments from the stack.
   4723   1.1  mbalmer 
   4724   1.1  mbalmer 
   4725   1.1  mbalmer <p>
   4726   1.2    lneto If <code>msgh</code> is 0,
   4727   1.6  salazar then the error object returned on the stack
   4728   1.6  salazar is exactly the original error object.
   4729   1.2    lneto Otherwise, <code>msgh</code> is the stack index of a
   4730   1.2    lneto <em>message handler</em>.
   4731   1.4  mbalmer (This index cannot be a pseudo-index.)
   4732   1.1  mbalmer In case of runtime errors,
   4733   1.9   nikita this handler will be called with the error object
   4734   1.6  salazar and its return value will be the object
   4735   1.2    lneto returned on the stack by <a href="#lua_pcall"><code>lua_pcall</code></a>.
   4736   1.1  mbalmer 
   4737   1.1  mbalmer 
   4738   1.1  mbalmer <p>
   4739   1.2    lneto Typically, the message handler is used to add more debug
   4740   1.6  salazar information to the error object, such as a stack traceback.
   4741   1.1  mbalmer Such information cannot be gathered after the return of <a href="#lua_pcall"><code>lua_pcall</code></a>,
   4742   1.1  mbalmer since by then the stack has unwound.
   4743   1.1  mbalmer 
   4744   1.1  mbalmer 
   4745   1.1  mbalmer <p>
   4746   1.9   nikita The <a href="#lua_pcall"><code>lua_pcall</code></a> function returns one of the following status codes:
   4747   1.9   nikita <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>, <a href="#pdf-LUA_ERRRUN"><code>LUA_ERRRUN</code></a>, <a href="#pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>, or <a href="#pdf-LUA_ERRERR"><code>LUA_ERRERR</code></a>.
   4748   1.2    lneto 
   4749   1.1  mbalmer 
   4750   1.1  mbalmer 
   4751   1.1  mbalmer 
   4752   1.1  mbalmer 
   4753   1.2    lneto <hr><h3><a name="lua_pcallk"><code>lua_pcallk</code></a></h3><p>
   4754   1.2    lneto <span class="apii">[-(nargs + 1), +(nresults|1), &ndash;]</span>
   4755   1.2    lneto <pre>int lua_pcallk (lua_State *L,
   4756   1.2    lneto                 int nargs,
   4757   1.2    lneto                 int nresults,
   4758   1.3    lneto                 int msgh,
   4759   1.3    lneto                 lua_KContext ctx,
   4760   1.2    lneto                 lua_KFunction k);</pre>
   4761   1.2    lneto 
   4762   1.2    lneto <p>
   4763   1.2    lneto This function behaves exactly like <a href="#lua_pcall"><code>lua_pcall</code></a>,
   4764   1.9   nikita except that it allows the called function to yield (see <a href="#4.5">&sect;4.5</a>).
   4765   1.2    lneto 
   4766   1.2    lneto 
   4767   1.2    lneto 
   4768   1.2    lneto 
   4769   1.2    lneto 
   4770   1.1  mbalmer <hr><h3><a name="lua_pop"><code>lua_pop</code></a></h3><p>
   4771   1.9   nikita <span class="apii">[-n, +0, <em>e</em>]</span>
   4772   1.1  mbalmer <pre>void lua_pop (lua_State *L, int n);</pre>
   4773   1.1  mbalmer 
   4774   1.1  mbalmer <p>
   4775   1.1  mbalmer Pops <code>n</code> elements from the stack.
   4776   1.9   nikita It is implemented as a macro over <a href="#lua_settop"><code>lua_settop</code></a>.
   4777   1.1  mbalmer 
   4778   1.1  mbalmer 
   4779   1.1  mbalmer 
   4780   1.1  mbalmer 
   4781   1.1  mbalmer 
   4782   1.1  mbalmer <hr><h3><a name="lua_pushboolean"><code>lua_pushboolean</code></a></h3><p>
   4783   1.2    lneto <span class="apii">[-0, +1, &ndash;]</span>
   4784   1.1  mbalmer <pre>void lua_pushboolean (lua_State *L, int b);</pre>
   4785   1.1  mbalmer 
   4786   1.1  mbalmer <p>
   4787   1.1  mbalmer Pushes a boolean value with value <code>b</code> onto the stack.
   4788   1.1  mbalmer 
   4789   1.1  mbalmer 
   4790   1.1  mbalmer 
   4791   1.1  mbalmer 
   4792   1.1  mbalmer 
   4793   1.1  mbalmer <hr><h3><a name="lua_pushcclosure"><code>lua_pushcclosure</code></a></h3><p>
   4794   1.5    lneto <span class="apii">[-n, +1, <em>m</em>]</span>
   4795   1.1  mbalmer <pre>void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);</pre>
   4796   1.1  mbalmer 
   4797   1.1  mbalmer <p>
   4798   1.1  mbalmer Pushes a new C&nbsp;closure onto the stack.
   4799   1.9   nikita This function receives a pointer to a C&nbsp;function
   4800   1.9   nikita and pushes onto the stack a Lua value of type <code>function</code> that,
   4801   1.9   nikita when called, invokes the corresponding C&nbsp;function.
   4802   1.9   nikita The parameter <code>n</code> tells how many upvalues this function will have
   4803   1.9   nikita (see <a href="#4.2">&sect;4.2</a>).
   4804   1.9   nikita 
   4805   1.9   nikita 
   4806   1.9   nikita <p>
   4807   1.9   nikita Any function to be callable by Lua must
   4808   1.9   nikita follow the correct protocol to receive its parameters
   4809   1.9   nikita and return its results (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>).
   4810   1.1  mbalmer 
   4811   1.1  mbalmer 
   4812   1.1  mbalmer <p>
   4813   1.1  mbalmer When a C&nbsp;function is created,
   4814   1.1  mbalmer it is possible to associate some values with it,
   4815   1.9   nikita the so called upvalues;
   4816   1.9   nikita these upvalues are then accessible to the function whenever it is called.
   4817   1.9   nikita This association is called a C&nbsp;closure (see <a href="#4.2">&sect;4.2</a>).
   4818   1.9   nikita To create a C&nbsp;closure,
   4819   1.9   nikita first the initial values for its upvalues must be pushed onto the stack.
   4820   1.9   nikita (When there are multiple upvalues, the first value is pushed first.)
   4821   1.1  mbalmer Then <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>
   4822   1.1  mbalmer is called to create and push the C&nbsp;function onto the stack,
   4823   1.2    lneto with the argument <code>n</code> telling how many values will be
   4824   1.1  mbalmer associated with the function.
   4825   1.1  mbalmer <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> also pops these values from the stack.
   4826   1.1  mbalmer 
   4827   1.1  mbalmer 
   4828   1.1  mbalmer <p>
   4829   1.1  mbalmer The maximum value for <code>n</code> is 255.
   4830   1.1  mbalmer 
   4831   1.1  mbalmer 
   4832   1.2    lneto <p>
   4833   1.2    lneto When <code>n</code> is zero,
   4834   1.7  mbalmer this function creates a <em>light C&nbsp;function</em>,
   4835   1.2    lneto which is just a pointer to the C&nbsp;function.
   4836   1.2    lneto In that case, it never raises a memory error.
   4837   1.2    lneto 
   4838   1.2    lneto 
   4839   1.1  mbalmer 
   4840   1.1  mbalmer 
   4841   1.1  mbalmer 
   4842   1.1  mbalmer <hr><h3><a name="lua_pushcfunction"><code>lua_pushcfunction</code></a></h3><p>
   4843   1.2    lneto <span class="apii">[-0, +1, &ndash;]</span>
   4844   1.1  mbalmer <pre>void lua_pushcfunction (lua_State *L, lua_CFunction f);</pre>
   4845   1.1  mbalmer 
   4846   1.1  mbalmer <p>
   4847   1.1  mbalmer Pushes a C&nbsp;function onto the stack.
   4848   1.9   nikita This function is equivalent to <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> with no upvalues.
   4849   1.1  mbalmer 
   4850   1.1  mbalmer 
   4851   1.1  mbalmer 
   4852   1.1  mbalmer 
   4853   1.1  mbalmer 
   4854   1.1  mbalmer <hr><h3><a name="lua_pushfstring"><code>lua_pushfstring</code></a></h3><p>
   4855   1.9   nikita <span class="apii">[-0, +1, <em>v</em>]</span>
   4856   1.1  mbalmer <pre>const char *lua_pushfstring (lua_State *L, const char *fmt, ...);</pre>
   4857   1.1  mbalmer 
   4858   1.1  mbalmer <p>
   4859   1.1  mbalmer Pushes onto the stack a formatted string
   4860   1.9   nikita and returns a pointer to this string (see <a href="#4.1.3">&sect;4.1.3</a>).
   4861   1.3    lneto It is similar to the ISO&nbsp;C function <code>sprintf</code>,
   4862   1.9   nikita but has two important differences.
   4863   1.9   nikita First,
   4864   1.9   nikita you do not have to allocate space for the result;
   4865   1.1  mbalmer the result is a Lua string and Lua takes care of memory allocation
   4866   1.1  mbalmer (and deallocation, through garbage collection).
   4867   1.9   nikita Second,
   4868   1.9   nikita the conversion specifiers are quite restricted.
   4869   1.1  mbalmer There are no flags, widths, or precisions.
   4870   1.1  mbalmer The conversion specifiers can only be
   4871   1.2    lneto '<code>%%</code>' (inserts the character '<code>%</code>'),
   4872   1.1  mbalmer '<code>%s</code>' (inserts a zero-terminated string, with no size restrictions),
   4873   1.1  mbalmer '<code>%f</code>' (inserts a <a href="#lua_Number"><code>lua_Number</code></a>),
   4874   1.4  mbalmer '<code>%I</code>' (inserts a <a href="#lua_Integer"><code>lua_Integer</code></a>),
   4875   1.9   nikita '<code>%p</code>' (inserts a pointer),
   4876   1.2    lneto '<code>%d</code>' (inserts an <code>int</code>),
   4877   1.2    lneto '<code>%c</code>' (inserts an <code>int</code> as a one-byte character), and
   4878   1.3    lneto '<code>%U</code>' (inserts a <code>long int</code> as a UTF-8 byte sequence).
   4879   1.1  mbalmer 
   4880   1.1  mbalmer 
   4881   1.6  salazar <p>
   4882   1.9   nikita This function may raise errors due to memory overflow
   4883   1.9   nikita or an invalid conversion specifier.
   4884   1.6  salazar 
   4885   1.6  salazar 
   4886   1.1  mbalmer 
   4887   1.1  mbalmer 
   4888   1.1  mbalmer 
   4889   1.2    lneto <hr><h3><a name="lua_pushglobaltable"><code>lua_pushglobaltable</code></a></h3><p>
   4890   1.2    lneto <span class="apii">[-0, +1, &ndash;]</span>
   4891   1.2    lneto <pre>void lua_pushglobaltable (lua_State *L);</pre>
   4892   1.2    lneto 
   4893   1.2    lneto <p>
   4894   1.2    lneto Pushes the global environment onto the stack.
   4895   1.2    lneto 
   4896   1.2    lneto 
   4897   1.2    lneto 
   4898   1.2    lneto 
   4899   1.2    lneto 
   4900   1.1  mbalmer <hr><h3><a name="lua_pushinteger"><code>lua_pushinteger</code></a></h3><p>
   4901   1.2    lneto <span class="apii">[-0, +1, &ndash;]</span>
   4902   1.1  mbalmer <pre>void lua_pushinteger (lua_State *L, lua_Integer n);</pre>
   4903   1.1  mbalmer 
   4904   1.1  mbalmer <p>
   4905   1.2    lneto Pushes an integer with value <code>n</code> onto the stack.
   4906   1.1  mbalmer 
   4907   1.1  mbalmer 
   4908   1.1  mbalmer 
   4909   1.1  mbalmer 
   4910   1.1  mbalmer 
   4911   1.1  mbalmer <hr><h3><a name="lua_pushlightuserdata"><code>lua_pushlightuserdata</code></a></h3><p>
   4912   1.2    lneto <span class="apii">[-0, +1, &ndash;]</span>
   4913   1.1  mbalmer <pre>void lua_pushlightuserdata (lua_State *L, void *p);</pre>
   4914   1.1  mbalmer 
   4915   1.1  mbalmer <p>
   4916   1.1  mbalmer Pushes a light userdata onto the stack.
   4917   1.1  mbalmer 
   4918   1.1  mbalmer 
   4919   1.1  mbalmer <p>
   4920   1.1  mbalmer Userdata represent C&nbsp;values in Lua.
   4921   1.2    lneto A <em>light userdata</em> represents a pointer, a <code>void*</code>.
   4922   1.1  mbalmer It is a value (like a number):
   4923   1.1  mbalmer you do not create it, it has no individual metatable,
   4924   1.1  mbalmer and it is not collected (as it was never created).
   4925   1.1  mbalmer A light userdata is equal to "any"
   4926   1.1  mbalmer light userdata with the same C&nbsp;address.
   4927   1.1  mbalmer 
   4928   1.1  mbalmer 
   4929   1.1  mbalmer 
   4930   1.1  mbalmer 
   4931   1.1  mbalmer 
   4932   1.1  mbalmer <hr><h3><a name="lua_pushliteral"><code>lua_pushliteral</code></a></h3><p>
   4933   1.5    lneto <span class="apii">[-0, +1, <em>m</em>]</span>
   4934   1.2    lneto <pre>const char *lua_pushliteral (lua_State *L, const char *s);</pre>
   4935   1.1  mbalmer 
   4936   1.1  mbalmer <p>
   4937   1.4  mbalmer This macro is equivalent to <a href="#lua_pushstring"><code>lua_pushstring</code></a>,
   4938   1.4  mbalmer but should be used only when <code>s</code> is a literal string.
   4939   1.9   nikita (Lua may optimize this case.)
   4940   1.1  mbalmer 
   4941   1.1  mbalmer 
   4942   1.1  mbalmer 
   4943   1.1  mbalmer 
   4944   1.1  mbalmer 
   4945   1.1  mbalmer <hr><h3><a name="lua_pushlstring"><code>lua_pushlstring</code></a></h3><p>
   4946   1.5    lneto <span class="apii">[-0, +1, <em>m</em>]</span>
   4947   1.2    lneto <pre>const char *lua_pushlstring (lua_State *L, const char *s, size_t len);</pre>
   4948   1.1  mbalmer 
   4949   1.1  mbalmer <p>
   4950   1.1  mbalmer Pushes the string pointed to by <code>s</code> with size <code>len</code>
   4951   1.1  mbalmer onto the stack.
   4952   1.9   nikita Lua will make or reuse an internal copy of the given string,
   4953   1.1  mbalmer so the memory at <code>s</code> can be freed or reused immediately after
   4954   1.1  mbalmer the function returns.
   4955   1.2    lneto The string can contain any binary data,
   4956   1.2    lneto including embedded zeros.
   4957   1.2    lneto 
   4958   1.2    lneto 
   4959   1.2    lneto <p>
   4960   1.9   nikita Returns a pointer to the internal copy of the string (see <a href="#4.1.3">&sect;4.1.3</a>).
   4961   1.1  mbalmer 
   4962   1.1  mbalmer 
   4963   1.1  mbalmer 
   4964   1.1  mbalmer 
   4965   1.1  mbalmer 
   4966   1.1  mbalmer <hr><h3><a name="lua_pushnil"><code>lua_pushnil</code></a></h3><p>
   4967   1.2    lneto <span class="apii">[-0, +1, &ndash;]</span>
   4968   1.1  mbalmer <pre>void lua_pushnil (lua_State *L);</pre>
   4969   1.1  mbalmer 
   4970   1.1  mbalmer <p>
   4971   1.1  mbalmer Pushes a nil value onto the stack.
   4972   1.1  mbalmer 
   4973   1.1  mbalmer 
   4974   1.1  mbalmer 
   4975   1.1  mbalmer 
   4976   1.1  mbalmer 
   4977   1.1  mbalmer <hr><h3><a name="lua_pushnumber"><code>lua_pushnumber</code></a></h3><p>
   4978   1.2    lneto <span class="apii">[-0, +1, &ndash;]</span>
   4979   1.1  mbalmer <pre>void lua_pushnumber (lua_State *L, lua_Number n);</pre>
   4980   1.1  mbalmer 
   4981   1.1  mbalmer <p>
   4982   1.2    lneto Pushes a float with value <code>n</code> onto the stack.
   4983   1.1  mbalmer 
   4984   1.1  mbalmer 
   4985   1.1  mbalmer 
   4986   1.1  mbalmer 
   4987   1.1  mbalmer 
   4988   1.1  mbalmer <hr><h3><a name="lua_pushstring"><code>lua_pushstring</code></a></h3><p>
   4989   1.5    lneto <span class="apii">[-0, +1, <em>m</em>]</span>
   4990   1.2    lneto <pre>const char *lua_pushstring (lua_State *L, const char *s);</pre>
   4991   1.1  mbalmer 
   4992   1.1  mbalmer <p>
   4993   1.1  mbalmer Pushes the zero-terminated string pointed to by <code>s</code>
   4994   1.1  mbalmer onto the stack.
   4995   1.9   nikita Lua will make or reuse an internal copy of the given string,
   4996   1.1  mbalmer so the memory at <code>s</code> can be freed or reused immediately after
   4997   1.1  mbalmer the function returns.
   4998   1.2    lneto 
   4999   1.2    lneto 
   5000   1.2    lneto <p>
   5001   1.9   nikita Returns a pointer to the internal copy of the string (see <a href="#4.1.3">&sect;4.1.3</a>).
   5002   1.2    lneto 
   5003   1.2    lneto 
   5004   1.2    lneto <p>
   5005   1.2    lneto If <code>s</code> is <code>NULL</code>, pushes <b>nil</b> and returns <code>NULL</code>.
   5006   1.1  mbalmer 
   5007   1.1  mbalmer 
   5008   1.1  mbalmer 
   5009   1.1  mbalmer 
   5010   1.1  mbalmer 
   5011   1.1  mbalmer <hr><h3><a name="lua_pushthread"><code>lua_pushthread</code></a></h3><p>
   5012   1.2    lneto <span class="apii">[-0, +1, &ndash;]</span>
   5013   1.1  mbalmer <pre>int lua_pushthread (lua_State *L);</pre>
   5014   1.1  mbalmer 
   5015   1.1  mbalmer <p>
   5016   1.1  mbalmer Pushes the thread represented by <code>L</code> onto the stack.
   5017   1.1  mbalmer Returns 1 if this thread is the main thread of its state.
   5018   1.1  mbalmer 
   5019   1.1  mbalmer 
   5020   1.1  mbalmer 
   5021   1.1  mbalmer 
   5022   1.1  mbalmer 
   5023   1.1  mbalmer <hr><h3><a name="lua_pushvalue"><code>lua_pushvalue</code></a></h3><p>
   5024   1.2    lneto <span class="apii">[-0, +1, &ndash;]</span>
   5025   1.1  mbalmer <pre>void lua_pushvalue (lua_State *L, int index);</pre>
   5026   1.1  mbalmer 
   5027   1.1  mbalmer <p>
   5028   1.2    lneto Pushes a copy of the element at the given index
   5029   1.1  mbalmer onto the stack.
   5030   1.1  mbalmer 
   5031   1.1  mbalmer 
   5032   1.1  mbalmer 
   5033   1.1  mbalmer 
   5034   1.1  mbalmer 
   5035   1.1  mbalmer <hr><h3><a name="lua_pushvfstring"><code>lua_pushvfstring</code></a></h3><p>
   5036   1.9   nikita <span class="apii">[-0, +1, <em>v</em>]</span>
   5037   1.1  mbalmer <pre>const char *lua_pushvfstring (lua_State *L,
   5038   1.1  mbalmer                               const char *fmt,
   5039   1.1  mbalmer                               va_list argp);</pre>
   5040   1.1  mbalmer 
   5041   1.1  mbalmer <p>
   5042   1.1  mbalmer Equivalent to <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>, except that it receives a <code>va_list</code>
   5043   1.1  mbalmer instead of a variable number of arguments.
   5044   1.1  mbalmer 
   5045   1.1  mbalmer 
   5046   1.1  mbalmer 
   5047   1.1  mbalmer 
   5048   1.1  mbalmer 
   5049   1.1  mbalmer <hr><h3><a name="lua_rawequal"><code>lua_rawequal</code></a></h3><p>
   5050   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   5051   1.1  mbalmer <pre>int lua_rawequal (lua_State *L, int index1, int index2);</pre>
   5052   1.1  mbalmer 
   5053   1.1  mbalmer <p>
   5054   1.2    lneto Returns 1 if the two values in indices <code>index1</code> and
   5055   1.1  mbalmer <code>index2</code> are primitively equal
   5056   1.9   nikita (that is, equal without calling the <code>__eq</code> metamethod).
   5057   1.1  mbalmer Otherwise returns&nbsp;0.
   5058   1.3    lneto Also returns&nbsp;0 if any of the indices are not valid.
   5059   1.1  mbalmer 
   5060   1.1  mbalmer 
   5061   1.1  mbalmer 
   5062   1.1  mbalmer 
   5063   1.1  mbalmer 
   5064   1.1  mbalmer <hr><h3><a name="lua_rawget"><code>lua_rawget</code></a></h3><p>
   5065   1.2    lneto <span class="apii">[-1, +1, &ndash;]</span>
   5066   1.2    lneto <pre>int lua_rawget (lua_State *L, int index);</pre>
   5067   1.1  mbalmer 
   5068   1.1  mbalmer <p>
   5069   1.1  mbalmer Similar to <a href="#lua_gettable"><code>lua_gettable</code></a>, but does a raw access
   5070   1.1  mbalmer (i.e., without metamethods).
   5071  1.10   nikita The value at <code>index</code> must be a table.
   5072   1.1  mbalmer 
   5073   1.1  mbalmer 
   5074   1.1  mbalmer 
   5075   1.1  mbalmer 
   5076   1.1  mbalmer 
   5077   1.2    lneto <hr><h3><a name="lua_rawgeti"><code>lua_rawgeti</code></a></h3><p>
   5078   1.2    lneto <span class="apii">[-0, +1, &ndash;]</span>
   5079   1.2    lneto <pre>int lua_rawgeti (lua_State *L, int index, lua_Integer n);</pre>
   5080   1.2    lneto 
   5081   1.2    lneto <p>
   5082   1.2    lneto Pushes onto the stack the value <code>t[n]</code>,
   5083   1.2    lneto where <code>t</code> is the table at the given index.
   5084   1.6  salazar The access is raw,
   5085   1.9   nikita that is, it does not use the <code>__index</code> metavalue.
   5086   1.2    lneto 
   5087   1.2    lneto 
   5088   1.2    lneto <p>
   5089   1.2    lneto Returns the type of the pushed value.
   5090   1.2    lneto 
   5091   1.2    lneto 
   5092   1.2    lneto 
   5093   1.2    lneto 
   5094   1.2    lneto 
   5095   1.2    lneto <hr><h3><a name="lua_rawgetp"><code>lua_rawgetp</code></a></h3><p>
   5096   1.2    lneto <span class="apii">[-0, +1, &ndash;]</span>
   5097   1.2    lneto <pre>int lua_rawgetp (lua_State *L, int index, const void *p);</pre>
   5098   1.2    lneto 
   5099   1.2    lneto <p>
   5100   1.2    lneto Pushes onto the stack the value <code>t[k]</code>,
   5101   1.2    lneto where <code>t</code> is the table at the given index and
   5102   1.2    lneto <code>k</code> is the pointer <code>p</code> represented as a light userdata.
   5103   1.2    lneto The access is raw;
   5104   1.9   nikita that is, it does not use the <code>__index</code> metavalue.
   5105   1.2    lneto 
   5106   1.2    lneto 
   5107   1.2    lneto <p>
   5108   1.2    lneto Returns the type of the pushed value.
   5109   1.2    lneto 
   5110   1.2    lneto 
   5111   1.2    lneto 
   5112   1.2    lneto 
   5113   1.2    lneto 
   5114   1.2    lneto <hr><h3><a name="lua_rawlen"><code>lua_rawlen</code></a></h3><p>
   5115   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   5116   1.9   nikita <pre>lua_Unsigned lua_rawlen (lua_State *L, int index);</pre>
   5117   1.2    lneto 
   5118   1.2    lneto <p>
   5119   1.2    lneto Returns the raw "length" of the value at the given index:
   5120   1.2    lneto for strings, this is the string length;
   5121   1.2    lneto for tables, this is the result of the length operator ('<code>#</code>')
   5122   1.2    lneto with no metamethods;
   5123   1.2    lneto for userdata, this is the size of the block of memory allocated
   5124   1.9   nikita for the userdata.
   5125   1.9   nikita For other values, this call returns&nbsp;0.
   5126   1.1  mbalmer 
   5127   1.1  mbalmer 
   5128   1.1  mbalmer 
   5129   1.1  mbalmer 
   5130   1.1  mbalmer 
   5131   1.1  mbalmer <hr><h3><a name="lua_rawset"><code>lua_rawset</code></a></h3><p>
   5132   1.5    lneto <span class="apii">[-2, +0, <em>m</em>]</span>
   5133   1.1  mbalmer <pre>void lua_rawset (lua_State *L, int index);</pre>
   5134   1.1  mbalmer 
   5135   1.1  mbalmer <p>
   5136   1.1  mbalmer Similar to <a href="#lua_settable"><code>lua_settable</code></a>, but does a raw assignment
   5137   1.1  mbalmer (i.e., without metamethods).
   5138  1.10   nikita The value at <code>index</code> must be a table.
   5139   1.1  mbalmer 
   5140   1.1  mbalmer 
   5141   1.1  mbalmer 
   5142   1.1  mbalmer 
   5143   1.1  mbalmer 
   5144   1.1  mbalmer <hr><h3><a name="lua_rawseti"><code>lua_rawseti</code></a></h3><p>
   5145   1.5    lneto <span class="apii">[-1, +0, <em>m</em>]</span>
   5146   1.3    lneto <pre>void lua_rawseti (lua_State *L, int index, lua_Integer i);</pre>
   5147   1.1  mbalmer 
   5148   1.1  mbalmer <p>
   5149   1.3    lneto Does the equivalent of <code>t[i] = v</code>,
   5150   1.2    lneto where <code>t</code> is the table at the given index
   5151   1.9   nikita and <code>v</code> is the value on the top of the stack.
   5152   1.2    lneto 
   5153   1.2    lneto 
   5154   1.2    lneto <p>
   5155   1.2    lneto This function pops the value from the stack.
   5156   1.6  salazar The assignment is raw,
   5157   1.9   nikita that is, it does not use the <code>__newindex</code> metavalue.
   5158   1.2    lneto 
   5159   1.2    lneto 
   5160   1.2    lneto 
   5161   1.2    lneto 
   5162   1.2    lneto 
   5163   1.2    lneto <hr><h3><a name="lua_rawsetp"><code>lua_rawsetp</code></a></h3><p>
   5164   1.5    lneto <span class="apii">[-1, +0, <em>m</em>]</span>
   5165   1.2    lneto <pre>void lua_rawsetp (lua_State *L, int index, const void *p);</pre>
   5166   1.2    lneto 
   5167   1.2    lneto <p>
   5168   1.4  mbalmer Does the equivalent of <code>t[p] = v</code>,
   5169   1.2    lneto where <code>t</code> is the table at the given index,
   5170   1.4  mbalmer <code>p</code> is encoded as a light userdata,
   5171   1.9   nikita and <code>v</code> is the value on the top of the stack.
   5172   1.1  mbalmer 
   5173   1.1  mbalmer 
   5174   1.1  mbalmer <p>
   5175   1.1  mbalmer This function pops the value from the stack.
   5176   1.6  salazar The assignment is raw,
   5177   1.9   nikita that is, it does not use the <code>__newindex</code> metavalue.
   5178   1.1  mbalmer 
   5179   1.1  mbalmer 
   5180   1.1  mbalmer 
   5181   1.1  mbalmer 
   5182   1.1  mbalmer 
   5183   1.1  mbalmer <hr><h3><a name="lua_Reader"><code>lua_Reader</code></a></h3>
   5184   1.1  mbalmer <pre>typedef const char * (*lua_Reader) (lua_State *L,
   5185   1.1  mbalmer                                     void *data,
   5186   1.1  mbalmer                                     size_t *size);</pre>
   5187   1.1  mbalmer 
   5188   1.1  mbalmer <p>
   5189   1.1  mbalmer The reader function used by <a href="#lua_load"><code>lua_load</code></a>.
   5190   1.9   nikita Every time <a href="#lua_load"><code>lua_load</code></a> needs another piece of the chunk,
   5191   1.9   nikita it calls the reader,
   5192   1.1  mbalmer passing along its <code>data</code> parameter.
   5193   1.1  mbalmer The reader must return a pointer to a block of memory
   5194   1.1  mbalmer with a new piece of the chunk
   5195   1.1  mbalmer and set <code>size</code> to the block size.
   5196   1.1  mbalmer The block must exist until the reader function is called again.
   5197   1.1  mbalmer To signal the end of the chunk,
   5198   1.1  mbalmer the reader must return <code>NULL</code> or set <code>size</code> to zero.
   5199   1.1  mbalmer The reader function may return pieces of any size greater than zero.
   5200   1.1  mbalmer 
   5201   1.1  mbalmer 
   5202   1.1  mbalmer 
   5203   1.1  mbalmer 
   5204   1.1  mbalmer 
   5205   1.1  mbalmer <hr><h3><a name="lua_register"><code>lua_register</code></a></h3><p>
   5206   1.1  mbalmer <span class="apii">[-0, +0, <em>e</em>]</span>
   5207   1.2    lneto <pre>void lua_register (lua_State *L, const char *name, lua_CFunction f);</pre>
   5208   1.1  mbalmer 
   5209   1.1  mbalmer <p>
   5210   1.7  mbalmer Sets the C&nbsp;function <code>f</code> as the new value of global <code>name</code>.
   5211   1.1  mbalmer It is defined as a macro:
   5212   1.1  mbalmer 
   5213   1.1  mbalmer <pre>
   5214   1.1  mbalmer      #define lua_register(L,n,f) \
   5215   1.1  mbalmer             (lua_pushcfunction(L, f), lua_setglobal(L, n))
   5216   1.1  mbalmer </pre>
   5217   1.1  mbalmer 
   5218   1.1  mbalmer 
   5219   1.1  mbalmer 
   5220   1.1  mbalmer 
   5221   1.1  mbalmer <hr><h3><a name="lua_remove"><code>lua_remove</code></a></h3><p>
   5222   1.2    lneto <span class="apii">[-1, +0, &ndash;]</span>
   5223   1.1  mbalmer <pre>void lua_remove (lua_State *L, int index);</pre>
   5224   1.1  mbalmer 
   5225   1.1  mbalmer <p>
   5226   1.1  mbalmer Removes the element at the given valid index,
   5227   1.1  mbalmer shifting down the elements above this index to fill the gap.
   5228   1.2    lneto This function cannot be called with a pseudo-index,
   5229   1.1  mbalmer because a pseudo-index is not an actual stack position.
   5230   1.1  mbalmer 
   5231   1.1  mbalmer 
   5232   1.1  mbalmer 
   5233   1.1  mbalmer 
   5234   1.1  mbalmer 
   5235   1.1  mbalmer <hr><h3><a name="lua_replace"><code>lua_replace</code></a></h3><p>
   5236   1.2    lneto <span class="apii">[-1, +0, &ndash;]</span>
   5237   1.1  mbalmer <pre>void lua_replace (lua_State *L, int index);</pre>
   5238   1.1  mbalmer 
   5239   1.1  mbalmer <p>
   5240   1.2    lneto Moves the top element into the given valid index
   5241   1.1  mbalmer without shifting any element
   5242   1.4  mbalmer (therefore replacing the value at that given index),
   5243   1.2    lneto and then pops the top element.
   5244   1.1  mbalmer 
   5245   1.1  mbalmer 
   5246   1.1  mbalmer 
   5247   1.1  mbalmer 
   5248   1.1  mbalmer 
   5249   1.9   nikita <hr><h3><a name="lua_resetthread"><code>lua_resetthread</code></a></h3><p>
   5250   1.9   nikita <span class="apii">[-0, +?, &ndash;]</span>
   5251   1.9   nikita <pre>int lua_resetthread (lua_State *L);</pre>
   5252   1.9   nikita 
   5253   1.9   nikita <p>
   5254  1.10   nikita This function is deprecated;
   5255  1.10   nikita it is equivalent to <a href="#lua_closethread"><code>lua_closethread</code></a> with
   5256  1.10   nikita <code>from</code> being <code>NULL</code>.
   5257   1.9   nikita 
   5258   1.9   nikita 
   5259   1.9   nikita 
   5260   1.9   nikita 
   5261   1.9   nikita 
   5262   1.1  mbalmer <hr><h3><a name="lua_resume"><code>lua_resume</code></a></h3><p>
   5263   1.2    lneto <span class="apii">[-?, +?, &ndash;]</span>
   5264   1.9   nikita <pre>int lua_resume (lua_State *L, lua_State *from, int nargs,
   5265   1.9   nikita                           int *nresults);</pre>
   5266   1.1  mbalmer 
   5267   1.1  mbalmer <p>
   5268   1.4  mbalmer Starts and resumes a coroutine in the given thread <code>L</code>.
   5269   1.1  mbalmer 
   5270   1.1  mbalmer 
   5271   1.1  mbalmer <p>
   5272   1.2    lneto To start a coroutine,
   5273   1.9   nikita you push the main function plus any arguments
   5274   1.9   nikita onto the empty stack of the thread.
   5275   1.1  mbalmer then you call <a href="#lua_resume"><code>lua_resume</code></a>,
   5276   1.2    lneto with <code>nargs</code> being the number of arguments.
   5277   1.1  mbalmer This call returns when the coroutine suspends or finishes its execution.
   5278   1.9   nikita When it returns,
   5279   1.9   nikita <code>*nresults</code> is updated and
   5280   1.9   nikita the top of the stack contains
   5281   1.9   nikita the <code>*nresults</code> values passed to <a href="#lua_yield"><code>lua_yield</code></a>
   5282   1.9   nikita or returned by the body function.
   5283   1.1  mbalmer <a href="#lua_resume"><code>lua_resume</code></a> returns
   5284   1.1  mbalmer <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the coroutine yields,
   5285   1.2    lneto <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> if the coroutine finishes its execution
   5286   1.1  mbalmer without errors,
   5287   1.9   nikita or an error code in case of errors (see <a href="#4.4.1">&sect;4.4.1</a>).
   5288   1.1  mbalmer In case of errors,
   5289   1.9   nikita the error object is on the top of the stack.
   5290   1.2    lneto 
   5291   1.2    lneto 
   5292   1.2    lneto <p>
   5293   1.2    lneto To resume a coroutine,
   5294   1.9   nikita you remove the <code>*nresults</code> yielded values from its stack,
   5295   1.9   nikita push the values to be passed as results from <code>yield</code>,
   5296   1.1  mbalmer and then call <a href="#lua_resume"><code>lua_resume</code></a>.
   5297   1.1  mbalmer 
   5298   1.1  mbalmer 
   5299   1.2    lneto <p>
   5300   1.2    lneto The parameter <code>from</code> represents the coroutine that is resuming <code>L</code>.
   5301   1.2    lneto If there is no such coroutine,
   5302   1.2    lneto this parameter can be <code>NULL</code>.
   5303   1.2    lneto 
   5304   1.2    lneto 
   5305   1.1  mbalmer 
   5306   1.1  mbalmer 
   5307   1.1  mbalmer 
   5308   1.2    lneto <hr><h3><a name="lua_rotate"><code>lua_rotate</code></a></h3><p>
   5309   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   5310   1.2    lneto <pre>void lua_rotate (lua_State *L, int idx, int n);</pre>
   5311   1.1  mbalmer 
   5312   1.1  mbalmer <p>
   5313   1.4  mbalmer Rotates the stack elements between the valid index <code>idx</code>
   5314   1.4  mbalmer and the top of the stack.
   5315   1.4  mbalmer The elements are rotated <code>n</code> positions in the direction of the top,
   5316   1.4  mbalmer for a positive <code>n</code>,
   5317   1.2    lneto or <code>-n</code> positions in the direction of the bottom,
   5318   1.2    lneto for a negative <code>n</code>.
   5319   1.2    lneto The absolute value of <code>n</code> must not be greater than the size
   5320   1.2    lneto of the slice being rotated.
   5321   1.4  mbalmer This function cannot be called with a pseudo-index,
   5322   1.4  mbalmer because a pseudo-index is not an actual stack position.
   5323   1.1  mbalmer 
   5324   1.1  mbalmer 
   5325   1.1  mbalmer 
   5326   1.1  mbalmer 
   5327   1.1  mbalmer 
   5328   1.2    lneto <hr><h3><a name="lua_setallocf"><code>lua_setallocf</code></a></h3><p>
   5329   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   5330   1.2    lneto <pre>void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);</pre>
   5331   1.1  mbalmer 
   5332   1.1  mbalmer <p>
   5333   1.2    lneto Changes the allocator function of a given state to <code>f</code>
   5334   1.2    lneto with user data <code>ud</code>.
   5335   1.1  mbalmer 
   5336   1.1  mbalmer 
   5337   1.1  mbalmer 
   5338   1.1  mbalmer 
   5339   1.1  mbalmer 
   5340   1.1  mbalmer <hr><h3><a name="lua_setfield"><code>lua_setfield</code></a></h3><p>
   5341   1.1  mbalmer <span class="apii">[-1, +0, <em>e</em>]</span>
   5342   1.1  mbalmer <pre>void lua_setfield (lua_State *L, int index, const char *k);</pre>
   5343   1.1  mbalmer 
   5344   1.1  mbalmer <p>
   5345   1.1  mbalmer Does the equivalent to <code>t[k] = v</code>,
   5346   1.2    lneto where <code>t</code> is the value at the given index
   5347   1.9   nikita and <code>v</code> is the value on the top of the stack.
   5348   1.1  mbalmer 
   5349   1.1  mbalmer 
   5350   1.1  mbalmer <p>
   5351   1.1  mbalmer This function pops the value from the stack.
   5352   1.1  mbalmer As in Lua, this function may trigger a metamethod
   5353   1.2    lneto for the "newindex" event (see <a href="#2.4">&sect;2.4</a>).
   5354   1.1  mbalmer 
   5355   1.1  mbalmer 
   5356   1.1  mbalmer 
   5357   1.1  mbalmer 
   5358   1.1  mbalmer 
   5359   1.1  mbalmer <hr><h3><a name="lua_setglobal"><code>lua_setglobal</code></a></h3><p>
   5360   1.1  mbalmer <span class="apii">[-1, +0, <em>e</em>]</span>
   5361   1.1  mbalmer <pre>void lua_setglobal (lua_State *L, const char *name);</pre>
   5362   1.1  mbalmer 
   5363   1.1  mbalmer <p>
   5364   1.1  mbalmer Pops a value from the stack and
   5365   1.1  mbalmer sets it as the new value of global <code>name</code>.
   5366   1.1  mbalmer 
   5367   1.1  mbalmer 
   5368   1.1  mbalmer 
   5369   1.1  mbalmer 
   5370   1.1  mbalmer 
   5371   1.3    lneto <hr><h3><a name="lua_seti"><code>lua_seti</code></a></h3><p>
   5372   1.3    lneto <span class="apii">[-1, +0, <em>e</em>]</span>
   5373   1.3    lneto <pre>void lua_seti (lua_State *L, int index, lua_Integer n);</pre>
   5374   1.3    lneto 
   5375   1.3    lneto <p>
   5376   1.3    lneto Does the equivalent to <code>t[n] = v</code>,
   5377   1.3    lneto where <code>t</code> is the value at the given index
   5378   1.9   nikita and <code>v</code> is the value on the top of the stack.
   5379   1.3    lneto 
   5380   1.3    lneto 
   5381   1.3    lneto <p>
   5382   1.3    lneto This function pops the value from the stack.
   5383   1.3    lneto As in Lua, this function may trigger a metamethod
   5384   1.3    lneto for the "newindex" event (see <a href="#2.4">&sect;2.4</a>).
   5385   1.3    lneto 
   5386   1.3    lneto 
   5387   1.3    lneto 
   5388   1.3    lneto 
   5389   1.3    lneto 
   5390   1.9   nikita <hr><h3><a name="lua_setiuservalue"><code>lua_setiuservalue</code></a></h3><p>
   5391   1.9   nikita <span class="apii">[-1, +0, &ndash;]</span>
   5392   1.9   nikita <pre>int lua_setiuservalue (lua_State *L, int index, int n);</pre>
   5393   1.9   nikita 
   5394   1.9   nikita <p>
   5395   1.9   nikita Pops a value from the stack and sets it as
   5396   1.9   nikita the new <code>n</code>-th user value associated to the
   5397   1.9   nikita full userdata at the given index.
   5398   1.9   nikita Returns 0 if the userdata does not have that value.
   5399   1.9   nikita 
   5400   1.9   nikita 
   5401   1.9   nikita 
   5402   1.9   nikita 
   5403   1.9   nikita 
   5404   1.1  mbalmer <hr><h3><a name="lua_setmetatable"><code>lua_setmetatable</code></a></h3><p>
   5405   1.2    lneto <span class="apii">[-1, +0, &ndash;]</span>
   5406   1.9   nikita <pre>int lua_setmetatable (lua_State *L, int index);</pre>
   5407   1.9   nikita 
   5408   1.9   nikita <p>
   5409   1.9   nikita Pops a table or <b>nil</b> from the stack and
   5410   1.9   nikita sets that value as the new metatable for the value at the given index.
   5411   1.9   nikita (<b>nil</b> means no metatable.)
   5412   1.9   nikita 
   5413   1.1  mbalmer 
   5414   1.1  mbalmer <p>
   5415   1.9   nikita (For historical reasons, this function returns an <code>int</code>,
   5416   1.9   nikita which now is always 1.)
   5417   1.1  mbalmer 
   5418   1.1  mbalmer 
   5419   1.1  mbalmer 
   5420   1.1  mbalmer 
   5421   1.1  mbalmer 
   5422   1.1  mbalmer <hr><h3><a name="lua_settable"><code>lua_settable</code></a></h3><p>
   5423   1.1  mbalmer <span class="apii">[-2, +0, <em>e</em>]</span>
   5424   1.1  mbalmer <pre>void lua_settable (lua_State *L, int index);</pre>
   5425   1.1  mbalmer 
   5426   1.1  mbalmer <p>
   5427   1.1  mbalmer Does the equivalent to <code>t[k] = v</code>,
   5428   1.2    lneto where <code>t</code> is the value at the given index,
   5429   1.9   nikita <code>v</code> is the value on the top of the stack,
   5430   1.1  mbalmer and <code>k</code> is the value just below the top.
   5431   1.1  mbalmer 
   5432   1.1  mbalmer 
   5433   1.1  mbalmer <p>
   5434   1.1  mbalmer This function pops both the key and the value from the stack.
   5435   1.1  mbalmer As in Lua, this function may trigger a metamethod
   5436   1.2    lneto for the "newindex" event (see <a href="#2.4">&sect;2.4</a>).
   5437   1.1  mbalmer 
   5438   1.1  mbalmer 
   5439   1.1  mbalmer 
   5440   1.1  mbalmer 
   5441   1.1  mbalmer 
   5442   1.1  mbalmer <hr><h3><a name="lua_settop"><code>lua_settop</code></a></h3><p>
   5443   1.9   nikita <span class="apii">[-?, +?, <em>e</em>]</span>
   5444   1.1  mbalmer <pre>void lua_settop (lua_State *L, int index);</pre>
   5445   1.1  mbalmer 
   5446   1.1  mbalmer <p>
   5447   1.2    lneto Accepts any index, or&nbsp;0,
   5448   1.1  mbalmer and sets the stack top to this index.
   5449   1.9   nikita If the new top is greater than the old one,
   5450   1.1  mbalmer then the new elements are filled with <b>nil</b>.
   5451   1.1  mbalmer If <code>index</code> is&nbsp;0, then all stack elements are removed.
   5452   1.1  mbalmer 
   5453   1.1  mbalmer 
   5454   1.9   nikita <p>
   5455   1.9   nikita This function can run arbitrary code when removing an index
   5456   1.9   nikita marked as to-be-closed from the stack.
   5457   1.9   nikita 
   5458   1.1  mbalmer 
   5459   1.1  mbalmer 
   5460   1.1  mbalmer 
   5461   1.9   nikita 
   5462   1.9   nikita <hr><h3><a name="lua_setwarnf"><code>lua_setwarnf</code></a></h3><p>
   5463   1.9   nikita <span class="apii">[-0, +0, &ndash;]</span>
   5464   1.9   nikita <pre>void lua_setwarnf (lua_State *L, lua_WarnFunction f, void *ud);</pre>
   5465   1.2    lneto 
   5466   1.2    lneto <p>
   5467   1.9   nikita Sets the warning function to be used by Lua to emit warnings
   5468   1.9   nikita (see <a href="#lua_WarnFunction"><code>lua_WarnFunction</code></a>).
   5469   1.9   nikita The <code>ud</code> parameter sets the value <code>ud</code> passed to
   5470   1.9   nikita the warning function.
   5471   1.2    lneto 
   5472   1.2    lneto 
   5473   1.2    lneto 
   5474   1.2    lneto 
   5475   1.2    lneto 
   5476   1.1  mbalmer <hr><h3><a name="lua_State"><code>lua_State</code></a></h3>
   5477   1.1  mbalmer <pre>typedef struct lua_State lua_State;</pre>
   5478   1.1  mbalmer 
   5479   1.1  mbalmer <p>
   5480   1.2    lneto An opaque structure that points to a thread and indirectly
   5481   1.2    lneto (through the thread) to the whole state of a Lua interpreter.
   5482   1.1  mbalmer The Lua library is fully reentrant:
   5483   1.1  mbalmer it has no global variables.
   5484   1.2    lneto All information about a state is accessible through this structure.
   5485   1.1  mbalmer 
   5486   1.1  mbalmer 
   5487   1.1  mbalmer <p>
   5488   1.2    lneto A pointer to this structure must be passed as the first argument to
   5489   1.1  mbalmer every function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>,
   5490   1.1  mbalmer which creates a Lua state from scratch.
   5491   1.1  mbalmer 
   5492   1.1  mbalmer 
   5493   1.1  mbalmer 
   5494   1.1  mbalmer 
   5495   1.1  mbalmer 
   5496   1.1  mbalmer <hr><h3><a name="lua_status"><code>lua_status</code></a></h3><p>
   5497   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   5498   1.1  mbalmer <pre>int lua_status (lua_State *L);</pre>
   5499   1.1  mbalmer 
   5500   1.1  mbalmer <p>
   5501   1.1  mbalmer Returns the status of the thread <code>L</code>.
   5502   1.1  mbalmer 
   5503   1.1  mbalmer 
   5504   1.1  mbalmer <p>
   5505   1.9   nikita The status can be <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> for a normal thread,
   5506   1.2    lneto an error code if the thread finished the execution
   5507   1.2    lneto of a <a href="#lua_resume"><code>lua_resume</code></a> with an error,
   5508   1.9   nikita or <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the thread is suspended.
   5509   1.1  mbalmer 
   5510   1.1  mbalmer 
   5511   1.2    lneto <p>
   5512   1.9   nikita You can call functions only in threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>.
   5513   1.2    lneto You can resume threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>
   5514   1.2    lneto (to start a new coroutine) or <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a>
   5515   1.2    lneto (to resume a coroutine).
   5516   1.2    lneto 
   5517   1.2    lneto 
   5518   1.2    lneto 
   5519   1.2    lneto 
   5520   1.2    lneto 
   5521   1.3    lneto <hr><h3><a name="lua_stringtonumber"><code>lua_stringtonumber</code></a></h3><p>
   5522   1.2    lneto <span class="apii">[-0, +1, &ndash;]</span>
   5523   1.3    lneto <pre>size_t lua_stringtonumber (lua_State *L, const char *s);</pre>
   5524   1.2    lneto 
   5525   1.2    lneto <p>
   5526   1.2    lneto Converts the zero-terminated string <code>s</code> to a number,
   5527   1.2    lneto pushes that number into the stack,
   5528   1.3    lneto and returns the total size of the string,
   5529   1.3    lneto that is, its length plus one.
   5530   1.2    lneto The conversion can result in an integer or a float,
   5531   1.2    lneto according to the lexical conventions of Lua (see <a href="#3.1">&sect;3.1</a>).
   5532   1.9   nikita The string may have leading and trailing whitespaces and a sign.
   5533   1.2    lneto If the string is not a valid numeral,
   5534   1.2    lneto returns 0 and pushes nothing.
   5535   1.3    lneto (Note that the result can be used as a boolean,
   5536   1.3    lneto true if the conversion succeeds.)
   5537   1.2    lneto 
   5538   1.2    lneto 
   5539   1.1  mbalmer 
   5540   1.1  mbalmer 
   5541   1.1  mbalmer 
   5542   1.1  mbalmer <hr><h3><a name="lua_toboolean"><code>lua_toboolean</code></a></h3><p>
   5543   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   5544   1.1  mbalmer <pre>int lua_toboolean (lua_State *L, int index);</pre>
   5545   1.1  mbalmer 
   5546   1.1  mbalmer <p>
   5547   1.2    lneto Converts the Lua value at the given index to a C&nbsp;boolean
   5548   1.1  mbalmer value (0&nbsp;or&nbsp;1).
   5549   1.1  mbalmer Like all tests in Lua,
   5550   1.2    lneto <a href="#lua_toboolean"><code>lua_toboolean</code></a> returns true for any Lua value
   5551   1.1  mbalmer different from <b>false</b> and <b>nil</b>;
   5552   1.2    lneto otherwise it returns false.
   5553   1.1  mbalmer (If you want to accept only actual boolean values,
   5554   1.1  mbalmer use <a href="#lua_isboolean"><code>lua_isboolean</code></a> to test the value's type.)
   5555   1.1  mbalmer 
   5556   1.1  mbalmer 
   5557   1.1  mbalmer 
   5558   1.1  mbalmer 
   5559   1.1  mbalmer 
   5560   1.1  mbalmer <hr><h3><a name="lua_tocfunction"><code>lua_tocfunction</code></a></h3><p>
   5561   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   5562   1.1  mbalmer <pre>lua_CFunction lua_tocfunction (lua_State *L, int index);</pre>
   5563   1.1  mbalmer 
   5564   1.1  mbalmer <p>
   5565   1.2    lneto Converts a value at the given index to a C&nbsp;function.
   5566   1.1  mbalmer That value must be a C&nbsp;function;
   5567   1.1  mbalmer otherwise, returns <code>NULL</code>.
   5568   1.1  mbalmer 
   5569   1.1  mbalmer 
   5570   1.1  mbalmer 
   5571   1.1  mbalmer 
   5572   1.1  mbalmer 
   5573   1.9   nikita <hr><h3><a name="lua_toclose"><code>lua_toclose</code></a></h3><p>
   5574   1.9   nikita <span class="apii">[-0, +0, <em>m</em>]</span>
   5575   1.9   nikita <pre>void lua_toclose (lua_State *L, int index);</pre>
   5576   1.9   nikita 
   5577   1.9   nikita <p>
   5578   1.9   nikita Marks the given index in the stack as a
   5579   1.9   nikita to-be-closed slot (see <a href="#3.3.8">&sect;3.3.8</a>).
   5580   1.9   nikita Like a to-be-closed variable in Lua,
   5581   1.9   nikita the value at that slot in the stack will be closed
   5582   1.9   nikita when it goes out of scope.
   5583   1.9   nikita Here, in the context of a C function,
   5584   1.9   nikita to go out of scope means that the running function returns to Lua,
   5585   1.9   nikita or there is an error,
   5586   1.9   nikita or the slot is removed from the stack through
   5587   1.9   nikita <a href="#lua_settop"><code>lua_settop</code></a> or <a href="#lua_pop"><code>lua_pop</code></a>,
   5588   1.9   nikita or there is a call to <a href="#lua_closeslot"><code>lua_closeslot</code></a>.
   5589   1.9   nikita A slot marked as to-be-closed should not be removed from the stack
   5590   1.9   nikita by any other function in the API except <a href="#lua_settop"><code>lua_settop</code></a> or <a href="#lua_pop"><code>lua_pop</code></a>,
   5591   1.9   nikita unless previously deactivated by <a href="#lua_closeslot"><code>lua_closeslot</code></a>.
   5592   1.9   nikita 
   5593   1.9   nikita 
   5594   1.9   nikita <p>
   5595   1.9   nikita This function should not be called for an index
   5596   1.9   nikita that is equal to or below an active to-be-closed slot.
   5597   1.9   nikita 
   5598   1.9   nikita 
   5599   1.9   nikita <p>
   5600   1.9   nikita Note that, both in case of errors and of a regular return,
   5601   1.9   nikita by the time the <code>__close</code> metamethod runs,
   5602   1.9   nikita the C&nbsp;stack was already unwound,
   5603   1.9   nikita so that any automatic C&nbsp;variable declared in the calling function
   5604   1.9   nikita (e.g., a buffer) will be out of scope.
   5605   1.9   nikita 
   5606   1.9   nikita 
   5607   1.9   nikita 
   5608   1.9   nikita 
   5609   1.9   nikita 
   5610   1.1  mbalmer <hr><h3><a name="lua_tointeger"><code>lua_tointeger</code></a></h3><p>
   5611   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   5612   1.1  mbalmer <pre>lua_Integer lua_tointeger (lua_State *L, int index);</pre>
   5613   1.1  mbalmer 
   5614   1.1  mbalmer <p>
   5615   1.2    lneto Equivalent to <a href="#lua_tointegerx"><code>lua_tointegerx</code></a> with <code>isnum</code> equal to <code>NULL</code>.
   5616   1.2    lneto 
   5617   1.2    lneto 
   5618   1.2    lneto 
   5619   1.2    lneto 
   5620   1.2    lneto 
   5621   1.2    lneto <hr><h3><a name="lua_tointegerx"><code>lua_tointegerx</code></a></h3><p>
   5622   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   5623   1.2    lneto <pre>lua_Integer lua_tointegerx (lua_State *L, int index, int *isnum);</pre>
   5624   1.2    lneto 
   5625   1.2    lneto <p>
   5626   1.2    lneto Converts the Lua value at the given index
   5627   1.1  mbalmer to the signed integral type <a href="#lua_Integer"><code>lua_Integer</code></a>.
   5628   1.2    lneto The Lua value must be an integer,
   5629   1.2    lneto or a number or string convertible to an integer (see <a href="#3.4.3">&sect;3.4.3</a>);
   5630   1.2    lneto otherwise, <code>lua_tointegerx</code> returns&nbsp;0.
   5631   1.1  mbalmer 
   5632   1.1  mbalmer 
   5633   1.1  mbalmer <p>
   5634   1.2    lneto If <code>isnum</code> is not <code>NULL</code>,
   5635   1.2    lneto its referent is assigned a boolean value that
   5636   1.2    lneto indicates whether the operation succeeded.
   5637   1.1  mbalmer 
   5638   1.1  mbalmer 
   5639   1.1  mbalmer 
   5640   1.1  mbalmer 
   5641   1.1  mbalmer 
   5642   1.1  mbalmer <hr><h3><a name="lua_tolstring"><code>lua_tolstring</code></a></h3><p>
   5643   1.5    lneto <span class="apii">[-0, +0, <em>m</em>]</span>
   5644   1.1  mbalmer <pre>const char *lua_tolstring (lua_State *L, int index, size_t *len);</pre>
   5645   1.1  mbalmer 
   5646   1.1  mbalmer <p>
   5647   1.2    lneto Converts the Lua value at the given index to a C&nbsp;string.
   5648   1.1  mbalmer If <code>len</code> is not <code>NULL</code>,
   5649   1.5    lneto it sets <code>*len</code> with the string length.
   5650   1.1  mbalmer The Lua value must be a string or a number;
   5651   1.1  mbalmer otherwise, the function returns <code>NULL</code>.
   5652   1.1  mbalmer If the value is a number,
   5653   1.2    lneto then <code>lua_tolstring</code> also
   5654   1.1  mbalmer <em>changes the actual value in the stack to a string</em>.
   5655   1.1  mbalmer (This change confuses <a href="#lua_next"><code>lua_next</code></a>
   5656   1.2    lneto when <code>lua_tolstring</code> is applied to keys during a table traversal.)
   5657   1.1  mbalmer 
   5658   1.1  mbalmer 
   5659   1.1  mbalmer <p>
   5660   1.5    lneto <code>lua_tolstring</code> returns a pointer
   5661   1.9   nikita to a string inside the Lua state (see <a href="#4.1.3">&sect;4.1.3</a>).
   5662   1.1  mbalmer This string always has a zero ('<code>\0</code>')
   5663   1.1  mbalmer after its last character (as in&nbsp;C),
   5664   1.1  mbalmer but can contain other zeros in its body.
   5665   1.3    lneto 
   5666   1.3    lneto 
   5667   1.1  mbalmer 
   5668   1.1  mbalmer 
   5669   1.1  mbalmer 
   5670   1.1  mbalmer <hr><h3><a name="lua_tonumber"><code>lua_tonumber</code></a></h3><p>
   5671   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   5672   1.1  mbalmer <pre>lua_Number lua_tonumber (lua_State *L, int index);</pre>
   5673   1.1  mbalmer 
   5674   1.1  mbalmer <p>
   5675   1.2    lneto Equivalent to <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> with <code>isnum</code> equal to <code>NULL</code>.
   5676   1.2    lneto 
   5677   1.2    lneto 
   5678   1.2    lneto 
   5679   1.2    lneto 
   5680   1.2    lneto 
   5681   1.2    lneto <hr><h3><a name="lua_tonumberx"><code>lua_tonumberx</code></a></h3><p>
   5682   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   5683   1.2    lneto <pre>lua_Number lua_tonumberx (lua_State *L, int index, int *isnum);</pre>
   5684   1.2    lneto 
   5685   1.2    lneto <p>
   5686   1.2    lneto Converts the Lua value at the given index
   5687   1.1  mbalmer to the C&nbsp;type <a href="#lua_Number"><code>lua_Number</code></a> (see <a href="#lua_Number"><code>lua_Number</code></a>).
   5688   1.1  mbalmer The Lua value must be a number or a string convertible to a number
   5689   1.2    lneto (see <a href="#3.4.3">&sect;3.4.3</a>);
   5690   1.2    lneto otherwise, <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> returns&nbsp;0.
   5691   1.2    lneto 
   5692   1.2    lneto 
   5693   1.2    lneto <p>
   5694   1.2    lneto If <code>isnum</code> is not <code>NULL</code>,
   5695   1.2    lneto its referent is assigned a boolean value that
   5696   1.2    lneto indicates whether the operation succeeded.
   5697   1.1  mbalmer 
   5698   1.1  mbalmer 
   5699   1.1  mbalmer 
   5700   1.1  mbalmer 
   5701   1.1  mbalmer 
   5702   1.1  mbalmer <hr><h3><a name="lua_topointer"><code>lua_topointer</code></a></h3><p>
   5703   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   5704   1.1  mbalmer <pre>const void *lua_topointer (lua_State *L, int index);</pre>
   5705   1.1  mbalmer 
   5706   1.1  mbalmer <p>
   5707   1.2    lneto Converts the value at the given index to a generic
   5708   1.1  mbalmer C&nbsp;pointer (<code>void*</code>).
   5709   1.9   nikita The value can be a userdata, a table, a thread, a string, or a function;
   5710   1.2    lneto otherwise, <code>lua_topointer</code> returns <code>NULL</code>.
   5711   1.1  mbalmer Different objects will give different pointers.
   5712   1.1  mbalmer There is no way to convert the pointer back to its original value.
   5713   1.1  mbalmer 
   5714   1.1  mbalmer 
   5715   1.1  mbalmer <p>
   5716   1.4  mbalmer Typically this function is used only for hashing and debug information.
   5717   1.1  mbalmer 
   5718   1.1  mbalmer 
   5719   1.1  mbalmer 
   5720   1.1  mbalmer 
   5721   1.1  mbalmer 
   5722   1.1  mbalmer <hr><h3><a name="lua_tostring"><code>lua_tostring</code></a></h3><p>
   5723   1.5    lneto <span class="apii">[-0, +0, <em>m</em>]</span>
   5724   1.1  mbalmer <pre>const char *lua_tostring (lua_State *L, int index);</pre>
   5725   1.1  mbalmer 
   5726   1.1  mbalmer <p>
   5727   1.1  mbalmer Equivalent to <a href="#lua_tolstring"><code>lua_tolstring</code></a> with <code>len</code> equal to <code>NULL</code>.
   5728   1.1  mbalmer 
   5729   1.1  mbalmer 
   5730   1.1  mbalmer 
   5731   1.1  mbalmer 
   5732   1.1  mbalmer 
   5733   1.1  mbalmer <hr><h3><a name="lua_tothread"><code>lua_tothread</code></a></h3><p>
   5734   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   5735   1.1  mbalmer <pre>lua_State *lua_tothread (lua_State *L, int index);</pre>
   5736   1.1  mbalmer 
   5737   1.1  mbalmer <p>
   5738   1.2    lneto Converts the value at the given index to a Lua thread
   5739   1.1  mbalmer (represented as <code>lua_State*</code>).
   5740   1.1  mbalmer This value must be a thread;
   5741   1.1  mbalmer otherwise, the function returns <code>NULL</code>.
   5742   1.1  mbalmer 
   5743   1.1  mbalmer 
   5744   1.1  mbalmer 
   5745   1.1  mbalmer 
   5746   1.1  mbalmer 
   5747   1.1  mbalmer <hr><h3><a name="lua_touserdata"><code>lua_touserdata</code></a></h3><p>
   5748   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   5749   1.1  mbalmer <pre>void *lua_touserdata (lua_State *L, int index);</pre>
   5750   1.1  mbalmer 
   5751   1.1  mbalmer <p>
   5752   1.2    lneto If the value at the given index is a full userdata,
   5753   1.9   nikita returns its memory-block address.
   5754   1.1  mbalmer If the value is a light userdata,
   5755   1.9   nikita returns its value (a pointer).
   5756   1.1  mbalmer Otherwise, returns <code>NULL</code>.
   5757   1.1  mbalmer 
   5758   1.1  mbalmer 
   5759   1.1  mbalmer 
   5760   1.1  mbalmer 
   5761   1.1  mbalmer 
   5762   1.1  mbalmer <hr><h3><a name="lua_type"><code>lua_type</code></a></h3><p>
   5763   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   5764   1.1  mbalmer <pre>int lua_type (lua_State *L, int index);</pre>
   5765   1.1  mbalmer 
   5766   1.1  mbalmer <p>
   5767   1.2    lneto Returns the type of the value in the given valid index,
   5768   1.9   nikita or <code>LUA_TNONE</code> for a non-valid but acceptable index.
   5769   1.1  mbalmer The types returned by <a href="#lua_type"><code>lua_type</code></a> are coded by the following constants
   5770   1.1  mbalmer defined in <code>lua.h</code>:
   5771   1.9   nikita <a name="pdf-LUA_TNIL"><code>LUA_TNIL</code></a>,
   5772   1.2    lneto <a name="pdf-LUA_TNUMBER"><code>LUA_TNUMBER</code></a>,
   5773   1.2    lneto <a name="pdf-LUA_TBOOLEAN"><code>LUA_TBOOLEAN</code></a>,
   5774   1.2    lneto <a name="pdf-LUA_TSTRING"><code>LUA_TSTRING</code></a>,
   5775   1.2    lneto <a name="pdf-LUA_TTABLE"><code>LUA_TTABLE</code></a>,
   5776   1.2    lneto <a name="pdf-LUA_TFUNCTION"><code>LUA_TFUNCTION</code></a>,
   5777   1.2    lneto <a name="pdf-LUA_TUSERDATA"><code>LUA_TUSERDATA</code></a>,
   5778   1.2    lneto <a name="pdf-LUA_TTHREAD"><code>LUA_TTHREAD</code></a>,
   5779   1.1  mbalmer and
   5780   1.2    lneto <a name="pdf-LUA_TLIGHTUSERDATA"><code>LUA_TLIGHTUSERDATA</code></a>.
   5781   1.1  mbalmer 
   5782   1.1  mbalmer 
   5783   1.1  mbalmer 
   5784   1.1  mbalmer 
   5785   1.1  mbalmer 
   5786   1.1  mbalmer <hr><h3><a name="lua_typename"><code>lua_typename</code></a></h3><p>
   5787   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   5788   1.2    lneto <pre>const char *lua_typename (lua_State *L, int tp);</pre>
   5789   1.1  mbalmer 
   5790   1.1  mbalmer <p>
   5791   1.1  mbalmer Returns the name of the type encoded by the value <code>tp</code>,
   5792   1.1  mbalmer which must be one the values returned by <a href="#lua_type"><code>lua_type</code></a>.
   5793   1.1  mbalmer 
   5794   1.1  mbalmer 
   5795   1.1  mbalmer 
   5796   1.1  mbalmer 
   5797   1.1  mbalmer 
   5798   1.2    lneto <hr><h3><a name="lua_Unsigned"><code>lua_Unsigned</code></a></h3>
   5799   1.2    lneto <pre>typedef ... lua_Unsigned;</pre>
   5800   1.2    lneto 
   5801   1.2    lneto <p>
   5802   1.2    lneto The unsigned version of <a href="#lua_Integer"><code>lua_Integer</code></a>.
   5803   1.2    lneto 
   5804   1.2    lneto 
   5805   1.2    lneto 
   5806   1.2    lneto 
   5807   1.2    lneto 
   5808   1.2    lneto <hr><h3><a name="lua_upvalueindex"><code>lua_upvalueindex</code></a></h3><p>
   5809   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   5810   1.2    lneto <pre>int lua_upvalueindex (int i);</pre>
   5811   1.2    lneto 
   5812   1.2    lneto <p>
   5813   1.2    lneto Returns the pseudo-index that represents the <code>i</code>-th upvalue of
   5814   1.9   nikita the running function (see <a href="#4.2">&sect;4.2</a>).
   5815   1.9   nikita <code>i</code> must be in the range <em>[1,256]</em>.
   5816   1.2    lneto 
   5817   1.2    lneto 
   5818   1.2    lneto 
   5819   1.2    lneto 
   5820   1.2    lneto 
   5821   1.2    lneto <hr><h3><a name="lua_version"><code>lua_version</code></a></h3><p>
   5822   1.6  salazar <span class="apii">[-0, +0, &ndash;]</span>
   5823   1.9   nikita <pre>lua_Number lua_version (lua_State *L);</pre>
   5824   1.9   nikita 
   5825   1.9   nikita <p>
   5826   1.9   nikita Returns the version number of this core.
   5827   1.9   nikita 
   5828   1.9   nikita 
   5829   1.9   nikita 
   5830   1.9   nikita 
   5831   1.9   nikita 
   5832   1.9   nikita <hr><h3><a name="lua_WarnFunction"><code>lua_WarnFunction</code></a></h3>
   5833   1.9   nikita <pre>typedef void (*lua_WarnFunction) (void *ud, const char *msg, int tocont);</pre>
   5834   1.9   nikita 
   5835   1.9   nikita <p>
   5836   1.9   nikita The type of warning functions, called by Lua to emit warnings.
   5837   1.9   nikita The first parameter is an opaque pointer
   5838   1.9   nikita set by <a href="#lua_setwarnf"><code>lua_setwarnf</code></a>.
   5839   1.9   nikita The second parameter is the warning message.
   5840   1.9   nikita The third parameter is a boolean that
   5841   1.9   nikita indicates whether the message is
   5842   1.9   nikita to be continued by the message in the next call.
   5843   1.9   nikita 
   5844   1.9   nikita 
   5845   1.9   nikita <p>
   5846   1.9   nikita See <a href="#pdf-warn"><code>warn</code></a> for more details about warnings.
   5847   1.9   nikita 
   5848   1.9   nikita 
   5849   1.9   nikita 
   5850   1.9   nikita 
   5851   1.9   nikita 
   5852   1.9   nikita <hr><h3><a name="lua_warning"><code>lua_warning</code></a></h3><p>
   5853   1.9   nikita <span class="apii">[-0, +0, &ndash;]</span>
   5854   1.9   nikita <pre>void lua_warning (lua_State *L, const char *msg, int tocont);</pre>
   5855   1.9   nikita 
   5856   1.9   nikita <p>
   5857   1.9   nikita Emits a warning with the given message.
   5858   1.9   nikita A message in a call with <code>tocont</code> true should be
   5859   1.9   nikita continued in another call to this function.
   5860   1.9   nikita 
   5861   1.2    lneto 
   5862   1.2    lneto <p>
   5863   1.9   nikita See <a href="#pdf-warn"><code>warn</code></a> for more details about warnings.
   5864   1.2    lneto 
   5865   1.2    lneto 
   5866   1.2    lneto 
   5867   1.2    lneto 
   5868   1.2    lneto 
   5869   1.1  mbalmer <hr><h3><a name="lua_Writer"><code>lua_Writer</code></a></h3>
   5870   1.1  mbalmer <pre>typedef int (*lua_Writer) (lua_State *L,
   5871   1.1  mbalmer                            const void* p,
   5872   1.1  mbalmer                            size_t sz,
   5873   1.1  mbalmer                            void* ud);</pre>
   5874   1.1  mbalmer 
   5875   1.1  mbalmer <p>
   5876   1.1  mbalmer The type of the writer function used by <a href="#lua_dump"><code>lua_dump</code></a>.
   5877   1.9   nikita Every time <a href="#lua_dump"><code>lua_dump</code></a> produces another piece of chunk,
   5878   1.9   nikita it calls the writer,
   5879   1.1  mbalmer passing along the buffer to be written (<code>p</code>),
   5880   1.1  mbalmer its size (<code>sz</code>),
   5881   1.9   nikita and the <code>ud</code> parameter supplied to <a href="#lua_dump"><code>lua_dump</code></a>.
   5882   1.1  mbalmer 
   5883   1.1  mbalmer 
   5884   1.1  mbalmer <p>
   5885   1.1  mbalmer The writer returns an error code:
   5886   1.1  mbalmer 0&nbsp;means no errors;
   5887   1.1  mbalmer any other value means an error and stops <a href="#lua_dump"><code>lua_dump</code></a> from
   5888   1.1  mbalmer calling the writer again.
   5889   1.1  mbalmer 
   5890   1.1  mbalmer 
   5891   1.1  mbalmer 
   5892   1.1  mbalmer 
   5893   1.1  mbalmer 
   5894   1.1  mbalmer <hr><h3><a name="lua_xmove"><code>lua_xmove</code></a></h3><p>
   5895   1.2    lneto <span class="apii">[-?, +?, &ndash;]</span>
   5896   1.1  mbalmer <pre>void lua_xmove (lua_State *from, lua_State *to, int n);</pre>
   5897   1.1  mbalmer 
   5898   1.1  mbalmer <p>
   5899   1.2    lneto Exchange values between different threads of the same state.
   5900   1.1  mbalmer 
   5901   1.1  mbalmer 
   5902   1.1  mbalmer <p>
   5903   1.1  mbalmer This function pops <code>n</code> values from the stack <code>from</code>,
   5904   1.1  mbalmer and pushes them onto the stack <code>to</code>.
   5905   1.1  mbalmer 
   5906   1.1  mbalmer 
   5907   1.1  mbalmer 
   5908   1.1  mbalmer 
   5909   1.1  mbalmer 
   5910   1.1  mbalmer <hr><h3><a name="lua_yield"><code>lua_yield</code></a></h3><p>
   5911   1.9   nikita <span class="apii">[-?, +?, <em>v</em>]</span>
   5912   1.2    lneto <pre>int lua_yield (lua_State *L, int nresults);</pre>
   5913   1.2    lneto 
   5914   1.2    lneto <p>
   5915   1.2    lneto This function is equivalent to <a href="#lua_yieldk"><code>lua_yieldk</code></a>,
   5916   1.9   nikita but it has no continuation (see <a href="#4.5">&sect;4.5</a>).
   5917   1.2    lneto Therefore, when the thread resumes,
   5918   1.3    lneto it continues the function that called
   5919   1.2    lneto the function calling <code>lua_yield</code>.
   5920   1.9   nikita To avoid surprises,
   5921   1.9   nikita this function should be called only in a tail call.
   5922   1.2    lneto 
   5923   1.2    lneto 
   5924   1.2    lneto 
   5925   1.2    lneto 
   5926   1.2    lneto 
   5927   1.2    lneto <hr><h3><a name="lua_yieldk"><code>lua_yieldk</code></a></h3><p>
   5928   1.9   nikita <span class="apii">[-?, +?, <em>v</em>]</span>
   5929   1.3    lneto <pre>int lua_yieldk (lua_State *L,
   5930   1.3    lneto                 int nresults,
   5931   1.3    lneto                 lua_KContext ctx,
   5932   1.3    lneto                 lua_KFunction k);</pre>
   5933   1.1  mbalmer 
   5934   1.1  mbalmer <p>
   5935   1.3    lneto Yields a coroutine (thread).
   5936   1.1  mbalmer 
   5937   1.1  mbalmer 
   5938   1.1  mbalmer <p>
   5939   1.3    lneto When a C&nbsp;function calls <a href="#lua_yieldk"><code>lua_yieldk</code></a>,
   5940   1.1  mbalmer the running coroutine suspends its execution,
   5941   1.1  mbalmer and the call to <a href="#lua_resume"><code>lua_resume</code></a> that started this coroutine returns.
   5942   1.1  mbalmer The parameter <code>nresults</code> is the number of values from the stack
   5943   1.2    lneto that will be passed as results to <a href="#lua_resume"><code>lua_resume</code></a>.
   5944   1.2    lneto 
   5945   1.2    lneto 
   5946   1.2    lneto <p>
   5947   1.2    lneto When the coroutine is resumed again,
   5948   1.2    lneto Lua calls the given continuation function <code>k</code> to continue
   5949   1.9   nikita the execution of the C&nbsp;function that yielded (see <a href="#4.5">&sect;4.5</a>).
   5950   1.2    lneto This continuation function receives the same stack
   5951   1.2    lneto from the previous function,
   5952   1.2    lneto with the <code>n</code> results removed and
   5953   1.2    lneto replaced by the arguments passed to <a href="#lua_resume"><code>lua_resume</code></a>.
   5954   1.2    lneto Moreover,
   5955   1.2    lneto the continuation function receives the value <code>ctx</code>
   5956   1.2    lneto that was passed to <a href="#lua_yieldk"><code>lua_yieldk</code></a>.
   5957   1.1  mbalmer 
   5958   1.1  mbalmer 
   5959   1.3    lneto <p>
   5960   1.3    lneto Usually, this function does not return;
   5961   1.3    lneto when the coroutine eventually resumes,
   5962   1.3    lneto it continues executing the continuation function.
   5963   1.3    lneto However, there is one special case,
   5964   1.3    lneto which is when this function is called
   5965   1.9   nikita from inside a line or a count hook (see <a href="#4.7">&sect;4.7</a>).
   5966   1.3    lneto In that case, <code>lua_yieldk</code> should be called with no continuation
   5967   1.6  salazar (probably in the form of <a href="#lua_yield"><code>lua_yield</code></a>) and no results,
   5968   1.3    lneto and the hook should return immediately after the call.
   5969   1.3    lneto Lua will yield and,
   5970   1.3    lneto when the coroutine resumes again,
   5971   1.3    lneto it will continue the normal execution
   5972   1.3    lneto of the (Lua) function that triggered the hook.
   5973   1.3    lneto 
   5974   1.3    lneto 
   5975   1.3    lneto <p>
   5976   1.3    lneto This function can raise an error if it is called from a thread
   5977   1.9   nikita with a pending C call with no continuation function
   5978   1.9   nikita (what is called a <em>C-call boundary</em>),
   5979   1.3    lneto or it is called from a thread that is not running inside a resume
   5980   1.9   nikita (typically the main thread).
   5981   1.3    lneto 
   5982   1.3    lneto 
   5983   1.1  mbalmer 
   5984   1.1  mbalmer 
   5985   1.1  mbalmer 
   5986   1.1  mbalmer 
   5987   1.1  mbalmer 
   5988   1.9   nikita <h2>4.7 &ndash; <a name="4.7">The Debug Interface</a></h2>
   5989   1.1  mbalmer 
   5990   1.1  mbalmer <p>
   5991   1.1  mbalmer Lua has no built-in debugging facilities.
   5992   1.1  mbalmer Instead, it offers a special interface
   5993   1.1  mbalmer by means of functions and <em>hooks</em>.
   5994   1.1  mbalmer This interface allows the construction of different
   5995   1.1  mbalmer kinds of debuggers, profilers, and other tools
   5996   1.1  mbalmer that need "inside information" from the interpreter.
   5997   1.1  mbalmer 
   5998   1.1  mbalmer 
   5999   1.1  mbalmer 
   6000   1.1  mbalmer <hr><h3><a name="lua_Debug"><code>lua_Debug</code></a></h3>
   6001   1.1  mbalmer <pre>typedef struct lua_Debug {
   6002   1.1  mbalmer   int event;
   6003   1.1  mbalmer   const char *name;           /* (n) */
   6004   1.1  mbalmer   const char *namewhat;       /* (n) */
   6005   1.1  mbalmer   const char *what;           /* (S) */
   6006   1.1  mbalmer   const char *source;         /* (S) */
   6007   1.9   nikita   size_t srclen;              /* (S) */
   6008   1.1  mbalmer   int currentline;            /* (l) */
   6009   1.1  mbalmer   int linedefined;            /* (S) */
   6010   1.1  mbalmer   int lastlinedefined;        /* (S) */
   6011   1.2    lneto   unsigned char nups;         /* (u) number of upvalues */
   6012   1.2    lneto   unsigned char nparams;      /* (u) number of parameters */
   6013   1.2    lneto   char isvararg;              /* (u) */
   6014   1.2    lneto   char istailcall;            /* (t) */
   6015   1.9   nikita   unsigned short ftransfer;   /* (r) index of first value transferred */
   6016   1.9   nikita   unsigned short ntransfer;   /* (r) number of transferred values */
   6017   1.1  mbalmer   char short_src[LUA_IDSIZE]; /* (S) */
   6018   1.1  mbalmer   /* private part */
   6019   1.1  mbalmer   <em>other fields</em>
   6020   1.1  mbalmer } lua_Debug;</pre>
   6021   1.1  mbalmer 
   6022   1.1  mbalmer <p>
   6023   1.1  mbalmer A structure used to carry different pieces of
   6024   1.2    lneto information about a function or an activation record.
   6025   1.1  mbalmer <a href="#lua_getstack"><code>lua_getstack</code></a> fills only the private part
   6026   1.1  mbalmer of this structure, for later use.
   6027   1.1  mbalmer To fill the other fields of <a href="#lua_Debug"><code>lua_Debug</code></a> with useful information,
   6028   1.9   nikita you must call <a href="#lua_getinfo"><code>lua_getinfo</code></a> with an appropriate parameter.
   6029   1.9   nikita (Specifically, to get a field,
   6030   1.9   nikita you must add the letter between parentheses in the field's comment
   6031   1.9   nikita to the parameter <code>what</code> of <a href="#lua_getinfo"><code>lua_getinfo</code></a>.)
   6032   1.1  mbalmer 
   6033   1.1  mbalmer 
   6034   1.1  mbalmer <p>
   6035   1.1  mbalmer The fields of <a href="#lua_Debug"><code>lua_Debug</code></a> have the following meaning:
   6036   1.1  mbalmer 
   6037   1.1  mbalmer <ul>
   6038   1.1  mbalmer 
   6039   1.2    lneto <li><b><code>source</code>: </b>
   6040   1.9   nikita the source of the chunk that created the function.
   6041   1.2    lneto If <code>source</code> starts with a '<code>@</code>',
   6042   1.2    lneto it means that the function was defined in a file where
   6043   1.2    lneto the file name follows the '<code>@</code>'.
   6044   1.2    lneto If <code>source</code> starts with a '<code>=</code>',
   6045   1.9   nikita the remainder of its contents describes the source in a user-dependent manner.
   6046   1.2    lneto Otherwise,
   6047   1.2    lneto the function was defined in a string where
   6048   1.2    lneto <code>source</code> is that string.
   6049   1.1  mbalmer </li>
   6050   1.1  mbalmer 
   6051   1.9   nikita <li><b><code>srclen</code>: </b>
   6052   1.9   nikita The length of the string <code>source</code>.
   6053   1.9   nikita </li>
   6054   1.9   nikita 
   6055   1.2    lneto <li><b><code>short_src</code>: </b>
   6056   1.1  mbalmer a "printable" version of <code>source</code>, to be used in error messages.
   6057   1.1  mbalmer </li>
   6058   1.1  mbalmer 
   6059   1.2    lneto <li><b><code>linedefined</code>: </b>
   6060   1.1  mbalmer the line number where the definition of the function starts.
   6061   1.1  mbalmer </li>
   6062   1.1  mbalmer 
   6063   1.2    lneto <li><b><code>lastlinedefined</code>: </b>
   6064   1.1  mbalmer the line number where the definition of the function ends.
   6065   1.1  mbalmer </li>
   6066   1.1  mbalmer 
   6067   1.2    lneto <li><b><code>what</code>: </b>
   6068   1.1  mbalmer the string <code>"Lua"</code> if the function is a Lua function,
   6069   1.1  mbalmer <code>"C"</code> if it is a C&nbsp;function,
   6070   1.2    lneto <code>"main"</code> if it is the main part of a chunk.
   6071   1.1  mbalmer </li>
   6072   1.1  mbalmer 
   6073   1.2    lneto <li><b><code>currentline</code>: </b>
   6074   1.1  mbalmer the current line where the given function is executing.
   6075   1.1  mbalmer When no line information is available,
   6076   1.1  mbalmer <code>currentline</code> is set to -1.
   6077   1.1  mbalmer </li>
   6078   1.1  mbalmer 
   6079   1.2    lneto <li><b><code>name</code>: </b>
   6080   1.1  mbalmer a reasonable name for the given function.
   6081   1.1  mbalmer Because functions in Lua are first-class values,
   6082   1.1  mbalmer they do not have a fixed name:
   6083   1.1  mbalmer some functions can be the value of multiple global variables,
   6084   1.1  mbalmer while others can be stored only in a table field.
   6085   1.1  mbalmer The <code>lua_getinfo</code> function checks how the function was
   6086   1.1  mbalmer called to find a suitable name.
   6087   1.1  mbalmer If it cannot find a name,
   6088   1.1  mbalmer then <code>name</code> is set to <code>NULL</code>.
   6089   1.1  mbalmer </li>
   6090   1.1  mbalmer 
   6091   1.2    lneto <li><b><code>namewhat</code>: </b>
   6092   1.1  mbalmer explains the <code>name</code> field.
   6093   1.1  mbalmer The value of <code>namewhat</code> can be
   6094   1.1  mbalmer <code>"global"</code>, <code>"local"</code>, <code>"method"</code>,
   6095   1.1  mbalmer <code>"field"</code>, <code>"upvalue"</code>, or <code>""</code> (the empty string),
   6096   1.1  mbalmer according to how the function was called.
   6097   1.1  mbalmer (Lua uses the empty string when no other option seems to apply.)
   6098   1.1  mbalmer </li>
   6099   1.1  mbalmer 
   6100   1.2    lneto <li><b><code>istailcall</code>: </b>
   6101   1.2    lneto true if this function invocation was called by a tail call.
   6102   1.2    lneto In this case, the caller of this level is not in the stack.
   6103   1.2    lneto </li>
   6104   1.2    lneto 
   6105   1.2    lneto <li><b><code>nups</code>: </b>
   6106   1.1  mbalmer the number of upvalues of the function.
   6107   1.1  mbalmer </li>
   6108   1.1  mbalmer 
   6109   1.2    lneto <li><b><code>nparams</code>: </b>
   6110   1.9   nikita the number of parameters of the function
   6111   1.2    lneto (always 0&nbsp;for C&nbsp;functions).
   6112   1.2    lneto </li>
   6113   1.2    lneto 
   6114   1.2    lneto <li><b><code>isvararg</code>: </b>
   6115  1.10   nikita true if the function is a variadic function
   6116   1.2    lneto (always true for C&nbsp;functions).
   6117   1.2    lneto </li>
   6118   1.2    lneto 
   6119   1.9   nikita <li><b><code>ftransfer</code>: </b>
   6120   1.9   nikita the index in the stack of the first value being "transferred",
   6121   1.9   nikita that is, parameters in a call or return values in a return.
   6122   1.9   nikita (The other values are in consecutive indices.)
   6123   1.9   nikita Using this index, you can access and modify these values
   6124   1.9   nikita through <a href="#lua_getlocal"><code>lua_getlocal</code></a> and <a href="#lua_setlocal"><code>lua_setlocal</code></a>.
   6125   1.9   nikita This field is only meaningful during a
   6126   1.9   nikita call hook, denoting the first parameter,
   6127   1.9   nikita or a return hook, denoting the first value being returned.
   6128   1.9   nikita (For call hooks, this value is always 1.)
   6129   1.9   nikita </li>
   6130   1.9   nikita 
   6131   1.9   nikita <li><b><code>ntransfer</code>: </b>
   6132   1.9   nikita The number of values being transferred (see previous item).
   6133   1.9   nikita (For calls of Lua functions,
   6134   1.9   nikita this value is always equal to <code>nparams</code>.)
   6135   1.9   nikita </li>
   6136   1.9   nikita 
   6137   1.1  mbalmer </ul>
   6138   1.1  mbalmer 
   6139   1.1  mbalmer 
   6140   1.1  mbalmer 
   6141   1.1  mbalmer 
   6142   1.1  mbalmer <hr><h3><a name="lua_gethook"><code>lua_gethook</code></a></h3><p>
   6143   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   6144   1.1  mbalmer <pre>lua_Hook lua_gethook (lua_State *L);</pre>
   6145   1.1  mbalmer 
   6146   1.1  mbalmer <p>
   6147   1.1  mbalmer Returns the current hook function.
   6148   1.1  mbalmer 
   6149   1.1  mbalmer 
   6150   1.1  mbalmer 
   6151   1.1  mbalmer 
   6152   1.1  mbalmer 
   6153   1.1  mbalmer <hr><h3><a name="lua_gethookcount"><code>lua_gethookcount</code></a></h3><p>
   6154   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   6155   1.1  mbalmer <pre>int lua_gethookcount (lua_State *L);</pre>
   6156   1.1  mbalmer 
   6157   1.1  mbalmer <p>
   6158   1.1  mbalmer Returns the current hook count.
   6159   1.1  mbalmer 
   6160   1.1  mbalmer 
   6161   1.1  mbalmer 
   6162   1.1  mbalmer 
   6163   1.1  mbalmer 
   6164   1.1  mbalmer <hr><h3><a name="lua_gethookmask"><code>lua_gethookmask</code></a></h3><p>
   6165   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   6166   1.1  mbalmer <pre>int lua_gethookmask (lua_State *L);</pre>
   6167   1.1  mbalmer 
   6168   1.1  mbalmer <p>
   6169   1.1  mbalmer Returns the current hook mask.
   6170   1.1  mbalmer 
   6171   1.1  mbalmer 
   6172   1.1  mbalmer 
   6173   1.1  mbalmer 
   6174   1.1  mbalmer 
   6175   1.1  mbalmer <hr><h3><a name="lua_getinfo"><code>lua_getinfo</code></a></h3><p>
   6176   1.9   nikita <span class="apii">[-(0|1), +(0|1|2), <em>m</em>]</span>
   6177   1.1  mbalmer <pre>int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar);</pre>
   6178   1.1  mbalmer 
   6179   1.1  mbalmer <p>
   6180   1.2    lneto Gets information about a specific function or function invocation.
   6181   1.1  mbalmer 
   6182   1.1  mbalmer 
   6183   1.1  mbalmer <p>
   6184   1.1  mbalmer To get information about a function invocation,
   6185   1.1  mbalmer the parameter <code>ar</code> must be a valid activation record that was
   6186   1.1  mbalmer filled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or
   6187   1.1  mbalmer given as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>).
   6188   1.1  mbalmer 
   6189   1.1  mbalmer 
   6190   1.1  mbalmer <p>
   6191   1.8    alnsn To get information about a function, you push it onto the stack
   6192   1.1  mbalmer and start the <code>what</code> string with the character '<code>&gt;</code>'.
   6193   1.1  mbalmer (In that case,
   6194   1.2    lneto <code>lua_getinfo</code> pops the function from the top of the stack.)
   6195   1.1  mbalmer For instance, to know in which line a function <code>f</code> was defined,
   6196   1.1  mbalmer you can write the following code:
   6197   1.1  mbalmer 
   6198   1.1  mbalmer <pre>
   6199   1.1  mbalmer      lua_Debug ar;
   6200   1.2    lneto      lua_getglobal(L, "f");  /* get global 'f' */
   6201   1.1  mbalmer      lua_getinfo(L, "&gt;S", &amp;ar);
   6202   1.1  mbalmer      printf("%d\n", ar.linedefined);
   6203   1.1  mbalmer </pre>
   6204   1.1  mbalmer 
   6205   1.1  mbalmer <p>
   6206   1.1  mbalmer Each character in the string <code>what</code>
   6207   1.1  mbalmer selects some fields of the structure <code>ar</code> to be filled or
   6208   1.9   nikita a value to be pushed on the stack.
   6209   1.9   nikita (These characters are also documented in the declaration of
   6210   1.9   nikita the structure <a href="#lua_Debug"><code>lua_Debug</code></a>,
   6211   1.9   nikita between parentheses in the comments following each field.)
   6212   1.1  mbalmer 
   6213   1.1  mbalmer <ul>
   6214   1.1  mbalmer 
   6215   1.9   nikita <li><b>'<code>f</code>': </b>
   6216   1.9   nikita pushes onto the stack the function that is
   6217   1.9   nikita running at the given level;
   6218   1.9   nikita </li>
   6219   1.9   nikita 
   6220   1.9   nikita <li><b>'<code>l</code>': </b> fills in the field <code>currentline</code>;
   6221   1.9   nikita </li>
   6222   1.9   nikita 
   6223   1.9   nikita <li><b>'<code>n</code>': </b> fills in the fields <code>name</code> and <code>namewhat</code>;
   6224   1.9   nikita </li>
   6225   1.9   nikita 
   6226   1.9   nikita <li><b>'<code>r</code>': </b> fills in the fields <code>ftransfer</code> and <code>ntransfer</code>;
   6227   1.1  mbalmer </li>
   6228   1.1  mbalmer 
   6229   1.2    lneto <li><b>'<code>S</code>': </b>
   6230   1.1  mbalmer fills in the fields <code>source</code>, <code>short_src</code>,
   6231   1.1  mbalmer <code>linedefined</code>, <code>lastlinedefined</code>, and <code>what</code>;
   6232   1.1  mbalmer </li>
   6233   1.1  mbalmer 
   6234   1.2    lneto <li><b>'<code>t</code>': </b> fills in the field <code>istailcall</code>;
   6235   1.1  mbalmer </li>
   6236   1.1  mbalmer 
   6237   1.2    lneto <li><b>'<code>u</code>': </b> fills in the fields
   6238   1.2    lneto <code>nups</code>, <code>nparams</code>, and <code>isvararg</code>;
   6239   1.1  mbalmer </li>
   6240   1.1  mbalmer 
   6241   1.2    lneto <li><b>'<code>L</code>': </b>
   6242   1.9   nikita pushes onto the stack a table whose indices are
   6243   1.9   nikita the lines on the function with some associated code,
   6244   1.9   nikita that is, the lines where you can put a break point.
   6245   1.9   nikita (Lines with no code include empty lines and comments.)
   6246   1.2    lneto If this option is given together with option '<code>f</code>',
   6247   1.2    lneto its table is pushed after the function.
   6248   1.9   nikita This is the only option that can raise a memory error.
   6249   1.1  mbalmer </li>
   6250   1.1  mbalmer 
   6251   1.1  mbalmer </ul>
   6252   1.1  mbalmer 
   6253   1.1  mbalmer <p>
   6254   1.9   nikita This function returns 0 to signal an invalid option in <code>what</code>;
   6255   1.9   nikita even then the valid options are handled correctly.
   6256   1.1  mbalmer 
   6257   1.1  mbalmer 
   6258   1.1  mbalmer 
   6259   1.1  mbalmer 
   6260   1.1  mbalmer 
   6261   1.1  mbalmer <hr><h3><a name="lua_getlocal"><code>lua_getlocal</code></a></h3><p>
   6262   1.2    lneto <span class="apii">[-0, +(0|1), &ndash;]</span>
   6263   1.3    lneto <pre>const char *lua_getlocal (lua_State *L, const lua_Debug *ar, int n);</pre>
   6264   1.1  mbalmer 
   6265   1.1  mbalmer <p>
   6266   1.9   nikita Gets information about a local variable or a temporary value
   6267   1.9   nikita of a given activation record or a given function.
   6268   1.2    lneto 
   6269   1.2    lneto 
   6270   1.2    lneto <p>
   6271   1.2    lneto In the first case,
   6272   1.2    lneto the parameter <code>ar</code> must be a valid activation record that was
   6273   1.1  mbalmer filled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or
   6274   1.1  mbalmer given as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>).
   6275   1.2    lneto The index <code>n</code> selects which local variable to inspect;
   6276   1.2    lneto see <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for details about variable indices
   6277   1.2    lneto and names.
   6278   1.2    lneto 
   6279   1.2    lneto 
   6280   1.2    lneto <p>
   6281   1.1  mbalmer <a href="#lua_getlocal"><code>lua_getlocal</code></a> pushes the variable's value onto the stack
   6282   1.1  mbalmer and returns its name.
   6283   1.1  mbalmer 
   6284   1.1  mbalmer 
   6285   1.1  mbalmer <p>
   6286   1.2    lneto In the second case, <code>ar</code> must be <code>NULL</code> and the function
   6287   1.9   nikita to be inspected must be on the top of the stack.
   6288   1.2    lneto In this case, only parameters of Lua functions are visible
   6289   1.2    lneto (as there is no information about what variables are active)
   6290   1.2    lneto and no values are pushed onto the stack.
   6291   1.1  mbalmer 
   6292   1.1  mbalmer 
   6293   1.1  mbalmer <p>
   6294   1.1  mbalmer Returns <code>NULL</code> (and pushes nothing)
   6295   1.1  mbalmer when the index is greater than
   6296   1.1  mbalmer the number of active local variables.
   6297   1.1  mbalmer 
   6298   1.1  mbalmer 
   6299   1.1  mbalmer 
   6300   1.1  mbalmer 
   6301   1.1  mbalmer 
   6302   1.1  mbalmer <hr><h3><a name="lua_getstack"><code>lua_getstack</code></a></h3><p>
   6303   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   6304   1.1  mbalmer <pre>int lua_getstack (lua_State *L, int level, lua_Debug *ar);</pre>
   6305   1.1  mbalmer 
   6306   1.1  mbalmer <p>
   6307   1.2    lneto Gets information about the interpreter runtime stack.
   6308   1.1  mbalmer 
   6309   1.1  mbalmer 
   6310   1.1  mbalmer <p>
   6311   1.1  mbalmer This function fills parts of a <a href="#lua_Debug"><code>lua_Debug</code></a> structure with
   6312   1.1  mbalmer an identification of the <em>activation record</em>
   6313   1.1  mbalmer of the function executing at a given level.
   6314   1.1  mbalmer Level&nbsp;0 is the current running function,
   6315   1.2    lneto whereas level <em>n+1</em> is the function that has called level <em>n</em>
   6316   1.9   nikita (except for tail calls, which do not count in the stack).
   6317   1.9   nikita When called with a level greater than the stack depth,
   6318   1.9   nikita <a href="#lua_getstack"><code>lua_getstack</code></a> returns 0;
   6319   1.9   nikita otherwise it returns 1.
   6320   1.1  mbalmer 
   6321   1.1  mbalmer 
   6322   1.1  mbalmer 
   6323   1.1  mbalmer 
   6324   1.1  mbalmer 
   6325   1.1  mbalmer <hr><h3><a name="lua_getupvalue"><code>lua_getupvalue</code></a></h3><p>
   6326   1.2    lneto <span class="apii">[-0, +(0|1), &ndash;]</span>
   6327   1.1  mbalmer <pre>const char *lua_getupvalue (lua_State *L, int funcindex, int n);</pre>
   6328   1.1  mbalmer 
   6329   1.1  mbalmer <p>
   6330   1.4  mbalmer Gets information about the <code>n</code>-th upvalue
   6331   1.4  mbalmer of the closure at index <code>funcindex</code>.
   6332   1.4  mbalmer It pushes the upvalue's value onto the stack
   6333   1.4  mbalmer and returns its name.
   6334   1.4  mbalmer Returns <code>NULL</code> (and pushes nothing)
   6335   1.4  mbalmer when the index <code>n</code> is greater than the number of upvalues.
   6336   1.4  mbalmer 
   6337   1.4  mbalmer 
   6338   1.4  mbalmer <p>
   6339   1.9   nikita See <a href="#pdf-debug.getupvalue"><code>debug.getupvalue</code></a> for more information about upvalues.
   6340   1.1  mbalmer 
   6341   1.1  mbalmer 
   6342   1.1  mbalmer 
   6343   1.1  mbalmer 
   6344   1.1  mbalmer 
   6345   1.1  mbalmer <hr><h3><a name="lua_Hook"><code>lua_Hook</code></a></h3>
   6346   1.1  mbalmer <pre>typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar);</pre>
   6347   1.1  mbalmer 
   6348   1.1  mbalmer <p>
   6349   1.1  mbalmer Type for debugging hook functions.
   6350   1.1  mbalmer 
   6351   1.1  mbalmer 
   6352   1.1  mbalmer <p>
   6353   1.1  mbalmer Whenever a hook is called, its <code>ar</code> argument has its field
   6354   1.1  mbalmer <code>event</code> set to the specific event that triggered the hook.
   6355   1.1  mbalmer Lua identifies these events with the following constants:
   6356   1.1  mbalmer <a name="pdf-LUA_HOOKCALL"><code>LUA_HOOKCALL</code></a>, <a name="pdf-LUA_HOOKRET"><code>LUA_HOOKRET</code></a>,
   6357   1.2    lneto <a name="pdf-LUA_HOOKTAILCALL"><code>LUA_HOOKTAILCALL</code></a>, <a name="pdf-LUA_HOOKLINE"><code>LUA_HOOKLINE</code></a>,
   6358   1.1  mbalmer and <a name="pdf-LUA_HOOKCOUNT"><code>LUA_HOOKCOUNT</code></a>.
   6359   1.1  mbalmer Moreover, for line events, the field <code>currentline</code> is also set.
   6360   1.1  mbalmer To get the value of any other field in <code>ar</code>,
   6361   1.1  mbalmer the hook must call <a href="#lua_getinfo"><code>lua_getinfo</code></a>.
   6362   1.2    lneto 
   6363   1.2    lneto 
   6364   1.2    lneto <p>
   6365   1.2    lneto For call events, <code>event</code> can be <code>LUA_HOOKCALL</code>,
   6366   1.2    lneto the normal value, or <code>LUA_HOOKTAILCALL</code>, for a tail call;
   6367   1.2    lneto in this case, there will be no corresponding return event.
   6368   1.1  mbalmer 
   6369   1.1  mbalmer 
   6370   1.1  mbalmer <p>
   6371   1.1  mbalmer While Lua is running a hook, it disables other calls to hooks.
   6372   1.1  mbalmer Therefore, if a hook calls back Lua to execute a function or a chunk,
   6373   1.1  mbalmer this execution occurs without any calls to hooks.
   6374   1.1  mbalmer 
   6375   1.1  mbalmer 
   6376   1.2    lneto <p>
   6377   1.2    lneto Hook functions cannot have continuations,
   6378   1.2    lneto that is, they cannot call <a href="#lua_yieldk"><code>lua_yieldk</code></a>,
   6379   1.2    lneto <a href="#lua_pcallk"><code>lua_pcallk</code></a>, or <a href="#lua_callk"><code>lua_callk</code></a> with a non-null <code>k</code>.
   6380   1.2    lneto 
   6381   1.2    lneto 
   6382   1.2    lneto <p>
   6383   1.2    lneto Hook functions can yield under the following conditions:
   6384   1.4  mbalmer Only count and line events can yield;
   6385   1.4  mbalmer to yield, a hook function must finish its execution
   6386   1.4  mbalmer calling <a href="#lua_yield"><code>lua_yield</code></a> with <code>nresults</code> equal to zero
   6387   1.4  mbalmer (that is, with no values).
   6388   1.2    lneto 
   6389   1.2    lneto 
   6390   1.1  mbalmer 
   6391   1.1  mbalmer 
   6392   1.1  mbalmer 
   6393   1.1  mbalmer <hr><h3><a name="lua_sethook"><code>lua_sethook</code></a></h3><p>
   6394   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   6395   1.2    lneto <pre>void lua_sethook (lua_State *L, lua_Hook f, int mask, int count);</pre>
   6396   1.1  mbalmer 
   6397   1.1  mbalmer <p>
   6398   1.1  mbalmer Sets the debugging hook function.
   6399   1.1  mbalmer 
   6400   1.1  mbalmer 
   6401   1.1  mbalmer <p>
   6402   1.1  mbalmer Argument <code>f</code> is the hook function.
   6403   1.1  mbalmer <code>mask</code> specifies on which events the hook will be called:
   6404   1.6  salazar it is formed by a bitwise OR of the constants
   6405   1.1  mbalmer <a name="pdf-LUA_MASKCALL"><code>LUA_MASKCALL</code></a>,
   6406   1.1  mbalmer <a name="pdf-LUA_MASKRET"><code>LUA_MASKRET</code></a>,
   6407   1.1  mbalmer <a name="pdf-LUA_MASKLINE"><code>LUA_MASKLINE</code></a>,
   6408   1.1  mbalmer and <a name="pdf-LUA_MASKCOUNT"><code>LUA_MASKCOUNT</code></a>.
   6409   1.1  mbalmer The <code>count</code> argument is only meaningful when the mask
   6410   1.1  mbalmer includes <code>LUA_MASKCOUNT</code>.
   6411   1.1  mbalmer For each event, the hook is called as explained below:
   6412   1.1  mbalmer 
   6413   1.1  mbalmer <ul>
   6414   1.1  mbalmer 
   6415   1.2    lneto <li><b>The call hook: </b> is called when the interpreter calls a function.
   6416   1.9   nikita The hook is called just after Lua enters the new function.
   6417   1.1  mbalmer </li>
   6418   1.1  mbalmer 
   6419   1.2    lneto <li><b>The return hook: </b> is called when the interpreter returns from a function.
   6420   1.1  mbalmer The hook is called just before Lua leaves the function.
   6421   1.1  mbalmer </li>
   6422   1.1  mbalmer 
   6423   1.2    lneto <li><b>The line hook: </b> is called when the interpreter is about to
   6424   1.1  mbalmer start the execution of a new line of code,
   6425   1.1  mbalmer or when it jumps back in the code (even to the same line).
   6426   1.9   nikita This event only happens while Lua is executing a Lua function.
   6427   1.1  mbalmer </li>
   6428   1.1  mbalmer 
   6429   1.2    lneto <li><b>The count hook: </b> is called after the interpreter executes every
   6430   1.1  mbalmer <code>count</code> instructions.
   6431   1.9   nikita This event only happens while Lua is executing a Lua function.
   6432   1.1  mbalmer </li>
   6433   1.1  mbalmer 
   6434   1.1  mbalmer </ul>
   6435   1.1  mbalmer 
   6436   1.1  mbalmer <p>
   6437   1.9   nikita Hooks are disabled by setting <code>mask</code> to zero.
   6438   1.1  mbalmer 
   6439   1.1  mbalmer 
   6440   1.1  mbalmer 
   6441   1.1  mbalmer 
   6442   1.1  mbalmer 
   6443   1.1  mbalmer <hr><h3><a name="lua_setlocal"><code>lua_setlocal</code></a></h3><p>
   6444   1.2    lneto <span class="apii">[-(0|1), +0, &ndash;]</span>
   6445   1.3    lneto <pre>const char *lua_setlocal (lua_State *L, const lua_Debug *ar, int n);</pre>
   6446   1.1  mbalmer 
   6447   1.1  mbalmer <p>
   6448   1.1  mbalmer Sets the value of a local variable of a given activation record.
   6449   1.9   nikita It assigns the value on the top of the stack
   6450   1.1  mbalmer to the variable and returns its name.
   6451   1.1  mbalmer It also pops the value from the stack.
   6452   1.1  mbalmer 
   6453   1.1  mbalmer 
   6454   1.1  mbalmer <p>
   6455   1.1  mbalmer Returns <code>NULL</code> (and pops nothing)
   6456   1.1  mbalmer when the index is greater than
   6457   1.1  mbalmer the number of active local variables.
   6458   1.1  mbalmer 
   6459   1.1  mbalmer 
   6460   1.4  mbalmer <p>
   6461   1.9   nikita Parameters <code>ar</code> and <code>n</code> are as in the function <a href="#lua_getlocal"><code>lua_getlocal</code></a>.
   6462   1.4  mbalmer 
   6463   1.4  mbalmer 
   6464   1.1  mbalmer 
   6465   1.1  mbalmer 
   6466   1.1  mbalmer 
   6467   1.1  mbalmer <hr><h3><a name="lua_setupvalue"><code>lua_setupvalue</code></a></h3><p>
   6468   1.2    lneto <span class="apii">[-(0|1), +0, &ndash;]</span>
   6469   1.1  mbalmer <pre>const char *lua_setupvalue (lua_State *L, int funcindex, int n);</pre>
   6470   1.1  mbalmer 
   6471   1.1  mbalmer <p>
   6472   1.1  mbalmer Sets the value of a closure's upvalue.
   6473   1.9   nikita It assigns the value on the top of the stack
   6474   1.1  mbalmer to the upvalue and returns its name.
   6475   1.1  mbalmer It also pops the value from the stack.
   6476   1.1  mbalmer 
   6477   1.1  mbalmer 
   6478   1.1  mbalmer <p>
   6479   1.1  mbalmer Returns <code>NULL</code> (and pops nothing)
   6480   1.4  mbalmer when the index <code>n</code> is greater than the number of upvalues.
   6481   1.4  mbalmer 
   6482   1.4  mbalmer 
   6483   1.4  mbalmer <p>
   6484   1.9   nikita Parameters <code>funcindex</code> and <code>n</code> are as in
   6485   1.9   nikita the function <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>.
   6486   1.1  mbalmer 
   6487   1.1  mbalmer 
   6488   1.1  mbalmer 
   6489   1.1  mbalmer 
   6490   1.1  mbalmer 
   6491   1.2    lneto <hr><h3><a name="lua_upvalueid"><code>lua_upvalueid</code></a></h3><p>
   6492   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   6493   1.2    lneto <pre>void *lua_upvalueid (lua_State *L, int funcindex, int n);</pre>
   6494   1.2    lneto 
   6495   1.2    lneto <p>
   6496   1.3    lneto Returns a unique identifier for the upvalue numbered <code>n</code>
   6497   1.2    lneto from the closure at index <code>funcindex</code>.
   6498   1.2    lneto 
   6499   1.2    lneto 
   6500   1.2    lneto <p>
   6501   1.2    lneto These unique identifiers allow a program to check whether different
   6502   1.2    lneto closures share upvalues.
   6503   1.2    lneto Lua closures that share an upvalue
   6504   1.2    lneto (that is, that access a same external local variable)
   6505   1.2    lneto will return identical ids for those upvalue indices.
   6506   1.2    lneto 
   6507   1.2    lneto 
   6508   1.4  mbalmer <p>
   6509   1.9   nikita Parameters <code>funcindex</code> and <code>n</code> are as in
   6510   1.9   nikita the function <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>,
   6511   1.4  mbalmer but <code>n</code> cannot be greater than the number of upvalues.
   6512   1.4  mbalmer 
   6513   1.4  mbalmer 
   6514   1.2    lneto 
   6515   1.2    lneto 
   6516   1.2    lneto 
   6517   1.2    lneto <hr><h3><a name="lua_upvaluejoin"><code>lua_upvaluejoin</code></a></h3><p>
   6518   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   6519   1.2    lneto <pre>void lua_upvaluejoin (lua_State *L, int funcindex1, int n1,
   6520   1.2    lneto                                     int funcindex2, int n2);</pre>
   6521   1.2    lneto 
   6522   1.2    lneto <p>
   6523   1.2    lneto Make the <code>n1</code>-th upvalue of the Lua closure at index <code>funcindex1</code>
   6524   1.2    lneto refer to the <code>n2</code>-th upvalue of the Lua closure at index <code>funcindex2</code>.
   6525   1.2    lneto 
   6526   1.2    lneto 
   6527   1.2    lneto 
   6528   1.2    lneto 
   6529   1.2    lneto 
   6530   1.1  mbalmer 
   6531   1.1  mbalmer 
   6532   1.2    lneto <h1>5 &ndash; <a name="5">The Auxiliary Library</a></h1>
   6533   1.1  mbalmer 
   6534   1.9   nikita 
   6535   1.9   nikita 
   6536   1.1  mbalmer <p>
   6537   1.1  mbalmer 
   6538   1.1  mbalmer The <em>auxiliary library</em> provides several convenient functions
   6539   1.1  mbalmer to interface C with Lua.
   6540   1.2    lneto While the basic API provides the primitive functions for all
   6541   1.1  mbalmer interactions between C and Lua,
   6542   1.1  mbalmer the auxiliary library provides higher-level functions for some
   6543   1.1  mbalmer common tasks.
   6544   1.1  mbalmer 
   6545   1.1  mbalmer 
   6546   1.1  mbalmer <p>
   6547   1.2    lneto All functions and types from the auxiliary library
   6548   1.1  mbalmer are defined in header file <code>lauxlib.h</code> and
   6549   1.1  mbalmer have a prefix <code>luaL_</code>.
   6550   1.1  mbalmer 
   6551   1.1  mbalmer 
   6552   1.1  mbalmer <p>
   6553   1.1  mbalmer All functions in the auxiliary library are built on
   6554   1.1  mbalmer top of the basic API,
   6555   1.2    lneto and so they provide nothing that cannot be done with that API.
   6556   1.2    lneto Nevertheless, the use of the auxiliary library ensures
   6557   1.2    lneto more consistency to your code.
   6558   1.2    lneto 
   6559   1.2    lneto 
   6560   1.2    lneto <p>
   6561   1.2    lneto Several functions in the auxiliary library use internally some
   6562   1.2    lneto extra stack slots.
   6563   1.2    lneto When a function in the auxiliary library uses less than five slots,
   6564   1.2    lneto it does not check the stack size;
   6565   1.2    lneto it simply assumes that there are enough slots.
   6566   1.1  mbalmer 
   6567   1.1  mbalmer 
   6568   1.1  mbalmer <p>
   6569   1.1  mbalmer Several functions in the auxiliary library are used to
   6570   1.1  mbalmer check C&nbsp;function arguments.
   6571   1.1  mbalmer Because the error message is formatted for arguments
   6572   1.1  mbalmer (e.g., "<code>bad argument #1</code>"),
   6573   1.1  mbalmer you should not use these functions for other stack values.
   6574   1.1  mbalmer 
   6575   1.1  mbalmer 
   6576   1.2    lneto <p>
   6577   1.2    lneto Functions called <code>luaL_check*</code>
   6578   1.2    lneto always raise an error if the check is not satisfied.
   6579   1.2    lneto 
   6580   1.2    lneto 
   6581   1.1  mbalmer 
   6582   1.9   nikita 
   6583   1.9   nikita 
   6584   1.2    lneto <h2>5.1 &ndash; <a name="5.1">Functions and Types</a></h2>
   6585   1.1  mbalmer 
   6586   1.1  mbalmer <p>
   6587   1.1  mbalmer Here we list all functions and types from the auxiliary library
   6588   1.1  mbalmer in alphabetical order.
   6589   1.1  mbalmer 
   6590   1.1  mbalmer 
   6591   1.1  mbalmer 
   6592   1.1  mbalmer <hr><h3><a name="luaL_addchar"><code>luaL_addchar</code></a></h3><p>
   6593   1.5    lneto <span class="apii">[-?, +?, <em>m</em>]</span>
   6594   1.1  mbalmer <pre>void luaL_addchar (luaL_Buffer *B, char c);</pre>
   6595   1.1  mbalmer 
   6596   1.1  mbalmer <p>
   6597   1.2    lneto Adds the byte <code>c</code> to the buffer <code>B</code>
   6598   1.1  mbalmer (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
   6599   1.1  mbalmer 
   6600   1.1  mbalmer 
   6601   1.1  mbalmer 
   6602   1.1  mbalmer 
   6603   1.1  mbalmer 
   6604   1.9   nikita <hr><h3><a name="luaL_addgsub"><code>luaL_addgsub</code></a></h3><p>
   6605   1.9   nikita <span class="apii">[-?, +?, <em>m</em>]</span>
   6606   1.9   nikita <pre>const void luaL_addgsub (luaL_Buffer *B, const char *s,
   6607   1.9   nikita                          const char *p, const char *r);</pre>
   6608   1.9   nikita 
   6609   1.9   nikita <p>
   6610   1.9   nikita Adds a copy of the string <code>s</code> to the buffer <code>B</code> (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>),
   6611   1.9   nikita replacing any occurrence of the string <code>p</code>
   6612   1.9   nikita with the string <code>r</code>.
   6613   1.9   nikita 
   6614   1.9   nikita 
   6615   1.9   nikita 
   6616   1.9   nikita 
   6617   1.9   nikita 
   6618   1.1  mbalmer <hr><h3><a name="luaL_addlstring"><code>luaL_addlstring</code></a></h3><p>
   6619   1.5    lneto <span class="apii">[-?, +?, <em>m</em>]</span>
   6620   1.1  mbalmer <pre>void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l);</pre>
   6621   1.1  mbalmer 
   6622   1.1  mbalmer <p>
   6623   1.1  mbalmer Adds the string pointed to by <code>s</code> with length <code>l</code> to
   6624   1.1  mbalmer the buffer <code>B</code>
   6625   1.1  mbalmer (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
   6626   1.2    lneto The string can contain embedded zeros.
   6627   1.1  mbalmer 
   6628   1.1  mbalmer 
   6629   1.1  mbalmer 
   6630   1.1  mbalmer 
   6631   1.1  mbalmer 
   6632   1.1  mbalmer <hr><h3><a name="luaL_addsize"><code>luaL_addsize</code></a></h3><p>
   6633   1.5    lneto <span class="apii">[-?, +?, &ndash;]</span>
   6634   1.1  mbalmer <pre>void luaL_addsize (luaL_Buffer *B, size_t n);</pre>
   6635   1.1  mbalmer 
   6636   1.1  mbalmer <p>
   6637   1.9   nikita Adds to the buffer <code>B</code>
   6638   1.1  mbalmer a string of length <code>n</code> previously copied to the
   6639   1.1  mbalmer buffer area (see <a href="#luaL_prepbuffer"><code>luaL_prepbuffer</code></a>).
   6640   1.1  mbalmer 
   6641   1.1  mbalmer 
   6642   1.1  mbalmer 
   6643   1.1  mbalmer 
   6644   1.1  mbalmer 
   6645   1.1  mbalmer <hr><h3><a name="luaL_addstring"><code>luaL_addstring</code></a></h3><p>
   6646   1.5    lneto <span class="apii">[-?, +?, <em>m</em>]</span>
   6647   1.1  mbalmer <pre>void luaL_addstring (luaL_Buffer *B, const char *s);</pre>
   6648   1.1  mbalmer 
   6649   1.1  mbalmer <p>
   6650   1.1  mbalmer Adds the zero-terminated string pointed to by <code>s</code>
   6651   1.1  mbalmer to the buffer <code>B</code>
   6652   1.1  mbalmer (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
   6653   1.1  mbalmer 
   6654   1.1  mbalmer 
   6655   1.1  mbalmer 
   6656   1.1  mbalmer 
   6657   1.1  mbalmer 
   6658   1.1  mbalmer <hr><h3><a name="luaL_addvalue"><code>luaL_addvalue</code></a></h3><p>
   6659   1.9   nikita <span class="apii">[-?, +?, <em>m</em>]</span>
   6660   1.1  mbalmer <pre>void luaL_addvalue (luaL_Buffer *B);</pre>
   6661   1.1  mbalmer 
   6662   1.1  mbalmer <p>
   6663   1.9   nikita Adds the value on the top of the stack
   6664   1.1  mbalmer to the buffer <code>B</code>
   6665   1.1  mbalmer (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
   6666   1.1  mbalmer Pops the value.
   6667   1.1  mbalmer 
   6668   1.1  mbalmer 
   6669   1.1  mbalmer <p>
   6670   1.1  mbalmer This is the only function on string buffers that can (and must)
   6671   1.1  mbalmer be called with an extra element on the stack,
   6672   1.1  mbalmer which is the value to be added to the buffer.
   6673   1.1  mbalmer 
   6674   1.1  mbalmer 
   6675   1.1  mbalmer 
   6676   1.1  mbalmer 
   6677   1.1  mbalmer 
   6678   1.1  mbalmer <hr><h3><a name="luaL_argcheck"><code>luaL_argcheck</code></a></h3><p>
   6679   1.1  mbalmer <span class="apii">[-0, +0, <em>v</em>]</span>
   6680   1.1  mbalmer <pre>void luaL_argcheck (lua_State *L,
   6681   1.1  mbalmer                     int cond,
   6682   1.2    lneto                     int arg,
   6683   1.1  mbalmer                     const char *extramsg);</pre>
   6684   1.1  mbalmer 
   6685   1.1  mbalmer <p>
   6686   1.1  mbalmer Checks whether <code>cond</code> is true.
   6687   1.2    lneto If it is not, raises an error with a standard message (see <a href="#luaL_argerror"><code>luaL_argerror</code></a>).
   6688   1.1  mbalmer 
   6689   1.1  mbalmer 
   6690   1.1  mbalmer 
   6691   1.1  mbalmer 
   6692   1.1  mbalmer 
   6693   1.1  mbalmer <hr><h3><a name="luaL_argerror"><code>luaL_argerror</code></a></h3><p>
   6694   1.1  mbalmer <span class="apii">[-0, +0, <em>v</em>]</span>
   6695   1.2    lneto <pre>int luaL_argerror (lua_State *L, int arg, const char *extramsg);</pre>
   6696   1.1  mbalmer 
   6697   1.1  mbalmer <p>
   6698   1.2    lneto Raises an error reporting a problem with argument <code>arg</code>
   6699   1.7  mbalmer of the C&nbsp;function that called it,
   6700   1.2    lneto using a standard message
   6701   1.2    lneto that includes <code>extramsg</code> as a comment:
   6702   1.1  mbalmer 
   6703   1.1  mbalmer <pre>
   6704   1.2    lneto      bad argument #<em>arg</em> to '<em>funcname</em>' (<em>extramsg</em>)
   6705   1.2    lneto </pre><p>
   6706   1.2    lneto This function never returns.
   6707   1.1  mbalmer 
   6708   1.1  mbalmer 
   6709   1.1  mbalmer 
   6710   1.1  mbalmer 
   6711   1.1  mbalmer 
   6712   1.9   nikita <hr><h3><a name="luaL_argexpected"><code>luaL_argexpected</code></a></h3><p>
   6713   1.9   nikita <span class="apii">[-0, +0, <em>v</em>]</span>
   6714   1.9   nikita <pre>void luaL_argexpected (lua_State *L,
   6715   1.9   nikita                        int cond,
   6716   1.9   nikita                        int arg,
   6717   1.9   nikita                        const char *tname);</pre>
   6718   1.9   nikita 
   6719   1.9   nikita <p>
   6720   1.9   nikita Checks whether <code>cond</code> is true.
   6721   1.9   nikita If it is not, raises an error about the type of the argument <code>arg</code>
   6722   1.9   nikita with a standard message (see <a href="#luaL_typeerror"><code>luaL_typeerror</code></a>).
   6723   1.9   nikita 
   6724   1.9   nikita 
   6725   1.9   nikita 
   6726   1.9   nikita 
   6727   1.9   nikita 
   6728   1.1  mbalmer <hr><h3><a name="luaL_Buffer"><code>luaL_Buffer</code></a></h3>
   6729   1.1  mbalmer <pre>typedef struct luaL_Buffer luaL_Buffer;</pre>
   6730   1.1  mbalmer 
   6731   1.1  mbalmer <p>
   6732   1.1  mbalmer Type for a <em>string buffer</em>.
   6733   1.1  mbalmer 
   6734   1.1  mbalmer 
   6735   1.1  mbalmer <p>
   6736   1.1  mbalmer A string buffer allows C&nbsp;code to build Lua strings piecemeal.
   6737   1.1  mbalmer Its pattern of use is as follows:
   6738   1.1  mbalmer 
   6739   1.1  mbalmer <ul>
   6740   1.1  mbalmer 
   6741   1.2    lneto <li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li>
   6742   1.1  mbalmer 
   6743   1.2    lneto <li>Then initialize it with a call <code>luaL_buffinit(L, &amp;b)</code>.</li>
   6744   1.1  mbalmer 
   6745   1.1  mbalmer <li>
   6746   1.2    lneto Then add string pieces to the buffer calling any of
   6747   1.1  mbalmer the <code>luaL_add*</code> functions.
   6748   1.1  mbalmer </li>
   6749   1.1  mbalmer 
   6750   1.1  mbalmer <li>
   6751   1.2    lneto Finish by calling <code>luaL_pushresult(&amp;b)</code>.
   6752   1.1  mbalmer This call leaves the final string on the top of the stack.
   6753   1.1  mbalmer </li>
   6754   1.1  mbalmer 
   6755   1.1  mbalmer </ul>
   6756   1.1  mbalmer 
   6757   1.1  mbalmer <p>
   6758   1.9   nikita If you know beforehand the maximum size of the resulting string,
   6759   1.2    lneto you can use the buffer like this:
   6760   1.2    lneto 
   6761   1.2    lneto <ul>
   6762   1.2    lneto 
   6763   1.2    lneto <li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li>
   6764   1.2    lneto 
   6765   1.2    lneto <li>Then initialize it and preallocate a space of
   6766   1.2    lneto size <code>sz</code> with a call <code>luaL_buffinitsize(L, &amp;b, sz)</code>.</li>
   6767   1.2    lneto 
   6768   1.9   nikita <li>Then produce the string into that space.</li>
   6769   1.2    lneto 
   6770   1.2    lneto <li>
   6771   1.2    lneto Finish by calling <code>luaL_pushresultsize(&amp;b, sz)</code>,
   6772   1.2    lneto where <code>sz</code> is the total size of the resulting string
   6773   1.9   nikita copied into that space (which may be less than or
   6774   1.9   nikita equal to the preallocated size).
   6775   1.2    lneto </li>
   6776   1.2    lneto 
   6777   1.2    lneto </ul>
   6778   1.2    lneto 
   6779   1.2    lneto <p>
   6780   1.1  mbalmer During its normal operation,
   6781   1.1  mbalmer a string buffer uses a variable number of stack slots.
   6782   1.1  mbalmer So, while using a buffer, you cannot assume that you know where
   6783   1.1  mbalmer the top of the stack is.
   6784   1.1  mbalmer You can use the stack between successive calls to buffer operations
   6785   1.1  mbalmer as long as that use is balanced;
   6786   1.1  mbalmer that is,
   6787   1.1  mbalmer when you call a buffer operation,
   6788   1.1  mbalmer the stack is at the same level
   6789   1.1  mbalmer it was immediately after the previous buffer operation.
   6790   1.1  mbalmer (The only exception to this rule is <a href="#luaL_addvalue"><code>luaL_addvalue</code></a>.)
   6791   1.9   nikita After calling <a href="#luaL_pushresult"><code>luaL_pushresult</code></a>,
   6792   1.9   nikita the stack is back to its level when the buffer was initialized,
   6793   1.1  mbalmer plus the final string on its top.
   6794   1.1  mbalmer 
   6795   1.1  mbalmer 
   6796   1.1  mbalmer 
   6797   1.1  mbalmer 
   6798   1.1  mbalmer 
   6799   1.9   nikita <hr><h3><a name="luaL_buffaddr"><code>luaL_buffaddr</code></a></h3><p>
   6800   1.9   nikita <span class="apii">[-0, +0, &ndash;]</span>
   6801   1.9   nikita <pre>char *luaL_buffaddr (luaL_Buffer *B);</pre>
   6802   1.9   nikita 
   6803   1.9   nikita <p>
   6804   1.9   nikita Returns the address of the current content of buffer <code>B</code>
   6805   1.9   nikita (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
   6806   1.9   nikita Note that any addition to the buffer may invalidate this address.
   6807   1.9   nikita 
   6808   1.9   nikita 
   6809   1.9   nikita 
   6810   1.9   nikita 
   6811   1.9   nikita 
   6812   1.1  mbalmer <hr><h3><a name="luaL_buffinit"><code>luaL_buffinit</code></a></h3><p>
   6813   1.9   nikita <span class="apii">[-0, +?, &ndash;]</span>
   6814   1.1  mbalmer <pre>void luaL_buffinit (lua_State *L, luaL_Buffer *B);</pre>
   6815   1.1  mbalmer 
   6816   1.1  mbalmer <p>
   6817   1.9   nikita Initializes a buffer <code>B</code>
   6818   1.9   nikita (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
   6819   1.1  mbalmer This function does not allocate any space;
   6820   1.9   nikita the buffer must be declared as a variable.
   6821   1.9   nikita 
   6822   1.9   nikita 
   6823   1.9   nikita 
   6824   1.9   nikita 
   6825   1.9   nikita 
   6826   1.9   nikita <hr><h3><a name="luaL_bufflen"><code>luaL_bufflen</code></a></h3><p>
   6827   1.9   nikita <span class="apii">[-0, +0, &ndash;]</span>
   6828   1.9   nikita <pre>size_t luaL_bufflen (luaL_Buffer *B);</pre>
   6829   1.9   nikita 
   6830   1.9   nikita <p>
   6831   1.9   nikita Returns the length of the current content of buffer <code>B</code>
   6832   1.1  mbalmer (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
   6833   1.1  mbalmer 
   6834   1.1  mbalmer 
   6835   1.1  mbalmer 
   6836   1.1  mbalmer 
   6837   1.1  mbalmer 
   6838   1.2    lneto <hr><h3><a name="luaL_buffinitsize"><code>luaL_buffinitsize</code></a></h3><p>
   6839   1.5    lneto <span class="apii">[-?, +?, <em>m</em>]</span>
   6840   1.2    lneto <pre>char *luaL_buffinitsize (lua_State *L, luaL_Buffer *B, size_t sz);</pre>
   6841   1.2    lneto 
   6842   1.2    lneto <p>
   6843   1.2    lneto Equivalent to the sequence
   6844   1.2    lneto <a href="#luaL_buffinit"><code>luaL_buffinit</code></a>, <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a>.
   6845   1.2    lneto 
   6846   1.2    lneto 
   6847   1.2    lneto 
   6848   1.2    lneto 
   6849   1.2    lneto 
   6850   1.9   nikita <hr><h3><a name="luaL_buffsub"><code>luaL_buffsub</code></a></h3><p>
   6851   1.9   nikita <span class="apii">[-?, +?, &ndash;]</span>
   6852   1.9   nikita <pre>void luaL_buffsub (luaL_Buffer *B, int n);</pre>
   6853   1.9   nikita 
   6854   1.9   nikita <p>
   6855  1.10   nikita Removes <code>n</code> bytes from the buffer <code>B</code>
   6856   1.9   nikita (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
   6857   1.9   nikita The buffer must have at least that many bytes.
   6858   1.9   nikita 
   6859   1.9   nikita 
   6860   1.9   nikita 
   6861   1.9   nikita 
   6862   1.9   nikita 
   6863   1.1  mbalmer <hr><h3><a name="luaL_callmeta"><code>luaL_callmeta</code></a></h3><p>
   6864   1.1  mbalmer <span class="apii">[-0, +(0|1), <em>e</em>]</span>
   6865   1.1  mbalmer <pre>int luaL_callmeta (lua_State *L, int obj, const char *e);</pre>
   6866   1.1  mbalmer 
   6867   1.1  mbalmer <p>
   6868   1.1  mbalmer Calls a metamethod.
   6869   1.1  mbalmer 
   6870   1.1  mbalmer 
   6871   1.1  mbalmer <p>
   6872   1.1  mbalmer If the object at index <code>obj</code> has a metatable and this
   6873   1.1  mbalmer metatable has a field <code>e</code>,
   6874   1.2    lneto this function calls this field passing the object as its only argument.
   6875   1.2    lneto In this case this function returns true and pushes onto the
   6876   1.1  mbalmer stack the value returned by the call.
   6877   1.1  mbalmer If there is no metatable or no metamethod,
   6878   1.9   nikita this function returns false without pushing any value on the stack.
   6879   1.1  mbalmer 
   6880   1.1  mbalmer 
   6881   1.1  mbalmer 
   6882   1.1  mbalmer 
   6883   1.1  mbalmer 
   6884   1.1  mbalmer <hr><h3><a name="luaL_checkany"><code>luaL_checkany</code></a></h3><p>
   6885   1.1  mbalmer <span class="apii">[-0, +0, <em>v</em>]</span>
   6886   1.2    lneto <pre>void luaL_checkany (lua_State *L, int arg);</pre>
   6887   1.1  mbalmer 
   6888   1.1  mbalmer <p>
   6889   1.1  mbalmer Checks whether the function has an argument
   6890   1.2    lneto of any type (including <b>nil</b>) at position <code>arg</code>.
   6891   1.1  mbalmer 
   6892   1.1  mbalmer 
   6893   1.1  mbalmer 
   6894   1.1  mbalmer 
   6895   1.1  mbalmer 
   6896   1.1  mbalmer <hr><h3><a name="luaL_checkinteger"><code>luaL_checkinteger</code></a></h3><p>
   6897   1.1  mbalmer <span class="apii">[-0, +0, <em>v</em>]</span>
   6898   1.2    lneto <pre>lua_Integer luaL_checkinteger (lua_State *L, int arg);</pre>
   6899   1.1  mbalmer 
   6900   1.1  mbalmer <p>
   6901   1.2    lneto Checks whether the function argument <code>arg</code> is an integer
   6902   1.2    lneto (or can be converted to an integer)
   6903   1.9   nikita and returns this integer.
   6904   1.1  mbalmer 
   6905   1.1  mbalmer 
   6906   1.1  mbalmer 
   6907   1.1  mbalmer 
   6908   1.1  mbalmer 
   6909   1.1  mbalmer <hr><h3><a name="luaL_checklstring"><code>luaL_checklstring</code></a></h3><p>
   6910   1.1  mbalmer <span class="apii">[-0, +0, <em>v</em>]</span>
   6911   1.2    lneto <pre>const char *luaL_checklstring (lua_State *L, int arg, size_t *l);</pre>
   6912   1.1  mbalmer 
   6913   1.1  mbalmer <p>
   6914   1.2    lneto Checks whether the function argument <code>arg</code> is a string
   6915   1.1  mbalmer and returns this string;
   6916   1.9   nikita if <code>l</code> is not <code>NULL</code> fills its referent
   6917   1.1  mbalmer with the string's length.
   6918   1.1  mbalmer 
   6919   1.1  mbalmer 
   6920   1.1  mbalmer <p>
   6921   1.1  mbalmer This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result,
   6922   1.1  mbalmer so all conversions and caveats of that function apply here.
   6923   1.1  mbalmer 
   6924   1.1  mbalmer 
   6925   1.1  mbalmer 
   6926   1.1  mbalmer 
   6927   1.1  mbalmer 
   6928   1.1  mbalmer <hr><h3><a name="luaL_checknumber"><code>luaL_checknumber</code></a></h3><p>
   6929   1.1  mbalmer <span class="apii">[-0, +0, <em>v</em>]</span>
   6930   1.2    lneto <pre>lua_Number luaL_checknumber (lua_State *L, int arg);</pre>
   6931   1.1  mbalmer 
   6932   1.1  mbalmer <p>
   6933   1.2    lneto Checks whether the function argument <code>arg</code> is a number
   6934   1.9   nikita and returns this number converted to a <code>lua_Number</code>.
   6935   1.1  mbalmer 
   6936   1.1  mbalmer 
   6937   1.1  mbalmer 
   6938   1.1  mbalmer 
   6939   1.1  mbalmer 
   6940   1.1  mbalmer <hr><h3><a name="luaL_checkoption"><code>luaL_checkoption</code></a></h3><p>
   6941   1.1  mbalmer <span class="apii">[-0, +0, <em>v</em>]</span>
   6942   1.1  mbalmer <pre>int luaL_checkoption (lua_State *L,
   6943   1.2    lneto                       int arg,
   6944   1.1  mbalmer                       const char *def,
   6945   1.1  mbalmer                       const char *const lst[]);</pre>
   6946   1.1  mbalmer 
   6947   1.1  mbalmer <p>
   6948   1.2    lneto Checks whether the function argument <code>arg</code> is a string and
   6949   1.1  mbalmer searches for this string in the array <code>lst</code>
   6950   1.1  mbalmer (which must be NULL-terminated).
   6951   1.1  mbalmer Returns the index in the array where the string was found.
   6952   1.1  mbalmer Raises an error if the argument is not a string or
   6953   1.1  mbalmer if the string cannot be found.
   6954   1.1  mbalmer 
   6955   1.1  mbalmer 
   6956   1.1  mbalmer <p>
   6957   1.1  mbalmer If <code>def</code> is not <code>NULL</code>,
   6958   1.1  mbalmer the function uses <code>def</code> as a default value when
   6959   1.2    lneto there is no argument <code>arg</code> or when this argument is <b>nil</b>.
   6960   1.1  mbalmer 
   6961   1.1  mbalmer 
   6962   1.1  mbalmer <p>
   6963   1.1  mbalmer This is a useful function for mapping strings to C&nbsp;enums.
   6964   1.1  mbalmer (The usual convention in Lua libraries is
   6965   1.1  mbalmer to use strings instead of numbers to select options.)
   6966   1.1  mbalmer 
   6967   1.1  mbalmer 
   6968   1.1  mbalmer 
   6969   1.1  mbalmer 
   6970   1.1  mbalmer 
   6971   1.1  mbalmer <hr><h3><a name="luaL_checkstack"><code>luaL_checkstack</code></a></h3><p>
   6972   1.1  mbalmer <span class="apii">[-0, +0, <em>v</em>]</span>
   6973   1.1  mbalmer <pre>void luaL_checkstack (lua_State *L, int sz, const char *msg);</pre>
   6974   1.1  mbalmer 
   6975   1.1  mbalmer <p>
   6976   1.1  mbalmer Grows the stack size to <code>top + sz</code> elements,
   6977   1.1  mbalmer raising an error if the stack cannot grow to that size.
   6978   1.2    lneto <code>msg</code> is an additional text to go into the error message
   6979   1.2    lneto (or <code>NULL</code> for no additional text).
   6980   1.1  mbalmer 
   6981   1.1  mbalmer 
   6982   1.1  mbalmer 
   6983   1.1  mbalmer 
   6984   1.1  mbalmer 
   6985   1.1  mbalmer <hr><h3><a name="luaL_checkstring"><code>luaL_checkstring</code></a></h3><p>
   6986   1.1  mbalmer <span class="apii">[-0, +0, <em>v</em>]</span>
   6987   1.2    lneto <pre>const char *luaL_checkstring (lua_State *L, int arg);</pre>
   6988   1.1  mbalmer 
   6989   1.1  mbalmer <p>
   6990   1.2    lneto Checks whether the function argument <code>arg</code> is a string
   6991   1.1  mbalmer and returns this string.
   6992   1.1  mbalmer 
   6993   1.1  mbalmer 
   6994   1.1  mbalmer <p>
   6995   1.1  mbalmer This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result,
   6996   1.1  mbalmer so all conversions and caveats of that function apply here.
   6997   1.1  mbalmer 
   6998   1.1  mbalmer 
   6999   1.1  mbalmer 
   7000   1.1  mbalmer 
   7001   1.1  mbalmer 
   7002   1.1  mbalmer <hr><h3><a name="luaL_checktype"><code>luaL_checktype</code></a></h3><p>
   7003   1.1  mbalmer <span class="apii">[-0, +0, <em>v</em>]</span>
   7004   1.2    lneto <pre>void luaL_checktype (lua_State *L, int arg, int t);</pre>
   7005   1.1  mbalmer 
   7006   1.1  mbalmer <p>
   7007   1.2    lneto Checks whether the function argument <code>arg</code> has type <code>t</code>.
   7008   1.1  mbalmer See <a href="#lua_type"><code>lua_type</code></a> for the encoding of types for <code>t</code>.
   7009   1.1  mbalmer 
   7010   1.1  mbalmer 
   7011   1.1  mbalmer 
   7012   1.1  mbalmer 
   7013   1.1  mbalmer 
   7014   1.1  mbalmer <hr><h3><a name="luaL_checkudata"><code>luaL_checkudata</code></a></h3><p>
   7015   1.1  mbalmer <span class="apii">[-0, +0, <em>v</em>]</span>
   7016   1.2    lneto <pre>void *luaL_checkudata (lua_State *L, int arg, const char *tname);</pre>
   7017   1.2    lneto 
   7018   1.2    lneto <p>
   7019   1.2    lneto Checks whether the function argument <code>arg</code> is a userdata
   7020   1.2    lneto of the type <code>tname</code> (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>) and
   7021   1.9   nikita returns the userdata's memory-block address (see <a href="#lua_touserdata"><code>lua_touserdata</code></a>).
   7022   1.2    lneto 
   7023   1.2    lneto 
   7024   1.2    lneto 
   7025   1.2    lneto 
   7026   1.2    lneto 
   7027   1.2    lneto <hr><h3><a name="luaL_checkversion"><code>luaL_checkversion</code></a></h3><p>
   7028   1.6  salazar <span class="apii">[-0, +0, <em>v</em>]</span>
   7029   1.2    lneto <pre>void luaL_checkversion (lua_State *L);</pre>
   7030   1.1  mbalmer 
   7031   1.1  mbalmer <p>
   7032   1.9   nikita Checks whether the code making the call and the Lua library being called
   7033   1.9   nikita are using the same version of Lua and the same numeric types.
   7034   1.1  mbalmer 
   7035   1.1  mbalmer 
   7036   1.1  mbalmer 
   7037   1.1  mbalmer 
   7038   1.1  mbalmer 
   7039   1.1  mbalmer <hr><h3><a name="luaL_dofile"><code>luaL_dofile</code></a></h3><p>
   7040   1.9   nikita <span class="apii">[-0, +?, <em>m</em>]</span>
   7041   1.1  mbalmer <pre>int luaL_dofile (lua_State *L, const char *filename);</pre>
   7042   1.1  mbalmer 
   7043   1.1  mbalmer <p>
   7044   1.1  mbalmer Loads and runs the given file.
   7045   1.1  mbalmer It is defined as the following macro:
   7046   1.1  mbalmer 
   7047   1.1  mbalmer <pre>
   7048   1.1  mbalmer      (luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0))
   7049   1.1  mbalmer </pre><p>
   7050  1.10   nikita It returns&nbsp;0 (<a href="#pdf-LUA_OK"><code>LUA_OK</code></a>) if there are no errors,
   7051  1.10   nikita or 1 in case of errors.
   7052   1.1  mbalmer 
   7053   1.1  mbalmer 
   7054   1.1  mbalmer 
   7055   1.1  mbalmer 
   7056   1.1  mbalmer 
   7057   1.1  mbalmer <hr><h3><a name="luaL_dostring"><code>luaL_dostring</code></a></h3><p>
   7058   1.2    lneto <span class="apii">[-0, +?, &ndash;]</span>
   7059   1.1  mbalmer <pre>int luaL_dostring (lua_State *L, const char *str);</pre>
   7060   1.1  mbalmer 
   7061   1.1  mbalmer <p>
   7062   1.1  mbalmer Loads and runs the given string.
   7063   1.1  mbalmer It is defined as the following macro:
   7064   1.1  mbalmer 
   7065   1.1  mbalmer <pre>
   7066   1.1  mbalmer      (luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0))
   7067   1.1  mbalmer </pre><p>
   7068  1.10   nikita It returns&nbsp;0 (<a href="#pdf-LUA_OK"><code>LUA_OK</code></a>) if there are no errors,
   7069  1.10   nikita or 1 in case of errors.
   7070   1.1  mbalmer 
   7071   1.1  mbalmer 
   7072   1.1  mbalmer 
   7073   1.1  mbalmer 
   7074   1.1  mbalmer 
   7075   1.1  mbalmer <hr><h3><a name="luaL_error"><code>luaL_error</code></a></h3><p>
   7076   1.1  mbalmer <span class="apii">[-0, +0, <em>v</em>]</span>
   7077   1.1  mbalmer <pre>int luaL_error (lua_State *L, const char *fmt, ...);</pre>
   7078   1.1  mbalmer 
   7079   1.1  mbalmer <p>
   7080   1.1  mbalmer Raises an error.
   7081   1.2    lneto The error message format is given by <code>fmt</code>
   7082   1.2    lneto plus any extra arguments,
   7083   1.2    lneto following the same rules of <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>.
   7084   1.2    lneto It also adds at the beginning of the message the file name and
   7085   1.2    lneto the line number where the error occurred,
   7086   1.2    lneto if this information is available.
   7087   1.2    lneto 
   7088   1.2    lneto 
   7089   1.2    lneto <p>
   7090   1.2    lneto This function never returns,
   7091   1.2    lneto but it is an idiom to use it in C&nbsp;functions
   7092   1.2    lneto as <code>return luaL_error(<em>args</em>)</code>.
   7093   1.2    lneto 
   7094   1.2    lneto 
   7095   1.2    lneto 
   7096   1.2    lneto 
   7097   1.2    lneto 
   7098   1.2    lneto <hr><h3><a name="luaL_execresult"><code>luaL_execresult</code></a></h3><p>
   7099   1.5    lneto <span class="apii">[-0, +3, <em>m</em>]</span>
   7100   1.2    lneto <pre>int luaL_execresult (lua_State *L, int stat);</pre>
   7101   1.2    lneto 
   7102   1.2    lneto <p>
   7103   1.2    lneto This function produces the return values for
   7104   1.2    lneto process-related functions in the standard library
   7105   1.2    lneto (<a href="#pdf-os.execute"><code>os.execute</code></a> and <a href="#pdf-io.close"><code>io.close</code></a>).
   7106   1.2    lneto 
   7107   1.2    lneto 
   7108   1.2    lneto 
   7109   1.2    lneto 
   7110   1.1  mbalmer 
   7111   1.2    lneto <hr><h3><a name="luaL_fileresult"><code>luaL_fileresult</code></a></h3><p>
   7112   1.5    lneto <span class="apii">[-0, +(1|3), <em>m</em>]</span>
   7113   1.2    lneto <pre>int luaL_fileresult (lua_State *L, int stat, const char *fname);</pre>
   7114   1.1  mbalmer 
   7115   1.1  mbalmer <p>
   7116   1.2    lneto This function produces the return values for
   7117   1.2    lneto file-related functions in the standard library
   7118   1.2    lneto (<a href="#pdf-io.open"><code>io.open</code></a>, <a href="#pdf-os.rename"><code>os.rename</code></a>, <a href="#pdf-file:seek"><code>file:seek</code></a>, etc.).
   7119   1.1  mbalmer 
   7120   1.1  mbalmer 
   7121   1.1  mbalmer 
   7122   1.1  mbalmer 
   7123   1.1  mbalmer 
   7124   1.1  mbalmer <hr><h3><a name="luaL_getmetafield"><code>luaL_getmetafield</code></a></h3><p>
   7125   1.5    lneto <span class="apii">[-0, +(0|1), <em>m</em>]</span>
   7126   1.1  mbalmer <pre>int luaL_getmetafield (lua_State *L, int obj, const char *e);</pre>
   7127   1.1  mbalmer 
   7128   1.1  mbalmer <p>
   7129   1.1  mbalmer Pushes onto the stack the field <code>e</code> from the metatable
   7130   1.8    alnsn of the object at index <code>obj</code> and returns the type of the pushed value.
   7131   1.1  mbalmer If the object does not have a metatable,
   7132   1.1  mbalmer or if the metatable does not have this field,
   7133   1.3    lneto pushes nothing and returns <code>LUA_TNIL</code>.
   7134   1.1  mbalmer 
   7135   1.1  mbalmer 
   7136   1.1  mbalmer 
   7137   1.1  mbalmer 
   7138   1.1  mbalmer 
   7139   1.1  mbalmer <hr><h3><a name="luaL_getmetatable"><code>luaL_getmetatable</code></a></h3><p>
   7140   1.5    lneto <span class="apii">[-0, +1, <em>m</em>]</span>
   7141   1.3    lneto <pre>int luaL_getmetatable (lua_State *L, const char *tname);</pre>
   7142   1.1  mbalmer 
   7143   1.1  mbalmer <p>
   7144   1.9   nikita Pushes onto the stack the metatable associated with the name <code>tname</code>
   7145   1.9   nikita in the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>),
   7146   1.9   nikita or <b>nil</b> if there is no metatable associated with that name.
   7147   1.4  mbalmer Returns the type of the pushed value.
   7148   1.1  mbalmer 
   7149   1.1  mbalmer 
   7150   1.1  mbalmer 
   7151   1.1  mbalmer 
   7152   1.1  mbalmer 
   7153   1.2    lneto <hr><h3><a name="luaL_getsubtable"><code>luaL_getsubtable</code></a></h3><p>
   7154   1.2    lneto <span class="apii">[-0, +1, <em>e</em>]</span>
   7155   1.2    lneto <pre>int luaL_getsubtable (lua_State *L, int idx, const char *fname);</pre>
   7156   1.2    lneto 
   7157   1.2    lneto <p>
   7158   1.2    lneto Ensures that the value <code>t[fname]</code>,
   7159   1.2    lneto where <code>t</code> is the value at index <code>idx</code>,
   7160   1.2    lneto is a table,
   7161   1.2    lneto and pushes that table onto the stack.
   7162   1.2    lneto Returns true if it finds a previous table there
   7163   1.2    lneto and false if it creates a new table.
   7164   1.2    lneto 
   7165   1.2    lneto 
   7166   1.2    lneto 
   7167   1.2    lneto 
   7168   1.2    lneto 
   7169   1.1  mbalmer <hr><h3><a name="luaL_gsub"><code>luaL_gsub</code></a></h3><p>
   7170   1.5    lneto <span class="apii">[-0, +1, <em>m</em>]</span>
   7171   1.1  mbalmer <pre>const char *luaL_gsub (lua_State *L,
   7172   1.1  mbalmer                        const char *s,
   7173   1.1  mbalmer                        const char *p,
   7174   1.1  mbalmer                        const char *r);</pre>
   7175   1.1  mbalmer 
   7176   1.1  mbalmer <p>
   7177   1.9   nikita Creates a copy of string <code>s</code>,
   7178   1.9   nikita replacing any occurrence of the string <code>p</code>
   7179   1.1  mbalmer with the string <code>r</code>.
   7180   1.1  mbalmer Pushes the resulting string on the stack and returns it.
   7181   1.1  mbalmer 
   7182   1.1  mbalmer 
   7183   1.1  mbalmer 
   7184   1.1  mbalmer 
   7185   1.1  mbalmer 
   7186   1.2    lneto <hr><h3><a name="luaL_len"><code>luaL_len</code></a></h3><p>
   7187   1.2    lneto <span class="apii">[-0, +0, <em>e</em>]</span>
   7188   1.2    lneto <pre>lua_Integer luaL_len (lua_State *L, int index);</pre>
   7189   1.2    lneto 
   7190   1.2    lneto <p>
   7191   1.2    lneto Returns the "length" of the value at the given index
   7192   1.2    lneto as a number;
   7193   1.2    lneto it is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">&sect;3.4.7</a>).
   7194   1.2    lneto Raises an error if the result of the operation is not an integer.
   7195   1.9   nikita (This case can only happen through metamethods.)
   7196   1.2    lneto 
   7197   1.2    lneto 
   7198   1.2    lneto 
   7199   1.2    lneto 
   7200   1.2    lneto 
   7201   1.1  mbalmer <hr><h3><a name="luaL_loadbuffer"><code>luaL_loadbuffer</code></a></h3><p>
   7202   1.2    lneto <span class="apii">[-0, +1, &ndash;]</span>
   7203   1.1  mbalmer <pre>int luaL_loadbuffer (lua_State *L,
   7204   1.1  mbalmer                      const char *buff,
   7205   1.1  mbalmer                      size_t sz,
   7206   1.1  mbalmer                      const char *name);</pre>
   7207   1.1  mbalmer 
   7208   1.1  mbalmer <p>
   7209   1.2    lneto Equivalent to <a href="#luaL_loadbufferx"><code>luaL_loadbufferx</code></a> with <code>mode</code> equal to <code>NULL</code>.
   7210   1.2    lneto 
   7211   1.2    lneto 
   7212   1.2    lneto 
   7213   1.2    lneto 
   7214   1.2    lneto 
   7215   1.2    lneto <hr><h3><a name="luaL_loadbufferx"><code>luaL_loadbufferx</code></a></h3><p>
   7216   1.2    lneto <span class="apii">[-0, +1, &ndash;]</span>
   7217   1.2    lneto <pre>int luaL_loadbufferx (lua_State *L,
   7218   1.2    lneto                       const char *buff,
   7219   1.2    lneto                       size_t sz,
   7220   1.2    lneto                       const char *name,
   7221   1.2    lneto                       const char *mode);</pre>
   7222   1.2    lneto 
   7223   1.2    lneto <p>
   7224   1.1  mbalmer Loads a buffer as a Lua chunk.
   7225   1.1  mbalmer This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the
   7226   1.1  mbalmer buffer pointed to by <code>buff</code> with size <code>sz</code>.
   7227   1.1  mbalmer 
   7228   1.1  mbalmer 
   7229   1.1  mbalmer <p>
   7230   1.1  mbalmer This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>.
   7231   1.1  mbalmer <code>name</code> is the chunk name,
   7232   1.1  mbalmer used for debug information and error messages.
   7233   1.9   nikita The string <code>mode</code> works as in the function <a href="#lua_load"><code>lua_load</code></a>.
   7234   1.1  mbalmer 
   7235   1.1  mbalmer 
   7236   1.1  mbalmer 
   7237   1.1  mbalmer 
   7238   1.1  mbalmer 
   7239   1.1  mbalmer <hr><h3><a name="luaL_loadfile"><code>luaL_loadfile</code></a></h3><p>
   7240   1.6  salazar <span class="apii">[-0, +1, <em>m</em>]</span>
   7241   1.1  mbalmer <pre>int luaL_loadfile (lua_State *L, const char *filename);</pre>
   7242   1.1  mbalmer 
   7243   1.1  mbalmer <p>
   7244   1.2    lneto Equivalent to <a href="#luaL_loadfilex"><code>luaL_loadfilex</code></a> with <code>mode</code> equal to <code>NULL</code>.
   7245   1.2    lneto 
   7246   1.2    lneto 
   7247   1.2    lneto 
   7248   1.2    lneto 
   7249   1.2    lneto 
   7250   1.2    lneto <hr><h3><a name="luaL_loadfilex"><code>luaL_loadfilex</code></a></h3><p>
   7251   1.6  salazar <span class="apii">[-0, +1, <em>m</em>]</span>
   7252   1.2    lneto <pre>int luaL_loadfilex (lua_State *L, const char *filename,
   7253   1.2    lneto                                             const char *mode);</pre>
   7254   1.2    lneto 
   7255   1.2    lneto <p>
   7256   1.1  mbalmer Loads a file as a Lua chunk.
   7257   1.1  mbalmer This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the file
   7258   1.1  mbalmer named <code>filename</code>.
   7259   1.1  mbalmer If <code>filename</code> is <code>NULL</code>,
   7260   1.1  mbalmer then it loads from the standard input.
   7261   1.1  mbalmer The first line in the file is ignored if it starts with a <code>#</code>.
   7262   1.1  mbalmer 
   7263   1.1  mbalmer 
   7264   1.1  mbalmer <p>
   7265   1.9   nikita The string <code>mode</code> works as in the function <a href="#lua_load"><code>lua_load</code></a>.
   7266   1.2    lneto 
   7267   1.2    lneto 
   7268   1.2    lneto <p>
   7269   1.9   nikita This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>
   7270   1.9   nikita or <a href="#pdf-LUA_ERRFILE"><code>LUA_ERRFILE</code></a> for file-related errors.
   7271   1.1  mbalmer 
   7272   1.1  mbalmer 
   7273   1.1  mbalmer <p>
   7274   1.1  mbalmer As <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk;
   7275   1.1  mbalmer it does not run it.
   7276   1.1  mbalmer 
   7277   1.1  mbalmer 
   7278   1.1  mbalmer 
   7279   1.1  mbalmer 
   7280   1.1  mbalmer 
   7281   1.1  mbalmer <hr><h3><a name="luaL_loadstring"><code>luaL_loadstring</code></a></h3><p>
   7282   1.2    lneto <span class="apii">[-0, +1, &ndash;]</span>
   7283   1.1  mbalmer <pre>int luaL_loadstring (lua_State *L, const char *s);</pre>
   7284   1.1  mbalmer 
   7285   1.1  mbalmer <p>
   7286   1.1  mbalmer Loads a string as a Lua chunk.
   7287   1.1  mbalmer This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in
   7288   1.1  mbalmer the zero-terminated string <code>s</code>.
   7289   1.1  mbalmer 
   7290   1.1  mbalmer 
   7291   1.1  mbalmer <p>
   7292   1.1  mbalmer This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>.
   7293   1.1  mbalmer 
   7294   1.1  mbalmer 
   7295   1.1  mbalmer <p>
   7296   1.1  mbalmer Also as <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk;
   7297   1.1  mbalmer it does not run it.
   7298   1.1  mbalmer 
   7299   1.1  mbalmer 
   7300   1.1  mbalmer 
   7301   1.1  mbalmer 
   7302   1.1  mbalmer 
   7303   1.2    lneto <hr><h3><a name="luaL_newlib"><code>luaL_newlib</code></a></h3><p>
   7304   1.5    lneto <span class="apii">[-0, +1, <em>m</em>]</span>
   7305   1.3    lneto <pre>void luaL_newlib (lua_State *L, const luaL_Reg l[]);</pre>
   7306   1.2    lneto 
   7307   1.2    lneto <p>
   7308   1.2    lneto Creates a new table and registers there
   7309   1.9   nikita the functions in the list <code>l</code>.
   7310   1.3    lneto 
   7311   1.3    lneto 
   7312   1.3    lneto <p>
   7313   1.2    lneto It is implemented as the following macro:
   7314   1.2    lneto 
   7315   1.2    lneto <pre>
   7316   1.2    lneto      (luaL_newlibtable(L,l), luaL_setfuncs(L,l,0))
   7317   1.3    lneto </pre><p>
   7318   1.3    lneto The array <code>l</code> must be the actual array,
   7319   1.3    lneto not a pointer to it.
   7320   1.3    lneto 
   7321   1.2    lneto 
   7322   1.2    lneto 
   7323   1.2    lneto 
   7324   1.2    lneto 
   7325   1.2    lneto <hr><h3><a name="luaL_newlibtable"><code>luaL_newlibtable</code></a></h3><p>
   7326   1.5    lneto <span class="apii">[-0, +1, <em>m</em>]</span>
   7327   1.2    lneto <pre>void luaL_newlibtable (lua_State *L, const luaL_Reg l[]);</pre>
   7328   1.2    lneto 
   7329   1.2    lneto <p>
   7330   1.2    lneto Creates a new table with a size optimized
   7331   1.2    lneto to store all entries in the array <code>l</code>
   7332   1.2    lneto (but does not actually store them).
   7333   1.2    lneto It is intended to be used in conjunction with <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a>
   7334   1.2    lneto (see <a href="#luaL_newlib"><code>luaL_newlib</code></a>).
   7335   1.2    lneto 
   7336   1.2    lneto 
   7337   1.2    lneto <p>
   7338   1.2    lneto It is implemented as a macro.
   7339   1.2    lneto The array <code>l</code> must be the actual array,
   7340   1.2    lneto not a pointer to it.
   7341   1.2    lneto 
   7342   1.2    lneto 
   7343   1.2    lneto 
   7344   1.2    lneto 
   7345   1.2    lneto 
   7346   1.1  mbalmer <hr><h3><a name="luaL_newmetatable"><code>luaL_newmetatable</code></a></h3><p>
   7347   1.5    lneto <span class="apii">[-0, +1, <em>m</em>]</span>
   7348   1.1  mbalmer <pre>int luaL_newmetatable (lua_State *L, const char *tname);</pre>
   7349   1.1  mbalmer 
   7350   1.1  mbalmer <p>
   7351   1.1  mbalmer If the registry already has the key <code>tname</code>,
   7352   1.1  mbalmer returns 0.
   7353   1.1  mbalmer Otherwise,
   7354   1.1  mbalmer creates a new table to be used as a metatable for userdata,
   7355   1.2    lneto adds to this new table the pair <code>__name = tname</code>,
   7356   1.2    lneto adds to the registry the pair <code>[tname] = new table</code>,
   7357   1.1  mbalmer and returns 1.
   7358   1.1  mbalmer 
   7359   1.1  mbalmer 
   7360   1.1  mbalmer <p>
   7361   1.9   nikita In both cases,
   7362   1.9   nikita the function pushes onto the stack the final value associated
   7363   1.1  mbalmer with <code>tname</code> in the registry.
   7364   1.1  mbalmer 
   7365   1.1  mbalmer 
   7366   1.1  mbalmer 
   7367   1.1  mbalmer 
   7368   1.1  mbalmer 
   7369   1.1  mbalmer <hr><h3><a name="luaL_newstate"><code>luaL_newstate</code></a></h3><p>
   7370   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   7371   1.1  mbalmer <pre>lua_State *luaL_newstate (void);</pre>
   7372   1.1  mbalmer 
   7373   1.1  mbalmer <p>
   7374   1.1  mbalmer Creates a new Lua state.
   7375   1.1  mbalmer It calls <a href="#lua_newstate"><code>lua_newstate</code></a> with an
   7376  1.10   nikita allocator based on the ISO&nbsp;C allocation functions
   7377   1.9   nikita and then sets a warning function and a panic function (see <a href="#4.4">&sect;4.4</a>)
   7378   1.9   nikita that print messages to the standard error output.
   7379   1.1  mbalmer 
   7380   1.1  mbalmer 
   7381   1.1  mbalmer <p>
   7382   1.1  mbalmer Returns the new state,
   7383   1.1  mbalmer or <code>NULL</code> if there is a memory allocation error.
   7384   1.1  mbalmer 
   7385   1.1  mbalmer 
   7386   1.1  mbalmer 
   7387   1.1  mbalmer 
   7388   1.1  mbalmer 
   7389   1.1  mbalmer <hr><h3><a name="luaL_openlibs"><code>luaL_openlibs</code></a></h3><p>
   7390   1.2    lneto <span class="apii">[-0, +0, <em>e</em>]</span>
   7391   1.1  mbalmer <pre>void luaL_openlibs (lua_State *L);</pre>
   7392   1.1  mbalmer 
   7393   1.1  mbalmer <p>
   7394   1.1  mbalmer Opens all standard Lua libraries into the given state.
   7395   1.1  mbalmer 
   7396   1.1  mbalmer 
   7397   1.1  mbalmer 
   7398   1.1  mbalmer 
   7399   1.1  mbalmer 
   7400   1.6  salazar <hr><h3><a name="luaL_opt"><code>luaL_opt</code></a></h3><p>
   7401   1.9   nikita <span class="apii">[-0, +0, &ndash;]</span>
   7402   1.6  salazar <pre>T luaL_opt (L, func, arg, dflt);</pre>
   7403   1.6  salazar 
   7404   1.6  salazar <p>
   7405   1.6  salazar This macro is defined as follows:
   7406   1.6  salazar 
   7407   1.6  salazar <pre>
   7408   1.6  salazar      (lua_isnoneornil(L,(arg)) ? (dflt) : func(L,(arg)))
   7409   1.6  salazar </pre><p>
   7410   1.6  salazar In words, if the argument <code>arg</code> is nil or absent,
   7411   1.6  salazar the macro results in the default <code>dflt</code>.
   7412   1.6  salazar Otherwise, it results in the result of calling <code>func</code>
   7413   1.6  salazar with the state <code>L</code> and the argument index <code>arg</code> as
   7414   1.8    alnsn arguments.
   7415   1.6  salazar Note that it evaluates the expression <code>dflt</code> only if needed.
   7416   1.6  salazar 
   7417   1.6  salazar 
   7418   1.6  salazar 
   7419   1.6  salazar 
   7420   1.6  salazar 
   7421   1.1  mbalmer <hr><h3><a name="luaL_optinteger"><code>luaL_optinteger</code></a></h3><p>
   7422   1.1  mbalmer <span class="apii">[-0, +0, <em>v</em>]</span>
   7423   1.1  mbalmer <pre>lua_Integer luaL_optinteger (lua_State *L,
   7424   1.2    lneto                              int arg,
   7425   1.1  mbalmer                              lua_Integer d);</pre>
   7426   1.1  mbalmer 
   7427   1.1  mbalmer <p>
   7428   1.2    lneto If the function argument <code>arg</code> is an integer
   7429   1.9   nikita (or it is convertible to an integer),
   7430   1.2    lneto returns this integer.
   7431   1.1  mbalmer If this argument is absent or is <b>nil</b>,
   7432   1.1  mbalmer returns <code>d</code>.
   7433   1.1  mbalmer Otherwise, raises an error.
   7434   1.1  mbalmer 
   7435   1.1  mbalmer 
   7436   1.1  mbalmer 
   7437   1.1  mbalmer 
   7438   1.1  mbalmer 
   7439   1.1  mbalmer <hr><h3><a name="luaL_optlstring"><code>luaL_optlstring</code></a></h3><p>
   7440   1.1  mbalmer <span class="apii">[-0, +0, <em>v</em>]</span>
   7441   1.1  mbalmer <pre>const char *luaL_optlstring (lua_State *L,
   7442   1.2    lneto                              int arg,
   7443   1.1  mbalmer                              const char *d,
   7444   1.1  mbalmer                              size_t *l);</pre>
   7445   1.1  mbalmer 
   7446   1.1  mbalmer <p>
   7447   1.2    lneto If the function argument <code>arg</code> is a string,
   7448   1.1  mbalmer returns this string.
   7449   1.1  mbalmer If this argument is absent or is <b>nil</b>,
   7450   1.1  mbalmer returns <code>d</code>.
   7451   1.1  mbalmer Otherwise, raises an error.
   7452   1.1  mbalmer 
   7453   1.1  mbalmer 
   7454   1.1  mbalmer <p>
   7455   1.1  mbalmer If <code>l</code> is not <code>NULL</code>,
   7456   1.9   nikita fills its referent with the result's length.
   7457   1.5    lneto If the result is <code>NULL</code>
   7458   1.5    lneto (only possible when returning <code>d</code> and <code>d == NULL</code>),
   7459   1.5    lneto its length is considered zero.
   7460   1.1  mbalmer 
   7461   1.1  mbalmer 
   7462   1.7  mbalmer <p>
   7463   1.7  mbalmer This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result,
   7464   1.7  mbalmer so all conversions and caveats of that function apply here.
   7465   1.7  mbalmer 
   7466   1.7  mbalmer 
   7467   1.1  mbalmer 
   7468   1.1  mbalmer 
   7469   1.1  mbalmer 
   7470   1.1  mbalmer <hr><h3><a name="luaL_optnumber"><code>luaL_optnumber</code></a></h3><p>
   7471   1.1  mbalmer <span class="apii">[-0, +0, <em>v</em>]</span>
   7472   1.2    lneto <pre>lua_Number luaL_optnumber (lua_State *L, int arg, lua_Number d);</pre>
   7473   1.1  mbalmer 
   7474   1.1  mbalmer <p>
   7475   1.2    lneto If the function argument <code>arg</code> is a number,
   7476   1.9   nikita returns this number as a <code>lua_Number</code>.
   7477   1.1  mbalmer If this argument is absent or is <b>nil</b>,
   7478   1.1  mbalmer returns <code>d</code>.
   7479   1.1  mbalmer Otherwise, raises an error.
   7480   1.1  mbalmer 
   7481   1.1  mbalmer 
   7482   1.1  mbalmer 
   7483   1.1  mbalmer 
   7484   1.1  mbalmer 
   7485   1.1  mbalmer <hr><h3><a name="luaL_optstring"><code>luaL_optstring</code></a></h3><p>
   7486   1.1  mbalmer <span class="apii">[-0, +0, <em>v</em>]</span>
   7487   1.1  mbalmer <pre>const char *luaL_optstring (lua_State *L,
   7488   1.2    lneto                             int arg,
   7489   1.1  mbalmer                             const char *d);</pre>
   7490   1.1  mbalmer 
   7491   1.1  mbalmer <p>
   7492   1.2    lneto If the function argument <code>arg</code> is a string,
   7493   1.1  mbalmer returns this string.
   7494   1.1  mbalmer If this argument is absent or is <b>nil</b>,
   7495   1.1  mbalmer returns <code>d</code>.
   7496   1.1  mbalmer Otherwise, raises an error.
   7497   1.1  mbalmer 
   7498   1.1  mbalmer 
   7499   1.1  mbalmer 
   7500   1.1  mbalmer 
   7501   1.1  mbalmer 
   7502   1.1  mbalmer <hr><h3><a name="luaL_prepbuffer"><code>luaL_prepbuffer</code></a></h3><p>
   7503   1.5    lneto <span class="apii">[-?, +?, <em>m</em>]</span>
   7504   1.1  mbalmer <pre>char *luaL_prepbuffer (luaL_Buffer *B);</pre>
   7505   1.1  mbalmer 
   7506   1.1  mbalmer <p>
   7507   1.2    lneto Equivalent to <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a>
   7508   1.2    lneto with the predefined size <a name="pdf-LUAL_BUFFERSIZE"><code>LUAL_BUFFERSIZE</code></a>.
   7509   1.2    lneto 
   7510   1.2    lneto 
   7511   1.2    lneto 
   7512   1.2    lneto 
   7513   1.2    lneto 
   7514   1.2    lneto <hr><h3><a name="luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a></h3><p>
   7515   1.5    lneto <span class="apii">[-?, +?, <em>m</em>]</span>
   7516   1.2    lneto <pre>char *luaL_prepbuffsize (luaL_Buffer *B, size_t sz);</pre>
   7517   1.2    lneto 
   7518   1.2    lneto <p>
   7519   1.2    lneto Returns an address to a space of size <code>sz</code>
   7520   1.1  mbalmer where you can copy a string to be added to buffer <code>B</code>
   7521   1.1  mbalmer (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
   7522   1.1  mbalmer After copying the string into this space you must call
   7523   1.2    lneto <a href="#luaL_addsize"><code>luaL_addsize</code></a> with the size of the string to actually add
   7524   1.1  mbalmer it to the buffer.
   7525   1.1  mbalmer 
   7526   1.1  mbalmer 
   7527   1.1  mbalmer 
   7528   1.1  mbalmer 
   7529   1.1  mbalmer 
   7530   1.9   nikita <hr><h3><a name="luaL_pushfail"><code>luaL_pushfail</code></a></h3><p>
   7531   1.9   nikita <span class="apii">[-0, +1, &ndash;]</span>
   7532   1.9   nikita <pre>void luaL_pushfail (lua_State *L);</pre>
   7533   1.9   nikita 
   7534   1.9   nikita <p>
   7535   1.9   nikita Pushes the <b>fail</b> value onto the stack (see <a href="#6">&sect;6</a>).
   7536   1.9   nikita 
   7537   1.9   nikita 
   7538   1.9   nikita 
   7539   1.9   nikita 
   7540   1.9   nikita 
   7541   1.1  mbalmer <hr><h3><a name="luaL_pushresult"><code>luaL_pushresult</code></a></h3><p>
   7542   1.5    lneto <span class="apii">[-?, +1, <em>m</em>]</span>
   7543   1.1  mbalmer <pre>void luaL_pushresult (luaL_Buffer *B);</pre>
   7544   1.1  mbalmer 
   7545   1.1  mbalmer <p>
   7546   1.1  mbalmer Finishes the use of buffer <code>B</code> leaving the final string on
   7547   1.1  mbalmer the top of the stack.
   7548   1.1  mbalmer 
   7549   1.1  mbalmer 
   7550   1.1  mbalmer 
   7551   1.1  mbalmer 
   7552   1.1  mbalmer 
   7553   1.2    lneto <hr><h3><a name="luaL_pushresultsize"><code>luaL_pushresultsize</code></a></h3><p>
   7554   1.5    lneto <span class="apii">[-?, +1, <em>m</em>]</span>
   7555   1.2    lneto <pre>void luaL_pushresultsize (luaL_Buffer *B, size_t sz);</pre>
   7556   1.2    lneto 
   7557   1.2    lneto <p>
   7558   1.2    lneto Equivalent to the sequence <a href="#luaL_addsize"><code>luaL_addsize</code></a>, <a href="#luaL_pushresult"><code>luaL_pushresult</code></a>.
   7559   1.2    lneto 
   7560   1.2    lneto 
   7561   1.2    lneto 
   7562   1.2    lneto 
   7563   1.2    lneto 
   7564   1.1  mbalmer <hr><h3><a name="luaL_ref"><code>luaL_ref</code></a></h3><p>
   7565   1.5    lneto <span class="apii">[-1, +0, <em>m</em>]</span>
   7566   1.1  mbalmer <pre>int luaL_ref (lua_State *L, int t);</pre>
   7567   1.1  mbalmer 
   7568   1.1  mbalmer <p>
   7569   1.1  mbalmer Creates and returns a <em>reference</em>,
   7570   1.1  mbalmer in the table at index <code>t</code>,
   7571   1.9   nikita for the object on the top of the stack (and pops the object).
   7572   1.1  mbalmer 
   7573   1.1  mbalmer 
   7574   1.1  mbalmer <p>
   7575   1.1  mbalmer A reference is a unique integer key.
   7576   1.9   nikita As long as you do not manually add integer keys into the table <code>t</code>,
   7577   1.1  mbalmer <a href="#luaL_ref"><code>luaL_ref</code></a> ensures the uniqueness of the key it returns.
   7578   1.9   nikita You can retrieve an object referred by the reference <code>r</code>
   7579   1.1  mbalmer by calling <code>lua_rawgeti(L, t, r)</code>.
   7580   1.9   nikita The function <a href="#luaL_unref"><code>luaL_unref</code></a> frees a reference.
   7581   1.1  mbalmer 
   7582   1.1  mbalmer 
   7583   1.1  mbalmer <p>
   7584   1.9   nikita If the object on the top of the stack is <b>nil</b>,
   7585   1.1  mbalmer <a href="#luaL_ref"><code>luaL_ref</code></a> returns the constant <a name="pdf-LUA_REFNIL"><code>LUA_REFNIL</code></a>.
   7586   1.1  mbalmer The constant <a name="pdf-LUA_NOREF"><code>LUA_NOREF</code></a> is guaranteed to be different
   7587   1.1  mbalmer from any reference returned by <a href="#luaL_ref"><code>luaL_ref</code></a>.
   7588   1.1  mbalmer 
   7589   1.1  mbalmer 
   7590   1.1  mbalmer 
   7591   1.1  mbalmer 
   7592   1.1  mbalmer 
   7593   1.1  mbalmer <hr><h3><a name="luaL_Reg"><code>luaL_Reg</code></a></h3>
   7594   1.1  mbalmer <pre>typedef struct luaL_Reg {
   7595   1.1  mbalmer   const char *name;
   7596   1.1  mbalmer   lua_CFunction func;
   7597   1.1  mbalmer } luaL_Reg;</pre>
   7598   1.1  mbalmer 
   7599   1.1  mbalmer <p>
   7600   1.1  mbalmer Type for arrays of functions to be registered by
   7601   1.2    lneto <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a>.
   7602   1.1  mbalmer <code>name</code> is the function name and <code>func</code> is a pointer to
   7603   1.1  mbalmer the function.
   7604   1.3    lneto Any array of <a href="#luaL_Reg"><code>luaL_Reg</code></a> must end with a sentinel entry
   7605   1.1  mbalmer in which both <code>name</code> and <code>func</code> are <code>NULL</code>.
   7606   1.1  mbalmer 
   7607   1.1  mbalmer 
   7608   1.1  mbalmer 
   7609   1.1  mbalmer 
   7610   1.1  mbalmer 
   7611   1.2    lneto <hr><h3><a name="luaL_requiref"><code>luaL_requiref</code></a></h3><p>
   7612   1.2    lneto <span class="apii">[-0, +1, <em>e</em>]</span>
   7613   1.2    lneto <pre>void luaL_requiref (lua_State *L, const char *modname,
   7614   1.2    lneto                     lua_CFunction openf, int glb);</pre>
   7615   1.2    lneto 
   7616   1.2    lneto <p>
   7617   1.9   nikita If <code>package.loaded[modname]</code> is not true,
   7618   1.9   nikita calls the function <code>openf</code> with the string <code>modname</code> as an argument
   7619   1.9   nikita and sets the call result to <code>package.loaded[modname]</code>,
   7620   1.2    lneto as if that function has been called through <a href="#pdf-require"><code>require</code></a>.
   7621   1.2    lneto 
   7622   1.2    lneto 
   7623   1.2    lneto <p>
   7624   1.2    lneto If <code>glb</code> is true,
   7625   1.9   nikita also stores the module into the global <code>modname</code>.
   7626   1.2    lneto 
   7627   1.2    lneto 
   7628   1.2    lneto <p>
   7629   1.3    lneto Leaves a copy of the module on the stack.
   7630   1.2    lneto 
   7631   1.2    lneto 
   7632   1.2    lneto 
   7633   1.2    lneto 
   7634   1.2    lneto 
   7635   1.2    lneto <hr><h3><a name="luaL_setfuncs"><code>luaL_setfuncs</code></a></h3><p>
   7636   1.5    lneto <span class="apii">[-nup, +0, <em>m</em>]</span>
   7637   1.2    lneto <pre>void luaL_setfuncs (lua_State *L, const luaL_Reg *l, int nup);</pre>
   7638   1.2    lneto 
   7639   1.2    lneto <p>
   7640   1.2    lneto Registers all functions in the array <code>l</code>
   7641   1.2    lneto (see <a href="#luaL_Reg"><code>luaL_Reg</code></a>) into the table on the top of the stack
   7642   1.2    lneto (below optional upvalues, see next).
   7643   1.2    lneto 
   7644   1.1  mbalmer 
   7645   1.1  mbalmer <p>
   7646   1.2    lneto When <code>nup</code> is not zero,
   7647   1.9   nikita all functions are created with <code>nup</code> upvalues,
   7648   1.9   nikita initialized with copies of the <code>nup</code> values
   7649   1.9   nikita previously pushed on the stack
   7650   1.2    lneto on top of the library table.
   7651   1.2    lneto These values are popped from the stack after the registration.
   7652   1.1  mbalmer 
   7653   1.1  mbalmer 
   7654   1.9   nikita <p>
   7655   1.9   nikita A function with a <code>NULL</code> value represents a placeholder,
   7656   1.9   nikita which is filled with <b>false</b>.
   7657   1.9   nikita 
   7658   1.9   nikita 
   7659   1.2    lneto 
   7660   1.2    lneto 
   7661   1.2    lneto 
   7662   1.2    lneto <hr><h3><a name="luaL_setmetatable"><code>luaL_setmetatable</code></a></h3><p>
   7663   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   7664   1.2    lneto <pre>void luaL_setmetatable (lua_State *L, const char *tname);</pre>
   7665   1.2    lneto 
   7666   1.2    lneto <p>
   7667   1.9   nikita Sets the metatable of the object on the top of the stack
   7668   1.2    lneto as the metatable associated with name <code>tname</code>
   7669   1.2    lneto in the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>).
   7670   1.2    lneto 
   7671   1.2    lneto 
   7672   1.2    lneto 
   7673   1.2    lneto 
   7674   1.2    lneto 
   7675   1.2    lneto <hr><h3><a name="luaL_Stream"><code>luaL_Stream</code></a></h3>
   7676   1.2    lneto <pre>typedef struct luaL_Stream {
   7677   1.2    lneto   FILE *f;
   7678   1.2    lneto   lua_CFunction closef;
   7679   1.2    lneto } luaL_Stream;</pre>
   7680   1.2    lneto 
   7681   1.1  mbalmer <p>
   7682   1.9   nikita The standard representation for file handles
   7683   1.9   nikita used by the standard I/O library.
   7684   1.1  mbalmer 
   7685   1.1  mbalmer 
   7686   1.1  mbalmer <p>
   7687   1.2    lneto A file handle is implemented as a full userdata,
   7688   1.3    lneto with a metatable called <code>LUA_FILEHANDLE</code>
   7689   1.3    lneto (where <code>LUA_FILEHANDLE</code> is a macro with the actual metatable's name).
   7690   1.2    lneto The metatable is created by the I/O library
   7691   1.2    lneto (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>).
   7692   1.2    lneto 
   7693   1.2    lneto 
   7694   1.2    lneto <p>
   7695   1.2    lneto This userdata must start with the structure <code>luaL_Stream</code>;
   7696   1.2    lneto it can contain other data after this initial structure.
   7697   1.9   nikita The field <code>f</code> points to the corresponding C stream
   7698   1.2    lneto (or it can be <code>NULL</code> to indicate an incompletely created handle).
   7699   1.9   nikita The field <code>closef</code> points to a Lua function
   7700   1.2    lneto that will be called to close the stream
   7701   1.2    lneto when the handle is closed or collected;
   7702   1.2    lneto this function receives the file handle as its sole argument and
   7703   1.9   nikita must return either a true value, in case of success,
   7704   1.9   nikita or a false value plus an error message, in case of error.
   7705   1.2    lneto Once Lua calls this field,
   7706   1.5    lneto it changes the field value to <code>NULL</code>
   7707   1.3    lneto to signal that the handle is closed.
   7708   1.2    lneto 
   7709   1.1  mbalmer 
   7710   1.1  mbalmer 
   7711   1.2    lneto 
   7712   1.2    lneto 
   7713   1.2    lneto <hr><h3><a name="luaL_testudata"><code>luaL_testudata</code></a></h3><p>
   7714   1.5    lneto <span class="apii">[-0, +0, <em>m</em>]</span>
   7715   1.2    lneto <pre>void *luaL_testudata (lua_State *L, int arg, const char *tname);</pre>
   7716   1.2    lneto 
   7717   1.1  mbalmer <p>
   7718   1.2    lneto This function works like <a href="#luaL_checkudata"><code>luaL_checkudata</code></a>,
   7719   1.2    lneto except that, when the test fails,
   7720   1.2    lneto it returns <code>NULL</code> instead of raising an error.
   7721   1.1  mbalmer 
   7722   1.1  mbalmer 
   7723   1.1  mbalmer 
   7724   1.1  mbalmer 
   7725   1.1  mbalmer 
   7726   1.2    lneto <hr><h3><a name="luaL_tolstring"><code>luaL_tolstring</code></a></h3><p>
   7727   1.2    lneto <span class="apii">[-0, +1, <em>e</em>]</span>
   7728   1.2    lneto <pre>const char *luaL_tolstring (lua_State *L, int idx, size_t *len);</pre>
   7729   1.2    lneto 
   7730   1.2    lneto <p>
   7731   1.2    lneto Converts any Lua value at the given index to a C&nbsp;string
   7732   1.2    lneto in a reasonable format.
   7733   1.2    lneto The resulting string is pushed onto the stack and also
   7734   1.9   nikita returned by the function (see <a href="#4.1.3">&sect;4.1.3</a>).
   7735   1.2    lneto If <code>len</code> is not <code>NULL</code>,
   7736   1.2    lneto the function also sets <code>*len</code> with the string length.
   7737   1.2    lneto 
   7738   1.1  mbalmer 
   7739   1.1  mbalmer <p>
   7740   1.6  salazar If the value has a metatable with a <code>__tostring</code> field,
   7741   1.2    lneto then <code>luaL_tolstring</code> calls the corresponding metamethod
   7742   1.2    lneto with the value as argument,
   7743   1.2    lneto and uses the result of the call as its result.
   7744   1.1  mbalmer 
   7745   1.1  mbalmer 
   7746   1.1  mbalmer 
   7747   1.1  mbalmer 
   7748   1.1  mbalmer 
   7749   1.2    lneto <hr><h3><a name="luaL_traceback"><code>luaL_traceback</code></a></h3><p>
   7750   1.5    lneto <span class="apii">[-0, +1, <em>m</em>]</span>
   7751   1.2    lneto <pre>void luaL_traceback (lua_State *L, lua_State *L1, const char *msg,
   7752   1.2    lneto                      int level);</pre>
   7753   1.1  mbalmer 
   7754   1.1  mbalmer <p>
   7755   1.2    lneto Creates and pushes a traceback of the stack <code>L1</code>.
   7756   1.9   nikita If <code>msg</code> is not <code>NULL</code>, it is appended
   7757   1.2    lneto at the beginning of the traceback.
   7758   1.2    lneto The <code>level</code> parameter tells at which level
   7759   1.2    lneto to start the traceback.
   7760   1.1  mbalmer 
   7761   1.2    lneto 
   7762   1.2    lneto 
   7763   1.2    lneto 
   7764   1.2    lneto 
   7765   1.9   nikita <hr><h3><a name="luaL_typeerror"><code>luaL_typeerror</code></a></h3><p>
   7766   1.9   nikita <span class="apii">[-0, +0, <em>v</em>]</span>
   7767  1.10   nikita <pre>int luaL_typeerror (lua_State *L, int arg, const char *tname);</pre>
   7768   1.9   nikita 
   7769   1.9   nikita <p>
   7770   1.9   nikita Raises a type error for the argument <code>arg</code>
   7771   1.9   nikita of the C&nbsp;function that called it,
   7772   1.9   nikita using a standard message;
   7773   1.9   nikita <code>tname</code> is a "name" for the expected type.
   7774   1.9   nikita This function never returns.
   7775   1.9   nikita 
   7776   1.9   nikita 
   7777   1.9   nikita 
   7778   1.9   nikita 
   7779   1.9   nikita 
   7780   1.2    lneto <hr><h3><a name="luaL_typename"><code>luaL_typename</code></a></h3><p>
   7781   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   7782   1.2    lneto <pre>const char *luaL_typename (lua_State *L, int index);</pre>
   7783   1.2    lneto 
   7784   1.2    lneto <p>
   7785   1.2    lneto Returns the name of the type of the value at the given index.
   7786   1.1  mbalmer 
   7787   1.1  mbalmer 
   7788   1.1  mbalmer 
   7789   1.1  mbalmer 
   7790   1.1  mbalmer 
   7791   1.1  mbalmer <hr><h3><a name="luaL_unref"><code>luaL_unref</code></a></h3><p>
   7792   1.2    lneto <span class="apii">[-0, +0, &ndash;]</span>
   7793   1.1  mbalmer <pre>void luaL_unref (lua_State *L, int t, int ref);</pre>
   7794   1.1  mbalmer 
   7795   1.1  mbalmer <p>
   7796   1.9   nikita Releases the reference <code>ref</code> from the table at index <code>t</code>
   7797   1.1  mbalmer (see <a href="#luaL_ref"><code>luaL_ref</code></a>).
   7798   1.1  mbalmer The entry is removed from the table,
   7799   1.1  mbalmer so that the referred object can be collected.
   7800   1.1  mbalmer The reference <code>ref</code> is also freed to be used again.
   7801   1.1  mbalmer 
   7802   1.1  mbalmer 
   7803   1.1  mbalmer <p>
   7804   1.1  mbalmer If <code>ref</code> is <a href="#pdf-LUA_NOREF"><code>LUA_NOREF</code></a> or <a href="#pdf-LUA_REFNIL"><code>LUA_REFNIL</code></a>,
   7805   1.1  mbalmer <a href="#luaL_unref"><code>luaL_unref</code></a> does nothing.
   7806   1.1  mbalmer 
   7807   1.1  mbalmer 
   7808   1.1  mbalmer 
   7809   1.1  mbalmer 
   7810   1.1  mbalmer 
   7811   1.1  mbalmer <hr><h3><a name="luaL_where"><code>luaL_where</code></a></h3><p>
   7812   1.5    lneto <span class="apii">[-0, +1, <em>m</em>]</span>
   7813   1.1  mbalmer <pre>void luaL_where (lua_State *L, int lvl);</pre>
   7814   1.1  mbalmer 
   7815   1.1  mbalmer <p>
   7816   1.1  mbalmer Pushes onto the stack a string identifying the current position
   7817   1.1  mbalmer of the control at level <code>lvl</code> in the call stack.
   7818   1.1  mbalmer Typically this string has the following format:
   7819   1.1  mbalmer 
   7820   1.1  mbalmer <pre>
   7821   1.1  mbalmer      <em>chunkname</em>:<em>currentline</em>:
   7822   1.1  mbalmer </pre><p>
   7823   1.1  mbalmer Level&nbsp;0 is the running function,
   7824   1.1  mbalmer level&nbsp;1 is the function that called the running function,
   7825   1.1  mbalmer etc.
   7826   1.1  mbalmer 
   7827   1.1  mbalmer 
   7828   1.1  mbalmer <p>
   7829   1.1  mbalmer This function is used to build a prefix for error messages.
   7830   1.1  mbalmer 
   7831   1.1  mbalmer 
   7832   1.1  mbalmer 
   7833   1.1  mbalmer 
   7834   1.1  mbalmer 
   7835   1.1  mbalmer 
   7836   1.1  mbalmer 
   7837   1.9   nikita <h1>6 &ndash; <a name="6">The Standard Libraries</a></h1>
   7838   1.9   nikita 
   7839   1.9   nikita 
   7840   1.1  mbalmer 
   7841   1.1  mbalmer <p>
   7842   1.1  mbalmer The standard Lua libraries provide useful functions
   7843   1.9   nikita that are implemented in&nbsp;C through the C&nbsp;API.
   7844   1.1  mbalmer Some of these functions provide essential services to the language
   7845   1.1  mbalmer (e.g., <a href="#pdf-type"><code>type</code></a> and <a href="#pdf-getmetatable"><code>getmetatable</code></a>);
   7846   1.9   nikita others provide access to outside services (e.g., I/O);
   7847   1.1  mbalmer and others could be implemented in Lua itself,
   7848   1.9   nikita but that for different reasons
   7849   1.1  mbalmer deserve an implementation in C (e.g., <a href="#pdf-table.sort"><code>table.sort</code></a>).
   7850   1.1  mbalmer 
   7851   1.1  mbalmer 
   7852   1.1  mbalmer <p>
   7853   1.1  mbalmer All libraries are implemented through the official C&nbsp;API
   7854   1.1  mbalmer and are provided as separate C&nbsp;modules.
   7855   1.9   nikita Unless otherwise noted,
   7856   1.9   nikita these library functions do not adjust its number of arguments
   7857   1.9   nikita to its expected parameters.
   7858   1.9   nikita For instance, a function documented as <code>foo(arg)</code>
   7859   1.9   nikita should not be called without an argument.
   7860   1.9   nikita 
   7861   1.9   nikita 
   7862   1.9   nikita <p>
   7863   1.9   nikita The notation <b>fail</b> means a false value representing
   7864   1.9   nikita some kind of failure.
   7865   1.9   nikita (Currently, <b>fail</b> is equal to <b>nil</b>,
   7866   1.9   nikita but that may change in future versions.
   7867   1.9   nikita The recommendation is to always test the success of these functions
   7868   1.9   nikita with <code>(not status)</code>, instead of <code>(status == nil)</code>.)
   7869   1.9   nikita 
   7870   1.9   nikita 
   7871   1.9   nikita <p>
   7872   1.1  mbalmer Currently, Lua has the following standard libraries:
   7873   1.1  mbalmer 
   7874   1.1  mbalmer <ul>
   7875   1.1  mbalmer 
   7876   1.2    lneto <li>basic library (<a href="#6.1">&sect;6.1</a>);</li>
   7877   1.1  mbalmer 
   7878   1.2    lneto <li>coroutine library (<a href="#6.2">&sect;6.2</a>);</li>
   7879   1.1  mbalmer 
   7880   1.2    lneto <li>package library (<a href="#6.3">&sect;6.3</a>);</li>
   7881   1.1  mbalmer 
   7882   1.2    lneto <li>string manipulation (<a href="#6.4">&sect;6.4</a>);</li>
   7883   1.1  mbalmer 
   7884   1.2    lneto <li>basic UTF-8 support (<a href="#6.5">&sect;6.5</a>);</li>
   7885   1.1  mbalmer 
   7886   1.2    lneto <li>table manipulation (<a href="#6.6">&sect;6.6</a>);</li>
   7887   1.1  mbalmer 
   7888   1.2    lneto <li>mathematical functions (<a href="#6.7">&sect;6.7</a>) (sin, log, etc.);</li>
   7889   1.1  mbalmer 
   7890   1.2    lneto <li>input and output (<a href="#6.8">&sect;6.8</a>);</li>
   7891   1.2    lneto 
   7892   1.2    lneto <li>operating system facilities (<a href="#6.9">&sect;6.9</a>);</li>
   7893   1.2    lneto 
   7894   1.2    lneto <li>debug facilities (<a href="#6.10">&sect;6.10</a>).</li>
   7895   1.1  mbalmer 
   7896   1.1  mbalmer </ul><p>
   7897   1.2    lneto Except for the basic and the package libraries,
   7898   1.1  mbalmer each library provides all its functions as fields of a global table
   7899   1.1  mbalmer or as methods of its objects.
   7900   1.1  mbalmer 
   7901   1.1  mbalmer 
   7902   1.1  mbalmer <p>
   7903   1.1  mbalmer To have access to these libraries,
   7904   1.1  mbalmer the C&nbsp;host program should call the <a href="#luaL_openlibs"><code>luaL_openlibs</code></a> function,
   7905   1.1  mbalmer which opens all standard libraries.
   7906   1.1  mbalmer Alternatively,
   7907   1.2    lneto the host program can open them individually by using
   7908   1.2    lneto <a href="#luaL_requiref"><code>luaL_requiref</code></a> to call
   7909   1.1  mbalmer <a name="pdf-luaopen_base"><code>luaopen_base</code></a> (for the basic library),
   7910   1.1  mbalmer <a name="pdf-luaopen_package"><code>luaopen_package</code></a> (for the package library),
   7911   1.2    lneto <a name="pdf-luaopen_coroutine"><code>luaopen_coroutine</code></a> (for the coroutine library),
   7912   1.1  mbalmer <a name="pdf-luaopen_string"><code>luaopen_string</code></a> (for the string library),
   7913   1.9   nikita <a name="pdf-luaopen_utf8"><code>luaopen_utf8</code></a> (for the UTF-8 library),
   7914   1.1  mbalmer <a name="pdf-luaopen_table"><code>luaopen_table</code></a> (for the table library),
   7915   1.1  mbalmer <a name="pdf-luaopen_math"><code>luaopen_math</code></a> (for the mathematical library),
   7916   1.1  mbalmer <a name="pdf-luaopen_io"><code>luaopen_io</code></a> (for the I/O library),
   7917   1.3    lneto <a name="pdf-luaopen_os"><code>luaopen_os</code></a> (for the operating system library),
   7918   1.1  mbalmer and <a name="pdf-luaopen_debug"><code>luaopen_debug</code></a> (for the debug library).
   7919   1.2    lneto These functions are declared in <a name="pdf-lualib.h"><code>lualib.h</code></a>.
   7920   1.1  mbalmer 
   7921   1.1  mbalmer 
   7922   1.1  mbalmer 
   7923   1.9   nikita 
   7924   1.9   nikita 
   7925   1.2    lneto <h2>6.1 &ndash; <a name="6.1">Basic Functions</a></h2>
   7926   1.1  mbalmer 
   7927   1.1  mbalmer <p>
   7928   1.2    lneto The basic library provides core functions to Lua.
   7929   1.1  mbalmer If you do not include this library in your application,
   7930   1.2    lneto you should check carefully whether you need to provide
   7931   1.1  mbalmer implementations for some of its facilities.
   7932   1.1  mbalmer 
   7933   1.1  mbalmer 
   7934   1.1  mbalmer <p>
   7935   1.1  mbalmer <hr><h3><a name="pdf-assert"><code>assert (v [, message])</code></a></h3>
   7936   1.2    lneto 
   7937   1.2    lneto 
   7938   1.2    lneto <p>
   7939   1.9   nikita Raises an error if
   7940   1.1  mbalmer the value of its argument <code>v</code> is false (i.e., <b>nil</b> or <b>false</b>);
   7941   1.1  mbalmer otherwise, returns all its arguments.
   7942   1.2    lneto In case of error,
   7943   1.2    lneto <code>message</code> is the error object;
   7944   1.2    lneto when absent, it defaults to "<code>assertion failed!</code>"
   7945   1.1  mbalmer 
   7946   1.1  mbalmer 
   7947   1.1  mbalmer 
   7948   1.1  mbalmer 
   7949   1.1  mbalmer <p>
   7950   1.2    lneto <hr><h3><a name="pdf-collectgarbage"><code>collectgarbage ([opt [, arg]])</code></a></h3>
   7951   1.1  mbalmer 
   7952   1.1  mbalmer 
   7953   1.1  mbalmer <p>
   7954   1.1  mbalmer This function is a generic interface to the garbage collector.
   7955   1.1  mbalmer It performs different functions according to its first argument, <code>opt</code>:
   7956   1.1  mbalmer 
   7957   1.1  mbalmer <ul>
   7958   1.1  mbalmer 
   7959   1.2    lneto <li><b>"<code>collect</code>": </b>
   7960   1.9   nikita Performs a full garbage-collection cycle.
   7961   1.2    lneto This is the default option.
   7962   1.1  mbalmer </li>
   7963   1.1  mbalmer 
   7964   1.2    lneto <li><b>"<code>stop</code>": </b>
   7965   1.9   nikita Stops automatic execution of the garbage collector.
   7966   1.2    lneto The collector will run only when explicitly invoked,
   7967   1.2    lneto until a call to restart it.
   7968   1.1  mbalmer </li>
   7969   1.1  mbalmer 
   7970   1.2    lneto <li><b>"<code>restart</code>": </b>
   7971   1.9   nikita Restarts automatic execution of the garbage collector.
   7972   1.1  mbalmer </li>
   7973   1.1  mbalmer 
   7974   1.2    lneto <li><b>"<code>count</code>": </b>
   7975   1.9   nikita Returns the total memory in use by Lua in Kbytes.
   7976   1.2    lneto The value has a fractional part,
   7977   1.2    lneto so that it multiplied by 1024
   7978   1.9   nikita gives the exact number of bytes in use by Lua.
   7979   1.1  mbalmer </li>
   7980   1.1  mbalmer 
   7981   1.2    lneto <li><b>"<code>step</code>": </b>
   7982   1.9   nikita Performs a garbage-collection step.
   7983   1.2    lneto The step "size" is controlled by <code>arg</code>.
   7984   1.2    lneto With a zero value,
   7985   1.2    lneto the collector will perform one basic (indivisible) step.
   7986   1.2    lneto For non-zero values,
   7987   1.2    lneto the collector will perform as if that amount of memory
   7988   1.9   nikita (in Kbytes) had been allocated by Lua.
   7989   1.1  mbalmer Returns <b>true</b> if the step finished a collection cycle.
   7990   1.1  mbalmer </li>
   7991   1.1  mbalmer 
   7992   1.9   nikita <li><b>"<code>isrunning</code>": </b>
   7993   1.9   nikita Returns a boolean that tells whether the collector is running
   7994   1.9   nikita (i.e., not stopped).
   7995   1.1  mbalmer </li>
   7996   1.1  mbalmer 
   7997   1.9   nikita <li><b>"<code>incremental</code>": </b>
   7998   1.9   nikita Change the collector mode to incremental.
   7999   1.9   nikita This option can be followed by three numbers:
   8000   1.9   nikita the garbage-collector pause,
   8001   1.9   nikita the step multiplier,
   8002   1.9   nikita and the step size (see <a href="#2.5.1">&sect;2.5.1</a>).
   8003   1.9   nikita A zero means to not change that value.
   8004   1.1  mbalmer </li>
   8005   1.1  mbalmer 
   8006   1.9   nikita <li><b>"<code>generational</code>": </b>
   8007   1.9   nikita Change the collector mode to generational.
   8008   1.9   nikita This option can be followed by two numbers:
   8009   1.9   nikita the garbage-collector minor multiplier
   8010   1.9   nikita and the major multiplier (see <a href="#2.5.2">&sect;2.5.2</a>).
   8011   1.9   nikita A zero means to not change that value.
   8012   1.2    lneto </li>
   8013   1.2    lneto 
   8014   1.9   nikita </ul><p>
   8015   1.9   nikita See <a href="#2.5">&sect;2.5</a> for more details about garbage collection
   8016   1.9   nikita and some of these options.
   8017   1.9   nikita 
   8018   1.9   nikita 
   8019   1.9   nikita <p>
   8020   1.9   nikita This function should not be called by a finalizer.
   8021   1.9   nikita 
   8022   1.1  mbalmer 
   8023   1.1  mbalmer 
   8024   1.1  mbalmer 
   8025   1.1  mbalmer <p>
   8026   1.2    lneto <hr><h3><a name="pdf-dofile"><code>dofile ([filename])</code></a></h3>
   8027   1.9   nikita Opens the named file and executes its content as a Lua chunk.
   8028   1.1  mbalmer When called without arguments,
   8029   1.9   nikita <code>dofile</code> executes the content of the standard input (<code>stdin</code>).
   8030   1.1  mbalmer Returns all values returned by the chunk.
   8031   1.1  mbalmer In case of errors, <code>dofile</code> propagates the error
   8032   1.9   nikita to its caller.
   8033   1.9   nikita (That is, <code>dofile</code> does not run in protected mode.)
   8034   1.1  mbalmer 
   8035   1.1  mbalmer 
   8036   1.1  mbalmer 
   8037   1.1  mbalmer 
   8038   1.1  mbalmer <p>
   8039   1.1  mbalmer <hr><h3><a name="pdf-error"><code>error (message [, level])</code></a></h3>
   8040   1.9   nikita Raises an error (see <a href="#2.3">&sect;2.3</a>) with <code>message</code> as the error object.
   8041   1.9   nikita This function never returns.
   8042   1.1  mbalmer 
   8043   1.1  mbalmer 
   8044   1.1  mbalmer <p>
   8045   1.1  mbalmer Usually, <code>error</code> adds some information about the error position
   8046   1.2    lneto at the beginning of the message, if the message is a string.
   8047   1.1  mbalmer The <code>level</code> argument specifies how to get the error position.
   8048   1.1  mbalmer With level&nbsp;1 (the default), the error position is where the
   8049   1.1  mbalmer <code>error</code> function was called.
   8050   1.1  mbalmer Level&nbsp;2 points the error to where the function
   8051   1.1  mbalmer that called <code>error</code> was called; and so on.
   8052   1.1  mbalmer Passing a level&nbsp;0 avoids the addition of error position information
   8053   1.1  mbalmer to the message.
   8054   1.1  mbalmer 
   8055   1.1  mbalmer 
   8056   1.1  mbalmer 
   8057   1.1  mbalmer 
   8058   1.1  mbalmer <p>
   8059   1.1  mbalmer <hr><h3><a name="pdf-_G"><code>_G</code></a></h3>
   8060   1.1  mbalmer A global variable (not a function) that
   8061   1.2    lneto holds the global environment (see <a href="#2.2">&sect;2.2</a>).
   8062   1.1  mbalmer Lua itself does not use this variable;
   8063   1.1  mbalmer changing its value does not affect any environment,
   8064   1.2    lneto nor vice versa.
   8065   1.1  mbalmer 
   8066   1.1  mbalmer 
   8067   1.1  mbalmer 
   8068   1.1  mbalmer 
   8069   1.1  mbalmer <p>
   8070   1.1  mbalmer <hr><h3><a name="pdf-getmetatable"><code>getmetatable (object)</code></a></h3>
   8071   1.1  mbalmer 
   8072   1.1  mbalmer 
   8073   1.1  mbalmer <p>
   8074   1.1  mbalmer If <code>object</code> does not have a metatable, returns <b>nil</b>.
   8075   1.1  mbalmer Otherwise,
   8076   1.6  salazar if the object's metatable has a <code>__metatable</code> field,
   8077   1.1  mbalmer returns the associated value.
   8078   1.1  mbalmer Otherwise, returns the metatable of the given object.
   8079   1.1  mbalmer 
   8080   1.1  mbalmer 
   8081   1.1  mbalmer 
   8082   1.1  mbalmer 
   8083   1.1  mbalmer <p>
   8084   1.1  mbalmer <hr><h3><a name="pdf-ipairs"><code>ipairs (t)</code></a></h3>
   8085   1.1  mbalmer 
   8086   1.1  mbalmer 
   8087   1.1  mbalmer <p>
   8088   1.3    lneto Returns three values (an iterator function, the table <code>t</code>, and 0)
   8089   1.1  mbalmer so that the construction
   8090   1.1  mbalmer 
   8091   1.1  mbalmer <pre>
   8092   1.1  mbalmer      for i,v in ipairs(t) do <em>body</em> end
   8093   1.1  mbalmer </pre><p>
   8094   1.3    lneto will iterate over the key&ndash;value pairs
   8095   1.3    lneto (<code>1,t[1]</code>), (<code>2,t[2]</code>), ...,
   8096   1.9   nikita up to the first absent index.
   8097   1.1  mbalmer 
   8098   1.1  mbalmer 
   8099   1.1  mbalmer 
   8100   1.1  mbalmer 
   8101   1.1  mbalmer <p>
   8102   1.3    lneto <hr><h3><a name="pdf-load"><code>load (chunk [, chunkname [, mode [, env]]])</code></a></h3>
   8103   1.1  mbalmer 
   8104   1.1  mbalmer 
   8105   1.1  mbalmer <p>
   8106   1.2    lneto Loads a chunk.
   8107   1.2    lneto 
   8108   1.2    lneto 
   8109   1.2    lneto <p>
   8110   1.3    lneto If <code>chunk</code> is a string, the chunk is this string.
   8111   1.3    lneto If <code>chunk</code> is a function,
   8112   1.2    lneto <code>load</code> calls it repeatedly to get the chunk pieces.
   8113   1.3    lneto Each call to <code>chunk</code> must return a string that concatenates
   8114   1.1  mbalmer with previous results.
   8115   1.1  mbalmer A return of an empty string, <b>nil</b>, or no value signals the end of the chunk.
   8116   1.1  mbalmer 
   8117   1.1  mbalmer 
   8118   1.1  mbalmer <p>
   8119   1.2    lneto If there are no syntactic errors,
   8120   1.9   nikita <code>load</code> returns the compiled chunk as a function;
   8121   1.9   nikita otherwise, it returns <b>fail</b> plus the error message.
   8122   1.1  mbalmer 
   8123   1.1  mbalmer 
   8124   1.1  mbalmer <p>
   8125   1.9   nikita When you load a main chunk,
   8126   1.2    lneto the resulting function will always have exactly one upvalue,
   8127   1.2    lneto the <code>_ENV</code> variable (see <a href="#2.2">&sect;2.2</a>).
   8128   1.3    lneto However,
   8129   1.3    lneto when you load a binary chunk created from a function (see <a href="#pdf-string.dump"><code>string.dump</code></a>),
   8130   1.9   nikita the resulting function can have an arbitrary number of upvalues,
   8131   1.9   nikita and there is no guarantee that its first upvalue will be
   8132   1.9   nikita the <code>_ENV</code> variable.
   8133   1.9   nikita (A non-main function may not even have an <code>_ENV</code> upvalue.)
   8134   1.9   nikita 
   8135   1.9   nikita 
   8136   1.9   nikita <p>
   8137   1.9   nikita Regardless, if the resulting function has any upvalues,
   8138   1.9   nikita its first upvalue is set to the value of <code>env</code>,
   8139   1.9   nikita if that parameter is given,
   8140   1.9   nikita or to the value of the global environment.
   8141   1.9   nikita Other upvalues are initialized with <b>nil</b>.
   8142   1.3    lneto All upvalues are fresh, that is,
   8143   1.3    lneto they are not shared with any other function.
   8144   1.1  mbalmer 
   8145   1.1  mbalmer 
   8146   1.2    lneto <p>
   8147   1.3    lneto <code>chunkname</code> is used as the name of the chunk for error messages
   8148   1.9   nikita and debug information (see <a href="#4.7">&sect;4.7</a>).
   8149   1.2    lneto When absent,
   8150   1.3    lneto it defaults to <code>chunk</code>, if <code>chunk</code> is a string,
   8151   1.2    lneto or to "<code>=(load)</code>" otherwise.
   8152   1.1  mbalmer 
   8153   1.1  mbalmer 
   8154   1.1  mbalmer <p>
   8155   1.2    lneto The string <code>mode</code> controls whether the chunk can be text or binary
   8156   1.2    lneto (that is, a precompiled chunk).
   8157   1.2    lneto It may be the string "<code>b</code>" (only binary chunks),
   8158   1.2    lneto "<code>t</code>" (only text chunks),
   8159   1.2    lneto or "<code>bt</code>" (both binary and text).
   8160   1.2    lneto The default is "<code>bt</code>".
   8161   1.1  mbalmer 
   8162   1.1  mbalmer 
   8163   1.1  mbalmer <p>
   8164   1.9   nikita It is safe to load malformed binary chunks;
   8165   1.9   nikita <code>load</code> signals an appropriate error.
   8166   1.9   nikita However,
   8167   1.9   nikita Lua does not check the consistency of the code inside binary chunks;
   8168   1.9   nikita running maliciously crafted bytecode can crash the interpreter.
   8169   1.1  mbalmer 
   8170   1.1  mbalmer 
   8171   1.1  mbalmer 
   8172   1.1  mbalmer 
   8173   1.1  mbalmer <p>
   8174   1.2    lneto <hr><h3><a name="pdf-loadfile"><code>loadfile ([filename [, mode [, env]]])</code></a></h3>
   8175   1.1  mbalmer 
   8176   1.1  mbalmer 
   8177   1.1  mbalmer <p>
   8178   1.1  mbalmer Similar to <a href="#pdf-load"><code>load</code></a>,
   8179   1.2    lneto but gets the chunk from file <code>filename</code>
   8180   1.2    lneto or from the standard input,
   8181   1.2    lneto if no file name is given.
   8182   1.1  mbalmer 
   8183   1.1  mbalmer 
   8184   1.1  mbalmer 
   8185   1.1  mbalmer 
   8186   1.1  mbalmer <p>
   8187   1.1  mbalmer <hr><h3><a name="pdf-next"><code>next (table [, index])</code></a></h3>
   8188   1.1  mbalmer 
   8189   1.1  mbalmer 
   8190   1.1  mbalmer <p>
   8191   1.1  mbalmer Allows a program to traverse all fields of a table.
   8192   1.1  mbalmer Its first argument is a table and its second argument
   8193   1.1  mbalmer is an index in this table.
   8194   1.9   nikita A call to <code>next</code> returns the next index of the table
   8195   1.1  mbalmer and its associated value.
   8196   1.1  mbalmer When called with <b>nil</b> as its second argument,
   8197   1.1  mbalmer <code>next</code> returns an initial index
   8198   1.1  mbalmer and its associated value.
   8199   1.1  mbalmer When called with the last index,
   8200   1.1  mbalmer or with <b>nil</b> in an empty table,
   8201   1.1  mbalmer <code>next</code> returns <b>nil</b>.
   8202   1.1  mbalmer If the second argument is absent, then it is interpreted as <b>nil</b>.
   8203   1.1  mbalmer In particular,
   8204   1.1  mbalmer you can use <code>next(t)</code> to check whether a table is empty.
   8205   1.1  mbalmer 
   8206   1.1  mbalmer 
   8207   1.1  mbalmer <p>
   8208   1.1  mbalmer The order in which the indices are enumerated is not specified,
   8209   1.1  mbalmer <em>even for numeric indices</em>.
   8210   1.4  mbalmer (To traverse a table in numerical order,
   8211   1.2    lneto use a numerical <b>for</b>.)
   8212   1.1  mbalmer 
   8213   1.1  mbalmer 
   8214   1.1  mbalmer <p>
   8215   1.9   nikita You should not assign any value to a non-existent field in a table
   8216   1.9   nikita during its traversal.
   8217   1.1  mbalmer You may however modify existing fields.
   8218   1.9   nikita In particular, you may set existing fields to nil.
   8219   1.1  mbalmer 
   8220   1.1  mbalmer 
   8221   1.1  mbalmer 
   8222   1.1  mbalmer 
   8223   1.1  mbalmer <p>
   8224   1.1  mbalmer <hr><h3><a name="pdf-pairs"><code>pairs (t)</code></a></h3>
   8225   1.1  mbalmer 
   8226   1.1  mbalmer 
   8227   1.1  mbalmer <p>
   8228   1.2    lneto If <code>t</code> has a metamethod <code>__pairs</code>,
   8229   1.2    lneto calls it with <code>t</code> as argument and returns the first three
   8230   1.2    lneto results from the call.
   8231   1.2    lneto 
   8232   1.2    lneto 
   8233   1.2    lneto <p>
   8234   1.2    lneto Otherwise,
   8235   1.2    lneto returns three values: the <a href="#pdf-next"><code>next</code></a> function, the table <code>t</code>, and <b>nil</b>,
   8236   1.1  mbalmer so that the construction
   8237   1.1  mbalmer 
   8238   1.1  mbalmer <pre>
   8239   1.1  mbalmer      for k,v in pairs(t) do <em>body</em> end
   8240   1.1  mbalmer </pre><p>
   8241   1.1  mbalmer will iterate over all key&ndash;value pairs of table <code>t</code>.
   8242   1.1  mbalmer 
   8243   1.1  mbalmer 
   8244   1.1  mbalmer <p>
   8245   1.1  mbalmer See function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying
   8246   1.1  mbalmer the table during its traversal.
   8247   1.1  mbalmer 
   8248   1.1  mbalmer 
   8249   1.1  mbalmer 
   8250   1.1  mbalmer 
   8251   1.1  mbalmer <p>
   8252   1.2    lneto <hr><h3><a name="pdf-pcall"><code>pcall (f [, arg1, &middot;&middot;&middot;])</code></a></h3>
   8253   1.1  mbalmer 
   8254   1.1  mbalmer 
   8255   1.1  mbalmer <p>
   8256   1.9   nikita Calls the function <code>f</code> with
   8257   1.1  mbalmer the given arguments in <em>protected mode</em>.
   8258   1.1  mbalmer This means that any error inside&nbsp;<code>f</code> is not propagated;
   8259   1.1  mbalmer instead, <code>pcall</code> catches the error
   8260   1.1  mbalmer and returns a status code.
   8261   1.1  mbalmer Its first result is the status code (a boolean),
   8262   1.9   nikita which is <b>true</b> if the call succeeds without errors.
   8263   1.1  mbalmer In such case, <code>pcall</code> also returns all results from the call,
   8264   1.1  mbalmer after this first result.
   8265   1.9   nikita In case of any error, <code>pcall</code> returns <b>false</b> plus the error object.
   8266   1.9   nikita Note that errors caught by <code>pcall</code> do not call a message handler.
   8267   1.1  mbalmer 
   8268   1.1  mbalmer 
   8269   1.1  mbalmer 
   8270   1.1  mbalmer 
   8271   1.1  mbalmer <p>
   8272   1.1  mbalmer <hr><h3><a name="pdf-print"><code>print (&middot;&middot;&middot;)</code></a></h3>
   8273   1.2    lneto Receives any number of arguments
   8274   1.1  mbalmer and prints their values to <code>stdout</code>,
   8275   1.9   nikita converting each argument to a string
   8276   1.9   nikita following the same rules of <a href="#pdf-tostring"><code>tostring</code></a>.
   8277   1.9   nikita 
   8278   1.9   nikita 
   8279   1.9   nikita <p>
   8280   1.9   nikita The function <code>print</code> is not intended for formatted output,
   8281   1.1  mbalmer but only as a quick way to show a value,
   8282   1.2    lneto for instance for debugging.
   8283   1.2    lneto For complete control over the output,
   8284   1.2    lneto use <a href="#pdf-string.format"><code>string.format</code></a> and <a href="#pdf-io.write"><code>io.write</code></a>.
   8285   1.1  mbalmer 
   8286   1.1  mbalmer 
   8287   1.1  mbalmer 
   8288   1.1  mbalmer 
   8289   1.1  mbalmer <p>
   8290   1.1  mbalmer <hr><h3><a name="pdf-rawequal"><code>rawequal (v1, v2)</code></a></h3>
   8291   1.1  mbalmer Checks whether <code>v1</code> is equal to <code>v2</code>,
   8292   1.6  salazar without invoking the <code>__eq</code> metamethod.
   8293   1.1  mbalmer Returns a boolean.
   8294   1.1  mbalmer 
   8295   1.1  mbalmer 
   8296   1.1  mbalmer 
   8297   1.1  mbalmer 
   8298   1.1  mbalmer <p>
   8299   1.1  mbalmer <hr><h3><a name="pdf-rawget"><code>rawget (table, index)</code></a></h3>
   8300   1.1  mbalmer Gets the real value of <code>table[index]</code>,
   8301   1.9   nikita without using the <code>__index</code> metavalue.
   8302   1.1  mbalmer <code>table</code> must be a table;
   8303   1.1  mbalmer <code>index</code> may be any value.
   8304   1.1  mbalmer 
   8305   1.1  mbalmer 
   8306   1.1  mbalmer 
   8307   1.1  mbalmer 
   8308   1.1  mbalmer <p>
   8309   1.2    lneto <hr><h3><a name="pdf-rawlen"><code>rawlen (v)</code></a></h3>
   8310   1.2    lneto Returns the length of the object <code>v</code>,
   8311   1.2    lneto which must be a table or a string,
   8312   1.6  salazar without invoking the <code>__len</code> metamethod.
   8313   1.2    lneto Returns an integer.
   8314   1.2    lneto 
   8315   1.2    lneto 
   8316   1.2    lneto 
   8317   1.2    lneto 
   8318   1.2    lneto <p>
   8319   1.1  mbalmer <hr><h3><a name="pdf-rawset"><code>rawset (table, index, value)</code></a></h3>
   8320   1.1  mbalmer Sets the real value of <code>table[index]</code> to <code>value</code>,
   8321   1.9   nikita without using the <code>__newindex</code> metavalue.
   8322   1.1  mbalmer <code>table</code> must be a table,
   8323   1.2    lneto <code>index</code> any value different from <b>nil</b> and NaN,
   8324   1.1  mbalmer and <code>value</code> any Lua value.
   8325   1.1  mbalmer 
   8326   1.1  mbalmer 
   8327   1.1  mbalmer <p>
   8328   1.1  mbalmer This function returns <code>table</code>.
   8329   1.1  mbalmer 
   8330   1.1  mbalmer 
   8331   1.1  mbalmer 
   8332   1.1  mbalmer 
   8333   1.1  mbalmer <p>
   8334   1.1  mbalmer <hr><h3><a name="pdf-select"><code>select (index, &middot;&middot;&middot;)</code></a></h3>
   8335   1.1  mbalmer 
   8336   1.1  mbalmer 
   8337   1.1  mbalmer <p>
   8338   1.1  mbalmer If <code>index</code> is a number,
   8339   1.2    lneto returns all arguments after argument number <code>index</code>;
   8340   1.2    lneto a negative number indexes from the end (-1 is the last argument).
   8341   1.1  mbalmer Otherwise, <code>index</code> must be the string <code>"#"</code>,
   8342   1.1  mbalmer and <code>select</code> returns the total number of extra arguments it received.
   8343   1.1  mbalmer 
   8344   1.1  mbalmer 
   8345   1.1  mbalmer 
   8346   1.1  mbalmer 
   8347   1.1  mbalmer <p>
   8348   1.1  mbalmer <hr><h3><a name="pdf-setmetatable"><code>setmetatable (table, metatable)</code></a></h3>
   8349   1.1  mbalmer 
   8350   1.1  mbalmer 
   8351   1.1  mbalmer <p>
   8352   1.1  mbalmer Sets the metatable for the given table.
   8353   1.1  mbalmer If <code>metatable</code> is <b>nil</b>,
   8354   1.1  mbalmer removes the metatable of the given table.
   8355   1.6  salazar If the original metatable has a <code>__metatable</code> field,
   8356   1.1  mbalmer raises an error.
   8357   1.1  mbalmer 
   8358   1.1  mbalmer 
   8359   1.1  mbalmer <p>
   8360   1.1  mbalmer This function returns <code>table</code>.
   8361   1.1  mbalmer 
   8362   1.1  mbalmer 
   8363   1.9   nikita <p>
   8364   1.9   nikita To change the metatable of other types from Lua code,
   8365   1.9   nikita you must use the debug library (<a href="#6.10">&sect;6.10</a>).
   8366   1.9   nikita 
   8367   1.9   nikita 
   8368   1.1  mbalmer 
   8369   1.1  mbalmer 
   8370   1.1  mbalmer <p>
   8371   1.1  mbalmer <hr><h3><a name="pdf-tonumber"><code>tonumber (e [, base])</code></a></h3>
   8372   1.2    lneto 
   8373   1.2    lneto 
   8374   1.2    lneto <p>
   8375   1.2    lneto When called with no <code>base</code>,
   8376   1.2    lneto <code>tonumber</code> tries to convert its argument to a number.
   8377   1.2    lneto If the argument is already a number or
   8378   1.2    lneto a string convertible to a number,
   8379   1.2    lneto then <code>tonumber</code> returns this number;
   8380   1.9   nikita otherwise, it returns <b>fail</b>.
   8381   1.1  mbalmer 
   8382   1.1  mbalmer 
   8383   1.1  mbalmer <p>
   8384   1.2    lneto The conversion of strings can result in integers or floats,
   8385   1.2    lneto according to the lexical conventions of Lua (see <a href="#3.1">&sect;3.1</a>).
   8386   1.9   nikita The string may have leading and trailing spaces and a sign.
   8387   1.2    lneto 
   8388   1.2    lneto 
   8389   1.2    lneto <p>
   8390   1.2    lneto When called with <code>base</code>,
   8391   1.2    lneto then <code>e</code> must be a string to be interpreted as
   8392   1.2    lneto an integer numeral in that base.
   8393   1.1  mbalmer The base may be any integer between 2 and 36, inclusive.
   8394   1.1  mbalmer In bases above&nbsp;10, the letter '<code>A</code>' (in either upper or lower case)
   8395   1.1  mbalmer represents&nbsp;10, '<code>B</code>' represents&nbsp;11, and so forth,
   8396   1.1  mbalmer with '<code>Z</code>' representing 35.
   8397   1.2    lneto If the string <code>e</code> is not a valid numeral in the given base,
   8398   1.9   nikita the function returns <b>fail</b>.
   8399   1.1  mbalmer 
   8400   1.1  mbalmer 
   8401   1.1  mbalmer 
   8402   1.1  mbalmer 
   8403   1.1  mbalmer <p>
   8404   1.2    lneto <hr><h3><a name="pdf-tostring"><code>tostring (v)</code></a></h3>
   8405   1.9   nikita 
   8406   1.9   nikita 
   8407   1.9   nikita <p>
   8408   1.2    lneto Receives a value of any type and
   8409   1.2    lneto converts it to a string in a human-readable format.
   8410   1.1  mbalmer 
   8411   1.1  mbalmer 
   8412   1.1  mbalmer <p>
   8413   1.6  salazar If the metatable of <code>v</code> has a <code>__tostring</code> field,
   8414   1.1  mbalmer then <code>tostring</code> calls the corresponding value
   8415   1.2    lneto with <code>v</code> as argument,
   8416   1.1  mbalmer and uses the result of the call as its result.
   8417   1.9   nikita Otherwise, if the metatable of <code>v</code> has a <code>__name</code> field
   8418   1.9   nikita with a string value,
   8419   1.9   nikita <code>tostring</code> may use that string in its final result.
   8420   1.9   nikita 
   8421   1.9   nikita 
   8422   1.9   nikita <p>
   8423   1.9   nikita For complete control of how numbers are converted,
   8424   1.9   nikita use <a href="#pdf-string.format"><code>string.format</code></a>.
   8425   1.1  mbalmer 
   8426   1.1  mbalmer 
   8427   1.1  mbalmer 
   8428   1.1  mbalmer 
   8429   1.1  mbalmer <p>
   8430   1.1  mbalmer <hr><h3><a name="pdf-type"><code>type (v)</code></a></h3>
   8431   1.9   nikita 
   8432   1.9   nikita 
   8433   1.9   nikita <p>
   8434   1.1  mbalmer Returns the type of its only argument, coded as a string.
   8435   1.1  mbalmer The possible results of this function are
   8436   1.1  mbalmer "<code>nil</code>" (a string, not the value <b>nil</b>),
   8437   1.1  mbalmer "<code>number</code>",
   8438   1.1  mbalmer "<code>string</code>",
   8439   1.1  mbalmer "<code>boolean</code>",
   8440   1.1  mbalmer "<code>table</code>",
   8441   1.1  mbalmer "<code>function</code>",
   8442   1.1  mbalmer "<code>thread</code>",
   8443   1.1  mbalmer and "<code>userdata</code>".
   8444   1.1  mbalmer 
   8445   1.1  mbalmer 
   8446   1.1  mbalmer 
   8447   1.1  mbalmer 
   8448   1.1  mbalmer <p>
   8449   1.1  mbalmer <hr><h3><a name="pdf-_VERSION"><code>_VERSION</code></a></h3>
   8450   1.5    lneto 
   8451   1.5    lneto 
   8452   1.5    lneto <p>
   8453   1.1  mbalmer A global variable (not a function) that
   8454   1.5    lneto holds a string containing the running Lua version.
   8455   1.9   nikita The current value of this variable is "<code>Lua 5.4</code>".
   8456   1.9   nikita 
   8457   1.9   nikita 
   8458   1.9   nikita 
   8459   1.9   nikita 
   8460   1.9   nikita <p>
   8461   1.9   nikita <hr><h3><a name="pdf-warn"><code>warn (msg1, &middot;&middot;&middot;)</code></a></h3>
   8462   1.9   nikita 
   8463   1.9   nikita 
   8464   1.9   nikita <p>
   8465   1.9   nikita Emits a warning with a message composed by the concatenation
   8466   1.9   nikita of all its arguments (which should be strings).
   8467   1.9   nikita 
   8468   1.9   nikita 
   8469   1.9   nikita <p>
   8470   1.9   nikita By convention,
   8471   1.9   nikita a one-piece message starting with '<code>@</code>'
   8472   1.9   nikita is intended to be a <em>control message</em>,
   8473   1.9   nikita which is a message to the warning system itself.
   8474   1.9   nikita In particular, the standard warning function in Lua
   8475   1.9   nikita recognizes the control messages "<code>@off</code>",
   8476   1.9   nikita to stop the emission of warnings,
   8477   1.9   nikita and "<code>@on</code>", to (re)start the emission;
   8478   1.9   nikita it ignores unknown control messages.
   8479   1.1  mbalmer 
   8480   1.1  mbalmer 
   8481   1.1  mbalmer 
   8482   1.1  mbalmer 
   8483   1.1  mbalmer <p>
   8484   1.2    lneto <hr><h3><a name="pdf-xpcall"><code>xpcall (f, msgh [, arg1, &middot;&middot;&middot;])</code></a></h3>
   8485   1.1  mbalmer 
   8486   1.1  mbalmer 
   8487   1.1  mbalmer <p>
   8488   1.1  mbalmer This function is similar to <a href="#pdf-pcall"><code>pcall</code></a>,
   8489   1.2    lneto except that it sets a new message handler <code>msgh</code>.
   8490   1.1  mbalmer 
   8491   1.1  mbalmer 
   8492   1.1  mbalmer 
   8493   1.1  mbalmer 
   8494   1.1  mbalmer 
   8495   1.1  mbalmer 
   8496   1.1  mbalmer 
   8497   1.2    lneto <h2>6.2 &ndash; <a name="6.2">Coroutine Manipulation</a></h2>
   8498   1.1  mbalmer 
   8499   1.1  mbalmer <p>
   8500   1.4  mbalmer This library comprises the operations to manipulate coroutines,
   8501   1.4  mbalmer which come inside the table <a name="pdf-coroutine"><code>coroutine</code></a>.
   8502   1.2    lneto See <a href="#2.6">&sect;2.6</a> for a general description of coroutines.
   8503   1.1  mbalmer 
   8504   1.1  mbalmer 
   8505   1.1  mbalmer <p>
   8506   1.9   nikita <hr><h3><a name="pdf-coroutine.close"><code>coroutine.close (co)</code></a></h3>
   8507   1.9   nikita 
   8508   1.9   nikita 
   8509   1.9   nikita <p>
   8510   1.9   nikita Closes coroutine <code>co</code>,
   8511   1.9   nikita that is,
   8512   1.9   nikita closes all its pending to-be-closed variables
   8513   1.9   nikita and puts the coroutine in a dead state.
   8514   1.9   nikita The given coroutine must be dead or suspended.
   8515   1.9   nikita In case of error
   8516   1.9   nikita (either the original error that stopped the coroutine or
   8517   1.9   nikita errors in closing methods),
   8518   1.9   nikita returns <b>false</b> plus the error object;
   8519   1.9   nikita otherwise returns <b>true</b>.
   8520   1.9   nikita 
   8521   1.9   nikita 
   8522   1.9   nikita 
   8523   1.9   nikita 
   8524   1.9   nikita <p>
   8525   1.1  mbalmer <hr><h3><a name="pdf-coroutine.create"><code>coroutine.create (f)</code></a></h3>
   8526   1.1  mbalmer 
   8527   1.1  mbalmer 
   8528   1.1  mbalmer <p>
   8529   1.1  mbalmer Creates a new coroutine, with body <code>f</code>.
   8530   1.4  mbalmer <code>f</code> must be a function.
   8531   1.2    lneto Returns this new coroutine,
   8532   1.2    lneto an object with type <code>"thread"</code>.
   8533   1.2    lneto 
   8534   1.2    lneto 
   8535   1.2    lneto 
   8536   1.2    lneto 
   8537   1.2    lneto <p>
   8538   1.9   nikita <hr><h3><a name="pdf-coroutine.isyieldable"><code>coroutine.isyieldable ([co])</code></a></h3>
   8539   1.2    lneto 
   8540   1.2    lneto 
   8541   1.2    lneto <p>
   8542   1.9   nikita Returns <b>true</b> when the coroutine <code>co</code> can yield.
   8543   1.9   nikita The default for <code>co</code> is the running coroutine.
   8544   1.2    lneto 
   8545   1.2    lneto 
   8546   1.2    lneto <p>
   8547   1.9   nikita A coroutine is yieldable if it is not the main thread and
   8548   1.7  mbalmer it is not inside a non-yieldable C&nbsp;function.
   8549   1.1  mbalmer 
   8550   1.1  mbalmer 
   8551   1.1  mbalmer 
   8552   1.1  mbalmer 
   8553   1.1  mbalmer <p>
   8554   1.1  mbalmer <hr><h3><a name="pdf-coroutine.resume"><code>coroutine.resume (co [, val1, &middot;&middot;&middot;])</code></a></h3>
   8555   1.1  mbalmer 
   8556   1.1  mbalmer 
   8557   1.1  mbalmer <p>
   8558   1.1  mbalmer Starts or continues the execution of coroutine <code>co</code>.
   8559   1.1  mbalmer The first time you resume a coroutine,
   8560   1.1  mbalmer it starts running its body.
   8561   1.2    lneto The values <code>val1</code>, ... are passed
   8562   1.1  mbalmer as the arguments to the body function.
   8563   1.1  mbalmer If the coroutine has yielded,
   8564   1.1  mbalmer <code>resume</code> restarts it;
   8565   1.2    lneto the values <code>val1</code>, ... are passed
   8566   1.1  mbalmer as the results from the yield.
   8567   1.1  mbalmer 
   8568   1.1  mbalmer 
   8569   1.1  mbalmer <p>
   8570   1.1  mbalmer If the coroutine runs without any errors,
   8571   1.1  mbalmer <code>resume</code> returns <b>true</b> plus any values passed to <code>yield</code>
   8572   1.2    lneto (when the coroutine yields) or any values returned by the body function
   8573   1.2    lneto (when the coroutine terminates).
   8574   1.1  mbalmer If there is any error,
   8575   1.1  mbalmer <code>resume</code> returns <b>false</b> plus the error message.
   8576   1.1  mbalmer 
   8577   1.1  mbalmer 
   8578   1.1  mbalmer 
   8579   1.1  mbalmer 
   8580   1.1  mbalmer <p>
   8581   1.1  mbalmer <hr><h3><a name="pdf-coroutine.running"><code>coroutine.running ()</code></a></h3>
   8582   1.1  mbalmer 
   8583   1.1  mbalmer 
   8584   1.1  mbalmer <p>
   8585   1.2    lneto Returns the running coroutine plus a boolean,
   8586   1.9   nikita <b>true</b> when the running coroutine is the main one.
   8587   1.1  mbalmer 
   8588   1.1  mbalmer 
   8589   1.1  mbalmer 
   8590   1.1  mbalmer 
   8591   1.1  mbalmer <p>
   8592   1.1  mbalmer <hr><h3><a name="pdf-coroutine.status"><code>coroutine.status (co)</code></a></h3>
   8593   1.1  mbalmer 
   8594   1.1  mbalmer 
   8595   1.1  mbalmer <p>
   8596   1.9   nikita Returns the status of the coroutine <code>co</code>, as a string:
   8597   1.1  mbalmer <code>"running"</code>,
   8598   1.9   nikita if the coroutine is running
   8599   1.9   nikita (that is, it is the one that called <code>status</code>);
   8600   1.1  mbalmer <code>"suspended"</code>, if the coroutine is suspended in a call to <code>yield</code>,
   8601   1.1  mbalmer or if it has not started running yet;
   8602   1.1  mbalmer <code>"normal"</code> if the coroutine is active but not running
   8603   1.1  mbalmer (that is, it has resumed another coroutine);
   8604   1.1  mbalmer and <code>"dead"</code> if the coroutine has finished its body function,
   8605   1.1  mbalmer or if it has stopped with an error.
   8606   1.1  mbalmer 
   8607   1.1  mbalmer 
   8608   1.1  mbalmer 
   8609   1.1  mbalmer 
   8610   1.1  mbalmer <p>
   8611   1.1  mbalmer <hr><h3><a name="pdf-coroutine.wrap"><code>coroutine.wrap (f)</code></a></h3>
   8612   1.1  mbalmer 
   8613   1.1  mbalmer 
   8614   1.1  mbalmer <p>
   8615   1.9   nikita Creates a new coroutine, with body <code>f</code>;
   8616   1.4  mbalmer <code>f</code> must be a function.
   8617   1.1  mbalmer Returns a function that resumes the coroutine each time it is called.
   8618   1.9   nikita Any arguments passed to this function behave as the
   8619   1.1  mbalmer extra arguments to <code>resume</code>.
   8620   1.9   nikita The function returns the same values returned by <code>resume</code>,
   8621   1.1  mbalmer except the first boolean.
   8622   1.9   nikita In case of error,
   8623   1.9   nikita the function closes the coroutine and propagates the error.
   8624   1.1  mbalmer 
   8625   1.1  mbalmer 
   8626   1.1  mbalmer 
   8627   1.1  mbalmer 
   8628   1.1  mbalmer <p>
   8629   1.1  mbalmer <hr><h3><a name="pdf-coroutine.yield"><code>coroutine.yield (&middot;&middot;&middot;)</code></a></h3>
   8630   1.1  mbalmer 
   8631   1.1  mbalmer 
   8632   1.1  mbalmer <p>
   8633   1.1  mbalmer Suspends the execution of the calling coroutine.
   8634   1.1  mbalmer Any arguments to <code>yield</code> are passed as extra results to <code>resume</code>.
   8635   1.1  mbalmer 
   8636   1.1  mbalmer 
   8637   1.1  mbalmer 
   8638   1.1  mbalmer 
   8639   1.1  mbalmer 
   8640   1.1  mbalmer 
   8641   1.1  mbalmer 
   8642   1.2    lneto <h2>6.3 &ndash; <a name="6.3">Modules</a></h2>
   8643   1.1  mbalmer 
   8644   1.1  mbalmer <p>
   8645   1.1  mbalmer The package library provides basic
   8646   1.2    lneto facilities for loading modules in Lua.
   8647   1.2    lneto It exports one function directly in the global environment:
   8648   1.2    lneto <a href="#pdf-require"><code>require</code></a>.
   8649   1.9   nikita Everything else is exported in the table <a name="pdf-package"><code>package</code></a>.
   8650   1.1  mbalmer 
   8651   1.1  mbalmer 
   8652   1.1  mbalmer <p>
   8653   1.1  mbalmer <hr><h3><a name="pdf-require"><code>require (modname)</code></a></h3>
   8654   1.1  mbalmer 
   8655   1.1  mbalmer 
   8656   1.1  mbalmer <p>
   8657   1.1  mbalmer Loads the given module.
   8658   1.1  mbalmer The function starts by looking into the <a href="#pdf-package.loaded"><code>package.loaded</code></a> table
   8659   1.1  mbalmer to determine whether <code>modname</code> is already loaded.
   8660   1.1  mbalmer If it is, then <code>require</code> returns the value stored
   8661   1.1  mbalmer at <code>package.loaded[modname]</code>.
   8662   1.9   nikita (The absence of a second result in this case
   8663   1.9   nikita signals that this call did not have to load the module.)
   8664   1.1  mbalmer Otherwise, it tries to find a <em>loader</em> for the module.
   8665   1.1  mbalmer 
   8666   1.1  mbalmer 
   8667   1.1  mbalmer <p>
   8668   1.1  mbalmer To find a loader,
   8669   1.9   nikita <code>require</code> is guided by the table <a href="#pdf-package.searchers"><code>package.searchers</code></a>.
   8670   1.9   nikita Each item in this table is a search function,
   8671   1.9   nikita that searches for the module in a particular way.
   8672   1.9   nikita By changing this table,
   8673   1.1  mbalmer we can change how <code>require</code> looks for a module.
   8674   1.1  mbalmer The following explanation is based on the default configuration
   8675   1.2    lneto for <a href="#pdf-package.searchers"><code>package.searchers</code></a>.
   8676   1.1  mbalmer 
   8677   1.1  mbalmer 
   8678   1.1  mbalmer <p>
   8679   1.1  mbalmer First <code>require</code> queries <code>package.preload[modname]</code>.
   8680   1.1  mbalmer If it has a value,
   8681   1.2    lneto this value (which must be a function) is the loader.
   8682   1.1  mbalmer Otherwise <code>require</code> searches for a Lua loader using the
   8683   1.1  mbalmer path stored in <a href="#pdf-package.path"><code>package.path</code></a>.
   8684   1.1  mbalmer If that also fails, it searches for a C&nbsp;loader using the
   8685   1.1  mbalmer path stored in <a href="#pdf-package.cpath"><code>package.cpath</code></a>.
   8686   1.1  mbalmer If that also fails,
   8687   1.2    lneto it tries an <em>all-in-one</em> loader (see <a href="#pdf-package.searchers"><code>package.searchers</code></a>).
   8688   1.1  mbalmer 
   8689   1.1  mbalmer 
   8690   1.1  mbalmer <p>
   8691   1.1  mbalmer Once a loader is found,
   8692   1.2    lneto <code>require</code> calls the loader with two arguments:
   8693   1.9   nikita <code>modname</code> and an extra value,
   8694   1.9   nikita a <em>loader data</em>,
   8695   1.9   nikita also returned by the searcher.
   8696   1.9   nikita The loader data can be any value useful to the module;
   8697   1.9   nikita for the default searchers,
   8698   1.9   nikita it indicates where the loader was found.
   8699   1.9   nikita (For instance, if the loader came from a file,
   8700   1.9   nikita this extra value is the file path.)
   8701   1.2    lneto If the loader returns any non-nil value,
   8702   1.1  mbalmer <code>require</code> assigns the returned value to <code>package.loaded[modname]</code>.
   8703   1.2    lneto If the loader does not return a non-nil value and
   8704   1.1  mbalmer has not assigned any value to <code>package.loaded[modname]</code>,
   8705   1.1  mbalmer then <code>require</code> assigns <b>true</b> to this entry.
   8706   1.1  mbalmer In any case, <code>require</code> returns the
   8707   1.1  mbalmer final value of <code>package.loaded[modname]</code>.
   8708   1.9   nikita Besides that value, <code>require</code> also returns as a second result
   8709   1.9   nikita the loader data returned by the searcher,
   8710   1.9   nikita which indicates how <code>require</code> found the module.
   8711   1.1  mbalmer 
   8712   1.1  mbalmer 
   8713   1.1  mbalmer <p>
   8714   1.1  mbalmer If there is any error loading or running the module,
   8715   1.1  mbalmer or if it cannot find any loader for the module,
   8716   1.2    lneto then <code>require</code> raises an error.
   8717   1.2    lneto 
   8718   1.2    lneto 
   8719   1.2    lneto 
   8720   1.2    lneto 
   8721   1.2    lneto <p>
   8722   1.2    lneto <hr><h3><a name="pdf-package.config"><code>package.config</code></a></h3>
   8723   1.2    lneto 
   8724   1.2    lneto 
   8725   1.2    lneto <p>
   8726   1.2    lneto A string describing some compile-time configurations for packages.
   8727   1.2    lneto This string is a sequence of lines:
   8728   1.2    lneto 
   8729   1.2    lneto <ul>
   8730   1.2    lneto 
   8731   1.2    lneto <li>The first line is the directory separator string.
   8732   1.2    lneto Default is '<code>\</code>' for Windows and '<code>/</code>' for all other systems.</li>
   8733   1.1  mbalmer 
   8734   1.2    lneto <li>The second line is the character that separates templates in a path.
   8735   1.2    lneto Default is '<code>;</code>'.</li>
   8736   1.2    lneto 
   8737   1.2    lneto <li>The third line is the string that marks the
   8738   1.2    lneto substitution points in a template.
   8739   1.2    lneto Default is '<code>?</code>'.</li>
   8740   1.2    lneto 
   8741   1.2    lneto <li>The fourth line is a string that, in a path in Windows,
   8742   1.2    lneto is replaced by the executable's directory.
   8743   1.2    lneto Default is '<code>!</code>'.</li>
   8744   1.2    lneto 
   8745   1.3    lneto <li>The fifth line is a mark to ignore all text after it
   8746   1.2    lneto when building the <code>luaopen_</code> function name.
   8747   1.2    lneto Default is '<code>-</code>'.</li>
   8748   1.2    lneto 
   8749   1.2    lneto </ul>
   8750   1.1  mbalmer 
   8751   1.1  mbalmer 
   8752   1.1  mbalmer 
   8753   1.1  mbalmer <p>
   8754   1.1  mbalmer <hr><h3><a name="pdf-package.cpath"><code>package.cpath</code></a></h3>
   8755   1.1  mbalmer 
   8756   1.1  mbalmer 
   8757   1.1  mbalmer <p>
   8758   1.9   nikita A string with the path used by <a href="#pdf-require"><code>require</code></a>
   8759   1.9   nikita to search for a C&nbsp;loader.
   8760   1.1  mbalmer 
   8761   1.1  mbalmer 
   8762   1.1  mbalmer <p>
   8763   1.1  mbalmer Lua initializes the C&nbsp;path <a href="#pdf-package.cpath"><code>package.cpath</code></a> in the same way
   8764   1.1  mbalmer it initializes the Lua path <a href="#pdf-package.path"><code>package.path</code></a>,
   8765   1.9   nikita using the environment variable <a name="pdf-LUA_CPATH_5_4"><code>LUA_CPATH_5_4</code></a>,
   8766   1.7  mbalmer or the environment variable <a name="pdf-LUA_CPATH"><code>LUA_CPATH</code></a>,
   8767   1.1  mbalmer or a default path defined in <code>luaconf.h</code>.
   8768   1.1  mbalmer 
   8769   1.1  mbalmer 
   8770   1.1  mbalmer 
   8771   1.1  mbalmer 
   8772   1.1  mbalmer <p>
   8773   1.1  mbalmer <hr><h3><a name="pdf-package.loaded"><code>package.loaded</code></a></h3>
   8774   1.1  mbalmer 
   8775   1.1  mbalmer 
   8776   1.1  mbalmer <p>
   8777   1.1  mbalmer A table used by <a href="#pdf-require"><code>require</code></a> to control which
   8778   1.1  mbalmer modules are already loaded.
   8779   1.1  mbalmer When you require a module <code>modname</code> and
   8780   1.1  mbalmer <code>package.loaded[modname]</code> is not false,
   8781   1.1  mbalmer <a href="#pdf-require"><code>require</code></a> simply returns the value stored there.
   8782   1.1  mbalmer 
   8783   1.1  mbalmer 
   8784   1.2    lneto <p>
   8785   1.2    lneto This variable is only a reference to the real table;
   8786   1.2    lneto assignments to this variable do not change the
   8787   1.2    lneto table used by <a href="#pdf-require"><code>require</code></a>.
   8788  1.10   nikita The real table is stored in the C registry (see <a href="#4.3">&sect;4.3</a>),
   8789  1.10   nikita indexed by the key <a name="pdf-LUA_LOADED_TABLE"><code>LUA_LOADED_TABLE</code></a>, a string.
   8790   1.2    lneto 
   8791   1.2    lneto 
   8792   1.2    lneto 
   8793   1.2    lneto 
   8794   1.2    lneto <p>
   8795   1.2    lneto <hr><h3><a name="pdf-package.loadlib"><code>package.loadlib (libname, funcname)</code></a></h3>
   8796   1.2    lneto 
   8797   1.2    lneto 
   8798   1.2    lneto <p>
   8799   1.2    lneto Dynamically links the host program with the C&nbsp;library <code>libname</code>.
   8800   1.2    lneto 
   8801   1.2    lneto 
   8802   1.2    lneto <p>
   8803   1.2    lneto If <code>funcname</code> is "<code>*</code>",
   8804   1.2    lneto then it only links with the library,
   8805   1.2    lneto making the symbols exported by the library
   8806   1.2    lneto available to other dynamically linked libraries.
   8807   1.2    lneto Otherwise,
   8808   1.2    lneto it looks for a function <code>funcname</code> inside the library
   8809   1.2    lneto and returns this function as a C&nbsp;function.
   8810   1.2    lneto So, <code>funcname</code> must follow the <a href="#lua_CFunction"><code>lua_CFunction</code></a> prototype
   8811   1.2    lneto (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>).
   8812   1.2    lneto 
   8813   1.2    lneto 
   8814   1.2    lneto <p>
   8815   1.2    lneto This is a low-level function.
   8816   1.2    lneto It completely bypasses the package and module system.
   8817   1.2    lneto Unlike <a href="#pdf-require"><code>require</code></a>,
   8818   1.2    lneto it does not perform any path searching and
   8819   1.2    lneto does not automatically adds extensions.
   8820   1.2    lneto <code>libname</code> must be the complete file name of the C&nbsp;library,
   8821   1.2    lneto including if necessary a path and an extension.
   8822   1.2    lneto <code>funcname</code> must be the exact name exported by the C&nbsp;library
   8823   1.2    lneto (which may depend on the C&nbsp;compiler and linker used).
   8824   1.2    lneto 
   8825   1.2    lneto 
   8826   1.2    lneto <p>
   8827  1.10   nikita This functionality is not supported by ISO&nbsp;C.
   8828   1.2    lneto As such, it is only available on some platforms
   8829   1.2    lneto (Windows, Linux, Mac OS X, Solaris, BSD,
   8830   1.2    lneto plus other Unix systems that support the <code>dlfcn</code> standard).
   8831   1.2    lneto 
   8832   1.2    lneto 
   8833   1.9   nikita <p>
   8834   1.9   nikita This function is inherently insecure,
   8835   1.9   nikita as it allows Lua to call any function in any readable dynamic
   8836   1.9   nikita library in the system.
   8837   1.9   nikita (Lua calls any function assuming the function
   8838   1.9   nikita has a proper prototype and respects a proper protocol
   8839   1.9   nikita (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>).
   8840   1.9   nikita Therefore,
   8841   1.9   nikita calling an arbitrary function in an arbitrary dynamic library
   8842   1.9   nikita more often than not results in an access violation.)
   8843   1.9   nikita 
   8844   1.9   nikita 
   8845   1.2    lneto 
   8846   1.2    lneto 
   8847   1.2    lneto <p>
   8848   1.2    lneto <hr><h3><a name="pdf-package.path"><code>package.path</code></a></h3>
   8849   1.2    lneto 
   8850   1.2    lneto 
   8851   1.2    lneto <p>
   8852   1.9   nikita A string with the path used by <a href="#pdf-require"><code>require</code></a>
   8853   1.9   nikita to search for a Lua loader.
   8854   1.2    lneto 
   8855   1.2    lneto 
   8856   1.2    lneto <p>
   8857   1.2    lneto At start-up, Lua initializes this variable with
   8858   1.9   nikita the value of the environment variable <a name="pdf-LUA_PATH_5_4"><code>LUA_PATH_5_4</code></a> or
   8859   1.2    lneto the environment variable <a name="pdf-LUA_PATH"><code>LUA_PATH</code></a> or
   8860   1.2    lneto with a default path defined in <code>luaconf.h</code>,
   8861   1.2    lneto if those environment variables are not defined.
   8862   1.9   nikita A "<code>;;</code>" in the value of the environment variable
   8863   1.2    lneto is replaced by the default path.
   8864   1.2    lneto 
   8865   1.2    lneto 
   8866   1.2    lneto 
   8867   1.2    lneto 
   8868   1.2    lneto <p>
   8869   1.2    lneto <hr><h3><a name="pdf-package.preload"><code>package.preload</code></a></h3>
   8870   1.2    lneto 
   8871   1.2    lneto 
   8872   1.2    lneto <p>
   8873   1.2    lneto A table to store loaders for specific modules
   8874   1.2    lneto (see <a href="#pdf-require"><code>require</code></a>).
   8875   1.2    lneto 
   8876   1.2    lneto 
   8877   1.2    lneto <p>
   8878   1.2    lneto This variable is only a reference to the real table;
   8879   1.2    lneto assignments to this variable do not change the
   8880   1.2    lneto table used by <a href="#pdf-require"><code>require</code></a>.
   8881  1.10   nikita The real table is stored in the C registry (see <a href="#4.3">&sect;4.3</a>),
   8882  1.10   nikita indexed by the key <a name="pdf-LUA_PRELOAD_TABLE"><code>LUA_PRELOAD_TABLE</code></a>, a string.
   8883   1.2    lneto 
   8884   1.2    lneto 
   8885   1.1  mbalmer 
   8886   1.1  mbalmer 
   8887   1.1  mbalmer <p>
   8888   1.2    lneto <hr><h3><a name="pdf-package.searchers"><code>package.searchers</code></a></h3>
   8889   1.1  mbalmer 
   8890   1.1  mbalmer 
   8891   1.1  mbalmer <p>
   8892   1.9   nikita A table used by <a href="#pdf-require"><code>require</code></a> to control how to find modules.
   8893   1.1  mbalmer 
   8894   1.1  mbalmer 
   8895   1.1  mbalmer <p>
   8896   1.1  mbalmer Each entry in this table is a <em>searcher function</em>.
   8897   1.1  mbalmer When looking for a module,
   8898   1.1  mbalmer <a href="#pdf-require"><code>require</code></a> calls each of these searchers in ascending order,
   8899   1.1  mbalmer with the module name (the argument given to <a href="#pdf-require"><code>require</code></a>) as its
   8900   1.9   nikita sole argument.
   8901   1.9   nikita If the searcher finds the module,
   8902   1.9   nikita it returns another function, the module <em>loader</em>,
   8903   1.9   nikita plus an extra value, a <em>loader data</em>,
   8904   1.9   nikita that will be passed to that loader and
   8905   1.9   nikita returned as a second result by <a href="#pdf-require"><code>require</code></a>.
   8906   1.9   nikita If it cannot find the module,
   8907   1.9   nikita it returns a string explaining why
   8908   1.1  mbalmer (or <b>nil</b> if it has nothing to say).
   8909   1.2    lneto 
   8910   1.2    lneto 
   8911   1.2    lneto <p>
   8912   1.2    lneto Lua initializes this table with four searcher functions.
   8913   1.1  mbalmer 
   8914   1.1  mbalmer 
   8915   1.1  mbalmer <p>
   8916   1.1  mbalmer The first searcher simply looks for a loader in the
   8917   1.1  mbalmer <a href="#pdf-package.preload"><code>package.preload</code></a> table.
   8918   1.1  mbalmer 
   8919   1.1  mbalmer 
   8920   1.1  mbalmer <p>
   8921   1.1  mbalmer The second searcher looks for a loader as a Lua library,
   8922   1.1  mbalmer using the path stored at <a href="#pdf-package.path"><code>package.path</code></a>.
   8923   1.2    lneto The search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>.
   8924   1.1  mbalmer 
   8925   1.1  mbalmer 
   8926   1.1  mbalmer <p>
   8927   1.1  mbalmer The third searcher looks for a loader as a C&nbsp;library,
   8928   1.1  mbalmer using the path given by the variable <a href="#pdf-package.cpath"><code>package.cpath</code></a>.
   8929   1.2    lneto Again,
   8930   1.2    lneto the search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>.
   8931   1.1  mbalmer For instance,
   8932   1.1  mbalmer if the C&nbsp;path is the string
   8933   1.1  mbalmer 
   8934   1.1  mbalmer <pre>
   8935   1.1  mbalmer      "./?.so;./?.dll;/usr/local/?/init.so"
   8936   1.1  mbalmer </pre><p>
   8937   1.1  mbalmer the searcher for module <code>foo</code>
   8938   1.1  mbalmer will try to open the files <code>./foo.so</code>, <code>./foo.dll</code>,
   8939   1.1  mbalmer and <code>/usr/local/foo/init.so</code>, in that order.
   8940   1.1  mbalmer Once it finds a C&nbsp;library,
   8941   1.1  mbalmer this searcher first uses a dynamic link facility to link the
   8942   1.1  mbalmer application with the library.
   8943   1.1  mbalmer Then it tries to find a C&nbsp;function inside the library to
   8944   1.1  mbalmer be used as the loader.
   8945   1.1  mbalmer The name of this C&nbsp;function is the string "<code>luaopen_</code>"
   8946   1.1  mbalmer concatenated with a copy of the module name where each dot
   8947   1.1  mbalmer is replaced by an underscore.
   8948   1.1  mbalmer Moreover, if the module name has a hyphen,
   8949   1.3    lneto its suffix after (and including) the first hyphen is removed.
   8950   1.3    lneto For instance, if the module name is <code>a.b.c-v2.1</code>,
   8951   1.3    lneto the function name will be <code>luaopen_a_b_c</code>.
   8952   1.1  mbalmer 
   8953   1.1  mbalmer 
   8954   1.1  mbalmer <p>
   8955   1.1  mbalmer The fourth searcher tries an <em>all-in-one loader</em>.
   8956   1.1  mbalmer It searches the C&nbsp;path for a library for
   8957   1.1  mbalmer the root name of the given module.
   8958   1.1  mbalmer For instance, when requiring <code>a.b.c</code>,
   8959   1.1  mbalmer it will search for a C&nbsp;library for <code>a</code>.
   8960   1.1  mbalmer If found, it looks into it for an open function for
   8961   1.1  mbalmer the submodule;
   8962   1.1  mbalmer in our example, that would be <code>luaopen_a_b_c</code>.
   8963   1.1  mbalmer With this facility, a package can pack several C&nbsp;submodules
   8964   1.1  mbalmer into one single library,
   8965   1.1  mbalmer with each submodule keeping its original open function.
   8966   1.1  mbalmer 
   8967   1.1  mbalmer 
   8968   1.1  mbalmer <p>
   8969   1.2    lneto All searchers except the first one (preload) return as the extra value
   8970   1.9   nikita the file path where the module was found,
   8971   1.2    lneto as returned by <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>.
   8972   1.9   nikita The first searcher always returns the string "<code>:preload:</code>".
   8973   1.9   nikita 
   8974   1.9   nikita 
   8975   1.9   nikita <p>
   8976   1.9   nikita Searchers should raise no errors and have no side effects in Lua.
   8977   1.9   nikita (They may have side effects in C,
   8978   1.9   nikita for instance by linking the application with a library.)
   8979   1.1  mbalmer 
   8980   1.1  mbalmer 
   8981   1.1  mbalmer 
   8982   1.1  mbalmer 
   8983   1.1  mbalmer <p>
   8984   1.2    lneto <hr><h3><a name="pdf-package.searchpath"><code>package.searchpath (name, path [, sep [, rep]])</code></a></h3>
   8985   1.1  mbalmer 
   8986   1.1  mbalmer 
   8987   1.1  mbalmer <p>
   8988   1.2    lneto Searches for the given <code>name</code> in the given <code>path</code>.
   8989   1.1  mbalmer 
   8990   1.1  mbalmer 
   8991   1.1  mbalmer <p>
   8992   1.2    lneto A path is a string containing a sequence of
   8993   1.2    lneto <em>templates</em> separated by semicolons.
   8994   1.2    lneto For each template,
   8995   1.2    lneto the function replaces each interrogation mark (if any)
   8996   1.2    lneto in the template with a copy of <code>name</code>
   8997   1.2    lneto wherein all occurrences of <code>sep</code>
   8998   1.2    lneto (a dot, by default)
   8999   1.2    lneto were replaced by <code>rep</code>
   9000   1.2    lneto (the system's directory separator, by default),
   9001   1.2    lneto and then tries to open the resulting file name.
   9002   1.1  mbalmer 
   9003   1.1  mbalmer 
   9004   1.1  mbalmer <p>
   9005   1.2    lneto For instance, if the path is the string
   9006   1.1  mbalmer 
   9007   1.2    lneto <pre>
   9008   1.2    lneto      "./?.lua;./?.lc;/usr/local/?/init.lua"
   9009   1.2    lneto </pre><p>
   9010   1.2    lneto the search for the name <code>foo.a</code>
   9011   1.2    lneto will try to open the files
   9012   1.2    lneto <code>./foo/a.lua</code>, <code>./foo/a.lc</code>, and
   9013   1.2    lneto <code>/usr/local/foo/a/init.lua</code>, in that order.
   9014   1.1  mbalmer 
   9015   1.1  mbalmer 
   9016   1.1  mbalmer <p>
   9017   1.2    lneto Returns the resulting name of the first file that it can
   9018   1.2    lneto open in read mode (after closing the file),
   9019   1.9   nikita or <b>fail</b> plus an error message if none succeeds.
   9020   1.2    lneto (This error message lists all file names it tried to open.)
   9021   1.1  mbalmer 
   9022   1.1  mbalmer 
   9023   1.1  mbalmer 
   9024   1.1  mbalmer 
   9025   1.1  mbalmer 
   9026   1.1  mbalmer 
   9027   1.1  mbalmer 
   9028   1.2    lneto <h2>6.4 &ndash; <a name="6.4">String Manipulation</a></h2>
   9029   1.1  mbalmer 
   9030   1.9   nikita 
   9031   1.9   nikita 
   9032   1.1  mbalmer <p>
   9033   1.1  mbalmer This library provides generic functions for string manipulation,
   9034   1.1  mbalmer such as finding and extracting substrings, and pattern matching.
   9035   1.1  mbalmer When indexing a string in Lua, the first character is at position&nbsp;1
   9036   1.1  mbalmer (not at&nbsp;0, as in C).
   9037   1.1  mbalmer Indices are allowed to be negative and are interpreted as indexing backwards,
   9038   1.1  mbalmer from the end of the string.
   9039   1.1  mbalmer Thus, the last character is at position -1, and so on.
   9040   1.1  mbalmer 
   9041   1.1  mbalmer 
   9042   1.1  mbalmer <p>
   9043   1.1  mbalmer The string library provides all its functions inside the table
   9044   1.1  mbalmer <a name="pdf-string"><code>string</code></a>.
   9045   1.1  mbalmer It also sets a metatable for strings
   9046   1.1  mbalmer where the <code>__index</code> field points to the <code>string</code> table.
   9047   1.1  mbalmer Therefore, you can use the string functions in object-oriented style.
   9048   1.2    lneto For instance, <code>string.byte(s,i)</code>
   9049   1.1  mbalmer can be written as <code>s:byte(i)</code>.
   9050   1.1  mbalmer 
   9051   1.1  mbalmer 
   9052   1.1  mbalmer <p>
   9053   1.1  mbalmer The string library assumes one-byte character encodings.
   9054   1.1  mbalmer 
   9055   1.1  mbalmer 
   9056   1.1  mbalmer <p>
   9057   1.1  mbalmer <hr><h3><a name="pdf-string.byte"><code>string.byte (s [, i [, j]])</code></a></h3>
   9058   1.4  mbalmer Returns the internal numeric codes of the characters <code>s[i]</code>,
   9059   1.2    lneto <code>s[i+1]</code>, ..., <code>s[j]</code>.
   9060   1.1  mbalmer The default value for <code>i</code> is&nbsp;1;
   9061   1.1  mbalmer the default value for <code>j</code> is&nbsp;<code>i</code>.
   9062   1.2    lneto These indices are corrected
   9063   1.2    lneto following the same rules of function <a href="#pdf-string.sub"><code>string.sub</code></a>.
   9064   1.1  mbalmer 
   9065   1.1  mbalmer 
   9066   1.1  mbalmer <p>
   9067   1.4  mbalmer Numeric codes are not necessarily portable across platforms.
   9068   1.1  mbalmer 
   9069   1.1  mbalmer 
   9070   1.1  mbalmer 
   9071   1.1  mbalmer 
   9072   1.1  mbalmer <p>
   9073   1.1  mbalmer <hr><h3><a name="pdf-string.char"><code>string.char (&middot;&middot;&middot;)</code></a></h3>
   9074   1.1  mbalmer Receives zero or more integers.
   9075   1.1  mbalmer Returns a string with length equal to the number of arguments,
   9076   1.4  mbalmer in which each character has the internal numeric code equal
   9077   1.1  mbalmer to its corresponding argument.
   9078   1.1  mbalmer 
   9079   1.1  mbalmer 
   9080   1.1  mbalmer <p>
   9081   1.4  mbalmer Numeric codes are not necessarily portable across platforms.
   9082   1.2    lneto 
   9083   1.2    lneto 
   9084   1.2    lneto 
   9085   1.2    lneto 
   9086   1.2    lneto <p>
   9087   1.2    lneto <hr><h3><a name="pdf-string.dump"><code>string.dump (function [, strip])</code></a></h3>
   9088   1.1  mbalmer 
   9089   1.1  mbalmer 
   9090   1.2    lneto <p>
   9091   1.2    lneto Returns a string containing a binary representation
   9092   1.2    lneto (a <em>binary chunk</em>)
   9093   1.2    lneto of the given function,
   9094   1.2    lneto so that a later <a href="#pdf-load"><code>load</code></a> on this string returns
   9095   1.2    lneto a copy of the function (but with new upvalues).
   9096   1.2    lneto If <code>strip</code> is a true value,
   9097   1.4  mbalmer the binary representation may not include all debug information
   9098   1.4  mbalmer about the function,
   9099   1.4  mbalmer to save space.
   9100   1.2    lneto 
   9101   1.2    lneto 
   9102   1.2    lneto <p>
   9103   1.3    lneto Functions with upvalues have only their number of upvalues saved.
   9104   1.3    lneto When (re)loaded,
   9105   1.9   nikita those upvalues receive fresh instances.
   9106   1.9   nikita (See the <a href="#pdf-load"><code>load</code></a> function for details about
   9107   1.9   nikita how these upvalues are initialized.
   9108   1.9   nikita You can use the debug library to serialize
   9109   1.3    lneto and reload the upvalues of a function
   9110   1.3    lneto in a way adequate to your needs.)
   9111   1.1  mbalmer 
   9112   1.1  mbalmer 
   9113   1.1  mbalmer 
   9114   1.1  mbalmer 
   9115   1.1  mbalmer <p>
   9116   1.1  mbalmer <hr><h3><a name="pdf-string.find"><code>string.find (s, pattern [, init [, plain]])</code></a></h3>
   9117   1.2    lneto 
   9118   1.2    lneto 
   9119   1.2    lneto <p>
   9120   1.1  mbalmer Looks for the first match of
   9121   1.3    lneto <code>pattern</code> (see <a href="#6.4.1">&sect;6.4.1</a>) in the string <code>s</code>.
   9122   1.1  mbalmer If it finds a match, then <code>find</code> returns the indices of&nbsp;<code>s</code>
   9123   1.1  mbalmer where this occurrence starts and ends;
   9124   1.9   nikita otherwise, it returns <b>fail</b>.
   9125   1.4  mbalmer A third, optional numeric argument <code>init</code> specifies
   9126   1.1  mbalmer where to start the search;
   9127   1.1  mbalmer its default value is&nbsp;1 and can be negative.
   9128   1.9   nikita A <b>true</b> as a fourth, optional argument <code>plain</code>
   9129   1.1  mbalmer turns off the pattern matching facilities,
   9130   1.1  mbalmer so the function does a plain "find substring" operation,
   9131   1.2    lneto with no characters in <code>pattern</code> being considered magic.
   9132   1.1  mbalmer 
   9133   1.1  mbalmer 
   9134   1.1  mbalmer <p>
   9135   1.1  mbalmer If the pattern has captures,
   9136   1.1  mbalmer then in a successful match
   9137   1.1  mbalmer the captured values are also returned,
   9138   1.1  mbalmer after the two indices.
   9139   1.1  mbalmer 
   9140   1.1  mbalmer 
   9141   1.1  mbalmer 
   9142   1.1  mbalmer 
   9143   1.1  mbalmer <p>
   9144   1.1  mbalmer <hr><h3><a name="pdf-string.format"><code>string.format (formatstring, &middot;&middot;&middot;)</code></a></h3>
   9145   1.2    lneto 
   9146   1.2    lneto 
   9147   1.2    lneto <p>
   9148   1.1  mbalmer Returns a formatted version of its variable number of arguments
   9149   1.9   nikita following the description given in its first argument,
   9150   1.9   nikita which must be a string.
   9151   1.3    lneto The format string follows the same rules as the ISO&nbsp;C function <code>sprintf</code>.
   9152   1.9   nikita The only differences are that the conversion specifiers and modifiers
   9153   1.9   nikita <code>F</code>, <code>n</code>, <code>*</code>, <code>h</code>, <code>L</code>, and <code>l</code> are not supported
   9154   1.9   nikita and that there is an extra specifier, <code>q</code>.
   9155   1.9   nikita Both width and precision, when present,
   9156   1.9   nikita are limited to two digits.
   9157   1.6  salazar 
   9158   1.6  salazar 
   9159   1.6  salazar <p>
   9160   1.9   nikita The specifier <code>q</code> formats booleans, nil, numbers, and strings
   9161   1.9   nikita in a way that the result is a valid constant in Lua source code.
   9162   1.9   nikita Booleans and nil are written in the obvious way
   9163   1.9   nikita (<code>true</code>, <code>false</code>, <code>nil</code>).
   9164   1.9   nikita Floats are written in hexadecimal,
   9165   1.9   nikita to preserve full precision.
   9166   1.9   nikita A string is written between double quotes,
   9167   1.2    lneto using escape sequences when necessary to ensure that
   9168   1.2    lneto it can safely be read back by the Lua interpreter.
   9169   1.1  mbalmer For instance, the call
   9170   1.1  mbalmer 
   9171   1.1  mbalmer <pre>
   9172   1.1  mbalmer      string.format('%q', 'a string with "quotes" and \n new line')
   9173   1.1  mbalmer </pre><p>
   9174   1.2    lneto may produce the string:
   9175   1.1  mbalmer 
   9176   1.1  mbalmer <pre>
   9177   1.1  mbalmer      "a string with \"quotes\" and \
   9178   1.1  mbalmer       new line"
   9179   1.9   nikita </pre><p>
   9180   1.9   nikita This specifier does not support modifiers (flags, width, precision).
   9181   1.9   nikita 
   9182   1.1  mbalmer 
   9183   1.1  mbalmer <p>
   9184   1.9   nikita The conversion specifiers
   9185   1.4  mbalmer <code>A</code>, <code>a</code>, <code>E</code>, <code>e</code>, <code>f</code>,
   9186   1.2    lneto <code>G</code>, and <code>g</code> all expect a number as argument.
   9187   1.9   nikita The specifiers <code>c</code>, <code>d</code>,
   9188   1.2    lneto <code>i</code>, <code>o</code>, <code>u</code>, <code>X</code>, and <code>x</code>
   9189   1.2    lneto expect an integer.
   9190   1.6  salazar When Lua is compiled with a C89 compiler,
   9191   1.9   nikita the specifiers <code>A</code> and <code>a</code> (hexadecimal floats)
   9192   1.9   nikita do not support modifiers.
   9193   1.6  salazar 
   9194   1.6  salazar 
   9195   1.6  salazar <p>
   9196   1.9   nikita The specifier <code>s</code> expects a string;
   9197   1.4  mbalmer if its argument is not a string,
   9198   1.2    lneto it is converted to one following the same rules of <a href="#pdf-tostring"><code>tostring</code></a>.
   9199   1.9   nikita If the specifier has any modifier,
   9200   1.9   nikita the corresponding string argument should not contain embedded zeros.
   9201   1.9   nikita 
   9202   1.9   nikita 
   9203   1.9   nikita <p>
   9204   1.9   nikita The specifier <code>p</code> formats the pointer
   9205   1.9   nikita returned by <a href="#lua_topointer"><code>lua_topointer</code></a>.
   9206   1.9   nikita That gives a unique string identifier for tables, userdata,
   9207   1.9   nikita threads, strings, and functions.
   9208   1.9   nikita For other values (numbers, nil, booleans),
   9209   1.9   nikita this specifier results in a string representing
   9210   1.9   nikita the pointer <code>NULL</code>.
   9211   1.1  mbalmer 
   9212   1.1  mbalmer 
   9213   1.1  mbalmer 
   9214   1.1  mbalmer 
   9215   1.1  mbalmer <p>
   9216   1.9   nikita <hr><h3><a name="pdf-string.gmatch"><code>string.gmatch (s, pattern [, init])</code></a></h3>
   9217   1.1  mbalmer Returns an iterator function that,
   9218   1.1  mbalmer each time it is called,
   9219   1.3    lneto returns the next captures from <code>pattern</code> (see <a href="#6.4.1">&sect;6.4.1</a>)
   9220   1.3    lneto over the string <code>s</code>.
   9221   1.1  mbalmer If <code>pattern</code> specifies no captures,
   9222   1.1  mbalmer then the whole match is produced in each call.
   9223   1.9   nikita A third, optional numeric argument <code>init</code> specifies
   9224   1.9   nikita where to start the search;
   9225   1.9   nikita its default value is&nbsp;1 and can be negative.
   9226   1.1  mbalmer 
   9227   1.1  mbalmer 
   9228   1.1  mbalmer <p>
   9229   1.1  mbalmer As an example, the following loop
   9230   1.2    lneto will iterate over all the words from string <code>s</code>,
   9231   1.2    lneto printing one per line:
   9232   1.1  mbalmer 
   9233   1.1  mbalmer <pre>
   9234   1.1  mbalmer      s = "hello world from Lua"
   9235   1.1  mbalmer      for w in string.gmatch(s, "%a+") do
   9236   1.1  mbalmer        print(w)
   9237   1.1  mbalmer      end
   9238   1.1  mbalmer </pre><p>
   9239   1.1  mbalmer The next example collects all pairs <code>key=value</code> from the
   9240   1.1  mbalmer given string into a table:
   9241   1.1  mbalmer 
   9242   1.1  mbalmer <pre>
   9243   1.1  mbalmer      t = {}
   9244   1.1  mbalmer      s = "from=world, to=Lua"
   9245   1.1  mbalmer      for k, v in string.gmatch(s, "(%w+)=(%w+)") do
   9246   1.1  mbalmer        t[k] = v
   9247   1.1  mbalmer      end
   9248   1.1  mbalmer </pre>
   9249   1.1  mbalmer 
   9250   1.1  mbalmer <p>
   9251   1.2    lneto For this function, a caret '<code>^</code>' at the start of a pattern does not
   9252   1.1  mbalmer work as an anchor, as this would prevent the iteration.
   9253   1.1  mbalmer 
   9254   1.1  mbalmer 
   9255   1.1  mbalmer 
   9256   1.1  mbalmer 
   9257   1.1  mbalmer <p>
   9258   1.1  mbalmer <hr><h3><a name="pdf-string.gsub"><code>string.gsub (s, pattern, repl [, n])</code></a></h3>
   9259   1.1  mbalmer Returns a copy of <code>s</code>
   9260   1.1  mbalmer in which all (or the first <code>n</code>, if given)
   9261   1.3    lneto occurrences of the <code>pattern</code> (see <a href="#6.4.1">&sect;6.4.1</a>) have been
   9262   1.1  mbalmer replaced by a replacement string specified by <code>repl</code>,
   9263   1.1  mbalmer which can be a string, a table, or a function.
   9264   1.1  mbalmer <code>gsub</code> also returns, as its second value,
   9265   1.1  mbalmer the total number of matches that occurred.
   9266   1.2    lneto The name <code>gsub</code> comes from <em>Global SUBstitution</em>.
   9267   1.1  mbalmer 
   9268   1.1  mbalmer 
   9269   1.1  mbalmer <p>
   9270   1.1  mbalmer If <code>repl</code> is a string, then its value is used for replacement.
   9271   1.1  mbalmer The character&nbsp;<code>%</code> works as an escape character:
   9272   1.2    lneto any sequence in <code>repl</code> of the form <code>%<em>d</em></code>,
   9273   1.2    lneto with <em>d</em> between 1 and 9,
   9274   1.9   nikita stands for the value of the <em>d</em>-th captured substring;
   9275   1.9   nikita the sequence <code>%0</code> stands for the whole match;
   9276   1.9   nikita the sequence <code>%%</code> stands for a single&nbsp;<code>%</code>.
   9277   1.1  mbalmer 
   9278   1.1  mbalmer 
   9279   1.1  mbalmer <p>
   9280   1.1  mbalmer If <code>repl</code> is a table, then the table is queried for every match,
   9281   1.2    lneto using the first capture as the key.
   9282   1.1  mbalmer 
   9283   1.1  mbalmer 
   9284   1.1  mbalmer <p>
   9285   1.1  mbalmer If <code>repl</code> is a function, then this function is called every time a
   9286   1.1  mbalmer match occurs, with all captured substrings passed as arguments,
   9287   1.2    lneto in order.
   9288   1.2    lneto 
   9289   1.2    lneto 
   9290   1.2    lneto <p>
   9291   1.2    lneto In any case,
   9292   1.1  mbalmer if the pattern specifies no captures,
   9293   1.2    lneto then it behaves as if the whole pattern was inside a capture.
   9294   1.1  mbalmer 
   9295   1.1  mbalmer 
   9296   1.1  mbalmer <p>
   9297   1.1  mbalmer If the value returned by the table query or by the function call
   9298   1.1  mbalmer is a string or a number,
   9299   1.1  mbalmer then it is used as the replacement string;
   9300   1.1  mbalmer otherwise, if it is <b>false</b> or <b>nil</b>,
   9301   1.1  mbalmer then there is no replacement
   9302   1.1  mbalmer (that is, the original match is kept in the string).
   9303   1.1  mbalmer 
   9304   1.1  mbalmer 
   9305   1.1  mbalmer <p>
   9306   1.1  mbalmer Here are some examples:
   9307   1.1  mbalmer 
   9308   1.1  mbalmer <pre>
   9309   1.1  mbalmer      x = string.gsub("hello world", "(%w+)", "%1 %1")
   9310   1.1  mbalmer      --&gt; x="hello hello world world"
   9311   1.1  mbalmer      
   9312   1.1  mbalmer      x = string.gsub("hello world", "%w+", "%0 %0", 1)
   9313   1.1  mbalmer      --&gt; x="hello hello world"
   9314   1.1  mbalmer      
   9315   1.1  mbalmer      x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1")
   9316   1.1  mbalmer      --&gt; x="world hello Lua from"
   9317   1.1  mbalmer      
   9318   1.1  mbalmer      x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv)
   9319   1.1  mbalmer      --&gt; x="home = /home/roberto, user = roberto"
   9320   1.1  mbalmer      
   9321   1.1  mbalmer      x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s)
   9322   1.2    lneto            return load(s)()
   9323   1.1  mbalmer          end)
   9324   1.1  mbalmer      --&gt; x="4+5 = 9"
   9325   1.1  mbalmer      
   9326   1.9   nikita      local t = {name="lua", version="5.4"}
   9327   1.1  mbalmer      x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t)
   9328   1.9   nikita      --&gt; x="lua-5.4.tar.gz"
   9329   1.1  mbalmer </pre>
   9330   1.1  mbalmer 
   9331   1.1  mbalmer 
   9332   1.1  mbalmer 
   9333   1.1  mbalmer <p>
   9334   1.1  mbalmer <hr><h3><a name="pdf-string.len"><code>string.len (s)</code></a></h3>
   9335   1.9   nikita 
   9336   1.9   nikita 
   9337   1.9   nikita <p>
   9338   1.1  mbalmer Receives a string and returns its length.
   9339   1.1  mbalmer The empty string <code>""</code> has length 0.
   9340   1.1  mbalmer Embedded zeros are counted,
   9341   1.1  mbalmer so <code>"a\000bc\000"</code> has length 5.
   9342   1.1  mbalmer 
   9343   1.1  mbalmer 
   9344   1.1  mbalmer 
   9345   1.1  mbalmer 
   9346   1.1  mbalmer <p>
   9347   1.1  mbalmer <hr><h3><a name="pdf-string.lower"><code>string.lower (s)</code></a></h3>
   9348   1.9   nikita 
   9349   1.9   nikita 
   9350   1.9   nikita <p>
   9351   1.1  mbalmer Receives a string and returns a copy of this string with all
   9352   1.1  mbalmer uppercase letters changed to lowercase.
   9353   1.1  mbalmer All other characters are left unchanged.
   9354   1.1  mbalmer The definition of what an uppercase letter is depends on the current locale.
   9355   1.1  mbalmer 
   9356   1.1  mbalmer 
   9357   1.1  mbalmer 
   9358   1.1  mbalmer 
   9359   1.1  mbalmer <p>
   9360   1.1  mbalmer <hr><h3><a name="pdf-string.match"><code>string.match (s, pattern [, init])</code></a></h3>
   9361   1.9   nikita 
   9362   1.9   nikita 
   9363   1.9   nikita <p>
   9364   1.1  mbalmer Looks for the first <em>match</em> of
   9365   1.9   nikita the <code>pattern</code> (see <a href="#6.4.1">&sect;6.4.1</a>) in the string <code>s</code>.
   9366   1.1  mbalmer If it finds one, then <code>match</code> returns
   9367   1.1  mbalmer the captures from the pattern;
   9368   1.9   nikita otherwise it returns <b>fail</b>.
   9369   1.1  mbalmer If <code>pattern</code> specifies no captures,
   9370   1.1  mbalmer then the whole match is returned.
   9371   1.4  mbalmer A third, optional numeric argument <code>init</code> specifies
   9372   1.1  mbalmer where to start the search;
   9373   1.1  mbalmer its default value is&nbsp;1 and can be negative.
   9374   1.1  mbalmer 
   9375   1.1  mbalmer 
   9376   1.1  mbalmer 
   9377   1.1  mbalmer 
   9378   1.1  mbalmer <p>
   9379   1.3    lneto <hr><h3><a name="pdf-string.pack"><code>string.pack (fmt, v1, v2, &middot;&middot;&middot;)</code></a></h3>
   9380   1.3    lneto 
   9381   1.3    lneto 
   9382   1.3    lneto <p>
   9383   1.3    lneto Returns a binary string containing the values <code>v1</code>, <code>v2</code>, etc.
   9384   1.9   nikita serialized in binary form (packed)
   9385   1.7  mbalmer according to the format string <code>fmt</code> (see <a href="#6.4.2">&sect;6.4.2</a>).
   9386   1.3    lneto 
   9387   1.3    lneto 
   9388   1.3    lneto 
   9389   1.3    lneto 
   9390   1.3    lneto <p>
   9391   1.3    lneto <hr><h3><a name="pdf-string.packsize"><code>string.packsize (fmt)</code></a></h3>
   9392   1.3    lneto 
   9393   1.3    lneto 
   9394   1.3    lneto <p>
   9395  1.10   nikita Returns the length of a string resulting from <a href="#pdf-string.pack"><code>string.pack</code></a>
   9396   1.3    lneto with the given format.
   9397   1.3    lneto The format string cannot have the variable-length options
   9398   1.3    lneto '<code>s</code>' or '<code>z</code>' (see <a href="#6.4.2">&sect;6.4.2</a>).
   9399   1.3    lneto 
   9400   1.3    lneto 
   9401   1.3    lneto 
   9402   1.3    lneto 
   9403   1.3    lneto <p>
   9404   1.2    lneto <hr><h3><a name="pdf-string.rep"><code>string.rep (s, n [, sep])</code></a></h3>
   9405   1.9   nikita 
   9406   1.9   nikita 
   9407   1.9   nikita <p>
   9408   1.1  mbalmer Returns a string that is the concatenation of <code>n</code> copies of
   9409   1.2    lneto the string <code>s</code> separated by the string <code>sep</code>.
   9410   1.2    lneto The default value for <code>sep</code> is the empty string
   9411   1.2    lneto (that is, no separator).
   9412   1.3    lneto Returns the empty string if <code>n</code> is not positive.
   9413   1.1  mbalmer 
   9414   1.1  mbalmer 
   9415   1.5    lneto <p>
   9416   1.5    lneto (Note that it is very easy to exhaust the memory of your machine
   9417   1.5    lneto with a single call to this function.)
   9418   1.5    lneto 
   9419   1.5    lneto 
   9420   1.1  mbalmer 
   9421   1.1  mbalmer 
   9422   1.1  mbalmer <p>
   9423   1.1  mbalmer <hr><h3><a name="pdf-string.reverse"><code>string.reverse (s)</code></a></h3>
   9424   1.9   nikita 
   9425   1.9   nikita 
   9426   1.9   nikita <p>
   9427   1.1  mbalmer Returns a string that is the string <code>s</code> reversed.
   9428   1.1  mbalmer 
   9429   1.1  mbalmer 
   9430   1.1  mbalmer 
   9431   1.1  mbalmer 
   9432   1.1  mbalmer <p>
   9433   1.1  mbalmer <hr><h3><a name="pdf-string.sub"><code>string.sub (s, i [, j])</code></a></h3>
   9434   1.9   nikita 
   9435   1.9   nikita 
   9436   1.9   nikita <p>
   9437   1.1  mbalmer Returns the substring of <code>s</code> that
   9438   1.1  mbalmer starts at <code>i</code>  and continues until <code>j</code>;
   9439   1.1  mbalmer <code>i</code> and <code>j</code> can be negative.
   9440   1.1  mbalmer If <code>j</code> is absent, then it is assumed to be equal to -1
   9441   1.1  mbalmer (which is the same as the string length).
   9442   1.1  mbalmer In particular,
   9443   1.1  mbalmer the call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code>
   9444   1.1  mbalmer with length <code>j</code>,
   9445   1.7  mbalmer and <code>string.sub(s, -i)</code> (for a positive <code>i</code>)
   9446   1.7  mbalmer returns a suffix of <code>s</code>
   9447   1.1  mbalmer with length <code>i</code>.
   9448   1.1  mbalmer 
   9449   1.1  mbalmer 
   9450   1.2    lneto <p>
   9451   1.2    lneto If, after the translation of negative indices,
   9452   1.2    lneto <code>i</code> is less than 1,
   9453   1.2    lneto it is corrected to 1.
   9454   1.2    lneto If <code>j</code> is greater than the string length,
   9455   1.2    lneto it is corrected to that length.
   9456   1.2    lneto If, after these corrections,
   9457   1.2    lneto <code>i</code> is greater than <code>j</code>,
   9458   1.2    lneto the function returns the empty string.
   9459   1.2    lneto 
   9460   1.2    lneto 
   9461   1.2    lneto 
   9462   1.2    lneto 
   9463   1.2    lneto <p>
   9464   1.3    lneto <hr><h3><a name="pdf-string.unpack"><code>string.unpack (fmt, s [, pos])</code></a></h3>
   9465   1.2    lneto 
   9466   1.2    lneto 
   9467   1.2    lneto <p>
   9468   1.3    lneto Returns the values packed in string <code>s</code> (see <a href="#pdf-string.pack"><code>string.pack</code></a>)
   9469   1.3    lneto according to the format string <code>fmt</code> (see <a href="#6.4.2">&sect;6.4.2</a>).
   9470   1.3    lneto An optional <code>pos</code> marks where
   9471   1.3    lneto to start reading in <code>s</code> (default is 1).
   9472   1.3    lneto After the read values,
   9473   1.3    lneto this function also returns the index of the first unread byte in <code>s</code>.
   9474   1.2    lneto 
   9475   1.2    lneto 
   9476   1.1  mbalmer 
   9477   1.1  mbalmer 
   9478   1.1  mbalmer <p>
   9479   1.1  mbalmer <hr><h3><a name="pdf-string.upper"><code>string.upper (s)</code></a></h3>
   9480   1.9   nikita 
   9481   1.9   nikita 
   9482   1.9   nikita <p>
   9483   1.1  mbalmer Receives a string and returns a copy of this string with all
   9484   1.1  mbalmer lowercase letters changed to uppercase.
   9485   1.1  mbalmer All other characters are left unchanged.
   9486   1.1  mbalmer The definition of what a lowercase letter is depends on the current locale.
   9487   1.1  mbalmer 
   9488   1.1  mbalmer 
   9489   1.1  mbalmer 
   9490   1.3    lneto 
   9491   1.3    lneto 
   9492   1.9   nikita 
   9493   1.9   nikita 
   9494   1.2    lneto <h3>6.4.1 &ndash; <a name="6.4.1">Patterns</a></h3>
   9495   1.1  mbalmer 
   9496   1.9   nikita 
   9497   1.9   nikita 
   9498   1.3    lneto <p>
   9499   1.3    lneto Patterns in Lua are described by regular strings,
   9500   1.3    lneto which are interpreted as patterns by the pattern-matching functions
   9501   1.3    lneto <a href="#pdf-string.find"><code>string.find</code></a>,
   9502   1.3    lneto <a href="#pdf-string.gmatch"><code>string.gmatch</code></a>,
   9503   1.3    lneto <a href="#pdf-string.gsub"><code>string.gsub</code></a>,
   9504   1.3    lneto and <a href="#pdf-string.match"><code>string.match</code></a>.
   9505   1.3    lneto This section describes the syntax and the meaning
   9506   1.3    lneto (that is, what they match) of these strings.
   9507   1.3    lneto 
   9508   1.3    lneto 
   9509   1.1  mbalmer 
   9510   1.9   nikita 
   9511   1.9   nikita 
   9512   1.1  mbalmer <h4>Character Class:</h4><p>
   9513   1.1  mbalmer A <em>character class</em> is used to represent a set of characters.
   9514   1.1  mbalmer The following combinations are allowed in describing a character class:
   9515   1.1  mbalmer 
   9516   1.1  mbalmer <ul>
   9517   1.1  mbalmer 
   9518   1.2    lneto <li><b><em>x</em>: </b>
   9519   1.1  mbalmer (where <em>x</em> is not one of the <em>magic characters</em>
   9520   1.1  mbalmer <code>^$()%.[]*+-?</code>)
   9521   1.1  mbalmer represents the character <em>x</em> itself.
   9522   1.1  mbalmer </li>
   9523   1.1  mbalmer 
   9524   1.2    lneto <li><b><code>.</code>: </b> (a dot) represents all characters.</li>
   9525   1.1  mbalmer 
   9526   1.2    lneto <li><b><code>%a</code>: </b> represents all letters.</li>
   9527   1.1  mbalmer 
   9528   1.2    lneto <li><b><code>%c</code>: </b> represents all control characters.</li>
   9529   1.1  mbalmer 
   9530   1.2    lneto <li><b><code>%d</code>: </b> represents all digits.</li>
   9531   1.1  mbalmer 
   9532   1.2    lneto <li><b><code>%g</code>: </b> represents all printable characters except space.</li>
   9533   1.1  mbalmer 
   9534   1.2    lneto <li><b><code>%l</code>: </b> represents all lowercase letters.</li>
   9535   1.1  mbalmer 
   9536   1.2    lneto <li><b><code>%p</code>: </b> represents all punctuation characters.</li>
   9537   1.1  mbalmer 
   9538   1.2    lneto <li><b><code>%s</code>: </b> represents all space characters.</li>
   9539   1.1  mbalmer 
   9540   1.2    lneto <li><b><code>%u</code>: </b> represents all uppercase letters.</li>
   9541   1.1  mbalmer 
   9542   1.2    lneto <li><b><code>%w</code>: </b> represents all alphanumeric characters.</li>
   9543   1.1  mbalmer 
   9544   1.2    lneto <li><b><code>%x</code>: </b> represents all hexadecimal digits.</li>
   9545   1.1  mbalmer 
   9546   1.2    lneto <li><b><code>%<em>x</em></code>: </b> (where <em>x</em> is any non-alphanumeric character)
   9547   1.1  mbalmer represents the character <em>x</em>.
   9548   1.1  mbalmer This is the standard way to escape the magic characters.
   9549   1.3    lneto Any non-alphanumeric character
   9550   1.4  mbalmer (including all punctuation characters, even the non-magical)
   9551   1.9   nikita can be preceded by a '<code>%</code>' to represent itself in a pattern.
   9552   1.1  mbalmer </li>
   9553   1.1  mbalmer 
   9554   1.2    lneto <li><b><code>[<em>set</em>]</code>: </b>
   9555   1.1  mbalmer represents the class which is the union of all
   9556   1.1  mbalmer characters in <em>set</em>.
   9557   1.1  mbalmer A range of characters can be specified by
   9558   1.2    lneto separating the end characters of the range,
   9559   1.2    lneto in ascending order, with a '<code>-</code>'.
   9560   1.1  mbalmer All classes <code>%</code><em>x</em> described above can also be used as
   9561   1.1  mbalmer components in <em>set</em>.
   9562   1.1  mbalmer All other characters in <em>set</em> represent themselves.
   9563   1.1  mbalmer For example, <code>[%w_]</code> (or <code>[_%w]</code>)
   9564   1.1  mbalmer represents all alphanumeric characters plus the underscore,
   9565   1.1  mbalmer <code>[0-7]</code> represents the octal digits,
   9566   1.1  mbalmer and <code>[0-7%l%-]</code> represents the octal digits plus
   9567   1.1  mbalmer the lowercase letters plus the '<code>-</code>' character.
   9568   1.1  mbalmer 
   9569   1.1  mbalmer 
   9570   1.1  mbalmer <p>
   9571   1.6  salazar You can put a closing square bracket in a set
   9572   1.6  salazar by positioning it as the first character in the set.
   9573   1.8    alnsn You can put a hyphen in a set
   9574   1.6  salazar by positioning it as the first or the last character in the set.
   9575   1.6  salazar (You can also use an escape for both cases.)
   9576   1.6  salazar 
   9577   1.6  salazar 
   9578   1.6  salazar <p>
   9579   1.1  mbalmer The interaction between ranges and classes is not defined.
   9580   1.1  mbalmer Therefore, patterns like <code>[%a-z]</code> or <code>[a-%%]</code>
   9581   1.1  mbalmer have no meaning.
   9582   1.1  mbalmer </li>
   9583   1.1  mbalmer 
   9584   1.2    lneto <li><b><code>[^<em>set</em>]</code>: </b>
   9585   1.1  mbalmer represents the complement of <em>set</em>,
   9586   1.1  mbalmer where <em>set</em> is interpreted as above.
   9587   1.1  mbalmer </li>
   9588   1.1  mbalmer 
   9589   1.1  mbalmer </ul><p>
   9590   1.1  mbalmer For all classes represented by single letters (<code>%a</code>, <code>%c</code>, etc.),
   9591   1.1  mbalmer the corresponding uppercase letter represents the complement of the class.
   9592   1.1  mbalmer For instance, <code>%S</code> represents all non-space characters.
   9593   1.1  mbalmer 
   9594   1.1  mbalmer 
   9595   1.1  mbalmer <p>
   9596   1.1  mbalmer The definitions of letter, space, and other character groups
   9597   1.1  mbalmer depend on the current locale.
   9598   1.1  mbalmer In particular, the class <code>[a-z]</code> may not be equivalent to <code>%l</code>.
   9599   1.1  mbalmer 
   9600   1.1  mbalmer 
   9601   1.1  mbalmer 
   9602   1.1  mbalmer 
   9603   1.1  mbalmer 
   9604   1.1  mbalmer <h4>Pattern Item:</h4><p>
   9605   1.1  mbalmer A <em>pattern item</em> can be
   9606   1.1  mbalmer 
   9607   1.1  mbalmer <ul>
   9608   1.1  mbalmer 
   9609   1.1  mbalmer <li>
   9610   1.1  mbalmer a single character class,
   9611   1.1  mbalmer which matches any single character in the class;
   9612   1.1  mbalmer </li>
   9613   1.1  mbalmer 
   9614   1.1  mbalmer <li>
   9615   1.1  mbalmer a single character class followed by '<code>*</code>',
   9616   1.9   nikita which matches sequences of zero or more characters in the class.
   9617   1.1  mbalmer These repetition items will always match the longest possible sequence;
   9618   1.1  mbalmer </li>
   9619   1.1  mbalmer 
   9620   1.1  mbalmer <li>
   9621   1.1  mbalmer a single character class followed by '<code>+</code>',
   9622   1.9   nikita which matches sequences of one or more characters in the class.
   9623   1.1  mbalmer These repetition items will always match the longest possible sequence;
   9624   1.1  mbalmer </li>
   9625   1.1  mbalmer 
   9626   1.1  mbalmer <li>
   9627   1.1  mbalmer a single character class followed by '<code>-</code>',
   9628   1.9   nikita which also matches sequences of zero or more characters in the class.
   9629   1.1  mbalmer Unlike '<code>*</code>',
   9630   1.2    lneto these repetition items will always match the shortest possible sequence;
   9631   1.1  mbalmer </li>
   9632   1.1  mbalmer 
   9633   1.1  mbalmer <li>
   9634   1.1  mbalmer a single character class followed by '<code>?</code>',
   9635   1.3    lneto which matches zero or one occurrence of a character in the class.
   9636   1.3    lneto It always matches one occurrence if possible;
   9637   1.1  mbalmer </li>
   9638   1.1  mbalmer 
   9639   1.1  mbalmer <li>
   9640   1.1  mbalmer <code>%<em>n</em></code>, for <em>n</em> between 1 and 9;
   9641   1.1  mbalmer such item matches a substring equal to the <em>n</em>-th captured string
   9642   1.1  mbalmer (see below);
   9643   1.1  mbalmer </li>
   9644   1.1  mbalmer 
   9645   1.1  mbalmer <li>
   9646   1.1  mbalmer <code>%b<em>xy</em></code>, where <em>x</em> and <em>y</em> are two distinct characters;
   9647   1.1  mbalmer such item matches strings that start with&nbsp;<em>x</em>, end with&nbsp;<em>y</em>,
   9648   1.1  mbalmer and where the <em>x</em> and <em>y</em> are <em>balanced</em>.
   9649   1.1  mbalmer This means that, if one reads the string from left to right,
   9650   1.1  mbalmer counting <em>+1</em> for an <em>x</em> and <em>-1</em> for a <em>y</em>,
   9651   1.1  mbalmer the ending <em>y</em> is the first <em>y</em> where the count reaches 0.
   9652   1.1  mbalmer For instance, the item <code>%b()</code> matches expressions with
   9653   1.1  mbalmer balanced parentheses.
   9654   1.1  mbalmer </li>
   9655   1.1  mbalmer 
   9656   1.2    lneto <li>
   9657   1.2    lneto <code>%f[<em>set</em>]</code>, a <em>frontier pattern</em>;
   9658   1.2    lneto such item matches an empty string at any position such that
   9659   1.2    lneto the next character belongs to <em>set</em>
   9660   1.2    lneto and the previous character does not belong to <em>set</em>.
   9661   1.2    lneto The set <em>set</em> is interpreted as previously described.
   9662   1.2    lneto The beginning and the end of the subject are handled as if
   9663   1.2    lneto they were the character '<code>\0</code>'.
   9664   1.2    lneto </li>
   9665   1.2    lneto 
   9666   1.1  mbalmer </ul>
   9667   1.1  mbalmer 
   9668   1.1  mbalmer 
   9669   1.1  mbalmer 
   9670   1.1  mbalmer 
   9671   1.1  mbalmer <h4>Pattern:</h4><p>
   9672   1.1  mbalmer A <em>pattern</em> is a sequence of pattern items.
   9673   1.2    lneto A caret '<code>^</code>' at the beginning of a pattern anchors the match at the
   9674   1.1  mbalmer beginning of the subject string.
   9675   1.1  mbalmer A '<code>$</code>' at the end of a pattern anchors the match at the
   9676   1.1  mbalmer end of the subject string.
   9677   1.1  mbalmer At other positions,
   9678   1.1  mbalmer '<code>^</code>' and '<code>$</code>' have no special meaning and represent themselves.
   9679   1.1  mbalmer 
   9680   1.1  mbalmer 
   9681   1.1  mbalmer 
   9682   1.1  mbalmer 
   9683   1.1  mbalmer 
   9684   1.1  mbalmer <h4>Captures:</h4><p>
   9685   1.1  mbalmer A pattern can contain sub-patterns enclosed in parentheses;
   9686   1.1  mbalmer they describe <em>captures</em>.
   9687   1.1  mbalmer When a match succeeds, the substrings of the subject string
   9688   1.1  mbalmer that match captures are stored (<em>captured</em>) for future use.
   9689   1.1  mbalmer Captures are numbered according to their left parentheses.
   9690   1.1  mbalmer For instance, in the pattern <code>"(a*(.)%w(%s*))"</code>,
   9691   1.1  mbalmer the part of the string matching <code>"a*(.)%w(%s*)"</code> is
   9692   1.9   nikita stored as the first capture, and therefore has number&nbsp;1;
   9693   1.1  mbalmer the character matching "<code>.</code>" is captured with number&nbsp;2,
   9694   1.1  mbalmer and the part matching "<code>%s*</code>" has number&nbsp;3.
   9695   1.1  mbalmer 
   9696   1.1  mbalmer 
   9697   1.1  mbalmer <p>
   9698   1.9   nikita As a special case, the capture <code>()</code> captures
   9699   1.1  mbalmer the current string position (a number).
   9700   1.1  mbalmer For instance, if we apply the pattern <code>"()aa()"</code> on the
   9701   1.1  mbalmer string <code>"flaaap"</code>, there will be two captures: 3&nbsp;and&nbsp;5.
   9702   1.1  mbalmer 
   9703   1.1  mbalmer 
   9704   1.2    lneto 
   9705   1.2    lneto 
   9706   1.2    lneto 
   9707   1.9   nikita <h4>Multiple matches:</h4><p>
   9708   1.9   nikita The function <a href="#pdf-string.gsub"><code>string.gsub</code></a> and the iterator <a href="#pdf-string.gmatch"><code>string.gmatch</code></a>
   9709   1.9   nikita match multiple occurrences of the given pattern in the subject.
   9710   1.9   nikita For these functions,
   9711   1.9   nikita a new match is considered valid only
   9712   1.9   nikita if it ends at least one byte after the end of the previous match.
   9713   1.9   nikita In other words, the pattern machine never accepts the
   9714   1.9   nikita empty string as a match immediately after another match.
   9715   1.9   nikita As an example,
   9716   1.9   nikita consider the results of the following code:
   9717   1.9   nikita 
   9718   1.9   nikita <pre>
   9719   1.9   nikita      &gt; string.gsub("abc", "()a*()", print);
   9720   1.9   nikita      --&gt; 1   2
   9721   1.9   nikita      --&gt; 3   3
   9722   1.9   nikita      --&gt; 4   4
   9723   1.9   nikita </pre><p>
   9724   1.9   nikita The second and third results come from Lua matching an empty
   9725   1.9   nikita string after '<code>b</code>' and another one after '<code>c</code>'.
   9726   1.9   nikita Lua does not match an empty string after '<code>a</code>',
   9727   1.9   nikita because it would end at the same position of the previous match.
   9728   1.9   nikita 
   9729   1.9   nikita 
   9730   1.9   nikita 
   9731   1.9   nikita 
   9732   1.9   nikita 
   9733   1.2    lneto 
   9734   1.2    lneto 
   9735   1.3    lneto <h3>6.4.2 &ndash; <a name="6.4.2">Format Strings for Pack and Unpack</a></h3>
   9736   1.3    lneto 
   9737   1.3    lneto <p>
   9738   1.3    lneto The first argument to <a href="#pdf-string.pack"><code>string.pack</code></a>,
   9739   1.3    lneto <a href="#pdf-string.packsize"><code>string.packsize</code></a>, and <a href="#pdf-string.unpack"><code>string.unpack</code></a>
   9740   1.3    lneto is a format string,
   9741   1.3    lneto which describes the layout of the structure being created or read.
   9742   1.3    lneto 
   9743   1.3    lneto 
   9744   1.3    lneto <p>
   9745   1.3    lneto A format string is a sequence of conversion options.
   9746   1.3    lneto The conversion options are as follows:
   9747   1.3    lneto 
   9748   1.3    lneto <ul>
   9749   1.3    lneto <li><b><code>&lt;</code>: </b>sets little endian</li>
   9750   1.3    lneto <li><b><code>&gt;</code>: </b>sets big endian</li>
   9751   1.3    lneto <li><b><code>=</code>: </b>sets native endian</li>
   9752   1.3    lneto <li><b><code>![<em>n</em>]</code>: </b>sets maximum alignment to <code>n</code>
   9753   1.3    lneto (default is native alignment)</li>
   9754   1.3    lneto <li><b><code>b</code>: </b>a signed byte (<code>char</code>)</li>
   9755   1.3    lneto <li><b><code>B</code>: </b>an unsigned byte (<code>char</code>)</li>
   9756   1.3    lneto <li><b><code>h</code>: </b>a signed <code>short</code> (native size)</li>
   9757   1.3    lneto <li><b><code>H</code>: </b>an unsigned <code>short</code> (native size)</li>
   9758   1.3    lneto <li><b><code>l</code>: </b>a signed <code>long</code> (native size)</li>
   9759   1.3    lneto <li><b><code>L</code>: </b>an unsigned <code>long</code> (native size)</li>
   9760   1.3    lneto <li><b><code>j</code>: </b>a <code>lua_Integer</code></li>
   9761   1.3    lneto <li><b><code>J</code>: </b>a <code>lua_Unsigned</code></li>
   9762   1.3    lneto <li><b><code>T</code>: </b>a <code>size_t</code> (native size)</li>
   9763   1.3    lneto <li><b><code>i[<em>n</em>]</code>: </b>a signed <code>int</code> with <code>n</code> bytes
   9764   1.3    lneto (default is native size)</li>
   9765   1.3    lneto <li><b><code>I[<em>n</em>]</code>: </b>an unsigned <code>int</code> with <code>n</code> bytes
   9766   1.3    lneto (default is native size)</li>
   9767   1.3    lneto <li><b><code>f</code>: </b>a <code>float</code> (native size)</li>
   9768   1.3    lneto <li><b><code>d</code>: </b>a <code>double</code> (native size)</li>
   9769   1.3    lneto <li><b><code>n</code>: </b>a <code>lua_Number</code></li>
   9770   1.3    lneto <li><b><code>c<em>n</em></code>: </b>a fixed-sized string with <code>n</code> bytes</li>
   9771   1.3    lneto <li><b><code>z</code>: </b>a zero-terminated string</li>
   9772   1.3    lneto <li><b><code>s[<em>n</em>]</code>: </b>a string preceded by its length
   9773   1.3    lneto coded as an unsigned integer with <code>n</code> bytes
   9774   1.3    lneto (default is a <code>size_t</code>)</li>
   9775   1.3    lneto <li><b><code>x</code>: </b>one byte of padding</li>
   9776   1.3    lneto <li><b><code>X<em>op</em></code>: </b>an empty item that aligns
   9777   1.3    lneto according to option <code>op</code>
   9778   1.3    lneto (which is otherwise ignored)</li>
   9779   1.9   nikita <li><b>'<code> </code>': </b>(space) ignored</li>
   9780   1.3    lneto </ul><p>
   9781   1.3    lneto (A "<code>[<em>n</em>]</code>" means an optional integral numeral.)
   9782   1.3    lneto Except for padding, spaces, and configurations
   9783   1.3    lneto (options "<code>xX &lt;=&gt;!</code>"),
   9784   1.9   nikita each option corresponds to an argument in <a href="#pdf-string.pack"><code>string.pack</code></a>
   9785   1.9   nikita or a result in <a href="#pdf-string.unpack"><code>string.unpack</code></a>.
   9786   1.3    lneto 
   9787   1.3    lneto 
   9788   1.3    lneto <p>
   9789   1.3    lneto For options "<code>!<em>n</em></code>", "<code>s<em>n</em></code>", "<code>i<em>n</em></code>", and "<code>I<em>n</em></code>",
   9790   1.3    lneto <code>n</code> can be any integer between 1 and 16.
   9791   1.3    lneto All integral options check overflows;
   9792   1.3    lneto <a href="#pdf-string.pack"><code>string.pack</code></a> checks whether the given value fits in the given size;
   9793   1.3    lneto <a href="#pdf-string.unpack"><code>string.unpack</code></a> checks whether the read value fits in a Lua integer.
   9794   1.9   nikita For the unsigned options,
   9795   1.9   nikita Lua integers are treated as unsigned values too.
   9796   1.3    lneto 
   9797   1.3    lneto 
   9798   1.3    lneto <p>
   9799   1.3    lneto Any format string starts as if prefixed by "<code>!1=</code>",
   9800   1.3    lneto that is,
   9801   1.3    lneto with maximum alignment of 1 (no alignment)
   9802   1.3    lneto and native endianness.
   9803   1.3    lneto 
   9804   1.3    lneto 
   9805   1.3    lneto <p>
   9806   1.9   nikita Native endianness assumes that the whole system is
   9807   1.9   nikita either big or little endian.
   9808   1.9   nikita The packing functions will not emulate correctly the behavior
   9809   1.9   nikita of mixed-endian formats.
   9810   1.9   nikita 
   9811   1.9   nikita 
   9812   1.9   nikita <p>
   9813   1.3    lneto Alignment works as follows:
   9814   1.3    lneto For each option,
   9815   1.3    lneto the format gets extra padding until the data starts
   9816   1.3    lneto at an offset that is a multiple of the minimum between the
   9817   1.3    lneto option size and the maximum alignment;
   9818   1.3    lneto this minimum must be a power of 2.
   9819   1.3    lneto Options "<code>c</code>" and "<code>z</code>" are not aligned;
   9820   1.3    lneto option "<code>s</code>" follows the alignment of its starting integer.
   9821   1.3    lneto 
   9822   1.3    lneto 
   9823   1.3    lneto <p>
   9824   1.3    lneto All padding is filled with zeros by <a href="#pdf-string.pack"><code>string.pack</code></a>
   9825   1.9   nikita and ignored by <a href="#pdf-string.unpack"><code>string.unpack</code></a>.
   9826   1.3    lneto 
   9827   1.3    lneto 
   9828   1.3    lneto 
   9829   1.2    lneto 
   9830   1.2    lneto 
   9831   1.2    lneto 
   9832   1.2    lneto 
   9833   1.2    lneto <h2>6.5 &ndash; <a name="6.5">UTF-8 Support</a></h2>
   9834   1.2    lneto 
   9835   1.2    lneto <p>
   9836   1.2    lneto This library provides basic support for UTF-8 encoding.
   9837   1.2    lneto It provides all its functions inside the table <a name="pdf-utf8"><code>utf8</code></a>.
   9838   1.2    lneto This library does not provide any support for Unicode other
   9839   1.2    lneto than the handling of the encoding.
   9840   1.2    lneto Any operation that needs the meaning of a character,
   9841   1.2    lneto such as character classification, is outside its scope.
   9842   1.2    lneto 
   9843   1.2    lneto 
   9844   1.2    lneto <p>
   9845   1.2    lneto Unless stated otherwise,
   9846   1.2    lneto all functions that expect a byte position as a parameter
   9847   1.2    lneto assume that the given position is either the start of a byte sequence
   9848   1.2    lneto or one plus the length of the subject string.
   9849   1.2    lneto As in the string library,
   9850   1.2    lneto negative indices count from the end of the string.
   9851   1.2    lneto 
   9852   1.2    lneto 
   9853   1.2    lneto <p>
   9854   1.9   nikita Functions that create byte sequences
   9855   1.9   nikita accept all values up to <code>0x7FFFFFFF</code>,
   9856   1.9   nikita as defined in the original UTF-8 specification;
   9857   1.9   nikita that implies byte sequences of up to six bytes.
   9858   1.9   nikita 
   9859   1.9   nikita 
   9860   1.9   nikita <p>
   9861   1.9   nikita Functions that interpret byte sequences only accept
   9862   1.9   nikita valid sequences (well formed and not overlong).
   9863   1.9   nikita By default, they only accept byte sequences
   9864   1.9   nikita that result in valid Unicode code points,
   9865   1.9   nikita rejecting values greater than <code>10FFFF</code> and surrogates.
   9866   1.9   nikita A boolean argument <code>lax</code>, when available,
   9867   1.9   nikita lifts these checks,
   9868   1.9   nikita so that all values up to <code>0x7FFFFFFF</code> are accepted.
   9869   1.9   nikita (Not well formed and overlong sequences are still rejected.)
   9870   1.9   nikita 
   9871   1.9   nikita 
   9872   1.9   nikita <p>
   9873   1.2    lneto <hr><h3><a name="pdf-utf8.char"><code>utf8.char (&middot;&middot;&middot;)</code></a></h3>
   9874   1.9   nikita 
   9875   1.9   nikita 
   9876   1.9   nikita <p>
   9877   1.2    lneto Receives zero or more integers,
   9878   1.2    lneto converts each one to its corresponding UTF-8 byte sequence
   9879   1.2    lneto and returns a string with the concatenation of all these sequences.
   9880   1.2    lneto 
   9881   1.2    lneto 
   9882   1.2    lneto 
   9883   1.2    lneto 
   9884   1.2    lneto <p>
   9885   1.3    lneto <hr><h3><a name="pdf-utf8.charpattern"><code>utf8.charpattern</code></a></h3>
   9886   1.9   nikita 
   9887   1.9   nikita 
   9888   1.9   nikita <p>
   9889   1.9   nikita The pattern (a string, not a function) "<code>[\0-\x7F\xC2-\xFD][\x80-\xBF]*</code>"
   9890   1.2    lneto (see <a href="#6.4.1">&sect;6.4.1</a>),
   9891   1.2    lneto which matches exactly one UTF-8 byte sequence,
   9892   1.2    lneto assuming that the subject is a valid UTF-8 string.
   9893   1.2    lneto 
   9894   1.2    lneto 
   9895   1.2    lneto 
   9896   1.2    lneto 
   9897   1.2    lneto <p>
   9898   1.9   nikita <hr><h3><a name="pdf-utf8.codes"><code>utf8.codes (s [, lax])</code></a></h3>
   9899   1.2    lneto 
   9900   1.2    lneto 
   9901   1.2    lneto <p>
   9902   1.2    lneto Returns values so that the construction
   9903   1.2    lneto 
   9904   1.2    lneto <pre>
   9905   1.2    lneto      for p, c in utf8.codes(s) do <em>body</em> end
   9906   1.2    lneto </pre><p>
   9907   1.9   nikita will iterate over all UTF-8 characters in string <code>s</code>,
   9908   1.2    lneto with <code>p</code> being the position (in bytes) and <code>c</code> the code point
   9909   1.2    lneto of each character.
   9910   1.2    lneto It raises an error if it meets any invalid byte sequence.
   9911   1.2    lneto 
   9912   1.2    lneto 
   9913   1.2    lneto 
   9914   1.2    lneto 
   9915   1.2    lneto <p>
   9916   1.9   nikita <hr><h3><a name="pdf-utf8.codepoint"><code>utf8.codepoint (s [, i [, j [, lax]]])</code></a></h3>
   9917   1.9   nikita 
   9918   1.9   nikita 
   9919   1.9   nikita <p>
   9920   1.9   nikita Returns the code points (as integers) from all characters in <code>s</code>
   9921   1.2    lneto that start between byte position <code>i</code> and <code>j</code> (both included).
   9922   1.2    lneto The default for <code>i</code> is 1 and for <code>j</code> is <code>i</code>.
   9923   1.2    lneto It raises an error if it meets any invalid byte sequence.
   9924   1.2    lneto 
   9925   1.2    lneto 
   9926   1.2    lneto 
   9927   1.2    lneto 
   9928   1.2    lneto <p>
   9929   1.9   nikita <hr><h3><a name="pdf-utf8.len"><code>utf8.len (s [, i [, j [, lax]]])</code></a></h3>
   9930   1.9   nikita 
   9931   1.9   nikita 
   9932   1.9   nikita <p>
   9933   1.2    lneto Returns the number of UTF-8 characters in string <code>s</code>
   9934   1.3    lneto that start between positions <code>i</code> and <code>j</code> (both inclusive).
   9935   1.2    lneto The default for <code>i</code> is 1 and for <code>j</code> is -1.
   9936   1.2    lneto If it finds any invalid byte sequence,
   9937   1.9   nikita returns <b>fail</b> plus the position of the first invalid byte.
   9938   1.2    lneto 
   9939   1.2    lneto 
   9940   1.2    lneto 
   9941   1.2    lneto 
   9942   1.2    lneto <p>
   9943   1.2    lneto <hr><h3><a name="pdf-utf8.offset"><code>utf8.offset (s, n [, i])</code></a></h3>
   9944   1.9   nikita 
   9945   1.9   nikita 
   9946   1.9   nikita <p>
   9947   1.2    lneto Returns the position (in bytes) where the encoding of the
   9948   1.2    lneto <code>n</code>-th character of <code>s</code>
   9949   1.2    lneto (counting from position <code>i</code>) starts.
   9950   1.2    lneto A negative <code>n</code> gets characters before position <code>i</code>.
   9951   1.2    lneto The default for <code>i</code> is 1 when <code>n</code> is non-negative
   9952   1.2    lneto and <code>#s + 1</code> otherwise,
   9953   1.2    lneto so that <code>utf8.offset(s, -n)</code> gets the offset of the
   9954   1.2    lneto <code>n</code>-th character from the end of the string.
   9955   1.3    lneto If the specified character is neither in the subject
   9956   1.3    lneto nor right after its end,
   9957   1.9   nikita the function returns <b>fail</b>.
   9958   1.2    lneto 
   9959   1.2    lneto 
   9960   1.2    lneto <p>
   9961   1.2    lneto As a special case,
   9962   1.2    lneto when <code>n</code> is 0 the function returns the start of the encoding
   9963   1.2    lneto of the character that contains the <code>i</code>-th byte of <code>s</code>.
   9964   1.2    lneto 
   9965   1.2    lneto 
   9966   1.1  mbalmer <p>
   9967   1.2    lneto This function assumes that <code>s</code> is a valid UTF-8 string.
   9968   1.1  mbalmer 
   9969   1.1  mbalmer 
   9970   1.1  mbalmer 
   9971   1.1  mbalmer 
   9972   1.1  mbalmer 
   9973   1.1  mbalmer 
   9974   1.1  mbalmer 
   9975   1.2    lneto <h2>6.6 &ndash; <a name="6.6">Table Manipulation</a></h2>
   9976   1.2    lneto 
   9977   1.2    lneto <p>
   9978   1.2    lneto This library provides generic functions for table manipulation.
   9979   1.2    lneto It provides all its functions inside the table <a name="pdf-table"><code>table</code></a>.
   9980   1.1  mbalmer 
   9981   1.1  mbalmer 
   9982   1.2    lneto <p>
   9983   1.2    lneto Remember that, whenever an operation needs the length of a table,
   9984   1.7  mbalmer all caveats about the length operator apply (see <a href="#3.4.7">&sect;3.4.7</a>).
   9985   1.2    lneto All functions ignore non-numeric keys
   9986   1.3    lneto in the tables given as arguments.
   9987   1.1  mbalmer 
   9988   1.1  mbalmer 
   9989   1.1  mbalmer <p>
   9990   1.2    lneto <hr><h3><a name="pdf-table.concat"><code>table.concat (list [, sep [, i [, j]]])</code></a></h3>
   9991   1.1  mbalmer 
   9992   1.1  mbalmer 
   9993   1.1  mbalmer <p>
   9994   1.2    lneto Given a list where all elements are strings or numbers,
   9995   1.2    lneto returns the string <code>list[i]..sep..list[i+1] &middot;&middot;&middot; sep..list[j]</code>.
   9996   1.1  mbalmer The default value for <code>sep</code> is the empty string,
   9997   1.1  mbalmer the default for <code>i</code> is 1,
   9998   1.2    lneto and the default for <code>j</code> is <code>#list</code>.
   9999   1.1  mbalmer If <code>i</code> is greater than <code>j</code>, returns the empty string.
   10000   1.1  mbalmer 
   10001   1.1  mbalmer 
   10002   1.1  mbalmer 
   10003   1.1  mbalmer 
   10004   1.1  mbalmer <p>
   10005   1.2    lneto <hr><h3><a name="pdf-table.insert"><code>table.insert (list, [pos,] value)</code></a></h3>
   10006   1.1  mbalmer 
   10007   1.1  mbalmer 
   10008   1.1  mbalmer <p>
   10009   1.2    lneto Inserts element <code>value</code> at position <code>pos</code> in <code>list</code>,
   10010   1.2    lneto shifting up the elements
   10011   1.2    lneto <code>list[pos], list[pos+1], &middot;&middot;&middot;, list[#list]</code>.
   10012   1.2    lneto The default value for <code>pos</code> is <code>#list+1</code>,
   10013   1.1  mbalmer so that a call <code>table.insert(t,x)</code> inserts <code>x</code> at the end
   10014   1.9   nikita of the list <code>t</code>.
   10015   1.1  mbalmer 
   10016   1.1  mbalmer 
   10017   1.1  mbalmer 
   10018   1.1  mbalmer 
   10019   1.1  mbalmer <p>
   10020   1.3    lneto <hr><h3><a name="pdf-table.move"><code>table.move (a1, f, e, t [,a2])</code></a></h3>
   10021   1.3    lneto 
   10022   1.3    lneto 
   10023   1.3    lneto <p>
   10024   1.9   nikita Moves elements from the table <code>a1</code> to the table <code>a2</code>,
   10025   1.6  salazar performing the equivalent to the following
   10026   1.3    lneto multiple assignment:
   10027   1.3    lneto <code>a2[t],&middot;&middot;&middot; = a1[f],&middot;&middot;&middot;,a1[e]</code>.
   10028   1.3    lneto The default for <code>a2</code> is <code>a1</code>.
   10029   1.3    lneto The destination range can overlap with the source range.
   10030   1.4  mbalmer The number of elements to be moved must fit in a Lua integer.
   10031   1.3    lneto 
   10032   1.3    lneto 
   10033   1.6  salazar <p>
   10034   1.6  salazar Returns the destination table <code>a2</code>.
   10035   1.6  salazar 
   10036   1.6  salazar 
   10037   1.3    lneto 
   10038   1.3    lneto 
   10039   1.3    lneto <p>
   10040   1.2    lneto <hr><h3><a name="pdf-table.pack"><code>table.pack (&middot;&middot;&middot;)</code></a></h3>
   10041   1.1  mbalmer 
   10042   1.1  mbalmer 
   10043   1.1  mbalmer <p>
   10044   1.8    alnsn Returns a new table with all arguments stored into keys 1, 2, etc.
   10045   1.8    alnsn and with a field "<code>n</code>" with the total number of arguments.
   10046   1.9   nikita Note that the resulting table may not be a sequence,
   10047   1.9   nikita if some arguments are <b>nil</b>.
   10048   1.1  mbalmer 
   10049   1.1  mbalmer 
   10050   1.1  mbalmer 
   10051   1.1  mbalmer 
   10052   1.1  mbalmer <p>
   10053   1.2    lneto <hr><h3><a name="pdf-table.remove"><code>table.remove (list [, pos])</code></a></h3>
   10054   1.1  mbalmer 
   10055   1.1  mbalmer 
   10056   1.1  mbalmer <p>
   10057   1.2    lneto Removes from <code>list</code> the element at position <code>pos</code>,
   10058   1.2    lneto returning the value of the removed element.
   10059   1.2    lneto When <code>pos</code> is an integer between 1 and <code>#list</code>,
   10060   1.2    lneto it shifts down the elements
   10061   1.2    lneto <code>list[pos+1], list[pos+2], &middot;&middot;&middot;, list[#list]</code>
   10062   1.2    lneto and erases element <code>list[#list]</code>;
   10063   1.2    lneto The index <code>pos</code> can also be 0 when <code>#list</code> is 0,
   10064   1.9   nikita or <code>#list + 1</code>.
   10065   1.2    lneto 
   10066   1.2    lneto 
   10067   1.2    lneto <p>
   10068   1.2    lneto The default value for <code>pos</code> is <code>#list</code>,
   10069   1.2    lneto so that a call <code>table.remove(l)</code> removes the last element
   10070   1.9   nikita of the list <code>l</code>.
   10071   1.2    lneto 
   10072   1.1  mbalmer 
   10073   1.1  mbalmer 
   10074   1.1  mbalmer 
   10075   1.2    lneto <p>
   10076   1.2    lneto <hr><h3><a name="pdf-table.sort"><code>table.sort (list [, comp])</code></a></h3>
   10077   1.2    lneto 
   10078   1.1  mbalmer 
   10079   1.1  mbalmer <p>
   10080   1.9   nikita Sorts the list elements in a given order, <em>in-place</em>,
   10081   1.2    lneto from <code>list[1]</code> to <code>list[#list]</code>.
   10082   1.1  mbalmer If <code>comp</code> is given,
   10083   1.2    lneto then it must be a function that receives two list elements
   10084   1.2    lneto and returns true when the first element must come
   10085   1.9   nikita before the second in the final order,
   10086   1.9   nikita so that, after the sort,
   10087   1.9   nikita <code>i &lt;= j</code> implies <code>not comp(list[j],list[i])</code>.
   10088   1.1  mbalmer If <code>comp</code> is not given,
   10089   1.1  mbalmer then the standard Lua operator <code>&lt;</code> is used instead.
   10090   1.1  mbalmer 
   10091   1.1  mbalmer 
   10092   1.1  mbalmer <p>
   10093   1.9   nikita The <code>comp</code> function must define a consistent order;
   10094   1.9   nikita more formally, the function must define a strict weak order.
   10095   1.9   nikita (A weak order is similar to a total order,
   10096   1.9   nikita but it can equate different elements for comparison purposes.)
   10097   1.5    lneto 
   10098   1.5    lneto 
   10099   1.5    lneto <p>
   10100   1.7  mbalmer The sort algorithm is not stable:
   10101   1.9   nikita Different elements considered equal by the given order
   10102   1.1  mbalmer may have their relative positions changed by the sort.
   10103   1.1  mbalmer 
   10104   1.1  mbalmer 
   10105   1.1  mbalmer 
   10106   1.1  mbalmer 
   10107   1.2    lneto <p>
   10108   1.2    lneto <hr><h3><a name="pdf-table.unpack"><code>table.unpack (list [, i [, j]])</code></a></h3>
   10109   1.2    lneto 
   10110   1.2    lneto 
   10111   1.2    lneto <p>
   10112   1.2    lneto Returns the elements from the given list.
   10113   1.2    lneto This function is equivalent to
   10114   1.2    lneto 
   10115   1.2    lneto <pre>
   10116   1.2    lneto      return list[i], list[i+1], &middot;&middot;&middot;, list[j]
   10117   1.2    lneto </pre><p>
   10118   1.2    lneto By default, <code>i</code> is&nbsp;1 and <code>j</code> is <code>#list</code>.
   10119   1.2    lneto 
   10120   1.2    lneto 
   10121   1.2    lneto 
   10122   1.1  mbalmer 
   10123   1.1  mbalmer 
   10124   1.1  mbalmer 
   10125   1.2    lneto 
   10126   1.2    lneto <h2>6.7 &ndash; <a name="6.7">Mathematical Functions</a></h2>
   10127   1.1  mbalmer 
   10128   1.1  mbalmer <p>
   10129   1.2    lneto This library provides basic mathematical functions.
   10130   1.2    lneto It provides all its functions and constants inside the table <a name="pdf-math"><code>math</code></a>.
   10131   1.2    lneto Functions with the annotation "<code>integer/float</code>" give
   10132   1.2    lneto integer results for integer arguments
   10133   1.9   nikita and float results for non-integer arguments.
   10134   1.9   nikita The rounding functions
   10135   1.9   nikita <a href="#pdf-math.ceil"><code>math.ceil</code></a>, <a href="#pdf-math.floor"><code>math.floor</code></a>, and <a href="#pdf-math.modf"><code>math.modf</code></a>
   10136   1.2    lneto return an integer when the result fits in the range of an integer,
   10137   1.3    lneto or a float otherwise.
   10138   1.1  mbalmer 
   10139   1.1  mbalmer 
   10140   1.1  mbalmer <p>
   10141   1.1  mbalmer <hr><h3><a name="pdf-math.abs"><code>math.abs (x)</code></a></h3>
   10142   1.1  mbalmer 
   10143   1.1  mbalmer 
   10144   1.1  mbalmer <p>
   10145   1.9   nikita Returns the maximum value between <code>x</code> and <code>-x</code>. (integer/float)
   10146   1.1  mbalmer 
   10147   1.1  mbalmer 
   10148   1.1  mbalmer 
   10149   1.1  mbalmer 
   10150   1.1  mbalmer <p>
   10151   1.1  mbalmer <hr><h3><a name="pdf-math.acos"><code>math.acos (x)</code></a></h3>
   10152   1.1  mbalmer 
   10153   1.1  mbalmer 
   10154   1.1  mbalmer <p>
   10155   1.1  mbalmer Returns the arc cosine of <code>x</code> (in radians).
   10156   1.1  mbalmer 
   10157   1.1  mbalmer 
   10158   1.1  mbalmer 
   10159   1.1  mbalmer 
   10160   1.1  mbalmer <p>
   10161   1.1  mbalmer <hr><h3><a name="pdf-math.asin"><code>math.asin (x)</code></a></h3>
   10162   1.1  mbalmer 
   10163   1.1  mbalmer 
   10164   1.1  mbalmer <p>
   10165   1.1  mbalmer Returns the arc sine of <code>x</code> (in radians).
   10166   1.1  mbalmer 
   10167   1.1  mbalmer 
   10168   1.1  mbalmer 
   10169   1.1  mbalmer 
   10170   1.1  mbalmer <p>
   10171   1.2    lneto <hr><h3><a name="pdf-math.atan"><code>math.atan (y [, x])</code></a></h3>
   10172   1.1  mbalmer 
   10173   1.1  mbalmer 
   10174   1.1  mbalmer <p>
   10175  1.10   nikita  
   10176   1.1  mbalmer Returns the arc tangent of <code>y/x</code> (in radians),
   10177  1.10   nikita using the signs of both arguments to find the
   10178   1.1  mbalmer quadrant of the result.
   10179   1.9   nikita It also handles correctly the case of <code>x</code> being zero.
   10180   1.1  mbalmer 
   10181   1.1  mbalmer 
   10182   1.2    lneto <p>
   10183   1.2    lneto The default value for <code>x</code> is 1,
   10184   1.2    lneto so that the call <code>math.atan(y)</code>
   10185   1.2    lneto returns the arc tangent of <code>y</code>.
   10186   1.2    lneto 
   10187   1.2    lneto 
   10188   1.1  mbalmer 
   10189   1.1  mbalmer 
   10190   1.1  mbalmer <p>
   10191   1.1  mbalmer <hr><h3><a name="pdf-math.ceil"><code>math.ceil (x)</code></a></h3>
   10192   1.1  mbalmer 
   10193   1.1  mbalmer 
   10194   1.1  mbalmer <p>
   10195   1.9   nikita Returns the smallest integral value greater than or equal to <code>x</code>.
   10196   1.1  mbalmer 
   10197   1.1  mbalmer 
   10198   1.1  mbalmer 
   10199   1.1  mbalmer 
   10200   1.1  mbalmer <p>
   10201   1.1  mbalmer <hr><h3><a name="pdf-math.cos"><code>math.cos (x)</code></a></h3>
   10202   1.1  mbalmer 
   10203   1.1  mbalmer 
   10204   1.1  mbalmer <p>
   10205   1.1  mbalmer Returns the cosine of <code>x</code> (assumed to be in radians).
   10206   1.1  mbalmer 
   10207   1.1  mbalmer 
   10208   1.1  mbalmer 
   10209   1.1  mbalmer 
   10210   1.1  mbalmer <p>
   10211   1.1  mbalmer <hr><h3><a name="pdf-math.deg"><code>math.deg (x)</code></a></h3>
   10212   1.1  mbalmer 
   10213   1.1  mbalmer 
   10214   1.1  mbalmer <p>
   10215   1.2    lneto Converts the angle <code>x</code> from radians to degrees.
   10216   1.1  mbalmer 
   10217   1.1  mbalmer 
   10218   1.1  mbalmer 
   10219   1.1  mbalmer 
   10220   1.1  mbalmer <p>
   10221   1.3    lneto <hr><h3><a name="pdf-math.exp"><code>math.exp (x)</code></a></h3>
   10222   1.3    lneto 
   10223   1.3    lneto 
   10224   1.3    lneto <p>
   10225   1.3    lneto Returns the value <em>e<sup>x</sup></em>
   10226   1.3    lneto (where <code>e</code> is the base of natural logarithms).
   10227   1.3    lneto 
   10228   1.3    lneto 
   10229   1.3    lneto 
   10230   1.3    lneto 
   10231   1.3    lneto <p>
   10232   1.1  mbalmer <hr><h3><a name="pdf-math.floor"><code>math.floor (x)</code></a></h3>
   10233   1.1  mbalmer 
   10234   1.1  mbalmer 
   10235   1.1  mbalmer <p>
   10236   1.9   nikita Returns the largest integral value less than or equal to <code>x</code>.
   10237   1.1  mbalmer 
   10238   1.1  mbalmer 
   10239   1.1  mbalmer 
   10240   1.1  mbalmer 
   10241   1.1  mbalmer <p>
   10242   1.1  mbalmer <hr><h3><a name="pdf-math.fmod"><code>math.fmod (x, y)</code></a></h3>
   10243   1.1  mbalmer 
   10244   1.1  mbalmer 
   10245   1.1  mbalmer <p>
   10246   1.1  mbalmer Returns the remainder of the division of <code>x</code> by <code>y</code>
   10247   1.2    lneto that rounds the quotient towards zero. (integer/float)
   10248   1.1  mbalmer 
   10249   1.1  mbalmer 
   10250   1.1  mbalmer 
   10251   1.1  mbalmer 
   10252   1.1  mbalmer <p>
   10253   1.2    lneto <hr><h3><a name="pdf-math.huge"><code>math.huge</code></a></h3>
   10254   1.1  mbalmer 
   10255   1.1  mbalmer 
   10256   1.1  mbalmer <p>
   10257   1.2    lneto The float value <code>HUGE_VAL</code>,
   10258   1.9   nikita a value greater than any other numeric value.
   10259   1.1  mbalmer 
   10260   1.1  mbalmer 
   10261   1.1  mbalmer 
   10262   1.1  mbalmer 
   10263   1.1  mbalmer <p>
   10264   1.2    lneto <hr><h3><a name="pdf-math.log"><code>math.log (x [, base])</code></a></h3>
   10265   1.1  mbalmer 
   10266   1.1  mbalmer 
   10267   1.1  mbalmer <p>
   10268   1.2    lneto Returns the logarithm of <code>x</code> in the given base.
   10269   1.2    lneto The default for <code>base</code> is <em>e</em>
   10270   1.2    lneto (so that the function returns the natural logarithm of <code>x</code>).
   10271   1.1  mbalmer 
   10272   1.1  mbalmer 
   10273   1.1  mbalmer 
   10274   1.1  mbalmer 
   10275   1.1  mbalmer <p>
   10276   1.2    lneto <hr><h3><a name="pdf-math.max"><code>math.max (x, &middot;&middot;&middot;)</code></a></h3>
   10277   1.1  mbalmer 
   10278   1.1  mbalmer 
   10279   1.1  mbalmer <p>
   10280   1.2    lneto Returns the argument with the maximum value,
   10281   1.9   nikita according to the Lua operator <code>&lt;</code>.
   10282   1.1  mbalmer 
   10283   1.1  mbalmer 
   10284   1.1  mbalmer 
   10285   1.1  mbalmer 
   10286   1.1  mbalmer <p>
   10287   1.2    lneto <hr><h3><a name="pdf-math.maxinteger"><code>math.maxinteger</code></a></h3>
   10288   1.2    lneto An integer with the maximum value for an integer.
   10289   1.1  mbalmer 
   10290   1.1  mbalmer 
   10291   1.1  mbalmer 
   10292   1.1  mbalmer 
   10293   1.1  mbalmer <p>
   10294   1.2    lneto <hr><h3><a name="pdf-math.min"><code>math.min (x, &middot;&middot;&middot;)</code></a></h3>
   10295   1.1  mbalmer 
   10296   1.1  mbalmer 
   10297   1.1  mbalmer <p>
   10298   1.2    lneto Returns the argument with the minimum value,
   10299   1.9   nikita according to the Lua operator <code>&lt;</code>.
   10300   1.1  mbalmer 
   10301   1.1  mbalmer 
   10302   1.1  mbalmer 
   10303   1.1  mbalmer 
   10304   1.1  mbalmer <p>
   10305   1.2    lneto <hr><h3><a name="pdf-math.mininteger"><code>math.mininteger</code></a></h3>
   10306   1.2    lneto An integer with the minimum value for an integer.
   10307   1.1  mbalmer 
   10308   1.1  mbalmer 
   10309   1.1  mbalmer 
   10310   1.1  mbalmer 
   10311   1.1  mbalmer <p>
   10312   1.1  mbalmer <hr><h3><a name="pdf-math.modf"><code>math.modf (x)</code></a></h3>
   10313   1.1  mbalmer 
   10314   1.1  mbalmer 
   10315   1.1  mbalmer <p>
   10316   1.2    lneto Returns the integral part of <code>x</code> and the fractional part of <code>x</code>.
   10317   1.2    lneto Its second result is always a float.
   10318   1.1  mbalmer 
   10319   1.1  mbalmer 
   10320   1.1  mbalmer 
   10321   1.1  mbalmer 
   10322   1.1  mbalmer <p>
   10323   1.1  mbalmer <hr><h3><a name="pdf-math.pi"><code>math.pi</code></a></h3>
   10324   1.1  mbalmer 
   10325   1.1  mbalmer 
   10326   1.1  mbalmer <p>
   10327   1.2    lneto The value of <em>&pi;</em>.
   10328   1.1  mbalmer 
   10329   1.1  mbalmer 
   10330   1.1  mbalmer 
   10331   1.1  mbalmer 
   10332   1.1  mbalmer <p>
   10333   1.1  mbalmer <hr><h3><a name="pdf-math.rad"><code>math.rad (x)</code></a></h3>
   10334   1.1  mbalmer 
   10335   1.1  mbalmer 
   10336   1.1  mbalmer <p>
   10337   1.2    lneto Converts the angle <code>x</code> from degrees to radians.
   10338   1.1  mbalmer 
   10339   1.1  mbalmer 
   10340   1.1  mbalmer 
   10341   1.1  mbalmer 
   10342   1.1  mbalmer <p>
   10343   1.1  mbalmer <hr><h3><a name="pdf-math.random"><code>math.random ([m [, n]])</code></a></h3>
   10344   1.1  mbalmer 
   10345   1.1  mbalmer 
   10346   1.1  mbalmer <p>
   10347   1.2    lneto When called without arguments,
   10348   1.2    lneto returns a pseudo-random float with uniform distribution
   10349   1.2    lneto in the range  <em>[0,1)</em>.  
   10350   1.2    lneto When called with two integers <code>m</code> and <code>n</code>,
   10351   1.2    lneto <code>math.random</code> returns a pseudo-random integer
   10352   1.2    lneto with uniform distribution in the range <em>[m, n]</em>.
   10353   1.9   nikita The call <code>math.random(n)</code>, for a positive <code>n</code>,
   10354   1.9   nikita is equivalent to <code>math.random(1,n)</code>.
   10355   1.9   nikita The call <code>math.random(0)</code> produces an integer with
   10356   1.9   nikita all bits (pseudo)random.
   10357   1.9   nikita 
   10358   1.9   nikita 
   10359   1.9   nikita <p>
   10360   1.9   nikita This function uses the <code>xoshiro256**</code> algorithm to produce
   10361   1.9   nikita pseudo-random 64-bit integers,
   10362   1.9   nikita which are the results of calls with argument&nbsp;0.
   10363   1.9   nikita Other results (ranges and floats)
   10364   1.9   nikita are unbiased extracted from these integers.
   10365   1.1  mbalmer 
   10366   1.1  mbalmer 
   10367   1.1  mbalmer <p>
   10368   1.9   nikita Lua initializes its pseudo-random generator with the equivalent of
   10369   1.9   nikita a call to <a href="#pdf-math.randomseed"><code>math.randomseed</code></a> with no arguments,
   10370   1.9   nikita so that <code>math.random</code> should generate
   10371   1.9   nikita different sequences of results each time the program runs.
   10372   1.1  mbalmer 
   10373   1.1  mbalmer 
   10374   1.1  mbalmer 
   10375   1.1  mbalmer 
   10376   1.1  mbalmer <p>
   10377   1.9   nikita <hr><h3><a name="pdf-math.randomseed"><code>math.randomseed ([x [, y]])</code></a></h3>
   10378   1.1  mbalmer 
   10379   1.1  mbalmer 
   10380   1.1  mbalmer <p>
   10381   1.9   nikita When called with at least one argument,
   10382   1.9   nikita the integer parameters <code>x</code> and <code>y</code> are
   10383   1.9   nikita joined into a 128-bit <em>seed</em> that
   10384   1.9   nikita is used to reinitialize the pseudo-random generator;
   10385   1.1  mbalmer equal seeds produce equal sequences of numbers.
   10386   1.9   nikita The default for <code>y</code> is zero.
   10387   1.9   nikita 
   10388   1.9   nikita 
   10389   1.9   nikita <p>
   10390   1.9   nikita When called with no arguments,
   10391   1.9   nikita Lua generates a seed with
   10392   1.9   nikita a weak attempt for randomness.
   10393   1.9   nikita 
   10394   1.9   nikita 
   10395   1.9   nikita <p>
   10396   1.9   nikita This function returns the two seed components
   10397   1.9   nikita that were effectively used,
   10398   1.9   nikita so that setting them again repeats the sequence.
   10399   1.9   nikita 
   10400   1.9   nikita 
   10401   1.9   nikita <p>
   10402   1.9   nikita To ensure a required level of randomness to the initial state
   10403   1.9   nikita (or contrarily, to have a deterministic sequence,
   10404   1.9   nikita for instance when debugging a program),
   10405   1.9   nikita you should call <a href="#pdf-math.randomseed"><code>math.randomseed</code></a> with explicit arguments.
   10406   1.1  mbalmer 
   10407   1.1  mbalmer 
   10408   1.1  mbalmer 
   10409   1.1  mbalmer 
   10410   1.1  mbalmer <p>
   10411   1.1  mbalmer <hr><h3><a name="pdf-math.sin"><code>math.sin (x)</code></a></h3>
   10412   1.1  mbalmer 
   10413   1.1  mbalmer 
   10414   1.1  mbalmer <p>
   10415   1.1  mbalmer Returns the sine of <code>x</code> (assumed to be in radians).
   10416   1.1  mbalmer 
   10417   1.1  mbalmer 
   10418   1.1  mbalmer 
   10419   1.1  mbalmer 
   10420   1.1  mbalmer <p>
   10421   1.1  mbalmer <hr><h3><a name="pdf-math.sqrt"><code>math.sqrt (x)</code></a></h3>
   10422   1.1  mbalmer 
   10423   1.1  mbalmer 
   10424   1.1  mbalmer <p>
   10425   1.1  mbalmer Returns the square root of <code>x</code>.
   10426   1.1  mbalmer (You can also use the expression <code>x^0.5</code> to compute this value.)
   10427   1.1  mbalmer 
   10428   1.1  mbalmer 
   10429   1.1  mbalmer 
   10430   1.1  mbalmer 
   10431   1.1  mbalmer <p>
   10432   1.1  mbalmer <hr><h3><a name="pdf-math.tan"><code>math.tan (x)</code></a></h3>
   10433   1.1  mbalmer 
   10434   1.1  mbalmer 
   10435   1.1  mbalmer <p>
   10436   1.1  mbalmer Returns the tangent of <code>x</code> (assumed to be in radians).
   10437   1.1  mbalmer 
   10438   1.1  mbalmer 
   10439   1.1  mbalmer 
   10440   1.1  mbalmer 
   10441   1.1  mbalmer <p>
   10442   1.3    lneto <hr><h3><a name="pdf-math.tointeger"><code>math.tointeger (x)</code></a></h3>
   10443   1.3    lneto 
   10444   1.3    lneto 
   10445   1.3    lneto <p>
   10446   1.3    lneto If the value <code>x</code> is convertible to an integer,
   10447   1.3    lneto returns that integer.
   10448   1.9   nikita Otherwise, returns <b>fail</b>.
   10449   1.3    lneto 
   10450   1.3    lneto 
   10451   1.3    lneto 
   10452   1.3    lneto 
   10453   1.3    lneto <p>
   10454   1.2    lneto <hr><h3><a name="pdf-math.type"><code>math.type (x)</code></a></h3>
   10455   1.1  mbalmer 
   10456   1.1  mbalmer 
   10457   1.1  mbalmer <p>
   10458   1.2    lneto Returns "<code>integer</code>" if <code>x</code> is an integer,
   10459   1.2    lneto "<code>float</code>" if it is a float,
   10460   1.9   nikita or <b>fail</b> if <code>x</code> is not a number.
   10461   1.1  mbalmer 
   10462   1.1  mbalmer 
   10463   1.1  mbalmer 
   10464   1.1  mbalmer 
   10465   1.3    lneto <p>
   10466   1.3    lneto <hr><h3><a name="pdf-math.ult"><code>math.ult (m, n)</code></a></h3>
   10467   1.3    lneto 
   10468   1.3    lneto 
   10469   1.3    lneto <p>
   10470   1.3    lneto Returns a boolean,
   10471   1.9   nikita <b>true</b> if and only if integer <code>m</code> is below integer <code>n</code> when
   10472   1.3    lneto they are compared as unsigned integers.
   10473   1.3    lneto 
   10474   1.3    lneto 
   10475   1.3    lneto 
   10476   1.3    lneto 
   10477   1.1  mbalmer 
   10478   1.1  mbalmer 
   10479   1.1  mbalmer 
   10480   1.2    lneto <h2>6.8 &ndash; <a name="6.8">Input and Output Facilities</a></h2>
   10481   1.1  mbalmer 
   10482   1.1  mbalmer <p>
   10483   1.1  mbalmer The I/O library provides two different styles for file manipulation.
   10484   1.2    lneto The first one uses implicit file handles;
   10485   1.1  mbalmer that is, there are operations to set a default input file and a
   10486   1.1  mbalmer default output file,
   10487   1.9   nikita and all input/output operations are done over these default files.
   10488   1.2    lneto The second style uses explicit file handles.
   10489   1.1  mbalmer 
   10490   1.1  mbalmer 
   10491   1.1  mbalmer <p>
   10492   1.2    lneto When using implicit file handles,
   10493   1.1  mbalmer all operations are supplied by table <a name="pdf-io"><code>io</code></a>.
   10494   1.2    lneto When using explicit file handles,
   10495   1.2    lneto the operation <a href="#pdf-io.open"><code>io.open</code></a> returns a file handle
   10496   1.2    lneto and then all operations are supplied as methods of the file handle.
   10497   1.1  mbalmer 
   10498   1.1  mbalmer 
   10499   1.1  mbalmer <p>
   10500   1.9   nikita The metatable for file handles provides metamethods
   10501   1.9   nikita for <code>__gc</code> and <code>__close</code> that try
   10502   1.9   nikita to close the file when called.
   10503   1.9   nikita 
   10504   1.9   nikita 
   10505   1.9   nikita <p>
   10506   1.1  mbalmer The table <code>io</code> also provides
   10507   1.2    lneto three predefined file handles with their usual meanings from C:
   10508   1.1  mbalmer <a name="pdf-io.stdin"><code>io.stdin</code></a>, <a name="pdf-io.stdout"><code>io.stdout</code></a>, and <a name="pdf-io.stderr"><code>io.stderr</code></a>.
   10509   1.1  mbalmer The I/O library never closes these files.
   10510   1.1  mbalmer 
   10511   1.1  mbalmer 
   10512   1.1  mbalmer <p>
   10513   1.1  mbalmer Unless otherwise stated,
   10514   1.9   nikita all I/O functions return <b>fail</b> on failure,
   10515   1.9   nikita plus an error message as a second result and
   10516   1.9   nikita a system-dependent error code as a third result,
   10517   1.9   nikita and some non-false value on success.
   10518   1.9   nikita On non-POSIX systems,
   10519   1.2    lneto the computation of the error message and error code
   10520   1.2    lneto in case of errors
   10521   1.2    lneto may be not thread safe,
   10522   1.2    lneto because they rely on the global C variable <code>errno</code>.
   10523   1.1  mbalmer 
   10524   1.1  mbalmer 
   10525   1.1  mbalmer <p>
   10526   1.1  mbalmer <hr><h3><a name="pdf-io.close"><code>io.close ([file])</code></a></h3>
   10527   1.1  mbalmer 
   10528   1.1  mbalmer 
   10529   1.1  mbalmer <p>
   10530   1.1  mbalmer Equivalent to <code>file:close()</code>.
   10531   1.1  mbalmer Without a <code>file</code>, closes the default output file.
   10532   1.1  mbalmer 
   10533   1.1  mbalmer 
   10534   1.1  mbalmer 
   10535   1.1  mbalmer 
   10536   1.1  mbalmer <p>
   10537   1.1  mbalmer <hr><h3><a name="pdf-io.flush"><code>io.flush ()</code></a></h3>
   10538   1.1  mbalmer 
   10539   1.1  mbalmer 
   10540   1.1  mbalmer <p>
   10541   1.2    lneto Equivalent to <code>io.output():flush()</code>.
   10542   1.1  mbalmer 
   10543   1.1  mbalmer 
   10544   1.1  mbalmer 
   10545   1.1  mbalmer 
   10546   1.1  mbalmer <p>
   10547   1.1  mbalmer <hr><h3><a name="pdf-io.input"><code>io.input ([file])</code></a></h3>
   10548   1.1  mbalmer 
   10549   1.1  mbalmer 
   10550   1.1  mbalmer <p>
   10551   1.1  mbalmer When called with a file name, it opens the named file (in text mode),
   10552   1.1  mbalmer and sets its handle as the default input file.
   10553   1.1  mbalmer When called with a file handle,
   10554   1.1  mbalmer it simply sets this file handle as the default input file.
   10555   1.8    alnsn When called without arguments,
   10556   1.1  mbalmer it returns the current default input file.
   10557   1.1  mbalmer 
   10558   1.1  mbalmer 
   10559   1.1  mbalmer <p>
   10560   1.1  mbalmer In case of errors this function raises the error,
   10561   1.1  mbalmer instead of returning an error code.
   10562   1.1  mbalmer 
   10563   1.1  mbalmer 
   10564   1.1  mbalmer 
   10565   1.1  mbalmer 
   10566   1.1  mbalmer <p>
   10567   1.5    lneto <hr><h3><a name="pdf-io.lines"><code>io.lines ([filename, &middot;&middot;&middot;])</code></a></h3>
   10568   1.1  mbalmer 
   10569   1.1  mbalmer 
   10570   1.1  mbalmer <p>
   10571   1.1  mbalmer Opens the given file name in read mode
   10572   1.2    lneto and returns an iterator function that
   10573   1.2    lneto works like <code>file:lines(&middot;&middot;&middot;)</code> over the opened file.
   10574   1.9   nikita When the iterator function fails to read any value,
   10575   1.9   nikita it automatically closes the file.
   10576   1.9   nikita Besides the iterator function,
   10577   1.9   nikita <code>io.lines</code> returns three other values:
   10578   1.9   nikita two <b>nil</b> values as placeholders,
   10579   1.9   nikita plus the created file handle.
   10580   1.9   nikita Therefore, when used in a generic <b>for</b> loop,
   10581   1.9   nikita the file is closed also if the loop is interrupted by an
   10582   1.9   nikita error or a <b>break</b>.
   10583   1.1  mbalmer 
   10584   1.1  mbalmer 
   10585   1.1  mbalmer <p>
   10586   1.1  mbalmer The call <code>io.lines()</code> (with no file name) is equivalent
   10587   1.9   nikita to <code>io.input():lines("l")</code>;
   10588   1.1  mbalmer that is, it iterates over the lines of the default input file.
   10589   1.8    alnsn In this case, the iterator does not close the file when the loop ends.
   10590   1.1  mbalmer 
   10591   1.1  mbalmer 
   10592   1.2    lneto <p>
   10593   1.9   nikita In case of errors opening the file,
   10594   1.9   nikita this function raises the error,
   10595   1.2    lneto instead of returning an error code.
   10596   1.2    lneto 
   10597   1.2    lneto 
   10598   1.1  mbalmer 
   10599   1.1  mbalmer 
   10600   1.1  mbalmer <p>
   10601   1.1  mbalmer <hr><h3><a name="pdf-io.open"><code>io.open (filename [, mode])</code></a></h3>
   10602   1.1  mbalmer 
   10603   1.1  mbalmer 
   10604   1.1  mbalmer <p>
   10605   1.1  mbalmer This function opens a file,
   10606   1.1  mbalmer in the mode specified in the string <code>mode</code>.
   10607   1.6  salazar In case of success,
   10608   1.6  salazar it returns a new file handle.
   10609   1.1  mbalmer 
   10610   1.1  mbalmer 
   10611   1.1  mbalmer <p>
   10612   1.1  mbalmer The <code>mode</code> string can be any of the following:
   10613   1.1  mbalmer 
   10614   1.1  mbalmer <ul>
   10615   1.2    lneto <li><b>"<code>r</code>": </b> read mode (the default);</li>
   10616   1.2    lneto <li><b>"<code>w</code>": </b> write mode;</li>
   10617   1.2    lneto <li><b>"<code>a</code>": </b> append mode;</li>
   10618   1.2    lneto <li><b>"<code>r+</code>": </b> update mode, all previous data is preserved;</li>
   10619   1.2    lneto <li><b>"<code>w+</code>": </b> update mode, all previous data is erased;</li>
   10620   1.2    lneto <li><b>"<code>a+</code>": </b> append update mode, previous data is preserved,
   10621   1.1  mbalmer   writing is only allowed at the end of file.</li>
   10622   1.1  mbalmer </ul><p>
   10623   1.1  mbalmer The <code>mode</code> string can also have a '<code>b</code>' at the end,
   10624   1.1  mbalmer which is needed in some systems to open the file in binary mode.
   10625   1.1  mbalmer 
   10626   1.1  mbalmer 
   10627   1.1  mbalmer 
   10628   1.1  mbalmer 
   10629   1.1  mbalmer <p>
   10630   1.1  mbalmer <hr><h3><a name="pdf-io.output"><code>io.output ([file])</code></a></h3>
   10631   1.1  mbalmer 
   10632   1.1  mbalmer 
   10633   1.1  mbalmer <p>
   10634   1.1  mbalmer Similar to <a href="#pdf-io.input"><code>io.input</code></a>, but operates over the default output file.
   10635   1.1  mbalmer 
   10636   1.1  mbalmer 
   10637   1.1  mbalmer 
   10638   1.1  mbalmer 
   10639   1.1  mbalmer <p>
   10640   1.1  mbalmer <hr><h3><a name="pdf-io.popen"><code>io.popen (prog [, mode])</code></a></h3>
   10641   1.1  mbalmer 
   10642   1.1  mbalmer 
   10643   1.1  mbalmer <p>
   10644   1.2    lneto This function is system dependent and is not available
   10645   1.2    lneto on all platforms.
   10646   1.2    lneto 
   10647   1.2    lneto 
   10648   1.2    lneto <p>
   10649   1.9   nikita Starts the program <code>prog</code> in a separated process and returns
   10650   1.1  mbalmer a file handle that you can use to read data from this program
   10651   1.1  mbalmer (if <code>mode</code> is <code>"r"</code>, the default)
   10652   1.1  mbalmer or to write data to this program
   10653   1.1  mbalmer (if <code>mode</code> is <code>"w"</code>).
   10654   1.1  mbalmer 
   10655   1.1  mbalmer 
   10656   1.1  mbalmer 
   10657   1.1  mbalmer 
   10658   1.1  mbalmer <p>
   10659   1.1  mbalmer <hr><h3><a name="pdf-io.read"><code>io.read (&middot;&middot;&middot;)</code></a></h3>
   10660   1.1  mbalmer 
   10661   1.1  mbalmer 
   10662   1.1  mbalmer <p>
   10663   1.2    lneto Equivalent to <code>io.input():read(&middot;&middot;&middot;)</code>.
   10664   1.1  mbalmer 
   10665   1.1  mbalmer 
   10666   1.1  mbalmer 
   10667   1.1  mbalmer 
   10668   1.1  mbalmer <p>
   10669   1.1  mbalmer <hr><h3><a name="pdf-io.tmpfile"><code>io.tmpfile ()</code></a></h3>
   10670   1.1  mbalmer 
   10671   1.1  mbalmer 
   10672   1.1  mbalmer <p>
   10673   1.6  salazar In case of success,
   10674   1.6  salazar returns a handle for a temporary file.
   10675   1.1  mbalmer This file is opened in update mode
   10676   1.1  mbalmer and it is automatically removed when the program ends.
   10677   1.1  mbalmer 
   10678   1.1  mbalmer 
   10679   1.1  mbalmer 
   10680   1.1  mbalmer 
   10681   1.1  mbalmer <p>
   10682   1.1  mbalmer <hr><h3><a name="pdf-io.type"><code>io.type (obj)</code></a></h3>
   10683   1.1  mbalmer 
   10684   1.1  mbalmer 
   10685   1.1  mbalmer <p>
   10686   1.1  mbalmer Checks whether <code>obj</code> is a valid file handle.
   10687   1.1  mbalmer Returns the string <code>"file"</code> if <code>obj</code> is an open file handle,
   10688   1.1  mbalmer <code>"closed file"</code> if <code>obj</code> is a closed file handle,
   10689   1.9   nikita or <b>fail</b> if <code>obj</code> is not a file handle.
   10690   1.1  mbalmer 
   10691   1.1  mbalmer 
   10692   1.1  mbalmer 
   10693   1.1  mbalmer 
   10694   1.1  mbalmer <p>
   10695   1.1  mbalmer <hr><h3><a name="pdf-io.write"><code>io.write (&middot;&middot;&middot;)</code></a></h3>
   10696   1.1  mbalmer 
   10697   1.1  mbalmer 
   10698   1.1  mbalmer <p>
   10699   1.2    lneto Equivalent to <code>io.output():write(&middot;&middot;&middot;)</code>.
   10700   1.1  mbalmer 
   10701   1.1  mbalmer 
   10702   1.1  mbalmer 
   10703   1.1  mbalmer 
   10704   1.1  mbalmer <p>
   10705   1.1  mbalmer <hr><h3><a name="pdf-file:close"><code>file:close ()</code></a></h3>
   10706   1.1  mbalmer 
   10707   1.1  mbalmer 
   10708   1.1  mbalmer <p>
   10709   1.1  mbalmer Closes <code>file</code>.
   10710   1.1  mbalmer Note that files are automatically closed when
   10711   1.1  mbalmer their handles are garbage collected,
   10712   1.1  mbalmer but that takes an unpredictable amount of time to happen.
   10713   1.1  mbalmer 
   10714   1.1  mbalmer 
   10715   1.2    lneto <p>
   10716   1.2    lneto When closing a file handle created with <a href="#pdf-io.popen"><code>io.popen</code></a>,
   10717   1.2    lneto <a href="#pdf-file:close"><code>file:close</code></a> returns the same values
   10718   1.2    lneto returned by <a href="#pdf-os.execute"><code>os.execute</code></a>.
   10719   1.2    lneto 
   10720   1.2    lneto 
   10721   1.1  mbalmer 
   10722   1.1  mbalmer 
   10723   1.1  mbalmer <p>
   10724   1.1  mbalmer <hr><h3><a name="pdf-file:flush"><code>file:flush ()</code></a></h3>
   10725   1.1  mbalmer 
   10726   1.1  mbalmer 
   10727   1.1  mbalmer <p>
   10728   1.1  mbalmer Saves any written data to <code>file</code>.
   10729   1.1  mbalmer 
   10730   1.1  mbalmer 
   10731   1.1  mbalmer 
   10732   1.1  mbalmer 
   10733   1.1  mbalmer <p>
   10734   1.2    lneto <hr><h3><a name="pdf-file:lines"><code>file:lines (&middot;&middot;&middot;)</code></a></h3>
   10735   1.1  mbalmer 
   10736   1.1  mbalmer 
   10737   1.1  mbalmer <p>
   10738   1.1  mbalmer Returns an iterator function that,
   10739   1.1  mbalmer each time it is called,
   10740   1.2    lneto reads the file according to the given formats.
   10741   1.2    lneto When no format is given,
   10742   1.2    lneto uses "<code>l</code>" as a default.
   10743   1.2    lneto As an example, the construction
   10744   1.1  mbalmer 
   10745   1.1  mbalmer <pre>
   10746   1.2    lneto      for c in file:lines(1) do <em>body</em> end
   10747   1.2    lneto </pre><p>
   10748   1.2    lneto will iterate over all characters of the file,
   10749   1.2    lneto starting at the current position.
   10750   1.2    lneto Unlike <a href="#pdf-io.lines"><code>io.lines</code></a>, this function does not close the file
   10751   1.2    lneto when the loop ends.
   10752   1.2    lneto 
   10753   1.2    lneto 
   10754   1.1  mbalmer 
   10755   1.1  mbalmer 
   10756   1.1  mbalmer <p>
   10757   1.1  mbalmer <hr><h3><a name="pdf-file:read"><code>file:read (&middot;&middot;&middot;)</code></a></h3>
   10758   1.1  mbalmer 
   10759   1.1  mbalmer 
   10760   1.1  mbalmer <p>
   10761   1.1  mbalmer Reads the file <code>file</code>,
   10762   1.1  mbalmer according to the given formats, which specify what to read.
   10763   1.1  mbalmer For each format,
   10764   1.2    lneto the function returns a string or a number with the characters read,
   10765   1.9   nikita or <b>fail</b> if it cannot read data with the specified format.
   10766   1.3    lneto (In this latter case,
   10767   1.3    lneto the function does not read subsequent formats.)
   10768   1.9   nikita When called without arguments,
   10769   1.2    lneto it uses a default format that reads the next line
   10770   1.1  mbalmer (see below).
   10771   1.1  mbalmer 
   10772   1.1  mbalmer 
   10773   1.1  mbalmer <p>
   10774   1.1  mbalmer The available formats are
   10775   1.1  mbalmer 
   10776   1.1  mbalmer <ul>
   10777   1.1  mbalmer 
   10778   1.2    lneto <li><b>"<code>n</code>": </b>
   10779   1.2    lneto reads a numeral and returns it as a float or an integer,
   10780   1.2    lneto following the lexical conventions of Lua.
   10781   1.9   nikita (The numeral may have leading whitespaces and a sign.)
   10782   1.2    lneto This format always reads the longest input sequence that
   10783   1.4  mbalmer is a valid prefix for a numeral;
   10784   1.4  mbalmer if that prefix does not form a valid numeral
   10785   1.9   nikita (e.g., an empty string, "<code>0x</code>", or "<code>3.4e-</code>")
   10786   1.9   nikita or it is too long (more than 200 characters),
   10787   1.9   nikita it is discarded and the format returns <b>fail</b>.
   10788   1.2    lneto </li>
   10789   1.2    lneto 
   10790   1.2    lneto <li><b>"<code>a</code>": </b>
   10791   1.1  mbalmer reads the whole file, starting at the current position.
   10792   1.9   nikita On end of file, it returns the empty string;
   10793   1.9   nikita this format never fails.
   10794   1.1  mbalmer </li>
   10795   1.1  mbalmer 
   10796   1.2    lneto <li><b>"<code>l</code>": </b>
   10797   1.2    lneto reads the next line skipping the end of line,
   10798   1.9   nikita returning <b>fail</b> on end of file.
   10799   1.1  mbalmer This is the default format.
   10800   1.1  mbalmer </li>
   10801   1.1  mbalmer 
   10802   1.2    lneto <li><b>"<code>L</code>": </b>
   10803   1.2    lneto reads the next line keeping the end-of-line character (if present),
   10804   1.9   nikita returning <b>fail</b> on end of file.
   10805   1.2    lneto </li>
   10806   1.2    lneto 
   10807   1.2    lneto <li><b><em>number</em>: </b>
   10808   1.2    lneto reads a string with up to this number of bytes,
   10809   1.9   nikita returning <b>fail</b> on end of file.
   10810   1.2    lneto If <code>number</code> is zero,
   10811   1.1  mbalmer it reads nothing and returns an empty string,
   10812   1.9   nikita or <b>fail</b> on end of file.
   10813   1.1  mbalmer </li>
   10814   1.1  mbalmer 
   10815   1.2    lneto </ul><p>
   10816   1.2    lneto The formats "<code>l</code>" and "<code>L</code>" should be used only for text files.
   10817   1.2    lneto 
   10818   1.1  mbalmer 
   10819   1.1  mbalmer 
   10820   1.1  mbalmer 
   10821   1.1  mbalmer <p>
   10822   1.2    lneto <hr><h3><a name="pdf-file:seek"><code>file:seek ([whence [, offset]])</code></a></h3>
   10823   1.1  mbalmer 
   10824   1.1  mbalmer 
   10825   1.1  mbalmer <p>
   10826   1.1  mbalmer Sets and gets the file position,
   10827   1.1  mbalmer measured from the beginning of the file,
   10828   1.1  mbalmer to the position given by <code>offset</code> plus a base
   10829   1.1  mbalmer specified by the string <code>whence</code>, as follows:
   10830   1.1  mbalmer 
   10831   1.1  mbalmer <ul>
   10832   1.2    lneto <li><b>"<code>set</code>": </b> base is position 0 (beginning of the file);</li>
   10833   1.2    lneto <li><b>"<code>cur</code>": </b> base is current position;</li>
   10834   1.2    lneto <li><b>"<code>end</code>": </b> base is end of file;</li>
   10835   1.1  mbalmer </ul><p>
   10836   1.2    lneto In case of success, <code>seek</code> returns the final file position,
   10837   1.1  mbalmer measured in bytes from the beginning of the file.
   10838   1.9   nikita If <code>seek</code> fails, it returns <b>fail</b>,
   10839   1.1  mbalmer plus a string describing the error.
   10840   1.1  mbalmer 
   10841   1.1  mbalmer 
   10842   1.1  mbalmer <p>
   10843   1.1  mbalmer The default value for <code>whence</code> is <code>"cur"</code>,
   10844   1.1  mbalmer and for <code>offset</code> is 0.
   10845   1.1  mbalmer Therefore, the call <code>file:seek()</code> returns the current
   10846   1.1  mbalmer file position, without changing it;
   10847   1.1  mbalmer the call <code>file:seek("set")</code> sets the position to the
   10848   1.1  mbalmer beginning of the file (and returns 0);
   10849   1.1  mbalmer and the call <code>file:seek("end")</code> sets the position to the
   10850   1.1  mbalmer end of the file, and returns its size.
   10851   1.1  mbalmer 
   10852   1.1  mbalmer 
   10853   1.1  mbalmer 
   10854   1.1  mbalmer 
   10855   1.1  mbalmer <p>
   10856   1.1  mbalmer <hr><h3><a name="pdf-file:setvbuf"><code>file:setvbuf (mode [, size])</code></a></h3>
   10857   1.1  mbalmer 
   10858   1.1  mbalmer 
   10859   1.1  mbalmer <p>
   10860   1.9   nikita Sets the buffering mode for a file.
   10861   1.1  mbalmer There are three available modes:
   10862   1.1  mbalmer 
   10863   1.1  mbalmer <ul>
   10864   1.9   nikita <li><b>"<code>no</code>": </b> no buffering.</li>
   10865   1.9   nikita <li><b>"<code>full</code>": </b> full buffering.</li>
   10866   1.9   nikita <li><b>"<code>line</code>": </b> line buffering.</li>
   10867   1.9   nikita </ul>
   10868   1.1  mbalmer 
   10869   1.9   nikita <p>
   10870   1.9   nikita For the last two cases,
   10871   1.9   nikita <code>size</code> is a hint for the size of the buffer, in bytes.
   10872   1.9   nikita The default is an appropriate size.
   10873   1.1  mbalmer 
   10874   1.1  mbalmer 
   10875   1.9   nikita <p>
   10876   1.9   nikita The specific behavior of each mode is non portable;
   10877   1.9   nikita check the underlying ISO&nbsp;C function <code>setvbuf</code> in your platform for
   10878   1.9   nikita more details.
   10879   1.1  mbalmer 
   10880   1.1  mbalmer 
   10881   1.1  mbalmer 
   10882   1.1  mbalmer 
   10883   1.1  mbalmer <p>
   10884   1.1  mbalmer <hr><h3><a name="pdf-file:write"><code>file:write (&middot;&middot;&middot;)</code></a></h3>
   10885   1.1  mbalmer 
   10886   1.1  mbalmer 
   10887   1.1  mbalmer <p>
   10888   1.2    lneto Writes the value of each of its arguments to <code>file</code>.
   10889   1.1  mbalmer The arguments must be strings or numbers.
   10890   1.2    lneto 
   10891   1.2    lneto 
   10892   1.2    lneto <p>
   10893   1.2    lneto In case of success, this function returns <code>file</code>.
   10894   1.1  mbalmer 
   10895   1.1  mbalmer 
   10896   1.1  mbalmer 
   10897   1.1  mbalmer 
   10898   1.1  mbalmer 
   10899   1.1  mbalmer 
   10900   1.1  mbalmer 
   10901   1.2    lneto <h2>6.9 &ndash; <a name="6.9">Operating System Facilities</a></h2>
   10902   1.1  mbalmer 
   10903   1.1  mbalmer <p>
   10904   1.1  mbalmer This library is implemented through table <a name="pdf-os"><code>os</code></a>.
   10905   1.1  mbalmer 
   10906   1.1  mbalmer 
   10907   1.1  mbalmer <p>
   10908   1.1  mbalmer <hr><h3><a name="pdf-os.clock"><code>os.clock ()</code></a></h3>
   10909   1.1  mbalmer 
   10910   1.1  mbalmer 
   10911   1.1  mbalmer <p>
   10912   1.1  mbalmer Returns an approximation of the amount in seconds of CPU time
   10913   1.9   nikita used by the program,
   10914   1.9   nikita as returned by the underlying ISO&nbsp;C function <code>clock</code>.
   10915   1.1  mbalmer 
   10916   1.1  mbalmer 
   10917   1.1  mbalmer 
   10918   1.1  mbalmer 
   10919   1.1  mbalmer <p>
   10920   1.1  mbalmer <hr><h3><a name="pdf-os.date"><code>os.date ([format [, time]])</code></a></h3>
   10921   1.1  mbalmer 
   10922   1.1  mbalmer 
   10923   1.1  mbalmer <p>
   10924   1.1  mbalmer Returns a string or a table containing date and time,
   10925   1.1  mbalmer formatted according to the given string <code>format</code>.
   10926   1.1  mbalmer 
   10927   1.1  mbalmer 
   10928   1.1  mbalmer <p>
   10929   1.1  mbalmer If the <code>time</code> argument is present,
   10930   1.1  mbalmer this is the time to be formatted
   10931   1.1  mbalmer (see the <a href="#pdf-os.time"><code>os.time</code></a> function for a description of this value).
   10932   1.1  mbalmer Otherwise, <code>date</code> formats the current time.
   10933   1.1  mbalmer 
   10934   1.1  mbalmer 
   10935   1.1  mbalmer <p>
   10936   1.1  mbalmer If <code>format</code> starts with '<code>!</code>',
   10937   1.1  mbalmer then the date is formatted in Coordinated Universal Time.
   10938   1.1  mbalmer After this optional character,
   10939   1.1  mbalmer if <code>format</code> is the string "<code>*t</code>",
   10940   1.1  mbalmer then <code>date</code> returns a table with the following fields:
   10941   1.5    lneto <code>year</code>, <code>month</code> (1&ndash;12), <code>day</code> (1&ndash;31),
   10942   1.9   nikita <code>hour</code> (0&ndash;23), <code>min</code> (0&ndash;59),
   10943   1.9   nikita <code>sec</code> (0&ndash;61, due to leap seconds),
   10944   1.6  salazar <code>wday</code> (weekday, 1&ndash;7, Sunday is&nbsp;1),
   10945   1.6  salazar <code>yday</code> (day of the year, 1&ndash;366),
   10946   1.1  mbalmer and <code>isdst</code> (daylight saving flag, a boolean).
   10947   1.2    lneto This last field may be absent
   10948   1.2    lneto if the information is not available.
   10949   1.1  mbalmer 
   10950   1.1  mbalmer 
   10951   1.1  mbalmer <p>
   10952   1.1  mbalmer If <code>format</code> is not "<code>*t</code>",
   10953   1.1  mbalmer then <code>date</code> returns the date as a string,
   10954   1.3    lneto formatted according to the same rules as the ISO&nbsp;C function <code>strftime</code>.
   10955   1.1  mbalmer 
   10956   1.1  mbalmer 
   10957   1.1  mbalmer <p>
   10958   1.9   nikita If <code>format</code> is absent, it defaults to "<code>%c</code>",
   10959   1.9   nikita which gives a human-readable date and time representation
   10960   1.9   nikita using the current locale.
   10961   1.1  mbalmer 
   10962   1.1  mbalmer 
   10963   1.2    lneto <p>
   10964   1.9   nikita On non-POSIX systems,
   10965   1.2    lneto this function may be not thread safe
   10966   1.2    lneto because of its reliance on C&nbsp;function <code>gmtime</code> and C&nbsp;function <code>localtime</code>.
   10967   1.2    lneto 
   10968   1.2    lneto 
   10969   1.1  mbalmer 
   10970   1.1  mbalmer 
   10971   1.1  mbalmer <p>
   10972   1.1  mbalmer <hr><h3><a name="pdf-os.difftime"><code>os.difftime (t2, t1)</code></a></h3>
   10973   1.1  mbalmer 
   10974   1.1  mbalmer 
   10975   1.1  mbalmer <p>
   10976   1.3    lneto Returns the difference, in seconds,
   10977   1.3    lneto from time <code>t1</code> to time <code>t2</code>
   10978   1.3    lneto (where the times are values returned by <a href="#pdf-os.time"><code>os.time</code></a>).
   10979   1.1  mbalmer In POSIX, Windows, and some other systems,
   10980   1.1  mbalmer this value is exactly <code>t2</code><em>-</em><code>t1</code>.
   10981   1.1  mbalmer 
   10982   1.1  mbalmer 
   10983   1.1  mbalmer 
   10984   1.1  mbalmer 
   10985   1.1  mbalmer <p>
   10986   1.1  mbalmer <hr><h3><a name="pdf-os.execute"><code>os.execute ([command])</code></a></h3>
   10987   1.1  mbalmer 
   10988   1.1  mbalmer 
   10989   1.1  mbalmer <p>
   10990   1.3    lneto This function is equivalent to the ISO&nbsp;C function <code>system</code>.
   10991   1.1  mbalmer It passes <code>command</code> to be executed by an operating system shell.
   10992   1.2    lneto Its first result is <b>true</b>
   10993   1.2    lneto if the command terminated successfully,
   10994   1.9   nikita or <b>fail</b> otherwise.
   10995   1.2    lneto After this first result
   10996   1.2    lneto the function returns a string plus a number,
   10997   1.2    lneto as follows:
   10998   1.2    lneto 
   10999   1.2    lneto <ul>
   11000   1.2    lneto 
   11001   1.2    lneto <li><b>"<code>exit</code>": </b>
   11002   1.2    lneto the command terminated normally;
   11003   1.2    lneto the following number is the exit status of the command.
   11004   1.2    lneto </li>
   11005   1.2    lneto 
   11006   1.2    lneto <li><b>"<code>signal</code>": </b>
   11007   1.2    lneto the command was terminated by a signal;
   11008   1.2    lneto the following number is the signal that terminated the command.
   11009   1.2    lneto </li>
   11010   1.2    lneto 
   11011   1.2    lneto </ul>
   11012   1.2    lneto 
   11013   1.2    lneto <p>
   11014   1.2    lneto When called without a <code>command</code>,
   11015   1.2    lneto <code>os.execute</code> returns a boolean that is true if a shell is available.
   11016   1.2    lneto 
   11017   1.1  mbalmer 
   11018   1.1  mbalmer 
   11019   1.1  mbalmer 
   11020   1.2    lneto <p>
   11021   1.2    lneto <hr><h3><a name="pdf-os.exit"><code>os.exit ([code [, close]])</code></a></h3>
   11022   1.2    lneto 
   11023   1.1  mbalmer 
   11024   1.1  mbalmer <p>
   11025   1.3    lneto Calls the ISO&nbsp;C function <code>exit</code> to terminate the host program.
   11026   1.2    lneto If <code>code</code> is <b>true</b>,
   11027   1.2    lneto the returned status is <code>EXIT_SUCCESS</code>;
   11028   1.2    lneto if <code>code</code> is <b>false</b>,
   11029   1.2    lneto the returned status is <code>EXIT_FAILURE</code>;
   11030   1.2    lneto if <code>code</code> is a number,
   11031   1.2    lneto the returned status is this number.
   11032   1.2    lneto The default value for <code>code</code> is <b>true</b>.
   11033   1.1  mbalmer 
   11034   1.1  mbalmer 
   11035   1.1  mbalmer <p>
   11036   1.2    lneto If the optional second argument <code>close</code> is true,
   11037  1.10   nikita the function closes the Lua state before exiting (see <a href="#lua_close"><code>lua_close</code></a>).
   11038   1.1  mbalmer 
   11039   1.1  mbalmer 
   11040   1.1  mbalmer 
   11041   1.1  mbalmer 
   11042   1.1  mbalmer <p>
   11043   1.1  mbalmer <hr><h3><a name="pdf-os.getenv"><code>os.getenv (varname)</code></a></h3>
   11044   1.1  mbalmer 
   11045   1.1  mbalmer 
   11046   1.1  mbalmer <p>
   11047   1.9   nikita Returns the value of the process environment variable <code>varname</code>
   11048   1.9   nikita or <b>fail</b> if the variable is not defined.
   11049   1.1  mbalmer 
   11050   1.1  mbalmer 
   11051   1.1  mbalmer 
   11052   1.1  mbalmer 
   11053   1.1  mbalmer <p>
   11054   1.1  mbalmer <hr><h3><a name="pdf-os.remove"><code>os.remove (filename)</code></a></h3>
   11055   1.1  mbalmer 
   11056   1.1  mbalmer 
   11057   1.1  mbalmer <p>
   11058   1.2    lneto Deletes the file (or empty directory, on POSIX systems)
   11059   1.2    lneto with the given name.
   11060   1.9   nikita If this function fails, it returns <b>fail</b>
   11061   1.2    lneto plus a string describing the error and the error code.
   11062   1.7  mbalmer Otherwise, it returns true.
   11063   1.1  mbalmer 
   11064   1.1  mbalmer 
   11065   1.1  mbalmer 
   11066   1.1  mbalmer 
   11067   1.1  mbalmer <p>
   11068   1.1  mbalmer <hr><h3><a name="pdf-os.rename"><code>os.rename (oldname, newname)</code></a></h3>
   11069   1.1  mbalmer 
   11070   1.1  mbalmer 
   11071   1.1  mbalmer <p>
   11072   1.7  mbalmer Renames the file or directory named <code>oldname</code> to <code>newname</code>.
   11073   1.9   nikita If this function fails, it returns <b>fail</b>,
   11074   1.2    lneto plus a string describing the error and the error code.
   11075   1.7  mbalmer Otherwise, it returns true.
   11076   1.1  mbalmer 
   11077   1.1  mbalmer 
   11078   1.1  mbalmer 
   11079   1.1  mbalmer 
   11080   1.1  mbalmer <p>
   11081   1.1  mbalmer <hr><h3><a name="pdf-os.setlocale"><code>os.setlocale (locale [, category])</code></a></h3>
   11082   1.1  mbalmer 
   11083   1.1  mbalmer 
   11084   1.1  mbalmer <p>
   11085   1.1  mbalmer Sets the current locale of the program.
   11086   1.2    lneto <code>locale</code> is a system-dependent string specifying a locale;
   11087   1.1  mbalmer <code>category</code> is an optional string describing which category to change:
   11088   1.1  mbalmer <code>"all"</code>, <code>"collate"</code>, <code>"ctype"</code>,
   11089   1.1  mbalmer <code>"monetary"</code>, <code>"numeric"</code>, or <code>"time"</code>;
   11090   1.1  mbalmer the default category is <code>"all"</code>.
   11091   1.1  mbalmer The function returns the name of the new locale,
   11092   1.9   nikita or <b>fail</b> if the request cannot be honored.
   11093   1.1  mbalmer 
   11094   1.1  mbalmer 
   11095   1.1  mbalmer <p>
   11096   1.1  mbalmer If <code>locale</code> is the empty string,
   11097   1.1  mbalmer the current locale is set to an implementation-defined native locale.
   11098   1.1  mbalmer If <code>locale</code> is the string "<code>C</code>",
   11099   1.1  mbalmer the current locale is set to the standard C locale.
   11100   1.1  mbalmer 
   11101   1.1  mbalmer 
   11102   1.1  mbalmer <p>
   11103   1.1  mbalmer When called with <b>nil</b> as the first argument,
   11104   1.1  mbalmer this function only returns the name of the current locale
   11105   1.1  mbalmer for the given category.
   11106   1.1  mbalmer 
   11107   1.1  mbalmer 
   11108   1.2    lneto <p>
   11109   1.2    lneto This function may be not thread safe
   11110   1.2    lneto because of its reliance on C&nbsp;function <code>setlocale</code>.
   11111   1.2    lneto 
   11112   1.2    lneto 
   11113   1.1  mbalmer 
   11114   1.1  mbalmer 
   11115   1.1  mbalmer <p>
   11116   1.1  mbalmer <hr><h3><a name="pdf-os.time"><code>os.time ([table])</code></a></h3>
   11117   1.1  mbalmer 
   11118   1.1  mbalmer 
   11119   1.1  mbalmer <p>
   11120   1.1  mbalmer Returns the current time when called without arguments,
   11121   1.4  mbalmer or a time representing the local date and time specified by the given table.
   11122   1.1  mbalmer This table must have fields <code>year</code>, <code>month</code>, and <code>day</code>,
   11123   1.2    lneto and may have fields
   11124   1.2    lneto <code>hour</code> (default is 12),
   11125   1.2    lneto <code>min</code> (default is 0),
   11126   1.2    lneto <code>sec</code> (default is 0),
   11127   1.2    lneto and <code>isdst</code> (default is <b>nil</b>).
   11128   1.4  mbalmer Other fields are ignored.
   11129   1.2    lneto For a description of these fields, see the <a href="#pdf-os.date"><code>os.date</code></a> function.
   11130   1.1  mbalmer 
   11131   1.1  mbalmer 
   11132   1.1  mbalmer <p>
   11133   1.9   nikita When the function is called,
   11134   1.9   nikita the values in these fields do not need to be inside their valid ranges.
   11135   1.4  mbalmer For instance, if <code>sec</code> is -10,
   11136   1.9   nikita it means 10 seconds before the time specified by the other fields;
   11137   1.4  mbalmer if <code>hour</code> is 1000,
   11138   1.9   nikita it means 1000 hours after the time specified by the other fields.
   11139   1.4  mbalmer 
   11140   1.4  mbalmer 
   11141   1.4  mbalmer <p>
   11142   1.1  mbalmer The returned value is a number, whose meaning depends on your system.
   11143   1.2    lneto In POSIX, Windows, and some other systems,
   11144   1.2    lneto this number counts the number
   11145   1.1  mbalmer of seconds since some given start time (the "epoch").
   11146   1.1  mbalmer In other systems, the meaning is not specified,
   11147   1.1  mbalmer and the number returned by <code>time</code> can be used only as an argument to
   11148   1.2    lneto <a href="#pdf-os.date"><code>os.date</code></a> and <a href="#pdf-os.difftime"><code>os.difftime</code></a>.
   11149   1.1  mbalmer 
   11150   1.1  mbalmer 
   11151   1.9   nikita <p>
   11152   1.9   nikita When called with a table,
   11153   1.9   nikita <code>os.time</code> also normalizes all the fields
   11154   1.9   nikita documented in the <a href="#pdf-os.date"><code>os.date</code></a> function,
   11155   1.9   nikita so that they represent the same time as before the call
   11156   1.9   nikita but with values inside their valid ranges.
   11157   1.9   nikita 
   11158   1.9   nikita 
   11159   1.1  mbalmer 
   11160   1.1  mbalmer 
   11161   1.1  mbalmer <p>
   11162   1.1  mbalmer <hr><h3><a name="pdf-os.tmpname"><code>os.tmpname ()</code></a></h3>
   11163   1.1  mbalmer 
   11164   1.1  mbalmer 
   11165   1.1  mbalmer <p>
   11166   1.1  mbalmer Returns a string with a file name that can
   11167   1.1  mbalmer be used for a temporary file.
   11168   1.1  mbalmer The file must be explicitly opened before its use
   11169   1.1  mbalmer and explicitly removed when no longer needed.
   11170   1.1  mbalmer 
   11171   1.1  mbalmer 
   11172   1.1  mbalmer <p>
   11173   1.8    alnsn In POSIX systems,
   11174   1.1  mbalmer this function also creates a file with that name,
   11175   1.1  mbalmer to avoid security risks.
   11176   1.1  mbalmer (Someone else might create the file with wrong permissions
   11177   1.1  mbalmer in the time between getting the name and creating the file.)
   11178   1.1  mbalmer You still have to open the file to use it
   11179   1.1  mbalmer and to remove it (even if you do not use it).
   11180   1.1  mbalmer 
   11181   1.1  mbalmer 
   11182   1.1  mbalmer <p>
   11183   1.1  mbalmer When possible,
   11184   1.1  mbalmer you may prefer to use <a href="#pdf-io.tmpfile"><code>io.tmpfile</code></a>,
   11185   1.1  mbalmer which automatically removes the file when the program ends.
   11186   1.1  mbalmer 
   11187   1.1  mbalmer 
   11188   1.1  mbalmer 
   11189   1.1  mbalmer 
   11190   1.1  mbalmer 
   11191   1.1  mbalmer 
   11192   1.1  mbalmer 
   11193   1.2    lneto <h2>6.10 &ndash; <a name="6.10">The Debug Library</a></h2>
   11194   1.1  mbalmer 
   11195   1.1  mbalmer <p>
   11196   1.1  mbalmer This library provides
   11197   1.9   nikita the functionality of the debug interface (<a href="#4.7">&sect;4.7</a>) to Lua programs.
   11198   1.1  mbalmer You should exert care when using this library.
   11199   1.2    lneto Several of its functions
   11200   1.2    lneto violate basic assumptions about Lua code
   11201   1.1  mbalmer (e.g., that variables local to a function
   11202   1.2    lneto cannot be accessed from outside;
   11203   1.2    lneto that userdata metatables cannot be changed by Lua code;
   11204   1.2    lneto that Lua programs do not crash)
   11205   1.1  mbalmer and therefore can compromise otherwise secure code.
   11206   1.2    lneto Moreover, some functions in this library may be slow.
   11207   1.1  mbalmer 
   11208   1.1  mbalmer 
   11209   1.1  mbalmer <p>
   11210   1.1  mbalmer All functions in this library are provided
   11211   1.1  mbalmer inside the <a name="pdf-debug"><code>debug</code></a> table.
   11212   1.1  mbalmer All functions that operate over a thread
   11213   1.1  mbalmer have an optional first argument which is the
   11214   1.1  mbalmer thread to operate over.
   11215   1.1  mbalmer The default is always the current thread.
   11216   1.1  mbalmer 
   11217   1.1  mbalmer 
   11218   1.1  mbalmer <p>
   11219   1.1  mbalmer <hr><h3><a name="pdf-debug.debug"><code>debug.debug ()</code></a></h3>
   11220   1.1  mbalmer 
   11221   1.1  mbalmer 
   11222   1.1  mbalmer <p>
   11223   1.1  mbalmer Enters an interactive mode with the user,
   11224   1.1  mbalmer running each string that the user enters.
   11225   1.1  mbalmer Using simple commands and other debug facilities,
   11226   1.1  mbalmer the user can inspect global and local variables,
   11227   1.1  mbalmer change their values, evaluate expressions, and so on.
   11228   1.1  mbalmer A line containing only the word <code>cont</code> finishes this function,
   11229   1.1  mbalmer so that the caller continues its execution.
   11230   1.1  mbalmer 
   11231   1.1  mbalmer 
   11232   1.1  mbalmer <p>
   11233   1.1  mbalmer Note that commands for <code>debug.debug</code> are not lexically nested
   11234   1.2    lneto within any function and so have no direct access to local variables.
   11235   1.1  mbalmer 
   11236   1.1  mbalmer 
   11237   1.1  mbalmer 
   11238   1.1  mbalmer 
   11239   1.1  mbalmer <p>
   11240   1.1  mbalmer <hr><h3><a name="pdf-debug.gethook"><code>debug.gethook ([thread])</code></a></h3>
   11241   1.1  mbalmer 
   11242   1.1  mbalmer 
   11243   1.1  mbalmer <p>
   11244   1.1  mbalmer Returns the current hook settings of the thread, as three values:
   11245   1.1  mbalmer the current hook function, the current hook mask,
   11246   1.9   nikita and the current hook count,
   11247   1.9   nikita as set by the <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> function.
   11248   1.9   nikita 
   11249   1.9   nikita 
   11250   1.9   nikita <p>
   11251   1.9   nikita Returns <b>fail</b> if there is no active hook.
   11252   1.1  mbalmer 
   11253   1.1  mbalmer 
   11254   1.1  mbalmer 
   11255   1.1  mbalmer 
   11256   1.1  mbalmer <p>
   11257   1.2    lneto <hr><h3><a name="pdf-debug.getinfo"><code>debug.getinfo ([thread,] f [, what])</code></a></h3>
   11258   1.1  mbalmer 
   11259   1.1  mbalmer 
   11260   1.1  mbalmer <p>
   11261   1.1  mbalmer Returns a table with information about a function.
   11262   1.2    lneto You can give the function directly
   11263   1.2    lneto or you can give a number as the value of <code>f</code>,
   11264   1.2    lneto which means the function running at level <code>f</code> of the call stack
   11265   1.1  mbalmer of the given thread:
   11266   1.1  mbalmer level&nbsp;0 is the current function (<code>getinfo</code> itself);
   11267   1.2    lneto level&nbsp;1 is the function that called <code>getinfo</code>
   11268   1.9   nikita (except for tail calls, which do not count in the stack);
   11269   1.1  mbalmer and so on.
   11270   1.9   nikita If <code>f</code> is a number greater than the number of active functions,
   11271   1.9   nikita then <code>getinfo</code> returns <b>fail</b>.
   11272   1.1  mbalmer 
   11273   1.1  mbalmer 
   11274   1.1  mbalmer <p>
   11275   1.1  mbalmer The returned table can contain all the fields returned by <a href="#lua_getinfo"><code>lua_getinfo</code></a>,
   11276   1.1  mbalmer with the string <code>what</code> describing which fields to fill in.
   11277   1.1  mbalmer The default for <code>what</code> is to get all information available,
   11278   1.1  mbalmer except the table of valid lines.
   11279   1.1  mbalmer If present,
   11280   1.1  mbalmer the option '<code>f</code>'
   11281   1.1  mbalmer adds a field named <code>func</code> with the function itself.
   11282   1.1  mbalmer If present,
   11283   1.1  mbalmer the option '<code>L</code>'
   11284   1.1  mbalmer adds a field named <code>activelines</code> with the table of
   11285   1.1  mbalmer valid lines.
   11286   1.1  mbalmer 
   11287   1.1  mbalmer 
   11288   1.1  mbalmer <p>
   11289   1.1  mbalmer For instance, the expression <code>debug.getinfo(1,"n").name</code> returns
   11290   1.4  mbalmer a name for the current function,
   11291   1.1  mbalmer if a reasonable name can be found,
   11292   1.1  mbalmer and the expression <code>debug.getinfo(print)</code>
   11293   1.1  mbalmer returns a table with all available information
   11294   1.1  mbalmer about the <a href="#pdf-print"><code>print</code></a> function.
   11295   1.1  mbalmer 
   11296   1.1  mbalmer 
   11297   1.1  mbalmer 
   11298   1.1  mbalmer 
   11299   1.1  mbalmer <p>
   11300   1.2    lneto <hr><h3><a name="pdf-debug.getlocal"><code>debug.getlocal ([thread,] f, local)</code></a></h3>
   11301   1.1  mbalmer 
   11302   1.1  mbalmer 
   11303   1.1  mbalmer <p>
   11304   1.1  mbalmer This function returns the name and the value of the local variable
   11305   1.2    lneto with index <code>local</code> of the function at level <code>f</code> of the stack.
   11306   1.2    lneto This function accesses not only explicit local variables,
   11307   1.9   nikita but also parameters and temporary values.
   11308   1.2    lneto 
   11309   1.2    lneto 
   11310   1.2    lneto <p>
   11311   1.2    lneto The first parameter or local variable has index&nbsp;1, and so on,
   11312   1.3    lneto following the order that they are declared in the code,
   11313   1.3    lneto counting only the variables that are active
   11314   1.3    lneto in the current scope of the function.
   11315   1.9   nikita Compile-time constants may not appear in this listing,
   11316   1.9   nikita if they were optimized away by the compiler.
   11317   1.8    alnsn Negative indices refer to vararg arguments;
   11318   1.8    alnsn -1 is the first vararg argument.
   11319   1.9   nikita The function returns <b>fail</b>
   11320   1.9   nikita if there is no variable with the given index,
   11321   1.2    lneto and raises an error when called with a level out of range.
   11322   1.1  mbalmer (You can call <a href="#pdf-debug.getinfo"><code>debug.getinfo</code></a> to check whether the level is valid.)
   11323   1.1  mbalmer 
   11324   1.1  mbalmer 
   11325   1.1  mbalmer <p>
   11326   1.2    lneto Variable names starting with '<code>(</code>' (open parenthesis) 
   11327   1.2    lneto represent variables with no known names
   11328   1.3    lneto (internal variables such as loop control variables,
   11329   1.2    lneto and variables from chunks saved without debug information).
   11330   1.2    lneto 
   11331   1.2    lneto 
   11332   1.2    lneto <p>
   11333   1.2    lneto The parameter <code>f</code> may also be a function.
   11334   1.2    lneto In that case, <code>getlocal</code> returns only the name of function parameters.
   11335   1.1  mbalmer 
   11336   1.1  mbalmer 
   11337   1.1  mbalmer 
   11338   1.1  mbalmer 
   11339   1.1  mbalmer <p>
   11340   1.2    lneto <hr><h3><a name="pdf-debug.getmetatable"><code>debug.getmetatable (value)</code></a></h3>
   11341   1.1  mbalmer 
   11342   1.1  mbalmer 
   11343   1.1  mbalmer <p>
   11344   1.2    lneto Returns the metatable of the given <code>value</code>
   11345   1.1  mbalmer or <b>nil</b> if it does not have a metatable.
   11346   1.1  mbalmer 
   11347   1.1  mbalmer 
   11348   1.1  mbalmer 
   11349   1.1  mbalmer 
   11350   1.1  mbalmer <p>
   11351   1.1  mbalmer <hr><h3><a name="pdf-debug.getregistry"><code>debug.getregistry ()</code></a></h3>
   11352   1.1  mbalmer 
   11353   1.1  mbalmer 
   11354   1.1  mbalmer <p>
   11355   1.9   nikita Returns the registry table (see <a href="#4.3">&sect;4.3</a>).
   11356   1.1  mbalmer 
   11357   1.1  mbalmer 
   11358   1.1  mbalmer 
   11359   1.1  mbalmer 
   11360   1.1  mbalmer <p>
   11361   1.2    lneto <hr><h3><a name="pdf-debug.getupvalue"><code>debug.getupvalue (f, up)</code></a></h3>
   11362   1.1  mbalmer 
   11363   1.1  mbalmer 
   11364   1.1  mbalmer <p>
   11365   1.1  mbalmer This function returns the name and the value of the upvalue
   11366   1.2    lneto with index <code>up</code> of the function <code>f</code>.
   11367   1.9   nikita The function returns <b>fail</b>
   11368   1.9   nikita if there is no upvalue with the given index.
   11369   1.1  mbalmer 
   11370   1.1  mbalmer 
   11371   1.2    lneto <p>
   11372   1.9   nikita (For Lua functions,
   11373   1.9   nikita upvalues are the external local variables that the function uses,
   11374   1.9   nikita and that are consequently included in its closure.)
   11375   1.9   nikita 
   11376   1.9   nikita 
   11377   1.9   nikita <p>
   11378   1.9   nikita For C&nbsp;functions, this function uses the empty string <code>""</code>
   11379   1.9   nikita as a name for all upvalues.
   11380   1.9   nikita 
   11381   1.9   nikita 
   11382   1.9   nikita <p>
   11383   1.9   nikita Variable name '<code>?</code>' (interrogation mark)
   11384   1.9   nikita represents variables with no known names
   11385   1.2    lneto (variables from chunks saved without debug information).
   11386   1.2    lneto 
   11387   1.2    lneto 
   11388   1.1  mbalmer 
   11389   1.1  mbalmer 
   11390   1.1  mbalmer <p>
   11391   1.9   nikita <hr><h3><a name="pdf-debug.getuservalue"><code>debug.getuservalue (u, n)</code></a></h3>
   11392   1.1  mbalmer 
   11393   1.1  mbalmer 
   11394   1.1  mbalmer <p>
   11395   1.9   nikita Returns the <code>n</code>-th user value associated
   11396   1.9   nikita to the userdata <code>u</code> plus a boolean,
   11397   1.9   nikita <b>false</b> if the userdata does not have that value.
   11398   1.1  mbalmer 
   11399   1.1  mbalmer 
   11400   1.1  mbalmer 
   11401   1.1  mbalmer 
   11402   1.1  mbalmer <p>
   11403   1.1  mbalmer <hr><h3><a name="pdf-debug.sethook"><code>debug.sethook ([thread,] hook, mask [, count])</code></a></h3>
   11404   1.1  mbalmer 
   11405   1.1  mbalmer 
   11406   1.1  mbalmer <p>
   11407   1.9   nikita Sets the given function as the debug hook.
   11408   1.1  mbalmer The string <code>mask</code> and the number <code>count</code> describe
   11409   1.1  mbalmer when the hook will be called.
   11410   1.2    lneto The string mask may have any combination of the following characters,
   11411   1.1  mbalmer with the given meaning:
   11412   1.1  mbalmer 
   11413   1.1  mbalmer <ul>
   11414   1.2    lneto <li><b>'<code>c</code>': </b> the hook is called every time Lua calls a function;</li>
   11415   1.2    lneto <li><b>'<code>r</code>': </b> the hook is called every time Lua returns from a function;</li>
   11416   1.2    lneto <li><b>'<code>l</code>': </b> the hook is called every time Lua enters a new line of code.</li>
   11417   1.1  mbalmer </ul><p>
   11418   1.2    lneto Moreover,
   11419   1.2    lneto with a <code>count</code> different from zero,
   11420   1.2    lneto the hook is called also after every <code>count</code> instructions.
   11421   1.1  mbalmer 
   11422   1.1  mbalmer 
   11423   1.1  mbalmer <p>
   11424   1.1  mbalmer When called without arguments,
   11425   1.1  mbalmer <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> turns off the hook.
   11426   1.1  mbalmer 
   11427   1.1  mbalmer 
   11428   1.1  mbalmer <p>
   11429   1.9   nikita When the hook is called, its first parameter is a string
   11430   1.1  mbalmer describing the event that has triggered its call:
   11431   1.9   nikita <code>"call"</code>, <code>"tail call"</code>, <code>"return"</code>,
   11432   1.1  mbalmer <code>"line"</code>, and <code>"count"</code>.
   11433   1.1  mbalmer For line events,
   11434   1.1  mbalmer the hook also gets the new line number as its second parameter.
   11435   1.1  mbalmer Inside a hook,
   11436   1.1  mbalmer you can call <code>getinfo</code> with level&nbsp;2 to get more information about
   11437   1.9   nikita the running function.
   11438   1.9   nikita (Level&nbsp;0 is the <code>getinfo</code> function,
   11439   1.9   nikita and level&nbsp;1 is the hook function.)
   11440   1.1  mbalmer 
   11441   1.1  mbalmer 
   11442   1.1  mbalmer 
   11443   1.1  mbalmer 
   11444   1.1  mbalmer <p>
   11445   1.1  mbalmer <hr><h3><a name="pdf-debug.setlocal"><code>debug.setlocal ([thread,] level, local, value)</code></a></h3>
   11446   1.1  mbalmer 
   11447   1.1  mbalmer 
   11448   1.1  mbalmer <p>
   11449   1.1  mbalmer This function assigns the value <code>value</code> to the local variable
   11450   1.1  mbalmer with index <code>local</code> of the function at level <code>level</code> of the stack.
   11451   1.9   nikita The function returns <b>fail</b> if there is no local
   11452   1.1  mbalmer variable with the given index,
   11453   1.1  mbalmer and raises an error when called with a <code>level</code> out of range.
   11454   1.1  mbalmer (You can call <code>getinfo</code> to check whether the level is valid.)
   11455   1.1  mbalmer Otherwise, it returns the name of the local variable.
   11456   1.1  mbalmer 
   11457   1.1  mbalmer 
   11458   1.2    lneto <p>
   11459   1.2    lneto See <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for more information about
   11460   1.2    lneto variable indices and names.
   11461   1.2    lneto 
   11462   1.2    lneto 
   11463   1.1  mbalmer 
   11464   1.1  mbalmer 
   11465   1.1  mbalmer <p>
   11466   1.2    lneto <hr><h3><a name="pdf-debug.setmetatable"><code>debug.setmetatable (value, table)</code></a></h3>
   11467   1.1  mbalmer 
   11468   1.1  mbalmer 
   11469   1.1  mbalmer <p>
   11470   1.2    lneto Sets the metatable for the given <code>value</code> to the given <code>table</code>
   11471   1.1  mbalmer (which can be <b>nil</b>).
   11472   1.2    lneto Returns <code>value</code>.
   11473   1.1  mbalmer 
   11474   1.1  mbalmer 
   11475   1.1  mbalmer 
   11476   1.1  mbalmer 
   11477   1.1  mbalmer <p>
   11478   1.2    lneto <hr><h3><a name="pdf-debug.setupvalue"><code>debug.setupvalue (f, up, value)</code></a></h3>
   11479   1.1  mbalmer 
   11480   1.1  mbalmer 
   11481   1.1  mbalmer <p>
   11482   1.1  mbalmer This function assigns the value <code>value</code> to the upvalue
   11483   1.2    lneto with index <code>up</code> of the function <code>f</code>.
   11484   1.9   nikita The function returns <b>fail</b> if there is no upvalue
   11485   1.1  mbalmer with the given index.
   11486   1.1  mbalmer Otherwise, it returns the name of the upvalue.
   11487   1.1  mbalmer 
   11488   1.1  mbalmer 
   11489   1.9   nikita <p>
   11490   1.9   nikita See <a href="#pdf-debug.getupvalue"><code>debug.getupvalue</code></a> for more information about upvalues.
   11491   1.9   nikita 
   11492   1.9   nikita 
   11493   1.1  mbalmer 
   11494   1.1  mbalmer 
   11495   1.1  mbalmer <p>
   11496   1.9   nikita <hr><h3><a name="pdf-debug.setuservalue"><code>debug.setuservalue (udata, value, n)</code></a></h3>
   11497   1.2    lneto 
   11498   1.2    lneto 
   11499   1.2    lneto <p>
   11500   1.2    lneto Sets the given <code>value</code> as
   11501   1.9   nikita the <code>n</code>-th user value associated to the given <code>udata</code>.
   11502   1.2    lneto <code>udata</code> must be a full userdata.
   11503   1.2    lneto 
   11504   1.2    lneto 
   11505   1.2    lneto <p>
   11506   1.9   nikita Returns <code>udata</code>,
   11507   1.9   nikita or <b>fail</b> if the userdata does not have that value.
   11508   1.2    lneto 
   11509   1.2    lneto 
   11510   1.2    lneto 
   11511   1.2    lneto 
   11512   1.2    lneto <p>
   11513   1.2    lneto <hr><h3><a name="pdf-debug.traceback"><code>debug.traceback ([thread,] [message [, level]])</code></a></h3>
   11514   1.1  mbalmer 
   11515   1.1  mbalmer 
   11516   1.1  mbalmer <p>
   11517   1.2    lneto If <code>message</code> is present but is neither a string nor <b>nil</b>,
   11518   1.2    lneto this function returns <code>message</code> without further processing.
   11519   1.2    lneto Otherwise,
   11520   1.2    lneto it returns a string with a traceback of the call stack.
   11521   1.3    lneto The optional <code>message</code> string is appended
   11522   1.1  mbalmer at the beginning of the traceback.
   11523   1.1  mbalmer An optional <code>level</code> number tells at which level
   11524   1.1  mbalmer to start the traceback
   11525   1.1  mbalmer (default is 1, the function calling <code>traceback</code>).
   11526   1.1  mbalmer 
   11527   1.1  mbalmer 
   11528   1.1  mbalmer 
   11529   1.1  mbalmer 
   11530   1.2    lneto <p>
   11531   1.2    lneto <hr><h3><a name="pdf-debug.upvalueid"><code>debug.upvalueid (f, n)</code></a></h3>
   11532   1.2    lneto 
   11533   1.2    lneto 
   11534   1.2    lneto <p>
   11535   1.3    lneto Returns a unique identifier (as a light userdata)
   11536   1.2    lneto for the upvalue numbered <code>n</code>
   11537   1.2    lneto from the given function.
   11538   1.2    lneto 
   11539   1.2    lneto 
   11540   1.2    lneto <p>
   11541   1.2    lneto These unique identifiers allow a program to check whether different
   11542   1.2    lneto closures share upvalues.
   11543   1.2    lneto Lua closures that share an upvalue
   11544   1.2    lneto (that is, that access a same external local variable)
   11545   1.2    lneto will return identical ids for those upvalue indices.
   11546   1.2    lneto 
   11547   1.2    lneto 
   11548   1.2    lneto 
   11549   1.2    lneto 
   11550   1.2    lneto <p>
   11551   1.2    lneto <hr><h3><a name="pdf-debug.upvaluejoin"><code>debug.upvaluejoin (f1, n1, f2, n2)</code></a></h3>
   11552   1.2    lneto 
   11553   1.2    lneto 
   11554   1.2    lneto <p>
   11555   1.2    lneto Make the <code>n1</code>-th upvalue of the Lua closure <code>f1</code>
   11556   1.2    lneto refer to the <code>n2</code>-th upvalue of the Lua closure <code>f2</code>.
   11557   1.2    lneto 
   11558   1.2    lneto 
   11559   1.2    lneto 
   11560   1.2    lneto 
   11561   1.1  mbalmer 
   11562   1.1  mbalmer 
   11563   1.1  mbalmer 
   11564   1.2    lneto <h1>7 &ndash; <a name="7">Lua Standalone</a></h1>
   11565   1.1  mbalmer 
   11566   1.1  mbalmer <p>
   11567   1.1  mbalmer Although Lua has been designed as an extension language,
   11568   1.1  mbalmer to be embedded in a host C&nbsp;program,
   11569   1.2    lneto it is also frequently used as a standalone language.
   11570   1.2    lneto An interpreter for Lua as a standalone language,
   11571   1.1  mbalmer called simply <code>lua</code>,
   11572   1.1  mbalmer is provided with the standard distribution.
   11573   1.2    lneto The standalone interpreter includes
   11574   1.9   nikita all standard libraries.
   11575   1.1  mbalmer Its usage is:
   11576   1.1  mbalmer 
   11577   1.1  mbalmer <pre>
   11578   1.1  mbalmer      lua [options] [script [args]]
   11579   1.1  mbalmer </pre><p>
   11580   1.1  mbalmer The options are:
   11581   1.1  mbalmer 
   11582   1.1  mbalmer <ul>
   11583   1.9   nikita <li><b><code>-e <em>stat</em></code>: </b> execute string <em>stat</em>;</li>
   11584   1.9   nikita <li><b><code>-i</code>: </b> enter interactive mode after running <em>script</em>;</li>
   11585   1.9   nikita <li><b><code>-l <em>mod</em></code>: </b> "require" <em>mod</em> and assign the
   11586   1.9   nikita   result to global <em>mod</em>;</li>
   11587  1.10   nikita <li><b><code>-l <em>g=mod</em></code>: </b> "require" <em>mod</em> and assign the
   11588  1.10   nikita   result to global <em>g</em>;</li>
   11589   1.9   nikita <li><b><code>-v</code>: </b> print version information;</li>
   11590   1.9   nikita <li><b><code>-E</code>: </b> ignore environment variables;</li>
   11591   1.9   nikita <li><b><code>-W</code>: </b> turn warnings on;</li>
   11592   1.9   nikita <li><b><code>--</code>: </b> stop handling options;</li>
   11593   1.9   nikita <li><b><code>-</code>: </b> execute <code>stdin</code> as a file and stop handling options.</li>
   11594   1.1  mbalmer </ul><p>
   11595  1.10   nikita (The form <code>-l <em>g=mod</em></code> was introduced in release&nbsp;5.4.4.)
   11596  1.10   nikita 
   11597  1.10   nikita 
   11598  1.10   nikita <p>
   11599   1.3    lneto After handling its options, <code>lua</code> runs the given <em>script</em>.
   11600   1.1  mbalmer When called without arguments,
   11601   1.1  mbalmer <code>lua</code> behaves as <code>lua -v -i</code>
   11602   1.1  mbalmer when the standard input (<code>stdin</code>) is a terminal,
   11603   1.1  mbalmer and as <code>lua -</code> otherwise.
   11604   1.1  mbalmer 
   11605   1.1  mbalmer 
   11606   1.1  mbalmer <p>
   11607   1.9   nikita When called without the option <code>-E</code>,
   11608   1.9   nikita the interpreter checks for an environment variable <a name="pdf-LUA_INIT_5_4"><code>LUA_INIT_5_4</code></a>
   11609   1.3    lneto (or <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a> if the versioned name is not defined)
   11610   1.2    lneto before running any argument.
   11611   1.2    lneto If the variable content has the format <code>@<em>filename</em></code>,
   11612   1.1  mbalmer then <code>lua</code> executes the file.
   11613   1.1  mbalmer Otherwise, <code>lua</code> executes the string itself.
   11614   1.1  mbalmer 
   11615   1.1  mbalmer 
   11616   1.1  mbalmer <p>
   11617   1.9   nikita When called with the option <code>-E</code>,
   11618   1.9   nikita Lua does not consult any environment variables.
   11619   1.9   nikita In particular,
   11620   1.9   nikita the values of <a href="#pdf-package.path"><code>package.path</code></a> and <a href="#pdf-package.cpath"><code>package.cpath</code></a>
   11621   1.9   nikita are set with the default paths defined in <code>luaconf.h</code>.
   11622   1.2    lneto 
   11623   1.2    lneto 
   11624   1.2    lneto <p>
   11625   1.9   nikita The options <code>-e</code>, <code>-l</code>, and <code>-W</code> are handled in
   11626   1.9   nikita the order they appear.
   11627   1.1  mbalmer For instance, an invocation like
   11628   1.1  mbalmer 
   11629   1.1  mbalmer <pre>
   11630   1.9   nikita      $ lua -e 'a=1' -llib1 script.lua
   11631   1.1  mbalmer </pre><p>
   11632   1.9   nikita will first set <code>a</code> to 1, then require the library <code>lib1</code>,
   11633   1.1  mbalmer and finally run the file <code>script.lua</code> with no arguments.
   11634   1.1  mbalmer (Here <code>$</code> is the shell prompt. Your prompt may be different.)
   11635   1.1  mbalmer 
   11636   1.1  mbalmer 
   11637   1.1  mbalmer <p>
   11638   1.2    lneto Before running any code,
   11639   1.2    lneto <code>lua</code> collects all command-line arguments
   11640   1.1  mbalmer in a global table called <code>arg</code>.
   11641   1.2    lneto The script name goes to index 0,
   11642   1.1  mbalmer the first argument after the script name goes to index 1,
   11643   1.1  mbalmer and so on.
   11644   1.1  mbalmer Any arguments before the script name
   11645   1.2    lneto (that is, the interpreter name plus its options)
   11646   1.1  mbalmer go to negative indices.
   11647   1.1  mbalmer For instance, in the call
   11648   1.1  mbalmer 
   11649   1.1  mbalmer <pre>
   11650   1.1  mbalmer      $ lua -la b.lua t1 t2
   11651   1.1  mbalmer </pre><p>
   11652   1.2    lneto the table is like this:
   11653   1.1  mbalmer 
   11654   1.1  mbalmer <pre>
   11655   1.1  mbalmer      arg = { [-2] = "lua", [-1] = "-la",
   11656   1.1  mbalmer              [0] = "b.lua",
   11657   1.1  mbalmer              [1] = "t1", [2] = "t2" }
   11658   1.1  mbalmer </pre><p>
   11659   1.2    lneto If there is no script in the call,
   11660   1.2    lneto the interpreter name goes to index 0,
   11661   1.2    lneto followed by the other arguments.
   11662   1.2    lneto For instance, the call
   11663   1.2    lneto 
   11664   1.2    lneto <pre>
   11665   1.2    lneto      $ lua -e "print(arg[1])"
   11666   1.2    lneto </pre><p>
   11667   1.2    lneto will print "<code>-e</code>".
   11668   1.3    lneto If there is a script,
   11669   1.8    alnsn the script is called with arguments
   11670   1.3    lneto <code>arg[1]</code>, &middot;&middot;&middot;, <code>arg[#arg]</code>.
   11671   1.9   nikita Like all chunks in Lua,
   11672  1.10   nikita the script is compiled as a variadic function.
   11673   1.1  mbalmer 
   11674   1.1  mbalmer 
   11675   1.1  mbalmer <p>
   11676   1.1  mbalmer In interactive mode,
   11677   1.2    lneto Lua repeatedly prompts and waits for a line.
   11678   1.2    lneto After reading a line,
   11679   1.2    lneto Lua first try to interpret the line as an expression.
   11680   1.2    lneto If it succeeds, it prints its value.
   11681   1.2    lneto Otherwise, it interprets the line as a statement.
   11682   1.2    lneto If you write an incomplete statement,
   11683   1.1  mbalmer the interpreter waits for its completion
   11684   1.1  mbalmer by issuing a different prompt.
   11685   1.1  mbalmer 
   11686   1.1  mbalmer 
   11687   1.1  mbalmer <p>
   11688   1.6  salazar If the global variable <a name="pdf-_PROMPT"><code>_PROMPT</code></a> contains a string,
   11689   1.6  salazar then its value is used as the prompt.
   11690   1.6  salazar Similarly, if the global variable <a name="pdf-_PROMPT2"><code>_PROMPT2</code></a> contains a string,
   11691   1.6  salazar its value is used as the secondary prompt
   11692   1.6  salazar (issued during incomplete statements).
   11693   1.6  salazar 
   11694   1.6  salazar 
   11695   1.6  salazar <p>
   11696   1.2    lneto In case of unprotected errors in the script,
   11697   1.2    lneto the interpreter reports the error to the standard error stream.
   11698   1.7  mbalmer If the error object is not a string but
   11699   1.3    lneto has a metamethod <code>__tostring</code>,
   11700   1.2    lneto the interpreter calls this metamethod to produce the final message.
   11701   1.3    lneto Otherwise, the interpreter converts the error object to a string
   11702   1.3    lneto and adds a stack traceback to it.
   11703   1.9   nikita When warnings are on,
   11704   1.9   nikita they are simply printed in the standard error output.
   11705   1.2    lneto 
   11706   1.2    lneto 
   11707   1.2    lneto <p>
   11708   1.2    lneto When finishing normally,
   11709   1.2    lneto the interpreter closes its main Lua state
   11710   1.2    lneto (see <a href="#lua_close"><code>lua_close</code></a>).
   11711   1.2    lneto The script can avoid this step by
   11712   1.2    lneto calling <a href="#pdf-os.exit"><code>os.exit</code></a> to terminate.
   11713   1.1  mbalmer 
   11714   1.1  mbalmer 
   11715   1.1  mbalmer <p>
   11716   1.1  mbalmer To allow the use of Lua as a
   11717   1.1  mbalmer script interpreter in Unix systems,
   11718   1.9   nikita Lua skips the first line of a file chunk if it starts with <code>#</code>.
   11719   1.1  mbalmer Therefore, Lua scripts can be made into executable programs
   11720   1.1  mbalmer by using <code>chmod +x</code> and the&nbsp;<code>#!</code> form,
   11721   1.1  mbalmer as in
   11722   1.1  mbalmer 
   11723   1.1  mbalmer <pre>
   11724   1.1  mbalmer      #!/usr/local/bin/lua
   11725   1.1  mbalmer </pre><p>
   11726   1.9   nikita Of course,
   11727   1.1  mbalmer the location of the Lua interpreter may be different in your machine.
   11728   1.1  mbalmer If <code>lua</code> is in your <code>PATH</code>,
   11729   1.2    lneto then
   11730   1.1  mbalmer 
   11731   1.1  mbalmer <pre>
   11732   1.1  mbalmer      #!/usr/bin/env lua
   11733   1.1  mbalmer </pre><p>
   11734   1.9   nikita is a more portable solution.
   11735   1.1  mbalmer 
   11736   1.1  mbalmer 
   11737   1.1  mbalmer 
   11738   1.2    lneto <h1>8 &ndash; <a name="8">Incompatibilities with the Previous Version</a></h1>
   11739   1.1  mbalmer 
   11740   1.9   nikita 
   11741   1.9   nikita 
   11742   1.1  mbalmer <p>
   11743   1.1  mbalmer Here we list the incompatibilities that you may find when moving a program
   11744   1.9   nikita from Lua&nbsp;5.3 to Lua&nbsp;5.4.
   11745   1.9   nikita 
   11746   1.9   nikita 
   11747   1.9   nikita <p>
   11748   1.2    lneto You can avoid some incompatibilities by compiling Lua with
   11749   1.1  mbalmer appropriate options (see file <code>luaconf.h</code>).
   11750   1.1  mbalmer However,
   11751   1.2    lneto all these compatibility options will be removed in the future.
   11752   1.9   nikita More often than not,
   11753   1.9   nikita compatibility issues arise when these compatibility options
   11754   1.9   nikita are removed.
   11755   1.9   nikita So, whenever you have the chance,
   11756   1.9   nikita you should try to test your code with a version of Lua compiled
   11757   1.9   nikita with all compatibility options turned off.
   11758   1.9   nikita That will ease transitions to newer versions of Lua.
   11759   1.1  mbalmer 
   11760   1.1  mbalmer 
   11761   1.2    lneto <p>
   11762   1.2    lneto Lua versions can always change the C API in ways that
   11763   1.2    lneto do not imply source-code changes in a program,
   11764   1.2    lneto such as the numeric values for constants
   11765   1.2    lneto or the implementation of functions as macros.
   11766   1.2    lneto Therefore,
   11767   1.9   nikita you should never assume that binaries are compatible between
   11768   1.2    lneto different Lua versions.
   11769   1.2    lneto Always recompile clients of the Lua API when
   11770   1.2    lneto using a new version.
   11771   1.1  mbalmer 
   11772   1.1  mbalmer 
   11773   1.2    lneto <p>
   11774   1.2    lneto Similarly, Lua versions can always change the internal representation
   11775   1.2    lneto of precompiled chunks;
   11776   1.3    lneto precompiled chunks are not compatible between different Lua versions.
   11777   1.1  mbalmer 
   11778   1.1  mbalmer 
   11779   1.2    lneto <p>
   11780   1.2    lneto The standard paths in the official distribution may
   11781   1.2    lneto change between versions.
   11782   1.1  mbalmer 
   11783   1.1  mbalmer 
   11784   1.1  mbalmer 
   11785   1.9   nikita 
   11786   1.9   nikita 
   11787   1.9   nikita <h2>8.1 &ndash; <a name="8.1">Incompatibilities in the Language</a></h2>
   11788   1.1  mbalmer <ul>
   11789   1.1  mbalmer 
   11790   1.1  mbalmer <li>
   11791   1.9   nikita The coercion of strings to numbers in
   11792   1.9   nikita arithmetic and bitwise operations
   11793   1.9   nikita has been removed from the core language.
   11794   1.9   nikita The string library does a similar job
   11795   1.9   nikita for arithmetic (but not for bitwise) operations
   11796   1.9   nikita using the string metamethods.
   11797   1.9   nikita However, unlike in previous versions,
   11798   1.9   nikita the new implementation preserves the implicit type of the numeral
   11799   1.9   nikita in the string.
   11800   1.9   nikita For instance, the result of <code>"1" + "2"</code> now is an integer,
   11801   1.9   nikita not a float.
   11802   1.9   nikita </li>
   11803   1.2    lneto 
   11804   1.9   nikita <li>
   11805   1.9   nikita Literal decimal integer constants that overflow are read as floats,
   11806   1.9   nikita instead of wrapping around.
   11807   1.9   nikita You can use hexadecimal notation for such constants if you
   11808   1.9   nikita want the old behavior
   11809   1.9   nikita (reading them as integers with wrap around).
   11810   1.9   nikita </li>
   11811   1.1  mbalmer 
   11812   1.9   nikita <li>
   11813   1.9   nikita The use of the <code>__lt</code> metamethod to emulate <code>__le</code>
   11814   1.9   nikita has been removed.
   11815   1.9   nikita When needed, this metamethod must be explicitly defined.
   11816   1.1  mbalmer </li>
   11817   1.1  mbalmer 
   11818   1.1  mbalmer <li>
   11819   1.9   nikita The semantics of the numerical <b>for</b> loop
   11820   1.9   nikita over integers changed in some details.
   11821   1.9   nikita In particular, the control variable never wraps around.
   11822   1.9   nikita </li>
   11823   1.1  mbalmer 
   11824   1.9   nikita <li>
   11825   1.9   nikita A label for a <b>goto</b> cannot be declared where a label with the same
   11826   1.9   nikita name is visible, even if this other label is declared in an enclosing
   11827   1.9   nikita block.
   11828   1.1  mbalmer </li>
   11829   1.1  mbalmer 
   11830   1.1  mbalmer <li>
   11831   1.9   nikita When finalizing an object,
   11832   1.9   nikita Lua does not ignore <code>__gc</code> metamethods that are not functions.
   11833   1.9   nikita Any value will be called, if present.
   11834   1.9   nikita (Non-callable values will generate a warning,
   11835   1.9   nikita like any other error when calling a finalizer.)
   11836   1.1  mbalmer </li>
   11837   1.1  mbalmer 
   11838   1.1  mbalmer </ul>
   11839   1.1  mbalmer 
   11840   1.1  mbalmer 
   11841   1.1  mbalmer 
   11842   1.1  mbalmer 
   11843   1.9   nikita <h2>8.2 &ndash; <a name="8.2">Incompatibilities in the Libraries</a></h2>
   11844   1.1  mbalmer <ul>
   11845   1.1  mbalmer 
   11846   1.1  mbalmer <li>
   11847   1.9   nikita The function <a href="#pdf-print"><code>print</code></a> does not call <a href="#pdf-tostring"><code>tostring</code></a>
   11848   1.9   nikita to format its arguments;
   11849   1.9   nikita instead, it has this functionality hardwired.
   11850   1.9   nikita You should use <code>__tostring</code> to modify how values are printed.
   11851   1.3    lneto </li>
   11852   1.3    lneto 
   11853   1.3    lneto <li>
   11854   1.9   nikita The pseudo-random number generator used by the function <a href="#pdf-math.random"><code>math.random</code></a>
   11855   1.9   nikita now starts with a somewhat random seed.
   11856   1.9   nikita Moreover, it uses a different algorithm.
   11857   1.3    lneto </li>
   11858   1.3    lneto 
   11859   1.3    lneto <li>
   11860   1.9   nikita By default, the decoding functions in the <a href="#pdf-utf8"><code>utf8</code></a> library
   11861   1.9   nikita do not accept surrogates as valid code points.
   11862   1.9   nikita An extra parameter in these functions makes them more permissive.
   11863   1.1  mbalmer </li>
   11864   1.1  mbalmer 
   11865   1.1  mbalmer <li>
   11866   1.9   nikita The options "<code>setpause</code>" and "<code>setstepmul</code>"
   11867   1.9   nikita of the function <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> are deprecated.
   11868   1.9   nikita You should use the new option "<code>incremental</code>" to set them.
   11869   1.1  mbalmer </li>
   11870   1.1  mbalmer 
   11871   1.1  mbalmer <li>
   11872   1.9   nikita The function <a href="#pdf-io.lines"><code>io.lines</code></a> now returns four values,
   11873   1.9   nikita instead of just one.
   11874   1.9   nikita That can be a problem when it is used as the sole
   11875   1.9   nikita argument to another function that has optional parameters,
   11876   1.9   nikita such as in <code>load(io.lines(filename, "L"))</code>.
   11877   1.9   nikita To fix that issue,
   11878   1.9   nikita you can wrap the call into parentheses,
   11879   1.9   nikita to adjust its number of results to one.
   11880   1.3    lneto </li>
   11881   1.3    lneto 
   11882   1.9   nikita </ul>
   11883   1.9   nikita 
   11884   1.1  mbalmer 
   11885   1.4  mbalmer 
   11886   1.2    lneto 
   11887   1.9   nikita <h2>8.3 &ndash; <a name="8.3">Incompatibilities in the API</a></h2>
   11888   1.2    lneto 
   11889   1.2    lneto 
   11890   1.9   nikita <ul>
   11891   1.2    lneto 
   11892   1.9   nikita <li>
   11893   1.9   nikita Full userdata now has an arbitrary number of associated user values.
   11894   1.9   nikita Therefore, the functions <code>lua_newuserdata</code>,
   11895   1.9   nikita <code>lua_setuservalue</code>, and <code>lua_getuservalue</code> were
   11896   1.9   nikita replaced by <a href="#lua_newuserdatauv"><code>lua_newuserdatauv</code></a>,
   11897   1.9   nikita <a href="#lua_setiuservalue"><code>lua_setiuservalue</code></a>, and <a href="#lua_getiuservalue"><code>lua_getiuservalue</code></a>,
   11898   1.9   nikita which have an extra argument.
   11899   1.2    lneto 
   11900   1.2    lneto 
   11901   1.9   nikita <p>
   11902   1.9   nikita For compatibility, the old names still work as macros assuming
   11903   1.9   nikita one single user value.
   11904   1.9   nikita Note, however, that userdata with zero user values
   11905   1.9   nikita are more efficient memory-wise.
   11906   1.9   nikita </li>
   11907   1.2    lneto 
   11908   1.1  mbalmer <li>
   11909   1.9   nikita The function <a href="#lua_resume"><code>lua_resume</code></a> has an extra parameter.
   11910   1.9   nikita This out parameter returns the number of values on
   11911   1.9   nikita the top of the stack that were yielded or returned by the coroutine.
   11912   1.9   nikita (In previous versions,
   11913   1.9   nikita those values were the entire stack.)
   11914   1.1  mbalmer </li>
   11915   1.1  mbalmer 
   11916   1.1  mbalmer <li>
   11917   1.9   nikita The function <a href="#lua_version"><code>lua_version</code></a> returns the version number,
   11918   1.9   nikita instead of an address of the version number.
   11919   1.9   nikita The Lua core should work correctly with libraries using their
   11920   1.9   nikita own static copies of the same core,
   11921   1.9   nikita so there is no need to check whether they are using the same
   11922   1.9   nikita address space.
   11923   1.1  mbalmer </li>
   11924   1.1  mbalmer 
   11925   1.3    lneto <li>
   11926   1.9   nikita The constant <code>LUA_ERRGCMM</code> was removed.
   11927   1.9   nikita Errors in finalizers are never propagated;
   11928   1.9   nikita instead, they generate a warning.
   11929   1.3    lneto </li>
   11930   1.3    lneto 
   11931   1.3    lneto <li>
   11932   1.9   nikita The options <code>LUA_GCSETPAUSE</code> and <code>LUA_GCSETSTEPMUL</code>
   11933   1.9   nikita of the function <a href="#lua_gc"><code>lua_gc</code></a> are deprecated.
   11934   1.9   nikita You should use the new option <code>LUA_GCINC</code> to set them.
   11935   1.3    lneto </li>
   11936   1.3    lneto 
   11937   1.1  mbalmer </ul>
   11938   1.1  mbalmer 
   11939   1.1  mbalmer 
   11940   1.1  mbalmer 
   11941   1.1  mbalmer 
   11942   1.2    lneto <h1>9 &ndash; <a name="9">The Complete Syntax of Lua</a></h1>
   11943   1.1  mbalmer 
   11944   1.1  mbalmer <p>
   11945   1.1  mbalmer Here is the complete syntax of Lua in extended BNF.
   11946   1.3    lneto As usual in extended BNF,
   11947   1.3    lneto {A} means 0 or more As,
   11948   1.3    lneto and [A] means an optional A.
   11949   1.3    lneto (For operator precedences, see <a href="#3.4.8">&sect;3.4.8</a>;
   11950   1.3    lneto for a description of the terminals
   11951   1.3    lneto Name, Numeral,
   11952   1.3    lneto and LiteralString, see <a href="#3.1">&sect;3.1</a>.)
   11953   1.1  mbalmer 
   11954   1.1  mbalmer 
   11955   1.1  mbalmer 
   11956   1.1  mbalmer 
   11957   1.1  mbalmer <pre>
   11958   1.1  mbalmer 
   11959   1.2    lneto 	chunk ::= block
   11960   1.1  mbalmer 
   11961   1.2    lneto 	block ::= {stat} [retstat]
   11962   1.1  mbalmer 
   11963   1.2    lneto 	stat ::=  &lsquo;<b>;</b>&rsquo; | 
   11964   1.2    lneto 		 varlist &lsquo;<b>=</b>&rsquo; explist | 
   11965   1.1  mbalmer 		 functioncall | 
   11966   1.2    lneto 		 label | 
   11967   1.2    lneto 		 <b>break</b> | 
   11968   1.2    lneto 		 <b>goto</b> Name | 
   11969   1.1  mbalmer 		 <b>do</b> block <b>end</b> | 
   11970   1.1  mbalmer 		 <b>while</b> exp <b>do</b> block <b>end</b> | 
   11971   1.1  mbalmer 		 <b>repeat</b> block <b>until</b> exp | 
   11972   1.1  mbalmer 		 <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> | 
   11973   1.2    lneto 		 <b>for</b> Name &lsquo;<b>=</b>&rsquo; exp &lsquo;<b>,</b>&rsquo; exp [&lsquo;<b>,</b>&rsquo; exp] <b>do</b> block <b>end</b> | 
   11974   1.1  mbalmer 		 <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> | 
   11975   1.1  mbalmer 		 <b>function</b> funcname funcbody | 
   11976   1.1  mbalmer 		 <b>local</b> <b>function</b> Name funcbody | 
   11977   1.9   nikita 		 <b>local</b> attnamelist [&lsquo;<b>=</b>&rsquo; explist] 
   11978   1.9   nikita 
   11979   1.9   nikita 	attnamelist ::=  Name attrib {&lsquo;<b>,</b>&rsquo; Name attrib}
   11980   1.9   nikita 
   11981   1.9   nikita 	attrib ::= [&lsquo;<b>&lt;</b>&rsquo; Name &lsquo;<b>&gt;</b>&rsquo;]
   11982   1.1  mbalmer 
   11983   1.2    lneto 	retstat ::= <b>return</b> [explist] [&lsquo;<b>;</b>&rsquo;]
   11984   1.1  mbalmer 
   11985   1.2    lneto 	label ::= &lsquo;<b>::</b>&rsquo; Name &lsquo;<b>::</b>&rsquo;
   11986   1.1  mbalmer 
   11987   1.2    lneto 	funcname ::= Name {&lsquo;<b>.</b>&rsquo; Name} [&lsquo;<b>:</b>&rsquo; Name]
   11988   1.1  mbalmer 
   11989   1.2    lneto 	varlist ::= var {&lsquo;<b>,</b>&rsquo; var}
   11990   1.1  mbalmer 
   11991   1.2    lneto 	var ::=  Name | prefixexp &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo; | prefixexp &lsquo;<b>.</b>&rsquo; Name 
   11992   1.1  mbalmer 
   11993   1.2    lneto 	namelist ::= Name {&lsquo;<b>,</b>&rsquo; Name}
   11994   1.1  mbalmer 
   11995   1.2    lneto 	explist ::= exp {&lsquo;<b>,</b>&rsquo; exp}
   11996   1.2    lneto 
   11997   1.3    lneto 	exp ::=  <b>nil</b> | <b>false</b> | <b>true</b> | Numeral | LiteralString | &lsquo;<b>...</b>&rsquo; | functiondef | 
   11998   1.1  mbalmer 		 prefixexp | tableconstructor | exp binop exp | unop exp 
   11999   1.1  mbalmer 
   12000   1.2    lneto 	prefixexp ::= var | functioncall | &lsquo;<b>(</b>&rsquo; exp &lsquo;<b>)</b>&rsquo;
   12001   1.1  mbalmer 
   12002   1.2    lneto 	functioncall ::=  prefixexp args | prefixexp &lsquo;<b>:</b>&rsquo; Name args 
   12003   1.1  mbalmer 
   12004   1.3    lneto 	args ::=  &lsquo;<b>(</b>&rsquo; [explist] &lsquo;<b>)</b>&rsquo; | tableconstructor | LiteralString 
   12005   1.1  mbalmer 
   12006   1.2    lneto 	functiondef ::= <b>function</b> funcbody
   12007   1.1  mbalmer 
   12008   1.2    lneto 	funcbody ::= &lsquo;<b>(</b>&rsquo; [parlist] &lsquo;<b>)</b>&rsquo; block <b>end</b>
   12009   1.1  mbalmer 
   12010   1.2    lneto 	parlist ::= namelist [&lsquo;<b>,</b>&rsquo; &lsquo;<b>...</b>&rsquo;] | &lsquo;<b>...</b>&rsquo;
   12011   1.1  mbalmer 
   12012   1.2    lneto 	tableconstructor ::= &lsquo;<b>{</b>&rsquo; [fieldlist] &lsquo;<b>}</b>&rsquo;
   12013   1.1  mbalmer 
   12014   1.1  mbalmer 	fieldlist ::= field {fieldsep field} [fieldsep]
   12015   1.1  mbalmer 
   12016   1.2    lneto 	field ::= &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo; &lsquo;<b>=</b>&rsquo; exp | Name &lsquo;<b>=</b>&rsquo; exp | exp
   12017   1.1  mbalmer 
   12018   1.2    lneto 	fieldsep ::= &lsquo;<b>,</b>&rsquo; | &lsquo;<b>;</b>&rsquo;
   12019   1.1  mbalmer 
   12020   1.2    lneto 	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; | 
   12021   1.2    lneto 		 &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; | 
   12022   1.2    lneto 		 &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; | 
   12023   1.1  mbalmer 		 <b>and</b> | <b>or</b>
   12024   1.1  mbalmer 
   12025   1.2    lneto 	unop ::= &lsquo;<b>-</b>&rsquo; | <b>not</b> | &lsquo;<b>#</b>&rsquo; | &lsquo;<b>~</b>&rsquo;
   12026   1.1  mbalmer 
   12027   1.1  mbalmer </pre>
   12028   1.1  mbalmer 
   12029   1.1  mbalmer <p>
   12030   1.1  mbalmer 
   12031   1.1  mbalmer 
   12032   1.1  mbalmer 
   12033   1.1  mbalmer 
   12034   1.1  mbalmer 
   12035   1.1  mbalmer 
   12036   1.1  mbalmer 
   12037   1.4  mbalmer <P CLASS="footer">
   12038   1.1  mbalmer Last update:
   12039  1.10   nikita Tue May  2 20:09:38 UTC 2023
   12040   1.4  mbalmer </P>
   12041   1.1  mbalmer <!--
   12042  1.10   nikita Last change: revised for Lua 5.4.6
   12043   1.1  mbalmer -->
   12044   1.1  mbalmer 
   12045   1.1  mbalmer </body></html>
   12046   1.1  mbalmer 
   12047