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 。

(未完待续)

你可能感兴趣的:(lua,Lua1.1)