6.1 - 基础库

基础库提供了Lua中的核心函数。如果你不想让程序中包含这个库，你应当仔细确认你是否需要自己提供这些工具的实现。

assert (v [, message])

当表达式 v 的值为假（即为nil或false）时抛出异常；否则返回其所有的参数。在发生错误时， 参数 message 会作为错误对象；如果该参数缺失，则使用默认值 "assertion failed!" 。

collectgarbage ([opt [, arg]])

此函数是GC的通用接口。其根据第一个参数 opt 来执行不同的方法：

• "collect"： 默认选项，执行一轮完整GC。
• "stop"： 停止GC的自动运行。收集器将只在显式触发时运行，直到调用 restart 。
• "restart"： 重启GC的自动执行。
• "count"： 返回Lua中正在使用的所有内存的大小（KB）。该值有小数部分，因此可以乘以1024得出Lua所使用内存的确切字节数。
• "step"： 单步运行GC。步长由 arg 参数控制。步长为零时，收集器将执行一步基础（不可分割）行为。步长不为零时，收集器将在Lua分配到了步长大小（KB）的内存后工作。如果这一步完成了一轮GC会返回true。
• "isrunning"： 返回一个布尔值以表示收集器是否正在运行（即没有被停止）。
• "incremental"： 将GC改为步进模式。该选项可以跟三个数值参数：GC停步（garbage-collector pause），GC步进乘数（garbage-collector step multiplier），以及GC步数（garbage-collector step size）（参见2.5.1），传零则表示不更改对应的设置值。
• "generational"： 将GC改为代际模式。该选项可以跟两个数值参数：次代乘数（minor multiplier）以及主乘数（major multiplier）（参见2.5.2），传零则表示不更改对应的设置值。

更多关于GC和以上选项的细节请参见2.5。

此函数不应当在终结器中调用。

dofile ([filename])

打开指定的文件并将其内容作为Lua代码块执行。不带参数调用时，dofile 会执行从标准输入获取的内容。会将代码块中所有的返回值原样返回。遇到错误时，dofile 会将错误传播给调用者（即 dofile 没有在保护模式下运行）。

error (message [, level])

抛出一个错误（参见2.3），错误对象为参数 message 。此函数永不返回。

通常，如果 message 是字符串的话，error 会在此之前添加一些关于错误位置的信息。参数 level 指定了如何获取错误的位置。当 level 为1（默认值），错误位置就是调用 error 函数的地方；当level 为2指的是调用 error 函数的地方的上层调用者；以此类推。当 level 为0时将不会添加错误位置的信息。

_G

持有全局环境（参见2.2）的一个全局变量。Lua自身并不使用它，改变这个变量的值并不会影响任何环境，反之亦然。

getmetatable (object)

如果 object 没有元表，则返回nil。或者如果 object 的元表中有 __metatable 字段，则返回这个字段相应的值。否则返回给出的 object 的元表。

ipairs (t)

返回三个值（迭代函数、表 t 、以及 0），因此这样的形式：

for i,v in ipairs(t) do body end

将会按序遍历 t 表中的键值对(1,t[1])，(2,t[2])，...，直到遇到缺失的索引。

load (chunk [, chunkname [, mode [, env]]])

加载代码块。

如果参数 chunk 是一个字符串，那么该字符串直接作为代码块加载。如果是一个函数，load 会反复调用该函数以获得代码块，其每次调用都必须返回紧跟在上一次结果后的字符串，返回空字符串或nil或无返回则表示代码块结束。

如果没有发生语法错误，load 会将代码块作为一个函数返回；否则返回fail加上其错误消息。

当你加载主代码块时，其返回的函数将额外带有一个上值—— _ENV 变量（参见2.2）。然而，当你加载一个由某个函数创建而来的二进制块时（参见string.dump），最后的结果函数可能要带上一些其原本的上值，而且其中的第一个上值不一定是 _ENV 变量。（一个非主函数的上值中甚至可能没有 _ENV 。）

但无论如何，如果最后的函数包含上值，那么第一个上值将被设为给出参数 env 的值，如果该参数缺省则使用全局环境的值。其他的上值则使用nil初始化。这里所有的上值都是崭新的，即它们不会和其他函数共享。

chunkname 作为代码块的名称以供错误或调试信息使用（参见4.7）。该参数缺省的情况下，chunk 为字符串时，则同该字符串，否则为 "=(load)" 。

字符串参数 mode 表示代码块是文本还是二进制数据（即预编译的代码块）。其可以是字符串 "b"（表示只可能是二进制块），或者字符串 "t"（表示只可能是文本），或是字符串 "bt"（二者皆可）。其默认值为 "bt" 。

加载不合规的二进制块并不危险；因为 load 会发出适当的错误。然而，Lua并不会检查二进制块中的代码一致性，因此运行恶意制作的字节码可能会导致解释器崩溃。

loadfile ([filename [, mode [, env]]])

和load类似，但是会从 filename 文件中获取代码块，如果没有给出文件名的话则会从标准输入中获取。

next (table [, index])

允许代码中遍历表的所有字段。第一个参数是一个表，第二个参数为表中的一个索引。调用 next 会返回表中下一个索引以及对应的值。当第二个参数为nil时，next 会返回起始索引和其对应的值。当第二个参数为表中最后的索引，或者是一个空表中的nil索引是，next 会返回nil。如果第二个参数缺省，则其会被当作nil处理。因此，你可以使用 next(t) 来检查是否为空表。

其中并没有对于每个索引的顺序做定义，即使是数字索引。（如果需要按照数值顺序遍历表，那么请使用数字形式的for语句。）

你不应当在遍历过程中给表中分配原本没有的字段，然而可以修改已存在的字段，甚至你可以将已存在的字段设为nil。

pairs (t)

如果 t 拥有元函数 __pairs ，则将 t 作为参数调用该元方法并返回调用结果的前三个。

否则，返回三个值：next函数、表 t 、以及nil，所以这样的代码：

for k,v in pairs(t) do body end

会遍历表 t 中的所有键值对。

关于遍历过程中对表的修改行为请参考next函数。

pcall (f [, arg1, ···])

在保护模式下使用给出的参数列表来调用函数 f 。意思是 f 中的任何错误都不会传播开；而是会由 pcall 捕获错误并返回状态码。其第一个返回值是一个状态码（布尔类型），没有错误则为true。这种情况下，pcall 会将所有的调用结果也放在第一个返回值后一并返回。在发生错误的情况下，pcall 会返回false加上错误对象。注意捕获的错误不会触发错误处理。

print (···)

接收任意数量的参数并将其输出到标准输出 stdout 中，其中会将每个参数转换为字符串，转换规则同tostring。

print 函数不适用于格式化输出，而是一个展示值的快捷方法，例如在调试的时候使用。如需完全控制输出的内容，请使用string.format和io.write。

rawequal (v1, v2)

检查 v1 和 v2 是否相等，并不会触发元函数 __eq 。返回值为布尔类型。

rawget (table, index)

直接获取 table[index] 的值，并不会触发元值 __index 。参数 table 必须是一个表；参数 index 可以是任何值。

rawlen (v)

返回对象 v 的长度，其必须是个表或者字符串，并不会触发元函数 __len 。返回值为一个整数。

rawset (table, index, value)

直接将 table[index] 设为 value ，不会使用元值 __newindex。参数 table 必须是一个表，参数 index 可以是除nil和 NaN 的任何值，参数 value 可以是任意Lua值。

此函数会将 table 返回

select (index, ···)

如果 index 是一个 number （或者可以转换为一个 number），那么返回后边参数列表第 index 个之后的所有参数；值为负数时则从后边开始数起（-1就是最后一个参数）。否则 index 必须为字符串 "#"，此时 select 会返回后边的参数列表中的参数数量。

setmetatable (table, metatable)

给一个表设置元表。如果 metatable 为nil，则删除表上的元表。如果原本的元表中含有 __metatable 字符，则抛出错误。

此函数会将传进来的 table 返回。

如需改变其他类型的元表，你必须使用调试库（参见6.10）。

tonumber (e [, base])

如果参数 base 缺省，tonumber 会尝试将参数 e 转换为一个 number 。其如果已经是一个 number 或者是一个可以转换为 number 的字符串，那么 tonumber 就将这个 number 值返回；否则返回fail。

字符串可以转换为整数或浮点数，由Lua的词法转换规则决定（参见3.1）。字符串的开头和结尾可以含有空格或单个符号。

当 base 不缺省时，那么 e 必须是一个可以转换为对应基数下整数的字符串。参数 base 可以是包括2到36之间的任意整数值。对于10以上的基数，字母 'A'（小写也可以）表示10，'B'表示11，以此类推，一直到 'Z' 表示35。如果字符串 e 不是一个有效的对应基数的数字，那么则返回fail。

tostring (v)

接收一个任意类型的值并将其转换为人类可读的格式的字符串。

如果 v 的元表中含有 __tostring 字段，那么 tostring 会将 v 作为参数调用对应的值，然后将调用结果返回。如果 v 的元表中含有 __name 字段，并且其值是一个字符串，那么 tostring 可能会将其作为最后的结果。

如需完全控制如何转换数字，可以使用string.format。

type (v)

只返回第一个参数的类型所对应的字符串。此函数的结果可能为 "nil"（是字符串，不是nil值）、"number"、"string"、"boolean"、"table"、"function"、"thread"、或者 "userdata" 。

_VERSION

一个包含了Lua版本的全局字符串变量。当前版本中此变量的值为 "Lua 5.4" 。

warn (msg1, ···)

发出一个警告，警告消息由传进来的参数连接而成（这些参数应该用字符串）。

根据约定，一块由 '@' 开头的警告信息为控制消息 control message ，是给警告系统本身的消息。特别是Lua中的标准警告函数可以识别的控制信息 "@off" ，其会停止发出警告，以及与之对应的 "@on" ，会（重新）开启警告；其会忽略不可识别的控制信息。

xpcall (f, msgh [, arg1, ···])

此函数类似于pcall，不同在于其可以新设置一个错误消息处理函数 msgh 。