Lua 5.1 参考手册

by Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes

云风 译 www.codingnow.com

checkip | getIP

Copyright© 2006 Lua.org, PUC-Rio. All rights reserved.

1 - 介绍

Lua 是一个扩展式程序设计语言,它被设计成支持通用的过程式编程,并有相关数据描述的设施。 Lua 也能对面向对象编程,函数式编程,数据驱动式编程提供很好的支持。 它可以作为一个强大、轻量的脚本语言,供任何需要的程序使用。 Lua 以一个用 clean C 写成的库形式提供。(所谓 Clean C ,指的 ANSI C 和 C++ 中共通的一个子集)

作为一个扩展式语言,Lua 没有 "main" 程序的概念:它只能 嵌入 一个宿主程序中工作,这个宿主程序被称作 embedding program 或简称为 host 。 宿主程序可以通过调用函数执行一小段 Lua 代码,可以读写 Lua 变量,可以注入 C 函数让 Lua 代码调用。 这些扩展的 C 函数,可以大大的扩展了 Lua 可以处理事务的领域,这样就可以订制出各种语言, 而它们共享一个统一的句法格式的框架。 Lua 的官方发布版就包含了一个叫做 lua 的简单的宿主程序,它用 Lua 库提供了一个保证独立的 Lua 解释器。

Lua 是一个自由软件,它的使用许可决定了对它的使用过程一般没有任何保证。 这份手册中描述的东西的实现,可以在 Lua 的官方网站 www.lua.org 找到,

跟其它的许多参考手册一样,这份文档有些地方比较枯燥。 关于 Lua 的设计想法的探讨,可以看看 Lua 网站上提供的技术论文。 有关用 Lua 编程的细节介绍,可以读一下 Roberto 的书,Programming in Lua (Second Edition)

2 - 语言

这一节从词法、语法、句法上描述 Lua 。 换句话说,这一节描述了哪些 token (符记)是有效的,它们如何被组合起来,这些组合方式有什么含义。

关于语言的构成概念将用常见的扩展 BNF 表达式写出。也就是这个样子: {a} 意思是 0 或多个 a , [a] 意思是一个可选的 a 。 非最终的符号会保留原来的样子,关键字则看起来像这样 kword , 其它最终的符号则写成 `=´ 。 完整的 Lua 语法可以在本手册最后找到。

2.1 - 词法约定

Lua 中用到的 名字(也称作 标识符)可以是任何非数字开头的字母、数字、下划线组成的字符串。 这符合几乎所有编程语言中关于名字的定义。 (字母的定义依赖于当前环境:系统环境中定义的字母表中的字母都可以被用于标识符。) 标识符用来命名变量,或作为表的域名。

下面的关键字是保留的,不能用作名字:

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

Lua 是一个大小写敏感的语言: and 是一个保留字,但是 AndAND 则是两个不同的合法的名字。 一般约定,以下划线开头连接一串大写字母的名字(比如 _VERSION)被保留用于 Lua 内部全局变量。

下面这些是其它的 token :

     +     -     *     /     %     ^     #
     ==    ~=    <=    >=    <     >     =
     (     )     {     }     [     ]
     ;     :     ,     .     ..    ...

字符串既可以用一对单引号引起,也可以是双引号,里面还可以包含类似 C 的转义符: '\a' (响铃), '\b' (退格), '\f' (表单), '\n' (换行), '\r' (回车), '\t' (横向制表), '\v' (纵向制表), '\\' (反斜杠), '\"' (双引号), 以及 '\'' (单引号)。 而且,如果在一个反斜杠后跟了一个真正的换行符,其结果就是在字符串中产生一个换行符。 我们还可以用反斜杠加数字的形式 \ddd 来描述一个字符。这里, ddd 是一串最多三位的十进制数字。(注意,如果需要在这种描述方法后接一个是数字的字符, 那么反斜杠后必须写满三个数字。)Lua 中的字符串可以包含任何 8 位的值。包括用 '\0' 表示的零。

只有在你需要把不同的引号、换行、反斜杠、或是零结束符这些字符置入字符串时, 你才必须使用转义符。别的任何字符都可以直接写在文本里。(一些控制符可以会影响文件系统造成某些问题, 但是不会引起 Lua 的任何问题。)

字符串还可以用一种长括号括起来的方式定义。 我们把两个正的方括号间插入 n 个等号定义为第 n 级正长括号。 就是说,0 级正的长括号写作 [[ , 一级正的长括号写作 [=[ ,如此等等。 反的长扩展也作类似定义; 举个例子,4 级反的长括号写作 ]====] 。 一个长字符串可以由任何一级的正的长括号开始,而由第一个碰到的同级反的长括号结束。 整个词法分析过程将不受分行限制,不处理任何转意符,并且忽略掉任何不同级别的长括号。 这种方式描述的字符串可以包含任何东西,当然特定级别的反长括号除外。

另一个约定是,当正的长括号后面立即跟了一个换行符, 这个换行符就不包含在这个字符串内。 举个例子,假设一个系统使用 ASCII 码 (这时,'a' 编码为 97 ,换行符编码为 10 ,'1' 编码为 49 ), 下面五种方式描述了完全相同的字符串:

     a = 'alo\n123"'
     a = "alo\n123\""
     a = '\97lo\10\04923"'
     a = [[alo
     123"]]
     a = [==[
     alo
     123"]==]

数字常量可以分两部分写,十进制底数部分和十进制的指数部分。指数部分是可选的。 Lua 也支持十六进制整数常量,只需要在前面加上前缀 0x 。 下面是一些合法的数字常量的例子:


     3   3.0   3.1416   314.16e-2   0.31416E1   0xff   0x56

注释可以在除字符串内的任何地方是以两横 (--) 开始。 如果跟在两横后面的不是一个长括号,这就是一个短注释,它的作用范围直到行末; 否则就是一个长注释,其作用范围直到遇到反的长括号。 长注释通常被用来临时屏蔽代码块。

2.2 - 值与类型

Lua 是一种 动态类型语言。 这意味着变量没有类型,只有值才有类型。 语言中不存在类型定义。而所有的值本身携带它们自己的类型信息。

Lua 中的所有值都是一致 (first-class) 的。 这意味着所有的值都可以被放在变量里,当作参数传递到另一个函数中,并被函数作为结果返回。

Lua 中有八种基本类型: nil, boolean, number, string, function, userdata, thread, and table. Nil 类型只有一种值 nil ,它的主要用途用于标表识和别的任何值的差异; 通常,当需要描述一个无意义的值时会用到它。 Boolean 类型只有两种值:falsetruenilfalse 都能导致条件为假;而另外所有的值都被当作真。 Number 表示实数(双精度浮点数)。 (编译一个其它内部数字类型的 Lua 解释器是件很容易的事;比如把内部数字类型改作 单精度浮点数或长整型。参见文件 luaconf.h 。) String 表示一串字符的数组。 Lua 是 8-bit clean 的: 字符串可以包含任何 8 位字符, 包括零结束符 ('\0') (参见 §2.1)。

Lua 可以调用(和处理)用 Lua 写的函数以及用 C 写的函数(参见 §2.5.8).

userdata 类型用来将任意 C 数据保存在 Lua 变量中。 这个类型相当于一块原生的内存,除了赋值和相同性判断,Lua 没有为之预定义任何操作。 然而,通过使用 metatable (元表) ,程序员可以为 userdata 自定义一组操作 (参见 §2.8)。 userdata 不能在 Lua 中创建出来,也不能在 Lua 中修改。这样的操作只能通过 C API。 这一点保证了宿主程序完全掌管其中的数据。

thread 类型用来区别独立的执行线程,它被用来实现 coroutine (协同例程)(参见 §2.11)。 不要把 Lua 线程跟操作系统的线程搞混。 Lua 可以在所有的系统上提供对 coroutine 的支持,即使系统并不支持线程。

table 类型实现了一个关联数组。也就是说, 数组可以用任何东西(除了nil)做索引,而不限于数字。 table 可以以不同类型的值构成;它可以包含所有的类型的值(除 nil 外)。 table 是 lua 中唯一的一种数据结构;它可以用来描述原始的数组、符号表、集合、 记录、图、树、等等。 用于表述记录时,lua 使用域名作为索引。 语言本身采用一种语法糖,支持以 a.name 的形式表示 a["name"]。 有很多形式用于在 lua 中创建一个 table (参见 §2.5.7)。

跟索引一样, table 每个域中的值也可以是任何类型(除 nil外)。 特别的,因为函数本身也是值,所以 table 的域中也可以放函数。 这样 table 中就可以有一些 methods 了 (参见see §2.5.9)。

table, function ,thread ,和 (full) userdata 这些类型的值是所谓的对象: 变量本身并不会真正的存放它们的值,而只是放了一个对对象的引用。 赋值,参数传递,函数返回,都是对这些对象的引用进行操作; 这些操作不会做暗地里做任何性质的拷贝。

库函数 type 可以返回一个描述给定值的类型的字符串。

2.2.1 - 强制转换

Lua 提供运行时字符串到数字的自动转换。 任何对字符串的数学运算操作都会尝试用一般的转换规则把这个字符串转换成一个数字。 相反,无论何时,一个数字需要作为字符串来使用时,数字都会以合理的格式转换为字符串。 需要完全控制数字怎样转换为字符串,可以使用字符串库中的 format 函数 (参见 string.format)。

2.3 - 变量

写上变量的地方意味着当以其保存的值来替代之。 Lua 中有三类变量:全局变量,局部变量,还有 table 的域。

一个单一的名字可以表示一个全局变量,也可以表示一个局部变量 (或者是一个函数的参数,这是一种特殊形式的局部变量):


	var ::= Name

Name 就是 §2.1 中所定义的标识符。

任何变量都被假定为全局变量,除非显式的以 local 修饰定义 (参见 §2.4.7)。 局部变量有其作用范围: 局部变量可以被定义在它作用范围中的函数自由使用 (参见 §2.6)。

在变量的首次赋值之前,变量的值均为 nil

方括号被用来对 table 作索引:

	var ::= prefixexp `[´ exp `]´

对全局变量以及 table 域之访问的含义可以通过 metatable 来改变。 以取一个变量下标指向的量 t[i] 等价于调用 gettable_event(t,i)。 (参见 §2.8 ,有一份完整的关于 gettable_event 函数的说明。 这个函数并没有在 lua 中定义出来,也不能在 lua 中调用。 这里我们把它列出来只是方便说明。)

var.Name 这种语法只是一个语法糖,用来表示 var["Name"]

	var ::= prefixexp `.´ Name

所有的全局变量都是放在一个特定 lua table 的诸个域中,这个特定的 table 叫作 environment (环境)table 或者简称为 环境 (参见 §2.9)。 每个函数都有对一个环境的引用, 所以一个函数中可见的所有全局变量都放在这个函数所引用的环境表(environment table)中。 当一个函数被创建出来,它会从创建它的函数中继承其环境,你可以调用 getfenv 取得其环境。 如果想改变环境,可以调用 setfenv。 (对于 C 函数,你只能通过 debug 库来改变其环境; 参见 §5.9)。

对一个全局变量 x 的访问 等价于 _env.x,而这又可以等价于

     gettable_event(_env, "x")

这里,_env 是当前运行的函数的环境。 (函数 gettable_event 的完整说明参见 §2.8。 这个函数并没有在 lua 中定义出来,也不能调用。 当然,_env 这个变量也同样没有在 Lua 中定义出来。 我们在这里使用它们,仅仅只是方便解释而已。)

2.4 - 语句段(Statement)

Lua 支持惯例形式的语句段,它和 Pascal 或是 C 很相象。 这个集合包括赋值,控制结构,函数调用,还有变量声明。

2.4.1 - Chunk(语句组)

Lua 的一个执行单元被称作 chunk。 一个 chunk 就是一串语句段,它们会被循序的执行。 每个语句段可以以一个分号结束:

	chunk ::= {stat [`;´]}

这儿不允许有空的语句段,所以 ';;' 是非法的。

lua 把一个 chunk 当作一个拥有不定参数的匿名函数 (参见 §2.5.9)处理。 正是这样,chunk 内可以定义局部变量,接收参数,并且返回值。

chunk 可以被保存在一个文件中,也可以保存在宿主程序的一个字符串中。 当一个 chunk 被执行,首先它会被预编译成虚拟机中的指令序列, 然后被虚拟机解释运行这些指令。

chunk 也可以被预编译成二进制形式;细节参考程序 luac。 用源码形式提供的程序和被编译过的二进制形式的程序是可以相互替换的; Lua 会自动识别文件类型并做正确的处理。

2.4.2 - 语句块

语句块是一列语句段;从语法上来说,一个语句块跟一个 chunk 相同:

	block ::= chunk

一个语句块可以被显式的写成一个单独的语句段:

	stat ::= do block end

显式的语句块对于控制变量的作用范围很有用。 有时候,显式的语句块被用来在另一个语句块中插入 return 或是 break (参见 §2.4.4)。

2.4.3 - 赋值

Lua 允许多重赋值。 因此,赋值的语法定义是等号左边放一系列变量, 而等号右边放一系列的表达式。 两边的元素都用逗号间开:

	stat ::= varlist1 `=´ explist1
	varlist1 ::= var {`,´ var}
	explist1 ::= exp {`,´ exp}

表达式放在 §2.5 里讨论。

在作赋值操作之前, 那一系列的右值会被对齐到左边变量需要的个数。 如果右值比需要的更多的话,多余的值就被扔掉。 如果右值的数量不够需求, 将会按所需扩展若干个 nil。 如果表达式列表以一个函数调用结束, 这个函数所返回的所有值都会在对齐操作之前被置入右值序列中。 (除非这个函数调用被用括号括了起来;参见 §2.5)。

赋值段首先会做运算完所有的表达式,然后仅仅做赋值操作。 因此,下面这段代码

     i = 3
     i, a[i] = i+1, 20

会把 a[3] 设置为 20,而不会影响到 a[4] 。 这是因为 a[i] 中的 i 在被赋值为 4 之前就被拿出来了(那时是 3 )。 简单说 ,这样一行

     x, y = y, x

可以用来交换 xy 中的值。

对全局变量以及 table 中的域的赋值操作的含义可以通过 metatable 来改变。 对变量下标指向的赋值,即 t[i] = val 等价于 settable_event(t,i,val)。 (关于函数 settable_event 的详细说明,参见 §2.8。 这个函数并没有在 Lua 中定义出来,也不可以被调用。 这里我们列出来,仅仅出于方便解释的目的)

对于全局变量的赋值 x = val 等价于 _env.x = val,这个又可以等价于

     settable_event(_env, "x", val)

这里,_env 指的是正在运行中的函数的环境。 (变量 _env 并没有在 Lua 中定义出来。 我们仅仅出于解释的目的在这里写出来。)

2.4.4 - 控制结构

ifwhile、以及 repeat 这些控制结构符合通常的意义,而且也有类似的语法:

	stat ::= while exp do block end

	stat ::= repeat block until exp
	stat ::= if exp then block {elseif exp then block} [else block] end

Lua 也有一个 for 语句,它有两种形式(参见 §2.4.5)。

控制结构中的条件表达式可以返回任何值。 falsenil 两者都被认为是假条件。 所有不同于 nilfalse 的其它值都被认为是真 (特别需要注意的是,数字 0 和空字符串也被认为是真)。

repeatuntil 循环中, 内部语句块的结束点不是在 until 这个关键字处, 它还包括了其后的条件表达式。 因此,条件表达式中可以使用循环内部语句块中的定义的局部变量。

return 被用于从函数或是 chunk(其实它就是一个函数)中 返回值。 函数和 chunk 可以返回不只一个值, 所以 return 的语法为


	stat ::= return [explist1]

break 被用来结束 whilerepeat、或 for 循环, 它将忽略掉循环中下面的语句段的运行:

	stat ::= break

break 跳出最内层的循环。

returnbreak 只能被写在一个语句块的最后一句。 如果你真的需要从语句块的中间 return 或是 break , 你可以使用显式的声名一个内部语句块。 一般写作 do return end 或是 do break end, 可以这样写是因为现在 returnbreak 都成了一个语句块的最后一句了。

2.4.5 - For 语句

for 有两种形式:一种是数字形式,另一种是一般形式。

数字形式的 for 循环,通过一个数学运算不断的运行内部的代码块。 下面是它的语法:

	stat ::= for Name `=´ exp `,´ exp [`,´ exp] do block end

block 将把 name 作循环变量。从第一个 exp 开始起,直到第二个 exp 的值为止,其步长为 第三个 exp 。 更确切的说,一个 for 循环看起来是这个样子

     for v = e1, e2, e3 do block end

这等价于代码:

     do
       local var, limit, step = tonumber(e1), tonumber(e2), tonumber(e3)
       if not (var and limit and step) then error() end
       while (step > 0 and var <= limit) or (step <= 0 and var >= limit) do
         local v = var

         block
         var = var + step
       end
     end

注意下面这几点:

一般形式的 for 通过一个叫作迭代器(iterators)的函数工作。 每次迭代,迭代器函数都会被调用以产生一个新的值, 当这个值为 nil 时,循环停止。 一般形式的 for 循环的语法如下:

	stat ::= for namelist in explist1 do block end
	namelist ::= Name {`,´ Name}

for 语句好似这样

     for var_1, ···, var_n in explist do block end

它等价于这样一段代码:

     do
       local f, s, var = explist
       while true do
         local var_1, ···, var_n = f(s, var)
         var = var_1

         if var == nil then break end
         block
       end
     end

注意以下几点:

2.4.6 - 把函数调用作为语句段

为了允许使用可能的副作用, 函数调用可以被作为一个语句段执行:

	stat ::= functioncall

在这种情况下,所有的返回值都被舍弃。 函数调用在 §2.5.8 中解释。

2.4.7 - 局部变量声名

局部变量可以在语句块中任何地方声名。 声名可以包含一个初始化赋值操作:


	stat ::= local namelist [`=´ explist1]

如果有的话,初始化赋值操作的行为等同于赋值操作(参见 §2.4.3)。 否则,所有的变量将被初始化为 nil

一个 chunk 同时也是一个语句块(参见 §2.4.1), 所以局部变量可以放在 chunk 中那些显式注明的语句块之外。 这些局部变量的作用范围从声明起一直延伸到 chunk 末尾。

局部变量的可见规则在 §2.6 中解释。

2.5 - 表达式

Lua 中有这些基本表达式:

	exp ::= prefixexp
	exp ::= nil | false | true

	exp ::= Number
	exp ::= String
	exp ::= function
	exp ::= tableconstructor
	exp ::= `...´
	exp ::= exp binop exp
	exp ::= unop exp
	prefixexp ::= var | functioncall | `(´ exp `)´

数字和字符串在 §2.1 中解释; 变量在 §2.3 中解释; 函数定义在 §2.5.9 中解释; 函数调用在 §2.5.8 中解释; table 的构造在 §2.5.7 中解释; 可变参数的表达式写作三个点 ('...') ,它只能被用在有可变参数的函数中; 这些在 §2.5.9 中解释。

二元操作符包含有数学运算操作符(参见 §2.5.1), 比较操作符(参见 §2.5.2),逻辑操作符(参见 §2.5.3), 以及连接操作符(参见 §2.5.4)。 一元操作符包括负号(参见see §2.5.1), 取反 not(参见 §2.5.3), 和取长度操作符(参见 §2.5.5)。

函数调用和可变参数表达式都可以放在多重返回值中。 如果表达式作为一个独立语句段出现(参见 §2.4.6) (这只能是一个函数调用), 它们的返回列表将被对齐到零个元素,也就是忽略所有返回值。 如果表达式用于表达式列表的最后(或者是唯一)的元素, 就不会有任何的对齐操作(除非函数调用用括号括起来)。 在任何其它的情况下,Lua 将把表达式结果看成单一元素, 忽略除第一个之外的任何值。

这里有一些例子:

     f()                -- 调整到 0 个结果
     g(f(), x)          -- f() 被调整到一个结果
     g(x, f())          -- g 被传入 x 加上所有 f() 的返回值
     a,b,c = f(), x     -- f() 被调整到一个结果 ( c 在这里被赋为 nil )
     a,b = ...          -- a 被赋值为可变参数中的第一个,
                        -- b 被赋值为第二个 (如果可变参数中并没有对应的值,
						-- 这里 a 和 b 都有可能被赋为 nil)
     
     a,b,c = x, f()     -- f() 被调整为两个结果
     a,b,c = f()        -- f() 被调整为三个结果
     return f()         -- 返回 f() 返回的所有结果
     return ...         -- 返回所有从可变参数中接收来的值
     return x,y,f()     -- 返回 x, y, 以及所有 f() 的返回值
     {f()}              -- 用 f() 的所有返回值创建一个列表
     {...}              -- 用可变参数中的所有值创建一个列表
     {f(), nil}         -- f() 被调整为一个结果

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

2.5.1 - 数学运算操作符

Lua 支持常见的数学运算操作符: 二元操作 + (加法), - (减法),* (乘法), / (除法), % (取模),以及 ^ (幂); 和一元操作 - (取负)。 如果对数字操作,或是可以转换为数字的字符串(参见 §2.2.1), 所有这些操作都依赖它通常的含义。 幂操作可以对任何幂值都正常工作。比如, x^(-0.5) 将计算出 x 平方根的倒数。 取模操作被定义为

     a % b == a - math.floor(a/b)*b

这就是说,其结果是商相对负无穷圆整后的余数。(译注:负数对正数取模的结果为正数)

2.5.2 - 比较操作符

Lua 中的比较操作符有

     ==    ~=    <     >     <=    >=

这些操作的结果不是 false 就是 true

等于操作 (==) 首先比较操作数的类型。 如果类型不同,结果就是 false。 否则,继续比较值。 数字和字符串都用常规的方式比较。 对象 (table ,userdata ,thread ,以及函数)以引用的形式比较: 两个对象只有在它们指向同一个东西时才认为相等。 每次你创建一个新对象(一个 table 或是 userdata ,thread 函数), 它们都各不相同,即不同于上次创建的东西。

你可以改变 Lua 比较 table 和 userdata 的方式,这需要使用 "eq" 这个原方法 (参见 §2.8)。

§2.2.1 中提及的转换规则并不作用于比较操作。 所以, "0"==0 等于 false, 而且 t[0]t["0"] 描述的是 table 中不同的域。

操作符 ~= 完全等价于 (==) 操作的反值。

大小比较操作以以下方式进行。 如果参数都是数字,那么就直接做数字比较。 否则,如果参数都是字符串,就用字符串比较的方式进行。 再则,Lua 就试着调用 "lt" 或是 "le" 元方法 (参见 §2.8)。

2.5.3 - 逻辑操作符

Lua 中的逻辑操作符有 and, or, 以及 not。 和控制结构(参见 §2.4.4)一样, 所有的逻辑操作符把 falsenil 都作为假, 而其它的一切都当作真。

取反操作 not 总是返回 falsetrue 中的一个。 与操作符 and 在第一个参数为 falsenil 时 返回这第一个参数; 否则,and 返回第二个参数。 或操作符 or 在第一个参数不为 nil 也不为 false 时, 返回这第一个参数,否则返回第二个参数。 andor 都遵循短路规则; 也就是说,第二个操作数只在需要的时候去求值。 这里有一些例子:

     10 or 20            --> 10
     10 or error()       --> 10
     nil or "a"          --> "a"
     nil and 10          --> nil
     false and error()   --> false
     false and nil       --> false
     false or nil        --> nil
     10 and 20           --> 20

(在这本手册中, --> 指前面表达式的结果。)

2.5.4 - 连接符

Lua 中字符串的连接操作符写作两个点 ('..')。 如果两个操作数都是字符串或都是数字,连接操作将以 §2.2.1 中提到的规则把其转换为字符串。 否则,会取调用元方法 "concat" (参见 §2.8)。

2.5.5 - 取长度操作符

取长度操作符写作一元操作 #。 字符串的长度是它的字节数(就是以一个字符一个字节计算的字符串长度)。

table t 的长度被定义成一个整数下标 n 。 它满足 t[n] 不是 nilt[n+1]nil; 此外,如果 t[1]niln 就可能是零。 对于常规的数组,里面从 1 到 n 放着一些非空的值的时候, 它的长度就精确的为 n,即最后一个值的下标。 如果数组有一个“空洞” (就是说,nil 值被夹在非空值之间), 那么 #t 可能是指向任何一个是 nil 值的前一个位置的下标 (就是说,任何一个 nil 值都有可能被当成数组的结束)。

2.5.6 - 优先级

Lua 中操作符的优先级写在下表中,从低到高优先级排序:

     or
     and
     <     >     <=    >=    ~=    ==
     ..
     +     -
     *     /     %
     not   #     - (unary)
     ^

通常,你可以用括号来改变运算次序。 连接操作符 ('..') 和幂操作 ('^') 是从右至左的。 其它所有的操作都是从左至右。

2.5.7 - Table 构造

table 构造子是一个构造 table 的表达式。 每次构造子被执行,都会构造出一个新的 table 。 构造子可以被用来构造一个空的 table, 也可以用来构造一个 table 并初始化其中的一些域。 一般的构造子的语法如下

	tableconstructor ::= `{´ [fieldlist] `}´
	fieldlist ::= field {fieldsep field} [fieldsep]
	field ::= `[´ exp `]´ `=´ exp | Name `=´ exp | exp
	fieldsep ::= `,´ | `;´

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

     a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 }

等价于

     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

如果表单中最后一个域的形式是 exp , 而且其表达式是一个函数调用或者是一个可变参数, 那么这个表达式所有的返回值将连续的进入列表 (参见 §2.5.8)。 为了避免这一点,你可以用括号把函数调用(或是可变参数)括起来 (参见 §2.5)。

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

2.5.8 - 函数调用

Lua 中的函数调用的语法如下:

	functioncall ::= prefixexp args

函数调用时,第一步,prefixexp 和 args 先被求值。 如果 prefixexp 的值的类型是 function, 那么这个函数就被用给出的参数调用。 否则 prefixexp 的元方法 "call" 就被调用, 第一个参数就是 prefixexp 的值,跟下来的是原来的调用参数 (参见 §2.8)。

这样的形式

	functioncall ::= prefixexp `:´ Name args

可以用来调用 "方法"。 这是 Lua 支持的一种语法糖。像 v:name(args) 这个样子,被解释成 v.name(v,args), 这里 v 只会被求值一次。

参数的语法如下:

	args ::= `(´ [explist1] `)´

	args ::= tableconstructor
	args ::= String

所有参数的表达式求值都在函数调用之前。 这样的调用形式 f{fields} 是一种语法糖用于表示 f({fields}); 这里指参数列表是一个单一的新创建出来的列表。 而这样的形式 f'string' (或是 f"string" 亦或是 f[[string]]) 也是一种语法糖,用于表示 f('string'); 这里指参数列表是一个单独的字符串。

因为表达式语法在 Lua 中比较自由, 所以你不能在函数调用的 '(' 前换行。 这个限制可以避免语言中的一些歧义。 比如你这样写

     a = f
     (g).x(a)

Lua 将把它当作一个单一语句段, a = f(g).x(a) 。 因此,如果你真的想作为成两个语句段,你必须在它们之间写上一个分号。 如果你真的想调用 f, 你必须从 (g) 前移去换行。

这样一种调用形式:return functioncall 将触发一个尾调用。 Lua 实现了适当的尾部调用(或是适当的尾递归): 在尾调用中, 被调用的函数重用调用它的函数的堆栈项。 因此,对于程序执行的嵌套尾调用的层数是没有限制的。 然而,尾调用将删除调用它的函数的任何调试信息。 注意,尾调用只发生在特定的语法下, 这时, return 只有单一函数调用作为参数; 这种语法使得调用函数的结果可以精确返回。 因此,下面这些例子都不是尾调用:

     return (f(x))        -- 返回值被调整为一个
     return 2 * f(x)
     return x, f(x)       -- 最加若干返回值
     f(x); return         -- 无返回值
     return x or f(x)     -- 返回值被调整为一个

2.5.9 - 函数定义

函数定义的语法如下:

	function ::= function funcbody
	funcbody ::= `(´ [parlist1] `)´ block end

另外定义了一些语法糖简化函数定义的写法:

	stat ::= function funcname funcbody
	stat ::= local function Name funcbody
	funcname ::= Name {`.´ Name} [`:´ Name]

这样的写法:

     function f () body end

被转换成

     f = function () body end

这样的写法:

     function t.a.b.c.f () body end

被转换成

     t.a.b.c.f = function () body end

这样的写法:

     local function f () body end

被转换成

     local f; f = function () body end

注意,并不是转换成


     local f = function () body end

(这个差别只在函数体内需要引用 f 时才有。)

一个函数定义是一个可执行的表达式, 执行结果是一个类型为 function 的值。 当 Lua 预编译一个 chunk 的时候, chunk 作为一个函数,整个函数体也就被预编译了。 那么,无论何时 Lua 执行了函数定义, 这个函数本身就被实例化了(或者说是关闭了)。 这个函数的实例(或者说是 closure(闭包)) 是表达式的最终值。 相同函数的不同实例有可能引用不同的外部局部变量, 也可能拥有不同的环境表。

形参(函数定义需要的参数)是一些由实参(实际传入参数)的值初始化的局部变量:

	parlist1 ::= namelist [`,´ `...´] | `...´

当一个函数被调用, 如果函数没有被定义为接收不定长参数,即在形参列表的末尾注明三个点 ('...'), 那么实参列表就会被调整到形参列表的长度, 变长参数函数不会调整实参列表; 取而代之的是,它将把所有额外的参数放在一起通过变长参数表达式传递给函数, 其写法依旧是三个点。 这个表达式的值是一串实参值的列表,看起来就跟一个可以返回多个结果的函数一样。 如果一个变长参数表达式放在另一个表达式中使用,或是放在另一串表达式的中间, 那么它的返回值就会被调整为单个值。 若这个表达式放在了一系列表达式的最后一个,就不会做调整了(除非用括号给括了起来)。

我们先做如下定义,然后再来看一个例子:

     function f(a, b) end
     function g(a, b, ...) end
     function r() return 1,2,3 end

下面看看实参到形参数以及可变长参数的映射关系:

     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, ... -->  (nothing)
     g(3, 4)          a=3, b=4,   ... -->  (nothing)
     g(3, 4, 5, 8)    a=3, b=4,   ... -->  5  8
     g(5, r())        a=5, b=1,   ... -->  2  3

结果由 return 来返回(参见 §2.4.4)。 如果执行到函数末尾依旧没有遇到任何 return 语句, 函数就不会返回任何结果。

冒号语法可以用来定义方法, 就是说,函数可以有一个隐式的形参 self。 因此,如下写法:


     function t.a.b.c:f (params) body end

是这样一种写法的语法糖:

     t.a.b.c.f = function (self, params) body end

2.6 - 可视规则

Lua 是一个有词法作用范围的语言。 变量的作用范围开始于声明它们之后的第一个语句段, 结束于包含这个声明的最内层语句块的结束点。 看下面这些例子:

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

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

因为有这样一个词法作用范围的规则, 所以可以在函数内部自由的定义局部变量并使用它们。 当一个局部变量被更内层的函数中使用的时候, 它被内层函数称作 upvalue(上值),或是 外部局部变量

注意,每次执行到一个 local 语句都会定义出一个新的局部变量。 看看这样一个例子:

     a = {}
     local x = 20
     for i=1,10 do
       local y = 0
       a[i] = function () y=y+1; return x+y end
     end

这个循环创建了十个 closure(这指十个匿名函数的实例)。 这些 closure 中的每一个都使用了不同的 y 变量, 而它们又共享了同一份 x

2.7 - 错误处理

因为 Lua 是一个嵌入式的扩展语言, 所有的 Lua 动作都是从宿主程序的 C 代码调用 Lua 库 (参见 lua_pcall)中的一个函数开始的。 在 Lua 编译或运行的任何时候发生了错误,控制权都会交还给 C , 而 C 可以来做一些恰当的措施(比如打印出一条错误信息)。

Lua 代码可以显式的调用 error 函数来产生一条错误。 如果你需要在 Lua 中捕获发生的错误, 你可以使用 pcall 函数。

2.8 - Metatable(元表)

Lua 中的每个值都可以用一个 metatable。 这个 metatable 就是一个原始的 Lua table , 它用来定义原始值在特定操作下的行为。 你可以通过在 metatable 中的特定域设一些值来改变拥有这个 metatable 的值 的指定操作之行为。 举例来说,当一个非数字的值作加法操作的时候, Lua 会检查它的 metatable 中 "__add" 域中的是否有一个函数。 如果有这么一个函数的话,Lua 调用这个函数来执行一次加法。

我们叫 metatable 中的键名为 事件 (event) ,把其中的值叫作 元方法 (metamethod)。 在上个例子中,事件是 "add" 而元方法就是那个执行加法操作的函数。

你可以通过 getmetatable 函数来查询到任何一个值的 metatable。

你可以通过 setmetatable 函数来替换掉 table 的 metatable 。 你不能从 Lua 中改变其它任何类型的值的 metatable (使用 debug 库例外); 要这样做的话必须使用 C API 。

每个 table 和 userdata 拥有独立的 metatable (当然多个 table 和 userdata 可以共享一个相同的表作它们的 metatable); 其它所有类型的值,每种类型都分别共享唯一的一个 metatable。 因此,所有的数字一起只有一个 metatable ,所有的字符串也是,等等。

一个 metatable 可以控制一个对象做数学运算操作、比较操作、连接操作、取长度操作、取下标操作时的行为, metatable 中还可以定义一个函数,让 userdata 作垃圾收集时调用它。 对于这些操作,Lua 都将其关联上一个被称作事件的指定健。 当 Lua 需要对一个值发起这些操作中的一个时, 它会去检查值中 metatable 中是否有对应事件。 如果有的话,键名对应的值(元方法)将控制 Lua 怎样做这个操作。

metatable 可以控制的操作已在下面列出来。 每个操作都用相应的名字区分。 每个操作的键名都是用操作名字加上两个下划线 '__' 前缀的字符串; 举例来说,"add" 操作的键名就是字符串 "__add"。 这些操作的语义用一个 Lua 函数来描述解释器如何执行更为恰当。

这里展示的用 Lua 写的代码仅作解说用; 实际的行为已经硬编码在解释器中,其执行效率要远高于这些模拟代码。 这些用于描述的的代码中用到的函数 ( rawgettonumber ,等等。) 都可以在 §5.1 中找到。 特别注意,我们使用这样一个表达式来从给定对象中提取元方法

     metatable(obj)[event]

这个应该被解读作

     rawget(getmetatable(obj) or {}, event)

这就是说,访问一个元方法不再会触发任何的元方法, 而且访问一个没有 metatable 的对象也不会失败(而只是简单返回 nil)。

2.9 - 环境

类型为 thread ,function ,以及 userdata 的对象,除了 metatable 外还可以用另外一个与之关联的被称作 它们的环境的一个表, 像 metatable 一样,环境也是一个常规的 table ,多个对象可以共享 同一个环境。

userdata 的环境在 Lua 中没有意义。 这个东西只是为了在程序员想把一个表关联到一个 userdata 上时提供便利。

关联在线程上的环境被称作全局环境。 全局环境被用作它其中的线程以及线程创建的非嵌套函数 (通过 loadfileloadstring 或是 load )的缺省环境。 而且它可以被 C 代码直接访问(参见 §3.3)。

关联在 C 函数上的环境可以直接被 C 代码访问(参见 §3.3)。 它们会作为这个 C 函数中创建的其它函数的缺省环境。

关联在 Lua 函数上的环境用来接管在函数内对全局变量(参见 §2.3)的所有访问。 它们也会作为这个函数内创建的其它函数的缺省环境。

你可以通过调用 setfenv 来改变一个 Lua 函数 或是正在运行中的线程的环境。 而想操控其它对象(userdata、C 函数、其它线程)的环境的话,就必须使用 C API 。

2.10 - 垃圾收集

Lua 提供了一个自动的内存管理。 这就是说你不需要关心创建新对象的分配内存操作,也不需要在这些对象不再需要时的主动释放内存。 Lua 通过运行一个垃圾收集器来自动管理内存,以此一遍又一遍的回收死掉的对象 (这是指 Lua 中不再访问的到的对象)占用的内存。 Lua 中所有对象都被自动管理,包括: table, userdata、 函数、线程、和字符串。

Lua 实现了一个增量标记清除的收集器。 它用两个数字来控制垃圾收集周期: garbage-collector pausegarbage-collector step multiplier

garbage-collector pause 控制了收集器在开始一个新的收集周期之前要等待多久。 随着数字的增大就导致收集器工作工作的不那么主动。 小于 1 的值意味着收集器在新的周期开始时不再等待。 当值为 2 的时候意味着在总使用内存数量达到原来的两倍时再开启新的周期。

step multiplier 控制了收集器相对内存分配的速度。 更大的数字将导致收集器工作的更主动的同时,也使每步收集的尺寸增加。 小于 1 的值会使收集器工作的非常慢,可能导致收集器永远都结束不了当前周期。 缺省值为 2 ,这意味着收集器将以内存分配器的两倍速运行。

你可以通过在 C 中调用 lua_gc 或是在 Lua 中调用 collectgarbage 来改变这些数字。 两者都接受百分比数值(因此传入参数 100 意味着实际值 1 )。 通过这些函数,你也可以直接控制收集器(例如,停止或是重启)。

2.10.1 - 垃圾收集的元方法

使用 C API , 你可以给 userdata (参见 §2.8)设置一个垃圾收集的元方法。 这个元方法也被称为结束子。 结束子允许你用额外的资源管理器和 Lua 的内存管理器协同工作 (比如关闭文件、网络连接、或是数据库连接,也可以说释放你自己的内存)。

一个 userdata 可被回收,若它的 metatable 中有 __gc 这个域 , 垃圾收集器就不立即收回它。 取而代之的是,Lua 把它们放到一个列表中。 最收集结束后,Lua 针对列表中的每个 userdata 执行了下面这个函数的等价操作:

     function gc_event (udata)
       local h = metatable(udata).__gc
 then require signals an error. 





package.cpath

The path used by require to search for a C loader.

Lua initializes the C path package.cpath in the same way it initializes the Lua path package.path, using the environment variable LUA_CPATH (plus another default path defined in luaconf.h).


package.loaded

A table used by require to control which modules are already loaded. When you require a module modname and package.loaded[modname] is not false, require simply returns the value stored there.


package.loadlib (libname, funcname)

Dynamically links the host program with the C library libname. Inside this library, looks for a function funcname and returns this function as a C function. (So, funcname must follow the protocol (see lua_CFunction)).

This is a low-level function. It completely bypasses the package and module system. Unlike require, it does not perform any path searching and does not automatically adds extensions. libname must be the complete file name of the C library, including if necessary a path and extension. funcname must be the exact name exported by the C library (which may depend on the C compiler and linker used).

This function is not supported by ANSI C. As such, it is only available on some platforms (Windows, Linux, Mac OS X, Solaris, BSD, plus other Unix systems that support the dlfcn standard).


package.path

The path used by require to search for a Lua loader.

At start-up, Lua initializes this variable with the value of the environment variable LUA_PATH or with a default path defined in luaconf.h, if the environment variable is not defined. Any ";;" in the value of the environment variable is replaced by the default path.

A path is a sequence of templates separated by semicolons. For each template, require will change each interrogation mark in the template by filename, which is modname with each dot replaced by a "directory separator" (such as "/" in Unix); then it will try to load the resulting file name. So, for instance, if the Lua path is

     "./?.lua;./?.lc;/usr/local/?/init.lua"

the search for a Lua loader for module foo will try to load the files ./foo.lua, ./foo.lc, and /usr/local/foo/init.lua, in that order.


package.preload

A table to store loaders for specific modules (see require).


package.seeall (module)

Sets a metatable for module with its __index field referring to the global environment, so that this module inherits values from the global environment. To be used as an option to function module.

5.4 - String Manipulation

This library provides generic functions for string manipulation, such as finding and extracting substrings, and pattern matching. When indexing a string in Lua, the first character is at position 1 (not at 0, as in C). Indices are allowed to be negative and are interpreted as indexing backwards, from the end of the string. Thus, the last character is at position -1, and so on.

The string library provides all its functions inside the table string. It also sets a metatable for strings where the __index field points to the string table. Therefore, you can use the string functions in object-oriented style. For instance, string.byte(s, i) can be written as s:byte(i).


string.byte (s [, i [, j]])

Returns the internal numerical codes of the characters s[i], s[i+1], ···, s[j]. The default value for i is 1; the default value for j is i.

Note that numerical codes are not necessarily portable across platforms.


string.char (···)

Receives zero or more integers. Returns a string with length equal to the number of arguments, in which each character has the internal numerical code equal to its corresponding argument.

Note that numerical codes are not necessarily portable across platforms.


string.dump (function)

Returns a string containing a binary representation of the given function, so that a later loadstring on this string returns a copy of the function. function must be a Lua function without upvalues.


string.find (s, pattern [, init [, plain]])

Looks for the first match of pattern in the string s. If it finds a match, then find returns the indices of s where this occurrence starts and ends; otherwise, it returns nil. A third, optional numerical argument init specifies where to start the search; its default value is 1 and may be negative. A value of true as a fourth, optional argument plain turns off the pattern matching facilities, so the function does a plain "find substring" operation, with no characters in pattern being considered "magic". Note that if plain is given, then init must be given as well.

If the pattern has captures, then in a successful match the captured values are also returned, after the two indices.


string.format (formatstring, ···)

Returns a formatted version of its variable number of arguments following the description given in its first argument (which must be a string). The format string follows the same rules as the printf family of standard C functions. The only differences are that the options/modifiers *, l, L, n, p, and h are not supported and that there is an extra option, q. The q option formats a string in a form suitable to be safely read back by the Lua interpreter: the string is written between double quotes, and all double quotes, newlines, embedded zeros, and backslashes in the string are correctly escaped when written. For instance, the call
     string.format('%q', 'a string with "quotes" and \n new line')

will produce the string:

     "a string with \"quotes\" and \
      new line"

The options c, d, E, e, f, g, G, i, o, u, X, and x all expect a number as argument, whereas q and s expect a string.

This function does not accept string values containing embedded zeros.


string.gmatch (s, pattern)

Returns an iterator function that, each time it is called, returns the next captures from pattern over string s.

If pattern specifies no captures, then the whole match is produced in each call.

As an example, the following loop

     s = "hello world from Lua"
     for w in string.gmatch(s, "%a+") do
       print(w)
     end

will iterate over all the words from string s, printing one per line. The next example collects all pairs key=value from the given string into a table:

     t = {}
     s = "from=world, to=Lua"
     for k, v in string.gmatch(s, "(%w+)=(%w+)") do
       t[k] = v
     end


string.gsub (s, pattern, repl [, n])

Returns a copy of s in which all occurrences of the pattern have been replaced by a replacement string specified by repl, which may be a string, a table, or a function. gsub also returns, as its second value, the total number of substitutions made.

If repl is a string, then its value is used for replacement. The character % works as an escape character: any sequence in repl of the form %n, with n between 1 and 9, stands for the value of the n-th captured substring (see below). The sequence %0 stands for the whole match. The sequence %% stands for a single %.

If repl is a table, then the table is queried for every match, using the first capture as the key; if the pattern specifies no captures, then the whole match is used as the key.

If repl is a function, then this function is called every time a match occurs, with all captured substrings passed as arguments, in order; if the pattern specifies no captures, then the whole match is passed as a sole argument.

If the value returned by the table query or by the function call is a string or a number, then it is used as the replacement string; otherwise, if it is false or nil, then there is no replacement (that is, the original match is kept in the string).

The optional last parameter n limits the maximum number of substitutions to occur. For instance, when n is 1 only the first occurrence of pattern is replaced.

Here are some examples:

     x = string.gsub("hello world", "(%w+)", "%1 %1")
     --> x="hello hello world world"
     
     x = string.gsub("hello world", "%w+", "%0 %0", 1)
     --> x="hello hello world"
     
     x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1")
     --> x="world hello Lua from"
     
     x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv)
     --> x="home = /home/roberto, user = roberto"
     
     x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s)
           return loadstring(s)()
         end)
     --> x="4+5 = 9"
     
     local t = {name="lua", version="5.1"}
     x = string.gsub("$name%-$version.tar.gz", "%$(%w+)", t)
     --> x="lua-5.1.tar.gz"


string.len (s)

Receives a string and returns its length. The empty string "" has length 0. Embedded zeros are counted, so "a\000bc\000" has length 5.


string.lower (s)

Receives a string and returns a copy of this string with all uppercase letters changed to lowercase. All other characters are left unchanged. The definition of what an uppercase letter is depends on the current locale.


string.match (s, pattern [, init])

Looks for the first match of pattern in the string s. If it finds one, then match returns the captures from the pattern; otherwise it returns nil. If pattern specifies no captures, then the whole match is returned. A third, optional numerical argument init specifies where to start the search; its default value is 1 and may be negative.


string.rep (s, n)

Returns a string that is the concatenation of n copies of the string s.


string.reverse (s)

Returns a string that is the string s reversed.


string.sub (s, i [, j])

Returns the substring of s that starts at i and continues until j; i and j may be negative. If j is absent, then it is assumed to be equal to -1 (which is the same as the string length). In particular, the call string.sub(s,1,j) returns a prefix of s with length j, and string.sub(s, -i) returns a suffix of s with length i.


string.upper (s)

Receives a string and returns a copy of this string with all lowercase letters changed to uppercase. All other characters are left unchanged. The definition of what a lowercase letter is depends on the current locale.

5.4.1 - Patterns

Character Class:

A character class is used to represent a set of characters. The following combinations are allowed in describing a character class:

For all classes represented by single letters (%a, %c, etc.), the corresponding uppercase letter represents the complement of the class. For instance, %S represents all non-space characters.

The definitions of letter, space, and other character groups depend on the current locale. In particular, the class [a-z] may not be equivalent to %l.

Pattern Item:

A pattern item may be

Pattern:

A pattern is a sequence of pattern items. A '^' at the beginning of a pattern anchors the match at the beginning of the subject string. A '$' at the end of a pattern anchors the match at the end of the subject string. At other positions, '^' and '$' have no special meaning and represent themselves.

Captures:

A pattern may contain sub-patterns enclosed in parentheses; they describe captures. When a match succeeds, the substrings of the subject string that match captures are stored (captured) for future use. Captures are numbered according to their left parentheses. For instance, in the pattern "(a*(.)%w(%s*))", the part of the string matching "a*(.)%w(%s*)" is stored as the first capture (and therefore has number 1); the character matching "." is captured with number 2, and the part matching "%s*" has number 3.

As a special case, the empty capture () captures the current string position (a number). For instance, if we apply the pattern "()aa()" on the string "flaaap", there will be two captures: 3 and 5.

A pattern cannot contain embedded zeros. Use %z instead.

5.5 - Table Manipulation

This library provides generic functions for table manipulation. It provides all its functions inside the table table.

Most functions in the table library assume that the table represents an array or a list. For these functions, when we talk about the "length" of a table we mean the result of the length operator.


table.concat (table [, sep [, i [, j]]])

Given an array where all elements are strings or numbers, returns table[i]..sep..table[i+1] ··· sep..table[j]. The default value for sep is the empty string, the default for i is 1, and the default for j is the length of the table. If i is greater than j, returns the empty string.


table.insert (table, [pos,] value)

Inserts element value at position pos in table, shifting up other elements to open space, if necessary. The default value for pos is n+1, where n is the length of the table (see §2.5.5), so that a call table.insert(t,x) inserts x at the end of table t.


table.maxn (table)

Returns the largest positive numerical index of the given table, or zero if the table has no positive numerical indices. (To do its job this function does a linear traversal of the whole table.)


table.remove (table [, pos])

Removes from table the element at position pos, shifting down other elements to close the space, if necessary. Returns the value of the removed element. The default value for pos is n, where n is the length of the table, so that a call table.remove(t) removes the last element of table t.


table.sort (table [, comp])

Sorts table elements in a given order, in-place, from table[1] to table[n], where n is the length of the table. If comp is given, then it must be a function that receives two table elements, and returns true when the first is less than the second (so that not comp(a[i+1],a[i]) will be true after the sort). If comp is not given, then the standard Lua operator < is used instead.

The sort algorithm is not stable; that is, elements considered equal by the given order may have their relative positions changed by the sort.

5.6 - Mathematical Functions

This library is an interface to the standard C math library. It provides all its functions inside the table math.


math.abs (x)

Returns the absolute value of x.


math.acos (x)

Returns the arc cosine of x (in radians).


math.asin (x)

Returns the arc sine of x (in radians).


math.atan (x)

Returns the arc tangent of x (in radians).


math.atan2 (x, y)

Returns the arc tangent of x/y (in radians), but uses the signs of both parameters to find the quadrant of the result. (It also handles correctly the case of y being zero.)


math.ceil (x)

Returns the smallest integer larger than or equal to x.


math.cos (x)

Returns the cosine of x (assumed to be in radians).


math.cosh (x)

Returns the hyperbolic cosine of x.


math.deg (x)

Returns the angle x (given in radians) in degrees.


math.exp (x)

Returns the the value ex.


math.floor (x)

Returns the largest integer smaller than or equal to x.


math.fmod (x, y)

Returns the remainder of the division of x by y.


math.frexp (x)

Returns m and e such that x = m2e, e is an integer and the absolute value of m is in the range [0.5, 1) (or zero when x is zero).


math.huge

The value HUGE_VAL, a value larger than or equal to any other numerical value.


math.ldexp (m, e)

Returns m2e (e should be an integer).


math.log (x)

Returns the natural logarithm of x.


math.log10 (x)

Returns the base-10 logarithm of x.


math.max (x, ···)

Returns the maximum value among its arguments.


math.min (x, ···)

Returns the minimum value among its arguments.


math.modf (x)

Returns two numbers, the integral part of x and the fractional part of x.


math.pi

The value of pi.


math.pow (x, y)

Returns xy. (You can also use the expression x^y to compute this value.)


math.rad (x)

Returns the angle x (given in degrees) in radians.


math.random ([m [, n]])

This function is an interface to the simple pseudo-random generator function rand provided by ANSI C. (No guarantees can be given for its statistical properties.)

When called without arguments, returns a pseudo-random real number in the range [0,1). When called with a number m, math.random returns a pseudo-random integer in the range [1, m]. When called with two numbers m and n, math.random returns a pseudo-random integer in the range [m, n].


math.randomseed (x)

Sets x as the "seed" for the pseudo-random generator: equal seeds produce equal sequences of numbers.


math.sin (x)

Returns the sine of x (assumed to be in radians).


math.sinh (x)

Returns the hyperbolic sine of x.


math.sqrt (x)

Returns the square root of x. (You can also use the expression x^0.5 to compute this value.)


math.tan (x)

Returns the tangent of x (assumed to be in radians).


math.tanh (x)

Returns the hyperbolic tangent of x.

5.7 - Input and Output Facilities

The I/O library provides two different styles for file manipulation. The first one uses implicit file descriptors; that is, there are operations to set a default input file and a default output file, and all input/output operations are over these default files. The second style uses explicit file descriptors.

When using implicit file descriptors, all operations are supplied by table io. When using explicit file descriptors, the operation io.open returns a file descriptor and then all operations are supplied as methods of the file descriptor.

The table io also provides three predefined file descriptors with their usual meanings from C: io.stdin, io.stdout, and io.stderr.

Unless otherwise stated, all I/O functions return nil on failure (plus an error message as a second result) and some value different from nil on success.


io.close ([file])

Equivalent to file:close(). Without a file, closes the default output file.


io.flush ()

Equivalent to file:flush over the default output file.


io.input ([file])

When called with a file name, it opens the named file (in text mode), and sets its handle as the default input file. When called with a file handle, it simply sets this file handle as the default input file. When called without parameters, it returns the current default input file.

In case of errors this function raises the error, instead of returning an error code.


io.lines ([filename])

Opens the given file name in read mode and returns an iterator function that, each time it is called, returns a new line from the file. Therefore, the construction


     for line in io.lines(filename) do body end

will iterate over all lines of the file. When the iterator function detects the end of file, it returns nil (to finish the loop) and automatically closes the file.

The call io.lines() (with no file name) is equivalent to io.input():lines(); that is, it iterates over the lines of the default input file. In this case it does not close the file when the loop ends.


io.open (filename [, mode])

This function opens a file, in the mode specified in the string mode. It returns a new file handle, or, in case of errors, nil plus an error message.

The mode string can be any of the following:

The mode string may also have a 'b' at the end, which is needed in some systems to open the file in binary mode. This string is exactly what is used in the standard C function fopen.


io.output ([file])

Similar to io.input, but operates over the default output file.


io.popen (prog [, mode])

Starts program prog in a separated process and returns a file handle that you can use to read data from this program (if mode is "r", the default) or to write data to this program (if mode is "w").

This function is system dependent and is not available on all platforms.


io.read (···)

Equivalent to io.input():read.


io.tmpfile ()

Returns a handle for a temporary file. This file is opened in update mode and it is automatically removed when the program ends.


io.type (obj)

Checks whether obj is a valid file handle. Returns the string "file" if obj is an open file handle, "closed file" if obj is a closed file handle, or nil if obj is not a file handle.


io.write (···)

Equivalent to io.output():write.


file:close ()

Closes file. Note that files are automatically closed when their handles are garbage collected, but that takes an unpredictable amount of time to happen.


file:flush ()

Saves any written data to file.


file:lines ()

Returns an iterator function that, each time it is called, returns a new line from the file. Therefore, the construction

     for line in file:lines() do body end

will iterate over all lines of the file. (Unlike io.lines, this function does not close the file when the loop ends.)


file:read (···)

Reads the file file, according to the given formats, which specify what to read. For each format, the function returns a string (or a number) with the characters read, or nil if it cannot read data with the specified format. When called without formats, it uses a default format that reads the entire next line (see below).

The available formats are


file:seek ([whence] [, offset])

Sets and gets the file position, measured from the beginning of the file, to the position given by offset plus a base specified by the string whence, as follows:

In case of success, function seek returns the final file position, measured in bytes from the beginning of the file. If this function fails, it returns nil, plus a string describing the error.

The default value for whence is "cur", and for offset is 0. Therefore, the call file:seek() returns the current file position, without changing it; the call file:seek("set") sets the position to the beginning of the file (and returns 0); and the call file:seek("end") sets the position to the end of the file, and returns its size.


file:setvbuf (mode [, size])

Sets the buffering mode for an output file. There are three available modes:

For the last two cases, sizes specifies the size of the buffer, in bytes. The default is an appropriate size.


file:write (···)

Writes the value of each of its arguments to the file. The arguments must be strings or numbers. To write other values, use tostring or string.format before write.

5.8 - Operating System Facilities

This library is implemented through table os.


os.clock ()

Returns an approximation of the amount in seconds of CPU time used by the program.


os.date ([format [, time]])

Returns a string or a table containing date and time, formatted according to the given string format.

If the time argument is present, this is the time to be formatted (see the os.time function for a description of this value). Otherwise, date formats the current time.

If format starts with '!', then the date is formatted in Coordinated Universal Time. After this optional character, if format is the string "*t", then date returns a table with the following fields: year (four digits), month (1--12), day (1--31), hour (0--23), min (0--59), sec (0--61), wday (weekday, Sunday is 1), yday (day of the year), and isdst (daylight saving flag, a boolean).

If format is not "*t", then date returns the date as a string, formatted according to the same rules as the C function strftime.

When called without arguments, date returns a reasonable date and time representation that depends on the host system and on the current locale (that is, os.date() is equivalent to os.date("%c")).


os.difftime (t2, t1)

Returns the number of seconds from time t1 to time t2. In POSIX, Windows, and some other systems, this value is exactly t2-t1.


os.execute ([command])

This function is equivalent to the C function system. It passes command to be executed by an operating system shell. It returns a status code, which is system-dependent. If command is absent, then it returns nonzero if a shell is available and zero otherwise.


os.exit ([code])

Calls the C function exit, with an optional code, to terminate the host program. The default value for code is the success code.


os.getenv (varname)

Returns the value of the process environment variable varname, or nil if the variable is not defined.


os.remove (filename)

Deletes the file or directory with the given name. Directories must be empty to be removed. If this function fails, it returns nil, plus a string describing the error.


os.rename (oldname, newname)

Renames file or directory named oldname to newname. If this function fails, it returns nil, plus a string describing the error.


os.setlocale (locale [, category])

Sets the current locale of the program. locale is a string specifying a locale; category is an optional string describing which category to change: "all", "collate", "ctype", "monetary", "numeric", or "time"; the default category is "all". The function returns the name of the new locale, or nil if the request cannot be honored.

When called with nil as the first argument, this function only returns the name of the current locale for the given category.


os.time ([table])

Returns the current time when called without arguments, or a time representing the date and time specified by the given table. This table must have fields year, month, and day, and may have fields hour, min, sec, and isdst (for a description of these fields, see the os.date function).

The returned value is a number, whose meaning depends on your system. In POSIX, Windows, and some other systems, this number counts the number of seconds since some given start time (the "epoch"). In other systems, the meaning is not specified, and the number returned by time can be used only as an argument to date and difftime.


os.tmpname ()

Returns a string with a file name that can be used for a temporary file. The file must be explicitly opened before its use and explicitly removed when no longer needed.

5.9 - The Debug Library

This library provides the functionality of the debug interface to Lua programs. You should exert care when using this library. The functions provided here should be used exclusively for debugging and similar tasks, such as profiling. Please resist the temptation to use them as a usual programming tool: they can be very slow. Moreover, several of its functions violate some assumptions about Lua code (e.g., that variables local to a function cannot be accessed from outside or that userdata metatables cannot be changed by Lua code) and therefore can compromise otherwise secure code.

All functions in this library are provided inside the debug table. All functions that operate over a thread have an optional first argument which is the thread to operate over. The default is always the current thread.


debug.debug ()

Enters an interactive mode with the user, running each string that the user enters. Using simple commands and other debug facilities, the user can inspect global and local variables, change their values, evaluate expressions, and so on. A line containing only the word cont finishes this function, so that the caller continues its execution.

Note that commands for debug.debug are not lexically nested within any function, and so have no direct access to local variables.


debug.getfenv (o)

Returns the environment of object o.


debug.gethook ([thread])

Returns the current hook settings of the thread, as three values: the current hook function, the current hook mask, and the current hook count (as set by the debug.sethook function).


debug.getinfo ([thread,] function [, what])

Returns a table with information about a function. You can give the function directly, or you can give a number as the value of function, which means the function running at level function of the call stack of the given thread: level 0 is the current function (getinfo itself); level 1 is the function that called getinfo; and so on. If function is a number larger than the number of active functions, then getinfo returns nil.

The returned table may contain all the fields returned by lua_getinfo, with the string what describing which fields to fill in. The default for what is to get all information available, except the table of valid lines. If present, the option 'f' adds a field named func with the function itself. If present, the option 'L' adds a field named activelines with the table of valid lines.

For instance, the expression debug.getinfo(1,"n").name returns a name of the current function, if a reasonable name can be found, and the expression debug.getinfo(print) returns a table with all available information about the print function.


debug.getlocal ([thread,] level, local)

This function returns the name and the value of the local variable with index local of the function at level level of the stack. (The first parameter or local variable has index 1, and so on, until the last active local variable.) The function returns nil if there is no local variable with the given index, and raises an error when called with a level out of range. (You can call debug.getinfo to check whether the level is valid.)

Variable names starting with '(' (open parentheses) represent internal variables (loop control variables, temporaries, and C function locals).


debug.getmetatable (object)

Returns the metatable of the given object or nil if it does not have a metatable.


debug.getregistry ()

Returns the registry table (see §3.5).


debug.getupvalue (func, up)

This function returns the name and the value of the upvalue with index up of the function func. The function returns nil if there is no upvalue with the given index.


debug.setfenv (object, table)

Sets the environment of the given object to the given table. Returns object.


debug.sethook ([thread,] hook, mask [, count])

Sets the given function as a hook. The string mask and the number count describe when the hook will be called. The string mask may have the following characters, with the given meaning:

With a count different from zero, the hook is called after every count instructions.

When called without arguments, debug.sethook turns off the hook.

When the hook is called, its first parameter is a string describing the event that has triggered its call: "call", "return" (or "tail return"), "line", and "count". For line events, the hook also gets the new line number as its second parameter. Inside a hook, you can call getinfo with level 2 to get more information about the running function (level 0 is the getinfo function, and level 1 is the hook function), unless the event is "tail return". In this case, Lua is only simulating the return, and a call to getinfo will return invalid data.


debug.setlocal ([thread,] level, local, value)

This function assigns the value value to the local variable with index local of the function at level level of the stack. The function returns nil if there is no local variable with the given index, and raises an error when called with a level out of range. (You can call getinfo to check whether the level is valid.) Otherwise, it returns the name of the local variable.


debug.setmetatable (object, table)

Sets the metatable for the given object to the given table (which can be nil).


debug.setupvalue (func, up, value)

This function assigns the value value to the upvalue with index up of the function func. The function returns nil if there is no upvalue with the given index. Otherwise, it returns the name of the upvalue.


debug.traceback ([thread,] [message] [, level])

Returns a string with a traceback of the call stack. An optional message string is appended at the beginning of the traceback. An optional level number tells at which level to start the traceback (default is 1, the function calling traceback).

6 - Lua Stand-alone

Although Lua has been designed as an extension language, to be embedded in a host C program, it is also frequently used as a stand-alone language. An interpreter for Lua as a stand-alone language, called simply lua, is provided with the standard distribution. The stand-alone interpreter includes all standard libraries, including the debug library. Its usage is:

     lua [options] [script [args]]

The options are:

After handling its options, lua runs the given script, passing to it the given args as string arguments. When called without arguments, lua behaves as lua -v -i when the standard input (stdin) is a terminal, and as lua - otherwise.

Before running any argument, the interpreter checks for an environment variable LUA_INIT. If its format is @filename, then lua executes the file. Otherwise, lua executes the string itself.

All options are handled in order, except -i. For instance, an invocation like

     $ lua -e'a=1' -e 'print(a)' script.lua

will first set a to 1, then print the value of a (which is '1'), and finally run the file script.lua with no arguments. (Here $ is the shell prompt. Your prompt may be different.)

Before starting to run the script, lua collects all arguments in the command line in a global table called arg. The script name is stored at index 0, the first argument after the script name goes to index 1, and so on. Any arguments before the script name (that is, the interpreter name plus the options) go to negative indices. For instance, in the call

     $ lua -la b.lua t1 t2

the interpreter first runs the file a.lua, then creates a table

     arg = { [-2] = "lua", [-1] = "-la",
             [0] = "b.lua",
             [1] = "t1", [2] = "t2" }

and finally runs the file b.lua. The script is called with arg[1], arg[2], ··· as arguments; it can also access these arguments with the vararg expression '...'.

In interactive mode, if you write an incomplete statement, the interpreter waits for its completion by issuing a different prompt.

If the global variable _PROMPT contains a string, then its value is used as the prompt. Similarly, if the global variable _PROMPT2 contains a string, its value is used as the secondary prompt (issued during incomplete statements). Therefore, both prompts can be changed directly on the command line. For instance,

     $ lua -e"_PROMPT='myprompt> '" -i

(the outer pair of quotes is for the shell, the inner pair is for Lua), or in any Lua programs by assigning to _PROMPT. Note the use of -i to enter interactive mode; otherwise, the program would just end silently right after the assignment to _PROMPT.

To allow the use of Lua as a script interpreter in Unix systems, the stand-alone interpreter skips the first line of a chunk if it starts with #. Therefore, Lua scripts can be made into executable programs by using chmod +x and the #! form, as in

     #!/usr/local/bin/lua

(Of course, the location of the Lua interpreter may be different in your machine. If lua is in your PATH, then

     #!/usr/bin/env lua

is a more portable solution.)

7 - Incompatibilities with the Previous Version

Here we list the incompatibilities that you may found when moving a program from Lua 5.0 to Lua 5.1. You can avoid most of the incompatibilities compiling Lua with appropriate options (see file luaconf.h). However, all these compatibility options will be removed in the next version of Lua.

7.1 - Changes in the Language

7.2 - Changes in the Libraries

7.3 - Changes in the API

8 - The Complete Syntax of Lua

Here is the complete syntax of Lua in extended BNF. (It does not describe operator precedences.)


	chunk ::= {stat [`;´]} [laststat [`;´]]

	block ::= chunk

	stat ::=  varlist1 `=´ explist1 | 
		 functioncall | 
		 do block end | 
		 while exp do block end | 
		 repeat block until exp | 
		 if exp then block {elseif exp then block} [else block] end | 
		 for Name `=´ exp `,´ exp [`,´ exp] do block end | 
		 for namelist in explist1 do block end | 
		 function funcname funcbody | 
		 local function Name funcbody | 
		 local namelist [`=´ explist1] 

	laststat ::= return [explist1] | break

	funcname ::= Name {`.´ Name} [`:´ Name]

	varlist1 ::= var {`,´ var}

	var ::=  Name | prefixexp `[´ exp `]´ | prefixexp `.´ Name 

	namelist ::= Name {`,´ Name}

	explist1 ::= {exp `,´} exp

	exp ::=  nil | false | true | Number | String | `...´ | function | 
		 prefixexp | tableconstructor | exp binop exp | unop exp 

	prefixexp ::= var | functioncall | `(´ exp `)´

	functioncall ::=  prefixexp args | prefixexp `:´ Name args 

	args ::=  `(´ [explist1] `)´ | tableconstructor | String 

	function ::= function funcbody

	funcbody ::= `(´ [parlist1] `)´ block end

	parlist1 ::= namelist [`,´ `...´] | `...´

	tableconstructor ::= `{´ [fieldlist] `}´

	fieldlist ::= field {fieldsep field} [fieldsep]

	field ::= `[´ exp `]´ `=´ exp | Name `=´ exp | exp

	fieldsep ::= `,´ | `;´

	binop ::= `+´ | `-´ | `*´ | `/´ | `^´ | `%´ | `..´ | 
		 `<´ | `<=´ | `>´ | `>=´ | `==´ | `~=´ | 
		 and | or

	unop ::= `-´ | not | `#´


Last update: Tue Oct 3 21:27:28 BRT 2006
译文最后更新:修改几处别字,2009年4月7日

checkip | getIP