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. 索引

（回到頂部）   it365工具箱