©
This document uses PHP Chinese website manual Release
标准的Lua库提供了直接通过C API实现的有用功能。其中一些功能为语言提供基本服务(例如type
和getmetatable
); 其他人提供对“外部”服务(例如I / O)的访问; 其他人可以在Lua本身实现,但是非常有用或者具有关键性能要求,应该在C中实现(例如table.sort
)。
所有库都通过官方C API实现,并作为单独的C模块提供。目前,Lua有以下标准库:
基础库(第6.1节);
协同程序库(第6.2节);
包库(第6.3节);
字符串操作(第6.4节);
基本的UTF-8支持(第6.5节);
表操作(第6.6节);
数学函数(§6.7)(sin,log等);
输入和输出(第6.8节);
操作系统设施(§6.9);
调试设施(第6.10节)。
除基本库和包库之外,每个库都将其所有功能作为全局表的字段或其对象的方法提供。
要访问这些库,C主机程序应调用该luaL_openlibs
函数,该函数将打开所有标准库。或者,主机程序可以通过luaL_requiref
调用luaopen_base
(对于基本库),luaopen_package
(对于包库),luaopen_coroutine
(对于协程库),luaopen_string
(对于字符串库),luaopen_utf8
(对于UTF8库),luaopen_table
(对于表库), luaopen_math
(用于数学库),(luaopen_io
对于I / O库), luaopen_os
(用于操作系统库),和luaopen_debug
(对于调试库)。这些函数在声明中lualib.h
。
基础库为Lua提供核心功能。如果您不在应用程序中包含此库,则应仔细检查是否需要为其某些设施提供实现。
assert (v [, message])
error
如果其参数的v
值为假(即,无或错误),则调用; 否则,返回它的所有参数。在出错的情况下,message
是错误对象; 当缺席时,它默认为“ assertion failed!
”
collectgarbage ([opt [, arg]])
该函数是垃圾收集器的通用接口。它根据它的第一个参数执行不同的功能opt
:
“ collect
”:执行完整的垃圾收集循环。这是默认选项。
“ stop
”:停止垃圾回收器的自动执行。收集器只有在显式调用时才会运行,直到调用才能重新启动。
“ restart
”:重新启动垃圾回收器的自动执行。
“ count
”:以千字节为单位返回Lua使用的总内存。该值有一个小数部分,所以它乘以1024给出了Lua使用的确切字节数(溢出除外)。
“ step
”:执行垃圾收集步骤。步骤“大小”由...控制arg
。使用零值时,收集器将执行一个基本(不可分)的步骤。对于非零值,收集器将执行内存数量(以千字节为单位)由Lua分配。如果步骤完成收集周期,则返回true。
“ setpause
”:设置arg
为收集器暂停的新值(见§2.5)。返回以前的暂停值。
“ setstepmul
”:设置arg
为收集器步骤乘数的新值(见§2.5)。返回步骤的前一个值。
“ isrunning
”:返回一个布尔值,告诉收集器是否正在运行(即未停止)。
dofile ([filename])
打开指定的文件并以Lua块的形式执行其内容。当不带参数调用时,dofile
执行标准input(stdin
)的内容。返回块返回的所有值。在发生错误的情况下,将错误dofile
传播给其调用者(即,dofile
不以保护模式运行)。
error (message [, level])
终止最后一个被调用的保护函数,并返回message
错误对象。函数error
永不返回。
通常,error
如果消息是字符串,则在消息的开头添加有关错误位置的一些信息。该level
参数指定如何获取错误位置。对于级别1(默认值),错误位置是error
调用函数的位置。级别2将错误指向调用的函数error
被调用的位置; 等等。通过级别0可避免在消息中添加错误位置信息。
_G
一个保存全局环境的全局变量(不是函数)(见§2.2)。Lua本身并不使用这个变量; 改变其价值不会影响任何环境,反之亦然。
getmetatable (object)
如果object
没有metatable,则返回nil。否则,如果对象的metatable有一个__metatable
字段,则返回相关的值。否则,返回给定对象的metatable。
ipairs (t)
返回三个值(一个迭代函数,表t
和0),以便构造
for i,v in ipairs(t) do body end
将迭代键值对(1,t[1]
),(2,t[2]
),...,直到第一个零值。
load (chunk [, chunkname [, mode [, env]]])
加载一个块。
如果chunk
是字符串,则块是该字符串。如果chunk
是一个函数,load
请重复调用它以获取块碎片。每次调用都chunk
必须返回一个与先前结果连接的字符串。返回一个空字符串,零或无值表示块的结尾。
如果没有语法错误,则将编译后的块作为函数返回; 否则,返回nil加上错误消息。
如果结果函数有价值,那么将第一个upvalue设置为值(env
如果给出该参数),或设置为全局环境的值。其他upvalues初始化为零。(当你加载一个主块时,结果函数总是只有一个正值,即_ENV
变量(参见§2.2)。但是,当你加载一个从函数创建的二进制块时(参见string.dump
),结果函数可以有一个任意数字)所有upvalues是新鲜的,也就是说,他们不与任何其他功能共享。
chunkname
用作错误消息和调试信息块的名称(请参阅第4.9节)。如果不存在,则默认为chunk
,如果chunk
是字符串,则为默认值,否则为“ =(load)
”。
该字符串mode
控制块是否可以是文本或二进制文件(即,预编译的块)。它可能是字符串“ b
”(仅二进制块),“ t
”(仅文本块)或“ bt
”(二进制和文本)。默认是“ bt
”。
Lua不检查二进制块的一致性。恶意制作的二进制块可能会导致解释器崩溃。
loadfile ([filename [, mode [, env]]])
类似于load
,但是从文件filename
或标准输入中获取块,如果没有给出文件名。
next (table [, index])
允许程序遍历表的所有字段。它的第一个参数是一个表,第二个参数是这个表中的一个索引。next
返回表格的下一个索引及其相关的值。当用nil作为第二个参数调用时,next
返回一个初始索引及其相关的值。当用最后一个索引调用时,或者在空表中调用nil时,next
返回nil。如果第二个参数不存在,那么它被解释为零。特别是,您可以使用next(t)
来检查表是否为空。
没有指定枚举索引的顺序,即使对于数字索引也是如此。(要按数字顺序遍历表,请使用数字表示。)
next
如果在遍历期间将任何值分配给表中不存在的字段,则其行为是未定义的。您可以修改现有的字段。特别是,您可以清除现有的字段。
pairs (t)
如果t
有metamethod __pairs
,则将其t
作为参数进行调用,并返回调用的前三个结果。
否则,返回三个值:next
函数,表t
和零,以便构建
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
metamethod。返回一个布尔值。
rawget (table, index)
获取真正的价值table[index]
,而不用调用__index
metamethod。table
必须是一张桌子; index
可能是任何值。
rawlen (v)
返回对象的长度,该对象v
必须是表或字符串,而不调用元__len
方法。返回一个整数。
rawset (table, index, value)
设置table[index]
to 的实际值value
,而不用调用__newindex
metamethod。table
必须是表格,index
不同于nil和NaN的value
值以及任何Lua值。
这个函数返回table
。
select (index, ···)
如果index
是一个数字,则返回参数号后面的所有参数index
; 从末尾开始的负数索引(-1是最后一个参数)。否则,index
必须是字符串"#"
,并select
返回它收到的额外参数的总数。
setmetatable (table, metatable)
设置给定表格的元数据。(要更改其他类型的从Lua代码的元表,则必须使用调试库(§6.10)。)如果metatable
是零,删除指定表的元表。如果原始metatable有一个__metatable
字段,则会引发错误。
这个函数返回table
。
tonumber (e [, base])
当用no调用时base
,tonumber
尝试将其参数转换为数字。如果参数已经是可转换为数字的数字或字符串,则tonumber
返回该数字; 否则返回nil。
根据Lua的词汇约定(见§3.1),字符串的转换可能导致整数或浮点数。(该字符串可能有前导和尾随空格以及符号。)
当用with调用时base
,那么e
必须是一个字符串,将其解释为该基数中的整数。基数可以是2到36之间的任何整数,包括2和36。在10以上的基数中,字母“ A
'(大写或小写)代表10,' B
'代表11等等,其中' Z
'代表35.如果字符串e
在给定基数中不是有效数字,则函数返回零。
tostring (v)
接收任何类型的值并将其转换为可读格式的字符串。(要完全控制数字如何转换,请使用string.format
。)
如果metatable v
有一个__tostring
字段,那么tostring
使用v
as参数调用相应的值,并将调用的结果作为结果。
type (v)
返回唯一参数的类型,以字符串形式编码。该函数的可能结果是“ nil
”(一个字符串,而不是值nil),“ number
”,“ string
”,“ boolean
”,“ table
”,“ function
”,“ thread
”和“ userdata
”。
_VERSION
一个全局变量(不是函数),它包含一个包含正在运行的Lua版本的字符串。这个变量的当前值是“ Lua 5.3
”。
xpcall (f, msgh [, arg1, ···])
这个功能类似于pcall
,除了它设置了一个新的消息处理程序msgh
。
这个库包含操作协程的操作,这些操作来自表格内部coroutine
。有关协程的一般描述,请参阅第2.6节。
coroutine.create (f)
创建一个新的协程,与身体f
。f
必须是一个功能。返回这个新的协程,它是一个带有类型的对象"thread"
。
coroutine.isyieldable ()
当运行的协程可以屈服时返回true。
如果运行的协程不是主线程,并且它不在不可执行的C函数内,则可运行协程。
coroutine.resume (co [, val1, ···])
启动或继续执行协程co
。你第一次恢复一个协程时,它开始运行它的身体。值val1
,...作为参数传递给正文函数。如果协程已经产生,resume
重新启动它; 值val1
,...作为收益结果传递。
如果协程没有任何错误地运行,则resume
返回true加上传递给yield
(当协程产生时)或者正文函数返回的任何值(当协程终止时)。如果有任何错误,则resume
返回错误并附加错误消息。
coroutine.running ()
当运行的协程是主协程时,返回正在运行的协程和布尔值。
coroutine.status (co)
返回协程的状态co
,作为字符串:"running"
,如果协程正在运行(即它被调用status
); "suspended"
,如果协程暂停了呼叫yield
,或者尚未开始运行; "normal"
如果协程是活动的但不运行(即它已经恢复了另一个协程); 并且"dead"
如果协程已经完成了它的主体功能,或者它已经停止了一个错误。
coroutine.wrap (f)
创建一个新的协程,与身体f
。f
必须是一个功能。返回一个函数,每次调用时都会恢复协程。任何传递给该函数的参数都会作为额外的参数resume
。返回resume
除第一个布尔值之外返回的相同值。在发生错误的情况下,传播错误。
coroutine.yield (···)
暂停调用协程的执行。任何参数yield
作为额外结果传递给resume
。
包库提供了用于在Lua中加载模块的基本设施。它直接在全球环境中输出一个函数:require
。其他的一切都以表格的形式输出package
。
require (modname)
加载给定的模块。该函数首先查看package.loaded
表以确定是否modname
已经加载。如果是,则require
返回存储在的值package.loaded[modname]
。否则,它会尝试为模块查找加载程序。
要找到一个装载机,require
由package.searchers
序列指导。通过改变这个顺序,我们可以改变如何require
查找模块。以下说明基于默认配置package.searchers
。
第一次require
查询package.preload[modname]
。如果它有一个值,这个值(它必须是一个函数)是加载器。否则require
使用存储在路径中的路径搜索Lua加载程序package.path
。如果这也失败了,它使用保存的路径搜索一个C加载器package.cpath
。如果这也失败了,它会尝试一个全功能的加载程序(请参阅参考资料package.searchers
)。
一旦找到一个加载器,require
就用两个参数调用加载器:modname
一个额外的值取决于它如何得到加载器。(如果加载程序来自文件,则此额外值为文件名。)如果加载程序返回任何非零值,require
则将返回值指定给package.loaded[modname]
。如果加载器没有返回非零值并且没有分配任何值package.loaded[modname]
,则将truerequire
赋值给该条目。无论如何,返回最终值。requirepackage.loaded[modname]
如果在加载或运行模块时出现任何错误,或者如果找不到该模块的任何加载程序,则会require
引发错误。
package.config
描述包的一些编译时配置的字符串。这个字符串是一系列的行:
第一行是目录分隔符字符串。\
对于Windows,默认值为' ',/
对于其他所有系统,默认值为' ' 。
第二行是分隔路径中模板的字符。默认是' ;
'。
第三行是标记模板中替换点的字符串。默认是' ?
'。
第四行是一个字符串,它在Windows的路径中被可执行文件的目录替换。默认是' !
'。
第五行是构建luaopen_
函数名称时忽略所有文本的标记。默认是' -
'。
package.cpath
require
搜索C加载器所用的路径。
Lua 使用环境变量或环境变量或者定义的缺省路径,以与package.cpath
初始化Lua路径相同的方式初始化C路径。package.pathLUA_CPATH_5_3LUA_CPATHluaconf.h
package.loaded
用于require
控制哪些模块已经加载的表格。当你需要一个模块modname
并且package.loaded[modname]
不是假的,require
只需返回存储在那里的值。
这个变量只是对真实表的引用; 赋给这个变量不会改变使用的表require
。
package.loadlib (libname, funcname)
将主机程序与C库动态链接libname
。
如果funcname
是“ *
”,那么它只与库链接,使库导出的符号可用于其他动态链接的库。否则,它将funcname
在库中查找函数,并将此函数作为C函数返回。所以,funcname
必须遵循lua_CFunction
原型(见lua_CFunction
)。
这是一个低级功能。它完全绕过了封装和模块系统。不像require
,它不执行任何路径搜索,也不会自动添加扩展。libname
必须是C库的完整文件名,包括必要时包含路径和扩展名。funcname
必须是由C库导出的确切名称(可能取决于所使用的C编译器和链接器)。
标准C不支持此功能。因此,它仅在某些平台(Windows,Linux,Mac OS X,Solaris,BSD以及支持该dlfcn
标准的其他Unix系统)上可用。
package.path
require
搜索Lua加载器所用的路径。
在启动时,如果没有定义这些环境变量,Lua会使用环境变量LUA_PATH_5_3
或环境变量的值LUA_PATH
或定义的默认路径来初始化此变量luaconf.h
。;;
环境变量值中的任何“ ”被替换为默认路径。
package.preload
用于存储特定模块的加载程序的表(请参阅require
)。
这个变量只是对真实表的引用; 赋给这个变量不会改变使用的表require
。
package.searchers
用于require
控制如何加载模块的表格。
此表中的每个条目都是搜索器功能。当查找一个模块时,require
以升序方式调用每个搜索器,并将模块名称(给出的参数require
)作为唯一参数。该函数可以返回另一个函数(模块加载器)加上一个将被传递给该加载器的额外值,或者一个字符串来解释为什么它找不到该模块(或者如果没有什么可说的话,则为零)。
Lua用四个搜索函数初始化这个表。
第一个搜索者只是在package.preload
表中寻找一个加载器。
第二个搜索器使用存储在的路径查找一个加载器作为Lua库package.path
。搜索按功能描述完成package.searchpath
。
第三个搜索器使用由变量给出的路径将加载器查找为C库package.cpath
。再次,搜索按功能描述完成package.searchpath
。例如,如果C路径是字符串
"./?.so;./?.dll;/usr/local/?/init.so"
对于模块搜索foo
将尝试打开这些文件./foo.so
,./foo.dll
以及/usr/local/foo/init.so
以该顺序。一旦找到一个C库,该搜索器首先使用动态链接工具将应用程序与库链接起来。然后它试图在库中找到一个用作加载器的C函数。此C函数的名称是字符串“ luaopen_
”,与模块名称的副本连接,每个点用下划线替换。此外,如果模块名称带有连字符,则会删除(并包括)第一个连字符后的后缀。例如,如果模块名称是a.b.c-v2.1
,函数名称将是luaopen_a_b_c
。
第四个搜索者尝试一个全功能的加载器。它在C路径中搜索给定模块的根名称的库。例如,当需要时a.b.c
,它会搜索一个C库a
。如果找到,它会查看子模块的打开功能; 在我们的例子中,那将是luaopen_a_b_c
。有了这个功能,软件包可以将几个C子模块打包到一个单独的库中,每个子模块保持其原有的开放功能。
除第一个搜索者(预加载)外,所有搜索者都会返回额外值作为返回的模块的文件名package.searchpath
。第一个搜索者没有返回任何额外的值。
package.searchpath (name, path [, sep [, rep]])
搜索给定name
的给定path
。
路径是包含由分号分隔的模板序列的字符串。对于每个模板,该函数将模板中的每个询问标记(如果有)替换为副本,name
其中sep
默认情况下所有出现的(缺省为点)被rep
(系统的目录分隔符,默认情况下)取代,然后尝试打开结果文件名。
例如,如果路径是字符串
"./?.lua;./?.lc;/usr/local/?/init.lua"
对于名称搜索foo.a
将尝试打开这些文件./foo/a.lua
,./foo/a.lc
以及/usr/local/foo/a/init.lua
以该顺序。
返回可以在读取模式下(关闭文件后)打开的第一个文件的结果名称,如果没有成功,则返回nil加上错误消息。(此错误消息列出了它试图打开的所有文件名。)
这个库提供了字符串操作的通用函数,例如查找和提取子字符串以及模式匹配。在Lua中索引一个字符串时,第一个字符位于位置1(不是0,如C)。索引被允许为负数,并被解释为从字符串的末尾向后索引。因此,最后一个字符位于-1,依此类推。
字符串库在表内提供了它的所有功能string
。它还为__index
字段指向表的字符串设置了metatable string
。因此,您可以在面向对象的风格中使用字符串函数。比如,string.byte(s,i)
可以写成s:byte(i)
。
字符串库采用单字节字符编码。
string.byte (s [, i [, j]])
返回字符的内部数字代码s[i]
,s[i+1]
,... s[j]
。默认值为i
1; j
is 的默认值i
。这些指数按照相同的功能规则进行修正string.sub
。
数字代码不一定是跨平台移植的。
string.char (···)
接收零个或多个整数。返回一个长度等于参数个数的字符串,其中每个字符的内部数字代码等于其相应的参数。
数字代码不一定是跨平台移植的。
string.dump (function [, strip])
返回包含给定函数的二进制表示(二进制块)的load
字符串,以便稍后在此字符串上返回该函数的副本(但具有新的upvalues)。如果strip
是真值,则二进制表示可能不包含有关该函数的所有调试信息,以节省空间。
具有upvalues的功能只有保存的upvalues的数量。当(重新)加载时,那些upvalues会收到包含nil的新实例。(您可以使用调试库以适合您需要的方式序列化并重新载入函数的upvalues。)
string.find (s, pattern [, init [, plain]])
pattern
查找字符串中的第一个匹配项(请参阅第6.4.1节)s
。如果找到匹配项,则find
返回s
此事件开始和结束位置的索引; 否则返回nil。第三个可选的数字参数init
指定从何处开始搜索; 其默认值是1,可以是负数。作为第四个可选参数的true值plain
会关闭模式匹配工具,因此该函数会执行简单的“查找子字符串”操作,而不会将字符pattern
视为魔术。请注意,如果plain
给出,那么也init
必须给出。
如果模式已经捕获,那么在成功的匹配中,捕获的值也会在两个索引之后返回。
string.format (formatstring, ···)
按照其第一个参数(必须是字符串)中给出的描述,返回其可变数量参数的格式化版本。格式字符串遵循与ISO C函数相同的规则sprintf
。唯一的区别是选项/修饰符*
,h
,L
,l
,n
,和p
不支持,并且有一个额外的选项,q
。
该q
选项在双引号之间格式化字符串,必要时使用转义序列以确保它可以安全地由Lua解释器读回。例如,电话
string.format('%q', 'a string with "quotes" and \n new line')
可能会产生字符串:
"a string with \"quotes\" and \ new line"
选项A
,a
,E
,e
,f
,G
,和g
所有期望一个数字作为论据。选项c
,d
,i
,o
,u
,X
,并x
期待一个整数。当使用C89编译器编译Lua时,选项A
和a
(十六进制浮点数)不支持任何修饰符(标志,宽度,长度)。
选项s
需要一个字符串; 如果它的参数不是一个字符串,它将被转换为一个遵循相同的规则tostring
。如果该选项具有任何修饰符(标志,宽度,长度),则字符串参数不应包含嵌入的零。
string.gmatch (s, pattern)
返回一个迭代器函数,每次调用它时,都会从pattern
字符串中返回下一个捕获(请参阅第6.4.1节)s
。如果pattern
没有指定捕捉,那么整个比赛都是在每个呼叫中产生的。
作为一个例子,下面的循环将遍历字符串中的所有单词s
,每行打印一个单词:
s = "hello world from Lua"for w in string.gmatch(s, "%a+") do print(w)end
下一个示例key=value
将给定字符串中的所有对收集到一个表中:
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])
返回一个副本,s
其中(见第6.4.1节)的所有(或第一个n
,如果给出)事件pattern
已被替换字符串替换,该字符串repl
可以是字符串,表格或函数。gsub
作为其第二个值还返回发生的匹配总数。这个名字gsub
来自全球性的Substitution。
如果repl
是字符串,则其值用于替换。该字符%
用作转义字符:repl
形式中的任何序列%d
,其中d在1和9之间,代表第d个捕获子字符串的值。序列%0
代表整个比赛。序列%%
代表一个单一的%
。
如果repl
是表格,则对每一个匹配查询表格,使用第一个捕捉作为关键字。
如果repl
是一个函数,那么每次匹配时都会调用该函数,所有捕获的子字符串按顺序作为参数传递。
无论如何,如果该模式没有指定捕获,那么它的行为就好像整个模式在捕获中一样。
如果表查询或函数调用返回的值是字符串或数字,则将其用作替换字符串; 否则,如果它是假或无,则没有替换(即,原始匹配保留在字符串中)。
这里有些例子:
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 load(s)() end)--> x="4+5 = 9"local t = {name="lua", version="5.3"}x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t)--> x="lua-5.3.tar.gz"
string.len (s)
接收一个字符串并返回其长度。空字符串的""
长度为0.嵌入的零计数,"a\000bc\000"
长度为5。
string.lower (s)
接收一个字符串并返回该字符串的一个副本,并将所有大写字母改为小写。所有其他角色保持不变。大写字母的定义取决于当前的语言环境。
string.match (s, pattern [, init])
查找字符串中的第一个匹配项pattern
(请参阅第6.4.1节)s
。如果它找到一个,然后match
从模式中返回捕获; 否则返回零。如果pattern
指定不捕获,则返回整个匹配。第三个可选的数字参数init
指定从何处开始搜索; 其默认值是1,可以是负数。
string.pack (fmt, v1, v2, ···)
返回包含的值的二进制串v1
,v2
等堆积(即,在二进制形式串行化)根据格式字符串fmt
(参见§6.4.2)。
string.packsize (fmt)
返回string.pack
给定格式的字符串的大小。格式字符串不能有可变长度选项' s
'或' z
'(见§6.4.2)。
string.rep (s, n [, sep])
返回一个字符串,它是n
由字符串s
分隔的字符串副本的串联sep
。默认值sep
是空字符串(即没有分隔符)。如果n
不是正值,则返回空字符串。
(请注意,通过一次调用此功能就可以很容易地消耗机器的内存。)
string.reverse (s)
返回一个字符串,该字符串是字符串s
反转
string.sub (s, i [, j])
返回该字符串的子字符串,s
并从此处i
继续j
; i
并j
可能是负面的。如果j
不存在,则假定它等于-1(这与字符串长度相同)。特别是,该调用string.sub(s,1,j)
返回s
长度的前缀j
,string.sub(s, -i)
(对于正数i
)返回s
长度的后缀i
。
如果在负指数转换后i
小于1,则校正为1.如果j
大于字符串长度,则校正为该长度。如果,这些修正后,i
大于j
,该函数返回空字符串。
string.unpack (fmt, s [, pos])
根据格式字符串返回按字符串打包的值s
(请参阅第6.4.2节)。可选标记从哪里开始阅读(默认为1)。在读取值之后,该函数还返回第一个未读字节的索引。string.packfmtposss
string.upper (s)
接收一个字符串并返回此字符串的一个副本,并将所有小写字母更改为大写。所有其他角色保持不变。小写字母的定义取决于当前的语言环境。
在Lua图案通过定期串,其通过模式匹配功能解释为图案描述string.find
,string.gmatch
,string.gsub
,和string.match
。本节介绍这些字符串的语法和含义(即它们匹配的内容)。
字符类用于表示一组字符。描述字符类时允许使用以下组合:
x:( 其中 x不是魔法字符之一 ^$()%.[]*+-?
)表示字符 x本身。
.
:(点)表示所有字符。
%a
:代表所有字母。
%c
:表示所有控制字符。
%d
:代表所有数字。
%g
:表示除空格外的所有可打印字符。
%l
:表示全部小写字母。
%p
:代表所有标点符号。
%s
:代表所有空格字符。
%u
:代表全部大写字母。
%w
:表示所有字母数字字符。
%x
:表示所有十六进制数字。
%x
:(其中x是任何非字母数字字符)表示字符x。这是摆脱魔法角色的标准方式。任何非字母数字字符(包括所有标点字符,甚至是非魔法字符)都可以在%
用于在模式中表示自己之前加上一个' '。
[set]
:表示集合中所有字符联合的类。字符范围可以通过将范围的结束字符按升序分隔为“ -
'来指定。上面描述的所有类%
x也可以用作组中的组件。集合中的所有其他字符表示自己。例如,[%w_]
(或[_%w]
)表示所有字母数字字符加上下划线,[0-7]
表示八进制数字,并且[0-7%l%-]
表示八进制数字加小写字母加上'-
'字符。您可以将一个方括号放入一个集合中,方法是将其定位为集合中的第一个字符。您可以通过将连字符定位为集合中的第一个或最后一个字符来在连字符中添加连字符。(您也可以在两种情况下使用转义。)范围和类之间的交互没有定义。因此,模式[%a-z]
或[a-%%]
没有意义。
[^set]
:表示集合的补码,其中集合被解释为如上。
对于以单个字母(%a
,%c
等)表示的所有类,相应的大写字母表示该类的补码。例如,%S
表示所有非空格字符。
字母,空格和其他字符组的定义取决于当前的语言环境。特别是,班级[a-z]
可能不等同于%l
。
一个模式项目可以
单个字符类,它匹配类中的任何单个字符;
一个单一的字符类,后面跟着' *
',它匹配类中零个或多个字符的重复。这些重复项目将始终匹配最长的序列;
一个单个字符类,后跟“ +
”,它匹配类中一个或多个字符的重复。这些重复项目将始终匹配最长的序列;
一个单一的字符类,后面跟着' -
',它也匹配类中零个或多个字符的重复。与' *
' 不同,这些重复项目将始终匹配最短的序列;
一个单一的字符类,后跟' ?
',匹配类中一个字符的零次或一次出现。如果可能,它始终匹配一个事件;
%n
,n在1和9之间; 这样的项目匹配一个子字符串等于第n个捕获的字符串(见下文)。
%bxy
,其中x和y是两个不同的字符; 这样的项目相匹配,与开头的字符串X,结尾ÿ,并且其中X和Ÿ是平衡的。这意味着,如果从左到右读取字符串,则对x计算+1并对于y计算-1,结尾y是计数达到0 的第一个y。例如,该项匹配具有平衡圆括号的表达式。%b()
%f[set]
,一个前沿模式 ; 这样的项目匹配任何位置上的空字符串,使得下一个字符属于set,并且前一个字符不属于set。如前所述解释集合集合。主题的开始和结束被处理,就好像它们是字符' \0
'。
甲图案是图案项的序列。^
在模式开头的一个插入符“ '将匹配锚定在主题字符串的开头。$
模式末尾的'' '将主题字符串末尾的匹配锚定。在其他职位上,' ^
'和' $
'没有特殊的含义并代表自己。
一个模式可以包含括在括号内的子模式; 他们描述捕获。匹配成功时,匹配捕获的主题字符串的子字符串将被存储(捕获)以备将来使用。捕捉按照左括号进行编号。例如,在该模式中"(a*(.)%w(%s*))"
,字符串匹配的部分"a*(.)%w(%s*)"
被存储为第一次捕获(因此具有数字1); .
用数字2捕获字符匹配“ ”,并且匹配“ %s*
” 的部分具有数字3。
作为一种特殊情况,空的捕获()
捕获当前的字符串位置(一个数字)。例如,如果我们将该模式"()aa()"
应用于字符串"flaaap"
,则会有两个捕获:3和5。
第一个参数是string.pack
,,string.packsize
并且string.unpack
是格式字符串,它描述正在创建或读取的结构的布局。
格式字符串是一系列转换选项。转换选项如下所示:
<
:设置小端
>
:设置大端
=
:设置本地排序
![n]
:将最大对齐设置为n
(默认为本地对齐)
b
:有符号字节(char
)
B
:一个无符号字节(char
)
h
:签名short
(本地大小)
H
:无符号short
(原生大小)
l
:签名long
(本地大小)
L
:无符号long
(原生大小)
j
: 一个 lua_Integer
J
: 一个 lua_Unsigned
T
:a size_t
(原生尺寸)
i[n]
:int
用n
字节签名(默认是原生大小)
I[n]
:int
与n
字节无符号(默认为本地大小)
f
:a float
(原生尺寸)
d
:a double
(原生尺寸)
n
: 一个 lua_Number
cn
:带n
字节的固定大小的字符串
z
:以零结尾的字符串
s[n]
:一个字符串前面的长度编码为带n
字节的无符号整数(默认值为a size_t
)
x
:一个字节的填充
Xop
:根据选项排列的空项目op
(否则将忽略)
'':(空格)被忽略
(A“ ”表示可选的整数。)除填充,空格和配置(选项“ ”)外,每个选项对应于参数(in )或结果(in )。[n]xX <=>!string.packstring.unpack
对于选项“ !n
”,“ sn
”,“ in
”和“ In
”,n
可以是1到16之间的任何整数。所有积分选项检查溢出; string.pack
检查给定的值是否符合给定的大小; string.unpack
检查读取值是否适合Lua整数。
任何格式字符串的起始位置都是前缀为“ !1=
”,即最大对齐为1(无对齐)和本机排序。
对齐方式的工作方式如下:对于每个选项,格式会获得额外的填充,直到数据以选项大小和最大对齐之间的最小值的倍数的偏移量开始; 这个最小值必须是2的幂。选项“ c
”和“ z
”不对齐; 选项“ s
”遵循其开始整数的对齐方式。
所有填充由零填充string.pack
(并被忽略string.unpack
)。
该库为UTF-8编码提供基本支持。它提供了表格内的所有功能utf8
。除了处理编码之外,该库不提供对Unicode的任何支持。任何需要字符含义的操作,如字符分类,都不在其范围之内。
除非另有说明,否则将字节位置作为参数的所有函数都假定给定的位置是字节序列的开始或加上主题字符串的长度。就像在字符串库中一样,从字符串末尾开始计算负指数。
utf8.char (···)
接收零个或多个整数,将每个整数转换为其对应的UTF-8字节序列,并返回一个串联所有这些序列的字符串。
utf8.charpattern
模式(一个字符串,不是函数)“ [\0-\x7F\xC2-\xF4][\x80-\xBF]*
”(见§6.4.1),它恰好匹配一个UTF-8字节序列,假设主体是一个有效的UTF-8字符串。
utf8.codes (s)
返回值以便构造
for p, c in utf8.codes(s) do body end
将迭代字符串中的所有字符s
,其中p
包括c
每个字符的位置(以字节为单位)和代码点。如果它遇到任何无效的字节序列,则会引发错误。
utf8.codepoint (s [, i [, j]])
返回s
字节位置i
和j
(均包含)之间的所有字符中的代码点(以整数形式)。缺省值i
是1和j
是i
。如果它遇到任何无效的字节序列,则会引发错误。
utf8.len (s [, i [, j]])
返回s
在位置i
和j
(包括两个端点)之间开始的字符串中UTF-8字符的数量。缺省值i
是1,并且j
是-1。如果发现任何无效的字节序列,则返回一个假值加上第一个无效字节的位置。
utf8.offset (s, n [, i])
返回(从位置开始计数)n
第 - 个字符开始编码的位置(以字节为单位)。负数在位置前获得字符。当为非负时默认为1 ,否则为从字符串末尾获得第 - 个字符的偏移量。如果指定的字符既不在主题中,也不在主题结束后,该函数返回nil。siniin#s + 1utf8.offset(s, -n)n
作为特殊情况,当n
为0时,函数返回包含第 - i
个字节的字符的编码开始s
。
这个函数假定这s
是一个有效的UTF-8字符串。
该库为表格操作提供了通用函数。它提供了表格内的所有功能table
。
记住,每当一个操作需要一个表的长度时,关于长度运算符的所有注意事项都适用(见§3.4.7)。所有函数都会忽略以参数形式给出的表中的非数字键。
table.concat (list [, sep [, i [, j]]])
给定一个列表,其中所有元素都是字符串或数字,返回字符串list[i]..sep..list[i+1] ··· sep..list[j]
。默认值为sep
空字符串,默认i
值为1,默认j
值为#list
。如果i
大于j
,则返回空字符串。
table.insert (list, [pos,] value)
插入元件value
在位置pos
中list
,上移的元素list[pos], list[pos+1], ···, list[#list]
。pos
is 的缺省值#list+1
,以便在列表末尾table.insert(t,x)
插入一个调用。xt
table.move (a1, f, e, t [,a2])
a1
将表格中的元素移动到表格a2
,执行与以下多重赋值相同的操作:a2[t],··· = a1[f],···,a1[e]
。a2
is 的默认值是a1
。目标范围可以与源范围重叠。要移动的元素数量必须符合Lua整数。
返回目标表a2
。
table.pack (···)
返回一个新表格,其中所有参数存储在键1,2等中,并带有一个n
带有参数总数“ ” 的字段。请注意,结果表可能不是一个序列。
table.remove (list [, pos])
从list
位置处的元素中移除pos
,返回已移除元素的值。当pos
是1和1之间的整数时#list
,它将元素向下移动list[pos+1], list[pos+2], ···, list[#list]
并擦除元素list[#list]
; pos
当#list
为0时,索引也可以为0,或者#list + 1
; 在这些情况下,该功能会擦除该元素list[pos]
。
pos
is 的默认值#list
,以便调用table.remove(l)
删除列表的最后一个元素l
。
table.sort (list [, comp])
排序列出一个给定的顺序元素,就地,从list[1]
到list[#list]
。如果comp
给出,那么它必须是一个接收两个列表元素的函数,并且当第一个元素必须位于最后一个顺序中的第二个元素之前时返回true(所以在排序后i < j
隐含not comp(list[j],list[i])
)。如果comp
没有给出,则使用标准的Lua运算符<
。
请注意,comp
函数必须在列表中的元素上定义严格的部分顺序; 也就是说,它必须是不对称和传递的。否则,无法进行有效的排序。
排序算法不稳定:按给定顺序认为相同的元素可能会根据排序而改变其相对位置。
table.unpack (list [, i [, j]])
返回给定列表中的元素。这个功能相当于
return list[i], list[i+1], ···, list[j]
默认情况下,i
是1并且j
是#list
。
这个库提供了基本的数学函数。它提供了表格中的所有功能和常量math
。带注释“ integer/float
”的函数给出整数参数的整数结果,以及浮点(或混合)参数的浮点结果。舍入函数(math.ceil
,,math.floor
和math.modf
)在结果符合整数范围时返回整数,否则返回浮点数。
math.abs (x)
返回的绝对值x
。(整数/浮点)
math.acos (x)
返回x
(弧度)的反余弦值。
math.asin (x)
返回x
(弧度)的反正弦值。
math.atan (y [, x])
返回y/x
(以弧度为单位)的反正切,但使用两个参数的符号来查找结果的象限。(它也可以正确处理x
为零的情况。)
默认值为x
1,以便该调用math.atan(y)
返回的反正切值y
。
math.ceil (x)
返回大于或等于的最小整数值x
。
math.cos (x)
返回余弦值x
(假设为弧度)。
math.deg (x)
将角度x
从弧度转换为度数。
math.exp (x)
返回值ex(其中e
是自然对数的底数)。
math.floor (x)
返回小于或等于的最大积分值x
。
math.fmod (x, y)
返回x
by 的除法余数,y
将商向零进行舍入。(整数/浮点)
math.huge
浮点值HUGE_VAL
,一个大于任何其他数值的值。
math.log (x [, base])
返回x
给定基数的对数。默认base
值为e(使函数返回自然对数x
)。
math.max (x, ···)
根据Lua运算符,返回具有最大值的参数<
。(整数/浮点)
math.maxinteger
一个整数,其最大值为整数。
math.min (x, ···)
根据Lua运算符,返回具有最小值的参数<
。(整数/浮点)
math.mininteger
一个整数的最小值的整数。
math.modf (x)
返回的整数部分x
和小数部分x
。其第二个结果总是一个浮动。
math.pi
π的值。
math.rad (x)
将x
度数转换为弧度。
math.random ([m [, n]])
在没有参数的情况下调用时,返回一个在[0,1]范围内均匀分布的伪随机浮点数。当与两个整数称为m
和n
,math.random
返回与在范围内均匀分布的伪随机整数M,N。(nm值不能是负数,必须符合一个Lua整数。)该调用math.random(n)
等价于math.random(1,n)
。
该功能是由C提供的下层伪随机生成器功能的接口。
math.randomseed (x)
设置x
为伪随机生成器的“种子”:相等的种子产生相同的数字序列。
math.sin (x)
返回x
(假定为弧度)的正弦值。
math.sqrt (x)
返回的平方根x
。(您也可以使用表达式x^0.5
来计算此值。)
math.tan (x)
返回x
(假定以弧度表示)的正切值。
math.tointeger (x)
如果该值x
可转换为整数,则返回该整数。否则,返回零。
math.type (x)
返回“ integer
”if x
是一个整数,“ float
”如果它是一个浮点数,或者nil如果x
不是一个数字。
math.ult (m, n)
返回一个布尔值,当且仅当整数真正m
低于整数n
,当他们为无符号整数比较。
I / O库为文件操作提供了两种不同的样式。第一个使用隐式文件句柄; 即有设置默认输入文件和默认输出文件的操作,并且所有输入/输出操作都在这些默认文件上。第二种风格使用显式文件句柄。
使用隐式文件句柄时,所有操作都由表提供io
。当使用显式文件句柄时,操作io.open
返回一个文件句柄,然后提供所有操作作为文件句柄的方法。
该表io
还提供了由C它们的通常含义三个预定义的文件句柄:io.stdin
,io.stdout
,和io.stderr
。I / O库从不关闭这些文件。
除非另有说明,否则所有I / O函数在失败时都会返回nil(作为第二个结果加上一个错误消息,并将第三个结果作为依赖于系统的错误代码),并且某些值与成功时的零值不同。在非POSIX系统上,在发生错误时计算错误消息和错误代码可能不是线程安全的,因为它们依赖于全局C变量errno
。
io.close ([file])
相当于file:close()
。没有file
,关闭默认的输出文件。
io.flush ()
相当于io.output():flush()
。
io.input ([file])
当用文件名称调用时,它将打开指定文件(以文本模式),并将其句柄设置为默认输入文件。当用文件句柄调用时,它只是将此文件句柄设置为默认输入文件。当不带参数调用时,它返回当前的默认输入文件。
如果出现错误,该函数会引发错误,而不是返回错误代码。
io.lines ([filename, ···])
以读取模式打开给定的文件名,并返回一个迭代器函数,它可以像file:lines(···)
打开的文件一样工作。当迭代器函数检测到文件结束时,它将不返回任何值(完成循环)并自动关闭文件。
通话io.lines()
(没有文件名)相当于io.input():lines("*l")
; 也就是说,它遍历默认输入文件的行。在这种情况下,循环结束时它不会关闭文件。
如果出现错误,该函数会引发错误,而不是返回错误代码。
io.open (filename [, mode])
该函数以字符串中指定的模式打开一个文件mode
。如果成功,它会返回一个新的文件句柄。
该mode
字符串可以是下列任何一项:
“ r
”:读取模式(默认);
“ w
”:写入模式;
“ a
”:追加模式;
“ r+
”:更新模式,所有以前的数据被保留;
“ w+
”:更新模式,所有先前的数据被擦除;
“ a+
”:追加更新模式,保留以前的数据,只允许在文件末尾写入。
该mode
字符串最后也可以有'' b
',这在某些系统中需要以二进制模式打开文件。
io.output ([file])
与io.input
默认输出文件类似,但操作在默认输出文件上。
io.popen (prog [, mode])
此功能取决于系统,并不适用于所有平台。
prog
以独立进程启动程序并返回一个文件句柄,您可以使用该句柄从此程序读取数据(如果mode
是"r"
,则为默认值)或将数据写入此程序(如果mode
是"w"
)。
io.read (···)
相当于io.input():read(···)
。
io.tmpfile ()
如果成功,则返回临时文件的句柄。该文件以更新模式打开,并在程序结束时自动删除。
io.type (obj)
检查是否obj
是有效的文件句柄。返回字符串,"file"
如果obj
是打开的文件句柄,"closed file"
if obj
是关闭的文件句柄,或者如果不是文件句柄,则返回nilobj
。
io.write (···)
相当于io.output():write(···)
。
file:close ()
关闭file
。请注意,文件在垃圾回收处理时会自动关闭,但需要花费无法预测的时间。
当关闭使用创建的文件句柄时io.popen
,file:close
返回相同的返回值os.execute
。
file:flush ()
保存任何写入的数据file
。
file:lines (···)
返回一个迭代器函数,每次调用时都会根据给定的格式读取文件。如果没有给出格式,则使用“ l
”作为默认值。作为一个例子,建设
for c in file:lines(1) do body end
将从当前位置开始迭代文件的所有字符。不像io.lines
,这个函数在循环结束时不会关闭文件。
如果出现错误,该函数会引发错误,而不是返回错误代码。
file:read (···)
file
根据给定的格式读取文件,这些格式指定要读取的内容。对于每种格式,该函数都返回一个字符串或一个数字,并读取字符; 如果无法读取指定格式的数据,则返回nil。(在后一种情况下,该函数不会读取后续格式。)当没有格式时,它使用读取下一行的默认格式(见下文)。
可用的格式是
“ n
”:按照Lua的词汇约定,读取一个数字并将其作为浮点数或整数返回。(数字可能有前导空格和符号。)这种格式总是读取最长的输入序列,该输入序列是数字的有效前缀; 如果该前缀未形成有效数字(例如,空字符串,“ 0x
”或“ 3.4e-
”),则将其丢弃并且函数返回nil。
“ a
”:从当前位置开始读取整个文件。在文件结尾处,它返回空字符串。
“ l
”:读取下一行跳过行尾,在文件结尾处返回零。这是默认格式。
“ L
”:读取保存行尾字符的下一行(如果存在),在文件结尾处返回nil。
number: 读取一个字节数最多的字符串,在文件结尾处返回 nil。如果number
为零,则它什么都不读,并返回一个空字符串,或者在文件结尾处为零。
格式“ l
”和“ L
”只能用于文本文件。
file:seek ([whence [, offset]])
设置并从文件开始处测量文件位置到offset
由字符串指定的基点加上的位置whence
,如下所示:
“ set
”:base是位置0(文件的开头);
“ cur
”:基数是当前位置;
“ end
”:基地是文件的结尾;
在成功的情况下,seek
返回最终的文件位置,从文件开始以字节为单位测量。如果seek
失败,则返回nil,加上描述错误的字符串。
whence
is 的默认值为"cur"
,并且for offset
为0.因此,调用file:seek()
返回当前文件位置,而不更改它; 该调用file:seek("set")
将位置设置为文件的开始位置(并返回0); 并且调用file:seek("end")
将该位置设置为文件末尾,并返回其大小。
file:setvbuf (mode [, size])
设置输出文件的缓冲模式。有三种可用模式:
“ no
”:无缓冲; 任何输出操作的结果都立即出现。
“ full
”:完全缓冲; 输出操作仅在缓冲区已满或您明确flush
指定文件时执行(请参阅io.flush
)。
“ line
”:行缓冲; 输出被缓冲直到输出换行符或者从某些特殊文件(例如终端设备)输入任何输入。
对于最后两种情况,请size
指定缓冲区的大小(以字节为单位)。默认值是合适的大小。
file:write (···)
将其每个参数的值写入file
。参数必须是字符串或数字。
如果成功,此函数返回file
。否则返回nil加一个描述错误的字符串。
这个库是通过表来实现的os
。
os.clock ()
返回程序使用的CPU时间量的近似值。
os.date ([format [, time]])
返回包含日期和时间的字符串或表格,并根据给定的字符串格式化format
。
如果time
参数存在,这是要格式化的时间(请参阅该os.time
函数以获取该值的说明)。否则,date
格式化当前时间。
如果format
以' !
' 开头,则日期格式为协调世界时。在此可选字符后,如果format
是字符串“ *t
”,则date
返回包含以下字段的表:year
,month
(1-12),day
(1-31),hour
(0-23),min
(0-59),sec
(0-61 ),wday
(星期一,星期一,星期日,星期一,星期一,星期一,星期一,星期一yday
,1-366)和isdst
夏令时标志布尔值。如果信息不可用,则最后一个字段可能不存在。
如果format
不是“ *t
”,则date
将该日期作为字符串返回,按照与ISO C函数相同的规则格式化strftime
。
在没有参数的情况下调用时,date
返回依赖于主机系统和当前语言环境的合理日期和时间表示。(更具体地说,os.date()
相当于os.date("%c")
。)
在非POSIX系统上,由于它依赖于C函数gmtime
和C函数,此函数可能不是线程安全的localtime
。
os.difftime (t2, t1)
t1
不时t2
(以秒为单位)返回差值(其中时间是返回的值os.time
)。在POSIX,Windows和其他一些系统中,这个值就是t2
-t1
。
os.execute ([command])
该功能等同于ISO C功能system
。它传递command
给操作系统shell执行。如果命令成功终止,其第一个结果是true,否则为零。在第一个结果之后,函数返回一个字符串加上一个数字,如下所示:
“ exit
”:命令正常终止; 以下数字是该命令的退出状态。
“ signal
”:命令被信号终止; 以下数字是终止命令的信号。
当没有调用时command
,os.execute
返回一个布尔值,如果shell可用,则返回true。
os.exit ([code [, close]])
调用 ISO C 函数exit
来终止主机程序。如果code
为真,返回的状态是EXIT_SUCCESS
; 如果code
是false,返回的状态是EXIT_FAILURE
; 如果code
是一个数字,返回的状态就是这个数字。作为默认值code
是真。
如果可选的第二个参数close
为true,则在退出之前关闭Lua状态。
os.getenv (varname)
返回流程环境变量的值,如果变量未定义varname
,则返回nil。
os.remove (filename)
用给定名称删除文件(或POSIX系统上的空目录)。如果此函数失败,则返回nil,加上描述错误和错误代码的字符串。否则,它返回true。
os.rename (oldname, newname)
重命名指定的文件或目录oldname
来newname
。如果此函数失败,则返回nil,加上描述错误和错误代码的字符串。否则,它返回true。
os.setlocale (locale [, category])
设置程序的当前区域设置。locale
是一个指定语言环境的依赖于系统的字符串; category
是可选的字符串描述改变哪一类:"all"
,"collate"
,"ctype"
,"monetary"
,"numeric"
,或"time"
; 默认类别是"all"
。该函数返回新语言环境的名称,或者如果请求无法兑现,则返回nil。
如果locale
是空字符串,则将当前语言环境设置为实现定义的本地语言环境。如果locale
是字符串“ C
”,则将当前语言环境设置为标准C语言环境。
当用nil作为第一个参数调用时,此函数仅返回给定类别的当前语言环境的名称。
这个函数可能不是线程安全的,因为它依赖于C函数setlocale
。
os.time ([table])
在不带参数的情况下调用当前时间,或者返回表示由给定表指定的本地日期和时间的时间。该表必须包含字段year
,month
和day
,并且可能有字段hour
(默认值为12),min
(默认值为0),sec
(默认值为0)和isdst
(默认值为零)。其他字段被忽略。有关这些字段的说明,请参阅该os.date
功能。
这些字段中的值不需要在有效范围内。例如,如果sec
是-10,则表示距其他字段指定的时间为-10秒; 如果hour
是1000,则表示距其他字段指定的时间+1000小时。
返回的值是一个数字,其含义取决于您的系统。在POSIX,Windows和其他一些系统中,这个数字计算自某些给定开始时间(“时代”)以来的秒数。在其它系统中,意思是未指定,并且通过返回的数字time
只能用于作为参数os.date
和os.difftime
。
os.tmpname ()
返回可用于临时文件的具有文件名的字符串。该文件必须在使用前明确打开,并在不再需要时明确删除。
在POSIX系统上,该功能还会创建一个具有该名称的文件,以避免安全风险。(其他人可能会在获取名称和创建文件之间的时间内以错误的权限创建文件。)您仍然必须打开文件才能使用该文件并将其删除(即使您不使用它)。
如果可能,您可能更喜欢使用io.tmpfile
,它会在程序结束时自动删除文件。
该库为Lua程序提供了调试接口(§4.9)的功能。使用这个库时应该小心。它的几个函数违反了关于Lua代码的基本假设(例如,函数本地的变量不能从外部访问;用户数据元表达式不能被Lua代码改变; Lua程序不会崩溃),因此可能危及其他安全代码。而且,这个库中的一些功能可能会很慢。
debug
表格中提供了该库中的所有功能。所有在线程上运行的函数都有一个可选的第一个参数,它是要运行的线程。默认总是当前线程。
debug.debug ()
与用户进入交互模式,运行用户输入的每个字符串。使用简单的命令和其他调试工具,用户可以检查全局和局部变量,更改它们的值,评估表达式等等。只包含单词的行cont
结束此函数,以便调用方继续执行。
请注意,用于命令的命令在debug.debug
词汇上不嵌套在任何函数中,因此不能直接访问局部变量。
debug.gethook ([thread])
返回线程的当前钩子设置,作为三个值:当前钩子函数,当前钩子掩码和当前钩子计数(由debug.sethook
函数设置)。
debug.getinfo ([thread,] f [, what])
返回包含有关函数信息的表格。你可以直接给这个函数,或者你可以给一个数字作为值f
,这意味着f
在给定线程的调用堆栈级别上运行的函数:0级是当前函数(getinfo
本身)。等级1是被调用的函数getinfo
(除了不计入堆栈的尾调用外); 等等。如果f
是大于活动函数数的数字,则getinfo
返回nil。
返回的表可以包含返回的所有字段lua_getinfo
,字符串what
描述填写哪些字段。缺省值what
是获取所有可用信息,有效行表除外。如果存在,则选项“ f
'添加一个以func
该函数本身命名的字段。如果存在,选项' L
'添加一个以activelines
有效行表命名的字段。
例如debug.getinfo(1,"n").name
,如果可以找到合理的名称,则该表达式返回当前函数的名称,并且该表达式debug.getinfo(print)
返回一个包含关于该print
函数的所有可用信息的表。
debug.getlocal ([thread,] f, local)
此函数返回本地变量的名称和值,以及堆栈local
级别的函数的索引f
。该函数不仅访问显式局部变量,还访问参数,临时对象等。
第一个参数或局部变量具有索引1,依此类推,按照它们在代码中声明的顺序,只计算在当前函数范围内处于活动状态的变量。负指数是指可变参数; -1是第一个可变参数。如果没有给定索引的变量,则该函数返回nil,并在超出范围的级别调用时引发错误。(您可以打电话debug.getinfo
查看该级别是否有效。)
以' (
'(左圆括号)开头的变量名称表示没有已知名称的变量(内部变量,如循环控制变量,以及块保存而没有调试信息的变量)。
该参数f
也可以是一个函数。在这种情况下,getlocal
只返回函数参数的名称。
debug.getmetatable (value)
返回给定value
或nil的metatable,如果它没有metatable。
debug.getregistry ()
返回注册表表(请参阅§4.5)。
debug.getupvalue (f, up)
该函数返回的名称和的upvalue的索引值up
的功能f
。如果给定索引不存在上值,则函数返回nil。
以' (
'(左括号)开头的变量名表示没有已知名称的变量(保存了没有调试信息的块的变量)。
debug.getuservalue (u)
返回与之相关的Lua值u
。如果u
不是完整的用户数据,则返回nil。
debug.sethook ([thread,] hook, mask [, count])
将给定的函数设置为钩子。字符串mask
和数字count
描述何时调用钩子。字符串掩码可以具有以下字符的任意组合,并具有给定的含义:
' c
':每次Lua调用函数时都会调用该钩子;
' r
':每次Lua从函数返回时都会调用钩子;
' l
':每次Lua输入一行新代码时都会调用钩子。
而且,与count
零不同的是,钩子在每个count
指令之后也被调用。
在没有参数的情况下调用时,debug.sethook
关闭钩子。
当钩被调用时,它的第一个参数是描述已经触发了呼叫事件的字符串:"call"
(或"tail call"
)"return"
,"line"
和"count"
。对于线事件,挂钩也会获取新的线号作为其第二个参数。在一个钩子里面,你可以调用getinfo
2级来获得关于运行函数的更多信息(0级是getinfo
函数,1级是钩子函数)。
debug.setlocal ([thread,] level, local, value)
该函数将该值赋给value
本地变量,并在堆栈local
级别使用该函数的索引level
。如果没有给定索引的局部变量,则该函数返回nil,并在level
超出范围调用时引发错误。(您可以调用getinfo
以检查该级别是否有效。)否则,它将返回本地变量的名称。
请参阅debug.getlocal
有关变量索引和名称的更多信息。
debug.setmetatable (value, table)
给定value
给定的元数据table
(可以为零)。退货value
。
debug.setupvalue (f, up, value)
该函数将该值value
与up
该函数的索引一起赋值f
。如果给定索引不存在上值,则函数返回nil。否则,它返回upvalue的名称。
debug.setuservalue (udata, value)
将给定设置为与给定value
关联的Lua值udata
。udata
必须是完整的用户数据。
Returns udata
.
debug.traceback ([thread,] [message [, level]])
如果message
存在但不是字符串也不是零,则此函数将message
不作处理返回。否则,它将返回一个带有回调调用堆栈的字符串。可选message
字符串被追加到回溯的开头。一个可选的level
数字告诉在哪个级别开始回溯(默认是1,函数调用traceback
)。
debug.upvalueid (f, n)
返回n
从给定函数编号的upvalue的唯一标识符(作为light userdata)。
这些唯一标识符允许程序检查不同的关闭是否共享upvalue。共享一个upvalue(也就是说,访问一个相同的外部局部变量)的Lua闭包将为这些upvalue索引返回相同的id。
debug.upvaluejoin (f1, n1, f2, n2)
使n1
Lua闭包f1
的n2
第 - 个最高值指Lua闭包的第 - 个最高值f2
。
虽然Lua被设计为扩展语言,但是它被嵌入到主机C程序中,但它也经常用作独立语言。Lua作为独立语言的解释器简单地称为lua
标准分发。独立解释器包含所有标准库,包括调试库。它的用法是:
lua [options] [script [args]]
选项是:
-e
stat
:执行字符串stat ;
-l
mod
:“需要” mod ;
-i
:运行脚本后进入交互模式;
-v
:打印版本信息;
-E
:忽略环境变量;
--
:停止处理选项;
-
:stdin
作为文件执行并停止处理选项。
处理lua
完选项后,运行给定的脚本。当不带参数调用时,lua
其行为lua -v -i
与标准输入(stdin
)是终端时相反,lua -
否则。
在没有选项-E
的情况下调用时,解释器在运行任何参数之前检查环境变量LUA_INIT_5_3
(或者LUA_INIT
如果未定义版本名称)。如果变量内容具有格式@filename
,则lua
执行该文件。否则,lua
执行字符串本身。
当用选项调用时-E
,除了忽略之外LUA_INIT
,Lua还会忽略和的值,LUA_PATH
并LUA_CPATH
设置package.path
和package.cpath
定义默认路径的值luaconf.h
。
所有选项都按顺序处理,除了-i
和-E
。例如,像一个调用
$ lua -e'a=1' -e 'print(a)' script.lua
将首先设置a
为1,然后打印该值a
,最后运行script.lua
没有参数的文件。(这里$
是shell提示符,您的提示可能会有所不同。)
在运行任何代码之前,lua
收集名为的全局表中的所有命令行参数arg
。脚本名称转到索引0,脚本名称转到索引1后的第一个参数,依此类推。脚本名称之前的任何参数(即解释器名称加上其选项)都会转到负数索引。例如,在通话中
$ lua -la b.lua t1 t2
表是这样的:
arg = { [-2] = "lua", [-1] = "-la", [0] = "b.lua", [1] = "t1", [2] = "t2" }
如果调用中没有脚本,则解释器名称将转到索引0,然后是其他参数。例如,电话
$ lua -e "print(arg[1])"
将打印“ -e
”。如果有一个脚本,脚本被调用参数arg[1]
,...,arg[#arg]
。(和Lua中的所有块一样,该脚本被编译为可变参数函数。)
在交互模式下,Lua重复提示并等待一条线。读完一行后,Lua首先尝试将该行解释为表达式。如果成功,则打印其值。否则,它会将该行解释为声明。如果你写一个不完整的语句,解释器通过发出不同的提示来等待它的完成。
如果全局变量_PROMPT
包含一个字符串,则其值将用作提示。同样,如果全局变量_PROMPT2
包含一个字符串,则其值将用作辅助提示(在不完整的语句中发出)。
如果脚本中存在未受保护的错误,解释器会将错误报告给标准错误流。如果错误对象不是一个字符串,但有一个metamethod __tostring
,解释器会调用这个metamethod来产生最终的消息。否则,解释器会将错误对象转换为字符串并向其添加堆栈回溯。
当正常结束时,解释者关闭其主要的Lua状态(参见lua_close
)。脚本可以通过调用os.exit
终止来避免这一步。
为了允许在Unix系统中使用Lua作为脚本解释器,独立解释器跳过块开始的块的第一行#
。因此,Lua脚本可以通过使用chmod +x
和#!
形式变成可执行程序,如
#!/usr/local/bin/lua
(当然,你的机器上Lua解释器的位置可能不同,如果你的机器lua
是在你的机器上的PATH
话
#!/usr/bin/env lua
是一种更便携的解决方案。)
这里我们列出了将程序从Lua 5.2移植到Lua 5.3时可能遇到的不兼容问题。你可以通过用适当的选项编译Lua来避免一些不兼容(见文件luaconf.h
)。但是,所有这些兼容性选项将在未来取消。
Lua版本总是可以以不暗示程序中源代码更改的方式更改C API,例如常量的数值或将函数实现为宏。因此,你不应该假设二进制文件在不同的Lua版本之间是兼容的。使用新版本时,总是重新编译Lua API的客户端。
同样,Lua版本可以随时更改预编译块的内部表示; 预编译的块在不同的Lua版本之间不兼容。
官方发行版中的标准路径可能会在版本之间发生变化。
Lua 5.2和Lua 5.3的主要区别在于引入了数字的整数子类型。尽管这种改变不应该影响“正常”的计算,但一些计算(主要是那些涉及某种溢出的计算)可以给出不同的结果。你可以通过强制一个数字成为一个浮点数来解决这些差异(在Lua 5.2中所有的数字都是浮点数),特别是用常量结尾.0
或x = x + 0.0
用来转换变量。(这个建议仅仅是为了偶尔的不兼容性的一个快速修复;它不是一个好的编程的一般指导。对于良好的编程,在需要浮点数和整数的地方使用浮点数,在需要整数的地方。)
如果float .0
看起来像一个整数,现在将float转换为字符串会为结果添加后缀。(例如,float 2.0将被打印为2.0
,而不是)2
。当您需要数字的特定格式时,您应始终使用明确的格式。(形式上这不是不兼容,因为Lua没有指定数字如何被格式化为字符串,但是某些程序采用了特定的格式。)
垃圾收集器的世代模式被删除。(这是Lua 5.2中的一个实验性功能。)
该bit32
图书馆已被弃用。很容易要求兼容的外部库,或者更好的是用适当的按位操作替换它的功能。(请记住,bit32
在32位整数上运行,而Lua 5.3中的按位运算符在Lua整数上运行,默认情况下有64位)。
表格库现在支持用于设置和获取元素的元方法。
该ipairs
迭代器现在尊重元方法及其__ipairs
元方法已被弃用。
选项名称中io.read
没有起始' *
'了。为了兼容性,Lua将继续接受(并忽略)这个角色。
下面的功能已废弃的数学库:atan2
,cosh
,sinh
,tanh
,pow
,frexp
,和ldexp
。您可以替换math.pow(x,y)
使用x^y
; 你可以math.atan2
用math.atan
它替换,现在可以接受一个或两个参数; 你可以math.ldexp(x,exp)
用x * 2.0^exp
。替换。对于其他操作,您可以使用外部库或在Lua中实施它们。
C装载器的搜索者require
改变了它处理版本名称的方式。现在,版本应该在模块名称之后(正如大多数其他工具一样)。为了兼容性,如果根据新样式找不到打开的函数,那么该搜索器仍会尝试旧格式。(Lua 5.2已经以这种方式工作,但它没有记录变化。)
该调用collectgarbage("count")
现在只返回一个结果。(您可以从第一个结果的小数部分计算出第二个结果。)
继续功能现在接收作为参数他们需要通过lua_getctx
,因此lua_getctx
已被删除。相应地调整您的代码。
函数lua_dump
有一个额外的参数,strip
。使用0作为此参数的值来获取旧的行为。
功能注入/项目无符号整数(lua_pushunsigned
,lua_tounsigned
,lua_tounsignedx
,luaL_checkunsigned
,luaL_optunsigned
)就被抛弃了。在类型转换中使用他们的签名等价物。
宏项目非默认的整数类型(luaL_checkint
,luaL_optint
,luaL_checklong
,luaL_optlong
)就被抛弃了。使用lua_Integer
类型转换(或者,如果可能,请lua_Integer
在代码中使用)。
这里是扩展BNF中Lua的完整语法。与扩展的BNF一样,{A}表示0或更多的As,A表示一个可选的A.(对于运算符优先级,请参阅§3.4.8;有关终端名称,数字和LiteralString的描述,请参阅§3.1。 )
chunk ::= block block ::= {stat} [retstat]stat ::= ‘;’ | varlist ‘=’ explist | functioncall | label | break | goto Name | 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 explist do block end | function funcname funcbody | local function Name funcbody | local namelist [‘=’ explist] retstat ::= return [explist] [‘;’]label ::= ‘::’ Name ‘::’ funcname ::= Name {‘.’ Name} [‘:’ Name]varlist ::= var {‘,’ var}var ::= Name | prefixexp ‘[’ exp ‘]’ | prefixexp ‘.’ Name namelist ::= Name {‘,’ Name}explist ::= exp {‘,’ exp}exp ::= nil | false | true | Numeral | LiteralString | ‘...’ | functiondef | prefixexp | tableconstructor | exp binop exp | unop exp prefixexp ::= var | functioncall | ‘(’ exp ‘)’ functioncall ::= prefixexp args | prefixexp ‘:’ Name args args ::= ‘(’ [explist] ‘)’ | tableconstructor | LiteralString functiondef ::= function funcbody funcbody ::= ‘(’ [parlist] ‘)’ block end parlist ::= namelist [‘,’ ‘...’] | ‘...’ tableconstructor ::= ‘{’ [fieldlist] ‘}’ fieldlist ::= field {fieldsep field} [fieldsep]field ::= ‘[’ exp ‘]’ ‘=’ exp | Name ‘=’ exp | exp fieldsep ::= ‘,’ | ‘;’ binop ::= ‘+’ | ‘-’ | ‘*’ | ‘/’ | ‘//’ | ‘^’ | ‘%’ | ‘&’ | ‘~’ | ‘|’ | ‘>>’ | ‘<<’ | ‘..’ | ‘<’ | ‘<=’ | ‘>’ | ‘>=’ | ‘==’ | ‘~=’ | and | or unop ::= ‘-’ | not | ‘#’ | ‘~’