2.15. Lua 脚本

内容

1. 介绍

2. 所需 DLL

3. Double Commander 函数库

3.1. DC 库

3.1.1. DC.ExecuteCommand 使用示例

3.2. 系统库

3.2.1. SysUtils.FileGetAttr 返回值详情

3.2.2. SysUtils.FileGetAttr 使用示例

3.2.3. 使用 FindFirst、FindNext 和 FindClose 的示例

3.3. 剪贴板库

3.3.1. 剪贴板库使用示例

3.4. 对话框库

3.4.1. Dialogs.MessageBox 中显示的按钮

3.4.2. Dialogs.MessageBox 的窗口样式

3.4.3. Dialogs.MessageBox 的默认活动按钮

3.4.4. Dialogs.MessageBox 的返回值

3.4.5. Dialogs.MessageBox 使用示例

3.4.6. Dialogs.InputQuery 使用示例

3.5. UTF-8 库

3.6. 字符库

3.7. 操作系统库

4. 索引

1. 介绍

有关 Lua 脚本编程语言的详细信息，请访问 Lua 网站。

Double Commander 可以通过 cm_ExecuteScript 命令执行 Lua 脚本。
脚本参数必须按原样传递，无需转义（无需引号或“\”），为此我们需要使用 %"0 变量：例如，对于光标下的文件使用 %"0%p0 而不是 %p0，对于当前目录使用 %"0%D 而不是 %D。否则，如果 Double Commander 自动添加引号，它们将作为参数的一部分传递，您将不得不考虑这一点。
要获取所有选定文件的列表，我们可以使用 变量（%LU、%FU 或 %RU）或内部命令（cm_SaveSelectionToFile、cm_SaveFileDetailsToFile、cm_CopyFullNamesToClip 或 cm_CopyFileDetailsToClip）。 例如，我们可以使用 %p：在这种情况下，Double Commander 将在一行中传递所有选定文件的名称，用空格分隔名称。

也可以使用 Lua 脚本编写内容插件，示例可以在程序文件夹中找到（plugins/wdx/scripts）。 Wiki 上有一个专门用于编写插件的页面。 限制：仅支持以下数据类型

• ft_numeric_32 (1) – 32位有符号数字；
• ft_numeric_64 (2) – 64位有符号数字；
• ft_numeric_floating (3) – 浮点数；
• ft_boolean (6) – 布尔类型：true 或 false；
• ft_multiplechoice (7) – 允许有限选择数量的值；
• ft_string (8) – 文本字符串；
• ft_fulltext (9) – 全文（多个文本字符串），仅用于插件搜索；
• ft_datetime (10) – 日期/时间：返回的日期将转换为格式化的日期和时间字符串（值取决于您的区域设置）。
  日期必须采用 Windows 格式，但 Lua 和 Double Commander 提供的用于搜索文件的函数使用 Unix 时间格式。要进行转换，可以使用以下公式：
  = UnixTime * 10000000 + 116444736000000000
  这是一个大数字，因此您需要 64 位版本的 Double Commander 或 Lua 5.3+。

上面的列表包含头文件中的名称，在 Lua 脚本中我们必须使用括号中指定的数值。

关于文本编码

下面描述的所有附加函数都接受 UTF-8 编码的字符串参数并返回此编码的字符串（LazUtf8.ConvertEncoding 函数除外）。

一些标准 Lua 库中的函数已被 Double Commander 或 Free Pascal/Lazarus 的函数替换（或编写了新函数），这提供了 UTF-8 支持。

编写插件时，我们也应该对文本数据使用 UTF-8（ft_multiplechoice、ft_string 和 ft_fulltext）。

保存脚本时，请使用不带 BOM 的 UTF-8 编码。

注意事项

使用 Lua 进行自动化具有很大的可能性，但在某些情况下可能需要注意一些细节。让我们尝试在本小节中收集这些内容。

1. 如果启用了自动刷新和在单独线程中加载文件列表选项，刷新功能将异步工作。同时，脚本在 Double Commander 的主线程中执行，因此在某些情况下，所有这些都可能影响您的脚本运行。例如，有时连续执行导航命令可能不起作用（例如，大目录、慢速磁盘），在这种情况下，请尝试禁用在单独线程中加载文件列表或寻找替代解决方案。

如果您的脚本在当前面板中创建新文件或重命名现有文件，但随后未完成并执行一些附加操作（例如，选择文件或移动光标），则在某些情况下这些操作将不会生效：并非所有文件都可能已在面板中，您需要首先调用cm_Refresh命令。在所述条件下，cm_Refresh也将异步执行，Double Commander 可能没有时间在您的更改后完全刷新文件列表。

自动刷新和在单独线程中加载文件列表是文件管理器的便捷功能，因此通过实验找到了稳定的工作方法，即暂时将控制权返回给程序并允许文件列表完全刷新：

DC.ExecuteCommand("cm_Refresh")
i = 10
while i > 0 do
  SysUtils.Sleep(10)
  DC.ExecuteCommand("")
  i = i - 1
end

2. Lua 函数 io.open 使用标准 C 函数 fopen：在文本模式下，此函数在读取和写入时可以转换行尾类型（CRLF、LF 或 CR），这可能导致意外结果。如果您遇到具有不同行尾类型的文件或正在编写跨平台脚本，则必须考虑这一点，或者更实际的做法是优先使用二进制模式。

3. 在 Linux 和其他类 Unix 操作系统中，对于文件属性对话框，调用 ContentGetValue 函数时带有 CONTENT_DELAYIFSLOW 标志（第四个参数，值为 1），这避免了打开窗口时的延迟：如果数据检索缓慢，我们可以通过简单地添加标志值检查并为这些字段或插件返回 nil 来排除这些数据。

4. 如果插件应该返回空字符串，则传递 nil 比传递 "" 更快。

（回到顶部）

2. 所需 DLL

为了能够解释 Lua 脚本文件，我们需要一个 Lua DLL 文件，Double Commander 支持 5.1 - 5.4 版本。

我们可以使用来自 LuaJIT 项目 的 DLL 文件。LuaJIT 结合了一个用汇编编写的高速解释器和一个先进的 JIT 编译器。此外，我们还获得了 FFI 库，它允许从纯 Lua 代码中调用外部 C 函数和使用 C 数据结构。

Windows 版本的 DC 默认包含 Lua DLL（在 DC 0.9.7 及更高版本中来自 LuaJIT 项目），在其他情况下，我们可以通过包管理器查找和安装它，或者自行编译。如果我们使用的是 64 位版本的 DC，则 DLL 也必须是 64 位版本。

默认情况下，DC 会在其目录和系统目录中查找名为 lua5.1.dll（Windows）、liblua5.1.so.0（Unix 或 GNU/Linux）或 liblua5.1.dylib（macOS）的文件。我们可以在 要使用的 Lua 库文件 参数中更改文件名（和路径）。

（回到顶部）

3. Double Commander 函数库

Double Commander 为我们的 Lua 脚本提供了一些函数库。

以下是这些库的列表。

（回到顶部）

3.1. DC 库

该库包含 Double Commander 特定的函数。

它在 DC 表中提供了所有函数。

除了内部命令之外，在脚本中我们还可以使用特殊命令 cm_ExecuteToolBarItem，该命令允许通过标识符调用工具栏按钮（在程序中，此功能提供了为工具栏按钮使用快捷键的功能）。该命令的使用方式与普通内部命令类似（见下面的示例），并且具有以下参数：

唯一标识符存储在 ID 标签中，我们有几种方式可以获取它：可以在 doublecmd.xml 文件、工具栏备份文件中找到按钮，或者简单地将按钮复制到剪贴板并在文本编辑器中粘贴其代码。

注意：标识符是自动生成的，不必与程序另一个副本中的类似按钮的标识符匹配，但如有必要，我们可以手动设置自己的值。

（回到顶部）

3.1.1. 使用 DC.ExecuteCommand 的示例

在这个示例中，我们编写了一个简单的脚本，它将执行以下操作：

1. 聚焦到右侧面板
2. 关闭所有打开的标签页
3. 切换到特定文件夹
4. 聚焦到左侧面板
5. 关闭所有打开的标签页
6. 切换到特定文件夹
7. 打开新标签页
8. 切换到特定文件夹

-- 1. 聚焦到右侧面板。
DC.ExecuteCommand("cm_FocusSwap", "side=right")

-- 2. 关闭所有标签页。
DC.ExecuteCommand("cm_CloseAllTabs")

-- 3. 切换到特定目录。
DC.ExecuteCommand("cm_ChangeDir", "E:\\FakeKey\\Documents\\Music")

-- 4. 聚焦到左侧面板。
DC.ExecuteCommand("cm_FocusSwap", "side=left")

-- 5. 关闭所有标签页。
DC.ExecuteCommand("cm_CloseAllTabs")

-- 6. 切换到特定目录。
DC.ExecuteCommand("cm_ChangeDir", "C:\\Users\\Public\\Music")

-- 7. 打开新标签页。
DC.ExecuteCommand("cm_NewTab")

-- 8. 切换到特定目录。
DC.ExecuteCommand("cm_ChangeDir", "E:\\VirtualMachines\\ShareFolder")

使用内部命令 cm_ExecuteScript，我们可以配置一个工具栏按钮来执行我们的脚本。

假设此脚本文件是 E:\scripts\lua\music.lua，我们可以这样配置按钮：

此外，我们还可以使用 Double Commander 内部编辑器来编辑脚本。如果文件名具有 .lua 扩展名，内部编辑器将识别它并提供针对 Lua 语言的语法高亮显示：

（回到顶部）

3.2. 系统库

该库包含各种系统函数。

它在 SysUtils 表中提供了所有函数。

（回到顶部）

3.2.1. SysUtils.FileGetAttr 返回值详情

FileGetAttr 返回文件 sFileName 的属性设置。

属性是以下常量的 OR 组合：

请参见下一节中的示例。

（回到顶部）

3.2.2. SysUtils.FileGetAttr 使用示例

以下脚本是 SysUtils.FileGetAttr 用法的一个示例。

当检测到参数是目录时，它将在活动面板中打开一个新标签页并切换到该目录。

local params = {...}
local iAttr

if #params == 1 then -- 我们至少得到了一个参数？
  iAttr = SysUtils.FileGetAttr(params[1])
  if iAttr > 0 then -- 我们得到了一个有效的属性？
    if math.floor(iAttr / 0x00000010) % 2 ~= 0 then
      -- 第4位被设置？所以它是一个目录。
      DC.ExecuteCommand("cm_NewTab")
      DC.ExecuteCommand("cm_ChangeDir", params[1])
    end
  end
end

在上面的例子中，params[1] 是传递给脚本的第一个参数。

当使用内部命令 cm_ExecuteScript 时，它将是脚本文件名后传递的第一个参数。

因此，在我们的示例中，我们可以像下面这样配置一个工具栏按钮：

在这个例子中，参数 %"0%p 将被传递给脚本。这将代表未加引号的当前活动面板中选中项目的文件名。

（回到顶部）

3.2.3. 使用 FindFirst、FindNext 和 FindClose 的示例

在以下脚本示例中，我们将扫描参数中接收的目录内容，并将结果数据存储到以第二个参数传递的文件名的文本文件中。

这将让我们很好地了解 FindFirst、FindNext 和 FindClose 的用法。

local params = {...}

if #params == 2 then -- 我们得到了两个参数？
  local Result = nil
  local hOutputFile = nil

  hOutputFile = io.output(params[2])

  local Handle, FindData = SysUtils.FindFirst(params[1] .. "\\*")
  if Handle ~= nil then
    repeat
      io.write(FindData.Name .. "\r")
      io.write(FindData.Size .. "\r")
      io.write("---------------\r")

      Result, FindData = SysUtils.FindNext(Handle)
    until Result == nil

    SysUtils.FindClose(Handle)
    io.close(hOutputFile)
  end
end

在上面的例子中，我们需要向脚本传递两个参数：

1. params[1] - 我们想要内容的目录
2. params[2] - 用于存储结果的输出文件名

因此，使用内部命令 cm_ExecuteScript 配置工具栏按钮并传递参数来完成这一切是很容易的。

在这个例子中，参数 %"0%Ds 将作为第一个参数传递给脚本。这将代表未加引号的活动面板显示的目录。

（回到顶部）

3.3. 剪贴板库

Double Commander 可以为我们的 Lua 脚本提供外部剪贴板功能。

下表给出了相关的函数：

（回到顶部）

3.3.1. 剪贴板库使用示例

以下示例使用了与剪贴板相关的三个函数：Clear、GetAsText 和 SetAsText。

这是一个相对较长的脚本，但它很好地将上面看到的一些函数组合在一起。

它假设我们的活动面板当前位于一个包含许多源文本文件的目录中。

它还假设我们当前在剪贴板中有一个单词，并且它将接收当前活动文件夹作为单个参数。

脚本将扫描当前目录级别的文件，并逐个读取它们的内容，以检测包含剪贴板中单词的文本行。

然后，包含至少一行该单词的文件名将被放置到剪贴板中。

然后，脚本将使用内部命令 cm_LoadSelectionFromClip，包含该单词的文件将被选中。

此外，在最后，我们将把需要搜索的原始单词放回剪贴板中。

local params = {...}
local Result = nil
local iAttr
local bFound = false
local sCompleteFilename = ""
local hInputFile = nil
local sLine = ""
local iPosS
local iPosE
local sFileToSelect = ""
local sSearchString = ""

if #params == 1 then -- 我们得到了参数？
  sSearchString = Clipbrd.GetAsText() -- 获取要搜索的表达式。
  Clipbrd.Clear() -- 确保剪贴板中没有任何内容。
  DC.ExecuteCommand("cm_MarkUnmarkAll") -- 确保没有选中任何内容。

  -- 让我们逐个扫描目录中的所有文件。
  local Handle, FindData = SysUtils.FindFirst(params[1] .. "\\*")
  if Handle ~= nil then
    repeat
      sCompleteFilename = params[1] .. "\\" .. FindData.Name
      iAttr = SysUtils.FileGetAttr(sCompleteFilename)
      if iAttr > 0 then -- 我们得到了一个有效的属性？
        -- 我们需要文件，而不是目录！
        if math.floor(iAttr / 0x00000010) % 2 == 0 then

          -- 现在让我们逐行读取文件，直到结束或找到。
          hInputFile = io.open(sCompleteFilename, "r")
          bFound = false

          while bFound == false do
            sLine = hInputFile:read()
            if sLine == nil then break end
            iPosS, iPosE = string.find(sLine, sSearchString)
            if iPosS ~= nil then bFound = true end
          end

          if bFound == true then
            sFileToSelect = sFileToSelect .. FindData.Name .. "\n"
          end

          io.close(hInputFile)
        end
      end
      Result, FindData = SysUtils.FindNext(Handle)
    until Result == nil

    SysUtils.FindClose(Handle)
  end

  -- 如果我们找到了什么，就选中它！
  if sFileToSelect ~= "" then
    Clipbrd.SetAsText(sFileToSelect)
    DC.ExecuteCommand("cm_LoadSelectionFromClip")
  end

  Clipbrd.SetAsText(sSearchString) -- 恢复我们在剪贴板中的内容。
end

（回到顶部）

3.4. 对话框库

该库允许我们的脚本与用户交互，显示消息、提示输入答案等。

下表列出了相关函数：

（回到顶部）

3.4.1. Dialogs.MessageBox 中显示的按钮

Dialogs.MessageBox 函数显示的按钮由以下常量的按位或值控制：

Dialogs.MessageBox 显示按钮的 ButFlags 常量
常量值	显示的按钮，从左到右
0x0000 MB_OK
0x0001 MB_OKCANCEL
0x0002 MB_ABORTRETRYIGNORE
0x0003 MB_YESNOCANCEL
0x0004 MB_YESNO
0x0005 MB_RETRYCANCEL

（回到顶部）

3.4.2. Dialogs.MessageBox 的窗口样式

Dialogs.MessageBox 函数显示的窗口样式由以下常量的按位或值控制：

Dialogs.MessageBox 图标和样式的 ButFlags 常量
常量值	窗口样式
0x0040 MB_ICONINFORMATION	信息窗口
0x0030 MB_ICONWARNING	警告窗口
0x0020 MB_ICONQUESTION	确认窗口
0x0010 MB_ICONERROR	错误窗口

（回到顶部）

3.4.3. Dialogs.MessageBox 的默认活动按钮

Dialogs.MessageBox 函数显示的默认活动按钮由以下常量的按位或值控制：

（回到顶部）

3.4.4. Dialogs.MessageBox 的返回值

Dialogs.MessageBox 函数返回的数字表示用户按下的按钮，如下所示：

Dialogs.MessageBox 按钮按下时返回的 ButPressed 值
常量值	按下的按钮
0x0000 mrNone	未按下任何按钮
0x0001 mrOK
0x0002 mrCancel
0x0003 mrAbort
0x0004 mrRetry
0x0005 mrIgnore
0x0006 mrYes
0x0007 mrNo

注意：如果按下右上角的“x”或按 Esc 关闭窗口，则将返回“取消”按钮的值。

（回到顶部）

3.4.5. Dialogs.MessageBox 使用示例

以下是一个使用 Dialogs.MessageBox 的小脚本以及将显示的结果窗口：

-- 显示的按钮
MB_OK = 0x0000
MB_OKCANCEL = 0x0001
MB_ABORTRETRYIGNORE = 0x0002
MB_YESNOCANCEL = 0x0003
MB_YESNO = 0x0004
MB_RETRYCANCEL = 0x0005

-- 窗口样式
MB_ICONINFORMATION = 0x0040
MB_ICONWARNING = 0x0030
MB_ICONQUESTION = 0x0020
MB_ICONERROR = 0x0010

-- 默认按钮
MB_DEFBUTTON1 = 0x0000
MB_DEFBUTTON2 = 0x0100
MB_DEFBUTTON3 = 0x0200

-- 返回按下的按钮
mrNone = 0x0000
mrOK = 0x0001
mrCancel = 0x0002
mrAbort = 0x0003
mrRetry = 0x0004
mrIgnore = 0x0005
mrYes = 0x0006
mrNo = 0x0007

iFlags = MB_YESNO + MB_ICONQUESTION + MB_DEFBUTTON2
iButton = Dialogs.MessageBox("您想要退出吗？", "问题", iFlags)

if iButton == mrYes then
  DC.ExecuteCommand("cm_Exit")
end

（回到顶部）

3.4.6. Dialogs.InputQuery 使用示例

以下是一个使用 Dialogs.InputQuery 的小脚本以及将显示的结果窗口：

bResult, sAnswer = Dialogs.InputQuery("身份验证", "请输入您的姓名：", false, "约翰")

if bResult == true then
  Dialogs.MessageBox("您好 " .. sAnswer .. "！", "欢迎！", 0x0040)
end

（回到顶部）

3.5. UTF-8 库

该库提供对 UTF-8 编码的基本支持。

它在 LazUtf8 表中提供了所有函数。

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

（回到顶部）

3.6. 字符库

该库包含用于检查字符是否属于特定 Unicode 类别的函数，以及获取字符类别的函数。

该库中可用函数的列表：

此外，这些函数支持使用两个参数：我们可以指定一个字符串和该字符串中字符的位置，而不是单个字符。

（回到顶部）

3.7. 操作系统库

该库包含与 Double Commander 运行所在的操作系统相关的函数。

以下是该库中可用函数的列表：

（回到顶部）

4. 索引

（回到顶部）