manual.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>

<head>
<title>Lua 5.3 参考手册</title>
<link rel="stylesheet" type="text/css" href="lua.css">
<link rel="stylesheet" type="text/css" href="manual.css">
<META HTTP-EQUIV="content-type" CONTENT="text/html; charset=utf-8">
</head>

<body>

<hr>
<h1>
<a href="http://www.lua.org/"><img src="logo.gif" alt="" border="0"></a>
Lua 5.3 参考手册
</h1>

作者 Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes
<p>
译者 <a href="http://blog.codingnow.com">云风</a>
<p>
<small>
Lua.org, PUC-Rio 版权所有 &copy; 2015 ，
在遵循
<A HREF="http://www.lua.org/license.html">Lua license</A>
条款下，可自由使用。
</small>
<hr>
<p>

<a href="contents.html#contents">目录</A>
&middot;
<a href="contents.html#index">索引</A>
&middot;
<A HREF="glossary.html">中英术语对照表</A>

<!-- ====================================================================== -->
<p>

<!-- $Id: manual.of,v 1.146 2015/01/06 11:23:01 roberto Exp $ -->


<h1>1 &ndash; <a name="1">简介</a></h1>

<p>
Lua 是一门扩展式程序设计语言，被设计成支持通用过程式编程，并有相关数据描述设施。
同时对面向对象编程、函数式编程和数据驱动式编程也提供了良好的支持。
它作为一个强大、轻量的嵌入式脚本语言，可供任何需要的程序使用。
Lua 由 <em>clean C（标准 C 和 C++ 间共通的子集）</em> 实现成一个库。


<p>
作为一门扩展式语言，Lua 没有 "main" 程序的概念：
它只能 <em>嵌入</em> 一个宿主程序中工作，
该宿主程序被称为 <em>被嵌入程序</em> 或者简称 <em>宿主</em> 。 
宿主程序可以调用函数执行一小段 Lua 代码，可以读写 Lua 变量，可以注册 C 函数让 Lua 代码调用。
依靠 C 函数，Lua 可以共享相同的语法框架来定制编程语言，从而适用不同的领域。
Lua 的官方发布版包含一个叫做 <code>lua</code> 的宿主程序示例，
它是一个利用 Lua 库实现的完整独立的 Lua 解释器，可用于交互式应用或批处理。


<p>
Lua 是一个自由软件，其使用许可证决定了它的使用过程无需任何担保。
本手册所描述的实现可以在 Lua 的官方网站 <code>www.lua.org</code> 找到。


<p>
与其它的许多参考手册一样，这份文档有些地方比较枯燥。
关于 Lua 背后的设计思想，
可以看看 Lua 网站上提供的技术论文。
至于用 Lua 编程的细节介绍，
请参阅 Roberto 的书，<em>Programming in Lua</em>。

<h1>2 &ndash; <a name="2">基本概念</a></h1>

<p>
本章描述了语言的基本概念。


<h2>2.1 &ndash; <a name="2.1">值与类型</a></h2>

<p>
Lua 是一门<em>动态类型语言</em>。
这意味着变量没有类型；只有值才有类型。
语言中不设类型定义。
所有的值携带自己的类型。


<p>
Lua 中所有的值都是 <em>一等公民</em>。
这意味着所有的值均可保存在变量中、
当作参数传递给其它函数、以及作为返回值。


<p>
Lua 中有八种基本类型：
<em>nil</em>、<em>boolean</em>、<em>number</em>、<em>string</em>、<em>function</em>、<em>userdata</em>、
<em>thread</em> 和 <em>table</em>。
<em>Nil</em> 是值 <b>nil</b> 的类型，
其主要特征就是和其它值区别开；通常用来表示一个有意义的值不存在时的状态。
<em>Boolean</em> 是 <b>false</b> 与 <b>true</b> 两个值的类型。
<b>nil</b> 和 <b>false</b> 都会导致条件判断为假；
而其它任何值都表示为真。
<em>Number</em> 代表了整数和实数（浮点数）。
<em>String</em> 表示一个不可变的字节序列。

Lua 对 8 位是友好的：
字符串可以容纳任意 8 位值，
其中包含零 ('<code>\0</code>') 。
Lua 的字符串与编码无关；
它不关心字符串中具体内容。


<p>
<em>number</em> 类型有两种内部表现方式，
 <em>整数</em> 和 <em>浮点数</em>。
对于何时使用哪种内部形式，Lua 有明确的规则，
但它也按需（参见 <a href="#3.4.3">&sect;3.4.3</a>）作自动转换。
因此，程序员多数情况下可以选择忽略整数与浮点数之间的差异或者假设完全控制每个数字的内部表现方式。
标准 Lua 使用 64 位整数和双精度（64 位）浮点数，
但你也可以把 Lua 编译成使用 32 位整数和单精度（32 位）浮点数。
以 32 位表示数字对小型机器以及嵌入式系统特别合适。
（参见 <code>luaconf.h</code> 文件中的宏 <code>LUA_32BITS</code> 。）


<p>
Lua 可以调用（以及操作）用 Lua 或 C （参见 <a href="#3.4.10">&sect;3.4.10</a>）编写的函数。
这两种函数有统一类型 <em>function</em>。


<p>
<em>userdata</em> 类型允许将 C 中的数据保存在 Lua 变量中。
用户数据类型的值是一个内存块，
有两种用户数据：
<em>完全用户数据</em> ，指一块由 Lua 管理的内存对应的对象；
<em>轻量用户数据</em> ，则指一个简单的 C 指针。
用户数据在 Lua 中除了赋值与相等性判断之外没有其他预定义的操作。
通过使用 <em>元表</em> ，程序员可以给完全用户数据定义一系列的操作
（参见 <a href="#2.4">&sect;2.4</a>）。
你只能通过 C API 而无法在 Lua 代码中创建或者修改用户数据的值，
这保证了数据仅被宿主程序所控制。


<p>
<em>thread</em> 类型表示了一个独立的执行序列，被用于实现协程
（参见 <a href="#2.6">&sect;2.6</a>）。
Lua 的线程与操作系统的线程毫无关系。
Lua 为所有的系统，包括那些不支持原生线程的系统，提供了协程支持。


<p>
<em>table</em> 是一个关联数组，
也就是说，这个数组不仅仅以数字做索引，除了 <b>nil</b> 和 NaN 之外的所有 Lua 值
都可以做索引。
（<em>Not a Number</em> 是一个特殊的数字，它用于表示未定义或表示不了的运算结果，比如 <code>0/0</code>。）
表可以是 <em>异构</em> 的；
也就是说，表内可以包含任何类型的值（ <b>nil</b> 除外）。
任何键的值若为 <b>nil</b> 就不会被记入表结构内部。
换言之，对于表内不存在的键，都对应着值 <b>nil</b> 。


<p>
表是 Lua 中唯一的数据结构，
它可被用于表示普通数组、序列、符号表、集合、记录、图、树等等。
对于记录，Lua 使用域名作为索引。
语言提供了 <code>a.name</code> 这样的语法糖来替代
<code>a["name"]</code> 这种写法以方便记录这种结构的使用。
在 Lua 中有多种便利的方式创建表（参见 <a href="#3.4.9">&sect;3.4.9</a>）。


<p>
我们使用 <em>序列</em> 这个术语来表示一个用 {1..<em>n</em>} 的正整数集做索引的表。
这里的非负整数 <em>n</em> 被称为该序列的长度（参见 <a href="#3.4.7">&sect;3.4.7</a>）。


<p>
和索引一样，表中每个域的值也可以是任何类型。
需要特别指出的是：既然函数是一等公民，那么表的域也可以是函数。
这样，表就可以携带 <em>方法</em> 了。
（参见 <a href="#3.4.11">&sect;3.4.11</a>）。


<p>
索引一张表的原则遵循语言中的直接比较规则。
当且仅当 <code>i</code> 与 <code>j</code>直接比较相等时
（即不通过元方法的比较），
表达式 <code>a[i]</code> 与 <code>a[j]</code>
表示了表中相同的元素。
特别指出：一个可以完全表示为整数的浮点数和对应的整数相等
（例如：<code>1.0 == 1</code>）。
为了消除歧义，当一个可以完全表示为整数的浮点数做为键值时，
都会被转换为对应的整数储存。
例如，当你写 <code>a[2.0] = true</code> 时，
实际被插入表中的键是整数 <code>2</code> 。
（另一方面，2 与 "<code>2</code>" 是两个不同的 Lua 值，
故而它们可以是同一张表中的不同项。）


<p>
表、函数、线程、以及完全用户数据在 Lua 中被称为 <em>对象</em>：
变量并不真的 <em>持有</em> 它们的值，而仅保存了对这些对象的 <em>引用</em>。
赋值、参数传递、函数返回，都是针对引用而不是针对值的操作，
这些操作均不会做任何形式的隐式拷贝。


<p>
库函数 <a href="#pdf-type"><code>type</code></a> 用于以字符串形式返回给定值的类型。
（参见 <a href="#6.1">&sect;6.1</a>）。


<h2>2.2 &ndash; <a name="2.2">环境与全局环境</a></h2>

<p>
后面在 <a href="#3.2">&sect;3.2</a> 以及 <a href="#3.3.3">&sect;3.3.3</a> 会讨论，
引用一个叫 <code>var</code> 的自由名字（指在任何层级都未被声明的名字）
在句法上都被翻译为 <code>_ENV.var</code> 。
此外，每个被编译的 Lua 代码块都会有一个外部的局部变量叫 <code>_ENV</code>
（参见 <a href="#3.3.2">&sect;3.3.2</a>），
因此，<code>_ENV</code> 这个名字永远都不会成为一个代码块中的自由名字。


<p>
在转译那些自由名字时，<code>_ENV</code> 是否是那个外部的局部变量无所谓。
<code>_ENV</code> 和其它你可以使用的变量名没有区别。
这里特别指出，你可以定义一个新变量或指定一个参数叫这个名字。
当编译器在转译自由名字时所用到的 <code>_ENV</code> ，
指的是你的程序在那个点上可见的那个名为 _ENV 的变量。
（Lua 的可见性规则参见 <a href="#3.5">&sect;3.5</a>）

<p>

被 <code>_ENV</code> 用于值的那张表被称为 <em>环境</em>。


<p>
Lua 保有一个被称为 <em>全局环境</em> 特别环境。它被保存在 C 注册表
（参见 <a href="#4.5">&sect;4.5</a>）的一个特别索引下。
在 Lua 中，全局变量 <a href="#pdf-_G"><code>_G</code></a> 被初始化为这个值。
（<a href="#pdf-_G"><code>_G</code></a> 不被内部任何地方使用。）


<p>
当 Lua 加载一个代码块，<code>_ENV</code> 这个上值的默认值就是这个全局环境
（参见 <a href="#pdf-load"><code>load</code></a>）。
因此，在默认情况下，Lua 代码中提及的自由名字都指的全局环境中的相关项
（因此，它们也被称为 <em>全局变量</em> ）。
此外，所有的标准库都被加载入全局环境，一些函数也针对这个环境做操作。
你可以用 <a href="#pdf-load"><code>load</code></a> （或 <a href="#pdf-loadfile"><code>loadfile</code></a>）加载代码块，并赋予它们不同的环境。
（在 C 里，当你加载一个代码块后，可以通过改变它的第一个上值来改变它的环境。）


<h2>2.3 &ndash; <a name="2.3">错误处理</a></h2>

<p>
由于 Lua 是一门嵌入式扩展语言，其所有行为均源于宿主程序中 C 代码对某个 Lua 库函数的调用。
（单独使用 Lua 时，<code>lua</code> 程序就是宿主程序。）
所以，在编译或运行 Lua 代码块的过程中，无论何时发生错误，
控制权都返回给宿主，由宿主负责采取恰当的措施（比如打印错误消息）。


<p>
可以在 Lua 代码中调用 <a href="#pdf-error"><code>error</code></a> 函数来显式地抛出一个错误。
如果你需要在 Lua 中捕获这些错误，
可以使用 <a href="#pdf-pcall"><code>pcall</code></a> 或
<a href="#pdf-xpcall"><code>xpcall</code></a>
在 <em>保护模式</em> 下调用一个函数。


<p>
无论何时出现错误，都会抛出一个携带错误信息的 <em>错误对象</em> 
（<em>错误消息</em>）。
Lua 本身只会为错误生成字符串类型的错误对象，
但你的程序可以为错误生成任何类型的错误对象，
这就看你的 Lua 程序或宿主程序如何处理这些错误对象。

<p>
使用 <a href="#pdf-xpcall"><code>xpcall</code></a> 或
<a href="#lua_pcall"><code>lua_pcall</code></a> 时，
你应该提供一个 <em>消息处理函数</em> 用于错误抛出时调用。
该函数需接收原始的错误消息，并返回一个新的错误消息。
它在错误发生后栈尚未展开时调用，
因此可以利用栈来收集更多的信息，
比如通过探知栈来创建一组栈回溯信息。
同时，该处理函数也处于保护模式下，所以该函数内发生的错误会再次触发它（递归）。
如果递归太深，Lua 会终止调用并返回一个合适的消息。


<h2>2.4 &ndash; <a name="2.4">元表及元方法</a></h2>

<p>
Lua 中的每个值都可以有一个 <em>元表</em>。
这个 <em>元表</em> 就是一个普通的 Lua 表，
它用于定义原始值在特定操作下的行为。
如果你想改变一个值在特定操作下的行为，你可以在它的元表中设置对应域。
例如，当你对非数字值做加操作时，
Lua 会检查该值的元表中的 "<code>__add</code>" 域下的函数。
如果能找到，Lua 则调用这个函数来完成加这个操作。


<p>
在元表中事件的键值是一个双下划线（<code>__</code>）加事件名的字符串；
键关联的那些值被称为 <em>元方法</em>。
在上一个例子中，<code>__add</code>  就是键值，
对应的元方法是执行加操作的函数。


<p>
你可以用 <a href="#pdf-getmetatable"><code>getmetatable</code></a> 函数
来获取任何值的元表。
Lua 使用直接访问的方式从元表中查询元方法（参见<a href="#pdf-rawget"><code>rawget</code></a>）。
所以，从对象 <code>o</code> 中获取事件 <code>ev</code> 的元方法等价于下面的代码：

<pre>
     rawget(getmetatable(<em>o</em>) or {}, "__<em>ev</em>")
</pre>


<p>
你可以使用 <a href="#pdf-setmetatable"><code>setmetatable</code></a> 
来替换一张表的元表。在 Lua 中，你不可以改变表以外其它类型的值的元表
（除非你使用调试库（参见<a href="#6.10">&sect;6.10</a>））；
若想改变这些非表类型的值的元表，请使用 C API。


<p>
表和完全用户数据有独立的元表
（当然，多个表和用户数据可以共享同一个元表）。
其它类型的值按类型共享元表；
也就是说所有的数字都共享同一个元表，
所有的字符串共享另一个元表等等。
默认情况下，值是没有元表的，
但字符串库在初始化的时候为字符串类型设置了元表
（参见 <a href="#6.4">&sect;6.4</a>）。


<p>
元表决定了一个对象在数学运算、位运算、比较、连接、
取长度、调用、索引时的行为。
元表还可以定义一个函数，当表对象或用户数据对象在垃圾回收
（参见<a href="#2.5">&sect;2.5</a>）时调用它。


<p>
对于一元操作符（取负、求长度、位反），
元方法调用的时候，第二个参数是个哑元，其值等于第一个参数。
这样处理仅仅是为了简化 Lua 的内部实现
（这样处理可以让所有的操作都和二元操作一致），
这个行为有可能在将来的版本中移除。
（使用这个额外参数的行为都是不确定的。）

<p>
接下来是元表可以控制的事件的详细列表。
每个操作都用对应的事件名来区分。
每个事件的键名用加有 '<code>__</code>' 前缀的字符串来表示；
例如 "add" 操作的键名为字符串 "<code>__add</code>"。


<ul>

<li><b><code>__add</code>: </b>
<code>+</code> 操作。

如果任何不是数字的值（包括不能转换为数字的字符串）做加法，
Lua 就会尝试调用元方法。
首先、Lua 检查第一个操作数（即使它是合法的），
如果这个操作数没有为 "<code>__add</code>" 事件定义元方法，
Lua 就会接着检查第二个操作数。
一旦 Lua 找到了元方法，
它将把两个操作数作为参数传入元方法，
元方法的结果（调整为单个值）作为这个操作的结果。
如果找不到元方法，将抛出一个错误。
</li>

<li><b><code>__sub</code>: </b>
<code>-</code> 操作。

行为和 "add" 操作类似。
</li>

<li><b><code>__mul</code>: </b>
<code>*</code> 操作。

行为和 "add" 操作类似。
</li>

<li><b><code>__div</code>: </b>
<code>/</code> 操作。

行为和 "add" 操作类似。
</li>

<li><b><code>__mod</code>: </b>
<code>%</code> 操作。

行为和 "add" 操作类似。
</li>

<li><b><code>__pow</code>: </b>
<code>^</code> （次方）操作。

行为和 "add" 操作类似。
</li>

<li><b><code>__unm</code>: </b>
<code>-</code> （取负）操作。

行为和 "add" 操作类似。
</li>

<li><b><code>__idiv</code>: </b>
<code>//</code> （向下取整除法）操作。

行为和 "add" 操作类似。
</li>

<li><b><code>__band</code>: </b>
<code>&amp;</code> （按位与）操作。

行为和 "add" 操作类似，
不同的是 Lua 会在任何一个操作数无法转换为整数时
（参见 <a href="#3.4.3">&sect;3.4.3</a>）尝试取元方法。
</li>

<li><b><code>__bor</code>: </b>
<code>|</code> （按位或）操作。

行为和 "band" 操作类似。
</li>

<li><b><code>__bxor</code>: </b>
<code>~</code> （按位异或）操作。

行为和 "band" 操作类似。
</li>

<li><b><code>__bnot</code>: </b>
<code>~</code> （按位非）操作。

行为和 "band" 操作类似。
</li>

<li><b><code>__shl</code>: </b>
<code>&lt;&lt;</code> （左移）操作。

行为和 "band" 操作类似。
</li>

<li><b><code>__shr</code>: </b>
<code>&gt;&gt;</code> （右移）操作。

行为和 "band" 操作类似。
</li>

<li><b><code>__concat</code>: </b>
<code>..</code> （连接）操作。

行为和 "add" 操作类似，
不同的是 Lua 在任何操作数即不是一个字符串
也不是数字（数字总能转换为对应的字符串）的情况下尝试元方法。
</li>

<li><b><code>__len</code>: </b>
<code>#</code> （取长度）操作。

如果对象不是字符串，Lua 会尝试它的元方法。
如果有元方法，则调用它并将对象以参数形式传入，
而返回值（被调整为单个）则作为结果。
如果对象是一张表且没有元方法，
Lua 使用表的取长度操作（参见 <a href="#3.4.7">&sect;3.4.7</a>）。
其它情况，均抛出错误。
</li>

<li><b><code>__eq</code>: </b>
<code>==</code> （等于）操作。

和 "add" 操作行为类似，
不同的是 Lua 仅在两个值都是表或都是完全用户数据
且它们不是同一个对象时才尝试元方法。
调用的结果总会被转换为布尔量。
</li>

<li><b><code>__lt</code>: </b>
<code>&lt;</code> （小于）操作。

和 "add" 操作行为类似，
不同的是 Lua 仅在两个值不全为整数也不全为字符串时才尝试元方法。
调用的结果总会被转换为布尔量。
</li>

<li><b><code>__le</code>: </b>
<code>&lt;=</code> （小于等于）操作。

和其它操作不同，
小于等于操作可能用到两个不同的事件。
首先，像 "lt" 操作的行为那样，Lua 在两个操作数中查找 "<code>__le</code>" 元方法。
如果一个元方法都找不到，就会再次查找 "<code>__lt</code>" 事件，
它会假设 <code>a &lt;= b</code> 等价于 <code>not (b &lt; a)</code>。
而其它比较操作符类似，其结果会被转换为布尔量。
</li>

<li><b><code>__index</code>: </b>
索引 <code>table[key]</code>。

当 <code>table</code> 不是表或是表 <code>table</code> 中不存在
<code>key</code> 这个键时，这个事件被触发。
此时，会读出 <code>table</code> 相应的元方法。

<p>
尽管名字取成这样，
这个事件的元方法其实可以是一个函数也可以是一张表。
如果它是一个函数，则以 <code>table</code> 和 <code>key</code> 作为参数调用它。
如果它是一张表，最终的结果就是以 <code>key</code> 取索引这张表的结果。
（这个索引过程是走常规的流程，而不是直接索引，
所以这次索引有可能引发另一次元方法。）
</li>

<li><b><code>__newindex</code>: </b>
索引赋值 <code>table[key] = value</code> 。

和索引事件类似，它发生在
<code>table</code> 不是表或是表 <code>table</code> 中不存在
<code>key</code> 这个键的时候。
此时，会读出 <code>table</code> 相应的元方法。

<p>
同索引过程那样，
这个事件的元方法即可以是函数，也可以是一张表。
如果是一个函数，
则以 <code>table</code>、 <code>key</code>、以及 <code>value</code> 为参数传入。
如果是一张表，
Lua 对这张表做索引赋值操作。
（这个索引过程是走常规的流程，而不是直接索引赋值，
所以这次索引赋值有可能引发另一次元方法。）


<p>
一旦有了 "newindex" 元方法，
Lua 就不再做最初的赋值操作。
（如果有必要，在元方法内部可以调用 <a href="#pdf-rawset"><code>rawset</code></a>
来做赋值。）
</li>

<li><b><code>__call</code>: </b>
函数调用操作 <code>func(args)</code>。

当 Lua 尝试调用一个非函数的值的时候会触发这个事件
（即 <code>func</code> 不是一个函数）。
查找 <code>func</code> 的元方法，
如果找得到，就调用这个元方法，
<code>func</code> 作为第一个参数传入，原来调用的参数（<code>args</code>）后依次排在后面。
</li>

</ul>


<h2>2.5 &ndash; <a name="2.5">垃圾收集</a></h2>

<p>
Lua 采用了自动内存管理。
这意味着你不用操心新创建的对象需要的内存如何分配出来，
也不用考虑在对象不再被使用后怎样释放它们所占用的内存。
Lua 运行了一个 <em>垃圾收集器</em> 来收集所有 <em>死对象</em>
（即在 Lua 中不可能再访问到的对象）来完成自动内存管理的工作。
Lua 中所有用到的内存，如：字符串、表、用户数据、函数、线程、
内部结构等，都服从自动管理。


<p>
Lua 实现了一个增量标记-扫描收集器。
它使用这两个数字来控制垃圾收集循环：
<em>垃圾收集器间歇率</em> 和 <em>垃圾收集器步进倍率</em>。
这两个数字都使用百分数为单位
（例如：值 100 在内部表示 1 ）。


<p>
垃圾收集器间歇率控制着收集器需要在开启新的循环前要等待多久。
增大这个值会减少收集器的积极性。
当这个值比 100 小的时候，收集器在开启新的循环前不会有等待。
设置这个值为 200 就会让收集器等到总内存使用量达到
之前的两倍时才开始新的循环。


<p>
垃圾收集器步进倍率控制着收集器运作速度相对于内存分配速度的倍率。
增大这个值不仅会让收集器更加积极，还会增加每个增量步骤的长度。
不要把这个值设得小于 100 ，
那样的话收集器就工作的太慢了以至于永远都干不完一个循环。
默认值是 200 ，这表示收集器以内存分配的“两倍”速工作。


<p>
如果你把步进倍率设为一个非常大的数字
（比你的程序可能用到的字节数还大 10% ），
收集器的行为就像一个 stop-the-world 收集器。
接着你若把间歇率设为 200 ，
收集器的行为就和过去的 Lua 版本一样了：
每次 Lua 使用的内存翻倍时，就做一次完整的收集。


<p>
你可以通过在 C 中调用 <a href="#lua_gc"><code>lua_gc</code></a>
或在 Lua 中调用 <a href="#pdf-collectgarbage"><code>collectgarbage</code></a>
来改变这俩数字。
这两个函数也可以用来直接控制收集器（例如停止它或重启它）。


<h3>2.5.1 &ndash; <a name="2.5.1">垃圾收集元方法</a></h3>

<p>
你可以为表设定垃圾收集的元方法，
对于完全用户数据（参见 <a href="#2.4">&sect;2.4</a>），
则需要使用 C API 。
该元方法被称为 <em>终结器</em>。
终结器允许你配合 Lua 的垃圾收集器做一些额外的资源管理工作
（例如关闭文件、网络或数据库连接，或是释放一些你自己的内存）。


<p>
如果要让一个对象（表或用户数据）在收集过程中进入终结流程，
你必须 <em>标记</em> 它需要触发终结器。

当你为一个对象设置元表时，若此刻这张元表中用一个以字符串
"<code>__gc</code>" 为索引的域，那么就标记了这个对象需要触发终结器。
注意：如果你给对象设置了一个没有 <code>__gc</code>
域的元表，之后才给元表加上这个域，
那么这个对象是没有被标记成需要触发终结器的。
然而，一旦对象被标记，
你还是可以自由的改变其元表中的 <code>__gc</code> 域的。


<p>
当一个被标记的对象成为了垃圾后，
垃圾收集器并不会立刻回收它。
取而代之的是，Lua 会将其置入一个链表。
在收集完成后，Lua 将遍历这个链表。
Lua 会检查每个链表中的对象的 <code>__gc</code>
元方法：如果是一个函数，那么就以对象为唯一参数调用它；
否则直接忽略它。


<p>
在每次垃圾收集循环的最后阶段，
本次循环中检测到的需要被回收之对象，
其终结器的触发次序按当初给对象作需要触发终结器的标记之次序的逆序进行；
这就是说，第一个被调用的终结器是程序中最后一个被标记的对象所携的那个。
每个终结器的运行可能发生在执行常规代码过程中的任意一刻。


<p>
由于被回收的对象还需要被终结器使用，
该对象（以及仅能通过它访问到的其它对象）一定会被 Lua <em>复活</em>。
通常，复活是短暂的，对象所属内存会在下一个垃圾收集循环释放。
然后，若终结器又将对象保存去一些全局的地方
（例如：放在一个全局变量里），这次复活就持续生效了。
此外，如果在终结器中对一个正进入终结流程的对象再次做一次标记让它触发终结器，
只要这个对象在下个循环中依旧不可达，它的终结函数还会再调用一次。
无论是哪种情况，
对象所属内存仅在垃圾收集循环中该对象不可达且
没有被标记成需要触发终结器才会被释放。


<p>
当你关闭一个状态机（参见 <a href="#lua_close"><code>lua_close</code></a>），
Lua 将调用所有被标记了需要触发终结器对象的终结过程，
其次序为标记次序的逆序。
在这个过程中，任何终结器再次标记对象的行为都不会生效。


<h3>2.5.2 &ndash; <a name="2.5.2">弱表</a></h3>

<p>
<em>弱表</em> 指内部元素为 <em>弱引用</em> 的表。
垃圾收集器会忽略掉弱引用。
换句话说，如果一个对象只被弱引用引用到，
垃圾收集器就会回收这个对象。


<p>
一张弱表可以有弱键或是弱值，也可以键值都是弱引用。
含有弱值的表允许收集器回收它的值，但会阻止收集器回收它的键。
若一张表的键值均为弱引用，
那么收集器可以回收其中的任意键和值。
任何情况下，只要键或值的任意一项被回收，
相关联的键值对都会从表中移除。
一张表的元表中的 <code>__mode</code> 域控制着这张表的弱属性。
当 <code>__mode</code> 域是一个包含字符 '<code>k</code>'
的字符串时，这张表的所有键皆为弱引用。
当 <code>__mode</code> 域是一个包含字符 '<code>v</code>'
的字符串时，这张表的所有值皆为弱引用。


<p>
属性为弱键强值的表也被称为 <em>暂时表</em>。
对于一张暂时表，
它的值是否可达仅取决于其对应键是否可达。
特别注意，如果表内的一个键仅仅被其值所关联引用，
这个键值对将被表内移除。


<p>
对一张表的弱属性的修改仅在下次收集循环才生效。
尤其是当你把表由弱改强，Lua 还是有可能在修改生效前回收表内一些项目。


<p>
只有那些有显式构造过程的对象才会从弱表中移除。
值，例如数字和轻量 C 函数，不受垃圾收集器管辖，
因此不会从弱表中移除
（除非它们的关联项被回收）。
虽然字符串受垃圾回收器管辖，
但它们没有显式的构造过程，所以也不会从弱表中移除。


<p>
弱表针对复活的对象
（指那些正在走终结流程，仅能被终结器访问的对象）
有着特殊的行为。
弱值引用的对象，在运行它们的终结器前就被移除了，
而弱键引用的对象则要等到终结器运行完毕后，到下次收集当对象真的被释放时才被移除。
这个行为使得终结器运行时得以访问到由该对象在弱表中所关联的属性。


<p>
如果一张弱表在当次收集循环内的复活对象中，
那么在下个循环前这张表有可能未被正确地清理。


<h2>2.6 &ndash; <a name="2.6">协程</a></h2>

<p>
Lua 支持协程，也叫 <em>协同式多线程</em>。
一个协程在 Lua 中代表了一段独立的执行线程。
然而，与多线程系统中的线程的区别在于，
协程仅在显式调用一个让出（yield）函数时才挂起当前的执行。


<p>
调用函数
<a href="#pdf-coroutine.create"><code>coroutine.create</code></a>
可创建一个协程。
其唯一的参数是该协程的主函数。
<code>create</code> 函数只负责新建一个协程并返回其句柄
（一个 <em>thread</em> 类型的对象）；
而不会启动该协程。


<p>
调用
<a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>
函数执行一个协程。
第一次调用
<a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>
时，第一个参数应传入
<a href="#pdf-coroutine.create"><code>coroutine.create</code></a>
返回的线程对象，然后协程从其主函数的第一行开始执行。
传递给
<a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>
的其他参数将作为协程主函数的参数传入。
协程启动之后，将一直运行到它终止或 <em>让出</em>。


<p>
协程的运行可能被两种方式终止：
正常途径是主函数返回
（显式返回或运行完最后一条指令）；
非正常途径是发生了一个未被捕获的错误。
对于正常结束，
<a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> 将返回 <b>true</b>，
并接上协程主函数的返回值。
当错误发生时，
<a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> 将返回 <b>false</b>
与错误消息。


<p>
通过调用
<a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a> 使协程暂停执行，让出执行权。
协程让出时，对应的最近 <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> 
函数会立刻返回，即使该让出操作发生在内嵌函数调用中
（即不在主函数，但在主函数直接或间接调用的函数内部）。
在协程让出的情况下，
<a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> 也会返回 <b>true</b>，
并加上传给
<a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a> 的参数。
当下次重启同一个协程时，
协程会接着从让出点继续执行。
此时，此前让出点处对 <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a> 的调用
会返回，返回值为传给
<a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>
的第一个参数之外的其他参数。


<p>
与
<a href="#pdf-coroutine.create"><code>coroutine.create</code></a> 类似，
<a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> 函数也会创建一个协程。
不同之处在于，它不返回协程本身，而是返回一个函数。
调用这个函数将启动该协程。
传递给该函数的任何参数均当作 <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> 的额外参数。
<a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a>
返回
<a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>
的所有返回值，除了第一个返回值（布尔型的错误码）。
和 <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> 不同，
<a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a>
不会捕获错误；
而是将任何错误都传播给调用者。


<p>
下面的代码展示了一个协程工作的范例：

<pre>
     function foo (a)
       print("foo", a)
       return coroutine.yield(2*a)
     end
     
     co = coroutine.create(function (a,b)
           print("co-body", a, b)
           local r = foo(a+1)
           print("co-body", r)
           local r, s = coroutine.yield(a+b, a-b)
           print("co-body", r, s)
           return b, "end"
     end)
     
     print("main", coroutine.resume(co, 1, 10))
     print("main", coroutine.resume(co, "r"))
     print("main", coroutine.resume(co, "x", "y"))
     print("main", coroutine.resume(co, "x", "y"))
</pre><p>
当你运行它，将产生下列输出：

<pre>
     co-body 1       10
     foo     2
     main    true    4
     co-body r
     main    true    11      -9
     co-body x       y
     main    true    10      end
     main    false   cannot resume dead coroutine
</pre>

<p>
你也可以通过 C API 来创建及操作协程：
参见函数
<a href="#lua_newthread"><code>lua_newthread</code></a>，
<a href="#lua_resume"><code>lua_resume</code></a>，
以及 <a href="#lua_yield"><code>lua_yield</code></a>。


<h1>3 &ndash; <a name="3">语言定义</a></h1>

<p>
这一章描述了 Lua 的词法、语法和句法。
换句话说，本章描述哪些符记是有效的，
它们如何被组合起来，这些组合方式有什么含义。


<p>
关于语言的构成概念将用常见的扩展 BNF 表达式写出。
也就是这个样子：
{<em>a</em>} 表示 0 或多个 <em>a</em>，
[<em>a</em>] 表示一个可选的 <em>a</em>。

可以被分解的非最终符号会这样写 non-terminal ，
关键字会写成这样 <b>kword</b>，
而其它不能被分解的最终符号则写成这样 &lsquo;<b>=</b>&rsquo; 。
完整的 Lua 语法可以在本手册最后一章 <a href="#9">&sect;9</a> 找到。


<h2>3.1 &ndash; <a name="3.1">词法约定</a></h2>

<p>
Lua 语言的格式自由。
它会忽略语法元素（符记）间的空格（包括换行）和注释，
仅把它们看作为名字和关键字间的分割符。


<p>
Lua 中的 <em>名字</em>
（也被称为 <em>标识符</em>）
可以是由非数字打头的任意字母下划线和数字构成的字符串。
标识符可用于对变量、表的域、以及标签命名。


<p>
下列 <em>关键字</em> 是保留的，不可用于名字：


<pre>
     and       break     do        else      elseif    end
     false     for       function  goto      if        in
     local     nil       not       or        repeat    return
     then      true      until     while
</pre>

<p>
Lua 语言对大小写敏感：
<code>and</code> 是一个保留字，但 <code>And</code> 与 <code>AND</code>
则是两个不同的有效名字。
作为一个约定，程序应避免创建以下划线加一个或多个大写字母构成的名字
（例如 <a href="#pdf-_VERSION"><code>_VERSION</code></a>）。


<p>
下列字符串是另外一些符记：

<pre>
     +     -     *     /     %     ^     #
     &amp;     ~     |     &lt;&lt;    &gt;&gt;    //
     ==    ~=    &lt;=    &gt;=    &lt;     &gt;     =
     (     )     {     }     [     ]     ::
     ;     :     ,     .     ..    ...
</pre>

<p>
<em>字面串</em> 可以用单引号或双引号括起。
字面串内部可以包含下列 C 风格的转义串： 
'<code>\a</code>' （响铃），
'<code>\b</code>' （退格），
'<code>\f</code>' （换页），
'<code>\n</code>' （换行），
'<code>\r</code>' （回车），
'<code>\t</code>' （横项制表），
'<code>\v</code>' （纵向制表），
'<code>\\</code>' （反斜杠），
'<code>\"</code>' （双引号），
以及 '<code>\'</code>' (单引号)。
在反斜杠后跟一个真正的换行等价于在字符串中写一个换行符。
转义串 '<code>\z</code>' 会忽略其后的一系列空白符，包括换行；
它在你需要对一个很长的字符串常量断行为多行并希望在每个新行保持缩进时非常有用。


<p>
Lua 中的字符串可以保存任意 8 位值，其中包括用 '<code>\0</code>' 表示的 0 。
一般而言，你可以用字符的数字值来表示这个字符。
方式是用转义串 <code>\x<em>XX</em></code>，
此处的 <em>XX</em> 必须是恰好两个字符的 16 进制数。
或者你也可以使用转义串 <code>\<em>ddd</em></code> ，
这里的 <em>ddd</em> 是一到三个十进制数字。
（注意，如果在转义符后接着恰巧是一个数字符号的话，
你就必须在这个转义形式中写满三个数字。）


<p>
对于用 UTF-8 编码的 Unicode 字符，你可以用
转义符 <code>\u{<em>XXX</em>}</code> 来表示
（这里必须有一对花括号），
此处的 <em>XXX</em> 是用 16 进制表示的字符编号。


<p>
字面串还可以用一种 <em>长括号</em> 括起来的方式定义。
我们把两个正的方括号间插入 <em>n</em> 个等号定义为 <em>第 <em>n</em> 级开长括号</em>。
就是说，0 级开的长括号写作 <code>[[</code> ， 一级开长括号写作 <code>[=[</code> ，
如此等等。
<em>闭长括号</em>也作类似定义； 
举个例子，4 级反的长括号写作 <code>]====]</code> 。
一个 <em>长字面串</em> 可以由任何一级的开长括号开始，而由第一个碰到的同级的闭长括号结束。
这种方式描述的字符串可以包含任何东西，当然特定级别的反长括号除外。
整个词法分析过程将不受分行限制，不处理任何转义符，并且忽略掉任何不同级别的长括号。 
其中碰到的任何形式的换行串（回车、换行、回车加换行、换行加回车），都会被转换为单个换行符。


<p>
字面串中的每个不被上述规则影响的字节都呈现为本身。
然而，Lua 是用文本模式打开源文件解析的，
一些系统的文件操作函数对某些控制字符的处理可能有问题。
因此，对于非文本数据，用引号括起来并显式按转义符规则来表述更安全。


<p>
为了方便起见，
当一个开长括号后紧接一个换行符时，
这个换行符不会放在字符串内。
举个例子，假设一个系统使用 ASCII 码
（此时 '<code>a</code>' 编码为 97 ，
换行编码为 10 ，'<code>1</code>' 编码为 49 ），
下面五种方式描述了完全相同的字符串：

<pre>
     a = 'alo\n123"'
     a = "alo\n123\""
     a = '\97lo\10\04923"'
     a = [[alo
     123"]]
     a = [==[
     alo
     123"]==]
</pre>

<p>
<em>数字常量</em> （或称为 <em>数字量</em>）
可以由可选的小数部分和可选的十为底的指数部分构成，
指数部分用字符 '<code>e</code>' 或 '<code>E</code>' 来标记。
Lua 也接受以 <code>0x</code> 或 <code>0X</code> 开头的 16 进制常量。
16 进制常量也接受小数加指数部分的形式，指数部分是以二为底，
用字符 '<code>p</code>' 或 '<code>P</code>' 来标记。
数字常量中包含小数点或指数部分时，被认为是一个浮点数；
否则被认为是一个整数。
下面有一些合法的整数常量的例子：
<pre>
     3   345   0xff   0xBEBADA
</pre><p>
以下为合法的浮点常量：
<pre>
     3.0     3.1416     314.16e-2     0.31416E1     34e1
     0x0.1E  0xA23p-4   0X1.921FB54442D18P+1
</pre>

<p>
在字符串外的任何地方出现以双横线 (<code>--</code>) 开头的部分是 <em>注释</em> 。
如果 <code>--</code> 后没有紧跟着一个开大括号，
该注释为 <em>短注释</em>，
注释到当前行末截至。
否则，这是一段 <em>长注释</em> ，
注释区一直维持到对应的闭长括号。
长注释通常用于临时屏蔽掉一大段代码。


<h2>3.2 &ndash; <a name="3.2">变量</a></h2>

<p>
变量是储存值的地方。
Lua 中有三种变量：
全局变量、局部变量和表的域。


<p>
单个名字可以指代一个全局变量也可以指代一个局部变量
（或者是一个函数的形参，这是一种特殊形式的局部变量）。

<pre>
	var ::= Name
</pre><p>
名字指 <a href="#3.1">&sect;3.1</a> 中定义的标识符。


<p>
所有没有显式声明为局部变量（参见 <a href="#3.3.7">&sect;3.3.7</a>）
的变量名都被当做全局变量。
局部变量有其 <em>作用范围</em> ：
局部变量可以被定义在它作用范围中的函数自由使用（参见
<a href="#3.5">&sect;3.5</a>）。


<p>
在变量的首次赋值之前，变量的值均为 <b>nil</b>。


<p>
方括号被用来对表作索引：

<pre>
	var ::= prefixexp &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo;
</pre><p>
对全局变量以及表的域之访问的含义可以通过元表来改变。 
以索引方式访问一个变量 <code>t[i]</code> 等价于
调用 <code>gettable_event(t,i)</code>。
（参见 <a href="#2.4">&sect;2.4</a> ，有一份完整的关于
<code>gettable_event</code> 函数的说明。
这个函数并没有在 lua 中定义出来，也不能在 lua 中调用。这里我们把提到它只是方便说明问题。）


<p>
<code>var.Name</code> 这种语法只是一个语法糖，用来表示
<code>var["Name"]</code>：

<pre>
	var ::= prefixexp &lsquo;<b>.</b>&rsquo; Name
</pre>

<p>
对全局变量 <code>x</code> 的操作等价于操作
<code>_ENV.x</code>。
由于代码块编译的方式，
<code>_ENV</code> 永远也不可能是一个全局名字 （参见 <a href="#2.2">&sect;2.2</a>）。


<h2>3.3 &ndash; <a name="3.3">语句</a></h2>

<p>
Lua 支持所有与 Pascal 或是 C 类似的常见形式的语句，
这个集合包括赋值，控制结构，函数调用，还有变量声明。


<h3>3.3.1 &ndash; <a name="3.3.1">语句块</a></h3>

<p>
语句块是一个语句序列，它们会按次序执行：

<pre>
	block ::= {stat}
</pre><p>
Lua 支持 <em>空语句</em>，
你可以用分号分割语句，也可以以分号开始一个语句块，
或是连着写两个分号：

<pre>
	stat ::= &lsquo;<b>;</b>&rsquo;
</pre>

<p>
函数调用和赋值语句都可能以一个小括号打头，
这可能让 Lua 的语法产生歧义。
我们来看看下面的代码片断：

<pre>
     a = b + c
     (print or io.write)('done')
</pre><p>
从语法上说，可能有两种解释方式：

<pre>
     a = b + c(print or io.write)('done')
     
     a = b + c; (print or io.write)('done')
</pre><p>
当前的解析器总是用第一种结构来解析，
它会将开括号看成函数调用的参数传递开始处。
为了避免这种二义性，
在一条语句以小括号开头时，前面放一个分号是个好习惯：

<pre>
     ;(print or io.write)('done')
</pre>

<p>

一个语句块可以被显式的定界为单条语句：

<pre>
	stat ::= <b>do</b> block <b>end</b>
</pre><p>
显式的对一个块定界通常用来控制内部变量声明的作用域。
有时，显式定界也用于在一个语句块中间插入
<b>return</b> （参见 <a href="#3.3.4">&sect;3.3.4</a>）。


<h3>3.3.2 &ndash; <a name="3.3.2">代码块</a></h3>

<p>
Lua 的一个编译单元被称为一个 <em>代码块</em>。
从句法构成上讲，一个代码块就是一个语句块。

<pre>
	chunk ::= block
</pre>

<p>
Lua 把一个代码块当作一个拥有不定参数的匿名函数
（参见<a href="#3.4.11">&sect;3.4.11</a>）来处理。
正是这样，代码块内可以定义局部变量，它可以接收参数，返回若干值。
此外，这个匿名函数在编译时还为它的作用域绑定了一个外部局部变量
<code>_ENV</code> （参见 <a href="#2.2">&sect;2.2</a>）。
该函数总是把 <code>_ENV</code> 作为它唯一的一个上值，
即使这个函数不使用这个变量，它也存在。


<p>
代码块可以被保存在文件中，也可以作为宿主程序内部的一个字符串。
要执行一个代码块，
首先要让 Lua <em>加载</em> 它，
将代码块中的代码预编译成虚拟机中的指令，
而后，Lua 用虚拟机解释器来运行编译后的代码。


<p>
代码块可以被预编译为二进制形式；
参见程序  <code>luac</code> 以及函数 <a href="#pdf-string.dump"><code>string.dump</code></a> 可获得更多细节。
用源码表示的程序和编译后的形式可自由替换；
Lua 会自动检测文件格式做相应的处理
（参见 <a href="#pdf-load"><code>load</code></a>）。


<h3>3.3.3 &ndash; <a name="3.3.3">赋值</a></h3>

<p>
Lua 允许多重赋值。
因此，赋值的语法定义是等号左边放一个变量列表， 而等号右边放一个表达式列表。
两边的列表中的元素都用逗号间开：

<pre>
	stat ::= varlist &lsquo;<b>=</b>&rsquo; explist
	varlist ::= var {&lsquo;<b>,</b>&rsquo; var}
	explist ::= exp {&lsquo;<b>,</b>&rsquo; exp}
</pre><p>
表达式放在 <a href="#3.4">&sect;3.4</a> 中讨论。


<p>
在作赋值操作之前，
那值列表会被 <em>调整</em> 为左边变量列表的个数。
如果值比需要的更多的话，多余的值就被扔掉。 
如果值的数量不够需求，
将会按所需扩展若干个 <b>nil</b>。
如果表达式列表以一个函数调用结束，
这个函数所返回的所有值都会在调整操作之前被置入值列表中
（除非这个函数调用被用括号括了起来；参见 <a href="#3.4">&sect;3.4</a>）。


<p>
赋值语句首先让所有的表达式完成运算，
之后再做赋值操作。
因此，下面这段代码

<pre>
     i = 3
     i, a[i] = i+1, 20
</pre><p>
会把 <code>a[3]</code> 设置为 20，而不会影响到 <code>a[4]</code> 。
这是因为 <code>a[i]</code> 中的 <code>i</code> 在被赋值为 4 之前就被计算出来了（当时是 3 ）。 
简单说 ，这样一行

<pre>
     x, y = y, x
</pre><p>
会交换 <code>x</code> 和 <code>y</code> 的值，
及

<pre>
     x, y, z = y, z, x
</pre><p>
会轮换 <code>x</code>，<code>y</code>，<code>z</code> 的值。


<p>
对全局变量以及表的域的赋值操作的含义可以通过元表来改变。
对 <code>t[i] = val</code> 这样的变量索引赋值，
等价于 <code>settable_event(t,i,val)</code>。
（关于函数 <code>settable_event</code> 的详细说明，参见
<a href="#2.4">&sect;2.4</a>。
这个函数并没有在 Lua 中定义出来，也不可以被调用。
这里我们列出来，仅仅出于方便解释的目的。）


<p>
对于全局变量 <code>x = val</code> 的赋值等价于
<code>_ENV.x = val</code>
（参见 <a href="#2.2">&sect;2.2</a>）。


<h3>3.3.4 &ndash; <a name="3.3.4">控制结构</a></h3><p>
<b>if</b>, <b>while</b>, and <b>repeat</b>
这些控制结构符合通常的意义，而且也有类似的语法：


<pre>
	stat ::= <b>while</b> exp <b>do</b> block <b>end</b>
	stat ::= <b>repeat</b> block <b>until</b> exp
	stat ::= <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b>
</pre><p>
Lua 也有一个 <b>for</b> 语句，它有两种形式
（参见 <a href="#3.3.5">&sect;3.3.5</a>）。


<p>
控制结构中的条件表达式可以返回任何值。
<b>false</b> 与 <b>nil</b> 两者都被认为是假。
所有不同于 <b>nil</b> 与 <b>false</b> 的其它值都被认为是真
（特别需要注意的是，数字 0 和空字符串也被认为是真）。


<p>
在 <b>repeat</b>&ndash;<b>until</b> 循环中，
内部语句块的结束点不是在 <b>until</b> 这个关键字处，
它还包括了其后的条件表达式。
因此，条件表达式中可以使用循环内部语句块中的定义的局部变量。


<p>
<b>goto</b> 语句将程序的控制点转移到一个标签处。
由于句法上的原因，
Lua 里的标签也被认为是语句：


<pre>
	stat ::= <b>goto</b> Name
	stat ::= label
	label ::= &lsquo;<b>::</b>&rsquo; Name &lsquo;<b>::</b>&rsquo;
</pre>

<p>
除了在内嵌函数中，以及在内嵌语句块中定义了同名标签，的情况外，
标签对于它定义所在的整个语句块可见。
只要 goto 没有进入一个新的局部变量的作用域，它可以跳转到任意可见标签处。


<p>
标签和没有内容的语句被称为<em>空语句</em>，它们不做任何操作。


<p>
<b>break</b> 被用来结束
<b>while</b>、 <b>repeat</b>、或 <b>for</b> 循环，
它将跳到循环外接着之后的语句运行：


<pre>
	stat ::= <b>break</b>
</pre><p>
<b>break</b> 跳出最内层的循环。


<p>
<b>return</b> 被用于从函数或是代码块（其实它就是一个函数）
中返回值。

函数可以返回不止一个值，所以 <b>return</b> 的语法为

<pre>
	stat ::= <b>return</b> [explist] [&lsquo;<b>;</b>&rsquo;]
</pre>

<p>
<b>return</b> 只能被写在一个语句块的最后一句。
如果你真的需要从语句块的中间 <b>return</b>，
你可以使用显式的定义一个内部语句块，
一般写作 <code>do return end</code>。
可以这样写是因为现在 <b>return</b> 成了（内部）语句块的最后一句了。


<h3>3.3.5 &ndash; <a name="3.3.5">For 语句</a></h3>

<p>
<b>for</b> 有两种形式：一种是数字形式，另一种是通用形式。


<p>
数字形式的 <b>for</b> 循环，通过一个数学运算不断地运行内部的代码块。
下面是它的语法：

<pre>
	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>
</pre><p>
<em>block</em> 将把 <em>name</em> 作循环变量。
从第一个 <em>exp</em> 开始起，直到第二个 <em>exp</em> 的值为止，
其步长为第三个 <em>exp</em> 。
更确切的说，一个 <b>for</b> 循环看起来是这个样子

<pre>
     for v = <em>e1</em>, <em>e2</em>, <em>e3</em> do <em>block</em> end
</pre><p>
这等价于代码：

<pre>
     do
       local <em>var</em>, <em>limit</em>, <em>step</em> = tonumber(<em>e1</em>), tonumber(<em>e2</em>), tonumber(<em>e3</em>)
       if not (<em>var</em> and <em>limit</em> and <em>step</em>) then error() end
       <em>var</em> = <em>var</em> - <em>step</em>
       while true do
         <em>var</em> = <em>var</em> + <em>step</em>
         if (<em>step</em> &gt;= 0 and <em>var</em> &gt; <em>limit</em>) or (<em>step</em> &lt; 0 and <em>var</em> &lt; <em>limit</em>) then
           break
         end
         local v = <em>var</em>
         <em>block</em>
       end
     end
</pre>

<p>
注意下面这几点：

<ul>

<li>
所有三个控制表达式都只被运算一次，
表达式的计算在循环开始之前。 
这些表达式的结果必须是数字。
</li>

<li>
<code><em>var</em></code>，<code><em>limit</em></code>，以及 <code><em>step</em></code>
都是一些不可见的变量。 
这里给它们起的名字都仅仅用于解释方便。
</li>

<li>
如果第三个表达式（步长）没有给出，会把步长设为 1 。
</li>

<li>
你可以用 <b>break</b> 和 <b>goto</b> 来退出 <b>for</b> 循环。
</li>

<li>
循环变量 <code>v</code> 是一个循环内部的局部变量；
如果你需要在循环结束后使用这个值，
在退出循环前把它赋给另一个变量。
</li>

</ul>

<p>
通用形式的 <b>for</b> 通过一个叫作 <em>迭代器</em> 的函数工作。
每次迭代，迭代器函数都会被调用以产生一个新的值，
当这个值为 <b>nil</b> 时，循环停止。 
通用形式的 <b>for</b> 循环的语法如下：

<pre>
	stat ::= <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b>
	namelist ::= Name {&lsquo;<b>,</b>&rsquo; Name}
</pre><p>
这样的 <b>for</b> 语句

<pre>
     for <em>var_1</em>, &middot;&middot;&middot;, <em>var_n</em> in <em>explist</em> do <em>block</em> end
</pre><p>
它等价于这样一段代码：

<pre>
     do
       local <em>f</em>, <em>s</em>, <em>var</em> = <em>explist</em>
       while true do
         local <em>var_1</em>, &middot;&middot;&middot;, <em>var_n</em> = <em>f</em>(<em>s</em>, <em>var</em>)
         if <em>var_1</em> == nil then break end
         <em>var</em> = <em>var_1</em>
         <em>block</em>
       end
     end
</pre><p>
注意以下几点：

<ul>

<li>
<code><em>explist</em></code> 只会被计算一次。
它返回三个值， 一个 <em>迭代器</em> 函数，
一个 <em>状态</em>，
一个 <em>迭代器的初始值</em>。
</li>

<li>
<code><em>f</em></code>， <code><em>s</em></code>，与 <code><em>var</em></code>
都是不可见的变量。
这里给它们起的名字都只是为了解说方便。
</li>

<li>
你可以使用 <b>break</b> 来跳出 <b>for</b> 循环。
</li>

<li>
环变量 <code><em>var_i</em></code> 对于循环来说是一个局部变量；
你不可以在 <b>for</b> 循环结束后继续使用。
如果你需要保留这些值，那么就在循环跳出或结束前赋值到别的变量里去。
</li>

</ul>


<h3>3.3.6 &ndash; <a name="3.3.6">函数调用语句</a></h3><p>
为了允许使用函数的副作用，
函数调用可以被作为一个语句执行：

<pre>
	stat ::= functioncall
</pre><p>
在这种情况下，所有的返回值都被舍弃。
函数调用在 <a href="#3.4.10">&sect;3.4.10</a> 中解释。


<h3>3.3.7 &ndash; <a name="3.3.7">局部声明</a></h3><p>
局部变量可以在语句块中任何地方声明。 
声明可以包含一个初始化赋值操作：


<pre>
	stat ::= <b>local</b> namelist [&lsquo;<b>=</b>&rsquo; explist]
</pre><p>
如果有初始化值的话，初始化赋值操作的语法和赋值操作一致
（参见 <a href="#3.3.3">&sect;3.3.3</a> ）。
若没有初始化值，所有的变量都被初始化为 <b>nil</b>。


<p>
一个代码块同时也是一个语句块（参见 <a href="#3.3.2">&sect;3.3.2</a>），
所以局部变量可以放在代码块中那些显式注明的语句块之外。 


<p>
局部变量的可见性规则在 <a href="#3.5">&sect;3.5</a> 中解释。


<h2>3.4 &ndash; <a name="3.4">表达式</a></h2>

<p>
Lua 中有这些基本表达式：

<pre>
	exp ::= prefixexp
	exp ::= <b>nil</b> | <b>false</b> | <b>true</b>
	exp ::= Numeral
	exp ::= LiteralString
	exp ::= functiondef
	exp ::= tableconstructor
	exp ::= &lsquo;<b>...</b>&rsquo;
	exp ::= exp binop exp
	exp ::= unop exp
	prefixexp ::= var | functioncall | &lsquo;<b>(</b>&rsquo; exp &lsquo;<b>)</b>&rsquo;
</pre>

<p>
数字和字面串在 <a href="#3.1">&sect;3.1</a> 中解释；
变量在 <a href="#3.2">&sect;3.2</a> 中解释；
函数定义在 <a href="#3.4.11">&sect;3.4.11</a> 中解释；
函数调用在 <a href="#3.4.10">&sect;3.4.10</a> 中解释；
表的构造在 <a href="#3.4.9">&sect;3.4.9</a> 中解释。
可变参数的表达式写作三个点（'<code>...</code>'），
它只能在有可变参数的函数中直接使用；这些在 <a href="#3.4.11">&sect;3.4.11</a> 中解释。


<p>
二元操作符包含有数学运算操作符（参见 <a href="#3.4.1">&sect;3.4.1</a>），
位操作符（参见 <a href="#3.4.2">&sect;3.4.2</a>），
比较操作符（参见 <a href="#3.4.4">&sect;3.4.4</a>），
逻辑操作符（参见 <a href="#3.4.5">&sect;3.4.5</a>），
以及连接操作符（参见 <a href="#3.4.6">&sect;3.4.6</a>）。
一元操作符包括负号（参见 <a href="#3.4.1">&sect;3.4.1</a>），
按位非（参见 <a href="#3.4.2">&sect;3.4.2</a>），
逻辑非（参见 <a href="#3.4.5">&sect;3.4.5</a>），
和取长度操作符（参见 <a href="#3.4.7">&sect;3.4.7</a>）。


<p>
函数调用和可变参数表达式都可以放在多重返回值中。 
如果函数调用被当作一条语句（参见 <a href="#3.3.6">&sect;3.3.6</a>），
其返回值列表被调整为零个元素，即抛弃所有的返回值。
如果表达式被用于表达式列表的最后（或是唯一的）一个元素，
那么不会做任何调整（除非表达式被括号括起来）。
在其它情况下，
Lua 都会把结果调整为一个元素置入表达式列表中，
即保留第一个结果而忽略之后的所有值，或是在没有结果时，
补单个 <b>nil</b>。


<p>
这里有一些例子：

<pre>
     f()                -- 调整为 0 个结果
     g(f(), x)          -- f() 会被调整为一个结果
     g(x, f())          -- g 收到 x 以及 f() 返回的所有结果
     a,b,c = f(), x     -- f() 被调整为 1 个结果 （c 收到 nil）
     a,b = ...          -- a 收到可变参数列表的第一个参数，
                        -- b 收到第二个参数（如果可变参数列表中
                        -- 没有实际的参数，a 和 b 都会收到 nil）
     
     a,b,c = x, f()     -- f() 被调整为 2 个结果
     a,b,c = f()        -- f() 被调整为 3 个结果
     return f()         -- 返回 f() 的所有返回结果
     return ...         -- 返回从可变参数列表中接收到的所有参数parameters
     return x,y,f()     -- 返回 x, y, 以及 f() 的所有返回值
     {f()}              -- 用 f() 的所有返回值创建一个列表
     {...}              -- 用可变参数中的所有值创建一个列表
     {f(), nil}         -- f() 被调整为一个结果
</pre>

<p>
被括号括起来的表达式永远被当作一个值。
所以，
<code>(f(x,y,z))</code> 即使 <code>f</code> 返回多个值，
这个表达式永远是一个单一值。 
（<code>(f(x,y,z))</code> 的值是 <code>f</code> 返回的第一个值。
如果 <code>f</code> 不返回值的话，那么它的值就是 <b>nil</b> 。）


<h3>3.4.1 &ndash; <a name="3.4.1">数学运算操作符</a></h3><p>
Lua 支持下列数学运算操作符：

<ul>
<li><b><code>+</code>: </b>加法</li>
<li><b><code>-</code>: </b>减法</li>
<li><b><code>*</code>: </b>乘法</li>
<li><b><code>/</code>: </b>浮点除法</li>
<li><b><code>//</code>: </b>向下取整除法</li>
<li><b><code>%</code>: </b>取模</li>
<li><b><code>^</code>: </b>乘方</li>
<li><b><code>-</code>: </b>取负</li>
</ul>

<p>
除了乘方和浮点除法运算，
数学运算按如下方式工作：
如果两个操作数都是整数，
该操作以整数方式操作且结果也将是一个整数。
否则，当两个操作数都是数字或可以被转换为数字的字符串
（参见 <a href="#3.4.3">&sect;3.4.3</a>）时，
操作数会被转换成两个浮点数，
操作按通常的浮点规则（一般遵循 IEEE 754 标准）
来进行，结果也是一个浮点数。


<p>
乘方和浮点除法 （<code>/</code>）
总是把操作数转换成浮点数进行，其结果总是浮点数。
乘方使用 ISO C 函数 <code>pow</code>，
因此它也可以接受非整数的指数。


<p>
向下取整的除法 （<code>//</code>）
指做一次除法，并将商圆整到靠近负无穷的一侧，
即对操作数做除法后取 floor 。


<p>
取模被定义成除法的余数，其商被圆整到靠近负无穷的一侧（向下取整的除法）。


<p>
对于整数数学运算的溢出问题，
这些操作采取的策略是按通常遵循的以 2 为补码的数学运算的 <em>环绕</em> 规则。
（换句话说，它们返回其运算的数学结果对 <em>2<sup>64</sup></em> 取模后的数字。）


<h3>3.4.2 &ndash; <a name="3.4.2">位操作符</a></h3><p>
Lua 支持下列位操作符：

<ul>
<li><b><code>&amp;</code>: </b>按位与</li>
<li><b><code>&#124;</code>: </b>按位或</li>
<li><b><code>~</code>: </b>按位异或</li>
<li><b><code>&gt;&gt;</code>: </b>右移</li>
<li><b><code>&lt;&lt;</code>: </b>左移</li>
<li><b><code>~</code>: </b>按位非</li>
</ul>

<p>
所有的位操作都将操作数先转换为整数
（参见 <a href="#3.4.3">&sect;3.4.3</a>），
然后按位操作，其结果是一个整数。


<p>
对于右移和左移，均用零来填补空位。
移动的位数若为负，则向反方向位移；
若移动的位数的绝对值大于等于
整数本身的位数，其结果为零
（所有位都被移出）。


<h3>3.4.3 &ndash; <a name="3.4.3">强制转换</a></h3><p>
Lua 对一些类型和值的内部表示会在运行时做一些数学转换。
位操作总是将浮点操作数转换成整数。
乘方和浮点除法总是将整数转换为浮点数。
其它数学操作若针对混合操作数
（整数和浮点数）将把整数转换为浮点数；
这一点被称为 <em>通常规则</em>。
C API 同样会按需把整数转换为浮点数以及
把浮点数转换为整数。
此外，字符串连接操作除了字符串，也可以接受数字作为参数。


<p>
当操作需要数字时，Lua 还会把字符串转换为数字。


<p>
当把一个整数转换为浮点数时，
若整数值恰好可以表示为一个浮点数，那就取那个浮点数。
否则，转换会取最接近的较大值或较小值来表示这个数。
这种转换是不会失败的。


<p>
将浮点数转为整数的过程会检查
浮点数能否被准确的表达为一个整数
（即，浮点数是一个整数值且在整数可以表达的区间）。
如果可以，结果就是那个数，否则转换失败。


<p>
从字符串到数字的转换过程遵循以下流程：
首先，遵循按 Lua 词法分析器的规则分析语法来转换为对应的
整数或浮点数。
（字符串可以有前置或后置的空格以及一个符号。）
然后，结果数字再按前述规则转换为所需要的类型（浮点或整数）。


<p>
从数字转换为字符串使用非指定的人可读的格式。
若想完全控制数字到字符串的转换过程，
可以使用字符串库中的 <code>format</code> 函数
（参见 <a href="#pdf-string.format"><code>string.format</code></a>）。


<h3>3.4.4 &ndash; <a name="3.4.4">比较操作符</a></h3><p>
Lua 支持下列比较操作符：

<ul>
<li><b><code>==</code>: </b>等于</li>
<li><b><code>~=</code>: </b>不等于</li>
<li><b><code>&lt;</code>: </b>小于</li>
<li><b><code>&gt;</code>: </b>大于</li>
<li><b><code>&lt;=</code>: </b>小于等于</li>
<li><b><code>&gt;=</code>: </b>大于等于</li>
</ul><p>
这些操作的结果不是 <b>false</b> 就是 <b>true</b>。


<p>
等于操作 （<code>==</code>）先比较操作数的类型。
如果类型不同，结果就是 <b>false</b>。
否则，继续比较值。 
字符串按一般的方式比较。
数字遵循二元操作的规则：
如果两个操作数都是整数，
它们按整数比较；
否则，它们先转换为浮点数，然后再做比较。


<p>
表，用户数据，以及线程都按引用比较：
只有两者引用同一个对象时才认为它们相等。
每次你创建一个新对象（一张表，一个用户数据，或一个线程），
新对象都一定和已有且存在的对象不同。
相同引用的闭包一定相等。
有任何可察觉的差异（不同的行为，不同的定义）一定不等。


<p>
你可以通过使用 "eq" 元方法（参见 <a href="#2.4">&sect;2.4</a>）
来改变 Lua 比较表和用户数据时的方式。


<p>
等于操作不会将字符串转换为数字，反之亦然。
即，<code>"0"==0</code> 结果为 <b>false</b>，
且 <code>t[0]</code> 与 <code>t["0"]</code> 指代着表中的不同项。


<p>
<code>~=</code> 操作完全等价于 (<code>==</code>) 操作的反值。


<p>
大小比较操作以以下方式进行。
如果参数都是数字，
它们按二元操作的常规进行。
否则，如果两个参数都是字符串，
它们的值按当前的区域设置来比较。
再则，Lua 就试着调用 "lt" 或是 "le" 元方法
（参见 <a href="#2.4">&sect;2.4</a>）。
<code>a &gt; b</code> 的比较被转译为 <code>b &lt; a</code>，
<code>a &gt;= b</code> 被转译为 <code>b &lt;= a</code>。


<h3>3.4.5 &ndash; <a name="3.4.5">逻辑操作符</a></h3><p>
Lua 中的逻辑操作符有 <b>and</b>， <b>or</b>，以及 <b>not</b>。
和控制结构（参见 <a href="#3.3.4">&sect;3.3.4</a>）一样，
所有的逻辑操作符把 <b>false</b> 和 <b>nil</b> 都作为假，
而其它的一切都当作真。


<p>
取反操作 <b>not</b> 总是返回 <b>false</b> 或 <b>true</b> 中的一个。
与操作符 <b>and</b> 在第一个参数为 <b>false</b> 或 <b>nil</b> 时
返回这第一个参数；
否则，<b>and</b> 返回第二个参数。 
或操作符 <b>or</b> 在第一个参数不为 <b>nil</b> 也不为 <b>false</b> 时，
返回这第一个参数，否则返回第二个参数。
<b>and</b> 和 <b>or</b> 都遵循短路规则；
也就是说，第二个操作数只在需要的时候去求值。
这里有一些例子：

<pre>
     10 or 20            --&gt; 10
     10 or error()       --&gt; 10
     nil or "a"          --&gt; "a"
     nil and 10          --&gt; nil
     false and error()   --&gt; false
     false and nil       --&gt; false
     false or nil        --&gt; nil
     10 and 20           --&gt; 20
</pre><p>
（在这本手册中，
<code>--&gt;</code> 指前面表达式的结果。）


<h3>3.4.6 &ndash; <a name="3.4.6">字符串连接</a></h3><p>
Lua 中字符串的连接操作符写作两个点（'<code>..</code>'）。
如果两个操作数都是字符串或都是数字，
连接操作将以 <a href="#3.4.3">&sect;3.4.3</a> 中提到的规则把其转换为字符串。
否则，会调用元方法 <code>__concat</code> （参见 <a href="#2.4">&sect;2.4</a>）。


<h3>3.4.7 &ndash; <a name="3.4.7">取长度操作符</a></h3>

<p>
取长度操作符写作一元前置符 <code>#</code>。
字符串的长度是它的字节数（就是以一个字符一个字节计算的字符串长度）。


<p>
程序可以通过 <code>__len</code> 元方法（参见 <a href="#2.4">&sect;2.4</a>）
来修改对字符串类型外的任何值的取长度操作行为。


<p>
如果 <code>__len</code> 元方法没有给出，
表 <code>t</code> 的长度只在表是一个 <em>序列</em> 时有定义。
序列指表的正数键集等于 <em>{1..n}</em> ，
其中 <em>n</em> 是一个非负整数。
在这种情况下，<em>n</em> 是表的长度。
注意这样的表

<pre>
     {10, 20, nil, 40}
</pre><p>
不是一个序列，因为它有键 <code>4</code>
却没有键 <code>3</code>。
（因此，该表的正整数键集不等于 <em>{1..n}</em> 集合，故而就不存在 <em>n</em>。）
注意，一张表是否是一个序列和它的非数字键无关。


<h3>3.4.8 &ndash; <a name="3.4.8">优先级</a></h3><p>
Lua 中操作符的优先级写在下表中，从低到高优先级排序：

<pre>
     or
     and
     &lt;     &gt;     &lt;=    &gt;=    ~=    ==
     |
     ~
     &amp;
     &lt;&lt;    &gt;&gt;
     ..
     +     -
     *     /     //    %
     unary operators (not   #     -     ~)
     ^
</pre><p>
通常，
你可以用括号来改变运算次序。
连接操作符 ('<code>..</code>') 和乘方操作 ('<code>^</code>') 
是从右至左的。 
其它所有的操作都是从左至右。


<h3>3.4.9 &ndash; <a name="3.4.9">表构建</a></h3><p>
表构造子是一个构造表的表达式。
每次构造子被执行，都会构造出一张新的表。
构造子可以被用来构造一张空表，
也可以用来构造一张表并初始化其中的一些域。
一般的构造子的语法如下

<pre>
	tableconstructor ::= &lsquo;<b>{</b>&rsquo; [fieldlist] &lsquo;<b>}</b>&rsquo;
	fieldlist ::= field {fieldsep field} [fieldsep]
	field ::= &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo; &lsquo;<b>=</b>&rsquo; exp | Name &lsquo;<b>=</b>&rsquo; exp | exp
	fieldsep ::= &lsquo;<b>,</b>&rsquo; | &lsquo;<b>;</b>&rsquo;
</pre>

<p>
每个形如 <code>[exp1] = exp2</code> 的域向表中增加新的一项，
其键为 <code>exp1</code> 而值为 <code>exp2</code>。
形如 <code>name = exp</code> 的域等价于
<code>["name"] = exp</code>。
最后，形如 <code>exp</code> 的域等价于 <code>[i] = exp</code> ，
这里的 <code>i</code> 是一个从 1 开始不断增长的数字。
这这个格式中的其它域不会破坏其记数。
举个例子：

<pre>
     a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 }
</pre><p>
等价于

<pre>
     do
       local t = {}
       t[f(1)] = g
       t[1] = "x"         -- 1st exp
       t[2] = "y"         -- 2nd exp
       t.x = 1            -- t["x"] = 1
       t[3] = f(x)        -- 3rd exp
       t[30] = 23
       t[4] = 45          -- 4th exp
       a = t
     end
</pre>

<p>
构造子中赋值的次序未定义。
（次序问题只会对那些键重复时的情况有影响。）


<p>
如果表单中最后一个域的形式是 <code>exp</code> ，
而且其表达式是一个函数调用或者是一个可变参数，
那么这个表达式所有的返回值将依次进入列表 
（参见 <a href="#3.4.10">&sect;3.4.10</a>）。


<p>
初始化域表可以在最后多一个分割符，
这样设计可以方便由机器生成代码。


<h3>3.4.10 &ndash; <a name="3.4.10">函数调用</a></h3><p>
Lua 中的函数调用的语法如下：

<pre>
	functioncall ::= prefixexp args
</pre><p>
函数调用时，
第一步，prefixexp 和 args 先被求值。
如果 prefixexp 的值的类型是 <em>function</em>，
那么这个函数就被用给出的参数调用。
否则 prefixexp 的元方法 "call" 就被调用，
第一个参数是 prefixexp 的值，
接下来的是原来的调用参数 
（参见 <a href="#2.4">&sect;2.4</a>）。


<p>
这样的形式

<pre>
	functioncall ::= prefixexp &lsquo;<b>:</b>&rsquo; Name args
</pre><p>
可以用来调用 "方法"。
这是 Lua 支持的一种语法糖。
像 <code>v:name(args)</code> 这个样子，
被解释成 <code>v.name(v,args)</code>，
这里的 <code>v</code> 只会被求值一次。


<p>
参数的语法如下：

<pre>
	args ::= &lsquo;<b>(</b>&rsquo; [explist] &lsquo;<b>)</b>&rsquo;
	args ::= tableconstructor
	args ::= LiteralString
</pre><p>
所有参数的表达式求值都在函数调用之前。
这样的调用形式 <code>f{fields}</code> 是一种语法糖用于表示
<code>f({fields})</code>；
这里指参数列表是一个新创建出来的列表。
而这样的形式 <code>f'<em>string</em>'</code>
（或是 <code>f"<em>string</em>"</code> 亦或是 <code>f[[<em>string</em>]]</code>）
也是一种语法糖，用于表示 <code>f('<em>string</em>')</code>；
此时的参数列表是一个单独的字符串。


<p>
<code>return <em>functioncall</em></code> 
这样的调用形式将触发一次 <em>尾调用</em>。
Lua 实现了 <em>完全尾调用</em>（或称为 <em>完全尾递归</em>）：
在尾调用中， 被调用的函数重用调用它的函数的堆栈项。
因此，对于程序执行的嵌套尾调用的层数是没有限制的。
然而，尾调用将删除调用它的函数的任何调试信息。
注意，尾调用只发生在特定的语法下，
仅当 <b>return</b> 只有单一函数调用作为参数时才发生尾调用；
这种语法使得调用函数的所有结果可以完整地返回。
因此，下面这些例子都不是尾调用：

<pre>
     return (f(x))        -- 返回值被调整为一个
     return 2 * f(x)
     return x, f(x)       -- 追加若干返回值
     f(x); return         -- 返回值全部被舍弃
     return x or f(x)     -- 返回值被调整为一个
</pre>


<h3>3.4.11 &ndash; <a name="3.4.11">函数定义</a></h3>

<p>
函数定义的语法如下：

<pre>
	functiondef ::= <b>function</b> funcbody
	funcbody ::= &lsquo;<b>(</b>&rsquo; [parlist] &lsquo;<b>)</b>&rsquo; block <b>end</b>
</pre>

<p>
另外定义了一些语法糖简化函数定义的写法：

<pre>
	stat ::= <b>function</b> funcname funcbody
	stat ::= <b>local</b> <b>function</b> Name funcbody
	funcname ::= Name {&lsquo;<b>.</b>&rsquo; Name} [&lsquo;<b>:</b>&rsquo; Name]
</pre><p>
该语句

<pre>
     function f () <em>body</em> end
</pre><p>
被转译成

<pre>
     f = function () <em>body</em> end
</pre><p>
该语句

<pre>
     function t.a.b.c.f () <em>body</em> end
</pre><p>
被转译成

<pre>
     t.a.b.c.f = function () <em>body</em> end
</pre><p>
该语句

<pre>
     local function f () <em>body</em> end
</pre><p>
被转译成

<pre>
     local f; f = function () <em>body</em> end
</pre><p>
而不是

<pre>
     local f = function () <em>body</em> end
</pre><p>
（这个差别只在函数体内需要引用 <code>f</code> 时才有。）


<p>
一个函数定义是一个可执行的表达式，
执行结果是一个类型为 <em>function</em> 的值。
当 Lua 预编译一个代码块时，
代码块作为一个函数，整个函数体也就被预编译了。
那么，无论何时 Lua 执行了函数定义，
这个函数本身就进行了 <em>实例化</em>（或者说是 <em>关闭</em>了）。
这个函数的实例（或者说是 <em>闭包</em>）是表达式的最终值。

<p>
形参被看作是一些局部变量，
它们将由实参的值来初始化：

<pre>
	parlist ::= namelist [&lsquo;<b>,</b>&rsquo; &lsquo;<b>...</b>&rsquo;] | &lsquo;<b>...</b>&rsquo;
</pre><p>
当一个函数被调用，
如果函数并非一个 <em>可变参数函数</em>，
即在形参列表的末尾注明三个点 ('<code>...</code>')，
那么实参列表就会被调整到形参列表的长度。
变长参数函数不会调整实参列表； 
取而代之的是，它将把所有额外的参数放在一起通过
<em>变长参数表达式</em>传递给函数，
其写法依旧是三个点。
这个表达式的值是一串实参值的列表，
看起来就跟一个可以返回多个结果的函数一样。
如果一个变长参数表达式放在另一个表达式中使用，
或是放在另一串表达式的中间，
那么它的返回值就会被调整为单个值。
若这个表达式放在了一系列表达式的最后一个，
就不会做调整了
（除非这最后一个参数被括号给括了起来）。


<p>
我们先做如下定义，然后再来看一个例子：

<pre>
     function f(a, b) end
     function g(a, b, ...) end
     function r() return 1,2,3 end
</pre><p>
下面看看实参到形参数以及可变长参数的映射关系：

<pre>
     CALL            PARAMETERS
     
     f(3)             a=3, b=nil
     f(3, 4)          a=3, b=4
     f(3, 4, 5)       a=3, b=4
     f(r(), 10)       a=1, b=10
     f(r())           a=1, b=2
     
     g(3)             a=3, b=nil, ... --&gt;  (nothing)
     g(3, 4)          a=3, b=4,   ... --&gt;  (nothing)
     g(3, 4, 5, 8)    a=3, b=4,   ... --&gt;  5  8
     g(5, r())        a=5, b=1,   ... --&gt;  2  3
</pre>

<p>
结果由 <b>return</b> 来返回（参见 <a href="#3.3.4">&sect;3.3.4</a>）。
如果执行到函数末尾依旧没有遇到任何 <b>return</b> 语句，
函数就不会返回任何结果。


<p>
关于函数可返回值的数量限制和系统有关。
这个限制一定大于 1000 。


<p>
<em>冒号</em> 语法可以用来定义 <em>方法</em>，
就是说，函数可以有一个隐式的形参 <code>self</code>。
因此，如下语句

<pre>
     function t.a.b.c:f (<em>params</em>) <em>body</em> end
</pre><p>
是这样一种写法的语法糖

<pre>
     t.a.b.c.f = function (self, <em>params</em>) <em>body</em> end
</pre>


<h2>3.5 &ndash; <a name="3.5">可见性规则</a></h2>

<p>
Lua 语言有词法作用范围。
变量的作用范围开始于声明它们之后的第一个语句段，
结束于包含这个声明的最内层语句块的最后一个非空语句。
看下面这些例子：

<pre>
     x = 10                -- 全局变量
     do                    -- 新的语句块
       local x = x         -- 新的一个 'x', 它的值现在是 10
       print(x)            --&gt; 10
       x = x+1
       do                  -- 另一个语句块
         local x = x+1     -- 又一个 'x'
         print(x)          --&gt; 12
       end
       print(x)            --&gt; 11
     end
     print(x)              --&gt; 10 （取到的是全局的那一个）
</pre>

<p>
注意这里，类似 <code>local x = x</code> 这样的声明，
新的 <code>x</code> 正在被声明，但是还没有进入它的作用范围，
所以第二个 <code>x</code> 指向的是外面一层的变量。


<p>
因为有这样一个词法作用范围的规则，
局部变量可以被在它的作用范围内定义的函数自由使用。
当一个局部变量被内层的函数中使用的时候，
它被内层函数称作 <em>上值</em>，或是 <em>外部局部变量</em>。


<p>
注意，每次执行到一个 <b>local</b> 语句都会定义出一个新的局部变量。
看看这样一个例子：

<pre>
     a = {}
     local x = 20
     for i=1,10 do
       local y = 0
       a[i] = function () y=y+1; return x+y end
     end
</pre><p>
这个循环创建了十个闭包（这指十个匿名函数的实例）。
这些闭包中的每一个都使用了不同的 <code>y</code> 变量，
而它们又共享了同一份 <code>x</code>。


<h1>4 &ndash; <a name="4">编程接口</a></h1>

<p>
这个部分描述了 Lua 的 C API ，
也就是宿主程序跟 Lua 通讯用的一组 C 函数。 
所有的 API 函数按相关的类型以及常量都声明在头文件 
<a name="pdf-lua.h"><code>lua.h</code></a> 中。


<p>
虽然我们说的是“函数”，
但一部分简单的 API 是以宏的形式提供的。 
除非另有说明，
所有的这些宏都只使用它们的参数一次 
（除了第一个参数，那一定是 Lua 状态），
因此你不需担心这些宏的展开会引起一些副作用。


<p>
C 库中所有的 Lua API 函数都不去检查参数是否相容及有效。
然而，你可以在编译 Lua 时加上打开一个宏开关
<a name="pdf-LUA_USE_APICHECK"><code>LUA_USE_APICHECK</code></a>
来改变这个行为。


<h2>4.1 &ndash; <a name="4.1">栈</a></h2>

<p>
Lua 使用一个 <em>虚拟栈</em> 来和 C 互传值。
栈上的的每个元素都是一个 Lua 值 （<b>nil</b>，数字，字符串，等等）。


<p>
无论何时 Lua 调用 C，被调用的函数都得到一个新的栈，
这个栈独立于 C 函数本身的栈，也独立于之前的 Lua 栈。
它里面包含了 Lua 传递给 C 函数的所有参数，
而 C 函数则把要返回的结果放入这个栈以返回给调用者 
（参见 <a href="#lua_CFunction"><code>lua_CFunction</code></a>）。


<p>
方便起见，
所有针对栈的 API 查询操作都不严格遵循栈的操作规则。
而是可以用一个 <em>索引</em> 来指向栈上的任何元素：
正的索引指的是栈上的绝对位置（从1开始）；
负的索引则指从栈顶开始的偏移量。
展开来说，如果堆栈有 <em>n</em> 个元素，
那么索引 1 表示第一个元素
（也就是最先被压栈的元素）
而索引 <em>n</em> 则指最后一个元素；
索引 -1 也是指最后一个元素
（即栈顶的元素）， 
索引 <em>-n</em> 是指第一个元素。


<h2>4.2 &ndash; <a name="4.2">栈大小</a></h2>

<p>
当你使用 Lua API 时，
就有责任保证做恰当的调用。 
特别需要注意的是，
<em>你有责任控制不要堆栈溢出</em>。
你可以使用 <a href="#lua_checkstack"><code>lua_checkstack</code></a>
这个函数来扩大可用堆栈的尺寸。


<p>
无论何时 Lua 调用 C ，
它都只保证至少有
<a name="pdf-LUA_MINSTACK"><code>LUA_MINSTACK</code></a>
这么多的堆栈空间可以使用。
<code>LUA_MINSTACK</code> 一般被定义为 20 ，
因此，只要你不是不断的把数据压栈，
通常你不用关心堆栈大小。


<p>
当你调用一个 Lua 函数却没有指定要接收多少个返回值时
（参见 <a href="#lua_call"><code>lua_call</code></a>），
Lua 可以保证栈一定有足够的空间来接收所有的返回值，
但不保证此外留有额外的空间。
因此，在做了一次这样的调用后，如果你需要继续压栈，
则需要使用 <a href="#lua_checkstack"><code>lua_checkstack</code></a>。


<h2>4.3 &ndash; <a name="4.3">有效索引与可接受索引</a></h2>

<p>
API 中的函数若需要传入栈索引，这个索引必须是
<em>有效索引</em> 或是 <em>可接受索引</em>。


<p>
<em>有效索引</em> 指引用栈内真实位置的索引；
即在 1 到栈顶之间的位置
（<code>1 &le; abs(index) &le; top</code>）。

通常，一个可能修改该位置的值的函数需要传入有效索引。


<p>
除非另有说明，
任何可以接受有效索引的函数同时也接受 <em>伪索引</em>。
伪索引指代一些可以被 C code 访问得到 Lua 值，而它们又不在栈内。
这用于访问注册表以及 C 函数的上值（参见 <a href="#4.4">&sect;4.4</a>）。


<p>
对于那些只是需要栈中的值（例如查询函数）
而不需要指定一个栈位置的函数，
可以用一个可接受的索引去调用它们。
<em>可接受索引</em> 不仅可以是任何包括伪索引在内的有效索引，
还可以是任何超过栈顶但落在为栈分配出来的空间内的正索引。
（注意 0 永远都不是一个可接受索引。）
除非另有说明，API 里的函数都接受可接受索引。


<p>
允许可接受索引是为了避免对栈顶以外的查询时做额外的检查。
例如，C 函数可以直接查询传给它的第三个参数，
而不用先检查是不是有第三个参数，
即不需要检查 3 是不是一个有效索引。


<p>
对于那可以接受索引调用的函数，
无效索引被看作包含了一个虚拟类型
<a name="pdf-LUA_TNONE"><code>LUA_TNONE</code></a> 的值，
这个值的行为和 nil 一致。


<h2>4.4 &ndash; <a name="4.4">C 闭包</a></h2>

<p>
当 C 函数被创建出来，
我们有可能会把一些值关联在一起，
也就是创建一个 <em>C 闭包</em>
（参见 <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>）；
这些被关联起来的值被叫做 <em>上值</em> ，
它们可以在函数被调用的时候访问的到。 


<p>
无论何时去调用 C 函数，
函数的上值都可以用伪索引定位。
我们可以用
<a href="#lua_upvalueindex"><code>lua_upvalueindex</code></a>
这个宏来生成这些伪索引。
第一个关联到函数的值放在
<code>lua_upvalueindex(1)</code> 位置处，依此类推。 
使用 <code>lua_upvalueindex(<em>n</em>)</code> 时，
若 <em>n</em> 大于当前函数的总上值个数
（但不可以大于 256）会产生一个可接受的但无效的索引。


<h2>4.5 &ndash; <a name="4.5">注册表</a></h2>

<p>
Lua 提供了一个 <em>注册表</em>，
这是一个预定义出来的表，
可以用来保存任何 C 代码想保存的 Lua 值。 
这个表可以用有效伪索引 
<a name="pdf-LUA_REGISTRYINDEX"><code>LUA_REGISTRYINDEX</code></a> 来定位。
任何 C 库都可以在这张表里保存数据，
为了防止冲突，你需要特别小心的选择键名。
一般的用法是，你可以用一个包含你的库名的字符串做为键名，
或者取你自己 C 对象的地址，以轻量用户数据的形式做键，
还可以用你的代码创建出来的任意 Lua 对象做键。
关于变量名，字符串键名中以下划线加大写字母的名字被 Lua 保留。


<p>
注册表中的整数键用于引用机制
（参见 <a href="#luaL_ref"><code>luaL_ref</code></a>），
以及一些预定义的值。
因此，整数键不要用于别的目的。


<p>
当你创建了一个新的 Lua 状态机，
其中的注册表内就预定义好了几个值。
这些预定义值可以用整数索引到，
这些整数以常数形式定义在 <code>lua.h</code> 中。
有下列常数：

<ul>
<li><b><a name="pdf-LUA_RIDX_MAINTHREAD"><code>LUA_RIDX_MAINTHREAD</code></a>: </b>
注册表中这个索引下是状态机的主线程。
（主线程和状态机同时被创建出来。）
</li>

<li><b><a name="pdf-LUA_RIDX_GLOBALS"><code>LUA_RIDX_GLOBALS</code></a>: </b> 
注册表的这个索引下是全局环境。
</li>
</ul>


<h2>4.6 &ndash; <a name="4.6">C 中的错误处理</a></h2>

<p>
在内部实现中，Lua 使用了 C 的 <code>longjmp</code> 机制来处理错误。
（如果你使用 C++ 编译，Lua 将换成异常；
细节请在源代码中搜索 <code>LUAI_THROW</code>。）
当 Lua 碰到任何错误
（比如内存分配错误、类型错误、语法错误、还有运行时错误）
它都会 <em>抛出</em>一个错误出去；
也就是调用一次长跳转。
在 <em>保护环境</em> 下，
Lua 使用 <code>setjmp</code> 来设置一个恢复点；
任何发生的错误都会跳转到最近的一个恢复点。


<p>
如果错误发生在保护环境之外，
Lua 会先调用 <em>panic 函数</em> （参见 <a href="#lua_atpanic"><code>lua_atpanic</code></a>）
然后调用 <code>abort</code> 来退出宿主程序。
你的 panic 函数只要不返回
（例如：长跳转到你在 Lua 外你自己设置的恢复点）
就可以不退出程序。


<p>
panic 函数以错误消息处理器（参见 <a href="#2.3">&sect;2.3</a>）的方式运行；
错误消息在栈顶。
不同的是，它不保证栈空间。
做任何压栈操作前，panic 函数都必须先检查是否有足够的空间
（参见 <a href="#4.2">&sect;4.2</a>）。


<p>
大多数 API 函数都有可能抛出错误，
例如在内存分配错误时就会抛出。
每个函数的文档都会注明它是否可能抛出错误。


<p>
在 C 函数内部，你可以通过调用 <a href="#lua_error"><code>lua_error</code></a>
来抛出错误。


<h2>4.7 &ndash; <a name="4.7">C 中的让出处理</a></h2>

<p>
Lua 内部使用 C 的 <code>longjmp</code> 机制让出一个协程。
因此，如果一个 C 函数 <code>foo</code> 调用了一个 API 函数，
而这个 API 函数让出了（直接或间接调用了让出函数）。
由于 <code>longjmp</code> 会移除 C 栈的栈帧，
Lua 就无法返回到 <code>foo</code> 里了。


<p>
为了回避这类问题，
碰到 API 调用中调用让出时，除了那些抛出错误的 API 外，还提供了三个函数：
<a href="#lua_yieldk"><code>lua_yieldk</code></a>，
<a href="#lua_callk"><code>lua_callk</code></a>，和 <a href="#lua_pcallk"><code>lua_pcallk</code></a> 。
它们在让出发生时，可以从传入的 <em>延续函数</em>
（名为 <code>k</code> 的参数）继续运行。


<p>
我们需要预设一些术语来解释延续点。
对于从 Lua 中调用的 C 函数，我们称之为 <em>原函数</em>。
从这个原函数中调用的上面所述的三个 C API 函数我们称之为 <em>被调函数</em>。
被调函数可以使当前线程让出。
（让出发生在被调函数是 <a href="#lua_yieldk"><code>lua_yieldk</code></a>，
或传入 <a href="#lua_callk"><code>lua_callk</code></a> 或
<a href="#lua_pcallk"><code>lua_pcallk</code></a> 的函数调用了让出时。）


<p>
假设正在运行的线程在执行被调函数时让出。
当再次延续这条线程，它希望继续被调函数的运行。
然而，被调函数不可能返回到原函数中。
这是因为之前的让出操作破坏了 C 栈的栈帧。
作为替代品，Lua 调用那个作为被调函数参数给出的 <em>延续函数</em> 。
正如其名，延续函数将延续原函数的任务。


<p>
下面的函数会做一个说明：

<pre>
     int original_function (lua_State *L) {
       ...     /* code 1 */
       status = lua_pcall(L, n, m, h);  /* calls Lua */
       ...     /* code 2 */
     }
</pre><p>
现在我们想允许被
<a href="#lua_pcall"><code>lua_pcall</code></a>
运行的 Lua 代码让出。
首先，我们把函数改写成这个样子：

<pre>
     int k (lua_State *L, int status, lua_KContext ctx) {
       ...  /* code 2 */
     }
     
     int original_function (lua_State *L) {
       ...     /* code 1 */
       return k(L, lua_pcall(L, n, m, h), ctx);
     }
</pre><p>
上面的代码中，新函数 <code>k</code>
就是一个 <em>延续函数</em>
（函数类型为 <a href="#lua_KFunction"><code>lua_KFunction</code></a>）。
它的工作就是原函数中调用 <a href="#lua_pcall"><code>lua_pcall</code></a>
之后做的那些事情。
现在我们必须通知 Lua 说，你必须在被
<a href="#lua_pcall"><code>lua_pcall</code></a>
执行的 Lua 代码发生过中断（错误或让出）后，
还得继续调用 <code>k</code> 。
所以我们还得继续改写这段代码，把
<a href="#lua_pcall"><code>lua_pcall</code></a> 替换成
<a href="#lua_pcallk"><code>lua_pcallk</code></a>：


<pre>
     int original_function (lua_State *L) {
       ...     /* code 1 */
       return k(L, lua_pcallk(L, n, m, h, ctx2, k), ctx1);
     }
</pre><p>
注意这里那个额外的显式的对延续函数的调用：
Lua 仅在需要时，这可能是由错误导致的也可能是发生了让出而需要继续运行，才会调用延续函数。
如果没有发生过任何让出，调用的函数正常返回，
那么 <a href="#lua_pcallk"><code>lua_pcallk</code></a>
（以及 <a href="#lua_callk"><code>lua_callk</code></a>）也会正常返回。
（当然，这个例子中你也可以不在之后调用延续函数，
而是在原函数的调用后直接写上需要做的工作。）


<p>
除了 Lua 状态，延续函数还有两个参数：
一个是调用最后的状态码，另一个一开始由
<a href="#lua_pcallk"><code>lua_pcallk</code></a> 传入的上下文
（<code>ctx</code>）。
（Lua 本身不使用这个值；它仅仅从原函数转发这个值给延续函数。）
对于 <a href="#lua_pcallk"><code>lua_pcallk</code></a> 而言，
状态码和 <a href="#lua_pcallk"><code>lua_pcallk</code></a>
本应返回值相同，区别仅在于发生过让出后才执行完时，状态码为
<a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a>（而不是
<a href="#pdf-LUA_OK"><code>LUA_OK</code></a>）。
对于 <a href="#lua_yieldk"><code>lua_yieldk</code></a> 和
<a href="#lua_callk"><code>lua_callk</code></a> 而言，
调用延续函数传入的状态码一定是
<a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a>。
（对这两个函数，Lua 不会因任何错误而调用延续函数。
因为它们并不处理错误。）
同样，当你使用 <a href="#lua_callk"><code>lua_callk</code></a> 时，
你应该用 <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>
作为状态码来调用延续函数。
（对于 <a href="#lua_yieldk"><code>lua_yieldk</code></a>，
几乎没有什么地方需要直接调用延续函数，
因为 <a href="#lua_yieldk"><code>lua_yieldk</code></a> 本身并不会返回。）


<p>
Lua 会把延续函数看作原函数。
延续函数将接收到和原函数相同的 Lua 栈，其接收到的 lua 状态也和
被调函数若返回后应该有的状态一致。
（例如，
<a href="#lua_callk"><code>lua_callk</code></a> 调用之后，
栈中之前压入的函数和调用参数都被调用产生的返回值所替代。）
这时也有相同的上值。
等到它返回的时候，Lua 会将其看待成原函数的返回去操作。


<h2>4.8 &ndash; <a name="4.8">函数和类型</a></h2>

<p>
这里按字母次序列出了所有 C API 中的函数和类型。
每个函数都有一个这样的提示：
<span class="apii">[-o, +p, <em>x</em>]</span>


<p>
对于第一个域，<code>o</code>，
指的是该函数会从栈上弹出多少个元素。
第二个域，<code>p</code>，
指该函数会将多少个元素压栈。
（所有函数都会在弹出参数后再把结果压栈。）
<code>x|y</code> 这种形式的域表示该函数根据具体情况可能压入（或弹出）
<code>x</code> 或 <code>y</code> 个元素；
问号 '<code>?</code>' 表示
我们无法仅通过参数来了解该函数会弹出/压入多少元素
（比如，数量取决于栈上有些什么）。
第三个域，<code>x</code>，
解释了该函数是否会抛出错误：
'<code>-</code>' 表示该函数绝对不会抛出错误；
'<code>e</code>' 表示该函数可能抛出错误；
'<code>v</code>' 表示该函数可能抛出有意义的错误。


<hr><h3><a name="lua_absindex"><code>lua_absindex</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>int lua_absindex (lua_State *L, int idx);</pre>

<p>
将一个可接受的索引 <code>idx</code> 转换为绝对索引
（即，一个不依赖栈顶在哪的值）。


<hr><h3><a name="lua_Alloc"><code>lua_Alloc</code></a></h3>
<pre>typedef void * (*lua_Alloc) (void *ud,
                             void *ptr,
                             size_t osize,
                             size_t nsize);</pre>

<p>
Lua 状态机中使用的内存分配器函数的类型。
内存分配函数必须提供一个功能类似于 <code>realloc</code>
但又不完全相同的函数。
它的参数有
<code>ud</code> ，一个由 <a href="#lua_newstate"><code>lua_newstate</code></a> 传给它的指针；
<code>ptr</code> ，一个指向已分配出来/将被重新分配/要释放的内存块指针；
<code>osize</code> ，内存块原来的尺寸或是关于什么将被分配出来的代码；
<code>nsize</code> ，新内存块的尺寸。 

<p>
如果 <code>ptr</code> 不是 <code>NULL</code>，
<code>osize</code> 是 <code>ptr</code> 指向的内存块的尺寸，
即这个内存块当初被分配或重分配的尺寸。


<p>
如果 <code>ptr</code> 是 <code>NULL</code>，
<code>osize</code> 是 Lua 即将分配对象类型的编码。
当（且仅当）Lua 创建一个对应类型的新对象时，
<code>osize</code> 是
<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>，
<a href="#pdf-LUA_TUSERDATA"><code>LUA_TUSERDATA</code></a>，或 <a href="#pdf-LUA_TTHREAD"><code>LUA_TTHREAD</code></a> 中的一个。
若 <code>osize</code> 是其它类型，Lua 将为其它东西分配内存。


<p>
Lua 假定分配器函数会遵循以下行为：


<p>
当 <code>nsize</code> 是零时，
分配器必须和 <code>free</code> 行为类似并返回 <code>NULL</code>。


<p>
当 <code>nsize</code> 不是零时，
分配器必须和 <code>realloc</code> 行为类似。
如果分配器无法完成请求，返回 <code>NULL</code>。
Lua 假定在 <code>osize &gt;= nsize</code> 成立的条件下，
分配器绝不会失败。


<p>
这里有一个简单的分配器函数的实现。
这个实现被放在补充库中，供
<a href="#luaL_newstate"><code>luaL_newstate</code></a> 使用。

<pre>
     static void *l_alloc (void *ud, void *ptr, size_t osize,
                                                size_t nsize) {
       (void)ud;  (void)osize;  /* not used */
       if (nsize == 0) {
         free(ptr);
         return NULL;
       }
       else
         return realloc(ptr, nsize);
     }
</pre><p>
注意，标准 C 能确保 <code>free(NULL)</code> 没有副作用，
且 <code>realloc(NULL,size)</code> 等价于 <code>malloc(size)</code>。
这段代码假定 <code>realloc</code> 在缩小块长度时不会失败。
（虽然标准 C 没有对此行为做出保证，但这看起来是一个安全的假定。）


<hr><h3><a name="lua_arith"><code>lua_arith</code></a></h3><p>
<span class="apii">[-(2|1), +1, <em>e</em>]</span>
<pre>void lua_arith (lua_State *L, int op);</pre>

<p>
对栈顶的两个值（或者一个，比如取反）做一次数学或位操作。
其中，栈顶的那个值是第二个操作数。
它会弹出压入的值，并把结果放在栈顶。
这个函数遵循 Lua 对应的操作符运算规则
（即有可能触发元方法）。


<p>
<code>op</code> 的值必须是下列常量中的一个：

<ul>

<li><b><a name="pdf-LUA_OPADD"><code>LUA_OPADD</code></a>: </b> 加法 (<code>+</code>)</li>
<li><b><a name="pdf-LUA_OPSUB"><code>LUA_OPSUB</code></a>: </b> 减法 (<code>-</code>)</li>
<li><b><a name="pdf-LUA_OPMUL"><code>LUA_OPMUL</code></a>: </b> 乘法 (<code>*</code>)</li>
<li><b><a name="pdf-LUA_OPDIV"><code>LUA_OPDIV</code></a>: </b> 浮点除法 (<code>/</code>)</li>
<li><b><a name="pdf-LUA_OPIDIV"><code>LUA_OPIDIV</code></a>: </b> 向下取整的除法 (<code>//</code>)</li>
<li><b><a name="pdf-LUA_OPMOD"><code>LUA_OPMOD</code></a>: </b> 取模 (<code>%</code>)</li>
<li><b><a name="pdf-LUA_OPPOW"><code>LUA_OPPOW</code></a>: </b> 乘方 (<code>^</code>)</li>
<li><b><a name="pdf-LUA_OPUNM"><code>LUA_OPUNM</code></a>: </b> 取负 (一元 <code>-</code>)</li>
<li><b><a name="pdf-LUA_OPBNOT"><code>LUA_OPBNOT</code></a>: </b> 按位取反 (<code>~</code>)</li>
<li><b><a name="pdf-LUA_OPBAND"><code>LUA_OPBAND</code></a>: </b> 按位与 (<code>&amp;</code>)</li>
<li><b><a name="pdf-LUA_OPBOR"><code>LUA_OPBOR</code></a>: </b> 按位或 (<code>|</code>)</li>
<li><b><a name="pdf-LUA_OPBXOR"><code>LUA_OPBXOR</code></a>: </b> 按位异或 (<code>~</code>)</li>
<li><b><a name="pdf-LUA_OPSHL"><code>LUA_OPSHL</code></a>: </b> 左移 (<code>&lt;&lt;</code>)</li>
<li><b><a name="pdf-LUA_OPSHR"><code>LUA_OPSHR</code></a>: </b> 右移 (<code>&gt;&gt;</code>)</li>

</ul>


<hr><h3><a name="lua_atpanic"><code>lua_atpanic</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);</pre>

<p>
设置一个新的 panic 函数，并返回之前设置的那个。
（参见 <a href="#4.6">&sect;4.6</a>）。


<hr><h3><a name="lua_call"><code>lua_call</code></a></h3><p>
<span class="apii">[-(nargs+1), +nresults, <em>e</em>]</span>
<pre>void lua_call (lua_State *L, int nargs, int nresults);</pre>

<p>
调用一个函数。


<p>
要调用一个函数请遵循以下协议：
首先，要调用的函数应该被压入栈；
接着，把需要传递给这个函数的参数按正序压栈；
这是指第一个参数首先压栈。
最后调用一下 <a href="#lua_call"><code>lua_call</code></a>；
<code>nargs</code> 是你压入栈的参数个数。
当函数调用完毕后，所有的参数以及函数本身都会出栈。
而函数的返回值这时则被压栈。
返回值的个数将被调整为 <code>nresults</code> 个，
除非 <code>nresults</code> 被设置成 <a name="pdf-LUA_MULTRET"><code>LUA_MULTRET</code></a>。
在这种情况下，所有的返回值都被压入堆栈中。 
Lua 会保证返回值都放入栈空间中。
函数返回值将按正序压栈（第一个返回值首先压栈），
因此在调用结束后，最后一个返回值将被放在栈顶。

<p>
被调用函数内发生的错误将（通过 <code>longjmp</code> ）一直上抛。

<p>
下面的例子中，这行 Lua 代码等价于在宿主程序中用 C 代码做一些工作：

<pre>
     a = f("how", t.x, 14)
</pre><p>
这里是 C 里的代码：

<pre>
     lua_getglobal(L, "f");                  /* function to be called */
     lua_pushliteral(L, "how");                       /* 1st argument */
     lua_getglobal(L, "t");                    /* table to be indexed */
     lua_getfield(L, -1, "x");        /* push result of t.x (2nd arg) */
     lua_remove(L, -2);                  /* remove 't' from the stack */
     lua_pushinteger(L, 14);                          /* 3rd argument */
     lua_call(L, 3, 1);     /* call 'f' with 3 arguments and 1 result */
     lua_setglobal(L, "a");                         /* set global 'a' */
</pre><p>
注意上面这段代码是 <em>平衡</em> 的：
到了最后，堆栈恢复成原有的配置。
这是一种良好的编程习惯。


<hr><h3><a name="lua_callk"><code>lua_callk</code></a></h3><p>
<span class="apii">[-(nargs + 1), +nresults, <em>e</em>]</span>
<pre>void lua_callk (lua_State *L,
                int nargs,
                int nresults,
                lua_KContext ctx,
                lua_KFunction k);</pre>

<p>
这个函数的行为和 <a href="#lua_call"><code>lua_call</code></a>
完全一致，只不过它还允许被调用的函数让出
（参见 <a href="#4.7">&sect;4.7</a>）。


<hr><h3><a name="lua_CFunction"><code>lua_CFunction</code></a></h3>
<pre>typedef int (*lua_CFunction) (lua_State *L);</pre>

<p>
C 函数的类型。


<p>
为了正确的和 Lua 通讯，
C 函数必须使用下列协议。
这个协议定义了参数以及返回值传递方法：
C 函数通过 Lua 中的栈来接受参数，
参数以正序入栈（第一个参数首先入栈）。
因此，当函数开始的时候，
<code>lua_gettop(L)</code> 可以返回函数收到的参数个数。
第一个参数（如果有的话）在索引 1 的地方，
而最后一个参数在索引 <code>lua_gettop(L)</code> 处。 
当需要向 Lua 返回值的时候，
C 函数只需要把它们以正序压到堆栈上（第一个返回值最先压入），
然后返回这些返回值的个数。
在这些返回值之下的，堆栈上的东西都会被 Lua 丢掉。
和 Lua 函数一样，从 Lua 中调用 C 函数也可以有很多返回值。

<p>
下面这个例子中的函数将接收若干数字参数，并返回它们的平均数与和：

<pre>
     static int foo (lua_State *L) {
       int n = lua_gettop(L);    /* 参数的个数 */
       lua_Number sum = 0.0;
       int i;
       for (i = 1; i &lt;= n; i++) {
         if (!lua_isnumber(L, i)) {
           lua_pushliteral(L, "incorrect argument");
           lua_error(L);
         }
         sum += lua_tonumber(L, i);
       }
       lua_pushnumber(L, sum/n);        /* 第一个返回值 */
       lua_pushnumber(L, sum);         /* 第二个返回值 */
       return 2;                   /* 返回值的个数 */
     }
</pre>


<hr><h3><a name="lua_checkstack"><code>lua_checkstack</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>int lua_checkstack (lua_State *L, int n);</pre>

<p>
确保堆栈上至少有 <code>n</code> 个额外空位。
如果不能把堆栈扩展到相应的尺寸，函数返回假。
失败的原因包括将把栈扩展到比固定最大尺寸还大
（至少是几千个元素）或分配内存失败。
这个函数永远不会缩小堆栈；
如果堆栈已经比需要的大了，那么就保持原样。


<hr><h3><a name="lua_close"><code>lua_close</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>void lua_close (lua_State *L);</pre>

<p>
销毁指定 Lua 状态机中的所有对象
（如果有垃圾收集相关的元方法的话，会调用它们），
并且释放状态机中使用的所有动态内存。
在一些平台上，你可以不必调用这个函数， 
因为当宿主程序结束的时候，所有的资源就自然被释放掉了。
另一方面，长期运行的程序，比如一个后台程序或是一个网站服务器，
会创建出多个 Lua 状态机。那么就应该在不需要时赶紧关闭它们。


<hr><h3><a name="lua_compare"><code>lua_compare</code></a></h3><p>
<span class="apii">[-0, +0, <em>e</em>]</span>
<pre>int lua_compare (lua_State *L, int index1, int index2, int op);</pre>

<p>
比较两个 Lua 值。
当索引 <code>index1</code> 处的值通过 <code>op</code>
和索引 <code>index2</code> 处的值做比较后条件满足，函数返回 1 。
这个函数遵循 Lua 对应的操作规则（即有可能触发元方法）。
反之，函数返回 0。
当任何一个索引无效时，函数也会返回 0 。


<p>
<code>op</code> 值必须是下列常量中的一个：

<ul>

<li><b><a name="pdf-LUA_OPEQ"><code>LUA_OPEQ</code></a>: </b> 相等比较 (<code>==</code>)</li>
<li><b><a name="pdf-LUA_OPLT"><code>LUA_OPLT</code></a>: </b> 小于比较 (<code>&lt;</code>)</li>
<li><b><a name="pdf-LUA_OPLE"><code>LUA_OPLE</code></a>: </b> 小于等于比较 (<code>&lt;=</code>)</li>

</ul>


<hr><h3><a name="lua_concat"><code>lua_concat</code></a></h3><p>
<span class="apii">[-n, +1, <em>e</em>]</span>
<pre>void lua_concat (lua_State *L, int n);</pre>

<p>
连接栈顶的 <code>n</code> 个值，
然后将这些值出栈，并把结果放在栈顶。
如果 <code>n</code> 为 1 ，结果就是那个值放在栈上（即，函数什么都不做）；
如果 <code>n</code> 为 0 ，结果是一个空串。 
连接依照 Lua 中通常语义完成（参见 <a href="#3.4.6">&sect;3.4.6</a> ）。


<hr><h3><a name="lua_copy"><code>lua_copy</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>void lua_copy (lua_State *L, int fromidx, int toidx);</pre>

<p>
从索引 <code>fromidx</code> 处复制一个值到一个有效索引
<code>toidx</code> 处，覆盖那里的原有值。
不会影响其它位置的值。


<hr><h3><a name="lua_createtable"><code>lua_createtable</code></a></h3><p>
<span class="apii">[-0, +1, <em>e</em>]</span>
<pre>void lua_createtable (lua_State *L, int narr, int nrec);</pre>

<p>
创建一张新的空表压栈。
参数 <code>narr</code> 建议了这张表作为序列使用时会有多少个元素；
参数 <code>nrec</code> 建议了这张表可能拥有多少序列之外的元素。
Lua 会使用这些建议来预分配这张新表。
如果你知道这张表用途的更多信息，预分配可以提高性能。
否则，你可以使用函数 <a href="#lua_newtable"><code>lua_newtable</code></a> 。


<hr><h3><a name="lua_dump"><code>lua_dump</code></a></h3><p>
<span class="apii">[-0, +0, <em>e</em>]</span>
<pre>int lua_dump (lua_State *L,
                        lua_Writer writer,
                        void *data,
                        int strip);</pre>

<p>
把函数导出成二进制代码块 。
函数接收栈顶的 Lua 函数做参数，
然后生成它的二进制代码块。
若被导出的东西被再次加载，
加载的结果就相当于原来的函数。
当它在产生代码块的时候，
<a href="#lua_dump"><code>lua_dump</code></a>
通过调用函数 <code>writer</code>
（参见 <a href="#lua_Writer"><code>lua_Writer</code></a> ）
来写入数据，后面的 <code>data</code> 参数会被传入 <code>writer</code> 。

<p>
如果 <code>strip</code> 为真，
二进制代码块将不包含该函数的调试信息。


<p>
最后一次由 <code>writer</code> 的返回值将作为这个函数的返回值返回；
0 表示没有错误。


<p>
该函数不会把 Lua 函数弹出堆栈。


<hr><h3><a name="lua_error"><code>lua_error</code></a></h3><p>
<span class="apii">[-1, +0, <em>v</em>]</span>
<pre>int lua_error (lua_State *L);</pre>

<p>
以栈顶的值作为错误对象，抛出一个 Lua 错误。
这个函数将做一次长跳转，所以一定不会返回
（参见 <a href="#luaL_error"><code>luaL_error</code></a>）。


<hr><h3><a name="lua_gc"><code>lua_gc</code></a></h3><p>
<span class="apii">[-0, +0, <em>e</em>]</span>
<pre>int lua_gc (lua_State *L, int what, int data);</pre>

<p>
控制垃圾收集器。


<p>
这个函数根据其参数 <code>what</code> 发起几种不同的任务：

<ul>

<li><b><code>LUA_GCSTOP</code>: </b>
停止垃圾收集器。
</li>

<li><b><code>LUA_GCRESTART</code>: </b>
重启垃圾收集器。
</li>

<li><b><code>LUA_GCCOLLECT</code>: </b>
发起一次完整的垃圾收集循环。
</li>

<li><b><code>LUA_GCCOUNT</code>: </b>
返回 Lua 使用的内存总量（以 K 字节为单位）。
</li>

<li><b><code>LUA_GCCOUNTB</code>: </b>
返回当前内存使用量除以 1024 的余数。
</li>

<li><b><code>LUA_GCSTEP</code>: </b>
发起一步增量垃圾收集。
</li>

<li><b><code>LUA_GCSETPAUSE</code>: </b>
把 <code>data</code> 设为 <em>垃圾收集器间歇率</em> 
（参见 <a href="#2.5">&sect;2.5</a>），并返回之前设置的值。
</li>

<li><b><code>LUA_GCSETSTEPMUL</code>: </b>
把 <code>data</code> 设为 <em>垃圾收集器步进倍率</em> 
（参见 <a href="#2.5">&sect;2.5</a>），并返回之前设置的值。
</li>

<li><b><code>LUA_GCISRUNNING</code>: </b>
返回收集器是否在运行（即没有停止）。
</li>

</ul>

<p>
关于这些选项的细节，参见 <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> 。


<hr><h3><a name="lua_getallocf"><code>lua_getallocf</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>lua_Alloc lua_getallocf (lua_State *L, void **ud);</pre>

<p>
返回给定状态机的内存分配器函数。
如果 <code>ud</code> 不是 <code>NULL</code> ，
Lua 把设置内存分配函数时设置的那个指针置入 <code>*ud</code> 。


<hr><h3><a name="lua_getfield"><code>lua_getfield</code></a></h3><p>
<span class="apii">[-0, +1, <em>e</em>]</span>
<pre>int lua_getfield (lua_State *L, int index, const char *k);</pre>

<p>
把 <code>t[k]</code> 的值压栈，
这里的 <code>t</code> 是索引指向的值。
在 Lua 中，这个函数可能触发对应 "index" 事件对应的元方法
（参见 <a href="#2.4">&sect;2.4</a> ）。


<p>
函数将返回压入值的类型。


<hr><h3><a name="lua_getextraspace"><code>lua_getextraspace</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>void *lua_getextraspace (lua_State *L);</pre>

<p>
返回一个 Lua 状态机中关联的内存块指针。
程序可以把这块内存用于任何用途；而 Lua 不会使用它。


<p>
每一个新线程都会携带一块内存，
初始化为主线程的这块内存的副本。


<p>
默认配置下，这块内存的大小为空指针的大小。
不过你可以重新编译 Lua 设定这块内存不同的大小。
（参见 <code>luaconf.h</code> 中的 <code>LUA_EXTRASPACE</code>。）


<hr><h3><a name="lua_getglobal"><code>lua_getglobal</code></a></h3><p>
<span class="apii">[-0, +1, <em>e</em>]</span>
<pre>int lua_getglobal (lua_State *L, const char *name);</pre>

<p>
把全局变量 <name>name</name> 里的值压栈，返回该值的类型。


<hr><h3><a name="lua_geti"><code>lua_geti</code></a></h3><p>
<span class="apii">[-0, +1, <em>e</em>]</span>
<pre>int lua_geti (lua_State *L, int index, lua_Integer i);</pre>

<p>
把 <code>t[i]</code> 的值压栈，
这里的 <code>t</code> 指给定的索引指代的值。
和在 Lua 里一样，这个函数可能会触发 "index" 事件的元方法
（参见 <a href="#2.4">&sect;2.4</a>）。


<p>
返回压入值的类型。


<hr><h3><a name="lua_getmetatable"><code>lua_getmetatable</code></a></h3><p>
<span class="apii">[-0, +(0|1), &ndash;]</span>
<pre>int lua_getmetatable (lua_State *L, int index);</pre>

<p>
如果该索引处的值有元表，则将其元表压栈，返回 1 。
否则不会将任何东西入栈，返回 0 。


<hr><h3><a name="lua_gettable"><code>lua_gettable</code></a></h3><p>
<span class="apii">[-1, +1, <em>e</em>]</span>
<pre>int lua_gettable (lua_State *L, int index);</pre>

<p>
把 <code>t[k]</code> 的值压栈，
这里的 <code>t</code> 是指索引指向的值，
而 <code>k</code> 则是栈顶放的值。


<p>
这个函数会弹出堆栈上的键，把结果放在栈上相同位置。
和在 Lua 中一样，
这个函数可能触发对应 "index" 事件的元方法 
（参见 <a href="#2.4">&sect;2.4</a> ）。


<p>
返回压入值的类型。


<hr><h3><a name="lua_gettop"><code>lua_gettop</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>int lua_gettop (lua_State *L);</pre>

<p>
返回栈顶元素的索引。 
因为索引是从 1 开始编号的，
所以这个结果等于栈上的元素个数；
特别指出，0 表示栈为空。


<hr><h3><a name="lua_getuservalue"><code>lua_getuservalue</code></a></h3><p>
<span class="apii">[-0, +1, &ndash;]</span>
<pre>int lua_getuservalue (lua_State *L, int index);</pre>

<p>
将给定索引处的用户数据所关联的 Lua 值压栈。

<p>
返回压入值的类型。


<hr><h3><a name="lua_insert"><code>lua_insert</code></a></h3><p>
<span class="apii">[-1, +1, &ndash;]</span>
<pre>void lua_insert (lua_State *L, int index);</pre>

<p>
把栈顶元素移动到指定的有效索引处，
依次移动这个索引之上的元素。
不要用伪索引来调用这个函数，
因为伪索引没有真正指向栈上的位置。


<hr><h3><a name="lua_Integer"><code>lua_Integer</code></a></h3>
<pre>typedef ... lua_Integer;</pre>

<p>
Lua 中的整数类型。


<p>
缺省时，这个就是 <code>long long</code>，
（通常是一个 64 位以二为补码的整数），
也可以修改它为 <code>long</code> 或 <code>int</code>
（通常是一个 32 位以二为补码的整数）。
（参见 <code>luaconf.h</code> 中的 <code>LUA_INT</code> 。）

<p>
Lua 定义了两个常量：
<a name="pdf-LUA_MININTEGER"><code>LUA_MININTEGER</code></a> 和
<a name="pdf-LUA_MAXINTEGER"><code>LUA_MAXINTEGER</code></a>
来表示这个类型可以表示的最小和最大值。


<hr><h3><a name="lua_isboolean"><code>lua_isboolean</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>int lua_isboolean (lua_State *L, int index);</pre>

<p>
当给定索引的值是一个布尔量时，返回 1 ，否则返回 0 。


<hr><h3><a name="lua_iscfunction"><code>lua_iscfunction</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>int lua_iscfunction (lua_State *L, int index);</pre>

<p>
当给定索引的值是一个 C 函数时，返回 1 ，否则返回 0 。


<hr><h3><a name="lua_isfunction"><code>lua_isfunction</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>int lua_isfunction (lua_State *L, int index);</pre>

<p>
当给定索引的值是一个函数（ C 或 Lua 函数均可）时，返回 1 ，否则返回 0 。


<hr><h3><a name="lua_isinteger"><code>lua_isinteger</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>int lua_isinteger (lua_State *L, int index);</pre>

<p>
当给定索引的值是一个整数
（其值是一个数字，且内部以整数储存），
时，返回 1 ，否则返回 0 。


<hr><h3><a name="lua_islightuserdata"><code>lua_islightuserdata</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>int lua_islightuserdata (lua_State *L, int index);</pre>

<p>
当给定索引的值是一个轻量用户数据时，返回 1 ，否则返回 0 。


<hr><h3><a name="lua_isnil"><code>lua_isnil</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>int lua_isnil (lua_State *L, int index);</pre>

<p>
当给定索引的值是 <b>nil</b> 时，返回 1 ，否则返回 0 。


<hr><h3><a name="lua_isnone"><code>lua_isnone</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>int lua_isnone (lua_State *L, int index);</pre>

<p>
当给定索引无效时，返回 1 ，否则返回 0 。


<hr><h3><a name="lua_isnoneornil"><code>lua_isnoneornil</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>int lua_isnoneornil (lua_State *L, int index);</pre>

<p>
当给定索引无效或其值是 <b>nil</b> 时，
返回 1 ，否则返回 0 。


<hr><h3><a name="lua_isnumber"><code>lua_isnumber</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>int lua_isnumber (lua_State *L, int index);</pre>

<p>
当给定索引的值是一个数字，或是一个可转换为数字的字符串时，返回 1 ，否则返回 0 。


<hr><h3><a name="lua_isstring"><code>lua_isstring</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>int lua_isstring (lua_State *L, int index);</pre>

<p>
当给定索引的值是一个字符串或是一个数字
（数字总能转换成字符串）时，返回 1 ，否则返回 0 。


<hr><h3><a name="lua_istable"><code>lua_istable</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>int lua_istable (lua_State *L, int index);</pre>

<p>
当给定索引的值是一张表时，返回 1 ，否则返回 0 。


<hr><h3><a name="lua_isthread"><code>lua_isthread</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>int lua_isthread (lua_State *L, int index);</pre>

<p>
当给定索引的值是一条线程时，返回 1 ，否则返回 0 。


<hr><h3><a name="lua_isuserdata"><code>lua_isuserdata</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>int lua_isuserdata (lua_State *L, int index);</pre>

<p>
当给定索引的值是一个用户数据（无论是完全的还是轻量的）时，
返回 1 ，否则返回 0 。


<hr><h3><a name="lua_isyieldable"><code>lua_isyieldable</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>int lua_isyieldable (lua_State *L);</pre>

<p>
如果给定的协程可以让出，返回 1 ，否则返回 0 。


<hr><h3><a name="lua_KContext"><code>lua_KContext</code></a></h3>
<pre>typedef ... lua_KContext;</pre>

<p>
延续函数上下文参数的类型。
这一定是一个数字类型。
当有 <code>intptr_t</code> 时，被定义为 <code>intptr_t</code> ，
因此它也可以保存指针。
否则，它被定义为 <code>ptrdiff_t</code>。


<hr><h3><a name="lua_KFunction"><code>lua_KFunction</code></a></h3>
<pre>typedef int (*lua_KFunction) (lua_State *L, int status, lua_KContext ctx);</pre>

<p>
延续函数的类型（参见 <a href="#4.7">&sect;4.7</a> ）。


<hr><h3><a name="lua_len"><code>lua_len</code></a></h3><p>
<span class="apii">[-0, +1, <em>e</em>]</span>
<pre>void lua_len (lua_State *L, int index);</pre>

<p>
返回给定索引的值的长度。
它等价于 Lua 中的 '<code>#</code>' 操作符
（参见 <a href="#3.4.7">&sect;3.4.7</a>）。
它有可能触发 "length" 事件对应的元方法
（参见 <a href="#2.4">&sect;2.4</a> ）。
结果压栈。


<hr><h3><a name="lua_load"><code>lua_load</code></a></h3><p>
<span class="apii">[-0, +1, &ndash;]</span>
<pre>int lua_load (lua_State *L,
              lua_Reader reader,
              void *data,
              const char *chunkname,
              const char *mode);</pre>

<p>
加载一段 Lua 代码块，但不运行它。
如果没有错误，
<code>lua_load</code> 把一个编译好的代码块作为一个 Lua 函数压到栈顶。
否则，压入错误消息。


<p>
<code>lua_load</code> 的返回值可以是：

<ul>

<li><b><a href="#pdf-LUA_OK"><code>LUA_OK</code></a>: </b> 没有错误；</li>

<li><b><a name="pdf-LUA_ERRSYNTAX"><code>LUA_ERRSYNTAX</code></a>: </b>
在预编译时碰到语法错误；</li>

<li><b><a href="#pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>: </b>
内存分配错误；</li>

<li><b><a href="#pdf-LUA_ERRGCMM"><code>LUA_ERRGCMM</code></a>: </b>
在运行 <code>__gc</code> 元方法时出错了。
（这个错误和代码块加载过程无关，它是由垃圾收集器引发的。）
</li>

</ul>

<p>
<code>lua_load</code> 函数使用一个用户提供的 <code>reader</code>
函数来读取代码块（参见 <a href="#lua_Reader"><code>lua_Reader</code></a> ）。
<code>data</code> 参数会被传入 <code>reader</code> 函数。


<p>
<code>chunkname</code> 这个参数可以赋予代码块一个名字，
这个名字被用于出错信息和调试信息（参见  <a href="#4.9">&sect;4.9</a>）。


<p>
<code>lua_load</code> 会自动检测代码块是文本的还是二进制的，
然后做对应的加载操作（参见程序 <code>luac</code> ）。
字符串 <code>mode</code> 的作用和函数 <a href="#pdf-load"><code>load</code></a> 一致。
它还可以是 <code>NULL</code> 等价于字符串 "<code>bt</code>"。


<p>
<code>lua_load</code> 的内部会使用栈，
因此 reader 函数必须永远在每次返回时保留栈的原样。


<p>
如果返回的函数有上值，
第一个上值会被设置为
保存在注册表（参见 <a href="#4.5">&sect;4.5</a>）
<code>LUA_RIDX_GLOBALS</code> 索引处的全局环境。
在加载主代码块时，这个上值是 <code>_ENV</code> 变量（参见 <a href="#2.2">&sect;2.2</a>）。
其它上值均被初始化为 <b>nil</b>。


<hr><h3><a name="lua_newstate"><code>lua_newstate</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>lua_State *lua_newstate (lua_Alloc f, void *ud);</pre>

<p>
创建一个运行在新的独立的状态机中的线程。
如果无法创建线程或状态机（由于内存有限）则返回 <code>NULL</code>。
参数 <code>f</code> 是一个分配器函数； 
Lua 将通过这个函数做状态机内所有的内存分配操作。
第二个参数 <code>ud</code> ，这个指针将在每次调用分配器时被转入。


<hr><h3><a name="lua_newtable"><code>lua_newtable</code></a></h3><p>
<span class="apii">[-0, +1, <em>e</em>]</span>
<pre>void lua_newtable (lua_State *L);</pre>

<p>
创建一张空表，并将其压栈。
它等价于 <code>lua_createtable(L, 0, 0)</code> 。


<hr><h3><a name="lua_newthread"><code>lua_newthread</code></a></h3><p>
<span class="apii">[-0, +1, <em>e</em>]</span>
<pre>lua_State *lua_newthread (lua_State *L);</pre>

<p>
创建一条新线程，并将其压栈，
并返回维护这个线程的 <a href="#lua_State"><code>lua_State</code></a> 指针。
这个函数返回的新线程共享原线程的全局环境， 但是它有独立的运行栈。


<p>
没有显式的函数可以用来关闭或销毁掉一个线程。
线程跟其它 Lua 对象一样是垃圾收集的条目之一。


<hr><h3><a name="lua_newuserdata"><code>lua_newuserdata</code></a></h3><p>
<span class="apii">[-0, +1, <em>e</em>]</span>
<pre>void *lua_newuserdata (lua_State *L, size_t size);</pre>

<p>
这个函数分配一块指定大小的内存块，
把内存块地址作为一个完全用户数据压栈，
并返回这个地址。

宿主程序可以随意使用这块内存。


<hr><h3><a name="lua_next"><code>lua_next</code></a></h3><p>
<span class="apii">[-1, +(2|0), <em>e</em>]</span>
<pre>int lua_next (lua_State *L, int index);</pre>

<p>
从栈顶弹出一个键，
然后把索引指定的表中的一个键值对压栈 （弹出的键之后的 “下一” 对）。
如果表中以无更多元素，
那么 <a href="#lua_next"><code>lua_next</code></a> 将返回 0 （什么也不压栈）。


<p>
典型的遍历方法是这样的：

<pre>
     /*  表放在索引 't' 处 */
     lua_pushnil(L);  /* 第一个键 */
     while (lua_next(L, t) != 0) {
       /* 使用 '键' （在索引 -2 处） 和 '值' （在索引 -1 处）*/
       printf("%s - %s\n",
              lua_typename(L, lua_type(L, -2)),
              lua_typename(L, lua_type(L, -1)));
       /* 移除 '值' ；保留 '键' 做下一次迭代 */
       lua_pop(L, 1);
     }
</pre>

<p>
在遍历一张表的时候，
不要直接对键调用 <a href="#lua_tolstring"><code>lua_tolstring</code></a> ，
除非你知道这个键一定是一个字符串。
调用 <a href="#lua_tolstring"><code>lua_tolstring</code></a> 有可能改变给定索引位置的值；
这会对下一次调用 <a href="#lua_next"><code>lua_next</code></a> 造成影响。


<p>
关于迭代过程中修改被迭代的表的注意事项参见 <a href="#pdf-next"><code>next</code></a> 函数。


<hr><h3><a name="lua_Number"><code>lua_Number</code></a></h3>
<pre>typedef double lua_Number;</pre>

<p>
Lua 中浮点数的类型。


<p>
Lua 中数字的类型。缺省是 double ，但是你可以改成 float 。
（参见 <code>luaconf.h</code> 中的 <code>LUA_REAL</code> 。）


<hr><h3><a name="lua_numbertointeger"><code>lua_numbertointeger</code></a></h3>
<pre>int lua_numbertointeger (lua_Number n, lua_Integer *p);</pre>

<p>
将一个 Lua 浮点数转换为一个 Lua 整数。
这个宏假设 <code>n</code> 有对应的整数值。
如果该值在 Lua 整数可表示范围内，
就将其转换为一个整数赋给 <code>*p</code>。
宏的结果是一个布尔量，表示转换是否成功。
（注意、由于圆整关系，这个范围测试不用此宏很难做对。）


<p>
该宏有可能对其参数做多次取值。


<hr><h3><a name="lua_pcall"><code>lua_pcall</code></a></h3><p>
<span class="apii">[-(nargs + 1), +(nresults|1), &ndash;]</span>
<pre>int lua_pcall (lua_State *L, int nargs, int nresults, int msgh);</pre>

<p>
以保护模式调用一个函数。


<p>
<code>nargs</code> 和 <code>nresults</code> 的含义与 <a href="#lua_call"><code>lua_call</code></a> 中的相同。
如果在调用过程中没有发生错误，
<a href="#lua_pcall"><code>lua_pcall</code></a> 的行为和 <a href="#lua_call"><code>lua_call</code></a> 完全一致。 
但是，如果有错误发生的话，
<a href="#lua_pcall"><code>lua_pcall</code></a> 会捕获它，
然后把唯一的值（错误消息）压栈，然后返回错误码。 
同 <a href="#lua_call"><code>lua_call</code></a> 一样，
<a href="#lua_pcall"><code>lua_pcall</code></a> 总是把函数本身和它的参数从栈上移除。


<p>
如果 <code>msgh</code> 是 0 ，
返回在栈顶的错误消息就和原始错误消息完全一致。
否则， <code>msgh</code> 就被当成是 <em>错误处理函数</em> 在栈上的索引位置。 
（在当前的实现里，这个索引不能是伪索引。）
在发生运行时错误时，
这个函数会被调用而参数就是错误消息。
错误处理函数的返回值将被 <a href="#lua_pcall"><code>lua_pcall</code></a>
作为错误消息返回在堆栈上。

<p>
典型的用法中，错误处理函数被用来给错误消息加上更多的调试信息，
比如栈跟踪信息。
这些信息在 <a href="#lua_pcall"><code>lua_pcall</code></a> 返回后，
由于栈已经展开，所以收集不到了。

<p>
<a href="#lua_pcall"><code>lua_pcall</code></a> 函数会返回下列常数
（定义在 <code>lua.h</code> 内）中的一个：

<ul>

<li><b><a name="pdf-LUA_OK"><code>LUA_OK</code></a> (0): </b>
成功。</li>

<li><b><a name="pdf-LUA_ERRRUN"><code>LUA_ERRRUN</code></a>: </b>
运行时错误。
</li>

<li><b><a name="pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>: </b>
内存分配错误。对于这种错，Lua 不会调用错误处理函数。
</li>

<li><b><a name="pdf-LUA_ERRERR"><code>LUA_ERRERR</code></a>: </b>
在运行错误处理函数时发生的错误。
</li>

<li><b><a name="pdf-LUA_ERRGCMM"><code>LUA_ERRGCMM</code></a>: </b>
在运行 <code>__gc</code> 元方法时发生的错误。
（这个错误和被调用的函数无关。）
</li>

</ul>


<hr><h3><a name="lua_pcallk"><code>lua_pcallk</code></a></h3><p>
<span class="apii">[-(nargs + 1), +(nresults|1), &ndash;]</span>
<pre>int lua_pcallk (lua_State *L,
                int nargs,
                int nresults,
                int msgh,
                lua_KContext ctx,
                lua_KFunction k);</pre>

<p>
这个函数的行为和 <a href="#lua_pcall"><code>lua_pcall</code></a>
完全一致，只不过它还允许被调用的函数让出
（参见 <a href="#4.7">&sect;4.7</a>）。


<hr><h3><a name="lua_pop"><code>lua_pop</code></a></h3><p>
<span class="apii">[-n, +0, &ndash;]</span>
<pre>void lua_pop (lua_State *L, int n);</pre>

<p>
从栈中弹出 <code>n</code> 个元素。


<hr><h3><a name="lua_pushboolean"><code>lua_pushboolean</code></a></h3><p>
<span class="apii">[-0, +1, &ndash;]</span>
<pre>void lua_pushboolean (lua_State *L, int b);</pre>

<p>
把 <code>b</code> 作为一个布尔量压栈。


<hr><h3><a name="lua_pushcclosure"><code>lua_pushcclosure</code></a></h3><p>
<span class="apii">[-n, +1, <em>e</em>]</span>
<pre>void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);</pre>

<p>
把一个新的 C 闭包压栈。

<p>
当创建了一个 C 函数后，
你可以给它关联一些值，
这就是在创建一个 C 闭包（参见 <a href="#4.4">&sect;4.4</a>）；
接下来无论函数何时被调用，这些值都可以被这个函数访问到。
为了将一些值关联到一个 C 函数上，
首先这些值需要先被压入堆栈（如果有多个值，第一个先压）。
接下来调用 <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>
来创建出闭包并把这个 C 函数压到栈上。
参数 <code>n</code> 告之函数有多少个值需要关联到函数上。
<a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> 也会把这些值从栈上弹出。


<p>
<code>n</code> 的最大值是 255 。


<p>
当 <code>n</code> 为零时，
这个函数将创建出一个 <em>轻量 C 函数</em>，
它就是一个指向 C 函数的指针。
这种情况下，不可能抛出内存错误。


<hr><h3><a name="lua_pushcfunction"><code>lua_pushcfunction</code></a></h3><p>
<span class="apii">[-0, +1, &ndash;]</span>
<pre>void lua_pushcfunction (lua_State *L, lua_CFunction f);</pre>

<p>
将一个 C 函数压栈。 
这个函数接收一个 C 函数指针，
并将一个类型为 <code>function</code> 的 Lua 值压栈。
当这个栈顶的值被调用时，将触发对应的 C 函数。


<p>
注册到 Lua 中的任何函数都必须遵循正确的协议来接收参数和返回值
（参见 <a href="#lua_CFunction"><code>lua_CFunction</code></a> ）。


<p>
<code>lua_pushcfunction</code> 是作为一个宏定义出现的：

<pre>
     #define lua_pushcfunction(L,f)  lua_pushcclosure(L,f,0)
</pre>


<hr><h3><a name="lua_pushfstring"><code>lua_pushfstring</code></a></h3><p>
<span class="apii">[-0, +1, <em>e</em>]</span>
<pre>const char *lua_pushfstring (lua_State *L, const char *fmt, ...);</pre>

<p>
把一个格式化过的字符串压栈，
然后返回这个字符串的指针。 
它和 C 函数 <code>sprintf</code> 比较像，
不过有一些重要的区别：

<ul>

<li>
你不需要为结果分配空间：
其结果是一个 Lua 字符串，由 Lua 来关心其内存分配 （同时通过垃圾收集来释放内存）。
</li>

<li>
这个转换非常的受限。
不支持符号、宽度、精度。
转换符只支持
'<code>%%</code>' （插入一个字符 '<code>%</code>'），
'<code>%s</code>' （插入一个带零终止符的字符串，没有长度限制）,
'<code>%f</code>' （插入一个 <a href="#lua_Number"><code>lua_Number</code></a>），
'<code>%I</code>' （插入一个 <a href="#lua_Integer"><code>lua_Integer</code></a>），
'<code>%p</code>' （插入一个指针或是一个十六进制数），
'<code>%d</code>' （插入一个 <code>int</code>），
'<code>%c</code>' （插入一个用 <code>int</code> 表示的单字节字符），以及
'<code>%U</code>' （插入一个用 <code>long int</code> 表示的 UTF-8 字）。
</li>

</ul>


<hr><h3><a name="lua_pushglobaltable"><code>lua_pushglobaltable</code></a></h3><p>
<span class="apii">[-0, +1, &ndash;]</span>
<pre>void lua_pushglobaltable (lua_State *L);</pre>

<p>
将全局环境压栈。


<hr><h3><a name="lua_pushinteger"><code>lua_pushinteger</code></a></h3><p>
<span class="apii">[-0, +1, &ndash;]</span>
<pre>void lua_pushinteger (lua_State *L, lua_Integer n);</pre>

<p>
把值为 <code>n</code> 的整数压栈。


<hr><h3><a name="lua_pushlightuserdata"><code>lua_pushlightuserdata</code></a></h3><p>
<span class="apii">[-0, +1, &ndash;]</span>
<pre>void lua_pushlightuserdata (lua_State *L, void *p);</pre>

<p>
把一个轻量用户数据压栈。


<p>
用户数据是保留在 Lua 中的 C 值。
<em>轻量用户数据</em> 表示一个指针 <code>void*</code>。
它是一个像数字一样的值：
你不需要专门创建它，它也没有独立的元表，而且也不会被收集（因为从来不需要创建）。
只要表示的 C 地址相同，两个轻量用户数据就相等。


<hr><h3><a name="lua_pushliteral"><code>lua_pushliteral</code></a></h3><p>
<span class="apii">[-0, +1, <em>e</em>]</span>
<pre>const char *lua_pushliteral (lua_State *L, const char *s);</pre>

<p>
这个宏等价于 <a href="#lua_pushstring"><code>lua_pushstring</code></a>，
区别仅在于只能在 <code>s</code> 是一个字面量时才能用它。
它会自动给出字符串的长度。


<hr><h3><a name="lua_pushlstring"><code>lua_pushlstring</code></a></h3><p>
<span class="apii">[-0, +1, <em>e</em>]</span>
<pre>const char *lua_pushlstring (lua_State *L, const char *s, size_t len);</pre>

<p>
把指针 <code>s</code> 指向的长度为 <code>len</code> 的字符串压栈。
Lua 对这个字符串做一个内部副本（或是复用一个副本），
因此 <code>s</code> 处的内存在函数返回后，可以释放掉或是立刻重用于其它用途。
字符串内可以是任意二进制数据，包括零字符。


<p>
返回内部副本的指针。


<hr><h3><a name="lua_pushnil"><code>lua_pushnil</code></a></h3><p>
<span class="apii">[-0, +1, &ndash;]</span>
<pre>void lua_pushnil (lua_State *L);</pre>

<p>
将空值压栈。


<hr><h3><a name="lua_pushnumber"><code>lua_pushnumber</code></a></h3><p>
<span class="apii">[-0, +1, &ndash;]</span>
<pre>void lua_pushnumber (lua_State *L, lua_Number n);</pre>

<p>
把一个值为 <code>n</code> 的浮点数压栈。


<hr><h3><a name="lua_pushstring"><code>lua_pushstring</code></a></h3><p>
<span class="apii">[-0, +1, <em>e</em>]</span>
<pre>const char *lua_pushstring (lua_State *L, const char *s);</pre>

<p>
将指针 s 指向的零结尾的字符串压栈。Lua 对这个字符串做一个内部副本（或是复用一个副本），
因此 <code>s</code> 处的内存在函数返回后，可以释放掉或是立刻重用于其它用途。


<p>
返回内部副本的指针。


<p>
如果 <code>s</code> 为 <code>NULL</code>，将 <b>nil</b> 压栈并返回 <code>NULL</code>。


<hr><h3><a name="lua_pushthread"><code>lua_pushthread</code></a></h3><p>
<span class="apii">[-0, +1, &ndash;]</span>
<pre>int lua_pushthread (lua_State *L);</pre>

<p>
把 <code>L</code> 表示的线程压栈。
如果这个线程是当前状态机的主线程的话，返回 1 。


<hr><h3><a name="lua_pushvalue"><code>lua_pushvalue</code></a></h3><p>
<span class="apii">[-0, +1, &ndash;]</span>
<pre>void lua_pushvalue (lua_State *L, int index);</pre>

<p>
把栈上给定索引处的元素作一个副本压栈。


<hr><h3><a name="lua_pushvfstring"><code>lua_pushvfstring</code></a></h3><p>
<span class="apii">[-0, +1, <em>e</em>]</span>
<pre>const char *lua_pushvfstring (lua_State *L,
                              const char *fmt,
                              va_list argp);</pre>

<p>
等价于 <a href="#lua_pushfstring"><code>lua_pushfstring</code></a> ，
不过是用 <code>va_list</code> 接收参数，而不是用可变数量的实际参数。


<hr><h3><a name="lua_rawequal"><code>lua_rawequal</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>int lua_rawequal (lua_State *L, int index1, int index2);</pre>

<p>
如果索引 <code>index1</code> 与索引 <code>index2</code> 处的值
本身相等（即不调用元方法），返回 1 。
否则返回 0 。
当任何一个索引无效时，也返回 0 。


<hr><h3><a name="lua_rawget"><code>lua_rawget</code></a></h3><p>
<span class="apii">[-1, +1, &ndash;]</span>
<pre>int lua_rawget (lua_State *L, int index);</pre>

<p>
类似于 <a href="#lua_gettable"><code>lua_gettable</code></a> ，
但是作一次直接访问（不触发元方法）。


<hr><h3><a name="lua_rawgeti"><code>lua_rawgeti</code></a></h3><p>
<span class="apii">[-0, +1, &ndash;]</span>
<pre>int lua_rawgeti (lua_State *L, int index, lua_Integer n);</pre>

<p>
把 <code>t[n]</code> 的值压栈，
这里的 <code>t</code> 是指给定索引处的表。
这是一次直接访问；就是说，它不会触发元方法。


<p>
返回入栈值的类型。


<hr><h3><a name="lua_rawgetp"><code>lua_rawgetp</code></a></h3><p>
<span class="apii">[-0, +1, &ndash;]</span>
<pre>int lua_rawgetp (lua_State *L, int index, const void *p);</pre>

<p>
把 <code>t[k]</code> 的值压栈，
这里的 <code>t</code> 是指给定索引处的表，
<code>k</code> 是指针 <code>p</code> 对应的轻量用户数据。
这是一次直接访问；就是说，它不会触发元方法。


<p>
返回入栈值的类型。


<hr><h3><a name="lua_rawlen"><code>lua_rawlen</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>size_t lua_rawlen (lua_State *L, int index);</pre>

<p>
返回给定索引处值的固有“长度”：
对于字符串，它指字符串的长度；
对于表；它指不触发元方法的情况下取长度操作（'<code>#</code>'）应得到的值；
对于用户数据，它指为该用户数据分配的内存块的大小；
对于其它值，它为 0 。


<hr><h3><a name="lua_rawset"><code>lua_rawset</code></a></h3><p>
<span class="apii">[-2, +0, <em>e</em>]</span>
<pre>void lua_rawset (lua_State *L, int index);</pre>

<p>
类似于 <a href="#lua_settable"><code>lua_settable</code></a> ，
但是是做一次直接赋值（不触发元方法）。


<hr><h3><a name="lua_rawseti"><code>lua_rawseti</code></a></h3><p>
<span class="apii">[-1, +0, <em>e</em>]</span>
<pre>void lua_rawseti (lua_State *L, int index, lua_Integer i);</pre>

<p>
等价于 <code>t[i] = v</code> ，
这里的 <code>t</code> 是指给定索引处的表，
而 <code>v</code> 是栈顶的值。

<p>
这个函数会将值弹出栈。
赋值是直接的；即不会触发元方法。


<hr><h3><a name="lua_rawsetp"><code>lua_rawsetp</code></a></h3><p>
<span class="apii">[-1, +0, <em>e</em>]</span>
<pre>void lua_rawsetp (lua_State *L, int index, const void *p);</pre>

<p>
等价于 <code>t[k] = v</code> ，
这里的 <code>t</code> 是指给定索引处的表，
<code>k</code> 是指针 <code>p</code> 对应的轻量用户数据。
而 <code>v</code> 是栈顶的值。


<p>
这个函数会将值弹出栈。
赋值是直接的；即不会触发元方法。


<hr><h3><a name="lua_Reader"><code>lua_Reader</code></a></h3>
<pre>typedef const char * (*lua_Reader) (lua_State *L,
                                    void *data,
                                    size_t *size);</pre>

<p>
<a href="#lua_load"><code>lua_load</code></a> 用到的读取器函数，
每次它需要一块新的代码块的时候，
<a href="#lua_load"><code>lua_load</code></a> 就调用读取器，
每次都会传入一个参数 <code>data</code> 。
读取器需要返回含有新的代码块的一块内存的指针，
并把 <code>size</code> 设为这块内存的大小。
内存块必须在下一次函数被调用之前一直存在。
读取器可以通过返回 <code>NULL</code> 或设 <code>size</code> 为 0 来指示代码块结束。
读取器可能返回多个块，每个块可以有任意的大于零的尺寸。


<hr><h3><a name="lua_register"><code>lua_register</code></a></h3><p>
<span class="apii">[-0, +0, <em>e</em>]</span>
<pre>void lua_register (lua_State *L, const char *name, lua_CFunction f);</pre>

<p>
把 C 函数 <code>f</code> 设到全局变量 <code>name</code> 中。
它通过一个宏定义：

<pre>
     #define lua_register(L,n,f) \
            (lua_pushcfunction(L, f), lua_setglobal(L, n))
</pre>


<hr><h3><a name="lua_remove"><code>lua_remove</code></a></h3><p>
<span class="apii">[-1, +0, &ndash;]</span>
<pre>void lua_remove (lua_State *L, int index);</pre>

<p>
从给定有效索引处移除一个元素，
把这个索引之上的所有元素移下来填补上这个空隙。
不能用伪索引来调用这个函数，因为伪索引并不指向真实的栈上的位置。


<hr><h3><a name="lua_replace"><code>lua_replace</code></a></h3><p>
<span class="apii">[-1, +0, &ndash;]</span>
<pre>void lua_replace (lua_State *L, int index);</pre>

<p>
把栈顶元素放置到给定位置而不移动其它元素
（因此覆盖了那个位置处的值），然后将栈顶元素弹出。


<hr><h3><a name="lua_resume"><code>lua_resume</code></a></h3><p>
<span class="apii">[-?, +?, &ndash;]</span>
<pre>int lua_resume (lua_State *L, lua_State *from, int nargs);</pre>

<p>
在给定线程中启动或延续一条协程 。


<p>
要启动一个协程的话，
你需要把主函数以及它需要的参数压入线程栈；
然后调用 <a href="#lua_resume"><code>lua_resume</code></a> ，
把 <code>nargs</code> 设为参数的个数。
这次调用会在协程挂起时或是结束运行后返回。
当函数返回时，堆栈中会有传给 <a href="#lua_yield"><code>lua_yield</code></a> 的所有值，
或是主函数的所有返回值。
当协程让出， <a href="#lua_resume"><code>lua_resume</code></a>
返回 <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> ，
若协程结束运行且没有任何错误时，返回 0 。
如果有错则返回错误代码（参见 <a href="#lua_pcall"><code>lua_pcall</code></a> ）。


<p>
在发生错误的情况下，
堆栈没有展开，
因此你可以使用调试 API 来处理它。
错误消息放在栈顶。


<p>
要延续一个协程，
你需要清除上次 <a href="#lua_yield"><code>lua_yield</code></a> 遗留下的所有结果，
你把需要传给 <code>yield</code> 作结果的值压栈，
然后调用 <a href="#lua_resume"><code>lua_resume</code></a> 。

<p>
参数 <code>from</code> 表示协程从哪个协程中来延续 <code>L</code> 的。
如果不存在这样一个协程，这个参数可以是 <code>NULL</code> 。


<hr><h3><a name="lua_rotate"><code>lua_rotate</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>void lua_rotate (lua_State *L, int idx, int n);</pre>

<p>
把从 <code>idx</code> 开始到栈顶的元素轮转 <code>n</code> 个位置。
对于 <code>n</code> 为正数时，轮转方向是向栈顶的；
当 <code>n</code> 为负数时，向栈底方向轮转 <code>-n</code> 个位置。
<code>n</code> 的绝对值不可以比参于轮转的切片长度大。


<hr><h3><a name="lua_setallocf"><code>lua_setallocf</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);</pre>

<p>
把指定状态机的分配器函数换成带上用户数据 <code>ud</code> 的 <code>f</code> 。


<hr><h3><a name="lua_setfield"><code>lua_setfield</code></a></h3><p>
<span class="apii">[-1, +0, <em>e</em>]</span>
<pre>void lua_setfield (lua_State *L, int index, const char *k);</pre>

<p>
做一个等价于 <code>t[k] = v</code> 的操作，
这里 <code>t</code> 是给出的索引处的值，
而 <code>v</code> 是栈顶的那个值。


<p>
这个函数将把这个值弹出栈。
跟在 Lua 中一样，这个函数可能触发一个 "newindex" 事件的元方法
（参见 <a href="#2.4">&sect;2.4</a>）。


<hr><h3><a name="lua_setglobal"><code>lua_setglobal</code></a></h3><p>
<span class="apii">[-1, +0, <em>e</em>]</span>
<pre>void lua_setglobal (lua_State *L, const char *name);</pre>

<p>
从堆栈上弹出一个值，并将其设为全局变量 <code>name</code> 的新值。


<hr><h3><a name="lua_seti"><code>lua_seti</code></a></h3><p>
<span class="apii">[-1, +0, <em>e</em>]</span>
<pre>void lua_seti (lua_State *L, int index, lua_Integer n);</pre>

<p>
做一个等价于 <code>t[n] = v</code> 的操作，
这里 <code>t</code> 是给出的索引处的值，
而 <code>v</code> 是栈顶的那个值。


<p>
这个函数将把这个值弹出栈。
跟在 Lua 中一样，这个函数可能触发一个 "newindex" 事件的元方法
（参见 <a href="#2.4">&sect;2.4</a>）。


<hr><h3><a name="lua_setmetatable"><code>lua_setmetatable</code></a></h3><p>
<span class="apii">[-1, +0, &ndash;]</span>
<pre>void lua_setmetatable (lua_State *L, int index);</pre>

<p>
把一张表弹出栈，并将其设为给定索引处的值的元表。


<hr><h3><a name="lua_settable"><code>lua_settable</code></a></h3><p>
<span class="apii">[-2, +0, <em>e</em>]</span>
<pre>void lua_settable (lua_State *L, int index);</pre>

<p>
做一个等价于 <code>t[k] = v</code> 的操作，
这里 <code>t</code> 是给出的索引处的值，
<code>v</code> 是栈顶的那个值，
<code>k</code> 是栈顶之下的值。

<p>
这个函数会将键和值都弹出栈。
跟在 Lua 中一样，这个函数可能触发一个 "newindex" 事件的元方法
（参见 <a href="#2.4">&sect;2.4</a>）。


<hr><h3><a name="lua_settop"><code>lua_settop</code></a></h3><p>
<span class="apii">[-?, +?, &ndash;]</span>
<pre>void lua_settop (lua_State *L, int index);</pre>

<p>
参数允许传入任何索引以及 0 。
它将把堆栈的栈顶设为这个索引。
如果新的栈顶比原来的大，
超出部分的新元素将被填为 <b>nil</b> 。
如果 <code>index</code> 为 0 ，
把栈上所有元素移除。


<hr><h3><a name="lua_setuservalue"><code>lua_setuservalue</code></a></h3><p>
<span class="apii">[-1, +0, &ndash;]</span>
<pre>void lua_setuservalue (lua_State *L, int index);</pre>

<p>
从栈上弹出一个值并将其设为给定索引处用户数据的关联值。


<hr><h3><a name="lua_State"><code>lua_State</code></a></h3>
<pre>typedef struct lua_State lua_State;</pre>

<p>
一个不透明的结构，
它指向一条线程并间接（通过该线程）引用了整个 Lua 解释器的状态。
Lua 库是完全可重入的：
它没有任何全局变量。
状态机所有的信息都可以通过这个结构访问到。

<p>
这个结构的指针必须作为第一个参数传递给每一个库函数。
<a href="#lua_newstate"><code>lua_newstate</code></a> 是一个例外，
这个函数会从头创建一个 Lua 状态机。


<hr><h3><a name="lua_status"><code>lua_status</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>int lua_status (lua_State *L);</pre>

<p>
返回线程 <code>L</code> 的状态。


<p>
正常的线程状态是 0 （<a href="#pdf-LUA_OK"><code>LUA_OK</code></a>）。
当线程用 <a href="#lua_resume"><code>lua_resume</code></a> 执行完毕并抛出了一个错误时，
状态值是错误码。
如果线程被挂起，状态为 <a name="pdf-LUA_YIELD"><code>LUA_YIELD</code></a> 。


<p>
你只能在状态为 <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> 的线程中调用函数。
你可以延续一个状态为 <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> 的线程
（用于开始新协程）或是状态为 <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> 的线程
（用于延续协程）。


<hr><h3><a name="lua_stringtonumber"><code>lua_stringtonumber</code></a></h3><p>
<span class="apii">[-0, +1, &ndash;]</span>
<pre>size_t lua_stringtonumber (lua_State *L, const char *s);</pre>

<p>
将一个零结尾的字符串 <code>s</code> 转换为一个数字，
将这个数字压栈，并返回字符串的总长度（即长度加一）。
转换的结果可能是整数也可能是浮点数，
这取决于 Lua 的转换语法（参见 <a href="#3.1">&sect;3.1</a>）。
这个字符串可以有前置和后置的空格以及符号。
如果字符串并非一个有效的数字，返回 0 并不把任何东西压栈。
（注意，这个结果可以当成一个布尔量使用，为真即转换成功。）


<hr><h3><a name="lua_toboolean"><code>lua_toboolean</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>int lua_toboolean (lua_State *L, int index);</pre>

<p>
把给定索引处的 Lua 值转换为一个 C 中的布尔量（ 0 或是 1 ）。
和 Lua 中做的所有测试一样， 
<a href="#lua_toboolean"><code>lua_toboolean</code></a> 
会把任何不同于 <b>false</b> 和 <b>nil</b> 的值当作真返回；
否则就返回假。
（如果你想只接收真正的 boolean 值，
就需要使用 <a href="#lua_isboolean"><code>lua_isboolean</code></a> 来测试值的类型。）


<hr><h3><a name="lua_tocfunction"><code>lua_tocfunction</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>lua_CFunction lua_tocfunction (lua_State *L, int index);</pre>

<p>
把给定索引处的 Lua 值转换为一个 C 函数。
这个值必须是一个 C 函数；
如果不是就返回 <code>NULL</code> 。


<hr><h3><a name="lua_tointeger"><code>lua_tointeger</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>lua_Integer lua_tointeger (lua_State *L, int index);</pre>

<p>
等价于调用 <a href="#lua_tointegerx"><code>lua_tointegerx</code></a>，
其参数 <code>isnum</code> 为 <code>NULL</code>。


<hr><h3><a name="lua_tointegerx"><code>lua_tointegerx</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>lua_Integer lua_tointegerx (lua_State *L, int index, int *isnum);</pre>

<p>
将给定索引处的 Lua 值转换为带符号的整数类型
<a href="#lua_Integer"><code>lua_Integer</code></a>。
这个 Lua 值必须是一个整数，或是一个可以被转换为整数
（参见 <a href="#3.4.3">&sect;3.4.3</a>）的数字或字符串；
否则，<code>lua_tointegerx</code> 返回 0 。


<p>
如果 <code>isnum</code> 不是 <code>NULL</code>，
<code>*isnum</code> 会被设为操作是否成功。


<hr><h3><a name="lua_tolstring"><code>lua_tolstring</code></a></h3><p>
<span class="apii">[-0, +0, <em>e</em>]</span>
<pre>const char *lua_tolstring (lua_State *L, int index, size_t *len);</pre>

<p>
把给定索引处的 Lua 值转换为一个 C 字符串。
如果 <code>len</code> 不为 <code>NULL</code> ，
它还把字符串长度设到 <code>*len</code> 中。
这个 Lua 值必须是一个字符串或是一个数字； 
否则返回 <code>NULL</code> 。
如果值是一个数字， <code>lua_tolstring</code>
还会 <em>把堆栈中的那个值的实际类型转换为一个字符串</em>。
（当遍历一张表的时候，
若把 <code>lua_tolstring</code> 作用在键上，
这个转换有可能导致 <a href="#lua_next"><code>lua_next</code></a> 弄错。）


<p>
<code>lua_tolstring</code> 返回一个已对齐指针
指向 Lua 状态机中的字符串。
这个字符串总能保证 （ C 要求的）最后一个字符为零 ('\0') ，
而且它允许在字符串内包含多个这样的零。 


<p>
因为 Lua 中可能发生垃圾收集，
所以不保证 <code>lua_tolstring</code> 返回的指针，
在对应的值从堆栈中移除后依然有效。


<hr><h3><a name="lua_tonumber"><code>lua_tonumber</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>lua_Number lua_tonumber (lua_State *L, int index);</pre>

<p>
等价于调用 <a href="#lua_tonumberx"><code>lua_tonumberx</code></a>，
其参数 <code>isnum</code> 为 <code>NULL</code>。


<hr><h3><a name="lua_tonumberx"><code>lua_tonumberx</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>lua_Number lua_tonumberx (lua_State *L, int index, int *isnum);</pre>

<p>
把给定索引处的 Lua 值转换为 <a href="#lua_Number"><code>lua_Number</code></a> 这样一个 C 类型
（参见 lua_Number ）。
这个 Lua 值必须是一个数字或是一个可转换为数字的字符串 
（参见 <a href="#3.4.3">&sect;3.4.3</a>）；
否则， <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> 返回 0 。


<p>
如果 <code>isnum</code> 不是 <code>NULL</code>，
<code>*isnum</code> 会被设为操作是否成功。


<hr><h3><a name="lua_topointer"><code>lua_topointer</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>const void *lua_topointer (lua_State *L, int index);</pre>

<p>
把给定索引处的值转换为一般的 C 指针 (<code>void*</code>) 。
这个值可以是一个用户对象，表 ，线程或是一个函数；
否则， <code>lua_topointer</code> 返回 <code>NULL</code> 。
不同的对象有不同的指针。
不存在把指针再转回原有类型的方法。


<p>
这个函数通常只用于调试信息。


<hr><h3><a name="lua_tostring"><code>lua_tostring</code></a></h3><p>
<span class="apii">[-0, +0, <em>e</em>]</span>
<pre>const char *lua_tostring (lua_State *L, int index);</pre>

<p>
等价于调用 <a href="#lua_tolstring"><code>lua_tolstring</code></a> ，
其参数 <code>len</code> 为 <code>NULL</code> 。


<hr><h3><a name="lua_tothread"><code>lua_tothread</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>lua_State *lua_tothread (lua_State *L, int index);</pre>

<p>
把给定索引处的值转换为一个 Lua 线程
（表示为 <code>lua_State*</code>）。
这个值必须是一个线程；
否则函数返回 <code>NULL</code>。


<hr><h3><a name="lua_touserdata"><code>lua_touserdata</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>void *lua_touserdata (lua_State *L, int index);</pre>

<p>
如果给定索引处的值是一个完全用户数据，
函数返回其内存块的地址。
如果值是一个轻量用户数据，
那么就返回它表示的指针。
否则，返回 <code>NULL</code> 。


<hr><h3><a name="lua_type"><code>lua_type</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>int lua_type (lua_State *L, int index);</pre>

<p>
返回给定有效索引处值的类型，
当索引无效（或无法访问）时则返回 <code>LUA_TNONE</code>。
<a href="#lua_type"><code>lua_type</code></a> 返回的类型被编码为一些个在
<code>lua.h</code> 中定义的常量：
<a name="pdf-LUA_TNIL"><code>LUA_TNIL</code></a>，
<a name="pdf-LUA_TNUMBER"><code>LUA_TNUMBER</code></a>，
<a name="pdf-LUA_TBOOLEAN"><code>LUA_TBOOLEAN</code></a>，
<a name="pdf-LUA_TSTRING"><code>LUA_TSTRING</code></a>，
<a name="pdf-LUA_TTABLE"><code>LUA_TTABLE</code></a>，
<a name="pdf-LUA_TFUNCTION"><code>LUA_TFUNCTION</code></a>，
<a name="pdf-LUA_TUSERDATA"><code>LUA_TUSERDATA</code></a>，
<a name="pdf-LUA_TTHREAD"><code>LUA_TTHREAD</code></a>，
<a name="pdf-LUA_TLIGHTUSERDATA"><code>LUA_TLIGHTUSERDATA</code></a>。


<hr><h3><a name="lua_typename"><code>lua_typename</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>const char *lua_typename (lua_State *L, int tp);</pre>

<p>
返回 <code>tp</code> 表示的类型名，
这个 <code>tp</code> 必须是 <a href="#lua_type"><code>lua_type</code></a>
可能返回的值中之一。


<hr><h3><a name="lua_Unsigned"><code>lua_Unsigned</code></a></h3>
<pre>typedef ... lua_Unsigned;</pre>

<p>
<a href="#lua_Integer"><code>lua_Integer</code></a> 的无符号版本。


<hr><h3><a name="lua_upvalueindex"><code>lua_upvalueindex</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>int lua_upvalueindex (int i);</pre>

<p>
返回当前运行的函数（参见 <a href="#4.4">&sect;4.4</a>）的第 <code>i</code> 个上值的伪索引。


<hr><h3><a name="lua_version"><code>lua_version</code></a></h3><p>
<span class="apii">[-0, +0, <em>v</em>]</span>
<pre>const lua_Number *lua_version (lua_State *L);</pre>

<p>
返回保存在 Lua 内核中储存的版本数字的地址。
当调用时传入一个合法的 <a href="#lua_State"><code>lua_State</code></a> ，
返回创建该状态机时的版本地址。
如果用 <code>NULL</code> 调用，
返回调用者的版本地址。


<hr><h3><a name="lua_Writer"><code>lua_Writer</code></a></h3>
<pre>typedef int (*lua_Writer) (lua_State *L,
                           const void* p,
                           size_t sz,
                           void* ud);</pre>

<p>
被 <a href="#lua_dump"><code>lua_dump</code></a> 用到的写入器函数。
每次 <a href="#lua_dump"><code>lua_dump</code></a> 产生了一段新的代码块，
它都会调用写入器。
传入要写入的缓冲区 (<code>p</code>) 和它的尺寸 (<code>sz</code>) ，
以及传给 <a href="#lua_dump"><code>lua_dump</code></a> 的参数 <code>data</code> 。


<p>
写入器会返回一个错误码：
0 表示没有错误； 别的值均表示一个错误，
并且会让 <a href="#lua_dump"><code>lua_dump</code></a> 停止再次调用写入器。


<hr><h3><a name="lua_xmove"><code>lua_xmove</code></a></h3><p>
<span class="apii">[-?, +?, &ndash;]</span>
<pre>void lua_xmove (lua_State *from, lua_State *to, int n);</pre>

<p>
交换同一个状态机下不同线程中的值。


<p>
这个函数会从 <code>from</code> 的栈上弹出 <code>n</code> 个值，
然后把它们压入 <code>to</code> 的栈上。


<hr><h3><a name="lua_yield"><code>lua_yield</code></a></h3><p>
<span class="apii">[-?, +?, <em>e</em>]</span>
<pre>int lua_yield (lua_State *L, int nresults);</pre>

<p>
这个函数等价于调用 <a href="#lua_yieldk"><code>lua_yieldk</code></a>，
不同的是不提供延续函数（参见 <a href="#4.7">&sect;4.7</a>）。
因此，当线程被延续，线程会继续运行调用 <code>lua_yield</code> 函数的函数。


<hr><h3><a name="lua_yieldk"><code>lua_yieldk</code></a></h3><p>
<span class="apii">[-?, +?, <em>e</em>]</span>
<pre>int lua_yieldk (lua_State *L,
                int nresults,
                lua_KContext ctx,
                lua_KFunction k);</pre>

<p>
让出协程（线程）。


<p>
当 C 函数调用了 <a href="#lua_yieldk"><code>lua_yieldk</code></a>，
当前运行的协程会挂起，
启动这个线程的 <a href="#lua_resume"><code>lua_resume</code></a> 调用返回。
参数 <code>nresults</code> 指栈上需返回给
<a href="#lua_resume"><code>lua_resume</code></a> 的返回值的个数。


<p>
当协程再次被延续时，
Lua 调用延续函数 <code>k</code> 继续运行被挂起（参见 <a href="#4.7">&sect;4.7</a>）的 C 函数。
延续函数会从前一个函数中接收到相同的栈，
栈中的 <code>n</code> 个返回值被移除而压入了从
<a href="#lua_resume"><code>lua_resume</code></a> 传入的参数。
此外，延续函数还会收到传给 <a href="#lua_yieldk"><code>lua_yieldk</code></a>
的参数 <code>ctx</code>。


<p>
通常，这个函数不会返回；
当协程一次次延续，将从延续函数继续运行。
然而，有一个例外：
当这个函数从一个逐行运行的钩子函数（参见 <a href="#4.9">&sect;4.9</a>）
中调用时，<code>lua_yieldk</code> 不可以提供延续函数。
（也就是类似 <a href="#lua_yield"><code>lua_yield</code></a> 的形式），
而此时，钩子函数在调用完让出后将立刻返回。
Lua 会使协程让出，一旦协程再次被延续，
触发钩子的函数会继续正常运行。


<p>
当一个线程处于未提供延续函数的 C 调用中，调用它会抛出一个错误。
从并非用延续方式（例如：主线程）启动的线程中调用它也会这样。


<h2>4.9 &ndash; <a name="4.9">调试接口</a></h2>

<p>
Lua 没有内置的调试机制。
但是它提供了一组特殊的函数接口以及 <em>钩子</em>。
这组接口可用于构建出不同的调试器、性能剖析器、
或是其它需要从解释器获取“内部信息”的工具。


<hr><h3><a name="lua_Debug"><code>lua_Debug</code></a></h3>
<pre>typedef struct lua_Debug {
  int event;
  const char *name;           /* (n) */
  const char *namewhat;       /* (n) */
  const char *what;           /* (S) */
  const char *source;         /* (S) */
  int currentline;            /* (l) */
  int linedefined;            /* (S) */
  int lastlinedefined;        /* (S) */
  unsigned char nups;         /* (u) 上值的数量 */
  unsigned char nparams;      /* (u) 参数的数量 */
  char isvararg;              /* (u) */
  char istailcall;            /* (t) */
  char short_src[LUA_IDSIZE]; /* (S) */
  /* 私有部分 */
  <em>其它域</em>
} lua_Debug;</pre>

<p>
这是一个携带有有关函数或活动记录的各种信息的结构。
<a href="#lua_getstack"><code>lua_getstack</code></a> 只会填充结构的私有部分供后面使用。
调用 <a href="#lua_getinfo"><code>lua_getinfo</code></a> 可以在
<a href="#lua_Debug"><code>lua_Debug</code></a> 中填充那些可被使用的信息域。


<p>
下面对 <a href="#lua_Debug"><code>lua_Debug</code></a> 的各个域做一个说明：

<ul>

<li><b><code>source</code>: </b>
创建这个函数的代码块的名字。
如果 <code>source</code> 以 '<code>@</code>' 打头，
指这个函数定义在一个文件中，而 '<code>@</code>' 之后的部分就是文件名。
若 <code>source</code> 以 '<code>=</code>' 打头，
剩余的部分由用户行为来决定如何表示源码。
其它的情况下，这个函数定义在一个字符串中，
而 <code>source</code> 正是那个字符串。
</li>

<li><b><code>short_src</code>: </b>
一个“可打印版本”的 <code>source</code> ，用于出错信息。
</li>

<li><b><code>linedefined</code>: </b>
函数定义开始处的行号。
</li>

<li><b><code>lastlinedefined</code>: </b>
函数定义结束处的行号。
</li>

<li><b><code>what</code>: </b>
如果函数是一个 Lua 函数，则为一个字符串 <code>"Lua"</code> ；
如果是一个 C 函数，则为 <code>"C"</code>；
如果它是一个代码块的主体部分，则为 <code>"main"</code>。
</li>

<li><b><code>currentline</code>: </b>
给定函数正在执行的那一行。 
当提供不了行号信息的时候， <code>currentline</code> 被设为 -1 。
</li>

<li><b><code>name</code>: </b>
给定函数的一个合理的名字。
因为 Lua 中的函数是一等公民，
所以它们没有固定的名字：
一些函数可能是全局复合变量的值，
另一些可能仅仅只是被保存在一张表的某个域中。
<code>lua_getinfo</code> 函数会检查函数是怎样被调用的，
以此来找到一个适合的名字。 
如果它找不到名字，
<code>name</code> 就被设置为 <code>NULL</code> 。
</li>

<li><b><code>namewhat</code>: </b>
用于解释 <code>name</code> 域。
<code>namewhat</code> 的值可以是
<code>"global"</code>, <code>"local"</code>, <code>"method"</code>, <code>"field"</code>, <code>"upvalue"</code>, 或是 <code>""</code> （空串）。
这取决于函数怎样被调用。
（Lua 用空串表示其它选项都不符合。）
</li>

<li><b><code>istailcall</code>: </b>
如果函数以尾调用形式调用，这个值就为真。
在这种情况下，当层的调用者不在栈中。
</li>

<li><b><code>nups</code>: </b>
函数的上值个数。
</li>

<li><b><code>nparams</code>: </b>
函数固定形参个数
（对于 C 函数永远是 0 ）。
</li>

<li><b><code>isvararg</code>: </b>
如果函数是一个可变参数函数则为真
（对于 C 函数永远为真）。
</li>

</ul>


<hr><h3><a name="lua_gethook"><code>lua_gethook</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>lua_Hook lua_gethook (lua_State *L);</pre>

<p>
返回当前的钩子函数。


<hr><h3><a name="lua_gethookcount"><code>lua_gethookcount</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>int lua_gethookcount (lua_State *L);</pre>

<p>
返回当前的钩子计数。


<hr><h3><a name="lua_gethookmask"><code>lua_gethookmask</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>int lua_gethookmask (lua_State *L);</pre>

<p>
返回当前的钩子掩码。


<hr><h3><a name="lua_getinfo"><code>lua_getinfo</code></a></h3><p>
<span class="apii">[-(0|1), +(0|1|2), <em>e</em>]</span>
<pre>int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar);</pre>

<p>
返回一个指定的函数或函数调用的信息。


<p>
当用于取得一次函数调用的信息时，
参数 <code>ar</code> 必须是一个有效的活动的记录。
这条记录可以是前一次调用 <a href="#lua_getstack"><code>lua_getstack</code></a> 得到的，
或是一个钩子 （参见 <a href="#lua_Hook"><code>lua_Hook</code></a> ）得到的参数。


<p>
用于获取一个函数的信息时，
可以把这个函数压入堆栈， 
然后把 <code>what</code> 字符串以字符 '<code>&gt;</code>' 起头。
（这会让 <code>lua_getinfo</code> 从栈顶上弹出函数。）
例如，想知道函数 <code>f</code> 是在哪一行定义的，
你可以使用下列代码：

<pre>
     lua_Debug ar;
     lua_getglobal(L, "f");  /* 取得全局变量 'f' */
     lua_getinfo(L, "&gt;S", &amp;ar);
     printf("%d\n", ar.linedefined);
</pre>

<p>
<code>what</code> 字符串中的每个字符都筛选出结构
<code>ar</code> 结构中一些域用于填充，
或是把一个值压入堆栈：

<ul>

<li><b>'<code>n</code>': </b> 填充 <code>name</code> 及 <code>namewhat</code> 域；
</li>

<li><b>'<code>S</code>': </b>
填充 <code>source</code> ， <code>short_src</code> ， <code>linedefined</code> ， <code>lastlinedefined</code> ，以及 <code>what</code> 域；
</li>

<li><b>'<code>l</code>': </b> 填充 <code>currentline</code> 域；
</li>

<li><b>'<code>t</code>': </b> 填充 <code>istailcall</code> 域；
</li>

<li><b>'<code>u</code>': </b> 填充 <code>nups</code>， <code>nparams</code>，及 <code>isvararg</code> 域；
</li>

<li><b>'<code>f</code>': </b>
把正在运行中指定层次处函数压栈；
</li>

<li><b>'<code>L</code>': </b>
将一张表压栈，这张表中的整数索引用于描述函数中哪些行是有效行。
（<em>有效行</em>指有实际代码的行，即你可以置入断点的行。 无效行包括空行和只有注释的行。）


<p>
如果这个选项和选项 '<code>f</code>' 同时使用，
这张表在函数之后压栈。
</li>

</ul>

<p>
这个函数出错会返回 0 （例如，<code>what</code> 中有一个无效选项）。


<hr><h3><a name="lua_getlocal"><code>lua_getlocal</code></a></h3><p>
<span class="apii">[-0, +(0|1), &ndash;]</span>
<pre>const char *lua_getlocal (lua_State *L, const lua_Debug *ar, int n);</pre>

<p>
从给定活动记录或从一个函数中获取一个局部变量的信息。


<p>
对于第一种情况，
参数 <code>ar</code> 必须是一个有效的活动的记录。 
这条记录可以是前一次调用 <a href="#lua_getstack"><code>lua_getstack</code></a> 得到的，
或是一个钩子 （参见 <a href="#lua_Hook"><code>lua_Hook</code></a> ）的参数。
索引 <code>n</code> 用于选择要检阅哪个局部变量；
参见 <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> 
中关于变量的索引和名字的介绍。


<p>
<a href="#lua_getlocal"><code>lua_getlocal</code></a> 将变量的值压栈，并返回其名字。


<p>
对于第二种情况，<code>ar</code> 必须填 <code>NULL</code> 。
需要探知的函数必须放在栈顶。
对于这种情况，只有 Lua 函数的形参是可见的
（没有关于还有哪些活动变量的信息）
也不会有任何值压栈。


<p>
当索引大于活动的局部变量的数量，
返回 <code>NULL</code> （无任何压栈）


<hr><h3><a name="lua_getstack"><code>lua_getstack</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>int lua_getstack (lua_State *L, int level, lua_Debug *ar);</pre>

<p>
获取解释器的运行时栈的信息。


<p>
这个函数用正在运行中的指定层次处函数的 <em>活动记录</em> 来填写
<a href="#lua_Debug"><code>lua_Debug</code></a> 结构的一部分。
0 层表示当前运行的函数，
<em>n+1</em> 层的函数就是调用第 <em>n</em> 层
（尾调用例外，它不算在栈层次中）
函数的那一个。
如果没有错误， <a href="#lua_getstack"><code>lua_getstack</code></a> 返回 1 ；
当调用传入的层次大于堆栈深度的时候，返回 0 。


<hr><h3><a name="lua_getupvalue"><code>lua_getupvalue</code></a></h3><p>
<span class="apii">[-0, +(0|1), &ndash;]</span>
<pre>const char *lua_getupvalue (lua_State *L, int funcindex, int n);</pre>

<p>
获取一个闭包的上值信息。
（对于 Lua 函数，上值是函数需要使用的外部局部变量，
因此这些变量被包含在闭包中。）
<a href="#lua_getupvalue"><code>lua_getupvalue</code></a> 获取第 <code>n</code> 个上值，
把这个上值的值压栈，
并且返回它的名字。 
<code>funcindex</code> 指向闭包在栈上的位置。
（ 因为上值在整个函数中都有效，所以它们没有特别的次序。
因此，它们以字母次序来编号。）


<p>
当索引号比上值数量大的时候，
返回 <code>NULL</code>（而且不会压入任何东西）。
对于 C 函数，所有上值的名字都是空串 <code>""</code>。


<hr><h3><a name="lua_Hook"><code>lua_Hook</code></a></h3>
<pre>typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar);</pre>

<p>
用于调试的钩子函数类型。


<p>
无论何时钩子被调用，它的参数 <code>ar</code> 
中的 <code>event</code> 域都被设为触发钩子的事件。
Lua 把这些事件定义为以下常量：
<a name="pdf-LUA_HOOKCALL"><code>LUA_HOOKCALL</code></a>，<a name="pdf-LUA_HOOKRET"><code>LUA_HOOKRET</code></a>，
<a name="pdf-LUA_HOOKTAILCALL"><code>LUA_HOOKTAILCALL</code></a>，<a name="pdf-LUA_HOOKLINE"><code>LUA_HOOKLINE</code></a>，
<a name="pdf-LUA_HOOKCOUNT"><code>LUA_HOOKCOUNT</code></a>。
除此之外，对于 line 事件， <code>currentline</code> 域也被设置。
要想获得 <code>ar</code> 中的其他域，
钩子必须调用 <a href="#lua_getinfo"><code>lua_getinfo</code></a> 。

<p>
对于 call 事件，<code>event</code> 可以是 <code>LUA_HOOKCALL</code> 这个通常值，
或是 <code>LUA_HOOKTAILCALL</code> 表示尾调用；
后一种情况，没有对应的返回事件。


<p>
当 Lua 运行在一个钩子内部时，
它将屏蔽掉其它对钩子的调用。
也就是说，如果一个钩子函数内再调回 Lua 来执行一个函数或是一个代码块 ，
这个执行操作不会触发任何的钩子。


<p>
钩子函数不能有延续点，
即不能用一个非空的 <code>k</code> 调用
<a href="#lua_yieldk"><code>lua_yieldk</code></a>，
<a href="#lua_pcallk"><code>lua_pcallk</code></a>，或 <a href="#lua_callk"><code>lua_callk</code></a>。

<p>
钩子函数可以在满足下列条件时让出：
只有行计数事件可以让出，且不能在让出时传出任何值；
从钩子里让出必须用 <a href="#lua_yield"><code>lua_yield</code></a>
来结束钩子的运行，且 <code>nresults</code> 必须为零。


<hr><h3><a name="lua_sethook"><code>lua_sethook</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>void lua_sethook (lua_State *L, lua_Hook f, int mask, int count);</pre>

<p>
设置一个调试用钩子函数。


<p>
参数 <code>f</code> 是钩子函数。
<code>mask</code> 指定在哪些事件时会调用：
它由下列一组位常量构成
<a name="pdf-LUA_MASKCALL"><code>LUA_MASKCALL</code></a>，
<a name="pdf-LUA_MASKRET"><code>LUA_MASKRET</code></a>，
<a name="pdf-LUA_MASKLINE"><code>LUA_MASKLINE</code></a>，
<a name="pdf-LUA_MASKCOUNT"><code>LUA_MASKCOUNT</code></a>。
参数 <code>count</code> 只在掩码中包含有 <code>LUA_MASKCOUNT</code> 才有意义。
对于每个事件，钩子被调用的情况解释如下：

<ul>

<li><b>call hook: </b>
在解释器调用一个函数时被调用。
钩子将于 Lua 进入一个新函数后，
函数获取参数前被调用。
</li>

<li><b>return hook: </b>
在解释器从一个函数中返回时调用。
钩子将于 Lua 离开函数之前的那一刻被调用。
没有标准方法来访问被函数返回的那些值。
</li>

<li><b>line hook: </b>
在解释器准备开始执行新的一行代码时，
或是跳转到这行代码中时（即使在同一行内跳转）被调用。
（这个事件仅仅在 Lua 执行一个 Lua 函数时发生。）
</li>

<li><b>count hook: </b>
在解释器每执行 <code>count</code> 条指令后被调用。
（这个事件仅仅在 Lua 执行一个 Lua 函数时发生。）
</li>

</ul>

<p>
钩子可以通过设置 <code>mask</code> 为零屏蔽。


<hr><h3><a name="lua_setlocal"><code>lua_setlocal</code></a></h3><p>
<span class="apii">[-(0|1), +0, &ndash;]</span>
<pre>const char *lua_setlocal (lua_State *L, const lua_Debug *ar, int n);</pre>

<p>
设置给定活动记录中的局部变量的值。
参数 <code>ar</code> 与 <code>n</code> 和
<a href="#lua_getlocal"><code>lua_getlocal</code></a> 中的一样 
（参见 <a href="#lua_getlocal"><code>lua_getlocal</code></a> ）。
<a href="#lua_setlocal"><code>lua_setlocal</code></a> 把栈顶的值赋给变量然后返回变量的名字。
它会将值从栈顶弹出。


<p>
当索引大于活动局部变量的数量时，返回 <code>NULL</code> （什么也不弹出）。


<hr><h3><a name="lua_setupvalue"><code>lua_setupvalue</code></a></h3><p>
<span class="apii">[-(0|1), +0, &ndash;]</span>
<pre>const char *lua_setupvalue (lua_State *L, int funcindex, int n);</pre>

<p>
设置闭包上值的值。
它把栈顶的值弹出并赋于上值并返回上值的名字。
参数 <code>funcindex</code> 与 <code>n</code> 和
<a href="#lua_getupvalue"><code>lua_getupvalue</code></a> 中的一样
（参见 <a href="#lua_getupvalue"><code>lua_getupvalue</code></a> ）。


<p>
当索引大于上值的数量时，返回 <code>NULL</code> （什么也不弹出）。


<hr><h3><a name="lua_upvalueid"><code>lua_upvalueid</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>void *lua_upvalueid (lua_State *L, int funcindex, int n);</pre>

<p>
返回索引 <code>funcindex</code> 处的闭包中
编号为 <code>n</code> 的上值的一个唯一标识符。
参数 <code>funcindex</code> 与 <code>n</code> 和
<a href="#lua_getupvalue"><code>lua_getupvalue</code></a> 中的一样
（参见 <a href="#lua_getupvalue"><code>lua_getupvalue</code></a> ）。
（但 <code>n</code> 不可以大于上值的数量）。


<p>
这些唯一标识符可用于检测不同的闭包是否共享了相同的上值。
共享同一个上值的 Lua 闭包（即它们指的同一个外部局部变量）
会针对这个上值返回相同的标识。


<hr><h3><a name="lua_upvaluejoin"><code>lua_upvaluejoin</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>void lua_upvaluejoin (lua_State *L, int funcindex1, int n1,
                                    int funcindex2, int n2);</pre>

<p>
让索引 <code>funcindex1</code> 处的 Lua 闭包的第 <code>n1</code> 个上值
引用索引 <code>funcindex2</code> 处的 Lua 闭包的第 <code>n2</code> 个上值。


<h1>5 &ndash; <a name="5">辅助库</a></h1>

<p>
<em>辅助库</em> 提供了一些便捷函数，方便在 C 中为 Lua 编程。
基础 API 提供了 C 和 Lua 交互用的主要函数，
而辅助库则为一些常见的任务提供了高阶函数。


<p>
所有辅助库中的函数和类型都定义在头文件 <code>lauxlib.h</code> 中，
它们均带有前缀 <code>luaL_</code>。


<p>
辅助库中的所有函数都基于基础 API 实现。
故而它们并没有提供任何基础 API 实现不了的功能。
虽然如此，使用辅助库可以让你的代码更为健壮。


<p>
一些辅助库函数会在内部使用一些额外的栈空间。
当辅助库使用的栈空间少于五个时，
它们不去检查栈大小；而是简单的假设栈够用。


<p>
一些辅助库中的函数用于检查 C 函数的参数。
因为错误信息格式化为指代参数
（例如，"<code>bad argument #1</code>"），
你就不要把这些函数用于参数之外的值了。

<p>
如果检查无法通过，
<code>luaL_check*</code> 这些函数一定会抛出错误。


<h2>5.1 &ndash; <a name="5.1">函数和类型</a></h2>

<p>
这里我们按字母表次序列出了辅助库中的所有函数和类型。


<hr><h3><a name="luaL_addchar"><code>luaL_addchar</code></a></h3><p>
<span class="apii">[-?, +?, <em>e</em>]</span>
<pre>void luaL_addchar (luaL_Buffer *B, char c);</pre>

<p>
向缓存 <code>B</code> （参见 <a href="#luaL_Buffer"><code>luaL_Buffer</code></a> ）
添加一个字节 <code>c</code>。


<hr><h3><a name="luaL_addlstring"><code>luaL_addlstring</code></a></h3><p>
<span class="apii">[-?, +?, <em>e</em>]</span>
<pre>void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l);</pre>

<p>
向缓存 <code>B</code> （参见 <a href="#luaL_Buffer"><code>luaL_Buffer</code></a> ）
添加一个长度为 <code>l</code> 的字符串 <code>s</code>。
这个字符串可以包含零。


<hr><h3><a name="luaL_addsize"><code>luaL_addsize</code></a></h3><p>
<span class="apii">[-?, +?, <em>e</em>]</span>
<pre>void luaL_addsize (luaL_Buffer *B, size_t n);</pre>

<p>
向缓存 <code>B</code> （参见 <a href="#luaL_Buffer"><code>luaL_Buffer</code></a> ）
添加一个已在之前复制到缓冲区（参见 <a href="#luaL_prepbuffer"><code>luaL_prepbuffer</code></a>）
的长度为 <code>n</code> 的字符串。


<hr><h3><a name="luaL_addstring"><code>luaL_addstring</code></a></h3><p>
<span class="apii">[-?, +?, <em>e</em>]</span>
<pre>void luaL_addstring (luaL_Buffer *B, const char *s);</pre>

<p>
向缓存 <code>B</code> （参见 <a href="#luaL_Buffer"><code>luaL_Buffer</code></a> ）
添加一个零结尾的字符串 <code>s</code>。


<hr><h3><a name="luaL_addvalue"><code>luaL_addvalue</code></a></h3><p>
<span class="apii">[-1, +?, <em>e</em>]</span>
<pre>void luaL_addvalue (luaL_Buffer *B);</pre>

<p>
向缓存 <code>B</code> （参见 <a href="#luaL_Buffer"><code>luaL_Buffer</code></a> ）
添加栈顶的一个值，随后将其弹出。


<p>
这个函数是操作字符串缓存的函数中，唯一一个会（且必须）在栈上放置额外元素的。
这个元素将被加入缓存。


<hr><h3><a name="luaL_argcheck"><code>luaL_argcheck</code></a></h3><p>
<span class="apii">[-0, +0, <em>v</em>]</span>
<pre>void luaL_argcheck (lua_State *L,
                    int cond,
                    int arg,
                    const char *extramsg);</pre>

<p>
检查 <code>cond</code> 是否为真。
如果不为真，以标准信息形式抛出一个错误
（参见 <a href="#luaL_argerror"><code>luaL_argerror</code></a>）。


<hr><h3><a name="luaL_argerror"><code>luaL_argerror</code></a></h3><p>
<span class="apii">[-0, +0, <em>v</em>]</span>
<pre>int luaL_argerror (lua_State *L, int arg, const char *extramsg);</pre>

<p>
抛出一个错误报告调用的 C 函数的第 <code>arg</code> 个参数的问题。
它使用下列标准信息并包含了一段 <code>extramsg</code> 作为注解：

<pre>
     bad argument #<em>arg</em> to '<em>funcname</em>' (<em>extramsg</em>)
</pre><p>
这个函数永远不会返回。


<hr><h3><a name="luaL_Buffer"><code>luaL_Buffer</code></a></h3>
<pre>typedef struct luaL_Buffer luaL_Buffer;</pre>

<p>
<em>字符串缓存</em> 的类型。


<p>
字符串缓存可以让 C 代码分段构造一个 Lua 字符串。
使用模式如下：

<ul>

<li>首先定义一个类型为 <a href="#luaL_Buffer"><code>luaL_Buffer</code></a> 的变量 <code>b</code>。</li>

<li>调用 <code>luaL_buffinit(L, &amp;b)</code> 初始化它。</li>

<li>
然后调用 <code>luaL_add*</code> 这组函数向其添加字符串片断。
</li>

<li>
最后调用 <code>luaL_pushresult(&amp;b)</code> 。
最后这次调用会在栈顶留下最终的字符串。
</li>

</ul>

<p>
如果你预先知道结果串的长度，
你可以这样使用缓存：

<ul>

<li>首先定义一个类型为 <a href="#luaL_Buffer"><code>luaL_Buffer</code></a> 的变量 <code>b</code>。</li>

<li>然后调用 <code>luaL_buffinitsize(L, &amp;b, sz)</code> 预分配 <code>sz</code> 大小的空间。</li>

<li>接着将字符串复制入这个空间。</li>

<li>
最后调用 <code>luaL_pushresultsize(&amp;b, sz)</code>，
这里的 <code>sz</code> 指已经复制到缓存内的字符串长度。
</li>

</ul>

<p>
一般的操作过程中，字符串缓存会使用不定量的栈槽。
因此，在使用缓存中，你不能假定目前栈顶在哪。
在对缓存操作的函数调用间，你都可以使用栈，只需要保证栈平衡即可；
即，在你做一次缓存操作调用时，当时的栈位置和上次调用缓存操作后的位置相同。
（对于 <a href="#luaL_addvalue"><code>luaL_addvalue</code></a> 是个唯一的例外。）
在调用完 <a href="#luaL_pushresult"><code>luaL_pushresult</code></a> 后，
栈会恢复到缓存初始化时的位置上，并在顶部压入最终的字符串。


<hr><h3><a name="luaL_buffinit"><code>luaL_buffinit</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>void luaL_buffinit (lua_State *L, luaL_Buffer *B);</pre>

<p>
初始化缓存 <code>B</code>。
这个函数不会分配任何空间；
缓存必须以一个变量的形式声明
（参见 <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>）。


<hr><h3><a name="luaL_buffinitsize"><code>luaL_buffinitsize</code></a></h3><p>
<span class="apii">[-?, +?, <em>e</em>]</span>
<pre>char *luaL_buffinitsize (lua_State *L, luaL_Buffer *B, size_t sz);</pre>

<p>
等价于调用序列
<a href="#luaL_buffinit"><code>luaL_buffinit</code></a>，
<a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a>。


<hr><h3><a name="luaL_callmeta"><code>luaL_callmeta</code></a></h3><p>
<span class="apii">[-0, +(0|1), <em>e</em>]</span>
<pre>int luaL_callmeta (lua_State *L, int obj, const char *e);</pre>

<p>
调用一个元方法。


<p>
如果在索引 <code>obj</code> 处的对象有元表，
且元表有域 <code>e</code> 。
这个函数会以该对象为参数调用这个域。
这种情况下，函数返回真并将调用返回值压栈。
如果那个位置没有元表，或没有对应的元方法，
此函数返回假（并不会将任何东西压栈）。


<hr><h3><a name="luaL_checkany"><code>luaL_checkany</code></a></h3><p>
<span class="apii">[-0, +0, <em>v</em>]</span>
<pre>void luaL_checkany (lua_State *L, int arg);</pre>

<p>
检查函数在 <code>arg</code> 位置是否有任何类型（包括 <b>nil</b>）的参数。


<hr><h3><a name="luaL_checkinteger"><code>luaL_checkinteger</code></a></h3><p>
<span class="apii">[-0, +0, <em>v</em>]</span>
<pre>lua_Integer luaL_checkinteger (lua_State *L, int arg);</pre>

<p>
检查函数的第 <code>arg</code> 个参数是否是一个
整数（或是可以被转换为一个整数）
并以  <a href="#lua_Integer"><code>lua_Integer</code></a> 类型返回这个整数值。


<hr><h3><a name="luaL_checklstring"><code>luaL_checklstring</code></a></h3><p>
<span class="apii">[-0, +0, <em>v</em>]</span>
<pre>const char *luaL_checklstring (lua_State *L, int arg, size_t *l);</pre>

<p>
检查函数的第 <code>arg</code> 个参数是否是一个
字符串，并返回该字符串；
如果 <code>l</code> 不为 <code>NULL</code> ，
将字符串的长度填入 <code>*l</code>。


<p>
这个函数使用 <a href="#lua_tolstring"><code>lua_tolstring</code></a> 来获取结果。
所以该函数有可能引发的转换都同样有效。


<hr><h3><a name="luaL_checknumber"><code>luaL_checknumber</code></a></h3><p>
<span class="apii">[-0, +0, <em>v</em>]</span>
<pre>lua_Number luaL_checknumber (lua_State *L, int arg);</pre>

<p>
检查函数的第 <code>arg</code> 个参数是否是一个
数字，并返回这个数字。


<hr><h3><a name="luaL_checkoption"><code>luaL_checkoption</code></a></h3><p>
<span class="apii">[-0, +0, <em>v</em>]</span>
<pre>int luaL_checkoption (lua_State *L,
                      int arg,
                      const char *def,
                      const char *const lst[]);</pre>

<p>
检查函数的第 <code>arg</code> 个参数是否是一个
字符串，并在数组 <code>lst</code> 
（比如是零结尾的字符串数组）
中查找这个字符串。
返回匹配到的字符串在数组中的索引号。
如果参数不是字符串，或是字符串在数组中匹配不到，都将抛出错误。


<p>
如果 <code>def</code> 不为 <code>NULL</code>，
函数就把 <code>def</code> 当作默认值。
默认值在参数 <code>arg</code> 不存在，或该参数是 <b>nil</b> 时生效。


<p>
这个函数通常用于将字符串映射为 C 枚举量。
（在 Lua 库中做这个转换可以让其使用字符串，而不是数字来做一些选项。）


<hr><h3><a name="luaL_checkstack"><code>luaL_checkstack</code></a></h3><p>
<span class="apii">[-0, +0, <em>v</em>]</span>
<pre>void luaL_checkstack (lua_State *L, int sz, const char *msg);</pre>

<p>
将栈空间扩展到 <code>top + sz</code> 个元素。
如果扩展不了，则抛出一个错误。
<code>msg</code> 是用于错误消息的额外文本
（<code>NULL</code> 表示不需要额外文本）。


<hr><h3><a name="luaL_checkstring"><code>luaL_checkstring</code></a></h3><p>
<span class="apii">[-0, +0, <em>v</em>]</span>
<pre>const char *luaL_checkstring (lua_State *L, int arg);</pre>

<p>
检查函数的第 <code>arg</code> 个参数是否是一个
字符串并返回这个字符串。


<p>
这个函数使用 <a href="#lua_tolstring"><code>lua_tolstring</code></a> 来获取结果。
所以该函数有可能引发的转换都同样有效。


<hr><h3><a name="luaL_checktype"><code>luaL_checktype</code></a></h3><p>
<span class="apii">[-0, +0, <em>v</em>]</span>
<pre>void luaL_checktype (lua_State *L, int arg, int t);</pre>

<p>
检查函数的第 <code>arg</code> 个参数的类型是否是 <code>t</code>。
参见 <a href="#lua_type"><code>lua_type</code></a> 查阅类型 <code>t</code> 的编码。


<hr><h3><a name="luaL_checkudata"><code>luaL_checkudata</code></a></h3><p>
<span class="apii">[-0, +0, <em>v</em>]</span>
<pre>void *luaL_checkudata (lua_State *L, int arg, const char *tname);</pre>

<p>
检查函数的第 <code>arg</code> 个参数是否是一个类型为
<code>tname</code> 的用户数据
（参见 <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a> )。
它会返回该用户数据的地址
（参见 <a href="#lua_touserdata"><code>lua_touserdata</code></a>）。


<hr><h3><a name="luaL_checkversion"><code>luaL_checkversion</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>void luaL_checkversion (lua_State *L);</pre>

<p>
检查调用它的内核是否是创建这个 Lua 状态机的内核。
以及调用它的代码是否使用了相同的 Lua 版本。
同时也检查调用它的内核与创建该 Lua  状态机的内核
是否使用了同一片地址空间。


<hr><h3><a name="luaL_dofile"><code>luaL_dofile</code></a></h3><p>
<span class="apii">[-0, +?, <em>e</em>]</span>
<pre>int luaL_dofile (lua_State *L, const char *filename);</pre>

<p>
加载并运行指定的文件。
它是用下列宏定义出来：

<pre>
     (luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0))
</pre><p>
如果没有错误，函数返回假；
有错则返回真。


<hr><h3><a name="luaL_dostring"><code>luaL_dostring</code></a></h3><p>
<span class="apii">[-0, +?, &ndash;]</span>
<pre>int luaL_dostring (lua_State *L, const char *str);</pre>

<p>
加载并运行指定的字符串。
它是用下列宏定义出来：

<pre>
     (luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0))
</pre><p>
如果没有错误，函数返回假；
有错则返回真。


<hr><h3><a name="luaL_error"><code>luaL_error</code></a></h3><p>
<span class="apii">[-0, +0, <em>v</em>]</span>
<pre>int luaL_error (lua_State *L, const char *fmt, ...);</pre>

<p>
抛出一个错误。
错误消息的格式由 <code>fmt</code> 给出。
后面需提供若干参数，
这些参数遵循 <a href="#lua_pushfstring"><code>lua_pushfstring</code></a> 中的规则。
如果能获得相关信息，它还会在消息前面加上错误发生时的文件名及行号。


<p>
这个函数永远不会返回。
但是在 C 函数中通常遵循惯用法：
<code>return luaL_error(<em>args</em>)</code> 。


<hr><h3><a name="luaL_execresult"><code>luaL_execresult</code></a></h3><p>
<span class="apii">[-0, +3, <em>e</em>]</span>
<pre>int luaL_execresult (lua_State *L, int stat);</pre>

<p>
这个函数用于生成标准库中和进程相关函数的返回值。
（指 <a href="#pdf-os.execute"><code>os.execute</code></a> 和 <a href="#pdf-io.close"><code>io.close</code></a>）。


<hr><h3><a name="luaL_fileresult"><code>luaL_fileresult</code></a></h3><p>
<span class="apii">[-0, +(1|3), <em>e</em>]</span>
<pre>int luaL_fileresult (lua_State *L, int stat, const char *fname);</pre>

<p>
这个函数用于生成标准库中和文件相关的函数的返回值。
（指 (<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>，等。)。


<hr><h3><a name="luaL_getmetafield"><code>luaL_getmetafield</code></a></h3><p>
<span class="apii">[-0, +(0|1), <em>e</em>]</span>
<pre>int luaL_getmetafield (lua_State *L, int obj, const char *e);</pre>

<p>
将索引 <code>obj</code> 处对象的元表中 <code>e</code> 域的值压栈。
如果该对象没有元表，或是该元表没有相关域，
此函数什么也不会压栈并返回 <code>LUA_TNIL</code>。


<hr><h3><a name="luaL_getmetatable"><code>luaL_getmetatable</code></a></h3><p>
<span class="apii">[-0, +1, &ndash;]</span>
<pre>int luaL_getmetatable (lua_State *L, const char *tname);</pre>

<p>
将注册表中 <code>tname</code> 对应的元表
（参见 <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>）压栈。
如果没有 <code>tname</code> 对应的元表，则将 <b>nil</b> 压栈并返回假。


<hr><h3><a name="luaL_getsubtable"><code>luaL_getsubtable</code></a></h3><p>
<span class="apii">[-0, +1, <em>e</em>]</span>
<pre>int luaL_getsubtable (lua_State *L, int idx, const char *fname);</pre>

<p>
确保 <code>t[fname]</code> 是一张表，并将这张表压栈。
这里的 <code>t</code> 指索引 <code>idx</code> 处的值。
如果它原来就是一张表，返回真；
否则为它创建一张新表，返回假。


<hr><h3><a name="luaL_gsub"><code>luaL_gsub</code></a></h3><p>
<span class="apii">[-0, +1, <em>e</em>]</span>
<pre>const char *luaL_gsub (lua_State *L,
                       const char *s,
                       const char *p,
                       const char *r);</pre>

<p>
将字符串 <code>s</code> 生成一个副本，
并将其中的所有字符串 <code>p</code>
都替换为字符串 <code>r</code> 。
将结果串压栈并返回它。


<hr><h3><a name="luaL_len"><code>luaL_len</code></a></h3><p>
<span class="apii">[-0, +0, <em>e</em>]</span>
<pre>lua_Integer luaL_len (lua_State *L, int index);</pre>

<p>
以数字形式返回给定索引处值的“长度”；
它等价于在 Lua 中调用 '<code>#</code>' 的操作
（参见 <a href="#3.4.7">&sect;3.4.7</a>）。
如果操作结果不是一个整数，则抛出一个错误。
（这种情况只发生在触发元方法时。）


<hr><h3><a name="luaL_loadbuffer"><code>luaL_loadbuffer</code></a></h3><p>
<span class="apii">[-0, +1, &ndash;]</span>
<pre>int luaL_loadbuffer (lua_State *L,
                     const char *buff,
                     size_t sz,
                     const char *name);</pre>

<p>
等价于 <a href="#luaL_loadbufferx"><code>luaL_loadbufferx</code></a>，
其 <code>mode</code> 参数等于 <code>NULL</code>。


<hr><h3><a name="luaL_loadbufferx"><code>luaL_loadbufferx</code></a></h3><p>
<span class="apii">[-0, +1, &ndash;]</span>
<pre>int luaL_loadbufferx (lua_State *L,
                      const char *buff,
                      size_t sz,
                      const char *name,
                      const char *mode);</pre>

<p>
把一段缓存加载为一个 Lua 代码块。
这个函数使用 <a href="#lua_load"><code>lua_load</code></a> 
来加载 <code>buff</code> 指向的长度为 <code>sz</code> 的内存区。


<p>
这个函数和 <a href="#lua_load"><code>lua_load</code></a> 返回值相同。
<code>name</code> 作为代码块的名字，用于调试信息和错误消息。
<code>mode</code> 字符串的作用同函数 <a href="#lua_load"><code>lua_load</code></a>。


<hr><h3><a name="luaL_loadfile"><code>luaL_loadfile</code></a></h3><p>
<span class="apii">[-0, +1, <em>e</em>]</span>
<pre>int luaL_loadfile (lua_State *L, const char *filename);</pre>

<p>
等价于 <a href="#luaL_loadfilex"><code>luaL_loadfilex</code></a>，
其 <code>mode</code> 参数等于 <code>NULL</code>。


<hr><h3><a name="luaL_loadfilex"><code>luaL_loadfilex</code></a></h3><p>
<span class="apii">[-0, +1, <em>e</em>]</span>
<pre>int luaL_loadfilex (lua_State *L, const char *filename,
                                            const char *mode);</pre>

<p>
把一个文件加载为 Lua 代码块。
这个函数使用 <a href="#lua_load"><code>lua_load</code></a> 加载文件中的数据。
代码块的名字被命名为 <code>filename</code>。
如果 <code>filename</code> 为 <code>NULL</code>，
它从标准输入加载。
如果文件的第一行以 <code>#</code> 打头，则忽略这一行。

<p>
<code>mode</code> 字符串的作用同函数 <a href="#lua_load"><code>lua_load</code></a>。


<p>
此函数的返回值和 <a href="#lua_load"><code>lua_load</code></a> 相同，
不过它还可能产生一个叫做 <a name="pdf-LUA_ERRFILE"><code>LUA_ERRFILE</code></a>
的出错码。这种错误发生于无法打开或读入文件时，或是文件的模式错误。


<p>
和 <a href="#lua_load"><code>lua_load</code></a> 一样，这个函数仅加载代码块不运行。


<hr><h3><a name="luaL_loadstring"><code>luaL_loadstring</code></a></h3><p>
<span class="apii">[-0, +1, &ndash;]</span>
<pre>int luaL_loadstring (lua_State *L, const char *s);</pre>

<p>
将一个字符串加载为 Lua 代码块。
这个函数使用 <a href="#lua_load"><code>lua_load</code></a> 加载一个零结尾的字符串
<code>s</code>。


<p>
此函数的返回值和 <a href="#lua_load"><code>lua_load</code></a> 相同。


<p>
也和 <a href="#lua_load"><code>lua_load</code></a> 一样，这个函数仅加载代码块不运行。


<hr><h3><a name="luaL_newlib"><code>luaL_newlib</code></a></h3><p>
<span class="apii">[-0, +1, <em>e</em>]</span>
<pre>void luaL_newlib (lua_State *L, const luaL_Reg l[]);</pre>

<p>
创建一张新的表，并把列表 <code>l</code> 中的函数注册进去。


<p>
它是用下列宏实现的：

<pre>
     (luaL_newlibtable(L,l), luaL_setfuncs(L,l,0))
</pre><p>
数组 <code>l</code> 必须是一个数组，而不能是一个指针。


<hr><h3><a name="luaL_newlibtable"><code>luaL_newlibtable</code></a></h3><p>
<span class="apii">[-0, +1, <em>e</em>]</span>
<pre>void luaL_newlibtable (lua_State *L, const luaL_Reg l[]);</pre>

<p>
创建一张新的表，并预分配足够保存下数组 <code>l</code>
内容的空间（但不填充）。
这是给 <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a>
一起用的
（参见 <a href="#luaL_newlib"><code>luaL_newlib</code></a>）。


<p>
它以宏形式实现，
数组 <code>l</code> 必须是一个数组，而不能是一个指针。


<hr><h3><a name="luaL_newmetatable"><code>luaL_newmetatable</code></a></h3><p>
<span class="apii">[-0, +1, <em>e</em>]</span>
<pre>int luaL_newmetatable (lua_State *L, const char *tname);</pre>

<p>
如果注册表中已存在键 <code>tname</code>，返回 0 。
否则，
为用户数据的元表创建一张新表。
向这张表加入 <code>__name = tname</code> 键值对，
并将 <code>[tname] = new table</code> 添加到注册表中，
返回 1 。
（<code>__name</code>项可用于一些错误输出函数。）


<p>
这两种情况都会把最终的注册表中关联 <code>tname</code> 的值压栈。


<hr><h3><a name="luaL_newstate"><code>luaL_newstate</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>lua_State *luaL_newstate (void);</pre>

<p>
创建一个新的 Lua 状态机。
它以一个基于标准 C 的 <code>realloc</code> 函数实现的内存分配器
调用 <a href="#lua_newstate"><code>lua_newstate</code></a> 。
并把可打印一些出错信息到标准错误输出的 panic 函数（参见 <a href="#4.6">&sect;4.6</a>）
设置好，用于处理致命错误。


<p>
返回新的状态机。
如果内存分配失败，则返回 <code>NULL</code> 。


<hr><h3><a name="luaL_openlibs"><code>luaL_openlibs</code></a></h3><p>
<span class="apii">[-0, +0, <em>e</em>]</span>
<pre>void luaL_openlibs (lua_State *L);</pre>

<p>
打开指定状态机中的所有 Lua 标准库。


<hr><h3><a name="luaL_optinteger"><code>luaL_optinteger</code></a></h3><p>
<span class="apii">[-0, +0, <em>v</em>]</span>
<pre>lua_Integer luaL_optinteger (lua_State *L,
                             int arg,
                             lua_Integer d);</pre>

<p>
如果函数的第 <code>arg</code> 个参数是一个
整数（或可以转换为一个整数），
返回该整数。
若该参数不存在或是 <b>nil</b>，
返回 <code>d</code>。
除此之外的情况，抛出错误。


<hr><h3><a name="luaL_optlstring"><code>luaL_optlstring</code></a></h3><p>
<span class="apii">[-0, +0, <em>v</em>]</span>
<pre>const char *luaL_optlstring (lua_State *L,
                             int arg,
                             const char *d,
                             size_t *l);</pre>

<p>
如果函数的第 <code>arg</code> 个参数是一个
字符串，返回该字符串。
若该参数不存在或是 <b>nil</b>，
返回 <code>d</code>。
除此之外的情况，抛出错误。


<p>
若 <code>l</code> 不为 <code>NULL</code>，
将结果的长度填入 <code>*l</code> 。


<hr><h3><a name="luaL_optnumber"><code>luaL_optnumber</code></a></h3><p>
<span class="apii">[-0, +0, <em>v</em>]</span>
<pre>lua_Number luaL_optnumber (lua_State *L, int arg, lua_Number d);</pre>

<p>
如果函数的第 <code>arg</code> 个参数是一个
数字，返回该数字。
若该参数不存在或是 <b>nil</b>，
返回 <code>d</code>。
除此之外的情况，抛出错误。


<hr><h3><a name="luaL_optstring"><code>luaL_optstring</code></a></h3><p>
<span class="apii">[-0, +0, <em>v</em>]</span>
<pre>const char *luaL_optstring (lua_State *L,
                            int arg,
                            const char *d);</pre>

<p>
如果函数的第 <code>arg</code> 个参数是一个
字符串，返回该字符串。
若该参数不存在或是 <b>nil</b>，
返回 <code>d</code>。
除此之外的情况，抛出错误。


<hr><h3><a name="luaL_prepbuffer"><code>luaL_prepbuffer</code></a></h3><p>
<span class="apii">[-?, +?, <em>e</em>]</span>
<pre>char *luaL_prepbuffer (luaL_Buffer *B);</pre>

<p>
等价于 <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a>，
其预定义大小为 <a name="pdf-LUAL_BUFFERSIZE"><code>LUAL_BUFFERSIZE</code></a>。


<hr><h3><a name="luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a></h3><p>
<span class="apii">[-?, +?, <em>e</em>]</span>
<pre>char *luaL_prepbuffsize (luaL_Buffer *B, size_t sz);</pre>

<p>
返回一段大小为 <code>sz</code> 的空间地址。
你可以将字符串复制其中以加到缓存 <code>B</code> 内
（参见 <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>）。
将字符串复制其中后，你必须调用 <a href="#luaL_addsize"><code>luaL_addsize</code></a>
传入字符串的大小，才会真正把它加入缓存。


<hr><h3><a name="luaL_pushresult"><code>luaL_pushresult</code></a></h3><p>
<span class="apii">[-?, +1, <em>e</em>]</span>
<pre>void luaL_pushresult (luaL_Buffer *B);</pre>

<p>
结束对缓存 <code>B</code> 的使用，将最终的字符串留在栈顶。


<hr><h3><a name="luaL_pushresultsize"><code>luaL_pushresultsize</code></a></h3><p>
<span class="apii">[-?, +1, <em>e</em>]</span>
<pre>void luaL_pushresultsize (luaL_Buffer *B, size_t sz);</pre>

<p>
等价于 <a href="#luaL_addsize"><code>luaL_addsize</code></a>，<a href="#luaL_pushresult"><code>luaL_pushresult</code></a>。


<hr><h3><a name="luaL_ref"><code>luaL_ref</code></a></h3><p>
<span class="apii">[-1, +0, <em>e</em>]</span>
<pre>int luaL_ref (lua_State *L, int t);</pre>

<p>
针对栈顶的对象，创建并返回一个在索引 <code>t</code> 指向的表中的 <em>引用</em>
（最后会弹出栈顶对象）。


<p>
此引用是一个唯一的整数键。
只要你不向表 <code>t</code> 手工添加整数键，
<a href="#luaL_ref"><code>luaL_ref</code></a> 可以保证它返回的键的唯一性。
你可以通过调用 <code>lua_rawgeti(L, t, r)</code> 来找回由
<code>r</code> 引用的对象。
函数 <a href="#luaL_unref"><code>luaL_unref</code></a> 用来释放一个引用关联的对象


<p>
如果栈顶的对象是 <b>nil</b>，
<a href="#luaL_ref"><code>luaL_ref</code></a> 将返回常量
<a name="pdf-LUA_REFNIL"><code>LUA_REFNIL</code></a>。
常量 <a name="pdf-LUA_NOREF"><code>LUA_NOREF</code></a> 可以保证和
<a href="#luaL_ref"><code>luaL_ref</code></a> 能返回的其它引用值不同。


<hr><h3><a name="luaL_Reg"><code>luaL_Reg</code></a></h3>
<pre>typedef struct luaL_Reg {
  const char *name;
  lua_CFunction func;
} luaL_Reg;</pre>

<p>
用于 <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a>
注册函数的数组类型。
<code>name</code> 指函数名，<code>func</code> 是函数指针。
任何 <a href="#luaL_Reg"><code>luaL_Reg</code></a> 数组必须以一对
<code>name</code> 与 <code>func</code> 皆为 <code>NULL</code> 结束。


<hr><h3><a name="luaL_requiref"><code>luaL_requiref</code></a></h3><p>
<span class="apii">[-0, +1, <em>e</em>]</span>
<pre>void luaL_requiref (lua_State *L, const char *modname,
                    lua_CFunction openf, int glb);</pre>

<p>
如果 <code>modname</code> 不在 <a href="#pdf-package.loaded"><code>package.loaded</code></a> 中，
则调用函数 <code>openf</code> ，并传入字符串 <code>modname</code>。
将其返回值置入 <code>package.loaded[modname]</code>。
这个行为好似该函数通过 <a href="#pdf-require"><code>require</code></a> 调用过一样。


<p>
如果 <code>glb</code> 为真，
同时也将模块设到全局变量 <code>modname</code> 里。


<p>
在栈上留下该模块的副本。


<hr><h3><a name="luaL_setfuncs"><code>luaL_setfuncs</code></a></h3><p>
<span class="apii">[-nup, +0, <em>e</em>]</span>
<pre>void luaL_setfuncs (lua_State *L, const luaL_Reg *l, int nup);</pre>

<p>
把数组 <code>l</code> 中的所有函数
（参见 <a href="#luaL_Reg"><code>luaL_Reg</code></a>）
注册到栈顶的表中（该表在可选的上值之下，见下面的解说）。

<p>
若 <code>nup</code> 不为零，
所有的函数都共享 <code>nup</code> 个上值。
这些值必须在调用之前，压在表之上。
这些值在注册完毕后都会从栈弹出。


<hr><h3><a name="luaL_setmetatable"><code>luaL_setmetatable</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>void luaL_setmetatable (lua_State *L, const char *tname);</pre>

<p>
将注册表中 <code>tname</code> 关联元表
（参见 <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>）
设为栈顶对象的元表。


<hr><h3><a name="luaL_Stream"><code>luaL_Stream</code></a></h3>
<pre>typedef struct luaL_Stream {
  FILE *f;
  lua_CFunction closef;
} luaL_Stream;</pre>

<p>
标准输入输出库中用到的标准文件句柄结构。

<p>
文件句柄实现为一个完全用户数据，
其元表被称为 <code>LUA_FILEHANDLE</code>
（<code>LUA_FILEHANDLE</code> 是一个代表真正元表的名字的宏）。
这张元表由标准输入输出库（参见 <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>）创建。


<p>
用户数据必须以结构 <code>luaL_Stream</code> 开头；
此结构其后可以包含任何其它数据。
<code>f</code> 域指向一个 C 数据流
（如果它为 <code>NULL</code> 表示一个没有创建好的句柄）。
<code>closef</code> 域指向一个在关闭或回收该流时需要调用的 Lua 函数。
该函数将收到一个参数，即文件句柄。
它需要返回 <b>true</b>（操作成功）或
<b>nil</b> 加错误消息（出错的时候）。
一旦 Lua 调用过这个域，该域的值就会修改为 <code>NULL</code>
以提示这个句柄已经被关闭了。


<hr><h3><a name="luaL_testudata"><code>luaL_testudata</code></a></h3><p>
<span class="apii">[-0, +0, <em>e</em>]</span>
<pre>void *luaL_testudata (lua_State *L, int arg, const char *tname);</pre>

<p>
此函数和 <a href="#luaL_checkudata"><code>luaL_checkudata</code></a> 类似。
但它在测试失败时会返回 <code>NULL</code> 而不是抛出错误。


<hr><h3><a name="luaL_tolstring"><code>luaL_tolstring</code></a></h3><p>
<span class="apii">[-0, +1, <em>e</em>]</span>
<pre>const char *luaL_tolstring (lua_State *L, int idx, size_t *len);</pre>

<p>
将给定索引处的 Lua 值转换为一个相应格式的 C 字符串。
结果串不仅会压栈，还会由函数返回。
如果 <code>len</code> 不为 <code>NULL</code> ，
它还把字符串长度设到 <code>*len</code> 中。


<p>
如果该值有一个带 <code>"__tostring"</code> 域的元表，
<code>luaL_tolstring</code> 会以该值为参数去调用对应的元方法，
并将其返回值作为结果。


<hr><h3><a name="luaL_traceback"><code>luaL_traceback</code></a></h3><p>
<span class="apii">[-0, +1, <em>e</em>]</span>
<pre>void luaL_traceback (lua_State *L, lua_State *L1, const char *msg,
                     int level);</pre>

<p>
将栈 <code>L1</code> 的栈回溯信息压栈。
如果 <code>msg</code> 不为 <code>NULL</code> ，它会附加到栈回溯信息之前。
<code>level</code> 参数指明从第几层开始做栈回溯。


<hr><h3><a name="luaL_typename"><code>luaL_typename</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>const char *luaL_typename (lua_State *L, int index);</pre>

<p>
返回给定索引处值的类型名。


<hr><h3><a name="luaL_unref"><code>luaL_unref</code></a></h3><p>
<span class="apii">[-0, +0, &ndash;]</span>
<pre>void luaL_unref (lua_State *L, int t, int ref);</pre>

<p>
释放索引 <code>t</code> 处表的 <code>ref</code> 引用对象
（参见 <a href="#luaL_ref"><code>luaL_ref</code></a> ）。
此条目会从表中移除以让其引用的对象可被垃圾收集。
而引用 <code>ref</code> 也被回收再次使用。


<p>
如果 <code>ref</code> 为 <a href="#pdf-LUA_NOREF"><code>LUA_NOREF</code></a> 
或 <a href="#pdf-LUA_REFNIL"><code>LUA_REFNIL</code></a>，
<a href="#luaL_unref"><code>luaL_unref</code></a> 什么也不做。


<hr><h3><a name="luaL_where"><code>luaL_where</code></a></h3><p>
<span class="apii">[-0, +1, <em>e</em>]</span>
<pre>void luaL_where (lua_State *L, int lvl);</pre>

<p>
将一个用于表示 <code>lvl</code> 层栈的控制点位置的字符串压栈。
这个字符串遵循下面的格式：

<pre>
     <em>chunkname</em>:<em>currentline</em>:
</pre><p>
0 层指当前正在运行的函数，
1 层指调用正在运行函数的函数，
依次类推。


<p>
这个函数用于构建错误消息的前缀。


<h1>6 &ndash; <a name="6">标准库</a></h1>

<p>
标准库提供了一些有用的函数,
它们都是直接用 C API 实现的。
其中一些函数提供了原本语言就有的服务
（例如，<a href="#pdf-type"><code>type</code></a> 与 <a href="#pdf-getmetatable"><code>getmetatable</code></a>）；
另一些提供和“外部”打交道的服务（例如 I/O ）；
还有些本可以用 Lua 本身来实现，但在 C 中实现可以满足关键点上的性能需求
（例如 <a href="#pdf-table.sort"><code>table.sort</code></a>）。

<p>
所有的库都是直接用 C API 实现的，并以分离的 C 模块形式提供。
目前，Lua 有下列标准库：

<ul>

<li>基础库 (<a href="#6.1">&sect;6.1</a>);</li>

<li>协程库 (<a href="#6.2">&sect;6.2</a>);</li>

<li>包管理库 (<a href="#6.3">&sect;6.3</a>);</li>

<li>字符串控制 (<a href="#6.4">&sect;6.4</a>);</li>

<li>基础 UTF-8 支持 (<a href="#6.5">&sect;6.5</a>);</li>

<li>表控制 (<a href="#6.6">&sect;6.6</a>);</li>

<li>数学函数 (<a href="#6.7">&sect;6.7</a>) (sin ，log 等);</li>

<li>输入输出 (<a href="#6.8">&sect;6.8</a>);</li>

<li>操作系统库 (<a href="#6.9">&sect;6.9</a>);</li>

<li>调试库 (<a href="#6.10">&sect;6.10</a>).</li>

</ul><p>
除了基础库和包管理库，
其它库都把自己的函数放在一张全局表的域中，
或是以对象方法的形式提供。


<p>
要使用这些库，
C 的宿主程序需要先调用一下
<a href="#luaL_openlibs"><code>luaL_openlibs</code></a> 这个函数，
这样就能打开所有的标准库。
或者宿主程序也可以用
<a href="#luaL_requiref"><code>luaL_requiref</code></a> 分别打开这些库：
<a name="pdf-luaopen_base"><code>luaopen_base</code></a> （基础库），
<a name="pdf-luaopen_package"><code>luaopen_package</code></a> （包管理库），
<a name="pdf-luaopen_coroutine"><code>luaopen_coroutine</code></a> （协程库），
<a name="pdf-luaopen_string"><code>luaopen_string</code></a> （字符串库），
<a name="pdf-luaopen_utf8"><code>luaopen_utf8</code></a> （UTF8 库），
<a name="pdf-luaopen_table"><code>luaopen_table</code></a> （表处理库），
<a name="pdf-luaopen_math"><code>luaopen_math</code></a> （数学库），
<a name="pdf-luaopen_io"><code>luaopen_io</code></a> （I/O 库），
<a name="pdf-luaopen_os"><code>luaopen_os</code></a> （操作系统库），
<a name="pdf-luaopen_debug"><code>luaopen_debug</code></a> （调试库）。
这些函数都定义在 <a name="pdf-lualib.h"><code>lualib.h</code></a> 中。


<h2>6.1 &ndash; <a name="6.1">基础函数</a></h2>

<p>
基础库提供了 Lua 核心函数。
如果你不将这个库包含在你的程序中，
你就需要小心检查程序是否需要自己提供其中一些特性的实现。

<p>
<hr><h3><a name="pdf-assert"><code>assert (v [, message])</code></a></h3>


<p>
如果其参数 <code>v</code> 的值为假（<b>nil</b> 或 <b>false</b>），
它就调用 <a href="#pdf-error"><code>error</code></a>；
否则，返回所有的参数。
在错误情况时，
<code>message</code> 指那个错误对象；
如果不提供这个参数，参数默认为 "<code>assertion failed!</code>" 。


<p>
<hr><h3><a name="pdf-collectgarbage"><code>collectgarbage ([opt [, arg]])</code></a></h3>


<p>
这个函数是垃圾收集器的通用接口。
通过参数 <code>opt</code> 它提供了一组不同的功能：

<ul>

<li><b>"<code>collect</code>": </b>
做一次完整的垃圾收集循环。
这是默认选项。
</li>

<li><b>"<code>stop</code>": </b>
停止垃圾收集器的运行。
在调用重启前，收集器只会因显式的调用运行。
</li>

<li><b>"<code>restart</code>": </b>
重启垃圾收集器的自动运行。
</li>

<li><b>"<code>count</code>": </b>
以 K 字节数为单位返回 Lua 使用的总内存数。
这个值有小数部分，所以只需要乘上 1024 就能得到
Lua 使用的准确字节数（除非溢出）。
</li>

<li><b>"<code>step</code>": </b>
单步运行垃圾收集器。
步长“大小”由 <code>arg</code> 控制。
传入 0 时，收集器步进（不可分割的）一步。
传入非 0 值，
收集器收集相当于 Lua 分配这些多（K 字节）内存的工作。
如果收集器结束一个循环将返回 <b>true</b> 。
</li>

<li><b>"<code>setpause</code>": </b>
将 <code>arg</code> 设为收集器的 <em>间歇率</em>
（参见 <a href="#2.5">&sect;2.5</a>）。
返回 <em>间歇率</em> 的前一个值。
</li>

<li><b>"<code>setstepmul</code>": </b>
将 <code>arg</code> 设为收集器的 <em>步进倍率</em>
（参见 <a href="#2.5">&sect;2.5</a>）。
返回 <em>步进倍率</em> 的前一个值。
</li>

<li><b>"<code>isrunning</code>": </b>
返回表示收集器是否在工作的布尔值
（即未被停止）。
</li>

</ul>


<p>
<hr><h3><a name="pdf-dofile"><code>dofile ([filename])</code></a></h3>
打开该名字的文件，并执行文件中的 Lua 代码块。
不带参数调用时， <code>dofile</code> 执行标准输入的内容（<code>stdin</code>）。
返回该代码块的所有返回值。
对于有错误的情况，<code>dofile</code> 将错误反馈给调用者
（即，<code>dofile</code> 没有运行在保护模式下）。


<p>
<hr><h3><a name="pdf-error"><code>error (message [, level])</code></a></h3>
中止上一次保护函数调用，
将错误对象 <code>message</code> 返回。
函数 <code>error</code> 永远不会返回。


<p>
当 message 是一个字符串时，通常 <code>error</code> 会把一些有关出错位置的信息附加在消息的前头。
<code>level</code> 参数指明了怎样获得出错位置。
对于 level 1 （默认值），出错位置指 <code>error</code> 函数调用的位置。
Level 2 将出错位置指向调用 <code>error</code>的函数的函数；以此类推。
传入 level 0 可以避免在消息前添加出错位置信息。


<p>
<hr><h3><a name="pdf-_G"><code>_G</code></a></h3>
一个全局变量（非函数），
内部储存有全局环境（参见 <a href="#2.2">&sect;2.2</a>）。
Lua 自己不使用这个变量；
改变这个变量的值不会对任何环境造成影响，反之亦然。


<p>
<hr><h3><a name="pdf-getmetatable"><code>getmetatable (object)</code></a></h3>


<p>
如果 <code>object</code> 不包含元表，返回 <b>nil</b> 。
否则，如果在该对象的元表中有 <code>"__metatable"</code> 域时返回其关联值，
没有时返回该对象的元表。


<p>
<hr><h3><a name="pdf-ipairs"><code>ipairs (t)</code></a></h3>


<p>
返回三个值（迭代函数、表 <code>t</code> 以及 0 ），
如此，以下代码

<pre>
     for i,v in ipairs(t) do <em>body</em> end
</pre><p>
将迭代键值对（<code>1,t[1]</code>) ，(<code>2,t[2]</code>)， ... ，直到第一个空值。


<p>
<hr><h3><a name="pdf-load"><code>load (chunk [, chunkname [, mode [, env]]])</code></a></h3>


<p>
加载一个代码块。


<p>
如果 <code>chunk</code> 是一个字符串，代码块指这个字符串。
如果 <code>chunk</code> 是一个函数，
<code>load</code> 不断地调用它获取代码块的片断。
每次对 <code>chunk</code> 的调用都必须返回一个字符串紧紧连接在上次调用的返回串之后。
当返回空串、<b>nil</b>、或是不返回值时，都表示代码块结束。


<p>
如果没有语法错误，
则以函数形式返回编译好的代码块；
否则，返回 <b>nil</b> 加上错误消息。


<p>
如果结果函数有上值，
<code>env</code> 被设为第一个上值。
若不提供此参数，将全局环境替代它。
所有其它上值初始化为 <b>nil</b>。
（当你加载主代码块时候，结果函数一定有且仅有一个上值 <code>_ENV</code> 
（参见 <a href="#2.2">&sect;2.2</a>））。
然而，如果你加载一个用函数（参见 <a href="#pdf-string.dump"><code>string.dump</code></a>，
结果函数可以有任意数量的上值）
创建出来的二进制代码块时，所有的上值都是新创建出来的。
也就是说它们不会和别的任何函数共享。


<p>
<code>chunkname</code> 在错误消息和调试消息中（参见 <a href="#4.9">&sect;4.9</a>），用于代码块的名字。
如果不提供此参数，它默认为字符串<code>chunk</code> 。
<code>chunk</code> 不是字符串时，则为 "<code>=(load)</code>" 。


<p>
字符串 <code>mode</code> 用于控制代码块是文本还是二进制（即预编译代码块）。
它可以是字符串 "<code>b</code>" （只能是二进制代码块），
"<code>t</code>" （只能是文本代码块），
或 "<code>bt</code>" （可以是二进制也可以是文本）。
默认值为 "<code>bt</code>"。


<p>
Lua 不会对二进制代码块做健壮性检查。
恶意构造一个二进制块有可能把解释器弄崩溃。


<p>
<hr><h3><a name="pdf-loadfile"><code>loadfile ([filename [, mode [, env]]])</code></a></h3>


<p>
和 <a href="#pdf-load"><code>load</code></a> 类似，
不过是从文件 <code>filename</code> 或标准输入（如果文件名未提供）中获取代码块。


<p>
<hr><h3><a name="pdf-next"><code>next (table [, index])</code></a></h3>


<p>
运行程序来遍历表中的所有域。
第一个参数是要遍历的表，第二个参数是表中的某个键。
<code>next</code> 返回该键的下一个键及其关联的值。
如果用 <b>nil</b> 作为第二个参数调用 <code>next</code>
将返回初始键及其关联值。
当以最后一个键去调用，或是以 <b>nil</b> 调用一张空表时，
<code>next</code> 返回 <b>nil</b>。
如果不提供第二个参数，将认为它就是 <b>nil</b>。
特别指出，你可以用 <code>next(t)</code> 来判断一张表是否是空的。


<p>
索引在遍历过程中的次序无定义，
<em>即使是数字索引也是这样</em>。
（如果想按数字次序遍历表，可以使用数字形式的 <b>for</b> 。）


<p>
当在遍历过程中你给表中并不存在的域赋值，
<code>next</code> 的行为是未定义的。
然而你可以去修改那些已存在的域。
特别指出，你可以清除一些已存在的域。


<p>
<hr><h3><a name="pdf-pairs"><code>pairs (t)</code></a></h3>


<p>
如果 <code>t</code> 有元方法 <code>__pairs</code>，
以 <code>t</code> 为参数调用它，并返回其返回的前三个值。


<p>
否则，返回三个值：<a href="#pdf-next"><code>next</code></a> 函数，
表 <code>t</code>，以及 <b>nil</b>。
因此以下代码

<pre>
     for k,v in pairs(t) do <em>body</em> end
</pre><p>
能迭代表 <code>t</code> 中的所有键值对。


<p>
参见函数 <a href="#pdf-next"><code>next</code></a> 中关于迭代过程中修改表的风险。


<p>
<hr><h3><a name="pdf-pcall"><code>pcall (f [, arg1, &middot;&middot;&middot;])</code></a></h3>


<p>
传入参数，以 <em>保护模式</em> 调用函数 <code>f</code> 。
这意味着 <code>f</code> 中的任何错误不会抛出；
取而代之的是，<code>pcall</code> 会将错误捕获到，并返回一个状态码。
第一个返回值是状态码（一个布尔量），
当没有错误时，其为真。
此时，<code>pcall</code> 同样会在状态码后返回所有调用的结果。
在有错误时，<code>pcall</code> 返回 <b>false</b> 加错误消息。


<p>
<hr><h3><a name="pdf-print"><code>print (&middot;&middot;&middot;)</code></a></h3>
接收任意数量的参数，并将它们的值打印到 <code>stdout</code>。
它用 <a href="#pdf-tostring"><code>tostring</code></a> 函数将每个参数都转换为字符串。
<code>print</code> 不用于做格式化输出。仅作为看一下某个值的快捷方式。
多用于调试。
完整的对输出的控制，请使用 <a href="#pdf-string.format"><code>string.format</code></a> 以及 <a href="#pdf-io.write"><code>io.write</code></a>。


<p>
<hr><h3><a name="pdf-rawequal"><code>rawequal (v1, v2)</code></a></h3>
在不触发任何元方法的情况下
检查 <code>v1</code> 是否和 <code>v2</code> 相等。
返回一个布尔量。


<p>
<hr><h3><a name="pdf-rawget"><code>rawget (table, index)</code></a></h3>
在不触发任何元方法的情况下
获取 <code>table[index]</code> 的值。
<code>table</code> 必须是一张表；
<code>index</code> 可以是任何值。


<p>
<hr><h3><a name="pdf-rawlen"><code>rawlen (v)</code></a></h3>
在不触发任何元方法的情况下
返回对象 <code>v</code> 的长度。
<code>v</code> 可以是表或字符串。
它返回一个整数。


<p>
<hr><h3><a name="pdf-rawset"><code>rawset (table, index, value)</code></a></h3>
在不触发任何元方法的情况下
将 <code>table[index]</code> 设为 <code>value</code>。
<code>table</code> 必须是一张表，
<code>index</code> 可以是 <b>nil</b> 与 NaN 之外的任何值。
<code>value</code> 可以是任何 Lua 值。


<p>
这个函数返回 <code>table</code>。


<p>
<hr><h3><a name="pdf-select"><code>select (index, &middot;&middot;&middot;)</code></a></h3>


<p>
如果 <code>index</code> 是个数字，
那么返回参数中第 <code>index</code> 个之后的部分；
负的数字会从后向前索引（-1 指最后一个参数）。
否则，<code>index</code> 必须是字符串 <code>"#"</code>，
此时 <code>select</code> 返回参数的个数。


<p>
<hr><h3><a name="pdf-setmetatable"><code>setmetatable (table, metatable)</code></a></h3>


<p>
给指定表设置元表。
（你不能在 Lua 中改变其它类型值的元表，那些只能在 C 里做。）
如果 <code>metatable</code> 是 <b>nil</b>，
将指定表的元表移除。
如果原来那张元表有 <code>"__metatable"</code> 域，抛出一个错误。


<p>
这个函数返回 <code>table</code>。


<p>
<hr><h3><a name="pdf-tonumber"><code>tonumber (e [, base])</code></a></h3>


<p>
如果调用的时候没有 <code>base</code>，
<code>tonumber</code> 尝试把参数转换为一个数字。
如果参数已经是一个数字，或是一个可以转换为数字的字符串，
<code>tonumber</code> 就返回这个数字；
否则返回 <b>nil</b>。


<p>
字符串的转换结果可能是整数也可能是浮点数，
这取决于 Lua 的转换文法（参见 <a href="#3.1">&sect;3.1</a>）。
（字符串可以有前置和后置的空格，可以带符号。）


<p>
当传入 <code>base</code> 调用它时，
<code>e</code> 必须是一个以该进制表示的整数字符串。
进制可以是 2 到 36 （包含 2 和 36）之间的任何整数。
大于 10 进制时，字母 '<code>A</code>' （大小写均可）表示 10 ，
'<code>B</code>' 表示 11，依次到 '<code>Z</code>' 表示 35 。
如果字符串 <code>e</code> 不是该进制下的合法数字，
函数返回 <b>nil</b>。


<p>
<hr><h3><a name="pdf-tostring"><code>tostring (v)</code></a></h3>
可以接收任何类型，它将其转换为人可阅读的字符串形式。
浮点数总被转换为浮点数的表现形式（小数点形式或是指数形式）。
（如果想完全控制数字如何被转换，可以使用
<a href="#pdf-string.format"><code>string.format</code></a>。）


<p>
如果 <code>v</code> 有 <code>"__tostring"</code> 域的元表，
<code>tostring</code> 会以 <code>v</code> 为参数调用它。
并用它的结果作为返回值。


<p>
<hr><h3><a name="pdf-type"><code>type (v)</code></a></h3>
将参数的类型编码为一个字符串返回。
函数可能的返回值有
"<code>nil</code>" （一个字符串，而不是 <b>nil</b> 值），
"<code>number</code>"，
"<code>string</code>"，
"<code>boolean</code>"，
"<code>table</code>"，
"<code>function</code>"，
"<code>thread</code>"，
"<code>userdata</code>"。


<p>
<hr><h3><a name="pdf-_VERSION"><code>_VERSION</code></a></h3>
一个包含有当前解释器版本号的全局变量（并非函数）。
当前这个变量的值为 "<code>Lua 5.3</code>"。


<p>
<hr><h3><a name="pdf-xpcall"><code>xpcall (f, msgh [, arg1, &middot;&middot;&middot;])</code></a></h3>


<p>
这个函数和 <a href="#pdf-pcall"><code>pcall</code></a> 类似。
不过它可以额外设置一个消息处理器 <code>msgh</code>。


<h2>6.2 &ndash; <a name="6.2">协程管理</a></h2>

<p>
关于协程的操作作为基础库的一个子库，
被放在一个独立表 <a name="pdf-coroutine"><code>coroutine</code></a> 中。
协程的介绍参见 <a href="#2.6">&sect;2.6</a> 。


<p>
<hr><h3><a name="pdf-coroutine.create"><code>coroutine.create (f)</code></a></h3>


<p>
创建一个主体函数为 <code>f</code> 的新协程。
<code>f</code> 必须是一个 Lua 的函数。
返回这个新协程，它是一个类型为 <code>"thread"</code> 的对象。


<p>
<hr><h3><a name="pdf-coroutine.isyieldable"><code>coroutine.isyieldable ()</code></a></h3>


<p>
如果正在运行的协程可以让出，则返回真。


<p>
不在主线程中或不在一个无法让出的 C 函数中时，当前协程是可让出的。


<p>
<hr><h3><a name="pdf-coroutine.resume"><code>coroutine.resume (co [, val1, &middot;&middot;&middot;])</code></a></h3>


<p>
开始或继续协程 <code>co</code> 的运行。
当你第一次延续一个协程，它会从主体函数处开始运行。
<code>val1</code>, ... 这些值会以参数形式传入主体函数。
如果该协程被让出，<code>resume</code> 会重新启动它；
<code>val1</code>, ... 这些参数会作为让出点的返回值。


<p>
如果协程运行起来没有错误，
<code>resume</code> 返回 <b>true</b> 加上传给 <code>yield</code> 的所有值
（当协程让出），
或是主体函数的所有返回值（当协程中止）。
如果有任何错误发生，
<code>resume</code> 返回 <b>false</b> 加错误消息。


<p>
<hr><h3><a name="pdf-coroutine.running"><code>coroutine.running ()</code></a></h3>


<p>
返回当前正在运行的协程加一个布尔量。
如果当前运行的协程是主线程，其为真。


<p>
<hr><h3><a name="pdf-coroutine.status"><code>coroutine.status (co)</code></a></h3>


<p>
以字符串形式返回协程 <code>co</code> 的状态：
当协程正在运行（它就是调用 <code>status</code> 的那个） ，返回 <code>"running"</code>；
如果协程调用 <code>yield</code> 挂起或是还没有开始运行，返回 <code>"suspended"</code>；
如果协程是活动的，但并不在运行（即它正在延续其它协程），返回 <code>"normal"</code>；
如果协程运行完主体函数或因错误停止，返回 <code>"dead"</code>。


<p>
<hr><h3><a name="pdf-coroutine.wrap"><code>coroutine.wrap (f)</code></a></h3>


<p>
创建一个主体函数为 <code>f</code> 的新协程。
<code>f</code> 必须是一个 Lua 的函数。
返回一个函数，
每次调用该函数都会延续该协程。
传给这个函数的参数都会作为 <code>resume</code> 的额外参数。
和 <code>resume</code> 返回相同的值，
只是没有第一个布尔量。
如果发生任何错误，抛出这个错误。


<p>
<hr><h3><a name="pdf-coroutine.yield"><code>coroutine.yield (&middot;&middot;&middot;)</code></a></h3>


<p>
挂起正在调用的协程的执行。
传递给 <code>yield</code> 的参数都会转为 <code>resume</code> 的额外返回值。


<h2>6.3 &ndash; <a name="6.3">模块</a></h2>

<p>
包管理库提供了从 Lua 中加载模块的基础库。
只有一个导出函数直接放在全局环境中：
<a href="#pdf-require"><code>require</code></a>。
所有其它的部分都导出在表 <a name="pdf-package"><code>package</code></a> 中。


<p>
<hr><h3><a name="pdf-require"><code>require (modname)</code></a></h3>


<p>
加载一个模块。
这个函数首先查找 <a href="#pdf-package.loaded"><code>package.loaded</code></a> 表，
检测 <code>modname</code> 是否被加载过。
如果被加载过，<code>require</code> 返回 <code>package.loaded[modname]</code> 中保存的值。
否则，它试着为模块寻找 <em>加载器</em> 。


<p>

<code>require</code> 遵循 <a href="#pdf-package.searchers"><code>package.searchers</code></a> 序列的指引来查找加载器。
如果改变这个序列，我们可以改变 <code>require</code> 如何查找一个模块。
下列说明基于 <a href="#pdf-package.searchers"><code>package.searchers</code></a>
的默认配置。


<p>
首先 <code>require</code> 查找 <code>package.preload[modname]</code> 。
如果这里有一个值，这个值（必须是一个函数）就是那个加载器。
否则 <code>require</code> 使用 Lua 加载器去查找
<a href="#pdf-package.path"><code>package.path</code></a> 的路径。
如果查找失败，接着使用 C 加载器去查找
<a href="#pdf-package.cpath"><code>package.cpath</code></a> 的路径。
如果都失败了，再尝试 <em>一体化</em> 加载器 （参见 <a href="#pdf-package.searchers"><code>package.searchers</code></a>）。


<p>
每次找到一个加载器，<code>require</code> 都用两个参数调用加载器：
<code>modname</code> 和一个在获取加载器过程中得到的参数。
（如果通过查找文件得到的加载器，这个额外参数是文件名。）
如果加载器返回非空值，
<code>require</code> 将这个值赋给 <code>package.loaded[modname]</code>。
如果加载器没能返回一个非空值用于赋给 <code>package.loaded[modname]</code>，
<code>require</code> 会在那里设入 <b>true</b> 。
无论是什么情况，<code>require</code> 都会返回
<code>package.loaded[modname]</code> 的最终值。


<p>
如果在加载或运行模块时有错误，
或是无法为模块找到加载器，
<code>require</code> 都会抛出错误。


<p>
<hr><h3><a name="pdf-package.config"><code>package.config</code></a></h3>


<p>
一个描述有一些为包管理准备的编译期配置信息的串。
这个字符串由一系列行构成：

<ul>

<li>第一行是目录分割串。
对于 Windows 默认是 '<code>\</code>' ，对于其它系统是 '<code>/</code>' 。</li>

<li>第二行是用于路径中的分割符。默认值是 '<code>;</code>' 。</li>

<li>第三行是用于标记模板替换点的字符串。
默认是 '<code>?</code>' 。</li>

<li>第四行是在 Windows 中将被替换成执行程序所在目录的路径的字符串。
默认是 '<code>!</code>' 。</li>

<li>第五行是一个记号，该记号之后的所有文本将在构建 <code>luaopen_</code> 函数名时被忽略掉。
默认是 '<code>-</code>'。</li>

</ul>


<p>
<hr><h3><a name="pdf-package.cpath"><code>package.cpath</code></a></h3>


<p>
这个路径被 <a href="#pdf-require"><code>require</code></a> 在 C 加载器中做搜索时用到。


<p>
Lua 用和初始化 Lua 路径 <a href="#pdf-package.path"><code>package.path</code></a>
相同的方式初始化 C 路径 <a href="#pdf-package.cpath"><code>package.cpath</code></a> 。
它会使用环境变量 <a name="pdf-LUA_CPATH_5_3"><code>LUA_CPATH_5_3</code></a> 或
环境变量 <a name="pdf-LUA_CPATH"><code>LUA_CPATH</code></a> 初始化。
要么就采用 <code>luaconf.h</code> 中定义的默认路径。


<p>
<hr><h3><a name="pdf-package.loaded"><code>package.loaded</code></a></h3>


<p>
用于 <a href="#pdf-require"><code>require</code></a> 控制哪些模块已经被加载的表。
当你请求一个 <code>modname</code> 模块，且
<code>package.loaded[modname]</code> 不为假时，
<a href="#pdf-require"><code>require</code></a> 简单返回储存在内的值。


<p>
这个变量仅仅是对真正那张表的引用；
改变这个值并不会改变 <a href="#pdf-require"><code>require</code></a> 使用的表。


<p>
<hr><h3><a name="pdf-package.loadlib"><code>package.loadlib (libname, funcname)</code></a></h3>


<p>
让宿主程序动态链接 C 库 <code>libname</code> 。


<p>
当 <code>funcname</code> 为 "<code>*</code>"，
它仅仅连接该库，让库中的符号都导出给其它动态链接库使用。
否则，它查找库中的函数 <code>funcname</code> ，以 C 函数的形式返回这个函数。
因此，<code>funcname</code> 必须遵循原型 <a href="#lua_CFunction"><code>lua_CFunction</code></a> 
（参见 <a href="#lua_CFunction"><code>lua_CFunction</code></a>）。


<p>
这是一个低阶函数。
它完全绕过了包模块系统。
和 <a href="#pdf-require"><code>require</code></a> 不同，
它不会做任何路径查询，也不会自动加扩展名。
<code>libname</code> 必须是一个 C 库需要的完整的文件名，如果有必要，需要提供路径和扩展名。
<code>funcname</code> 必须是 C 库需要的准确名字
（这取决于使用的 C 编译器和链接器）。


<p>
这个函数在标准 C 中不支持。
因此，它只在部分平台有效
（ Windows ，Linux ，Mac OS X, Solaris, BSD, 加上支持
<code>dlfcn</code> 标准的 Unix 系统）。


<p>
<hr><h3><a name="pdf-package.path"><code>package.path</code></a></h3>


<p>
这个路径被 <a href="#pdf-require"><code>require</code></a> 在 Lua 加载器中做搜索时用到。


<p>
在启动时，Lua 用环境变量 <a name="pdf-LUA_PATH_5_3"><code>LUA_PATH_5_3</code></a>
或环境变量 <a name="pdf-LUA_PATH"><code>LUA_PATH</code></a> 来初始化这个变量。
或采用 <code>luaconf.h</code> 中的默认路径。
环境变量中出现的所有 "<code>;;</code>" 都会被替换成默认路径。


<p>
<hr><h3><a name="pdf-package.preload"><code>package.preload</code></a></h3>


<p>
保存有一些特殊模块的加载器
（参见 <a href="#pdf-require"><code>require</code></a>）。


<p>
这个变量仅仅是对真正那张表的引用；
改变这个值并不会改变 <a href="#pdf-require"><code>require</code></a> 使用的表。


<p>
<hr><h3><a name="pdf-package.searchers"><code>package.searchers</code></a></h3>


<p>
用于 <a href="#pdf-require"><code>require</code></a> 控制如何加载模块的表。


<p>
这张表内的每一项都是一个 <em>查找器函数</em>。
当查找一个模块时，
<a href="#pdf-require"><code>require</code></a> 按次序调用这些查找器，
并传入模块名（<a href="#pdf-require"><code>require</code></a> 的参数）作为唯一的一个参数。
此函数可以返回另一个函数（模块的 <em>加载器</em>）加上另一个将传递给这个加载器的参数。
或是返回一个描述为何没有找到这个模块的字符串
（或是返回 <b>nil</b> 什么也不想说）。


<p>
Lua 用四个查找器函数初始化这张表。


<p>
第一个查找器就是简单的在 <a href="#pdf-package.preload"><code>package.preload</code></a> 表中查找加载器。


<p>
第二个查找器用于查找 Lua 库的加载库。
它使用储存在 <a href="#pdf-package.path"><code>package.path</code></a> 中的路径来做查找工作。
查找过程和函数 <a href="#pdf-package.searchpath"><code>package.searchpath</code></a> 描述的一致。


<p>
第三个查找器用于查找 C 库的加载库。
它使用储存在 <a href="#pdf-package.path"><code>package.cpath</code></a> 中的路径来做查找工作。
同样，
查找过程和函数 <a href="#pdf-package.searchpath"><code>package.searchpath</code></a> 描述的一致。
例如，如果 C 路径是这样一个字符串

<pre>
     "./?.so;./?.dll;/usr/local/?/init.so"
</pre><p>
查找器查找模块 <code>foo</code> 
会依次尝试打开文件 <code>./foo.so</code>，<code>./foo.dll</code>，
以及 <code>/usr/local/foo/init.so</code>。
一旦它找到一个 C 库，
查找器首先使用动态链接机制连接该库。
然后尝试在该库中找到可以用作加载器的 C 函数。
这个 C 函数的名字是 "<code>luaopen_</code>" 紧接模块名的字符串，
其中字符串中所有的下划线都会被替换成点。
此外，如果模块名中有横线，
横线后面的部分（包括横线）都被去掉。
例如，如果模块名为 <code>a.b.c-v2.1</code>，
函数名就是 <code>luaopen_a_b_c</code>。


<p>
第四个搜索器是　<em>一体化加载器</em>。
它从 C 路径中查找指定模块的根名字。
例如，当请求 <code>a.b.c</code>　时，
它将查找 <code>a</code> 这个 C 库。
如果找得到，它会在里面找子模块的加载函数。
在我们的例子中，就是找　<code>luaopen_a_b_c</code>。
利用这个机制，可以把若干 C 子模块打包进单个库。
每个子模块都可以有原本的加载函数名。


<p>
除了第一个（预加载）搜索器外，每个搜索器都会返回
它找到的模块的文件名。
这和 <a href="#pdf-package.searchpath"><code>package.searchpath</code></a> 的返回值一样。
第一个搜索器没有返回值。


<p>
<hr><h3><a name="pdf-package.searchpath"><code>package.searchpath (name, path [, sep [, rep]])</code></a></h3>


<p>
在指定 <code>path</code> 中搜索指定的 <code>name</code> 。


<p>
路径是一个包含有一系列以分号分割的 <em>模板</em> 构成的字符串。
对于每个模板，都会用 <code>name</code> 替换其中的每个问号（如果有的话）。
且将其中的 <code>sep</code> （默认是点）替换为  <code>rep</code>
（默认是系统的目录分割符）。
然后尝试打开这个文件名。


<p>
例如，如果路径是字符串

<pre>
     "./?.lua;./?.lc;/usr/local/?/init.lua"
</pre><p>
搜索 <code>foo.a</code>　这个名字将
依次尝试打开文件
<code>./foo/a.lua</code>　， <code>./foo/a.lc</code>　，以及
<code>/usr/local/foo/a/init.lua</code>。


<p>
返回第一个可以用读模式打开（并马上关闭该文件）的文件的名字。
如果不存在这样的文件，返回 <b>nil</b> 加上错误消息。
（这条错误消息列出了所有尝试打开的文件名。）


<h2>6.4 &ndash; <a name="6.4">字符串处理</a></h2>

<p>
这个库提供了字符串处理的通用函数。
例如字符串查找、子串、模式匹配等。
当在 Lua 中对字符串做索引时，第一个字符从 1 开始计算（而不是 C 里的 0 ）。
索引可以是负数，它指从字符串末尾反向解析。
即，最后一个字符在 -1 位置处，等等。


<p>
字符串库中的所有函数都在表 <a name="pdf-string"><code>string</code></a> 中。
它还将其设置为字符串元表的 <code>__index</code> 域。
因此，你可以以面向对象的形式使用字符串函数。
例如，<code>string.byte(s,i)</code> 可以写成 <code>s:byte(i)</code>。


<p>
字符串库假定采用单字节字符编码。


<p>
<hr><h3><a name="pdf-string.byte"><code>string.byte (s [, i [, j]])</code></a></h3>
返回字符 <code>s[i]</code>，
<code>s[i+1]</code>， ...　，<code>s[j]</code>
的内部数字编码。
<code>i</code> 的默认值是 1 ；
<code>j</code> 的默认值是 <code>i</code>。
这些索引以函数 <a href="#pdf-string.sub"><code>string.sub</code></a> 的规则修正。


<p>
数字编码没有必要跨平台。


<p>
<hr><h3><a name="pdf-string.char"><code>string.char (&middot;&middot;&middot;)</code></a></h3>
接收零或更多的整数。
返回和参数数量相同长度的字符串。
其中每个字符的内部编码值等于对应的参数值。

<p>
数字编码没有必要跨平台。


<p>
<hr><h3><a name="pdf-string.dump"><code>string.dump (function [, strip])</code></a></h3>


<p>
返回包含有以二进制方式表示的（一个 <em>二进制代码块</em> ）指定函数的字符串。
之后可以用 <a href="#pdf-load"><code>load</code></a> 调用这个字符串获得
该函数的副本（但是绑定新的上值）。
如果　<code>strip</code> 为真值，
二进制代码块不携带该函数的调试信息
（局部变量名，行号，等等。）。


<p>
带上值的函数只保存上值的数目。
当（再次）加载时，这些上值被更新为 <b>nil</b> 的实例。
（你可以使用调试库按你需要的方式来序列化上值，并重载到函数中）


<p>
<hr><h3><a name="pdf-string.find"><code>string.find (s, pattern [, init [, plain]])</code></a></h3>


<p>
查找第一个字符串 <code>s</code> 中匹配到的 <code>pattern</code>
（参见 <a href="#6.4.1">&sect;6.4.1</a>）。
如果找到一个匹配，<code>find</code> 会返回 <code>s</code>
中关于它起始及终点位置的索引；
否则，返回 <b>nil</b>。
第三个可选数字参数 <code>init</code>
指明从哪里开始搜索；
默认值为 1 ，同时可以是负值。
第四个可选参数 <code>plain</code> 为 <b>true</b> 时，
关闭模式匹配机制。
此时函数仅做直接的 “查找子串”的操作，
而 <code>pattern</code> 中没有字符被看作魔法字符。
注意，如果给定了 <code>plain</code>　，就必须写上 <code>init</code> 。


<p>
如果在模式中定义了捕获，捕获到的若干值也会在两个索引之后返回。


<p>
<hr><h3><a name="pdf-string.format"><code>string.format (formatstring, &middot;&middot;&middot;)</code></a></h3>


<p>
返回不定数量参数的格式化版本，
格式化串为第一个参数（必须是一个字符串）。
格式化字符串遵循 ISO C 函数 <code>sprintf</code> 的规则。
不同点在于选项
<code>*</code>, <code>h</code>, <code>L</code>, <code>l</code>, <code>n</code>,
<code>p</code> 不支持，
另外还增加了一个选项 <code>q</code>。
<code>q</code> 选项将一个字符串格式化为两个双引号括起，对内部字符做恰当的转义处理的字符串。
该字符串可以安全的被 Lua 解释器读回来。
例如，调用

<pre>
     string.format('%q', 'a string with "quotes" and \n new line')
</pre><p>
会产生字符串：

<pre>
     "a string with \"quotes\" and \
      new line"
</pre>

<p>
选项
<code>A</code> and <code>a</code> （如果有的话），
<code>E</code>, <code>e</code>, <code>f</code>,
<code>G</code>, and <code>g</code> 都期待一个对应的数字参数。
选项 <code>c</code>, <code>d</code>,
<code>i</code>, <code>o</code>, <code>u</code>, <code>X</code>, and <code>x</code>
则期待一个整数。
选项 <code>q</code> 期待一个字符串；
选项 <code>s</code> 期待一个没有内嵌零的字符串。
如果选项 <code>s</code> 对应的参数不是字符串，它会用和
<a href="#pdf-tostring"><code>tostring</code></a> 一致的规则转换成字符串。


<p>
<hr><h3><a name="pdf-string.gmatch"><code>string.gmatch (s, pattern)</code></a></h3>
返回一个迭代器函数。
每次调用这个函数都会继续以 <code>pattern</code> （参见　<a href="#6.4.1">&sect;6.4.1</a>）
对 <code>s</code> 做匹配，并返回所有捕获到的值。
如果 <code>pattern</code> 中没有指定捕获，则每次捕获整个 <code>pattern</code>。


<p>
下面这个例子会循环迭代字符串 <code>s</code> 中所有的单词，
并逐行打印：

<pre>
     s = "hello world from Lua"
     for w in string.gmatch(s, "%a+") do
       print(w)
     end
</pre><p>
下一个例子从指定的字符串中收集所有的键值对
<code>key=value</code>
置入一张表：

<pre>
     t = {}
     s = "from=world, to=Lua"
     for k, v in string.gmatch(s, "(%w+)=(%w+)") do
       t[k] = v
     end
</pre>

<p>
对这个函数来说，模板前开始的 '<code>^</code>' 不会当成锚点。因为这样会阻止迭代。


<p>
<hr><h3><a name="pdf-string.gsub"><code>string.gsub (s, pattern, repl [, n])</code></a></h3>
将字符串 <code>s</code> 中，所有的（或是在 <code>n</code> 给出时的前 <code>n</code> 个）
<code>pattern</code> （参见
 <a href="#6.4.1">&sect;6.4.1</a>）都替换成 <code>repl</code> ，并返回其副本。
<code>repl</code> 可以是字符串、表、或函数。
<code>gsub</code> 还会在第二个返回值返回一共发生了多少次匹配。
<code>gsub</code> 这个名字来源于 <em>Global SUBstitution</em> 。


<p>
如果 <code>repl</code> 是一个字符串，那么把这个字符串作为替换品。
字符 <code>%</code> 是一个转义符：
<code>repl</code> 中的所有形式为 <code>%<em>d</em></code> 的串表示
第 <em>d</em> 个捕获到的子串，<em>d</em> 可以是 1 到 9 。
串 <code>%0</code> 表示整个匹配。
串 <code>%%</code> 表示单个 <code>%</code>。


<p>
如果 <code>repl</code> 是张表，每次匹配时都会用第一个捕获物作为键去查这张表。


<p>
如果 <code>repl</code> 是个函数，则在每次匹配发生时都会调用这个函数。
所有捕获到的子串依次作为参数传入。


<p>
任何情况下，模板中没有设定捕获都看成是捕获整个模板。


<p>
如果表的查询结果或函数的返回结果是一个字符串或是个数字，
都将其作为替换用串；
而在返回 <b>false</b> 或 <b>nil</b>　时不作替换
（即保留匹配前的原始串）。


<p>
这里有一些用例：

<pre>
     x = string.gsub("hello world", "(%w+)", "%1 %1")
     --&gt; x="hello hello world world"
     
     x = string.gsub("hello world", "%w+", "%0 %0", 1)
     --&gt; x="hello hello world"
     
     x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1")
     --&gt; x="world hello Lua from"
     
     x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv)
     --&gt; x="home = /home/roberto, user = roberto"
     
     x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s)
           return load(s)()
         end)
     --&gt; x="4+5 = 9"
     
     local t = {name="lua", version="5.3"}
     x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t)
     --&gt; x="lua-5.3.tar.gz"
</pre>


<p>
<hr><h3><a name="pdf-string.len"><code>string.len (s)</code></a></h3>
接收一个字符串，返回其长度。
空串 <code>""</code> 的长度为 0 。
内嵌零也统计在内，因此
<code>"a\000bc\000"</code> 的长度为 5 。


<p>
<hr><h3><a name="pdf-string.lower"><code>string.lower (s)</code></a></h3>
接收一个字符串，将其中的大写字符都转为小写后返回其副本。
其它的字符串不会更改。
对大写字符的定义取决于当前的区域设置。


<p>
<hr><h3><a name="pdf-string.match"><code>string.match (s, pattern [, init])</code></a></h3>
在字符串 <code>s</code> 中找到第一个能用 <code>pattern</code>
（参见 <a href="#6.4.1">&sect;6.4.1</a>）匹配到的部分。
如果能找到，<code>match</code> 返回其中的捕获物；
否则返回 <b>nil</b> 。
如果 <code>pattern</code> 中未指定捕获，
返回整个 <code>pattern</code> 捕获到的串。
第三个可选数字参数 <code>init</code>
指明从哪里开始搜索；
它默认为 1 且可以是负数。


<p>
<hr><h3><a name="pdf-string.pack"><code>string.pack (fmt, v1, v2, &middot;&middot;&middot;)</code></a></h3>


<p>
返回一个打包了（即以二进制形式序列化） <code>v1</code>, <code>v2</code> 等值的二进制字符串。
字符串 <code>fmt</code> 为打包格式（参见 <a href="#6.4.2">&sect;6.4.2</a>）。


<p>
<hr><h3><a name="pdf-string.packsize"><code>string.packsize (fmt)</code></a></h3>


<p>
返回以指定格式用 <a href="#pdf-string.pack"><code>string.pack</code></a>
打包的字符串的长度。
格式化字符串中不可以有变长选项 '<code>s</code>' 或 '<code>z</code>'
（参见 <a href="#6.4.2">&sect;6.4.2</a>）。


<p>
<hr><h3><a name="pdf-string.rep"><code>string.rep (s, n [, sep])</code></a></h3>
返回 <code>n</code> 个字符串 <code>s</code> 以字符串 <code>sep</code>
为分割符连在一起的字符串。
默认的 <code>sep</code> 值为空字符串（即没有分割符）。
如果 <code>n</code> 不是正数则返回空串。


<p>
<hr><h3><a name="pdf-string.reverse"><code>string.reverse (s)</code></a></h3>
返回字符串 <code>s</code> 的翻转串。


<p>
<hr><h3><a name="pdf-string.sub"><code>string.sub (s, i [, j])</code></a></h3>
返回 <code>s</code> 的子串，
该子串从 <code>i</code> 开始到 <code>j</code> 为止；
<code>i</code> 和 <code>j</code> 都可以为负数。
如果不给出 <code>j</code> ，就当它是 -1 
（和字符串长度相同）。
特别是，
调用 <code>string.sub(s,1,j)</code> 可以返回 <code>s</code>
的长度为 <code>j</code> 的前缀串，
而 <code>string.sub(s, -i)</code> 返回长度为 <code>i</code>
的后缀串。


<p>
如果在对负数索引转义后 <code>i</code> 小于 1 的话，就修正回 1 。
如果 <code>j</code> 比字符串的长度还大，就修正为字符串长度。
如果在修正之后，<code>i</code> 大于 <code>j</code>，
函数返回空串。


<p>
<hr><h3><a name="pdf-string.unpack"><code>string.unpack (fmt, s [, pos])</code></a></h3>


<p>
返回以格式 <code>fmt</code> （参见 <a href="#6.4.2">&sect;6.4.2</a>）
打包在字符串 <code>s</code> （参见 <a href="#pdf-string.pack"><code>string.pack</code></a>）
中的值。
选项 <code>pos</code>（默认为 1 ）标记了从 <code>s</code>
中哪里开始读起。
读完所有的值后，函数返回 <code>s</code> 中第一个未读字节的位置。


<p>
<hr><h3><a name="pdf-string.upper"><code>string.upper (s)</code></a></h3>
接收一个字符串，将其中的小写字符都转为大写后返回其副本。
其它的字符串不会更改。
对小写字符的定义取决于当前的区域设置。


<h3>6.4.1 &ndash; <a name="6.4.1">匹配模式</a></h3>

<p>
Lua 中的匹配模式直接用常规的字符串来描述。
它用于模式匹配函数
<a href="#pdf-string.find"><code>string.find</code></a>,
<a href="#pdf-string.gmatch"><code>string.gmatch</code></a>,
<a href="#pdf-string.gsub"><code>string.gsub</code></a>,
<a href="#pdf-string.match"><code>string.match</code></a>。
这一节表述了这些字符串的语法及含义（即它能匹配到什么）。


<h4>字符类：</h4><p>
<em>字符类</em> 用于表示一个字符集合。
下列组合可用于字符类：

<ul>

<li><b><em>x</em>: </b>
（这里 <em>x</em> 不能是 <em>魔法字符</em> <code>^$()%.[]*+-?</code> 中的一员）
表示字符 <em>x</em> 自身。
</li>

<li><b><code>.</code>: </b> （一个点）可表示任何字符。</li>

<li><b><code>%a</code>: </b> 表示任何字母。</li>

<li><b><code>%c</code>: </b> 表示任何控制字符。</li>

<li><b><code>%d</code>: </b> 表示任何数字。</li>

<li><b><code>%g</code>: </b> 表示任何除空白符外的可打印字符。</li>

<li><b><code>%l</code>: </b> 表示所有小写字母。</li>

<li><b><code>%p</code>: </b> 表示所有标点符号。</li>

<li><b><code>%s</code>: </b> 表示所有空白字符。</li>

<li><b><code>%u</code>: </b> 表示所有大写字母。</li>

<li><b><code>%w</code>: </b> 表示所有字母及数字。</li>

<li><b><code>%x</code>: </b> 表示所有 16 进制数字符号。</li>

<li><b><code>%<em>x</em></code>: </b> 
（这里的 <em>x</em> 是任意非字母或数字的字符）
表示字符 <em>x</em>。
这是对魔法字符转义的标准方法。
所有非字母或数字的字符
（包括所有标点，也包括非魔法字符）
都可以用前置一个 '<code>%</code>' 放在模式串中表示自身。
</li>

<li><b><code>[<em>set</em>]</code>: </b>
表示 <em>set</em>　中所有字符的联合。
可以以 '<code>-</code>' 连接，升序书写范围两端的字符来表示一个范围的字符集。
上面提到的 <code>%</code><em>x</em> 形式也可以在 <em>set</em> 中使用
表示其中的一个元素。
其它出现在 <em>set</em> 中的字符则代表它们自己。
例如，<code>[%w_]</code> （或 <code>[_%w]</code>）
表示所有的字母数字加下划线），
<code>[0-7]</code> 表示 8 进制数字，
<code>[0-7%l%-]</code>　表示 8 进制数字加小写字母与 '<code>-</code>' 字符。


<p>
交叉使用类和范围的行为未定义。
因此，像 <code>[%a-z]</code> 或 <code>[a-%%]</code>
这样的模式串没有意义。
</li>

<li><b><code>[^<em>set</em>]</code>: </b>
表示 <em>set</em> 的补集，
其中 <em>set</em> 如上面的解释。
</li>

</ul><p>
所有单个字母表示的类别（<code>%a</code>，<code>%c</code>，等），
若将其字母改为大写，均表示对应的补集。
例如，<code>%S</code> 表示所有非空格的字符。


<p>
如何定义字母、空格、或是其他字符组取决于当前的区域设置。
特别注意：<code>[a-z]</code>　未必等价于 <code>%l</code> 。


<h4>模式条目：</h4><p>
<em>模式条目</em> 可以是

<ul>

<li>
单个字符类匹配该类别中任意单个字符；
</li>

<li>
单个字符类跟一个 '<code>*</code>'，
将匹配零或多个该类的字符。
这个条目总是匹配尽可能长的串；
</li>

<li>
单个字符类跟一个 '<code>+</code>'，
将匹配一或更多个该类的字符。
这个条目总是匹配尽可能长的串；
</li>

<li>
单个字符类跟一个 '<code>-</code>'，
将匹配零或更多个该类的字符。
和 '<code>*</code>' 不同，
这个条目总是匹配尽可能短的串；
</li>

<li>
单个字符类跟一个 '<code>?</code>'，
将匹配零或一个该类的字符。
只要有可能，它会匹配一个；
</li>

<li>
<code>%<em>n</em></code>，
这里的 <em>n</em> 可以从 1 到 9；
这个条目匹配一个等于 <em>n</em> 号捕获物（后面有描述）的子串。
</li>

<li>
<code>%b<em>xy</em></code>，
这里的 <em>x</em> 和 <em>y</em> 是两个明确的字符；
这个条目匹配以 <em>x</em> 开始 <em>y</em> 结束，
且其中 <em>x</em> 和 <em>y</em> 保持 <em>平衡</em> 的字符串。
意思是，如果从左到右读这个字符串，对每次读到一个
<em>x</em> 就 <em>+1</em> ，读到一个 <em>y</em> 就 <em>-1</em>，
最终结束处的那个 <em>y</em> 是第一个记数到 0 的 <em>y</em>。
举个例子，条目 <code>%b()</code> 可以匹配到括号平衡的表达式。
</li>

<li>
<code>%f[<em>set</em>]</code>，
指 <em>边境模式</em>；
这个条目会匹配到一个位于 <em>set</em> 内某个字符之前的一个空串，
且这个位置的前一个字符不属于 <em>set</em> 。
集合 <em>set</em> 的含义如前面所述。
匹配出的那个空串之开始和结束点的计算就看成该处有个字符
'<code>\0</code>' 一样。
</li>

</ul>


<h4>模式：</h4><p>
<em>模式</em> 指一个模式条目的序列。
在模式最前面加上符号 '<code>^</code>' 将锚定从字符串的开始处做匹配。
在模式最后面加上符号 '<code>$</code>' 将使匹配过程锚定到字符串的结尾。
如果 '<code>^</code>' 和 '<code>$</code>' 出现在其它位置，它们均没有特殊含义，只表示自身。


<h4>捕获：</h4><p>
模式可以在内部用小括号括起一个子模式；
这些子模式被称为 <em>捕获物</em>。
当匹配成功时，由 <em>捕获物</em> 匹配到的字符串中的子串被保存起来用于未来的用途。
捕获物以它们左括号的次序来编号。
例如，对于模式 <code>"(a*(.)%w(%s*))"</code> ，
字符串中匹配到 <code>"a*(.)%w(%s*)"</code> 的部分保存在第一个捕获物中
（因此是编号 1 ）；
由 "<code>.</code>" 匹配到的字符是 2 号捕获物，
匹配到 "<code>%s*</code>" 的那部分是 3 号。


<p>
作为一个特例，空的捕获 <code>()</code> 将捕获到当前字符串的位置（它是一个数字）。
例如，如果将模式 <code>"()aa()"</code> 作用到字符串
<code>"flaaap"</code> 上，将产生两个捕获物：
3 和 5 。


<h3>6.4.2 &ndash; <a name="6.4.2">打包和解包用到的格式串</a></h3>

<p>
用于 <a href="#pdf-string.pack"><code>string.pack</code></a>，
<a href="#pdf-string.packsize"><code>string.packsize</code></a>，
<a href="#pdf-string.unpack"><code>string.unpack</code></a>
的第一个参数。
它是一个描述了需要创建或读取的结构之布局。


<p>
格式串是由转换选项构成的序列。
这些转换选项列在后面：

<ul>
<li><b><code>&lt;</code>: </b>设为小端编码</li>
<li><b><code>&gt;</code>: </b>设为大端编码</li>
<li><b><code>=</code>: </b>大小端遵循本地设置</li>
<li><b><code>![<em>n</em>]</code>: </b>将最大对齐数设为 <code>n</code>
（默认遵循本地对齐设置）</li>
<li><b><code>b</code>: </b>一个有符号字节 (<code>char</code>)</li>
<li><b><code>B</code>: </b>一个无符号字节 (<code>char</code>)</li>
<li><b><code>h</code>: </b>一个有符号 <code>short</code> （本地大小）</li>
<li><b><code>H</code>: </b>一个无符号 <code>short</code> （本地大小）</li>
<li><b><code>l</code>: </b>一个有符号 <code>long</code> （本地大小）</li>
<li><b><code>L</code>: </b>一个无符号 <code>long</code> （本地大小）</li>
<li><b><code>j</code>: </b>一个 <code>lua_Integer</code></li>
<li><b><code>J</code>: </b>一个 <code>lua_Unsigned</code></li>
<li><b><code>T</code>: </b>一个 <code>size_t</code> （本地大小）</li>
<li><b><code>i[<em>n</em>]</code>: </b>一个 <code>n</code> 字节长（默认为本地大小）的有符号 <code>int</code></li>
<li><b><code>I[<em>n</em>]</code>: </b>一个 <code>n</code> 字节长（默认为本地大小）的无符号 <code>int</code></li>
<li><b><code>f</code>: </b>一个 <code>float</code> （本地大小）</li>
<li><b><code>d</code>: </b>一个 <code>double</code> （本地大小）</li>
<li><b><code>n</code>: </b>一个 <code>lua_Number</code></li>
<li><b><code>c<em>n</em></code>: </b><code>n</code>字节固定长度的字符串</li>
<li><b><code>z</code>: </b>零结尾的字符串</li>
<li><b><code>s[<em>n</em>]</code>: </b>长度加内容的字符串，其长度编码为一个 <code>n</code> 字节（默认是个 <code>size_t</code>） 长的无符号整数。</li>
<li><b><code>x</code>: </b>一个字节的填充</li>
<li><b><code>X<em>op</em></code>: </b>按选项 <code>op</code> 的方式对齐（忽略它的其它方面）的一个空条目</li>
<li><b>'<code> </code>': </b>（空格）忽略</li>
</ul><p>
（ "<code>[<em>n</em>]</code>" 表示一个可选的整数。）
除填充、空格、配置项（选项 "<code>xX &lt;=&gt;!</code>"）外，
每个选项都关联一个参数（对于 <a href="#pdf-string.pack"><code>string.pack</code></a>）
或结果（对于 <a href="#pdf-string.unpack"><code>string.unpack</code></a>）。


<p>
对于选项 "<code>!<em>n</em></code>", "<code>s<em>n</em></code>", "<code>i<em>n</em></code>", "<code>I<em>n</em></code>",
<code>n</code> 可以是 1 到 16 间的整数。
所有的整数选项都将做溢出检查；
<a href="#pdf-string.pack"><code>string.pack</code></a> 检查提供的值是否能用指定的字长表示；
<a href="#pdf-string.unpack"><code>string.unpack</code></a> 检查读出的值能否置入 Lua 整数中。


<p>
任何格式串都假设有一个 "<code>!1=</code>" 前缀，
即最大对齐为 1 （无对齐）且采用本地大小端设置。


<p>
对齐行为按如下规则工作：
对每个选项，格式化时都会填充一些字节直到数据从一个特定偏移处开始，
这个位置是该选项的大小和最大对齐数中较小的那个数的倍数；
这个较小值必须是 2 个整数次方。
选项 "<code>c</code>" 及 "<code>z</code>" 不做对齐处理；
选项 "<code>s</code>" 对对齐遵循其开头的整数。


<p>
<a href="#pdf-string.pack"><code>string.pack</code></a> 用零去填充
（<a href="#pdf-string.unpack"><code>string.unpack</code></a> 则忽略它）。


<h2>6.5 &ndash; <a name="6.5">UTF-8 支持</a></h2>

<p>
这个库提供了对 UTF-8 编码的基础支持。
所有的函数都放在表 <a name="pdf-utf8"><code>utf8</code></a> 中。
此库不提供除编码处理之外的任何 Unicode 支持。
所有需要了解字符含义的操作，比如字符分类，都不在此范畴。


<p>
除非另有说明，
当一个函数需要一个字节位置的参数时，
都假定这个位置要么从字节序列的开始计算，
要么从字符串长度加一的位置算。
和字符串库一样，负的索引从字符串末尾计起。


<p>
<hr><h3><a name="pdf-utf8.char"><code>utf8.char (&middot;&middot;&middot;)</code></a></h3>
接收零或多个整数，
将每个整数转换成对应的 UTF-8 字节序列，并返回这些序列连接到一起的字符串。


<p>
<hr><h3><a name="pdf-utf8.charpattern"><code>utf8.charpattern</code></a></h3>
用于精确匹配到一个 UTF-8 字节序列的模式（是一个字符串，并非函数）"<code>[\0-\x7F\xC2-\xF4][\x80-\xBF]*</code>"
（参见 <a href="#6.4.1">&sect;6.4.1</a>）。
它假定处理的对象是一个合法的 UTF-8 字符串。


<p>
<hr><h3><a name="pdf-utf8.codes"><code>utf8.codes (s)</code></a></h3>


<p>
返回一系列的值，可以让

<pre>
     for p, c in utf8.codes(s) do <em>body</em> end
</pre><p>
迭代出字符串 <code>s</code> 中所有的字符。
这里的 <code>p</code> 是位置（按字节数）而 <code>c</code> 是每个字符的编号。
如果处理到一个不合法的字节序列，将抛出一个错误。


<p>
<hr><h3><a name="pdf-utf8.codepoint"><code>utf8.codepoint (s [, i [, j]])</code></a></h3>
以整数形式返回 <code>s</code> 中
从位置 <code>i</code> 到 <code>j</code> 间（包括两端）
所有字符的编号。
默认的 <code>i</code> 为 1 ，默认的 <code>j</code> 为 <code>i</code>。
如果碰上不合法的字节序列，抛出一个错误。


<p>
<hr><h3><a name="pdf-utf8.len"><code>utf8.len (s [, i [, j]])</code></a></h3>
返回字符串 <code>s</code> 中
从位置 <code>i</code> 到 <code>j</code> 间 （包括两端）
UTF-8 字符的个数。
默认的 <code>i</code> 为 1 ，默认的 <code>j</code> 为 -1 。
如果它找到任何不合法的字节序列，
返回假值加上第一个不合法字节的位置。


<p>
<hr><h3><a name="pdf-utf8.offset"><code>utf8.offset (s, n [, i])</code></a></h3>
返回编码在 <code>s</code> 中的第 <code>n</code> 个字符的开始位置（按字节数）
（从位置 <code>i</code> 处开始统计）。
负 <code>n</code> 则取在位置 <code>i</code> 前的字符。
当 <code>n</code> 是非负数时，默认的 <code>i</code> 是 1，
否则默认为 <code>#s + 1</code>。
因此，<code>utf8.offset(s, -n)</code> 取字符串的倒数第
<code>n</code> 个字符的位置。
如果指定的字符不在其中或在结束点之后，函数返回 <b>nil</b>。


<p>
作为特例，当 <code>n</code> 等于 0 时，
此函数返回含有 <code>s</code> 第 <code>i</code> 字节的那个字符的开始位置。


<p>
这个函数假定 <code>s</code> 是一个合法的 UTF-8 字符串。


<h2>6.6 &ndash; <a name="6.6">表处理</a></h2>

<p>
这个库提供了表处理的通用函数。
所有函数都放在表 <a name="pdf-table"><code>table</code></a> 中。


<p>
记住，无论何时，若一个操作需要取表的长度，
这张表必须是一个真序列，或是拥有 <code>__len</code> 元方法
（参见 <a href="#3.4.7">&sect;3.4.7</a> ）。
所有的函数都忽略传入参数的那张表中的非数字键。


<p>
<hr><h3><a name="pdf-table.concat"><code>table.concat (list [, sep [, i [, j]]])</code></a></h3>


<p>
提供一个列表，其所有元素都是字符串或数字，返回字符串
<code>list[i]..sep..list[i+1] &middot;&middot;&middot; sep..list[j]</code>。
<code>sep</code> 的默认值是空串，
<code>i</code> 的默认值是 1 ，
<code>j</code> 的默认值是 <code>#list</code> 。
如果 <code>i</code> 比 <code>j</code> 大，返回空串。


<p>
<hr><h3><a name="pdf-table.insert"><code>table.insert (list, [pos,] value)</code></a></h3>


<p>
在 <code>list</code> 的位置 <code>pos</code> 处插入元素 <code>value</code> ，
并后移元素 <code>list[pos], list[pos+1], &middot;&middot;&middot;, list[#list]</code> 。
<code>pos</code> 的默认值为 <code>#list+1</code> ，
因此调用 <code>table.insert(t,x)</code> 会将 <code>x</code> 插在列表 <code>t</code> 的末尾。


<p>
<hr><h3><a name="pdf-table.move"><code>table.move (a1, f, e, t [,a2])</code></a></h3>


<p>
将元素从表 <code>a1</code> 移到表 <code>a2</code>。
这个函数做了次等价于后面这个多重赋值的等价操作：
<code>a2[t],&middot;&middot;&middot; = a1[f],&middot;&middot;&middot;,a1[e]</code>。
<code>a2</code> 的默认值为 <code>a1</code>。
目标区间可以和源区间重叠。
索引 <code>f</code> 必须是正数。


<p>
<hr><h3><a name="pdf-table.pack"><code>table.pack (&middot;&middot;&middot;)</code></a></h3>


<p>
返回用所有参数以键 1,2, 等填充的新表，
并将 "<code>n</code>" 这个域设为参数的总数。
注意这张返回的表不一定是一个序列。


<p>
<hr><h3><a name="pdf-table.remove"><code>table.remove (list [, pos])</code></a></h3>


<p>
移除 <code>list</code> 中 <code>pos</code> 位置上的元素，并返回这个被移除的值。
当 <code>pos</code> 是在 1 到 <code>#list</code> 之间的整数时，
它向前移动元素　<code>list[pos+1], list[pos+2], &middot;&middot;&middot;, list[#list]</code>
并删除元素 <code>list[#list]</code>；
索引 <code>pos</code> 可以是 <code>#list + 1</code> ，或在 <code>#list</code> 为 0 时可以是 0 ；
在这些情况下，函数删除元素 <code>list[pos]</code>。


<p>
<code>pos</code> 默认为 <code>#list</code>，
因此调用 <code>table.remove(l)</code> 将移除表 <code>l</code> 的最后一个元素。


<p>
<hr><h3><a name="pdf-table.sort"><code>table.sort (list [, comp])</code></a></h3>


<p>
在表内从 <code>list[1]</code> 到 <code>list[#list]</code> <em>原地</em> 
对其间元素按指定次序排序。
如果提供了 <code>comp</code> ，
它必须是一个可以接收两个列表内元素为参数的函数。
当第一个元素需要排在第二个元素之前时，返回真
（因此 <code>not comp(list[i+1],list[i])</code> 在排序结束后将为真）。
如果没有提供 <code>comp</code>，
将使用标准 Lua 操作 <code>&lt;</code> 作为替代品。


<p>
排序算法并不稳定；
即当两个元素次序相等时，它们在排序后的相对位置可能会改变。


<p>
<hr><h3><a name="pdf-table.unpack"><code>table.unpack (list [, i [, j]])</code></a></h3>


<p>
返回列表中的元素。
这个函数等价于

<pre>
     return list[i], list[i+1], &middot;&middot;&middot;, list[j]
</pre><p>
<code>i</code> 默认为 1 ，<code>j</code> 默认为 <code>#list</code>。


<h2>6.7 &ndash; <a name="6.7">数学函数</a></h2>

<p>
这个库提供了基本的数学函数。
所以函数都放在表 <a name="pdf-math"><code>math</code></a> 中。
注解有 "<code>integer/float</code>" 的函数会对整数参数返回整数结果，
对浮点（或混合）参数返回浮点结果。
圆整函数（<a href="#pdf-math.ceil"><code>math.ceil</code></a>, <a href="#pdf-math.floor"><code>math.floor</code></a>, <a href="#pdf-math.modf"><code>math.modf</code></a>）
在结果在整数范围内时返回整数，否则返回浮点数。

<p>
<hr><h3><a name="pdf-math.abs"><code>math.abs (x)</code></a></h3>


<p>
返回 <code>x</code> 的绝对值。(integer/float)


<p>
<hr><h3><a name="pdf-math.acos"><code>math.acos (x)</code></a></h3>


<p>
返回 <code>x</code> 的反余弦值（用弧度表示）。


<p>
<hr><h3><a name="pdf-math.asin"><code>math.asin (x)</code></a></h3>


<p>
返回 <code>x</code> 的反正弦值（用弧度表示）。


<p>
<hr><h3><a name="pdf-math.atan"><code>math.atan (y [, x])</code></a></h3>


<p>
返回 <code>y/x</code> 的反正切值（用弧度表示）。
它会使用两个参数的符号来找到结果落在哪个象限中。
（即使 <code>x</code> 为零时，也可以正确的处理。）

<p>
默认的 <code>x</code> 是 1 ，
因此调用 <code>math.atan(y)</code> 将返回
<code>y</code> 的反正切值。


<p>
<hr><h3><a name="pdf-math.ceil"><code>math.ceil (x)</code></a></h3>


<p>
返回不小于 <code>x</code> 的最小整数值。


<p>
<hr><h3><a name="pdf-math.cos"><code>math.cos (x)</code></a></h3>


<p>
返回 <code>x</code> 的余弦（假定参数是弧度）。


<p>
<hr><h3><a name="pdf-math.deg"><code>math.deg (x)</code></a></h3>


<p>
将角 <code>x</code> 从弧度转换为角度。


<p>
<hr><h3><a name="pdf-math.exp"><code>math.exp (x)</code></a></h3>


<p>
返回 <em>e<sup>x</sup></em> 的值
（<code>e</code> 为自然对数的底）。


<p>
<hr><h3><a name="pdf-math.floor"><code>math.floor (x)</code></a></h3>


<p>
返回不大于 <code>x</code> 的最大整数值。


<p>
<hr><h3><a name="pdf-math.fmod"><code>math.fmod (x, y)</code></a></h3>


<p>
返回 <code>x</code> 除以 <code>y</code>，将商向零圆整后的余数。
(integer/float)


<p>
<hr><h3><a name="pdf-math.huge"><code>math.huge</code></a></h3>


<p>
浮点数 <code>HUGE_VAL</code>，
这个数比任何数字值都大。


<p>
<hr><h3><a name="pdf-math.log"><code>math.log (x [, base])</code></a></h3>


<p>
返回以指定底的 <code>x</code> 的对数。
默认的 <code>base</code> 是 <em>e</em>
（因此此函数返回 <code>x</code> 的自然对数）。


<p>
<hr><h3><a name="pdf-math.max"><code>math.max (x, &middot;&middot;&middot;)</code></a></h3>


<p>
返回参数中最大的值，
大小由 Lua 操作 <code>&lt;</code> 决定。
(integer/float)


<p>
<hr><h3><a name="pdf-math.maxinteger"><code>math.maxinteger</code></a></h3>
最大值的整数。


<p>
<hr><h3><a name="pdf-math.min"><code>math.min (x, &middot;&middot;&middot;)</code></a></h3>


<p>
返回参数中最小的值，
大小由 Lua 操作 <code>&lt;</code> 决定。
(integer/float)


<p>
<hr><h3><a name="pdf-math.mininteger"><code>math.mininteger</code></a></h3>
最小值的整数。


<p>
<hr><h3><a name="pdf-math.modf"><code>math.modf (x)</code></a></h3>


<p>
返回 <code>x</code> 的整数部分和小数部分。
第二个结果一定是浮点数。


<p>
<hr><h3><a name="pdf-math.pi"><code>math.pi</code></a></h3>


<p>
<em>&pi;</em> 的值。


<p>
<hr><h3><a name="pdf-math.rad"><code>math.rad (x)</code></a></h3>


<p>
将角 <code>x</code> 从角度转换为弧度。


<p>
<hr><h3><a name="pdf-math.random"><code>math.random ([m [, n]])</code></a></h3>


<p>
当不带参数调用时，
返回一个 <em>[0,1)</em> 区间内一致分布的浮点伪随机数。
当以两个整数 <code>m</code> 与 <code>n</code> 调用时，
<code>math.random</code> 返回一个 <em>[m, n]</em> 区间
内一致分布的整数伪随机数。
（值 <em>n-m</em> 不能是负数，且必须在 Lua 整数的表示范围内。）
调用 <code>math.random(n)</code> 等价于 <code>math.random(1,n)</code>。


<p>
这个函数是对 C 提供的位随机数函数的封装。
对其统计属性不作担保。


<p>
<hr><h3><a name="pdf-math.randomseed"><code>math.randomseed (x)</code></a></h3>


<p>
把 <code>x</code> 设为伪随机数发生器的“种子”：
相同的种子产生相同的随机数列。


<p>
<hr><h3><a name="pdf-math.sin"><code>math.sin (x)</code></a></h3>


<p>
返回 <code>x</code> 的正弦值（假定参数是弧度）。


<p>
<hr><h3><a name="pdf-math.sqrt"><code>math.sqrt (x)</code></a></h3>


<p>
返回 <code>x</code> 的平方根。
（你也可以使用乘方 <code>x^0.5</code> 来计算这个值。）


<p>
<hr><h3><a name="pdf-math.tan"><code>math.tan (x)</code></a></h3>


<p>
返回 <code>x</code> 的正切值（假定参数是弧度）。


<p>
<hr><h3><a name="pdf-math.tointeger"><code>math.tointeger (x)</code></a></h3>


<p>
如果 <code>x</code> 可以转换为一个整数，
返回该整数。
否则返回 <b>nil</b>。


<p>
<hr><h3><a name="pdf-math.type"><code>math.type (x)</code></a></h3>


<p>
如果 <code>x</code> 是整数，返回 "<code>integer</code>"，
如果它是浮点数，返回 "<code>float</code>"，
如果 <code>x</code> 不是数字，返回 <b>nil</b>。


<p>
<hr><h3><a name="pdf-math.ult"><code>math.ult (m, n)</code></a></h3>


<p>
如果整数 <code>m</code> 和 <code>n</code> 以无符号整数形式比较，
<code>m</code> 在 <code>n</code> 之下，返回布尔真否则返回假。


<h2>6.8 &ndash; <a name="6.8">输入输出库</a></h2>

<p>
I/O 库提供了两套不同风格的文件处理接口。
第一种风格使用隐式的文件句柄；
它提供设置默认输入文件及默认输出文件的操作，
所有的输入输出操作都针对这些默认文件。
第二种风格使用显式的文件句柄。


<p>
当使用隐式文件句柄时，
所有的操作都由表 <a name="pdf-io"><code>io</code></a> 提供。
若使用显式文件句柄，
<a href="#pdf-io.open"><code>io.open</code></a> 
会返回一个文件句柄，且所有的操作都由该文件句柄的方法来提供。


<p>
表 <code>io</code> 中也提供了三个
和 C 中含义相同的预定义文件句柄：
<a name="pdf-io.stdin"><code>io.stdin</code></a>， <a name="pdf-io.stdout"><code>io.stdout</code></a>， 以及 <a name="pdf-io.stderr"><code>io.stderr</code></a>。
I/O 库永远不会关闭这些文件。


<p>
除非另有说明，
I/O 函数在出错时都返回 <b>nil</b>
（第二个返回值为错误消息，第三个返回值为系统相关的错误码）。
成功时返回与 <b>nil</b> 不同的值。
在非 POSIX 系统上，
根据错误码取出错误消息的过程可能并非线程安全的，
因为这使用了 C 的全局变量 <code>errno</code> 。

<p>
<hr><h3><a name="pdf-io.close"><code>io.close ([file])</code></a></h3>


<p>
等价于 <code>file:close()</code>。
不给出 <code>file</code> 时将关闭默认输出文件。


<p>
<hr><h3><a name="pdf-io.flush"><code>io.flush ()</code></a></h3>


<p>
等价于 <code>io.output():flush()</code>。


<p>
<hr><h3><a name="pdf-io.input"><code>io.input ([file])</code></a></h3>


<p>
用文件名调用它时，（以文本模式）来打开该名字的文件，
并将文件句柄设为默认输入文件。
如果用文件句柄去调用它，
就简单的将该句柄设为默认输入文件。
如果调用时不传参数，它返回当前的默认输入文件。


<p>
在出错的情况下，函数抛出错误而不是返回错误码。


<p>
<hr><h3><a name="pdf-io.lines"><code>io.lines ([filename &middot;&middot;&middot;])</code></a></h3>


<p>
以读模式打开指定的文件名并返回一个迭代函数。
此迭代函数的工作方式和用一个已打开的文件去调用
<code>file:lines(&middot;&middot;&middot;)</code> 得到的迭代器相同。
当迭代函数检测到文件结束，
它不返回值（让循环结束）并自动关闭文件。


<p>
调用 <code>io.lines()</code> （不传文件名）
等价于 <code>io.input():lines("*l")</code>；
即，它将按行迭代标准输入文件。
在此情况下，循环结束后它不会关闭文件。


<p>
在出错的情况下，函数抛出错误而不是返回错误码。


<p>
<hr><h3><a name="pdf-io.open"><code>io.open (filename [, mode])</code></a></h3>


<p>
这个函数用字符串 <code>mode</code> 指定的模式打开一个文件。
返回新的文件句柄。
当出错时，返回 <b>nil</b> 加错误消息。


<p>
<code>mode</code> 字符串可以是下列任意值：

<ul>
<li><b>"<code>r</code>": </b> 读模式（默认）；</li>
<li><b>"<code>w</code>": </b> 写模式；</li>
<li><b>"<code>a</code>": </b> 追加模式；</li>
<li><b>"<code>r+</code>": </b> 更新模式，所有之前的数据都保留；</li>
<li><b>"<code>w+</code>": </b> 更新模式，所有之前的数据都删除；</li>
<li><b>"<code>a+</code>": </b> 追加更新模式，所有之前的数据都保留，只允许在文件尾部做写入。</li>
</ul><p>
<code>mode</code> 字符串可以在最后加一个 '<code>b</code>' ，
这会在某些系统上以二进制方式打开文件。


<p>
<hr><h3><a name="pdf-io.output"><code>io.output ([file])</code></a></h3>


<p>
类似于 <a href="#pdf-io.input"><code>io.input</code></a>。
不过都针对默认输出文件操作。


<p>
<hr><h3><a name="pdf-io.popen"><code>io.popen (prog [, mode])</code></a></h3>


<p>
这个函数和系统有关，不是所有的平台都提供。

<p>
用一个分离进程开启程序 <code>prog</code>，
返回的文件句柄可用于从这个程序中读取数据
（如果 <code>mode</code> 为 <code>"r"</code>，这是默认值）
或是向这个程序写入输入（当
<code>mode</code> 为 <code>"w"</code> 时）。


<p>
<hr><h3><a name="pdf-io.read"><code>io.read (&middot;&middot;&middot;)</code></a></h3>


<p>
等价于 <code>io.input():read(&middot;&middot;&middot;)</code>。


<p>
<hr><h3><a name="pdf-io.tmpfile"><code>io.tmpfile ()</code></a></h3>


<p>
如果成功，返回一个临时文件的句柄。
这个文件以更新模式打开，在程序结束时会自动删除。


<p>
<hr><h3><a name="pdf-io.type"><code>io.type (obj)</code></a></h3>


<p>
检查 <code>obj</code> 是否是合法的文件句柄。
如果 <code>obj</code> 它是一个打开的文件句柄，返回字符串 <code>"file"</code>。
如果 <code>obj</code> 是一个关闭的文件句柄，返回字符串 <code>"closed file"</code>。
如果 <code>obj</code> 不是文件句柄，返回 <b>nil</b> 。


<p>
<hr><h3><a name="pdf-io.write"><code>io.write (&middot;&middot;&middot;)</code></a></h3>


<p>
等价于 <code>io.output():write(&middot;&middot;&middot;)</code>。


<p>
<hr><h3><a name="pdf-file:close"><code>file:close ()</code></a></h3>


<p>
关闭 <code>file</code>。
注意，文件在句柄被垃圾回收时会自动关闭，
但是多久以后发生，时间不可预期的。

<p>
当关闭用 <a href="#pdf-io.popen"><code>io.popen</code></a> 创建出来的文件句柄时，
<a href="#pdf-file:close"><code>file:close</code></a>
返回 <a href="#pdf-os.execute"><code>os.execute</code></a>
会返回的一样的值。


<p>
<hr><h3><a name="pdf-file:flush"><code>file:flush ()</code></a></h3>


<p>
将写入的数据保存到 <code>file</code> 中。


<p>
<hr><h3><a name="pdf-file:lines"><code>file:lines (&middot;&middot;&middot;)</code></a></h3>


<p>
返回一个迭代器函数，
每次调用迭代器时，都从文件中按指定格式读数据。
如果没有指定格式，使用默认值 "<code>l</code>" 。
看一个例子

<pre>
     for c in file:lines(1) do <em>body</em> end
</pre><p>
会从文件当前位置开始，中不断读出字符。
和 <a href="#pdf-io.lines"><code>io.lines</code></a> 不同，
这个函数在循环结束后不会关闭文件。


<p>
在出错的情况下，函数抛出错误而不是返回错误码。


<p>
<hr><h3><a name="pdf-file:read"><code>file:read (&middot;&middot;&middot;)</code></a></h3>


<p>
读文件 <code>file</code>，
指定的格式决定了要读什么。
对于每种格式，函数返回读出的字符对应的字符串或数字。
若不能以该格式对应读出数据则返回 <b>nil</b>。
（对于最后这种情况，
函数不会读出后续的格式。）
当调用时不传格式，它会使用默认格式读下一行（见下面描述）。


<p>
提供的格式有

<ul>

<li><b>"<code>n</code>": </b>
读取一个数字，根据 Lua 的转换文法，可能返回浮点数或整数。
（数字可以有前置或后置的空格，以及符号。）
只要能构成合法的数字，这个格式总是去读尽量长的串；
如果读出来的前缀无法构成合法的数字
（比如空串，"<code>0x</code>" 或 "<code>3.4e-</code>"），
就中止函数运行，返回 <b>nil</b>。
</li>

<li><b>"<code>a</code>": </b>
从当前位置开始读取整个文件。
如果已在文件末尾，返回空串。
</li>

<li><b>"<code>l</code>": </b>
读取一行并忽略行结束标记。
当在文件末尾时，返回 <b>nil</b>
这是默认格式。
</li>

<li><b>"<code>L</code>": </b>
读取一行并保留行结束标记（如果有的话），
当在文件末尾时，返回 <b>nil</b>。
</li>

<li><b><em>number</em>: </b>
读取一个不超过这个数量字节数的字符串。
当在文件末尾时，返回 <b>nil</b>。
如果 <code>number</code> 为零，
它什么也不读，返回一个空串。
当在文件末尾时，返回 <b>nil</b>。
</li>

</ul><p>
格式 "<code>l</code>" 和 "<code>L</code>" 只能用于文本文件。


<p>
<hr><h3><a name="pdf-file:seek"><code>file:seek ([whence [, offset]])</code></a></h3>


<p>
设置及获取基于文件开头处计算出的位置。
设置的位置由 <code>offset</code> 和
<code>whence</code> 字符串 <code>whence</code>
指定的基点决定。基点可以是：

<ul>
<li><b>"<code>set</code>": </b> 基点为 0 （文件开头）；</li>
<li><b>"<code>cur</code>": </b> 基点为当前位置；</li>
<li><b>"<code>end</code>": </b> 基点为文件尾；</li>
</ul><p>
当 <code>seek</code> 成功时，返回最终从文件开头计算起的文件的位置。
当 <code>seek</code> 失败时，返回 <b>nil</b> 加上一个错误描述字符串。


<p>
<code>whence</code> 的默认值是 <code>"cur"</code>，
<code>offset</code> 默认为 0 。
因此，调用 <code>file:seek()</code> 可以返回文件当前位置，并不改变它；
调用 <code>file:seek("set")</code> 将位置设为文件开头（并返回 0）；
调用 <code>file:seek("end")</code> 将位置设到文件末尾，并返回文件大小。


<p>
<hr><h3><a name="pdf-file:setvbuf"><code>file:setvbuf (mode [, size])</code></a></h3>


<p>
设置输出文件的缓冲模式。
有三种模式：

<ul>

<li><b>"<code>no</code>": </b>
不缓冲；输出操作立刻生效。
</li>

<li><b>"<code>full</code>": </b>
完全缓冲；只有在缓存满或当你显式的对文件调用
<code>flush</code>（参见 <a href="#pdf-io.flush"><code>io.flush</code></a>）
时才真正做输出操作。
</li>

<li><b>"<code>line</code>": </b>
行缓冲；
输出将缓冲到每次换行前，
对于某些特殊文件（例如终端设备）缓冲到任何输入前。
</li>

</ul><p>
对于后两种情况，<code>size</code> 以字节数为单位
指定缓冲区大小。
默认会有一个恰当的大小。


<p>
<hr><h3><a name="pdf-file:write"><code>file:write (&middot;&middot;&middot;)</code></a></h3>


<p>
将参数的值逐个写入 <code>file</code>。
参数必须是字符串或数字。


<p>
成功时，函数返回 <code>file</code>。
否则返回 <b>nil</b> 加错误描述字符串。


<h2>6.9 &ndash; <a name="6.9">操作系统库</a></h2>

<p>
这个库都通过表 <a name="pdf-os"><code>os</code></a> 实现。


<p>
<hr><h3><a name="pdf-os.clock"><code>os.clock ()</code></a></h3>


<p>
返回程序使用的按秒计 CPU 时间的近似值。


<p>
<hr><h3><a name="pdf-os.date"><code>os.date ([format [, time]])</code></a></h3>


<p>
返回一个包含日期及时刻的字符串或表。
格式化方法取决于所给字符串 <code>format</code>。


<p>
如果提供了 <code>time</code> 参数，
格式化这个时间
（这个值的含义参见 <a href="#pdf-os.time"><code>os.time</code></a> 函数）。
否则，<code>date</code> 格式化当前时间。


<p>
如果 <code>format</code> 以 '<code>!</code>' 打头，
日期以协调世界时格式化。
在这个可选字符项之后，
如果 <code>format</code> 为字符串 "<code>*t</code>"，
<code>date</code> 返回有后续域的表：
<code>year</code> （四位数字），<code>month</code> （1&ndash;12），<code>day</code> （1&ndash;31），
<code>hour</code> （0&ndash;23），<code>min</code> （0&ndash;59），<code>sec</code> （0&ndash;61），
<code>wday</code> （星期几，星期天为 1 ），
<code>yday</code> （当年的第几天），
以及 <code>isdst</code> （夏令时标记，一个布尔量）。
对于最后一个域，如果该信息不提供的话就不存在。


<p>
如果 <code>format</code> 并非 "<code>*t</code>"，
<code>date</code> 以字符串形式返回，
格式化方法遵循 ISO C 函数 <code>strftime</code> 的规则。


<p>
如果不传参数调用，
<code>date</code> 返回一个合理的日期时间串，
格式取决于宿主程序以及当前的区域设置
（即，<code>os.date()</code> 等价于 <code>os.date("%c")</code>）。


<p>
在非 POSIX 系统上，
由于这个函数依赖 C 函数 <code>gmtime</code> 和 <code>localtime</code>，
它可能并非线程安全的。


<p>
<hr><h3><a name="pdf-os.difftime"><code>os.difftime (t2, t1)</code></a></h3>


<p>
返回以秒计算的时刻 <code>t1</code> 到 <code>t2</code> 的差值。
（这里的时刻是由 <a href="#pdf-os.time"><code>os.time</code></a> 返回的值）。
在 POSIX，Windows，和其它一些系统中，这个值就等于
<code>t2</code><em>-</em><code>t1</code>。


<p>
<hr><h3><a name="pdf-os.execute"><code>os.execute ([command])</code></a></h3>


<p>
这个函数等价于 ISO C 函数 <code>system</code>。
它调用系统解释器执行 <code>command</code>。
如果命令成功运行完毕，第一个返回值就是 <b>true</b>，
否则是 <b>nil</b>。
在第一个返回值之后，函数返回一个字符串加一个数字。如下：
<ul>

<li><b>"<code>exit</code>": </b>
命令正常结束；
接下来的数字是命令的退出状态码。
</li>

<li><b>"<code>signal</code>": </b>
命令被信号打断；
接下来的数字是打断该命令的信号。
</li>

</ul>

<p>
如果不带参数调用，
<code>os.execute</code> 在系统解释器存在的时候返回真。


<p>
<hr><h3><a name="pdf-os.exit"><code>os.exit ([code [, close]])</code></a></h3>


<p>
调用 ISO C 函数 <code>exit</code> 终止宿主程序。
如果 <code>code</code> 为 <b>true</b>，
返回的状态码是 <code>EXIT_SUCCESS</code>；
如果 <code>code</code> 为 <b>false</b>，
返回的状态码是 <code>EXIT_FAILURE</code>；
如果 <code>code</code> 是一个数字，
返回的状态码就是这个数字。
<code>code</code> 的默认值为 <b>true</b>。


<p>
如果第二个可选参数 <code>close</code> 为真，
在退出前关闭 Lua 状态机。


<p>
<hr><h3><a name="pdf-os.getenv"><code>os.getenv (varname)</code></a></h3>


<p>
返回进程环境变量 <code>varname</code> 的值，
如果该变量未定义，返回 <b>nil</b> 。


<p>
<hr><h3><a name="pdf-os.remove"><code>os.remove (filename)</code></a></h3>


<p>
删除指定名字的文件（在 POSIX 系统上可以是一个空目录）
如果函数失败，返回 <b>nil</b>
加一个错误描述串及出错码。


<p>
<hr><h3><a name="pdf-os.rename"><code>os.rename (oldname, newname)</code></a></h3>


<p>
将名字为 <code>oldname</code> 的文件或目录更名为 <code>newname</code>。
如果函数失败，返回 <b>nil</b>
加一个错误描述串及出错码。


<p>
<hr><h3><a name="pdf-os.setlocale"><code>os.setlocale (locale [, category])</code></a></h3>


<p>
设置程序的当前区域。
<code>locale</code> 是一个区域设置的系统相关字符串；
<code>category</code> 是一个描述有改变哪个分类的可选字符串：
<code>"all"</code>，<code>"collate"</code>， <code>"ctype"</code>，
<code>"monetary"</code>， <code>"numeric"</code>， 或 <code>"time"</code>；
默认的分类为 <code>"all"</code>。
此函数返回新区域的名字。
如果请求未被获准，返回 <b>nil</b> 。


<p>
当 <code>locale</code> 是一个空串，
当前区域被设置为一个在实现中定义好的本地区域。
当 <code>locale</code> 为字符串 "<code>C</code>"，
当前区域被设置为标准 C 区域。


<p>
当第一个参数为 <b>nil</b> 时，
此函数仅返回当前区域指定分类的名字。


<p>
由于这个函数依赖 C 函数 <code>setlocale</code>，
它可能并非线程安全的。


<p>
<hr><h3><a name="pdf-os.time"><code>os.time ([table])</code></a></h3>


<p>
当不传参数时，返回当前时刻。
如果传入一张表，就返回由这张表表示的时刻。
这张表必须包含域 <code>year</code>，<code>month</code>，及 <code>day</code>；
可以包含有　<code>hour</code> （默认为 12 ），
<code>min</code> （默认为 0），
<code>sec</code> （默认为 0），以及 <code>isdst</code> （默认为 <b>nil</b>）。
关于这些域的详细描述，参见 <a href="#pdf-os.date"><code>os.date</code></a> 函数。


<p>
返回值是一个含义由你的系统决定的数字。
在 POSIX，Windows，和其它一些系统中，
这个数字统计了从指定时间（"epoch"）开始经历的秒数。
对于另外的系统，其含义未定义，
你只能把 <code>time</code> 的返回数字用于
<a href="#pdf-os.date"><code>os.date</code></a> 和 <a href="#pdf-os.difftime"><code>os.difftime</code></a>
的参数。


<p>
<hr><h3><a name="pdf-os.tmpname"><code>os.tmpname ()</code></a></h3>


<p>
返回一个可用于临时文件的文件名字符串。
这个文件在使用前必须显式打开，不再使用时需要显式删除。

<p>
在 POSIX 系统上，
这个函数会以此文件名创建一个文件以回避安全风险。
（别人可能未经允许在获取到这个文件名到创建该文件之间的时刻创建此文件。）
你依旧需要在使用它的时候先打开，并最后删除（即使你没使用到）。

<p>
只有有可能，你更应该使用
<a href="#pdf-io.tmpfile"><code>io.tmpfile</code></a>，
因为该文件可以在程序结束时自动删除。


<h2>6.10 &ndash; <a name="6.10">调试库</a></h2>

<p>
这个库提供了 Lua 程序调试接口（<a href="#4.9">&sect;4.9</a>）的功能。
其中一些函数违反了 Lua 代码的基本假定
（例如，不会从函数之外访问函数的局部变量；
用户数据的元表不会被 Lua 代码修改；
Lua 程序不会崩溃），
因此它们有可能危害到其它代码的安全性。
此外，库里的一些函数可能运行的很慢。


<p>
这个库里的所有函数都提供在表 <a name="pdf-debug"><code>debug</code></a> 内。
所有操作线程的函数，可选的第一个参数都是针对的线程。
默认值永远是当前线程。


<p>
<hr><h3><a name="pdf-debug.debug"><code>debug.debug ()</code></a></h3>


<p>
进入一个用户交互模式，运行用户输入的每个字符串。
使用简单的命令以及其它调试设置，用户可以检阅全局变量和局部变量，
改变变量的值，计算一些表达式，等等。
输入一行仅包含 <code>cont</code> 的字符串将结束这个函数，
这样调用者就可以继续向下运行。


<p>
注意，<code>debug.debug</code> 输入的命令在文法上并没有内嵌到任何函数中，
因此不能直接去访问局部变量。


<p>
<hr><h3><a name="pdf-debug.gethook"><code>debug.gethook ([thread])</code></a></h3>


<p>
返回三个表示线程钩子设置的值：
当前钩子函数，当前钩子掩码，当前钩子计数
（<a href="#pdf-debug.sethook"><code>debug.sethook</code></a> 设置的那些）。


<p>
<hr><h3><a name="pdf-debug.getinfo"><code>debug.getinfo ([thread,] f [, what])</code></a></h3>


<p>
返回关于一个函数信息的表。
你可以直接提供该函数，
也可以用一个数字 <code>f</code> 表示该函数。
数字 <code>f</code> 表示运行在指定线程的调用栈对应层次上的函数：
0 层表示当前函数（<code>getinfo</code> 自身）；
1 层表示调用 <code>getinfo</code> 的函数
（除非是尾调用，这种情况不计入栈）；等等。
如果 <code>f</code> 是一个比活动函数数量还大的数字，
<code>getinfo</code> 返回 <b>nil</b>。


<p>
只有字符串 <code>what</code> 中有描述要填充哪些项，
返回的表可以包含 <a href="#lua_getinfo"><code>lua_getinfo</code></a> 能返回的所有项。
<code>what</code> 默认是返回提供的除合法行号表外的所有信息。
对于选项 '<code>f</code>' ，会在可能的情况下，增加
<code>func</code> 域保存函数自身。
对于选项 '<code>L</code>' ，会在可能的情况下，增加
<code>activelines</code> 域保存合法行号表。


<p>
例如,表达式 <code>debug.getinfo(1,"n")</code>
返回带有当前函数名字信息的表（如果找的到名字的话），
表达式 <code>debug.getinfo(print)</code> 
返回关于 <a href="#pdf-print"><code>print</code></a> 函数的
包含有所有能提供信息的表。


<p>
<hr><h3><a name="pdf-debug.getlocal"><code>debug.getlocal ([thread,] f, local)</code></a></h3>


<p>
此函数返回在栈的 <code>f</code> 层处函数的索引为 <code>local</code> 的局部变量
的名字和值。
这个函数不仅用于访问显式定义的局部变量，也包括形参、临时变量等。


<p>
第一个形参或是定义的第一个局部变量的索引为 1 ，
然后遵循在代码中定义次序，以次类推。
其中只计算函数当前作用域的活动变量。
负索引指可变参数；
-1 指第一个可变参数。
如果该索引处没有变量，函数返回 <b>nil</b>。
若指定的层次越界，抛出错误。
（你可以调用 <a href="#pdf-debug.getinfo"><code>debug.getinfo</code></a> 来检查层次是否合法。）


<p>
以 '<code>(</code>' （开括号）打头的变量名表示没有名字的变量
（比如是循环控制用到的控制变量，
或是去除了调试信息的代码块）。


<p>
参数 <code>f</code> 也可以是一个函数。
这种情况下，<code>getlocal</code> 仅返回函数形参的名字。


<p>
<hr><h3><a name="pdf-debug.getmetatable"><code>debug.getmetatable (value)</code></a></h3>


<p>
返回给定 <code>value</code> 的元表。
若其没有元表则返回 <b>nil</b> 。


<p>
<hr><h3><a name="pdf-debug.getregistry"><code>debug.getregistry ()</code></a></h3>


<p>
返回注册表（参见 <a href="#4.5">&sect;4.5</a>）。


<p>
<hr><h3><a name="pdf-debug.getupvalue"><code>debug.getupvalue (f, up)</code></a></h3>


<p>
此函数返回函数 <code>f</code> 的第 <code>up</code> 个上值的名字和值。
如果该函数没有那个上值，返回 <b>nil</b> 。


<p>
以 '<code>(</code>' （开括号）打头的变量名表示没有名字的变量
（去除了调试信息的代码块）。


<p>
<hr><h3><a name="pdf-debug.getuservalue"><code>debug.getuservalue (u)</code></a></h3>


<p>
返回关联在 <code>u</code> 上的 Lua 值。
如果 <code>u</code> 并非用户数据，返回 <b>nil</b>。


<p>
<hr><h3><a name="pdf-debug.sethook"><code>debug.sethook ([thread,] hook, mask [, count])</code></a></h3>


<p>
将一个函数作为钩子函数设入。
字符串 <code>mask</code> 以及数字 <code>count</code> 决定了钩子将在何时调用。
掩码是由下列字符组合成的字符串，每个字符有其含义：

<ul>
<li><b>'<code>c</code>': </b> 每当 Lua 调用一个函数时，调用钩子；</li>
<li><b>'<code>r</code>': </b> 每当 Lua 从一个函数内返回时，调用钩子；</li>
<li><b>'<code>l</code>': </b> 每当 Lua 进入新的一行时，调用钩子。</li>
</ul><p>
此外，
传入一个不为零的 <code>count</code> ，
钩子将在每运行 <code>count</code> 条指令时调用。


<p>
如果不传入参数，
<a href="#pdf-debug.sethook"><code>debug.sethook</code></a> 关闭钩子。


<p>
当钩子被调用时，
第一个参数是触发这次调用的事件：
<code>"call"</code> （或 <code>"tail call"</code>），
<code>"return"</code>，
<code>"line"</code>， <code>"count"</code>。
对于行事件，
钩子的第二个参数是新的行号。
在钩子内，你可以调用 <code>getinfo</code> ，指定第 2 层，
来获得正在运行的函数的详细信息
（0 层指 <code>getinfo</code> 函数，
1 层指钩子函数）。


<p>
<hr><h3><a name="pdf-debug.setlocal"><code>debug.setlocal ([thread,] level, local, value)</code></a></h3>


<p>
这个函数将 <code>value</code> 赋给
栈上第 <code>level</code> 层函数的第 <code>local</code> 个局部变量。
如果没有那个变量，函数返回 <b>nil</b> 。
如果 <code>level</code> 越界，抛出一个错误。
（你可以调用 <a href="#pdf-debug.getinfo"><code>debug.getinfo</code></a> 来检查层次是否合法。）
否则，它返回局部变量的名字。


<p>
关于变量索引和名字，参见 <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a>。


<p>
<hr><h3><a name="pdf-debug.setmetatable"><code>debug.setmetatable (value, table)</code></a></h3>


<p>
将 <code>value</code> 的元表设为 <code>table</code> （可以是 <b>nil</b>）。
返回 <code>value</code>。


<p>
<hr><h3><a name="pdf-debug.setupvalue"><code>debug.setupvalue (f, up, value)</code></a></h3>


<p>
这个函数将 <code>value</code> 设为函数 <code>f</code> 的第
<code>up</code> 个上值。
如果函数没有那个上值，返回 <b>nil</b>
否则，返回该上值的名字。


<p>
<hr><h3><a name="pdf-debug.setuservalue"><code>debug.setuservalue (udata, value)</code></a></h3>


<p>
将 <code>value</code> 设为 <code>udata</code> 的关联值。
<code>udata</code> 必须是一个完全用户数据。


<p>
返回 <code>udata</code>。


<p>
<hr><h3><a name="pdf-debug.traceback"><code>debug.traceback ([thread,] [message [, level]])</code></a></h3>


<p>
如果 <code>message</code> 有，且不是字符串或 <b>nil</b>，
函数不做任何处理直接返回 <code>message</code>。
否则，它返回调用栈的栈回溯信息。
字符串可选项 <code>message</code> 被添加在栈回溯信息的开头。
数字可选项 <code>level</code> 指明从栈的哪一层开始回溯
（默认为 1 ，即调用 <code>traceback</code> 的那里）。


<p>
<hr><h3><a name="pdf-debug.upvalueid"><code>debug.upvalueid (f, n)</code></a></h3>


<p>
返回指定函数第 <code>n</code>
个上值的唯一标识符（一个轻量用户数据）。


<p>
这个唯一标识符可以让程序检查两个不同的闭包是否共享了上值。
若 Lua 闭包之间共享的是同一个上值
（即指向一个外部局部变量），会返回相同的标识符。


<p>
<hr><h3><a name="pdf-debug.upvaluejoin"><code>debug.upvaluejoin (f1, n1, f2, n2)</code></a></h3>


<p>
让 Lua 闭包 <code>f1</code> 的第 <code>n1</code> 个上值
引用  Lua 闭包 <code>f2</code> 的第 <code>n2</code> 个上值。


<h1>7 &ndash; <a name="7">独立版 Lua</a></h1>

<p>
虽然 Lua 被设计成一门扩展式语言，用于嵌入一个宿主程序。
但经常也会被当成独立语言使用。
独立版的 Lua 语言解释器随标准包发布，就叫 <code>lua</code>。
独立版解释器保留了所有的标准库及调试库。
其命令行用法为：

<pre>
     lua [options] [script [args]]
</pre><p>
选项有：

<ul>
<li><b><code>-e <em>stat</em></code>: </b> 执行一段字符串 <em>stat</em> ；</li>
<li><b><code>-l <em>mod</em></code>: </b> “请求模块” <em>mod</em> ；</li>
<li><b><code>-i</code>: </b> 在运行完 <em>脚本</em> 后进入交互模式；</li>
<li><b><code>-v</code>: </b> 打印版本信息；</li>
<li><b><code>-E</code>: </b> 忽略环境变量；</li>
<li><b><code>--</code>: </b> 中止对后面选项的处理；</li>
<li><b><code>-</code>: </b> 把 <code>stdin</code> 当作一个文件运行，并中止对后面选项的处理。</li>
</ul><p>
在处理完选项后，<code>lua</code> 运行指定的 <em>脚本</em>。
如果不带参数调用，
在标准输入（<code>stdin</code>）是终端时，<code>lua</code> 的行为和 <code>lua -v -i</code> 相同。
否则相当于 <code>lua -</code> 。


<p>
如果调用时不带选项 <code>-E</code>，
解释器会在运行任何参数前，检查环境变量 <a name="pdf-LUA_INIT_5_3"><code>LUA_INIT_5_3</code></a>
（或在版本名未定义时，检查 <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a> ）。
如果该变量内存格式为 <code>@<em>filename</em></code>，
<code>lua</code> 执行该文件。
否则，<code>lua</code> 执行该字符串。


<p>
如果调用时有选项 <code>-E</code>，
除了忽略 <code>LUA_INIT</code> 外，
Lua 还忽略 <code>LUA_PATH</code> 与 <code>LUA_CPATH</code> 的值。
将 <a href="#pdf-package.path"><code>package.path</code></a> 和 <a href="#pdf-package.cpath"><code>package.cpath</code></a>
的值设为定义在 <code>luaconf.h</code> 中的默认路径。

<p>
除 <code>-i</code> 与 <code>-E</code> 外所有的选项都按次序处理。
例如，这样调用

<pre>
     $ lua -e'a=1' -e 'print(a)' script.lua
</pre><p>
将先把 <code>a</code> 设为 1，然后打印 <code>a</code> 的值，
最后运行文件 <code>script.lua</code> 并不带参数。
（这里的 <code>$</code> 是命令行提示。你的命令行提示可能不一样。）


<p>
在运行任何代码前，
<code>lua</code> 会将所有命令行传入的参数放到一张全局表 <code>arg</code> 中。
脚本的名字放在索引 0 的地方，
脚本名后紧跟的第一个参数在索引 1 处，依次类推。
在脚本名前面的任何参数
（即解释器的名字以及各选项）
放在负索引处。
例如，调用

<pre>
     $ lua -la b.lua t1 t2
</pre><p>
这张表是这样的：

<pre>
     arg = { [-2] = "lua", [-1] = "-la",
             [0] = "b.lua",
             [1] = "t1", [2] = "t2" }
</pre><p>
如果调用中没提供脚本名，
解释器的名字就放在索引 0 处，后面接着其它参数。
例如，调用

<pre>
     $ lua -e "print(arg[1])"
</pre><p>
将打印出 "<code>-e</code>" 。
如果提供了脚本名，
就以 <code>arg[1]</code>, &middot;&middot;&middot;, <code>arg[#arg]</code>
为参数调用脚本。
（和 Lua 所有的代码块一样，
脚本被编译成一个可变参数函数。）


<p>
在交互模式下，
Lua 不断的显示提示符，并等待下一行输入。
一旦读到一行，
首先试着把这行解释为一个表达式。
如果成功解释，就打印表达式的值。
否则，将这行解释为语句。
如果你写了一行未完成的语句，
解释器会用一个不同的提示符来等待你写完。


<p>
当脚本中出现了未保护的错误，
解释器向标准错误流报告错误。
如果错误对象并非一个字符串，但是却有元方法
<code>__tostring</code> 的话，
解释器会调用这个元方法生成最终的消息。
否则，解释器将错误对象转换为一个字符串，并把栈回溯信息加在前面。


<p>
如果正常结束运行，
解释器会关闭主 Lua 状态机
（参见 <a href="#lua_close"><code>lua_close</code></a>）。
脚本可以通过调用
<a href="#pdf-os.exit"><code>os.exit</code></a>
来结束，以回避这个步骤。


<p>
为了让 Lua 可以用于 Unix 系统的脚本解释器。
独立版解释器会忽略代码块的以 <code>#</code> 打头的第一行。
因此，Lua 脚本可以通过
<code>chmod +x</code> 以及 <code>#!</code> 形式变成一个可执行文件。
类似这样
<pre>
     #!/usr/local/bin/lua
</pre><p>
（当然，
Lua 解释器的位置对于你的机器来说可能不一样。
如果 <code>lua</code> 在你的 <code>PATH</code> 中，
写成
<pre>
     #!/usr/bin/env lua
</pre><p>
更为通用。）


<h1>8 &ndash; <a name="8">与之前版本不兼容的地方</a></h1>

<p>
这里我们列出了把程序从 Lua 5.2 迁移到 Lua 5.3 会碰到的不兼容的地方。
你可以在编译 Lua 时定义一些恰当的选项（参见文件 <code>luaconf.h</code>），
来回避一些不兼容性。
然而，这些兼容选项以后会移除。

<p>
Lua 的版本更替总是会修改一些 C API 并涉及源代码的改变。
例如一些常量的数字值，用宏来实现一些函数。
因此，你不能假设在不同的 Lua 版本间可以做到二进制兼容。
当你使用新版时，一定要将使用了 Lua API 的客户程序重新编译。


<p>
同样，Lua 版本更替还会改变预编译代码块的内部呈现方式；
在不同的 Lua 版本间，预编译代码块不兼容。

<p>
官方发布版的标准路径也可能随版本变化。


<h2>8.1 &ndash; <a name="8.1">语言的变更</a></h2>
<ul>

<li>
Lua 5.2 到 Lua 5.3 最大的变化是引入了数字的整数子类型。
虽然这个变化不会影响“一般”计算，
但一些计算
（主要是涉及溢出的）
会得到不同的结果。


<p>
你可以通过把数字都强制转换为浮点数来消除差异
（在 Lua 5.2 中，所有的数字都是浮点数）。
比如你可以将所有的常量都以 <code>.0</code> 结尾，
或是使用 <code>x = x + 0.0</code> 来转换一个变量。
（这条建议仅用于偶尔快速解决一些不兼容问题；
这不是一条好的编程准则。
好好写程序的话，你应该在需要使用浮点数的地方用浮点数，
需要整数的地方用整数。）
</li>

<li>
把浮点数转为字符串的地方，现在都对等于整数的浮点数加了 <code>.0</code> 后缀。
（例如，浮点数 2.0 会被打印成 <code>2.0</code>，
而不是 <code>2</code>。）
如果你需要定制数字的格式，就必须显式的格式化它们。


<p>
（准确说这个不是兼容性问题，
因为 Lua 并没有规定数字如何格式化成字符串，
但一些程序假定遵循某种特别的格式。）
</li>

<li>
分代垃圾收集器没有了。
（它是 Lua 5.2 中的一个试验性特性。）
</li>

</ul>


<h2>8.2 &ndash; <a name="8.2">库的变更</a></h2>
<ul>

<li>
<code>bit32</code> 库废弃了。
使用一个外部兼容库很容易，
不过最好直接用对应的位操作符来替换它。
（注意 <code>bit32</code> 只能针对 32 位整数运算，
而标准 Lua 中的位操作可以用于 64 位整数。）
</li>

<li>
表处理库现在在读写其中的元素时会考虑元方法。
</li>

<li>
<a href="#pdf-ipairs"><code>ipairs</code></a> 这个迭代器也会考虑元方法，而 <code>__ipairs</code> 元方法被废弃了。
</li>

<li>
<a href="#pdf-io.read"><code>io.read</code></a> 的选项名不再用 '<code>*</code>' 打头。
但出于兼容性考虑，Lua 会继续忽略掉这个字符。
</li>

<li>
数学库中的这些函数废弃了：
<code>atan2</code>， <code>cosh</code>， <code>sinh</code>， <code>tanh</code>， <code>pow</code>，
<code>frexp</code>， 以及 <code>ldexp</code> 。
你可以用 <code>x^y</code> 替换 <code>math.pow(x,y)</code>；
你可以用 <code>math.atan</code> 替换 <code>math.atan2</code>，前者现在可以接收一或两个参数；
你可以用 <code>x * 2.0^exp</code> 替换 <code>math.ldexp(x,exp)</code>。
若用到其它操作，你可以写一个扩展库，或在 Lua 中实现它们。
</li>

<li>
<a href="#pdf-require"><code>require</code></a> 在搜索 C 加载器时处理版本号的方式有所变化。
现在，版本号应该跟在模块名后（其它大多数工具都是这样干的）。
出于兼容性考虑，如果使用新格式找不到加载器的话，搜索器依然会尝试旧格式。
（Lua 5.2 已经是这样处理了，但是并没有写在文档里。）
</li>

</ul>


<h2>8.3 &ndash; <a name="8.3">API 的变更</a></h2>


<ul>

<li>
延续函数现在接收原来用
<code>lua_getctx</code> 获取的参数，
所以 <code>lua_getctx</code> 就去掉了。
按需要改写你的代码。
</li>

<li>
函数 <a href="#lua_dump"><code>lua_dump</code></a> 有了一个额外的参数 <code>strip</code>。
如果想和之前的行为一致，这个值传 0 。
</li>

<li>
用于传入传出无符号整数的函数
（<code>lua_pushunsigned</code>， <code>lua_tounsigned</code>， <code>lua_tounsignedx</code>，
<code>luaL_checkunsigned</code>， <code>luaL_optunsigned</code>）
都废弃了。
直接从有符号版做类型转换。
</li>

<li>
处理输入非默认整数类型的宏
（<code>luaL_checkint</code>， <code>luaL_optint</code>， <code>luaL_checklong</code>， <code>luaL_optlong</code>）
废弃掉了。
直接使用 <a href="#lua_Integer"><code>lua_Integer</code></a> 加一个类型转换就可以替代
（或是只要有可能，就在你的代码中使用 <a href="#lua_Integer"><code>lua_Integer</code></a>）。
</li>

</ul>


<h1>9 &ndash; <a name="9">Lua 的完整语法</a></h1>

<p>
这是一份采用扩展 BNF 描述的 Lua 完整语法。
在扩展 BNF 中，
{A} 表示 0 或多个 A ，
[A] 表示一个可选的 A 。
（操作符优先级，参见 <a href="#3.4.8">&sect;3.4.8</a>；
对于最终符号，名字，数字，字符串字面量的解释，参见 <a href="#3.1">&sect;3.1</a>。）


<pre>

	chunk ::= block

	block ::= {stat} [retstat]

	stat ::=  &lsquo;<b>;</b>&rsquo; | 
		 varlist &lsquo;<b>=</b>&rsquo; explist | 
		 functioncall | 
		 label | 
		 <b>break</b> | 
		 <b>goto</b> Name | 
		 <b>do</b> block <b>end</b> | 
		 <b>while</b> exp <b>do</b> block <b>end</b> | 
		 <b>repeat</b> block <b>until</b> exp | 
		 <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> | 
		 <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> | 
		 <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> | 
		 <b>function</b> funcname funcbody | 
		 <b>local</b> <b>function</b> Name funcbody | 
		 <b>local</b> namelist [&lsquo;<b>=</b>&rsquo; explist] 

	retstat ::= <b>return</b> [explist] [&lsquo;<b>;</b>&rsquo;]

	label ::= &lsquo;<b>::</b>&rsquo; Name &lsquo;<b>::</b>&rsquo;

	funcname ::= Name {&lsquo;<b>.</b>&rsquo; Name} [&lsquo;<b>:</b>&rsquo; Name]

	varlist ::= var {&lsquo;<b>,</b>&rsquo; var}

	var ::=  Name | prefixexp &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo; | prefixexp &lsquo;<b>.</b>&rsquo; Name 

	namelist ::= Name {&lsquo;<b>,</b>&rsquo; Name}

	explist ::= exp {&lsquo;<b>,</b>&rsquo; exp}

	exp ::=  <b>nil</b> | <b>false</b> | <b>true</b> | Numeral | LiteralString | &lsquo;<b>...</b>&rsquo; | functiondef | 
		 prefixexp | tableconstructor | exp binop exp | unop exp 

	prefixexp ::= var | functioncall | &lsquo;<b>(</b>&rsquo; exp &lsquo;<b>)</b>&rsquo;

	functioncall ::=  prefixexp args | prefixexp &lsquo;<b>:</b>&rsquo; Name args 

	args ::=  &lsquo;<b>(</b>&rsquo; [explist] &lsquo;<b>)</b>&rsquo; | tableconstructor | LiteralString 

	functiondef ::= <b>function</b> funcbody

	funcbody ::= &lsquo;<b>(</b>&rsquo; [parlist] &lsquo;<b>)</b>&rsquo; block <b>end</b>

	parlist ::= namelist [&lsquo;<b>,</b>&rsquo; &lsquo;<b>...</b>&rsquo;] | &lsquo;<b>...</b>&rsquo;

	tableconstructor ::= &lsquo;<b>{</b>&rsquo; [fieldlist] &lsquo;<b>}</b>&rsquo;

	fieldlist ::= field {fieldsep field} [fieldsep]

	field ::= &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo; &lsquo;<b>=</b>&rsquo; exp | Name &lsquo;<b>=</b>&rsquo; exp | exp

	fieldsep ::= &lsquo;<b>,</b>&rsquo; | &lsquo;<b>;</b>&rsquo;

	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; | 
		 &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; | 
		 &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; | 
		 <b>and</b> | <b>or</b>

	unop ::= &lsquo;<b>-</b>&rsquo; | <b>not</b> | &lsquo;<b>#</b>&rsquo; | &lsquo;<b>~</b>&rsquo;

</pre>

<p>


<HR>
<SMALL CLASS="footer">
最后更新时间：
2015年1月18日19:54
</SMALL>

</body></html>