Lua1.1 Lua 的参考手册 （二）

（接上篇）

--------------------------------------
5 API
--------------------------------------
这节主要描述 Lua 的 API， 也就是宿主程序和库交互的一组 C 函数。API 函数可以分为以下几类：
1. 执行 Lua 代码；
2. 在 Lua 和 C 之间进行值的转化；
3. 操作（读写）Lua 对象；
4. 调用 Lua 函数；
5. 由 Lua 调用的 C 函数；
6. 错误处理。

所有的 API 都在文件 lua.h 中声明。除非另有说明，API 函数返回一个错误码：0 为成功，非 0 为失败。

-------------------
5.1 执行 Lua 代码
-------------------
一个宿主程序可以执行写在文件中或在字符串中的 Lua 代码，使用下面的函数：
int lua_dofile (char *filename);
int lua_dostring (char *string);

-------------------
5.2 在 Lua 和 C 之间进行值的转化
-------------------
因为 Lua 没有静态的类型系统，所有的在 Lua 和 C 之间传递的值的类型为 lua_Object，它像是 C 中的可保存任何 Lua 值的一个抽象的类型。 lua_Object 声明如下：
typedef struct Object *lua_Object;
Object 没有在 lua.h 中声明。

Lua 有垃圾回收。所以，不保证在一个 lua_Object 是可用的在执行了其它的 Lua 代码之后。一个好的编程实践是在这些值可用的时候把它转化为 C 语言的值，并且永远不要把它们保存在全局变量中。

可以使用下面的函数来检查一个 lua_Obejct 的类型：
int lua_isnil (lua_Object object);
int lua_isnumber (lua_Object object);
int lua_isstring (lua_Object object);
int lua_istable (lua_Object object);
int lua_iscfunction (lua_Object object);
int lua_isuserdata (lua_Object object);
它们返回 1 如果类型是指定的类型的话， 否则返回 0。

可以使用下面的函数把一个 lua_Object 转化为 C 类型：
float lua_getnumber (lua_Object object);
char *lua_getstring (lua_Object object);
char *lua_copystring (lua_Object object);
lua_CFunction lua_getcfunction (lua_Object object);
void *lua_getuserdata (lua_Object object);
lua_getnumber 可以把一个 lua_Obejct 转化为一个浮点数。这个 lua_Object 必须是一个数字或者一个可以转化为数字的字符串（见 4.2 节）；否则，该函数返回 0。

lua_getstring 把 lua_Object 转化为一个 string（char *）。这个 lua_Object 必须是一个字符串或者一个数字；否则，该函数返回 0 （空指针）。该函数不会创建一个新的字符串，它只是返回一个指向 Lua 环境中的字符串的指针。因为 Lua 有垃圾回收，没有什么保证这个指针在执行了另外的 Lua 代码之后依然有效。函数 lua_copystring 表现和 lua_getstring 完全一样，但是它返回那个字符串的一个全新拷贝。

lua_getfunction 把 lua_Object 转化为一个 C 函数。这个 lua_Obejct 类型必须为 Cfunction; 否则返回 0 （空指针）。类型 lua_CFunction 在 5.5 节中解释。

lua_getuserdata 把 lua_Object 转化为一个 void *。这个 lua_Obejct 类型必须为 userdata; 否则返回 0 （空指针）。

相反，把一个 C 类型转化为 lua_Obejct 类型用以下的函数：
int lua_pushnumber (float n);
int lua_pushstring (char *s);
int lua_pushcfunction (lua_CFunction f);
int lua_pushuserdata (void *u);
这些函数都接受一个 C 值，把它转化为 lua_Object，并把结果保存在 Lua 栈顶，在那里它可以被赋值给一个变量，做为参数传递给一个 Lua 函数，等（见下文）。为了完成设置，nil 或者 lua_Object 也可以压栈，用下面的函数：
int lua_pushnil (void);
int lua_pushobject (lua_Object object);

-------------------
5.3 操作Lua 对象
-------------------
可以使用以下的函数读取 Lua 全局变量的值：
lua_Object lua_getglobal (char *varname);

把前先压到栈顶的一个值保存到一个全局变量，用下面的函数：
int lua_storeglobal (char *varname);

表也可以通过 API 来操作，给定一个表，函数：
lua_Object lua_getindexed (lua_Object table, float index);
lua_Object lua_getfield (lua_Object table, char *field);
返回索引的内容。第一个用数字索引，第二个用任何的字符串索引。因为在 Lua 中，如果一个索引不在表中的话，返回的 Lua_Object 的值为 nil。

把前先压到栈顶的值保存到 Lua 表中的话，可以使用以下函数：
int lua_storeindexed (lua_Object object, float index);
int lua_storefield (lua_Object object, char *field);
同样，第一个用数字索引，第二个用字符串索引。
-------------------
5.4 调用 Lua 函数
-------------------
在宿主程序中可以调用由模块执行 dofile 或者 dostring 定义的函数。这采用如下的协议：前行，函数参数压到 Lua 栈上（详见 5.2 节），压栈的顺序和参数一致，也就是第一个参数首先压栈。然后，函数调用可以用：
int lua_call (char *functionname, int nparam);
第二个参数（nparam）是被压到栈上的值的个数。最后，返回的值（Lua 函数可以返回多个值）以逆序出栈，也就是最后一个返回值最先出栈。出栈用下面的函数：
lua_Object lua_pop (void);
当没有返回值可出栈时，函数返回 0。
7.5 节有一个 C 代码调用 Lua 函数的例子。

-------------------
5.5 C 函数
-------------------
注册 C 函数到 Lua ，用下面的宏：
#define lua_register(n,f) (lua_pushcfunction(f), lua_storeglobal(n))
/* char *n; */
/* lua_CFunction f; */
它接受函数在 Lua 中的名字，一个函数指针。这个指针的类型必须为 lua_CFunction，其定义为：
typedef void (*lua_CFunction) (void);
也就是一个无参无返回值的函数指针。

为了和 Lua 正确的交互，C 函数必须遵守一个协议，这个协议规定了参数和返回值传递的方法。
为了得到它的参数，C 函数调用 ：
lua_Object lua_getparam (int number);
number 从 1 开始返回第一个参数。当用一个大于参数实际个数的值来调用时，该函数返回 0。用这种方法，写可变参数个数的函数就是可行的。
为了从 C 返回值到 Lua, C 函数可以把返回值顺序压栈；见 5.2 节。就像 Lua 函数一样，一个由 Lua 调用的 C 函数也可以返回多个值。

7.4 节展示了一个 Cfunction 的例子。

-------------------
5.6 错误处理
-------------------
当在 Lua 编译或执行时出现一个错误的时候，会调用一个查错程序，相应的 lua_dofile 或 lua_dostring 会中断并返回一个出错状态。

查错程序的唯一的一个参数就是一个字符串，它描述了出现的错误和一个额外的信息，像当前的行（当错误发生在编译时）或者当前的函数（当错误发生在运行时）。错误的查错程序只是打印这个信息到标准错误输出。如果需要的话，可以给它设置一个新的查错程序，用下面的函数：
void lua_errorfunction (void (*fn) (char *s));
它的参数是错误处理函数的地址。

--------------------------------------
6 预定义的函数和库
--------------------------------------
Lua 的一组预定义函数虽少但功能强大。他们中大多数提供的功能让语言有一定程度的自反性。这些功能不能通过语言的其它部分模拟也不能通过标准的 API 模拟。

库，在另一方面，提供了一种通过标准 API 实现的有用的程序。因此，它们并非语言必须的部分，并且作为单独的 C 模块被提供，它可以根据需要被连接到应用程序。
目前，有三个库：
字符串处理
数学函数（sin, cos, 等）
输入输出

预定义函数能处理以下任务：执行包含在一个文件或字符串中的 Lua 模块；遍历一个表的所有字段；枚举所有的全局变量；类型查询和转换。

-------------------
6.1 预定义函数
-------------------
dofile (filename)
函数接受一个函数名字，打开并执行它的内容做为一个 Lua 模块。它返回 1 如果没有出错，否则返回 0。

dostring (string)
函数执行一个给定的字符串做为一个 Lua 模块，没有错误返回 1， 否则返回 0。

next (table, index)
函数允许一个程序枚举一个表的所有字段。它的第一个参数是一个表，第二个参数是表中的索引；这个索引可以是数字或字符串。它返回表的下一个键值对（索引及和索引关联的值）。当用 nil 做为第二个参数调用它时，函数返回表的第一个健值对。当用最后一个索引调用，或者用 nil 调用一个空表，均返回 nil。

Lua 中没有字段的声明；在语义上，表中一个字段不存在和字段的值为 nil 没有区别。所以，该函数只考虑没有空值的字段。索引的枚举顺序没有规定，就算是数字索引的也没有规定。

7.1 节有一个使用这个函数的例子。

nextvar (name)
函数和 next 函数类似，但它在全局变量上遍历。它的参数是全局变量的名字，或者是 nil （可以获得第一个名字）。和 next 类似，它返回另一个变量的名字和值。或者是 nil 如果没有更多的变量了（遍历结束了）。
7.1 节 有一个使用这个函数的例子。

print (e1, e2, ...)
函数可以接受任意数量的参数，以一种合理的格式打印它们的值。每一个值都在一个新行上打印。这个函数不是为了格式化输出，只是为了以一种快速的方法显示一个值，例如打印一个出错信息或者调试。详见 6.4 节一个格式化输出函数。

tonumber (e)
函数接受一个参数，尝试把它转化为一个数字。如果参数已经是一个数字或者是一个可以转化为数字的字符串（详见 4.2 节），它返回那个数字；否则，返回 nil。

type (v)
函数允许 Lua 测试一个值的类型。它接受一个参数，返回它的类型，以一个字符串表示。这个函数可能的返回值是：
'nil'
'number'
'string'
'table'
'cfunction'
'function'
'userdata'

-------------------
6.2 字符串处理
-------------------
这个库提供字符串处理的通用函数，如查找和提取子串。索引一个字符串的时候，第一个字符的索引是 1。7.2 节有一些字符串处理的例子。

strfind (str, substr)
接受两个字符串参数，返回一个数字。这个数字标明第二个参数在第一个参数中第一次出现的位置。如果第二个参数不是第一个参数的子串，返回 nil。

strlen (s)
接受一个字符串返回它的长度。

strsub (s, i, j)
返回另一个字符串，它是 s 的子串，始于 i 终于 j 。 如果 j 不指定或者为 nil，它被假定为 s 的长度。特别的，strsub(s,1,j) 调用返回 s 的 j 个字符的前缀，strsub(s,i) 返回 s 的后缀。

strlower (s)
接受一个字符串，返回它的所有大写字母都转化为小写的拷贝。其它的字符保持不变。

strupper (s)
接受一个字符串，返回它的所有小写字母都转化为大写的拷贝。其它的字符保持不变。

-------------------
6.3 数学函数
-------------------
这个库到一些标准 C 函数库函数的一个接口。它提供了以下的函数：
abs acos asin atan ceil cos floor max min
mod pow sin sqrt tan
函数 floor, sqrt, pow, ceil, sin, cos, tan, asin, acos, 和 atan 只是到 C 函数库中同名函数的接口，不同之处是，在三角函数中，所有的角度被转化为弧度。

max 返回数字参数列表中的最大值，类似的，min 返回最小值。它们的参数个数都是任意的。

mode 和 C 语言中的 % 操作符是等价的。

-------------------
6.4 I/O
-------------------
Lua 中所有的 I/O 操作都是基于两个当前文件，一个是为了读，一个是为了写。当前的输入输出文件的初始值分别是 stdin, stdout。
除非特别规定，所有的 I/O 函数功能时返回 1 失败时返回 nil。

readfrom (filename)
函数打开一个名为 filename 的文件并且把它设置为当前的入出文件。当无参调用它时，这个函数把当前的输入文件恢复为 stdin。

writeto (filename)
函数打开一个名为 filename 的文件并且把它设置为当前的输出文件。注意，如果这个文件是已经存在，调用这个操作会清除它。当无参调用它时，这个函数把当前的输出文件恢复为 stdout。

appendto (filename)
函数打开一个名为 filename 的文件并且把它设置为当前的输出文件。不像 writeto 操作，这个函数不会清除文件之前的内容。当无参调用它时，这个函数把当前的输出文件恢复为 stdout。这个函数返回 2 如果文件已经存在，返回 1 如果新建了一个文件，返回 nil 如果失败。

read ([format])
函数返回从当前输入读取的值。一个可选的参数指定输入的解释方式。

如果没有格式化参数，read 首先跳过空白（空格，制表符，换行符）。然后它检查当前的字符是否是单引号或双引号（”，’）。如果是，它读取一个字符串直到字符串结束标志，并且返回这个字符串，不带字符串的标志符。否则，它读取直到另一个空白（空格，制表符，换行符）。

格式化字符串可以是以下的形式：
?[n]
? 可以是：
's' 或者 'S' 读一个字符串；
'f' 或者 'F' 读一个实数；
'i' 或者 'I' 读一个整数。
可选的 n 是一个数字指示为了构成输入而必须读取多少个字符。

write (value, [format])
函数写第一个参数的值到当前输出。可选的第二个参数指示使用格式。这个格式作为一个字符串给出，由四部分组成。第一个部分是必不少的，它必须是下面的几个字符之一：
's' 或者 'S' 写字符串；
'f' 或者 'F' 写实数；
'i' 或者 'I' 写整数。
这些字符可以后接：
[?][m][.n]

？ 指示字段的对齐方式
'<' 右对齐
'>' 左对齐
'|' 居中对齐

m 指示字符的大小

.n 对于实数，指示小数点的位数。对于整数，它是最小位数。对于字符串此位无意义。

当这个函数调用没有给出格式字符串时，这个函数写数字使用 %g 格式，写字符串使用 %s 。

（未完待续）