2.15. Scripts Lua

Contenu

1. Introduction

2. DLL requises

3. Bibliothèques de fonctions de Double Commander

3.1. Bibliothèque DC

3.1.1. Exemple d'utilisation de DC.ExecuteCommand

3.2. Bibliothèque Système (SysUtils)

3.2.1. Détails sur la valeur de retour de SysUtils.FileGetAttr

3.2.2. Exemple d'utilisation de SysUtils.FileGetAttr

3.2.3. Exemple d'utilisation de FindFirst, FindNext et FindClose

3.3. Bibliothèque Presse-papiers (Clipbrd)

3.3.1. Exemple d'utilisation de la bibliothèque Presse-papiers

3.4. Bibliothèque Dialogues (Dialogs)

3.4.1. Boutons affichés dans Dialogs.MessageBox

3.4.2. Styles de fenêtre de Dialogs.MessageBox

3.4.3. Bouton actif par défaut de Dialogs.MessageBox

3.4.4. Valeurs de retour de Dialogs.MessageBox

3.4.5. Exemple d'utilisation de Dialogs.MessageBox

3.4.6. Exemple d'utilisation de Dialogs.InputQuery

3.5. Bibliothèque UTF-8 (LazUtf8)

3.6. Bibliothèque Caractères (Char)

3.7. Bibliothèque Système d'exploitation (os)

4. Index

1. Introduction

Pour des informations détaillées sur le langage de programmation de script Lua, veuillez visiter le site web de Lua.

Double Commander peut exécuter des scripts Lua via la commande cm_ExecuteScript.
Les paramètres du script doivent être transmis tels quels, sans échappement (sans guillemets ni "\"), pour cela nous devons utiliser la variable %"0 : par exemple, pour le fichier sous le curseur, utilisez %"0%p0 au lieu de %p0, et pour le répertoire courant, utilisez %"0%D au lieu de %D. Sinon, si Double Commander ajoute automatiquement des guillemets, ils seront transmis comme faisant partie des paramètres et vous devrez en tenir compte.
Pour obtenir une liste de tous les fichiers sélectionnés, nous pouvons utiliser des variables (%LU, %FU ou %RU) ou des commandes internes (cm_SaveSelectionToFile, cm_SaveFileDetailsToFile, cm_CopyFullNamesToClip ou cm_CopyFileDetailsToClip). Par exemple, nous pouvons utiliser %p : dans ce cas, Double Commander transmettra les noms de tous les fichiers sélectionnés sur une seule ligne, en séparant les noms par des espaces.

Les scripts Lua peuvent également être utilisés pour écrire des plugins de contenu, des exemples peuvent être trouvés dans le dossier du programme (plugins/wdx/scripts). Il existe une page dédiée au développement de plugins sur le Wiki. Limitations : seuls les types de données suivants sont pris en charge

• ft_numeric_32 (1) – Nombre entier signé 32 bits ;
• ft_numeric_64 (2) – Nombre entier signé 64 bits ;
• ft_numeric_floating (3) – Nombre à virgule flottante ;
• ft_boolean (6) – Type booléen : true ou false ;
• ft_multiplechoice (7) – Permet une valeur parmi un nombre limité de choix ;
• ft_string (8) – Chaîne de texte ;
• ft_fulltext (9) – Texte intégral (plusieurs chaînes de texte), utilisé uniquement pour la recherche de plugins ;
• ft_datetime (10) – Date/Heure : la date retournée sera convertie en une chaîne de date et d'heure formatée (la valeur dépend de vos paramètres régionaux).
  La date doit être au format Windows, mais les fonctions fournies par Lua et Double Commander pour la recherche de fichiers utilisent le format de temps Unix. Pour effectuer la conversion, vous pouvez utiliser la formule suivante :
  = UnixTime * 10000000 + 116444736000000000
  C'est un grand nombre, vous aurez donc besoin de la version 64 bits de Double Commander ou de Lua 5.3+.

La liste ci-dessus contient les noms des fichiers d'en-tête, dans les scripts Lua, nous devons utiliser les valeurs numériques spécifiées entre parenthèses.

À propos de l'encodage du texte

Toutes les fonctions supplémentaires décrites ci-dessous acceptent des arguments de chaîne encodés en UTF-8 et retournent des chaînes avec cet encodage (à l'exception de la fonction LazUtf8.ConvertEncoding).

Certaines fonctions des bibliothèques Lua standard ont été remplacées par des fonctions de Double Commander ou de Free Pascal/Lazarus (ou de nouvelles fonctions ont été écrites), ce qui assure le support de l'UTF-8.

Lors de l'écriture de plugins, nous devrions également utiliser l'UTF-8 pour les données textuelles (ft_multiplechoice, ft_string et ft_fulltext).

Lors de l'enregistrement de scripts, veuillez utiliser l'encodage UTF-8 sans BOM.

Remarques

L'utilisation de Lua pour l'automatisation offre de grandes possibilités, mais dans certains cas, il faut prêter attention à certains détails. Essayons de les rassembler dans cette sous-section.

1. Si les options Actualisation automatique et Chargement de la liste de fichiers dans un thread séparé sont activées, la fonction d'actualisation fonctionnera de manière asynchrone. Parallèlement, le script s'exécute dans le thread principal de Double Commander, ce qui peut affecter l'exécution de votre script dans certains cas. Par exemple, l'exécution consécutive de commandes de navigation peut parfois ne pas fonctionner (par exemple, grands répertoires, disques lents). Dans ce cas, essayez de désactiver Chargement de la liste de fichiers dans un thread séparé ou cherchez une solution alternative.

Si votre script crée de nouveaux fichiers ou renomme des fichiers existants dans le panneau actuel, mais ne se termine pas ensuite et effectue des opérations supplémentaires (par exemple, sélection de fichiers ou déplacement du curseur), dans certains cas, ces opérations ne prendront pas effet : il se peut que tous les fichiers ne soient pas encore dans le panneau, vous devez d'abord appeler la commande cm_Refresh. Dans les conditions mentionnées, cm_Refresh s'exécutera également de manière asynchrone, et Double Commander pourrait ne pas avoir le temps de rafraîchir complètement la liste des fichiers après vos modifications.

L'actualisation automatique et le chargement de la liste de fichiers dans un thread séparé sont des fonctionnalités pratiques du gestionnaire de fichiers. Une méthode de travail stable a donc été trouvée expérimentalement, consistant à rendre temporairement le contrôle au programme et à permettre à la liste des fichiers de se rafraîchir complètement :

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

2. La fonction Lua io.open utilise la fonction C standard fopen : en mode texte, cette fonction peut convertir les types de fin de ligne (CRLF, LF ou CR) lors de la lecture et de l'écriture, ce qui peut entraîner des résultats inattendus. Si vous travaillez avec des fichiers ayant différents types de fin de ligne ou si vous écrivez des scripts multiplateformes, vous devez en tenir compte, ou plus pratiquement, privilégier le mode binaire.

3. Sous Linux et d'autres systèmes d'exploitation de type Unix, pour la boîte de dialogue Propriétés du fichier, la fonction ContentGetValue est appelée avec le drapeau CONTENT_DELAYIFSLOW (quatrième paramètre, valeur 1), ce qui évite les retards lors de l'ouverture de la fenêtre : si la récupération des données est lente, nous pouvons exclure ces données en ajoutant simplement une vérification de la valeur du drapeau et en retournant nil pour ces champs ou plugins.

4. Si un plugin doit retourner une chaîne vide, transmettre nil est plus rapide que de transmettre "".

（Retour au début）

2. DLL requises

Pour pouvoir interpréter les fichiers de script Lua, nous avons besoin d'un fichier DLL Lua. Double Commander prend en charge les versions 5.1 à 5.4.

Nous pouvons utiliser les fichiers DLL du projet LuaJIT. LuaJIT combine un interpréteur haute vitesse écrit en assembleur avec un compilateur JIT avancé. De plus, nous obtenons la bibliothèque FFI, qui permet d'appeler des fonctions C externes et d'utiliser des structures de données C depuis du code Lua pur.

Les versions Windows de DC incluent par défaut la DLL Lua (provenant du projet LuaJIT dans DC 0.9.7 et versions ultérieures). Dans d'autres cas, nous pouvons la trouver et l'installer via un gestionnaire de paquets, ou la compiler nous-mêmes. Si nous utilisons la version 64 bits de DC, la DLL doit également être en version 64 bits.

Par défaut, DC recherche des fichiers nommés lua5.1.dll (Windows), liblua5.1.so.0 (Unix ou GNU/Linux) ou liblua5.1.dylib (macOS) dans son répertoire et dans les répertoires système. Nous pouvons changer le nom du fichier (et le chemin) dans le paramètre Bibliothèque Lua à utiliser.

（Retour au début）

3. Bibliothèques de fonctions de Double Commander

Double Commander fournit plusieurs bibliothèques de fonctions pour nos scripts Lua.

Voici la liste de ces bibliothèques.

（Retour au début）

3.1. Bibliothèque DC

Cette bibliothèque contient des fonctions spécifiques à Double Commander.

Elle fournit toutes ses fonctions dans la table DC.

En plus des commandes internes, nous pouvons également utiliser la commande spéciale cm_ExecuteToolBarItem dans les scripts, qui permet d'appeler un bouton de la barre d'outils via son identifiant (dans le programme, cette fonction permet d'utiliser des raccourcis clavier pour les boutons de la barre d'outils). Cette commande s'utilise comme une commande interne normale (voir l'exemple ci-dessous) et possède les paramètres suivants :

L'identifiant unique est stocké dans la balise ID, et nous avons plusieurs façons de l'obtenir : on peut trouver le bouton dans le fichier doublecmd.xml, dans les fichiers de sauvegarde de la barre d'outils, ou simplement copier le bouton dans le presse-papiers et coller son code dans un éditeur de texte.

Note : Les identifiants sont générés automatiquement et ne correspondent pas nécessairement aux identifiants de boutons similaires dans une autre copie du programme, mais nous pouvons définir manuellement nos propres valeurs si nécessaire.

（Retour au début）

3.1.1. Exemple d'utilisation de DC.ExecuteCommand

Dans cet exemple, nous avons écrit un script simple qui fera les choses suivantes :

1. Donner le focus au panneau de droite
2. Fermer tous les onglets ouverts
3. Passer à un dossier spécifique
4. Donner le focus au panneau de gauche
5. Fermer tous les onglets ouverts
6. Passer à un dossier spécifique
7. Ouvrir un nouvel onglet
8. Passer à un dossier spécifique

-- 1. Focus sur le panneau de droite.
DC.ExecuteCommand("cm_FocusSwap", "side=right")

-- 2. Fermer tous les onglets.
DC.ExecuteCommand("cm_CloseAllTabs")

-- 3. Aller dans un répertoire spécifique.
DC.ExecuteCommand("cm_ChangeDir", "E:\\FakeKey\\Documents\\Music")

-- 4. Focus sur le panneau de gauche.
DC.ExecuteCommand("cm_FocusSwap", "side=left")

-- 5. Fermer tous les onglets.
DC.ExecuteCommand("cm_CloseAllTabs")

-- 6. Aller dans un répertoire spécifique.
DC.ExecuteCommand("cm_ChangeDir", "C:\\Users\\Public\\Music")

-- 7. Ouvrir un nouvel onglet.
DC.ExecuteCommand("cm_NewTab")

-- 8. Aller dans un répertoire spécifique.
DC.ExecuteCommand("cm_ChangeDir", "E:\\VirtualMachines\\ShareFolder")

En utilisant la commande interne cm_ExecuteScript, nous pouvons configurer un bouton de la barre d'outils pour exécuter notre script.

Supposons que ce fichier de script est E:\scripts\lua\music.lua, nous pouvons configurer le bouton comme ceci :

De plus, nous pouvons utiliser l'éditeur interne de Double Commander pour modifier les scripts. Si le nom du fichier a l'extension .lua, l'éditeur interne le reconnaîtra et fournira une coloration syntaxique pour le langage Lua :

（Retour au début）

3.2. Bibliothèque Système (SysUtils)

Cette bibliothèque contient diverses fonctions système.

Elle fournit toutes ses fonctions dans la table SysUtils.

（Retour au début）

3.2.1. Détails sur la valeur de retour de SysUtils.FileGetAttr

FileGetAttr retourne les paramètres d'attributs du fichier sFileName.

Les attributs sont une combinaison OU des constantes suivantes :

Voir l'exemple dans la section suivante.

（Retour au début）

3.2.2. Exemple d'utilisation de SysUtils.FileGetAttr

Le script suivant est un exemple d'utilisation de SysUtils.FileGetAttr.

Lorsqu'il détecte que le paramètre est un répertoire, il ouvre un nouvel onglet dans le panneau actif et passe à ce répertoire.

local params = {...}
local iAttr

if #params == 1 then -- Avons-nous au moins un paramètre ?
  iAttr = SysUtils.FileGetAttr(params[1])
  if iAttr > 0 then -- Avons-nous obtenu un attribut valide ?
    if math.floor(iAttr / 0x00000010) % 2 ~= 0 then
      -- Le 4ème bit est défini ? C'est donc un répertoire.
      DC.ExecuteCommand("cm_NewTab")
      DC.ExecuteCommand("cm_ChangeDir", params[1])
    end
  end
end

Dans l'exemple ci-dessus, params[1] est le premier paramètre transmis au script.

Lorsqu'on utilise la commande interne cm_ExecuteScript, il s'agira du premier paramètre transmis après le nom du fichier script.

Ainsi, dans notre exemple, nous pourrions configurer un bouton de la barre d'outils comme ceci :

Dans cet exemple, le paramètre %"0%p sera transmis au script. Cela représente le nom du fichier de l'élément sélectionné dans le panneau actuellement actif, sans guillemets.

（Retour au début）

3.2.3. Exemple d'utilisation de FindFirst, FindNext et FindClose

Dans l'exemple de script suivant, nous allons scanner le contenu du répertoire reçu en paramètre et stocker les données résultantes dans un fichier texte dont le nom est transmis comme second paramètre.

Cela nous donnera une bonne idée de l'utilisation de FindFirst, FindNext et FindClose.

local params = {...}

if #params == 2 then -- Avons-nous deux paramètres ?
  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

Dans l'exemple ci-dessus, nous devons transmettre deux paramètres au script :

1. params[1] - Le répertoire dont nous voulons le contenu
2. params[2] - Le nom du fichier de sortie pour stocker les résultats

Il est donc très facile de configurer un bouton de la barre d'outils avec la commande interne cm_ExecuteScript et de transmettre les paramètres pour accomplir tout cela.

Dans cet exemple, le paramètre %"0%Ds sera transmis comme premier argument au script. Cela représentera le répertoire affiché par le panneau actif, sans guillemets.

（Retour au début）

3.3. Bibliothèque Presse-papiers (Clipbrd)

Double Commander peut fournir des fonctions pour le presse-papiers externe à nos scripts Lua.

Le tableau ci-dessous donne les fonctions correspondantes :

（Retour au début）

3.3.1. Exemple d'utilisation de la bibliothèque Presse-papiers

L'exemple suivant utilise les trois fonctions liées au presse-papiers : Clear, GetAsText et SetAsText.

C'est un script relativement long, mais il combine bien certaines des fonctions vues précédemment.

Il suppose que notre panneau actif se trouve actuellement dans un répertoire contenant de nombreux fichiers texte sources.

Il suppose également que nous avons actuellement un mot dans le presse-papiers, et il recevra le dossier actif actuel comme paramètre unique.

Le script va scanner les fichiers du répertoire actuel un par un et lire leur contenu pour détecter les lignes de texte contenant le mot présent dans le presse-papiers.

Ensuite, les noms des fichiers contenant au moins une ligne avec ce mot seront placés dans le presse-papiers.

Le script utilisera ensuite la commande interne cm_LoadSelectionFromClip, et les fichiers contenant le mot seront sélectionnés.

De plus, à la fin, nous remettrons le mot original à rechercher dans le presse-papiers.

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 -- Avons-nous le paramètre ?
  sSearchString = Clipbrd.GetAsText() -- Obtenir l'expression à rechercher.
  Clipbrd.Clear() -- S'assurer que le presse-papiers est vide.
  DC.ExecuteCommand("cm_MarkUnmarkAll") -- S'assurer que rien n'est sélectionné.

  -- Scannons tous les fichiers du répertoire un par un.
  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 -- Avons-nous obtenu un attribut valide ?
        -- Nous voulons des fichiers, pas des répertoires !
        if math.floor(iAttr / 0x00000010) % 2 == 0 then

          -- Lisons maintenant le fichier ligne par ligne jusqu'à la fin ou jusqu'à trouver.
          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

  -- Si nous avons trouvé quelque chose, sélectionnons-le !
  if sFileToSelect ~= "" then
    Clipbrd.SetAsText(sFileToSelect)
    DC.ExecuteCommand("cm_LoadSelectionFromClip")
  end

  Clipbrd.SetAsText(sSearchString) -- Restaurer le contenu du presse-papiers.
end

（Retour au début）

3.4. Bibliothèque Dialogues (Dialogs)

Cette bibliothèque permet à nos scripts d'interagir avec l'utilisateur, d'afficher des messages, de demander des réponses, etc.

Le tableau ci-dessous répertorie les fonctions correspondantes :

（Retour au début）

3.4.1. Boutons affichés dans Dialogs.MessageBox

Les boutons affichés par la fonction Dialogs.MessageBox sont contrôlés par la valeur OR bit à bit des constantes suivantes :

Constantes ButFlags pour les boutons affichés dans Dialogs.MessageBox
Valeur de la constante	Boutons affichés, de gauche à droite
0x0000 MB_OK
0x0001 MB_OKCANCEL
0x0002 MB_ABORTRETRYIGNORE
0x0003 MB_YESNOCANCEL
0x0004 MB_YESNO
0x0005 MB_RETRYCANCEL

（Retour au début）

3.4.2. Styles de fenêtre de Dialogs.MessageBox

Le style de fenêtre affiché par la fonction Dialogs.MessageBox est contrôlé par la valeur OR bit à bit des constantes suivantes :

Constantes ButFlags pour les icônes et styles dans Dialogs.MessageBox
Valeur de la constante	Style de fenêtre
0x0040 MB_ICONINFORMATION	Fenêtre d'information
0x0030 MB_ICONWARNING	Fenêtre d'avertissement
0x0020 MB_ICONQUESTION	Fenêtre de confirmation
0x0010 MB_ICONERROR	Fenêtre d'erreur

（Retour au début）

3.4.3. Bouton actif par défaut de Dialogs.MessageBox

Le bouton actif par défaut affiché par la fonction Dialogs.MessageBox est contrôlé par la valeur OR bit à bit des constantes suivantes :

（Retour au début）

3.4.4. Valeurs de retour de Dialogs.MessageBox

Le nombre retourné par la fonction Dialogs.MessageBox représente le bouton sur lequel l'utilisateur a appuyé, comme suit :

Valeurs ButPressed retournées lors de l'appui sur un bouton dans Dialogs.MessageBox
Valeur de la constante	Bouton appuyé
0x0000 mrNone	Aucun bouton appuyé
0x0001 mrOK
0x0002 mrCancel
0x0003 mrAbort
0x0004 mrRetry
0x0005 mrIgnore
0x0006 mrYes
0x0007 mrNo

Note : Si vous fermez la fenêtre en appuyant sur le "x" dans le coin supérieur droit ou en appuyant sur Échap, la valeur du bouton "Annuler" sera retournée.

（Retour au début）

3.4.5. Exemple d'utilisation de Dialogs.MessageBox

Voici un petit script utilisant Dialogs.MessageBox ainsi que la fenêtre de résultat qui sera affichée :

-- Boutons affichés
MB_OK = 0x0000
MB_OKCANCEL = 0x0001
MB_ABORTRETRYIGNORE = 0x0002
MB_YESNOCANCEL = 0x0003
MB_YESNO = 0x0004
MB_RETRYCANCEL = 0x0005

-- Style de la fenêtre
MB_ICONINFORMATION = 0x0040
MB_ICONWARNING = 0x0030
MB_ICONQUESTION = 0x0020
MB_ICONERROR = 0x0010

-- Bouton par défaut
MB_DEFBUTTON1 = 0x0000
MB_DEFBUTTON2 = 0x0100
MB_DEFBUTTON3 = 0x0200

-- Retour du bouton appuyé
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("Voulez-vous quitter ?", "Question", iFlags)

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

（Retour au début）

3.4.6. Exemple d'utilisation de Dialogs.InputQuery

Voici un petit script utilisant Dialogs.InputQuery ainsi que la fenêtre de résultat qui sera affichée :

bResult, sAnswer = Dialogs.InputQuery("Authentification", "Veuillez entrer votre nom :", false, "Jean")

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

（Retour au début）

3.5. Bibliothèque UTF-8 (LazUtf8)

Cette bibliothèque fournit un support de base pour l'encodage UTF-8.

Elle fournit toutes ses fonctions dans la table LazUtf8.

-- Affiche les paires sous la forme "Position : Caractère"
for iPos, sChar in LazUtf8.Next(String) do
  DC.LogWrite(iPos .. " : " .. sChar)
end

（Retour au début）

3.6. Bibliothèque Caractères (Char)

Cette bibliothèque contient des fonctions pour vérifier si un caractère appartient à une catégorie Unicode spécifique, ainsi que pour obtenir la catégorie d'un caractère.

Liste des fonctions disponibles dans cette bibliothèque :

De plus, ces fonctions supportent l'utilisation de deux paramètres : nous pouvons spécifier une chaîne et la position du caractère dans cette chaîne, au lieu d'un seul caractère.

（Retour au début）

3.7. Bibliothèque Système d'exploitation (os)

Cette bibliothèque contient des fonctions liées au système d'exploitation sur lequel Double Commander s'exécute.

Voici la liste des fonctions disponibles dans cette bibliothèque :

（Retour au début）

4. Index

（Retour au début）   it365 Toolbox