2.15. Lua 脚本

DC.LogWrite(sMessage, iMsgType, bForce, bLogFile)

向日志窗口写入一条消息：

• sMessage : 要写入日志的消息文本。
• iMsgType : 消息类型：0 - 信息，1 - 成功，2 - 错误。
• bForce : 布尔值，若为 true，则在日志窗口不可见时强制显示该窗口。
• bLogFile : 布尔值，若为 true，则同时将消息写入日志文件。

Double Commander 用于写入日志的内部函数采用异步工作方式（请参阅简介中的说明），因此通过 DC.LogWrite 写入的消息不会立即记录到日志中，而是在脚本运行结束后才写入。若需要立即写入日志消息，可在 DC.LogWrite 后尝试调用 DC.ExecuteCommand("") 来实现。

iPanel = DC.CurrentPanel()

获取活动面板：如果左侧面板是活动的返回 0，右侧返回 1。

DC.CurrentPanel(iPanel)

设置活动面板：当 iPanel 为 0 时切换到左侧面板，为 1 时切换到右侧面板。

DC.ExecuteCommand(sCommand, Param1, Param2,...,ParamX)

允许脚本调用 Double Commander 的 内部命令。

sCommand 为内部命令的名称。

可以按需提供多个 Param... 参数，具体取决于命令支持的参数数量。

DC.GoToFile(sFileName, bActive)

打开 sFileName 文件所在的目录并将光标定位到 sFileName 文件。要打开目录，请使用 cm_ChangeDir 命令，或尝试在 sFileName 后添加目录分隔符和".."（不含引号）。

bActive —— 此为可选参数：函数可在活动文件面板（true）或非活动面板（false）中运行。默认值为true。

Result = DC.GetPluginField(sFileName, sPlugin, iField, iUnit)

允许通过已安装的信息（或内容）插件（WDX）获取数据：

• sFileName：文件的完整（绝对）名称。
• sPlugin：插件名称，需与对应 插件配置 中保存的名称一致。
• iField：插件字段索引（从0开始计数）。
• iUnit：计量单位索引（从0开始计数）；如果不存在请指定0。
• Result：返回值：可返回有符号整数（包括Unix时间格式）、浮点数、布尔值、字符串或 nil 。

sResult = DC.ExpandVar(String)

返回将其中所有变量替换为其对应值的字符串（环境变量除外，处理环境变量请使用SysUtils.ExpandEnv）。

SysUtils.Sleep(iMilliseconds)

暂停脚本执行指定的 iMilliseconds 毫秒。
到期后继续执行脚本。

SysUtils.GetTickCount()

返回递增的时钟滴答计数，可用于时间测量，但不应对滴答间隔作严格假设。

bExists = SysUtils.FileExists(sFileName)

检查指定文件是否存在于文件系统中。

如果磁盘上存在名为 sFileName 的文件，则在 bExists 中返回 true，否则返回 false。

bExists = SysUtils.DirectoryExists(sDirectory)

检查 sDirectory 是否存在且确为目录。

若是则返回 bExists 为 true，否则返回 false。

iAttr = SysUtils.FileGetAttr(sFileName)

在 iAttr 中返回文件 sFileName 的属性设置。

有关返回值的详细说明见 此处。

Handle, FindData = SysUtils.FindFirst(sPath)

查找匹配 sPath（通常包含通配符）的文件。

如果未找到任何文件，Handle 将为 nil。

如果找到至少一个项目，返回的 Handle 可用于随后的 SysUtils.FindNext 来查找同一模式的其他匹配项。

FindData 表包含有关找到的文件或目录的信息。

FindData 表的字段包括：

• Name ：文件名（不含路径）。
• Attr ：文件属性（详见 此处）。
• Size ：文件大小（字节）。
• Time ：文件时间戳（自 1970 年 1 月 1 日起的秒数）。

Result, FindData = SysUtils.FindNext(Handle)

使用之前返回的 Handle 查找由 FindFirst 发起的搜索序列的下一个匹配项。

如果找到文件或目录，返回的 Result 将非 nil，否则为 nil。

关于 SysUtils.FindFirst 的说明同样适用于此函数。

注意： 每次最后的 SysUtils.FindNext 调用必须配对一次 SysUtils.FindClose（传入相同的 Handle），否则会造成内存泄漏。

SysUtils.FindClose(Handle)

结束一系列 SysUtils.FindFirst/SysUtils.FindNext 调用。

释放这些调用占用的内存。

务必调用此函数，否则可能会发生内存泄漏。

bResult = SysUtils.CreateDirectory(sDirectory)

创建目录链，sDirectory 为目标目录的完整路径。

如果目录已存在或创建成功则返回 true，如任一部分创建失败则返回 false。

bResult = SysUtils.RemoveDirectory(sDirectory)

删除名为 sDirectory 的目录。成功时返回 true ，否则返回 false 。

与 os.remove 不同，此函数在出错时不会返回错误描述，但能够删除非空目录。

bResult = SysUtils.CreateHardLink(sFileName, sLinkName)

为文件 sFileName 创建硬链接 sLinkName。

成功返回 true，失败返回 false。

bResult = SysUtils.CreateSymbolicLink(sFileName, sLinkName)

为文件或目录 sFileName 创建符号链接 sLinkName。

成功返回 true，失败返回 false。

sTarget = SysUtils.ReadSymbolicLink(sLinkName, bRecursive)

读取符号链接 sLinkName 的目标路径。

如果 bRecursive 为 true，且目标仍为链接，则会递归解析直到得到非链接的有效路径。

返回符号链接指向的路径；当链接无效或目标不存在且 bRecursive 为 true 时返回空字符串。

sName = SysUtils.ExtractFileName(sFileName)

从完整路径中提取文件名部分。

文件名为最后一个目录分隔符（"/" 或 "\"）或盘符之后的所有字符。

sExt = SysUtils.ExtractFileExt(sFileName)

返回文件的扩展名（最后一个点之后的所有字符，包含点字符）。

sPath = SysUtils.ExtractFilePath(sFileName)

从文件名中提取路径部分（包含盘符）。

路径为最后一个目录分隔符（"/" 或 "\"）之前的所有字符，包含该分隔符本身。

sDir = SysUtils.ExtractFileDir(sFileName)

仅提取 sFileName 的目录部分，包含盘符。

该目录名不包含结尾的目录分隔符，这点不同于 SysUtils.ExtractFilePath。

sDrive = SysUtils.ExtractFileDrive(sFileName)

从文件名中提取盘符部分。

注意，某些操作系统不支持盘符概念。

sName = SysUtils.GetAbsolutePath(sFileName, sBaseDirectory)

返回文件的绝对（完整）路径：

• sFileName : 带相对路径的文件名。
• sBaseDirectory : 用作 sFileName 基准的目录。

如果无法获得绝对路径，函数将返回原始的 sFileName 值。

sName = SysUtils.GetRelativePath(sFileName, sBaseDirectory)

返回相对于指定目录的文件名：

• sFileName : 完整的（绝对）文件名。
• sBaseDirectory : 用作 sFileName 基准的目录。

如果 sFileName 与 sBaseDirectory 相同，函数将返回空字符串（""）。若无法计算相对路径，则返回原始的 sFileName 值。

bResult = SysUtils.MatchesMask(sFileName, sMask, iMaskOptions)

如果 sFileName 与给定掩码 sMask 匹配则返回 true。

iMaskOptions（可选，默认值 0）由以下值相加而成：

bResult = SysUtils.MatchesMaskList(sFileName, sMaskList, sSeparator, iMaskOptions)

如果 sFileName 与以 sSeparator 分隔的掩码列表 sMaskList 中的任一项匹配，则返回 true（默认分隔符为 ";"）。

sSeparator and iMaskOptions (see above) are optional parameters.

bResult = SysUtils.Execute(sCommand)

执行 sCommand 命令，类似于在命令行中输入命令。成功时返回 true ，否则返回 false （该函数不会等待启动的命令执行完毕）。

注意：在 Windows 系统中，使用 os.execute 函数每次都会打开终端窗口，而 SysUtils.Execute 函数则无此问题。

sResult = SysUtils.ExpandEnv(String, bSpecial)

返回将其中所有环境变量替换为当前用户对应值的字符串。

bSpecial —— 此为可选参数：若为 true ，则同时会展开伪环境变量（详见 此处 说明）。默认值为 false 。

sTempFileName = SysUtils.GetTempName()

返回一个可用作临时文件的文件名（位于系统临时文件目录中），类似于 os.tmpname 函数，但文件将创建在 _dc~~~ 子目录下，该子目录会在 Double Commander 关闭时自动删除。
如果函数无法创建唯一名称，则将返回空字符串。

Result = SysUtils.GetFileProperty(sFileName, iValue)

返回与 iValue 对应的文件属性：

返回数值（文件大小、时间戳）或字符串（其他情况）。如果操作失败，函数返回 nil 。

bResult = SysUtils.FileSetTime(sFileName, iModification, iCreation, iLastAccess)

允许为 sFileName 设置时间戳（Unix时间格式）：修改时间、创建时间和最后访问时间。对于需要忽略的时间戳，请指定为零。

成功时返回 true ，否则返回 false 。

SysUtils.PathDelim

当前操作系统用于分隔路径中目录名称的字符。

在 Unix/Linux 系统上为 "/"，在 Windows 上为 "\"。

Clipbrd.Clear()

清空剪贴板内容。

sVar = Clipbrd.GetAsText()

获取剪贴板当前的文本内容并返回到 sVar。如果剪贴板不包含文本，则返回空字符串。

Clipbrd.SetAsText(sVar)

将字符串 sVar 的文本内容存入剪贴板。

Clipbrd.SetAsHtml(sHtml)

将 HTML 格式的文本 sHtml 添加到剪贴板（采用 CF_HTML 剪贴板格式）。

支持该剪贴板格式的应用（如 MS Word、LibreOffice Writer 等）在粘贴时会使用该格式。

可以同时使用 Clipbrd.SetAsText 和 Clipbrd.SetAsHtml 保存数据，粘贴时应用会选择其支持的最佳格式。

例如：

• Clipbrd.SetAsText("Welcome to Double Commander!")
• Clipbrd.SetAsHtml("Welcome to <b>Double Commander</b>!")

如果在记事本中粘贴，将得到纯文本（由 Clipbrd.SetAsText 提供）；但在 Microsoft Word 中粘贴时，会使用 HTML 格式并显示加粗的 Double Commander。

iButton = Dialogs.MessageBox(sMessage, sTitle, iFlags)

显示一个消息框，用户按下的按钮会作为返回值返回：

• sMessage：消息框中的文本。
• sTitle：消息框的标题文本。
• iFlags：按位或的常量值，用于控制显示哪些按钮、窗口样式和默认按钮。参见下面关于 显示按钮、窗口样式 与 默认按钮 的说明。
• iButton：返回值，表示用户按下的按钮（见 返回值表）。

bResult, sAnswer = Dialogs.InputQuery(sTitle, sMessage, bMask, sDefault)

显示一个请求输入的对话框，用户可以输入字符串值：

• sTitle：对话框标题。
• sMessage：对话框中的提示信息。
• bMask：布尔值，若为 true，则以“星号”隐藏输入字符（用于密码输入）。
• sDefault：默认建议值，用户可在此基础上编辑。
• bResult：返回的布尔值，指示用户是否实际输入并确认。
• sAnswer：当用户输入并点击确定时返回的字符串，否则为 nil 或空。

sItem, iItem = Dialogs.InputListBox(sTitle, sMessage, aItems, sDefault)

显示一个供用户从列表中选择的对话框：

• sTitle：对话框标题。
• sMessage：对话框中的说明文本。
• aItems：一个 Lua 表，每个元素应为字符串，表示列表项。
• sDefault：列表中默认选中的项。
• sItem：返回所选项的字符串，若取消则返回 nil。
• iItem：所选项的索引（从 1 开始，符合 Lua 表的惯例）。

iResult = LazUtf8.Pos(SearchText, SourceText, Offset)

在字符串中从指定位置查找子串，区分大小写。

返回从位置 Offset（默认 1）开始在 SourceText 中首次出现 SearchText 的位置。

若在指定位置之后未找到子串，则返回 0。

LazUtf8.Next(String)

一个迭代器函数，每次调用返回字符串 String 中的下一个字符及该字符在字节流中的起始位置。

示例：

-- 以“位置 : 字符”的形式打印数值对
for iPos, sChar in LazUtf8.Next(String) do
  DC.LogWrite(iPos .. " : " .. sChar)
end

sResult = LazUtf8.Copy(String, iIndex, iCount)

复制字符串的一部分。

返回从位置 iIndex 开始的 iCount 个字符组成的新字符串。

若 iCount 大于字符串长度则会截断；若 iIndex 超出字符串长度则返回空字符串。

iResult = LazUtf8.Length(String)

返回字符串中 UTF-8 字符的个数（字符数，而非字节数）。

sResult = LazUtf8.UpperCase(String)

把字符串中的小写字母转换为大写并返回转换后的字符串副本。

sResult = LazUtf8.LowerCase(String)

把字符串中的大写字母转换为小写并返回转换后的字符串副本。

sResult = LazUtf8.ConvertEncoding(String, FromEnc, ToEnc)

将 String 的编码从 FromEnc 转换为 ToEnc。

支持的编码列表：

• 默认系统编码（取决于系统区域设置）："default"。
• 默认 ANSI（Windows）编码（取决于系统区域设置）："ansi"。
• 默认 OEM（DOS）编码（取决于系统区域设置）："oem"。
• Unicode："utf8"，"utf8bom"，"ucs2le"，"ucs2be"。
• ANSI (Windows)："cp1250", "cp1251", "cp1252", "cp1253", "cp1254", "cp1255", "cp1256", "cp1257", "cp1258"。
• OEM (DOS)："cp437", "cp850", "cp852", "cp865", "cp866", "cp874", "cp932", "cp936", "cp949", "cp950"。
• ISO 8859："iso88591", "iso88592", "iso88593", "iso88594", "iso88595", "iso88597", "iso88599", "iso885910", "iso885913", "iso885914", "iso885915", "iso885916"。
• 其他: "macintosh", "koi8r", "koi8u", "koi8ru"。

• "默认" - cp1252 或 cp1251
• "ansi" - cp1252 或 cp1251
• "oem" - cp850 或 cp866

• "默认" - utf8
• "ansi" - cp1252 或 cp1251
• "oem" - cp850 或 cp866

sEnc = LazUtf8.DetectEncoding(String)

检测并返回传入文本的编码类型。支持的编码与 LazUtf8.ConvertEncoding 中列出的相同。

iResult = Char.GetUnicodeCategory(Character)

返回字符 Character 的 Unicode 类别，取值含义如下：

bResult = Char.IsDigit(Character)

如果 Character 属于十进制数字类别（Nd），则返回 true。

bResult = Char.IsLetter(Character)

如果 Character 属于字母类（Lu、Ll、Lt、Lm 或 Lo），则返回 true。

bResult = Char.IsLetterOrDigit(Character)

如果 Character 属于字母或数字类别（Lu、Ll、Lt、Lm、Lo、Nd 或 Nl），则返回 true。

bResult = Char.IsLower(Character)

如果 Character 属于小写字母类别（Ll），则返回 true。

bResult = Char.IsUpper(Character)

如果 Character 属于大写字母类别（Lu），则返回 true。

iResultCode = os.execute(sCommand)

在命令行中执行 sCommand，并返回操作的返回码。

sCommand 可以是：

• 终端命令，例如 os.execute("dir > all.txt")
• 可执行文件，例如 os.execute("C:\\Windows\\System32\\calc.exe")
• 带参数的可执行文件，例如：
  os.execute("C:\\Utils\\fsum.exe -md5 test.bin > md5.txt")

sTempFileName = os.tmpname()

返回一个可用于临时文件的文件名（位于系统临时目录）。若无法创建唯一名称，则返回空字符串。

bResult, sError, iError = os.remove(sFileName)

删除名为 sFileName 的文件或目录。

成功时函数返回 true；失败时函数返回三项：

1. nil 表示操作失败
2. sError：错误消息描述
3. iError：错误代码数字

bResult, sError, iError = os.rename(sOldName, sNewName)

将文件 sOldName 重命名为 sNewName。

注意： 若目标文件 sNewName 已存在，将被覆盖！

成功时返回 true；失败时返回三项（同 os.remove）：nil, sError, iError。

Value = os.getenv(VariableName)

返回环境变量 VariableName 的值；若该变量不存在，则返回 nil。

os.setenv(VariableName, Value)

添加或修改环境变量 VariableName 的值。发生错误时函数返回 -1。

os.unsetenv(VariableName)

移除环境变量 VariableName。发生错误时函数返回 -1。