编辑“Help:Lua”

{{mbox|text=本页的部分内容，部分来自[[mw:Extension:Scribunto/Lua_reference_manual/zh|参考手册的中文翻译]]。}}
{{NoteTA|G1=IT|G2=MediaWiki}}

'''Lua'''是轻量的动态类型语言。MediaWiki的[[mw:Special:MyLanguage/Extension:Scribunto|Scribunto]]扩展允许页面调用Lua代码，其中Lua代码放置在“Module:”命名空间下。MediaWiki使用的Lua版本为5.1，但进行了一些修改，并移植了之后的版本的一些功能。

本帮助页面将简单地介绍Lua的语法、用法及特点等，但不会特别细致，建议有一定编程基础的用户阅读。请注意，本页提及了一些MediaWiki及其扩展提供的库，这些在MediaWiki之外的标准运行环境中是不直接具备的。本页还会提及本wiki中的（包括搬运的）部分模块，不一定适用于其他基于MediaWiki的网站。零基础的用户如需学习Lua语言，可在网上自行搜索入门教程。

== 变量 ==
Lua的'''变量'''分为'''全局变量'''和'''局部变量'''。局部变量应使用local关键字进行声明。同其他语言一样，我们使用等号进行赋值。在没有声明局部变量的情况下进行赋值，则默认赋值给全局变量。例如，

<syntaxhighlight lang=lua>
a = 1 -- 声明一个全局变量
do -- 一个作用域
    local b = 1 -- 声明一个局部变量
    b = "2" -- 修改一个局部变量
end
print(b) -- 局部变量超出作用域会失效，所以为nil
</syntaxhighlight>

注意：
# 上面这个例子中，只是标准的开发环境，因此使用了全局变量，并使用print函数以将值输出到控制台。MediaWiki不同于标准的开发环境，不应当修改全局变量，也不应该使用print函数。
# 在MediaWiki的模块中，'''不应该创建或修改任何全局变量，而应该定义局部变量，并在模块末尾使用return语句返回你需要返回的值。'''

局部变量也可以先声明再赋值。没有赋值的变量，以及不存在的变量，其值都为nil，使用这些变量并不会抛出错误，但仍需留意。

变量可以多重赋值，例如{{code|code=a, b = 1, 2|lang=lua}}是有效的，但不支持{{code|code=a = b = 1|lang=lua}}这样的语法。等号右边也可以是返回多个值的函数（如unpack或string.find）。如果等号右边的值的个数超过左边，则多余的会被忽略；如果少于左边的，则缺少的会赋值为nil。注意Lua没有元组（tuple）。

变量名称不能以数字开头，不能为保留字，也不可以有中文。

== 数据类型 ==
Lua是动态类型语言，变量没有类型，只有值有。声明局部变量、函数参数等，均无需声明类型。

=== 基本类型介绍 ===
在Scribunto扩展中，Lua只有6个基本的类型：

==== nil ====
'''空值（nil）'''表示这个值不存在。尝试访问不存在的变量或表中不存在的字段的值时，会得到nil。函数调用中未提供的参数的值都会被视为nil。很多函数也会在失败时返回nil而不是抛出错误，例如tonumber函数在无法转换成数字时会返回nil。

==== boolean ====
'''布尔值（boolean）'''只有true或false。将其他数据类型转化为布尔值时，只有false和nil视为false，其他的一律视为true。

==== string====
'''字符串（string）'''为一系列的8比特字节；这取决于应用程序以哪种特定的编码来解析。字符串使用单引号或双引号表示，单引号和双引号无区别，也不会区分“字符”与“字符串”。字符串可以转义。

字符串也可以使用长括号来定义。长括号之间可以夹杂着0个或更多个等号（两边的等号要等量）。例如，{{code|"abc"|lang=lua}}、{{code|'abc'|lang=lua}}、{{code|[[abc]]|lang=lua}}、{{code|code=[==[abc]==]|lang=lua}}都是等价的。注意：由长括号定义的字符串'''可以直接换行，且不会处理转义序列'''。

Lua标准库中的[[Help:Lua/string|string库]]可用于处理字符串，MediaWiki库中的[[Help:Lua/mw.text|mw.text]]和[[Help:Lua/mw.ustring|mw.ustring]]则提供了更多的处理方法。

==== number  ====
Lua中的'''数字（number）'''均为双精度浮点数，-9007199254740992到9007199254740992之间的整数都会准确表达，更大的数和带有小数部分的数将会受到舍入的误差。

数字可以用点（.）来表示小数，例如123456.78。数字也可以用不带空格的科学计数法，例如1.23e-10、123.45e20或者1.23E5。也可以用16进制表示整数，方法就是以0x开头，例如0x3A。 

1/0会得到inf，0/0会得到nan。inf和nan都可以正确地储存，但是并无直接的文字表示方法（无穷大可以使用<code>math.huge</code>表示）。使用时，应当留意inf和nan可能带来的潜在错误。nan不等于它自己，也就是说，'''<code>nan == nan</code>会返回false'''。

Lua标准库中的[[Help:Lua/math|math库]]可用于处理数字。

==== table ====
'''表（table）'''是复合数据类型，是Lua中最复杂的一种数据类型，很像JavaScript中的对象（object）或者Python中的字典（dict）。在Lua中，表同时充当了映射、列表、集合的功能。

表由多个（或者零个）字段组成，每个字段都有'''键（key）'''和'''值（value）'''，其中键可以是除nil或nan外的任何值。不存在的字段可视为其值为nil。键是唯一的，值不是唯一的。若键为表或函数，则判断其唯一性是根据其是否为同一个对象。

声明一个表的方法是：在一组花括号中，使用“[键] = 值”的方式表示一个字段，多个字段使用逗号或分号隔开。如果键是字符串的字面量，且该字符串符合变量名称要求，则可以省略引号并使用“键 = 值”的方式表示。例如，{{code|code={a = 1, b = "2"}|lang=lua}}中，{{code|"a"|lang=lua}}和{{code|"b"|lang=lua}}都是键，{{code|1|lang=lua}}和{{code|"2"|lang=lua}}是对应的值，也可以表示为{{code|code={["a"] = 1, ["b"] = 2}|lang=lua}}。

声明一个表时，键是可以省略的。例如，{{code|{"a", "b", "c", "d", "e"}|lang=lua}}等价于{{code|code={[1]="a", [2]="b",[3]="c", [4]="d", [5]="e"}|lang=lua}}，这样的表称为'''数组（array）'''或'''序列（sequence）'''，其特点就是键是连续不间断的正整数。空表也可以视为数组

对于表t和数字b，如果满足{{code|code=(t == 0 or t[b] ~= nil) and t[b + 1] == nil|lang=lua}}，则称b为表t的一个'''边界（border）'''。数组只有一个边界。有多个边界的表不是严格的数组，称为'''稀疏数组（sparse array）'''，对其进行取长运算会返回其中一个边界，存在不确定性。例如，{{code|code={nil, 2, 3, nil, nil, 6} }}是个稀疏数组，其边界为0、3、6，因此其长度可能是0、3、6中的某一个值。

表也可以用作'''集合（set）'''，如{{code|code={a = true, b = true, c = true}|lang=lua}}，因为键是不能重复的，所以可以通过判断键对应的值是否存在来判断集合是否包含某个元素。

'''表的字段访问：'''可以通过“<code>-{}-变量名称[键]</code>”或“<code>-{}-变量名称.键</code>”（该方法的键必须是可作标识符的字符串）的方式来访问表中的键对应的值，也就是说，找到一个键为指定的值（表、函数等需要是同一对象，字符串、数字等只需要值相等即可）的字段，并返回其值。例如，如果t是一个表，则{{code|code=t[true]|lang=lua}}表示布尔值键true对应的值，{{code|code=t.abc|lang=lua}}或{{code|code=t["abc"]|lang=lua}}表示字符串键{{code|"abc"|lang=lua}}对应的值。如果这个值不存在，返回nil。

'''表的字段赋值：'''可以通过赋值语句修改表中的键对应的值。可以给表添加字段、修改现有字段的值或者清除一个字段。例如，{{code|code=t[true] = "q"|lang=lua}}表示将键true对应的值修改为字符串"q"，{{code|code=t["abc"] = nil|lang=lua}}或{{code|code=t.abc = nil|lang=lua}}（该方法的键必须是可作标识符的字符串）表示将键{{code|"abc"|lang=lua}}对应的值修改为nil（相当于删除这个字段，如果其原来的值不是nil的话）。注意：键可以是除nil或nan外的任意值，可以是函数、表，甚至是表自身，也就是说{{code|code=t[print] = 1|lang=lua}}、{{code|code=t[t] = t|lang=lua}}这样的用法都是有效的，而{{code|code=t[0/0] = 1|lang=lua}}则是无效的（0/0相当于nan，参考[[#number]]）。

表不会自动复制。例如如果t是一个表，则赋值语句{{code|code=s = t|lang=lua}}'''不会将t的内容复制到新的表s中，而是会让变量s和t的指针都指向同一个内存空间，它们仍是同一个对象'''，对表s的修改和对t的修改是同步、等价的。

Lua中，判断两个表是否相等的标准是两个表是否'''是同一个对象'''，而不是内容是否一致。例如，在上面这一段的例子中，{{code|code=s == t|lang=lua}}就会返回true，而{{code|code={} == {}|lang=lua}}会返回false。一般来说，每对花括号都意味着创建了一个新的对象。

Lua标准库中的[[Help:Lua/table|table库]]可用于处理表，其中大部分函数都是用于处理数组（表中的数组部分）的。此外，本wiki也搬运了元模块[[Module:TableTools|TableTools]]，可用于对表进行一些高级的处理。

此外，表的索引、赋值、判断相等等操作都可以受到[[#元表]]影响。

==== function ====
Lua中的'''函数（function）'''是'''闭包'''，这意味着它们维护对它们声明的作用域的引用，并可以访问和操作该作用域中的变量。

定义一个函数的基本语法是：
<syntaxhighlight lang=lua>
function 函数名称(参数列表)
    语句……
end
</syntaxhighlight>

函数名称可以是表的字段，例如t.abc。或者，你也可在function前面加上{{code|local|lang=lua}}关键字，表示该函数是个局部变量。参数是可选的，且视为局部变量。定义函数时，可以使用{{code|...|lang=lua}}表示不定数量的参数（参见[[Help:Lua/基本#select|select]]）。

函数内可以使用return语句，表示函数返回一个值，return语句后面应当紧跟代码块的结束。如果没有执行return语句，函数不会返回值，可以认为返回了nil。

匿名函数的表示方法为：
<syntaxhighlight lang=lua>
function (参数列表)
    语句……
end
</syntaxhighlight>

匿名函数与普通的函数无区别，例如，下面两个语句的效果是一样的：
* {{code|code=local function f(x) return x+1 end|lang=lua}}
* {{code|code=local f = function (x) return x+1 end|lang=lua}}

注意：通过匿名函数赋值的方式定义的函数，如果需要在函数内调用函数自身，应当先声明再赋值。例如：
* 正确：{{code|code=local function f(x) return x < 5 and f(x + 1) or x end|lang=lua}}
* 错误：{{code|code=local f = function (x) return x < 5 and f(x + 1) or x end|lang=lua}}（这里的f(x+1)中的f视为全局变量）
* 正确：{{code|code=local f; f = function (x) return x < 5 and f(x + 1) or x end|lang=lua}}

事实上，在Lua中，{{code|local function f(...)|lang=lua}}是一个语法糖，在字节码中，实际上是先声明局部变量再赋值的。

调用函数的语法为：
<syntaxhighlight lang=lua>
函数名称(参数列表)
</syntaxhighlight>

函数的调用可以单独作为语句，也可以作为表达式。此外，如果调用函数时（无论作为语句还是表达式），只有一个参数，且该参数为字符串或表的字面量，则括号可以省略，例如：

* {{code|print "abc"|lang=lua}}等价于{{code|print("abc")|lang=lua}}。
* {{code|print{1, 2, 3}|lang=lua}}等价于{{code|print({1, 2, 3})|lang=lua}}。

Lua的函数不支持方法重载或多重派发，也不能够直接给参数设置默认值。调用函数时，缺失的参数视为nil<ref>如果函数有不定数量的参数，则这些参数的数量是准确的；此外一些Lua内置函数也不会补充参数，例如{{code|tostring()|lang=lua}}会抛出错误，而不是理解为{{code|tostring(nil)|lang=lua}}。</ref>，多余的参数会被忽略。一种常见的间接设置默认值的方式是，检查某个参数的值是否存在，如果为nil则赋值为默认值，例如：
<syntaxhighlight lang=lua>
function f(name)
  name = name or 'default'
  ...
end
</syntaxhighlight>

===== 方法 =====
函数作为表的字段时可以作为'''方法（method）'''调用，会自动将表自身作为第一个参数。方法是'''面向对象'''的一种体现。

Lua并没有严格意义上的方法，但Lua提供了下面两种语法糖：
* 声明方法：{{code|function table:method(args)|lang=lua}}等价于{{code|function table.method(self, args)|lang=lua}}；
* 调用方法：{{code|table:method("foo")|lang=lua}}等价于{{code|table.method(table, "foo")|lang=lua}}。

此外，字符串也可以面向对象使用（参见[[#元表]]）。

=== 类型转换 ===
Lua的数据类型可以相互转换。

[[Help:Lua/基本#tonumber|tonumber]]函数可以将字符串转化为数字，例如{{code|tonumber("123")|lang=lua}}会返回123。不能转化为数字的，则会转化为nil。对字符串进行算数运算时会尝试自动转换成数字。

[[Help:Lua/基本#tostring|tostring]]函数可以将任意值转化为字符串。表会转化为{{code|"table"|lang=lua}}（受[[#元表]]影响的除外），函数会转化为{{code|"function"|lang=lua}}。数字与字符串连接、数字之间连接时会自动转换成字符串。

[[Help:Lua/基本#type|type]]函数可以返回值的数据类型，用字符串表示。例如{{code|type(1/0)|lang=lua}}会返回{{code|"string"|lang=lua}}，{{code|type(true)|lang=lua}}会返回{{code|"boolean"|lang=lua}}。

== 运算 ==
和大多数语言一样，Lua支持'''算术运算'''。其中，除以零不会出错，会得到inf或nan。模运算的定义为{{code|code=a % b == a - math.floor( a / b ) * b|lang=lua}}，例如-4%3会返回2而非-1。幂运算的符号为<code>^</code>。对字符串进行算数运算，会尝试使用tonumber函数转化为数字，如无法转换则会抛出错误。

'''关系运算'''包括<code>==</code>、<code>~=</code>、<code><</code>、<code>></code>、<code><=</code>和<code>>=</code>，运算结果一定是布尔值。对于<code>==</code>，不同类型的数据比较为false。注意表或函数的比较会比较指针，当两个值指向同一个表或函数时才会返回true，除非受元表影响。

'''逻辑运算'''包括<code>and</code>、<code>or</code>和<code>not</code>。注意：逻辑运算的结果不一定是布尔值，且进行逻辑运算时，并不会提前把所有值算出来，例如{{code|3 or error()}}的值为3，不会抛出错误。可以使用逻辑运算来组成'''“三元运算”'''，例如{{code|code=a and b or c|lang=lua}}相当于JavaScript、Julia或Java中的{{code|code=a ? b : c|lang=java}}或Python中的{{code|code=b if a else c|lang=python}}，前提是b不能为false。

对两个字符串进行'''连接运算'''的方式是{{code|a .. b|lang=lua}}，而非{{code|a + b|lang=java}}或{{code|a * b|lang=julia}}。可以对数字进行连接，连接时会尝试转化为字符串。注意：Lua的字符串是不可变的（immutable），而且Lua不提供任何类型的“字符串构造器（string builder）”，所以反复进行{{code|code=a = a .. b|lang=lua}}会多次创建新的字符串，并最终将旧字符串作为垃圾收集。如果许多字符串都需要连接，则应使用[[Help:Lua/string#format|string.format]]，或将所有的字符串添加到一个数组然后最后使用table.concat()连接。 

{{code|#a|lang=lua}}可以获取字符串或者数组a的'''长度'''。对于字符串，会获取其字节数，类似于string.len，获取字符数可以使用函数[[Help:Lua/mw.ustring#len|mw.ustring.len]]。对于表，只会获取其数组部分的长度，其他部分的字段一律忽略（对于{{code|{1, 2, nil, 4}|lang=lua}}这样的稀疏数组，其长度是其边界中的某一个，例如可能为2或4<ref>需要留意这种情况，因为会导致一些不确定性。</ref>），如需获取表中所有字段的个数，应使用一次for循环，或导入[[模块:TableTools]]并使用其中的size函数。

对于表，上述所有运算都可以通过[[#元表]]控制。

=== 优先级 ===
Lua中，各运算的优先级如下：
# <code>^</code>
# <code>not</code> <code>#</code> <code>-</code>（负号）
# <code>*</code> <code>/</code> <code>%</code>
# <code>+</code> <code>-</code>（减号）
# <code>..</code>
# <code><</code> <code>></code> <code><=</code> <code>>=</code> <code>~=</code> <code>==</code>
# <code>and</code>
# <code>or</code>
此外，对于同级运算，<code>a/b/c</code>相当于<code>(a/b)/c</code>，<code>a^b^c</code>相当于<code>a^(b^c)</code>。

== 流程控制 ==
Lua和大多数语言一样，具有条件语句和循环语句，没有switch——case语句。

=== 条件语句 ===
条件语句的基本语法是：
<syntaxhighlight lang=lua>
if 条件1 then
    语句块1
elseif 条件2 then
    语句块2
else
    语句块3
end
</syntaxhighlight>
当条件1成立时，执行语句块1，否则当条件2成立时，执行语句块2，否则执行语句块3。elseif和else的结构都是可选的，当然elseif可以有多个。

=== 循环语句 ===
while循环的基本语法：
<syntaxhighlight lang=lua>
while 条件 do
    语句块
end
</syntaxhighlight>

repeat循环的基本语法：
<syntaxhighlight lang=lua>
repeat
    语句块
until 条件
</syntaxhighlight>

在repeat循环中，语句块至少执行一次。条件可以使用语句块中的局部变量。

for循环的基本语法：
<syntaxhighlight lang=lua>
for 名称 = 表达式1, 表达式2, 表达式3 do
    语句块
end
</syntaxhighlight>

这种循环会声明一个局部变量，由“表达式1”的值开始，以“表达式3”的值为步长，循环到“表达式2”的值。表达式3可以省略，默认为1，但不能为false或nil。

for语句除了用来循环之外，还可以进行迭代。语法为：
<syntaxhighlight lang=lua>
for 变量 in 表达式 do
    语句块
end
</syntaxhighlight>

变量、表达式可以有多个。通常表达式是返回3个值的一个函数调用。如果迭代器函数可以被写入，那么只取决于传入的参数，这会更加有效。否则，在Lua中编程建议返回闭包比返回表更好，因为静态变量在每次迭代更新其成员。

在上述for、repeat和两种for循环中，均可使用{{code|break|lang=lua}}关键字来立即跳出循环，break后面内容不再执行。Lua没有continue语句<ref>Lua 5.2以上的版本具有标签功能，可达到类似于continue的效果，但MediaWiki使用的Lua 5.1，是不支持标签的。</ref>，但可以调用包含循环代码块的函数，用{{code|return|lang=lua}}来代替。

常用的迭代函数有[[Help:Lua/基本#pairs|pairs]]、[[Help:Lua/基本#ipairs|ipairs]]、[[Help:Lua/string#gmatch|string.gmatch]]、[[Help:Lua/mw.text#gsplit|mw.text.gsplit]]等。例如，对于一个普通的表t，我们可以使用这样的方式迭代其所有的键和值：

<syntaxhighlight lang=lua>
for k,v in pairs(t) do
    含有k和v的语句块
end
</syntaxhighlight>

== 元表 ==
每个表都可以设置一个'''元表（metatable）'''，用来修改特定的行为。{{code|setmetatable(t, m)|lang=lua}}可以用来将表t的元表设为m（m也可以为nil，表示取消元表设置）<ref name="setmetatable">原版Lua中，debug.setmetatable函数可以强制设置一个值（不限于表）的元表，且不受__metatable元方法影响。MediaWiki删除了此函数。</ref>，该函数自身也会返回修改后的表；{{code|getmetatable(t)|lang=lua}}可以用来获取表t的元表。

如果元表具有'''__index字段'''，则当通过指定的键访问表的字段的时候，如果该字段不存在，则会使用元表__index字段。如果__index是表，则会访问这个表的字段。如果__index是函数，则会调用这个函数。例如，访问{{code|t[k]|lang=lua}}时，如果表本身的这个字段不存在，则会尝试访问{{code|__index[k]|lang=lua}}（如果__index是表）或{{code|__index(t, k)|lang=lua}}（如果__index是函数）。rawget函数可绕过这个元方法。

'''__newindex字段'''则用于修改给表的字段赋值的行为。赋值给表的一个不存在的键时，如果__newindex字段的值是表，则会在该表中重复赋值。如果__newindex的值是函数，则会调用这个函数。例如，执行{{code|code=t[k] = v|lang=lua}}时，表本身不存在这个字段，则会执行{{code|code=__newindex[k] = v|lang=lua}}（如果__newindex是表）或{{code|code=__newindex(t, k, v)|lang=lua}}（如果__newindex是函数）。rawset函数可绕过这个元方法。

'''__call字段'''可以让表能像函数那样调用，值必须是函数。如果这个元表字段存在，则调用表{{code|t(...)|lang=lua}}时，会像{{code|__call(t, ...)|lang=lua}}这样调用，而不是抛出无法调用表的错误。

'''__metatable字段'''用于保护元表，防止其被访问或修改。如果该字段存在，当对表进行getmetatable时，不会返回真正的元表，而是返回该字段的值<ref name="getmetatable">原版Lua的debug.getmetatable函数可以强制获取任意值的元表，不受__metatable元方法影响。MediaWiki删除了此函数。</ref>，如果进行setmetatable，则会抛出错误<ref name="setmetatable" />。

'''__mode字段'''用于使表保持弱引用。在Lua中，变量和表的字段对对象（函数、表等）的引用是强引用，只要某个函数和表依然存在引用，例如存储在某个全局变量或者没有超出作用域的局部变量中，或作为键或者值存储在未被清理掉的表中，那么它就不会被垃圾收集机制清理掉，而是一直存储在内存中。弱引用则表示其引用不会阻止该表中存储的内容被清理。当<code>__mode</code>的值为<code>k</code>表示键保持弱引用，<code>v</code>表示值为弱引用，<code>kv</code>表示键和值均为弱引用。例如：
<syntaxhighlight lang=lua>
t = setmetatable({value = {1, 2, 3}}, {__mode = 'v'})
print(t.value)
collectgarbage()
print(t.value)
</syntaxhighlight>
输出的结果为：
<pre>
table
nil
</pre>

元表的一些其他字段用法如下，其值一般都是函数，函数的第一个参数是表自身。例如，如果元表<code>__add</code>字段存在，则对表t计算t + a时，则会调用{{code|__add(t, a)|lang=lua}}，而不是抛出无法对表进行算术运算的错误。

{| class=wikitable style="margin:auto"
! 字段名称和用法 !! 对应操作 
|-
| __add(self, v) || self + v
|-
| __sub(self, v) || self - v
|-
| __mul(self, v) || self * v
|-
| __div(self, v) || self / v
|-
| __mod(self, v) || self % v
|-
| __pow(self, v) || self ^ v
|-
| __unm(self)    || -self
|-
| __concat(self, v) || self .. v
|-
| __len(self) || #self
|-
| __eq(self, v) || self == v
|-
| __lt(self, v) || self < v
|-
| __le(self, v) || self <= v
|-
| __pairs(self)<ref name="pairs">原版Lua 5.1没有__pairs和__ipairs的功能（是在后面的版本才加入的），不过Scribunto扩展在Lua中移植了该功能，因此你可以在MediaWiki中使用此元表。</ref> || pairs(self)
|-
| __ipairs(self)<ref name="pairs" /> || ipairs(self)
|-
| __tostring(self) || tostring(self)
|}

所有字符串共用同一个元表，该元表的__index字段等同于[[Help:Lua/string|string库]]的一个副本，以使得字符串能够作为对象使用。比如，{{code|string.match("label123", "^label%d")|lang=lua}}等价于{{code|("label123"):match("^label%d")|lang=lua}}。注意这个元表无法通过[[Help:Lua/基本#getmetatable|getmetatable]]函数获得<ref>原版Lua可以获取任意值的元表，只要元表存在。</ref>。

== 注释 ==
<references/>

{{帮助页面}}
[[Category:Lua参考手册]]