2.15. Lua Scripting

Content

1. Introduction

2. DLL required

3. Double Commander functions libraries

3.1. DC library

3.1.1. Example with the DC.ExecuteCommand

3.2. System library

3.2.1. Details on SysUtils.FileGetAttr returned value

3.2.2. Example with SysUtils.FileGetAttr

3.2.3. Example using FindFirst, FindNext and FindClose

3.3. Clipboard library

3.3.1. Example of usage clipboard library

3.4. Dialogs library

3.4.1. Buttons displayed in Dialogs.MessageBox

3.4.2. Style of box of Dialogs.MessageBox

3.4.3. Default active button of Dialogs.MessageBox

3.4.4. Returned value of Dialogs.MessageBox

3.4.5. Example of usage of the Dialogs.MessageBox

3.4.6. Example of usage of the Dialogs.InputQuery

3.5. UTF-8 library

3.6. Char library

3.7. OS library

4. Index

1. Introduction

Detailed information about the Lua scripting programming language can be found on the Lua website.

Double Commander can execute Lua scripts via cm_ExecuteScript command.
Script parameters must be passed as is, without escaping (without quotes or "\"), for this we need to use the %"0 variable: for example, %"0%p0 for the file under cursor instead of %p0 or %"0%D for the current directory instead of %D. Otherwise, if Double Commander automatically adds quotes, they will be passed as part of the parameter and you will have to take them into account.
To get a list of all selected files we can use variables (%LU, %FU or %RU) or internal commands (cm_SaveSelectionToFile, cm_SaveFileDetailsToFile, cm_CopyFullNamesToClip or cm_CopyFileDetailsToClip). We can use, for example, %p: in this case, Double Commander will pass the names of all selected files in one line, separating the names with a space.

It is also possible to write content plugins using Lua script, examples can be found in the program folder (plugins/wdx/scripts). The Wiki has a page dedicated to writing plugins. Limitations: only the following data types are supported

• ft_numeric_32 (1) – a 32-bit signed number;
• ft_numeric_64 (2) – a 64-bit signed number;
• ft_numeric_floating (3) – a floating point number;
• ft_boolean (6) – boolean type: true or false;
• ft_multiplechoice (7) – a value allowing a limited number of choices;
• ft_string (8) – a text string;
• ft_fulltext (9) – a full text (multiple text strings), used only for searching with plugins ;
• ft_datetime (10) – for date/time: a returned date will be converted to a formatted date and time string (value depends on your regional settings).
  The date must be in Windows format, but Lua and the functions that Double Commander provides for searching files use Unix time format. To convert we can use the formula:
  = UnixTime * 10000000 + 116444736000000000
  This is a large number, so you will need a 64-bit version of Double Commander or Lua 5.3+.

The list above contains the names from the header files, in Lua scripts we must use the numeric values which are specified in parentheses.

About text encoding

All additional functions described below accept string parameters in UTF-8 encoding and return strings in this encoding (except for the LazUtf8.ConvertEncoding function).

Some functions from the standard Lua libraries have been replaced with functions from Double Commander or Free Pascal/Lazarus (or new ones have been written), this provides UTF-8 support.

When writing plugins, we should also use UTF-8 for text data (ft_multiplechoice, ft_string and ft_fulltext).

When saving scripts, use UTF-8 encoding without BOM.

Notes

Automation with Lua has great possibilities, but there may be nuances that in some cases need to be kept in mind. Let's try to collect them in this subsection.

1. If auto refresh and the Load file list in separate thread option are enabled, the refresh function will work asynchronously. At the same time, scripts are executed in the main thread of Double Commander and therefore, in some cases, all this may affect the operation of your script. For example, sometimes sequential execution of commands for navigation may not work (for example, large directories, slow disk), in this case try to disable Load file list in separate thread or look for an alternative solution.

If your script creates new files in the current panel or renames existing files, but then does not complete and performs some additional actions (for example, selecting files or moving the cursor), then in some cases these actions will not have an effect: not all files may be in the panel yet and you will need to first call the cm_Refresh command. Under the described conditions, cm_Refresh will also be executed asynchronously and Double Commander may not have time to completely refresh the list of files after your changes.

Auto-refreshing and loading the list of files in a separate thread are convenient functions for a file manager, so the stable working method was experimentally found to temporarily return control to the program and allow the file list to be completely refreshed:

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

2. Lua function io.open uses the standard C function fopen: in text mode, this function can convert the type of line endings (CRLF, LF or CR) when reading and writing and it can lead to unexpected results. If you come across files with different types of line endings or if you are writing a cross-platform script, this must be taken into account or it may be more practical to give preference to the binary mode.

3. For the file properties dialog in Linux and other Unix-like operating systems, the ContentGetValue function is called with the CONTENT_DELAYIFSLOW flag (the fourth parameter, the value is 1), this avoids the delay in opening the window: if data retrieval is slow, we can exclude this data by simply adding a flag value check and returning nil for such fields or plugin.

4. If the plugin should return an empty string, it will be faster to pass nil instead of "".

(back to top)

2. DLL required

In order to interpret Lua script file, we need to have a Lua DLL file, Double Commander supports versions 5.1 - 5.4.

By default DC looks for a file with name lua5.1.dll (Windows), liblua5.1.so.0 (Unix or GNU/Linux) or liblua5.1.dylib (macOS) in its directory and in the system directory. We can change the file name (and path) in the Lua library file to use parameter.

We can use DLL file from LuaJIT project. LuaJIT combines a high-speed interpreter, written in assembler, with a state-of-the-art JIT compiler. Also we get FFI library, which allows calling external C functions and using C data structures from pure Lua code.

DC distributives for Windows have Lua DLL by default (in DC 0.9.7 and newer from LuaJIT project), in other cases we may find and install it through our packages manager or compile it. If we're using a 64-bits version of DC, the DLL must be the 64-bits version as well.

(back to top)

3. Double Commander functions libraries

Double Commander offer a few libraries of functions for our Lua scripts.

Here is the list of them.

(back to top)

3.1. DC library

This library contains Double Commander specific functions.

It provides all its functions inside the table DC.

In addition to internal commands, in scripts we can use the special command cm_ExecuteToolBarItem, this command allows to call toolbar buttons by their identifier (in the program, this function provides the use of hotkeys for toolbar buttons). The command is used similarly to ordinary internal commands (see examples below) and has the following parameters:

The unique identifier is stored in the ID tag and we have several ways to get it: we can find the button in the doublecmd.xml file, in the toolbar backup file, or simply copy the button to the clipboard and paste its code into a text editor.

Note: Identifiers are generated automatically and do not have to match the identifiers of similar buttons in another copy of the program, but if necessary, we can manually set our own value.

(back to top)

3.1.1. Example with the DC.ExecuteCommand

In this example, we wrote a simple script that will do the following:

1. focus to right panel
2. close all opened tabs
3. switch to a specific folder
4. focus the left panel
5. close all opened tabs
6. switch to a specific folder
7. open a new tab
8. switch to a specific folder

-- 1. Focus on right panel.
DC.ExecuteCommand("cm_FocusSwap", "side=right")

-- 2. Close all tabs.
DC.ExecuteCommand("cm_CloseAllTabs")

-- 3. Switch to a specific directory.
DC.ExecuteCommand("cm_ChangeDir", "E:\\FakeKey\\Documents\\Music")

-- 4. Focus on left panel.
DC.ExecuteCommand("cm_FocusSwap", "side=left")

-- 5. Close all tabs.
DC.ExecuteCommand("cm_CloseAllTabs")

-- 6. Switch to a specific directory.
DC.ExecuteCommand("cm_ChangeDir", "C:\\Users\\Public\\Music")

-- 7. Open a new tab.
DC.ExecuteCommand("cm_NewTab")

-- 8. Switch to a specific directory.
DC.ExecuteCommand("cm_ChangeDir", "E:\\VirtualMachines\\ShareFolder")

Using the internal command cm_ExecuteScript, we may configure a tool bar button that will execute our script.

Assuming this script file is E:\scripts\lua\music.lua, we could have the button configured this way:

Also, we may use the internal Double Commander Editor for editing our scripts. If filename has .lua file extension, it will be recognized by internal editor and it will provide us syntax highlighting specific for this Lua language:

(back to top)

3.2. System library

This library contains various system functions.

It provides all its functions inside the table SysUtils.

(back to top)

3.2.1. Details on SysUtils.FileGetAttr returned value

FileGetAttr returns the attribute settings of file sFileName.

The attribute is a OR-ed combination of the following constants:

See an example in the next section.

(back to top)

3.2.2. Example with SysUtils.FileGetAttr

This following script is an example of usage of the SysUtils.FileGetAttr.

When the parameter is detected to be a directory, it will open a new tab in the active panel and switch to it.

local params = {...}
local iAttr

if #params == 1 then -- We got at least one parameter?
  iAttr = SysUtils.FileGetAttr(params[1])
  if iAttr > 0 then -- We got a valid attribute?
    if math.floor(iAttr / 0x00000010) % 2 ~= 0 then
      -- bit 4 is set? So it's a directory.
      DC.ExecuteCommand("cm_NewTab")
      DC.ExecuteCommand("cm_ChangeDir", params[1])
    end
  end
end

In the above example, the params[1] is the 1st parameter passed to the script.

When using the internal command cm_ExecuteScript, it will will be the first parameter passed after the script filename.

So in our example, we may program a sample toolbar button like the following:

In this example, the parameter %"0%p will be passed to the script. This will represent, unquoted, the filename of the item currently selected in the active panel at the moment we press the toolbar button.

(back to top)

3.2.3. Example using FindFirst, FindNext and FindClose

In the following script example, we'll scan the content of the directory we received in parameter and store resulting data into a text file with the filename passed as a second parameter.

This will give us a good idea of the usage of FindFirst, FindNext and FindClose.

local params = {...}

if #params == 2 then -- We got our 2 parameters?
  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

In the above example, we need to pass two parameters to our script:

1. params[1] - which is the directory we want the content
2. params[2] - which is the outputfilename to store the result

So it's easy to configure a toolbar button using the internal command cm_ExecuteScript and pass the parameter to accomplish all this.

In this example, the parameter %"0%Ds will be passed to the script as the first parameter. This will represent, unquoted, the directory displayed by the active panel.

(back to top)

3.3. Clipboard library

Double Commander may provide external clipboard functionality to our Lua scripts.

Following table gives us the related functions:

(back to top)

3.3.1. Example of usage clipboard library

The following example is using three functions related with the clipboard: Clear, GetAsText and SetAsText.

It's a relative long script but it's good to put together a few functions we've seen above.

It assumes our active panel is currently into a directory with many source text files.

It also assumes we currently have in clipboard a single word and that it will receive as a single parameter the current active folder.

The script will scan the file in that current level of directory and will read the content of them one by one to detect text line that contains the word that was in clipboard.

Then, the filenames of the files that contain at least one line with that word will be place into the clipboard.

Then, the script will use the internal command cm_LoadSelectionFromClip and the files that have the words will then be selected.

Also, at the end, we put back in our clipboard the original word that needed to be searched.

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 -- We got our parameter?
  sSearchString = Clipbrd.GetAsText() -- Get the expression to search.
  Clipbrd.Clear() -- Making sure we have nothing in clipboard.
  DC.ExecuteCommand("cm_MarkUnmarkAll") -- Make sure nothing is selected.

  -- Let's scan one by one all the files of our directory.
  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 -- We got a valid attribute?
        -- We need file, not directory!
        if math.floor(iAttr / 0x00000010) % 2 == 0 then

          -- Let's now read the file line by line until the the end OR a found.
          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 we've found something, select it!
  if sFileToSelect ~= "" then
    Clipbrd.SetAsText(sFileToSelect)
    DC.ExecuteCommand("cm_LoadSelectionFromClip")
  end

  Clipbrd.SetAsText(sSearchString) -- Restoring what we had in clipboard.
end

(back to top)

3.4. Dialogs library

This library allows our scripts to interact with user to display message, prompt for answers, etc.

Following table gives us the related functions:

(back to top)

3.4.1. Buttons displayed in Dialogs.MessageBox

The buttons displayed in the box displayed by Dialogs.MessageBox function are controlled by a OR'ed value with one of the following:

Constant of ButFlags regarding the buttons displayed of Dialogs.MessageBox
Constant value	Buttons displayed, from left to right
0x0000 MB_OK
0x0001 MB_OKCANCEL
0x0002 MB_ABORTRETRYIGNORE
0x0003 MB_YESNOCANCEL
0x0004 MB_YESNO
0x0005 MB_RETRYCANCEL

(back to top)

3.4.2. Style of box of Dialogs.MessageBox

The style of the box displayed by Dialogs.MessageBox function are controlled by a OR'ed value with one of the following:

Constant of ButFlags regarding the icon and style of Dialogs.MessageBox
Constant value	Style of window
0x0040 MB_ICONINFORMATION	Informative window
0x0030 MB_ICONWARNING	Warning window
0x0020 MB_ICONQUESTION	Confirmation window
0x0010 MB_ICONERROR	Error window

(back to top)

3.4.3. Default active button of Dialogs.MessageBox

The default active button of the box displayed by Dialogs.MessageBox function are controlled by a OR'ed value with one of the following:

(back to top)

3.4.4. Returned value of Dialogs.MessageBox

The number returned by the Dialogs.MessageBox function represent the button user has pressed according to the following:

ButPressed value returned based on button pressed of Dialogs.MessageBox
Constant value	Button pressed
0x0000 mrNone	No button pressed
0x0001 mrOK
0x0002 mrCancel
0x0003 mrAbort
0x0004 mrRetry
0x0005 mrIgnore
0x0006 mrYes
0x0007 mrNo

Note: If we press the "x" in top right or press Esc to close the window, then the value of the button "Cancel" is will returned.

(back to top)

3.4.5. Example of usage of the Dialogs.MessageBox

Here is a little script using Dialogs.MessageBox and the resulting window that will be displayed:

-- Buttons displayed
MB_OK = 0x0000
MB_OKCANCEL = 0x0001
MB_ABORTRETRYIGNORE = 0x0002
MB_YESNOCANCEL = 0x0003
MB_YESNO = 0x0004
MB_RETRYCANCEL = 0x0005

-- Box style
MB_ICONINFORMATION = 0x0040
MB_ICONWARNING = 0x0030
MB_ICONQUESTION = 0x0020
MB_ICONERROR = 0x0010

-- Default button
MB_DEFBUTTON1 = 0x0000
MB_DEFBUTTON2 = 0x0100
MB_DEFBUTTON3 = 0x0200

-- Returned button pressed
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("Do you want to quit?", "Question", iFlags)

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

(back to top)

3.4.6. Example of usage of the Dialogs.InputQuery

Here is a little script using Dialogs.InputQuery and the resulting window that will be displayed:

bResult, sAnswer = Dialogs.InputQuery("Identification", "Enter your name:", false, "John")

if bResult == true then
  Dialogs.MessageBox("Hello " .. sAnswer .. "!", "Welcome!", 0x0040)
end

(back to top)

3.5. UTF-8 library

This library provides basic support for UTF-8 encoding.

It provides all its functions inside the table LazUtf8.

-- Print pairs of values in the form "position : character"
for iPos, sChar in LazUtf8.Next(String) do
  DC.LogWrite(iPos .. " : " .. sChar)
end

(back to top)

3.6. Char library

This library contains functions for checking whether a character belongs to a particular Unicode category, as well as getting the category of a character.

List of available functions in this library:

Also, these functions support working with two parameters: instead of a single character, we can specify a string and the position of the character in this string.

(back to top)

3.7. OS library

This library contains functions related with the operating system where Double Commander is running.

Here is the list of available functions in this library:

(back to top)

4. Index

(back to top)