2.15. Scripting Lua

Contenuto

1. Introduzione

2. Librerie dinamiche richieste (DLL)

3. Librerie di funzioni di Double Commander

3.1. Libreria DC

3.1.1. Esempio di utilizzo di DC.ExecuteCommand

3.2. Libreria di sistema

3.2.1. Dettagli sul valore restituito da SysUtils.FileGetAttr

3.2.2. Esempio di utilizzo di SysUtils.FileGetAttr

3.2.3. Esempio di utilizzo di FindFirst, FindNext e FindClose

3.3. Libreria degli appunti

3.3.1. Esempio di utilizzo della libreria degli appunti

3.4. Libreria dei dialoghi

3.4.1. Pulsanti visualizzati in Dialogs.MessageBox

3.4.2. Stili di finestra per Dialogs.MessageBox

3.4.3. Pulsante attivo predefinito di Dialogs.MessageBox

3.4.4. Valore restituito da Dialogs.MessageBox

3.4.5. Esempio di utilizzo di Dialogs.MessageBox

3.4.6. Esempio di utilizzo di Dialogs.InputQuery

3.5. Libreria UTF-8

3.6. Libreria dei caratteri

3.7. Libreria del sistema operativo

4. Indice

1. Introduzione

Per informazioni dettagliate sul linguaggio di programmazione Lua, visitare il sito ufficiale di Lua.

Double Commander consente di eseguire script Lua tramite il comando cm_ExecuteScript.
I parametri degli script devono essere passati così come sono, senza necessità di escape (senza virgolette o barre rovesciate "\\"), a tale scopo è consigliabile utilizzare la variabile %"0: ad esempio, per il file sotto il cursore utilizzare %"0%p0 anziché %p0, e per la cartella corrente %"0%D anziché %D. In caso contrario, se Double Commander aggiungesse automaticamente le virgolette, esse verrebbero passate come parte del parametro, e si dovrebbe gestirne la presenza nello script.
Per ottenere un elenco di tutti i file selezionati, è possibile ricorrere alle variabili di sistema (come %LU, %FU o %RU) oppure a comandi interni (quali cm_SaveSelectionToFile, cm_SaveFileDetailsToFile, cm_CopyFullNamesToClip o cm_CopyFileDetailsToClip). Ad esempio, se si utilizza la variabile %p, Double Commander passerà l'elenco dei nomi di tutti i file selezionati in un'unica riga di testo, separati da spazi.

Inoltre, è possibile sviluppare plugin di contenuto (WDX) tramite script Lua; alcuni esempi pratici sono disponibili nella cartella dell'applicazione (plugins/wdx/scripts). Sul wiki del progetto è presente una pagina dedicata allo sviluppo dei plugin. Limitazioni: sono supportati esclusivamente i seguenti tipi di dati:

• ft_numeric_32 (1) – numero intero a 32 bit con segno;
• ft_numeric_64 (2) – numero intero a 64 bit con segno;
• ft_numeric_floating (3) – numero in virgola mobile;
• ft_boolean (6) – tipo booleano: true o false;
• ft_multiplechoice (7) – valore a scelta multipla tra un insieme limitato;
• ft_string (8) – stringa di testo;
• ft_fulltext (9) – testo completo (più stringhe di testo), utilizzato unicamente per le funzioni di ricerca del plugin;
• ft_datetime (10) – data/ora: la data restituita verrà convertita in una stringa formattata di data e ora (il formato dipende dalle impostazioni internazionali del sistema).
  La data deve essere nel formato nativo di Windows, mentre le funzioni fornite da Lua e Double Commander per la ricerca dei file utilizzano il formato orario Unix. Per effettuare la conversione è possibile utilizzare la seguente formula:
  = UnixTime * 10000000 + 116444736000000000
  Trattandosi di un valore numerico molto grande, è richiesta la versione a 64 bit di Double Commander o una versione di Lua 5.3 o superiore.

L'elenco sopra riporta i nomi definiti nei file header (.h); negli script Lua è necessario fare riferimento ai rispettivi valori numerici indicati tra parentesi.

Informazioni sulla codifica del testo

Tutte le funzioni aggiuntive descritte di seguito accettano parametri stringa in formato codificato UTF-8 e restituiscono stringhe con la medesima codifica (ad eccezione della funzione LazUtf8.ConvertEncoding).

Alcune funzioni delle librerie standard di Lua sono state sostituite da equivalenti di Double Commander o di Free Pascal/Lazarus (oppure ne sono state create di nuove) per garantire il supporto nativo alla codifica UTF-8.

Nello sviluppo di plugin, è altrettanto necessario utilizzare la codifica UTF-8 per tutti i dati di tipo testo (ft_multiplechoice, ft_string e ft_fulltext).

Si consiglia di salvare i file di script utilizzando la codifica UTF-8 senza firma BOM.

Note importanti

L'automazione tramite Lua offre ampie potenzialità, ma in determinati contesti richiede attenzione ad alcuni dettagli implementativi. Di seguito sono raccolte alcune raccomandazioni utili.

1. Se sono attive le opzioni di aggiornamento automatico e di caricamento dell'elenco file in un thread separato, le funzioni di rinfresco operano in modalità asincrona. Poiché lo script viene eseguito nel thread principale (UI thread) di Double Commander, questa concorrenza potrebbe influenzare l'esecuzione in rari casi. Ad esempio, la chiamata consecutiva di comandi di navigazione potrebbe non produrre l'effetto sperato (specialmente con cartelle molto grandi o dischi lenti); in tali circostanze si consiglia di disabilitare il caricamento in thread separato o cercare percorsi alternativi.

Se lo script crea nuovi file o ne rinomina di esistenti nel pannello corrente e successivamente esegue operazioni aggiuntive (come la selezione o lo spostamento del cursore), in alcuni casi queste potrebbero fallire poiché l'elenco non è ancora aggiornato. È necessario chiamare preventivamente il comando cm_Refresh. Nelle condizioni descritte, anche cm_Refresh verrà eseguito in modo asincrono e Double Commander potrebbe non avere il tempo di ricostruire interamente l'elenco prima che lo script proceda.

Poiché l'aggiornamento automatico e il caricamento asincrono sono funzioni comode per l'utente, un metodo empirico e stabile per consentire a Double Commander di completare l'operazione consiste nel restituire momentaneamente il controllo al programma con una breve pausa:

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

2. La funzione io.open di Lua fa affidamento sulla funzione standard C fopen: in modalità testo, questa funzione effettua la conversione automatica delle interruzioni di riga (CRLF, LF o CR) in fase di lettura e scrittura, il che può produrre risultati imprevisti. Se si lavora con file aventi terminatori di riga diversi o se si sviluppano script multi-piattaforma, è essenziale tenerne conto, o più semplicemente forzare l'uso della modalità binaria.

3. Nei sistemi operativi Linux e Unix-like, all'interno del dialogo delle proprietà dei file, la funzione ContentGetValue viene richiamata impostando il flag CONTENT_DELAYIFSLOW (come quarto parametro, con valore pari a 1) per prevenire rallentamenti nell'apertura della finestra: se il recupero dei dati è particolarmente lento, è possibile restituire semplicemente nil per quel campo o per l'intero plugin verificando la presenza del suddetto flag.

4. Se il plugin deve restituire una stringa vuota, passare il valore nil risulta più efficiente rispetto alla stringa vuota "".

(Torna su)

2. Librerie dinamiche richieste (DLL)

Per poter interpretare ed eseguire gli script Lua, Double Commander richiede la presenza della libreria dinamica di Lua; sono supportate le versioni da 5.1 a 5.4.

È possibile utilizzare le librerie derivanti dal progetto LuaJIT. LuaJIT combina un interprete ad alte prestazioni scritto in assembly con un compilatore JIT avanzato. Inoltre, fornisce l'accesso alla libreria FFI, che consente di invocare funzioni C esterne e di utilizzare strutture dati C direttamente da codice Lua.

La versione per Windows di Double Commander include già la libreria di Lua preinstallata (basata su LuaJIT a partire da DC 0.9.7); su altre piattaforme è possibile installarla tramite il gestore dei pacchetti di sistema o compilarla autonomamente. Se si utilizza la versione a 64 bit di Double Commander, anche la libreria dinamica deve essere compilata per architetture a 64 bit.

Per impostazione predefinita, DC ricerca la libreria all'interno della propria cartella e nei percorsi di sistema cercando i file lua5.1.dll (in Windows), liblua5.1.so.0 (in Linux e sistemi Unix-like) o liblua5.1.dylib (in macOS). È possibile modificare il nome del file e il relativo percorso impostando il parametro Libreria di runtime Lua da utilizzare nelle opzioni.

(Torna su)

3. Librerie di funzioni di Double Commander

Double Commander espone diverse librerie di funzioni pronte all'uso per gli script Lua.

Di seguito viene riportato l'elenco delle librerie disponibili:

(Torna su)

3.1. Libreria DC

Questa libreria racchiude le funzioni native specifiche di Double Commander.

Tutte le funzioni sono esposte all'interno della tabella globale DC.

In aggiunta ai comandi interni standard, è possibile utilizzare il comando speciale cm_ExecuteToolBarItem, che consente di azionare un pulsante della barra degli strumenti specificandone l'identificatore univoco (questa funzionalità permette, ad esempio, di associare scorciatoie da tastiera ai pulsanti). Il comando si utilizza in modo del tutto analogo a un normale comando interno ed accetta i seguenti parametri:

L'identificatore univoco è memorizzato all'interno del tag ID. Ci sono diversi modi per recuperarlo: esaminando il file di configurazione doublecmd.xml, i file di backup delle barre degli strumenti, oppure copiando semplicemente il pulsante negli appunti e incollandone il codice XML in un editor di testo.

Nota: questi identificatori vengono generati automaticamente e potrebbero differire tra diverse installazioni del programma; se necessario, è comunque possibile assegnare manualmente un valore personalizzato.

(Torna su)

3.1.1. Esempio di utilizzo di DC.ExecuteCommand

In questo esempio viene illustrato un semplice script che esegue in sequenza le seguenti operazioni:

1. Sposta il focus sul pannello destro;
2. Chiude tutte le schede aperte al suo interno;
3. Cambia percorso selezionando una cartella specifica;
4. Sposta il focus sul pannello sinistro;
5. Chiude tutte le schede aperte;
6. Cambia percorso selezionando una cartella specifica;
7. Apre una nuova scheda;
8. Cambia percorso selezionando una cartella specifica.

-- 1. Sposta il focus sul pannello destro.
DC.ExecuteCommand("cm_FocusSwap", "side=right")
 
-- 2. Chiude tutte le schede.
DC.ExecuteCommand("cm_CloseAllTabs")
 
-- 3. Passa alla cartella specificata.
DC.ExecuteCommand("cm_ChangeDir", "E:\\FakeKey\\Documents\\Music")
 
-- 4. Sposta il focus sul pannello sinistro.
DC.ExecuteCommand("cm_FocusSwap", "side=left")
 
-- 5. Chiude tutte le schede.
DC.ExecuteCommand("cm_CloseAllTabs")
 
-- 6. Passa alla cartella specificata.
DC.ExecuteCommand("cm_ChangeDir", "C:\\Users\\Public\\Music")
 
-- 7. Apre una nuova scheda.
DC.ExecuteCommand("cm_NewTab")
 
-- 8. Passa alla cartella specificata.
DC.ExecuteCommand("cm_ChangeDir", "E:\\VirtualMachines\\ShareFolder")

Utilizzando il comando interno cm_ExecuteScript, è possibile configurare un pulsante sulla barra degli strumenti per l'esecuzione del nostro script.

Ipotizzando che il file di script sia salvato in E:\scripts\lua\music.lua, il pulsante può essere configurato come segue:

È inoltre possibile utilizzare il visualizzatore/editor interno di Double Commander per modificare lo script. Se il file presenta l'estensione .lua, l'editor ne riconoscerà il tipo abilitando l'evidenziazione sintattica nativa per il linguaggio Lua:

(Torna su)

3.2. Libreria di sistema

Questa libreria racchiude varie funzioni di interazione con il sistema operativo.

Tutte le funzioni sono accessibili tramite la tabella SysUtils.

(Torna su)

3.2.1. Dettagli sul valore restituito da SysUtils.FileGetAttr

FileGetAttr restituisce lo stato degli attributi per il file sFileName.

La maschera degli attributi restituita è una combinazione logica OR dei seguenti valori costanti:

Si veda l'esempio pratico riportato nella sezione successiva.

(Torna su)

3.2.2. Esempio di utilizzo di SysUtils.FileGetAttr

Lo script seguente illustra un esempio pratico di utilizzo di SysUtils.FileGetAttr.

Se il parametro ricevuto corrisponde a una cartella, lo script aprirà una nuova scheda nel pannello attivo e vi si sposterà all'interno.

local params = {...}
local iAttr
 
if #params == 1 then -- È stato passato almeno un parametro?
  iAttr = SysUtils.FileGetAttr(params[1])
  if iAttr > 0 then -- È stato recuperato un attributo valido?
    if math.floor(iAttr / 0x00000010) % 2 ~= 0 then
      -- Il quarto bit (0x10) è attivo? In tal caso è una cartella.
      DC.ExecuteCommand("cm_NewTab")
      DC.ExecuteCommand("cm_ChangeDir", params[1])
    end
  end
end

Nell'esempio sopra riportato, params[1] rappresenta il primo parametro passato allo script.

Quando si utilizza the comando interno cm_ExecuteScript, i parametri dello script vengono passati subito dopo il nome del file.

Di conseguenza, per questo esempio, è possibile configurare un pulsante sulla barra degli strumenti come segue:

In questo esempio, viene passata allo script la variabile %"0%p. Essa rappresenta il nome del file dell'elemento attualmente selezionato nel pannello attivo, senza virgolette esterne.

(Torna su)

3.2.3. Esempio di utilizzo di FindFirst, FindNext e FindClose

Nel seguente esempio pratico, lo script effettua la scansione di una cartella (ricevuta come primo parametro) e scrive l'elenco e le dimensioni degli elementi individuati in un file di testo (il cui nome è passato come secondo parametro).

Questo script illustra chiaramente l'uso corretto delle funzioni di scansione FindFirst, FindNext e FindClose.

local params = {...}
 
if #params == 2 then -- Sono stati passati entrambi i parametri richiesti?
  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

Nell'esempio sopra riportato, è necessario passare due parametri allo script:

1. params[1] - la cartella di cui scansionare il contenuto;
2. params[2] - il nome del file di testo in cui salvare i risultati.

È quindi molto semplice configurare un pulsante sulla barra degli strumenti che invoca il comando interno cm_ExecuteScript passando i relativi parametri.

In questo esempio, viene passata come primo parametro la variabile %"0%Ds, che corrisponde al percorso della cartella correntemente aperta nel pannello attivo, senza virgolette.

(Torna su)

3.3. Libreria degli appunti

Double Commander espone ai nostri script Lua alcune funzioni per interagire con gli appunti di sistema.

La tabella seguente riporta le funzioni disponibili nella libreria:

(Torna su)

3.3.1. Esempio di utilizzo della libreria degli appunti

Il seguente esempio pratico combina l'uso di tre funzioni della libreria: Clear, GetAsText e SetAsText.

Si tratta di uno script più strutturato, utile per comprendere come far cooperare diverse librerie tra di loro.

Lo script assume che il pannello attivo si trovi all'interno di una cartella contenente diversi file di testo.

Presuppone inoltre che negli appunti sia memorizzata una parola da cercare e che la cartella attiva venga passata allo script come parametro.

Lo script effettua la scansione di tutti i file presenti nella cartella e ne legge il contenuto riga per riga per verificare se vi sia presente la parola cercata.

I nomi dei file che contengono almeno una riga con la parola cercata vengono raccolti in un elenco e copiati negli appunti.

Successivamente, richiamando il comando interno cm_LoadSelectionFromClip, Double Commander selezionerà automaticamente tutti questi file nel pannello.

Infine, lo script provvederà a ripristinare la parola di ricerca originale negli appunti di sistema.

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 -- Il parametro richiesto è stato passato?
  sSearchString = Clipbrd.GetAsText() -- Recupera la parola chiave da cercare.
  Clipbrd.Clear() -- Pulisce temporaneamente gli appunti.
  DC.ExecuteCommand("cm_MarkUnmarkAll") -- Rimuove le selezioni correnti nel pannello.
 
  -- Inizia la scansione di tutti gli elementi della cartella.
  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 -- È stato recuperato un attributo valido?
        -- Considera solo i file ed esclude le cartelle!
        if math.floor(iAttr / 0x00000010) % 2 == 0 then
 
          -- Legge il file riga per riga fino alla fine o alla prima corrispondenza.
          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
 
  -- Se ci sono file corrispondenti, selezionali nel pannello!
  if sFileToSelect ~= "" then
    Clipbrd.SetAsText(sFileToSelect)
    DC.ExecuteCommand("cm_LoadSelectionFromClip")
  end
 
  Clipbrd.SetAsText(sSearchString) -- Ripristina la parola chiave originale negli appunti.
end

(Torna su)

3.4. Libreria dei dialoghi

Questa libreria consente agli script di interagire direttamente con l'utente, mostrando messaggi, ponendo domande o richiedendo l'inserimento di dati.

La tabella seguente riporta l'elenco delle funzioni disponibili:

(Torna su)

3.4.1. Pulsanti visualizzati in Dialogs.MessageBox

I pulsanti mostrati dalla funzione Dialogs.MessageBox sono controllati dalla combinazione dei seguenti flag costanti:

Costanti ButFlags per i pulsanti di Dialogs.MessageBox
Costante e valore	Pulsanti visualizzati (da sinistra a destra)
0x0000 MB_OK
0x0001 MB_OKCANCEL
0x0002 MB_ABORTRETRYIGNORE
0x0003 MB_YESNOCANCEL
0x0004 MB_YESNO
0x0005 MB_RETRYCANCEL

(Torna su)

3.4.2. Stili di finestra per Dialogs.MessageBox

L'icona e lo stile grafico della finestra di dialogo sono determinati dai seguenti flag costanti:

Costanti ButFlags per icone e stili di Dialogs.MessageBox
Costante e valore	Stile della finestra
0x0040 MB_ICONINFORMATION	Finestra informativa
0x0030 MB_ICONWARNING	Finestra di avvertimento
0x0020 MB_ICONQUESTION	Finestra di conferma/domanda
0x0010 MB_ICONERROR	Finestra di errore

(Torna su)

3.4.3. Pulsante attivo predefinito di Dialogs.MessageBox

Il pulsante attivo di default all'apertura del dialogo è definito dai seguenti flag costanti:

(Torna su)

3.4.4. Valore restituito da Dialogs.MessageBox

Il valore numerico restituito da Dialogs.MessageBox identifica il pulsante premuto dall'utente, come illustrato di seguito:

Valori di ritorno ButPressed per i pulsanti di Dialogs.MessageBox
Costante e valore	Pulsante premuto
0x0000 mrNone	Nessun pulsante premuto
0x0001 mrOK
0x0002 mrCancel
0x0003 mrAbort
0x0004 mrRetry
0x0005 mrIgnore
0x0006 mrYes
0x0007 mrNo

Nota: se l'utente chiude la finestra facendo clic sulla "x" in alto a destra o premendo il tasto Esc, viene restituito il codice corrispondente al pulsante "Annulla" (mrCancel).

(Torna su)

3.4.5. Esempio di utilizzo di Dialogs.MessageBox

Di seguito viene riportato un breve script di esempio che utilizza la funzione Dialogs.MessageBox e la finestra grafica generata:

-- Pulsanti visualizzati
MB_OK = 0x0000
MB_OKCANCEL = 0x0001
MB_ABORTRETRYIGNORE = 0x0002
MB_YESNOCANCEL = 0x0003
MB_YESNO = 0x0004
MB_RETRYCANCEL = 0x0005
 
-- Stile della finestra
MB_ICONINFORMATION = 0x0040
MB_ICONWARNING = 0x0030
MB_ICONQUESTION = 0x0020
MB_ICONERROR = 0x0010
 
-- Pulsante predefinito
MB_DEFBUTTON1 = 0x0000
MB_DEFBUTTON2 = 0x0100
MB_DEFBUTTON3 = 0x0200
 
-- Pulsante premuto restituito
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("Vuoi uscire da Double Commander?", "Domanda", iFlags)
 
if iButton == mrYes then
  DC.ExecuteCommand("cm_Exit")
end

(Torna su)

3.4.6. Esempio di utilizzo di Dialogs.InputQuery

Il seguente esempio mostra l'uso della funzione Dialogs.InputQuery per richiedere dati all'utente:

bResult, sAnswer = Dialogs.InputQuery("Autenticazione", "Inserisci il tuo nome:", false, "John")
 
if bResult == true then
  Dialogs.MessageBox("Ciao " .. sAnswer .. "!", "Benvenuto!", 0x0040)
end

(Torna su)

3.5. Libreria UTF-8

Questa libreria fornisce il support essenziale alla gestione di testi con codifica UTF-8.

Le funzioni sono disponibili all'interno della tabella LazUtf8.

-- Stampa le coppie "posizione : carattere"
for iPos, sChar in LazUtf8.Next(String) do
  DC.LogWrite(iPos .. " : " .. sChar)
end

(Torna su)

3.6. Libreria dei caratteri

Questa libreria contiene funzioni utili a determinare se un carattere appartiene a una specifica classe Unicode e a leggerne la relativa categoria.

Elenco delle funzioni disponibili in questa libreria:

In aggiunta, tutte queste funzioni supportano il passaggio di due parametri: anziché un singolo carattere, è possibile passare una stringa di testo e l'indice di posizione del carattere al suo interno.

(Torna su)

3.7. Libreria del sistema operativo

Questa libreria racchiude funzioni strettamente legate all'interazione con il sistema operativo ospite.

Di seguito viene riportato l'elenco delle funzioni disponibili:

(Torna su)

4. Indice

(Torna su)   it365 Toolbox