Lua1.1 Lua 的参考手册 (二)

转载出处:http://my.oschina.net/xhan/blog/310017

 

(接上篇)

 

--------------------------------------

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 。

 

(未完待续)

你可能感兴趣的:(Lua1.1 Lua 的参考手册 (二))