2.15. Scripts Lua

Contenido

1. Introducción

2. DLL requerida

3. Bibliotecas de funciones de Double Commander

3.1. Biblioteca DC

3.1.1. Ejemplo de uso de DC.ExecuteCommand

3.2. Biblioteca del sistema

3.2.1. Detalles del valor devuelto por SysUtils.FileGetAttr

3.2.2. Ejemplo de uso de SysUtils.FileGetAttr

3.2.3. Ejemplo usando FindFirst, FindNext y FindClose

3.3. Biblioteca del portapapeles

3.3.1. Ejemplo de uso de la biblioteca del portapapeles

3.4. Biblioteca de diálogos

3.4.1. Botones mostrados en Dialogs.MessageBox

3.4.2. Estilo de ventana de Dialogs.MessageBox

3.4.3. Botón activo predeterminado de Dialogs.MessageBox

3.4.4. Valor devuelto de Dialogs.MessageBox

3.4.5. Ejemplo de uso de Dialogs.MessageBox

3.4.6. Ejemplo de uso de Dialogs.InputQuery

3.5. Biblioteca UTF-8

3.6. Biblioteca de caracteres

3.7. Biblioteca del sistema operativo

4. Índice

1. Introducción

Para obtener información detallada sobre el lenguaje de programación de scripts Lua, visite el sitio web de Lua.

Double Commander puede ejecutar scripts Lua mediante el comando cm_ExecuteScript.
Los parámetros del script deben pasarse tal cual, sin escape (sin comillas o "\"), para ello necesitamos usar la variable %"0: por ejemplo, para el archivo bajo el cursor use %"0%p0 en lugar de %p0, para el directorio actual use %"0%D en lugar de %D. De lo contrario, si Double Commander agrega automáticamente comillas, estas se pasarán como parte del parámetro y tendrá que tener esto en cuenta.
Para obtener una lista de todos los archivos seleccionados, podemos usar variables (%LU, %FU o %RU) o comandos internos (cm_SaveSelectionToFile, cm_SaveFileDetailsToFile, cm_CopyFullNamesToClip o cm_CopyFileDetailsToClip). Por ejemplo, podemos usar %p: en este caso, Double Commander pasará todos los nombres de archivos seleccionados en una línea, separando los nombres con espacios.

También es posible escribir plugins de contenido usando scripts Lua, los ejemplos se pueden encontrar en la carpeta del programa (plugins/wdx/scripts). Hay una página dedicada a la escritura de plugins en la Wiki. Restricción: solo se admiten los siguientes tipos de datos

• ft_numeric_32 (1) – número firmado de 32 bits;
• ft_numeric_64 (2) – número firmado de 64 bits;
• ft_numeric_floating (3) – número de punto flotante;
• ft_boolean (6) – tipo booleano: true o false;
• ft_multiplechoice (7) – permite un número limitado de valores de selección;
• ft_string (8) – cadena de texto;
• ft_fulltext (9) – texto completo (múltiples cadenas de texto), solo para búsqueda de plugins;
• ft_datetime (10) – fecha/hora: la fecha devuelta se convertirá a una cadena formateada de fecha y hora (el valor depende de su configuración regional).
  La fecha debe estar en formato Windows, pero las funciones proporcionadas por Lua y Double Commander para buscar archivos usan el formato de tiempo Unix. Para realizar la conversión, puede usar la siguiente fórmula:
  = UnixTime * 10000000 + 116444736000000000
  Este es un número grande, por lo que necesita la versión de 64 bits de Double Commander o Lua 5.3+.

La lista anterior contiene nombres del archivo de encabezado, en scripts Lua debemos usar los valores numéricos especificados entre paréntesis.

Acerca de la codificación de texto

Todas las funciones adicionales descritas a continuación aceptan parámetros de cadena codificados en UTF-8 y devuelven cadenas en esta codificación (excepto la función LazUtf8.ConvertEncoding).

Algunas funciones en bibliotecas estándar de Lua han sido reemplazadas por funciones de Double Commander o Free Pascal/Lazarus (o se han escrito nuevas funciones), lo que proporciona soporte UTF-8.

Al escribir plugins, también deberíamos usar UTF-8 para datos de texto (ft_multiplechoice, ft_string y ft_fulltext).

Al guardar scripts, utilice la codificación UTF-8 sin BOM.

Notas importantes

El uso de Lua para automatización tiene grandes posibilidades, pero en ciertas situaciones puede ser necesario prestar atención a algunos detalles. Intentemos recopilar estos contenidos en esta subsección.

1. Si las opciones actualización automática y cargar lista de archivos en un hilo separado están habilitadas, la función de actualización trabajará de forma asíncrona. Al mismo tiempo, los scripts se ejecutan en el hilo principal de Double Commander, por lo que en ciertos casos todo esto puede afectar la ejecución de sus scripts. Por ejemplo, a veces la ejecución consecutiva de comandos de navegación puede no funcionar (por ejemplo, directorios grandes, discos lentos), en este caso, intente deshabilitar cargar lista de archivos en un hilo separado o busque soluciones alternativas.

Si su script crea nuevos archivos o renombra archivos existentes en el panel actual, pero luego no finaliza y ejecuta algunas operaciones adicionales (por ejemplo, seleccionar archivos o mover el cursor), en ciertos casos estas operaciones no tendrán efecto: no todos los archivos pueden haber estado ya en el panel, primero necesita llamar al comando cm_Refresh. Bajo las condiciones mencionadas, cm_Refresh también se ejecutará de forma asíncrona, y Double Commander puede no tener tiempo para actualizar completamente la lista de archivos después de sus cambios.

La actualización automática y cargar la lista de archivos en un hilo separado son funciones convenientes del administrador de archivos, por lo tanto, a través de experimentación se encontró un método estable de trabajo, que es devolver temporalmente el control al programa y permitir que la lista de archivos se actualice completamente:

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

2. La función Lua io.open usa la función estándar C fopen: en modo texto, esta función puede convertir tipos de fin de línea (CRLF, LF o CR) al leer y escribir, lo que podría causar resultados inesperados. Si encuentra archivos con diferentes tipos de fin de línea o está escribiendo scripts multiplataforma, debe considerar esto, o más prácticamente, priorizar el uso del modo binario.

3. En Linux y otros sistemas operativos tipo Unix, para el cuadro de diálogo de propiedades de archivo, se llama a la función ContentGetValue con la bandera CONTENT_DELAYIFSLOW (cuarto parámetro, valor 1), esto evita retrasos al abrir la ventana: si la recuperación de datos es lenta, podemos excluir estos datos simplemente agregando una verificación del valor de la bandera y devolviendo nil para esos campos o plugins.

4. Si el plugin debería devolver una cadena vacía, pasar nil es más rápido que pasar "".

(Volver arriba)

2. DLL requerida

Para poder interpretar archivos de script Lua, necesitamos un archivo DLL de Lua. Double Commander soporta las versiones 5.1 a 5.4.

Podemos utilizar el archivo DLL del proyecto LuaJIT. LuaJIT combina un intérprete de alta velocidad escrito en ensamblador con un compilador avanzado JIT. Además, obtenemos la biblioteca FFI, que permite llamar funciones externas en C y usar estructuras de datos en C desde código Lua puro.

La versión de Windows de DC incluye por defecto la DLL de Lua (en DC 0.9.7 y versiones posteriores proviene del proyecto LuaJIT). En otros casos, podemos buscar e instalarla mediante un gestor de paquetes o compilarla nosotros mismos. Si utilizamos la versión de 64 bits de DC, entonces la DLL también debe ser de 64 bits.

Por defecto, DC busca un archivo llamado lua5.1.dll (Windows), liblua5.1.so.0 (Unix o GNU/Linux) o liblua5.1.dylib (macOS) en su propio directorio y en los directorios del sistema. Podemos cambiar el nombre del archivo (y la ruta) en el parámetro Archivo de biblioteca Lua a usar.

(Volver arriba)

3. Bibliotecas de funciones de Double Commander

Double Commander proporciona algunas bibliotecas de funciones para nuestros scripts Lua.

A continuación se muestra la lista de estas bibliotecas.

(Volver arriba)

3.1. Biblioteca DC

Esta biblioteca contiene funciones específicas de Double Commander.

Proporciona todas las funciones en la tabla DC.

Además de los comandos internos, en los scripts también podemos usar el comando especial cm_ExecuteToolBarItem, que permite invocar botones de la barra de herramientas mediante identificadores (en el programa, esta función proporciona la capacidad de usar atajos de teclado para los botones de la barra de herramientas). El uso de este comando es similar al de los comandos internos normales (ver ejemplo a continuación) y tiene los siguientes parámetros:

Los identificadores únicos se almacenan en la etiqueta ID. Tenemos varias formas de obtenerlo: podemos encontrar el botón en el archivo doublecmd.xml o en los archivos de copia de seguridad de la barra de herramientas, o simplemente copiar el botón al portapapeles y pegar su código en un editor de texto.

Nota: Los identificadores se generan automáticamente y no tienen por qué coincidir con los identificadores de botones similares en otra copia del programa, pero si es necesario, podemos establecer manualmente nuestros propios valores.

(Volver arriba)

3.1.1. Ejemplo de uso de DC.ExecuteCommand

En este ejemplo, escribimos un script simple que realizará las siguientes acciones:

1. Enfocar el panel derecho
2. Cerrar todas las pestañas abiertas
3. Cambiar a una carpeta específica
4. Enfocar el panel izquierdo
5. Cerrar todas las pestañas abiertas
6. Cambiar a una carpeta específica
7. Abrir una nueva pestaña
8. Cambiar a una carpeta específica

-- 1. Enfocar el panel derecho.
DC.ExecuteCommand("cm_FocusSwap", "side=right")

-- 2. Cerrar todas las pestañas.
DC.ExecuteCommand("cm_CloseAllTabs")

-- 3. Cambiar a un directorio específico.
DC.ExecuteCommand("cm_ChangeDir", "E:\\FakeKey\\Documents\\Music")

-- 4. Enfocar el panel izquierdo.
DC.ExecuteCommand("cm_FocusSwap", "side=left")

-- 5. Cerrar todas las pestañas.
DC.ExecuteCommand("cm_CloseAllTabs")

-- 6. Cambiar a un directorio específico.
DC.ExecuteCommand("cm_ChangeDir", "C:\\Users\\Public\\Music")

-- 7. Abrir una nueva pestaña.
DC.ExecuteCommand("cm_NewTab")

-- 8. Cambiar a un directorio específico.
DC.ExecuteCommand("cm_ChangeDir", "E:\\VirtualMachines\\ShareFolder")

Usando el comando interno cm_ExecuteScript, podemos configurar un botón de la barra de herramientas para ejecutar nuestro script.

Supongamos que este archivo de script es E:\scripts\lua\music.lua, podemos configurar el botón de la siguiente manera:

Además, también podemos usar el editor interno de Double Commander para editar scripts. Si el nombre del archivo tiene la extensión .lua, el editor interno lo reconocerá y proporcionará resaltado de sintaxis para el lenguaje Lua:

(Volver arriba)

3.2. Biblioteca del sistema

Esta biblioteca contiene varias funciones del sistema.

Proporciona todas las funciones en la tabla SysUtils.

(Volver arriba)

3.2.1. Detalles del valor devuelto por SysUtils.FileGetAttr

FileGetAttr devuelve la configuración de atributos del archivo sFileName.

Los atributos son una combinación OR de las siguientes constantes:

Vea el ejemplo en la siguiente sección.

(Volver arriba)

3.2.2. Ejemplo de uso de SysUtils.FileGetAttr

El siguiente script es un ejemplo del uso de SysUtils.FileGetAttr.

Cuando detecta que el argumento es un directorio, abre una nueva pestaña en el panel activo y cambia a ese directorio.

local params = {...}
local iAttr

if #params == 1 then -- ¿Recibimos al menos un parámetro?
  iAttr = SysUtils.FileGetAttr(params[1])
  if iAttr > 0 then -- ¿Obtuvimos un atributo válido?
    if math.floor(iAttr / 0x00000010) % 2 ~= 0 then
      -- ¿Está establecido el cuarto bit? Entonces es un directorio.
      DC.ExecuteCommand("cm_NewTab")
      DC.ExecuteCommand("cm_ChangeDir", params[1])
    end
  end
end

En el ejemplo anterior, params[1] es el primer argumento pasado al script.

Cuando se utiliza el comando interno cm_ExecuteScript, será el primer argumento pasado después del nombre del archivo de script.

Por lo tanto, en nuestro ejemplo, podemos configurar un botón de la barra de herramientas como sigue:

En este ejemplo, el parámetro %"0%p se pasará al script. Esto representará el nombre del archivo del elemento seleccionado en el panel activo actual sin comillas.

(Volver arriba)

3.2.3. Ejemplo usando FindFirst, FindNext y FindClose

En el siguiente ejemplo de script, escanearemos el contenido del directorio recibido como parámetro y almacenaremos los datos resultantes en un archivo de texto cuyo nombre se pasa como segundo parámetro.

Esto nos dará una buena comprensión del uso de FindFirst, FindNext y FindClose.

local params = {...}

if #params == 2 then -- ¿Recibimos dos parámetros?
  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

En el ejemplo anterior, necesitamos pasar dos argumentos al script:

1. params[1] - El directorio cuyo contenido queremos
2. params[2] - El nombre del archivo de salida donde almacenar los resultados

Por lo tanto, es fácil configurar un botón de la barra de herramientas usando el comando interno cm_ExecuteScript y pasarle los parámetros.

En este ejemplo, el parámetro %"0%Ds se pasará como primer argumento al script. Esto representará el directorio mostrado en el panel activo sin comillas.

(Volver arriba)

3.3. Biblioteca del portapapeles

Double Commander puede proporcionar funcionalidad de portapapeles externo para nuestros scripts Lua.

La siguiente tabla muestra las funciones relacionadas:

(Volver arriba)

3.3.1. Ejemplo de uso de la biblioteca del portapapeles

El siguiente ejemplo utiliza tres funciones relacionadas con el portapapeles: Clear, GetAsText y SetAsText.

Este es un script relativamente largo, pero combina muy bien algunas de las funciones vistas anteriormente.

Se asume que nuestro panel activo está actualmente ubicado en un directorio que contiene muchos archivos de texto fuente.

También se asume que actualmente tenemos una palabra en el portapapeles y que recibirá la carpeta activa actual como único parámetro.

El script escaneará los archivos del nivel del directorio actual y leerá su contenido uno por uno para detectar líneas de texto que contengan la palabra del portapapeles.

Luego, los nombres de archivo que contengan al menos una línea con esa palabra se colocarán en el portapapeles.

Posteriormente, el script utilizará el comando interno cm_LoadSelectionFromClip para seleccionar los archivos que contengan dicha palabra.

Además, al final, volveremos a colocar la palabra original que necesitábamos buscar en el portapapeles.

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 -- ¿Recibimos un parámetro?
  sSearchString = Clipbrd.GetAsText() -- Obtener la expresión a buscar.
  Clipbrd.Clear() -- Asegurarnos de que el portapapeles esté vacío.
  DC.ExecuteCommand("cm_MarkUnmarkAll") -- Asegurarnos de que nada esté seleccionado.

  -- Escaneemos uno por uno todos los archivos del directorio.
  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 -- ¿Obtuvimos un atributo válido?
        -- ¡Necesitamos archivos, no directorios!
        if math.floor(iAttr / 0x00000010) % 2 == 0 then

          -- Ahora leamos el archivo línea por línea hasta el final o hasta encontrarlo.
          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 encontramos algo, seleccionémoslo!
  if sFileToSelect ~= "" then
    Clipbrd.SetAsText(sFileToSelect)
    DC.ExecuteCommand("cm_LoadSelectionFromClip")
  end

  Clipbrd.SetAsText(sSearchString) -- Restaurar el contenido del portapapeles.
end

(Volver arriba)

3.4. Biblioteca de diálogos

Esta biblioteca permite que nuestros scripts interactúen con el usuario, mostrando mensajes, solicitando respuestas, etc.

La siguiente tabla enumera las funciones relacionadas:

(Volver arriba)

3.4.1. Botones mostrados en Dialogs.MessageBox

Los botones mostrados por la función Dialogs.MessageBox están controlados por los siguientes valores constantes combinados con OR bit a bit:

Constantes ButFlags para mostrar botones en Dialogs.MessageBox
Valor de la constante	Botones mostrados, de izquierda a derecha
0x0000 MB_OK
0x0001 MB_OKCANCEL
0x0002 MB_ABORTRETRYIGNORE
0x0003 MB_YESNOCANCEL
0x0004 MB_YESNO
0x0005 MB_RETRYCANCEL

(Volver arriba)

3.4.2. Estilo de ventana de Dialogs.MessageBox

El estilo de ventana mostrado por la función Dialogs.MessageBox está controlado por los siguientes valores constantes combinados con OR bit a bit:

Constantes ButFlags para iconos y estilos de Dialogs.MessageBox
Valor de la constante	Estilo de ventana
0x0040 MB_ICONINFORMATION	Ventana de información
0x0030 MB_ICONWARNING	Ventana de advertencia
0x0020 MB_ICONQUESTION	Ventana de confirmación
0x0010 MB_ICONERROR	Ventana de error

(Volver arriba)

3.4.3. Botón activo predeterminado de Dialogs.MessageBox

El botón activo predeterminado mostrado por la función Dialogs.MessageBox está controlado por los siguientes valores constantes combinados con OR bit a bit:

(Volver arriba)

3.4.4. Valor devuelto de Dialogs.MessageBox

El número devuelto por la función Dialogs.MessageBox representa el botón presionado por el usuario, como se muestra a continuación:

Valores ButPressed devueltos cuando se presiona un botón en Dialogs.MessageBox
Valor de la constante	Botón presionado
0x0000 mrNone	No se presionó ningún botón
0x0001 mrOK
0x0002 mrCancel
0x0003 mrAbort
0x0004 mrRetry
0x0005 mrIgnore
0x0006 mrYes
0x0007 mrNo

Nota: Si se presiona la "x" en la esquina superior derecha o se cierra la ventana con Esc, se devolverá el valor del botón "Cancelar".

(Volver arriba)

3.4.5. Ejemplo de uso de Dialogs.MessageBox

A continuación se muestra un pequeño script usando Dialogs.MessageBox y la ventana resultante que se mostrará:

-- Botones mostrados
MB_OK = 0x0000
MB_OKCANCEL = 0x0001
MB_ABORTRETRYIGNORE = 0x0002
MB_YESNOCANCEL = 0x0003
MB_YESNO = 0x0004
MB_RETRYCANCEL = 0x0005

-- Estilo de ventana
MB_ICONINFORMATION = 0x0040
MB_ICONWARNING = 0x0030
MB_ICONQUESTION = 0x0020
MB_ICONERROR = 0x0010

-- Botón predeterminado
MB_DEFBUTTON1 = 0x0000
MB_DEFBUTTON2 = 0x0100
MB_DEFBUTTON3 = 0x0200

-- Devolución del botón presionado
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("¿Desea salir?", "Pregunta", iFlags)

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

(Volver arriba)

3.4.6. Ejemplo de uso de Dialogs.InputQuery

A continuación se muestra un pequeño script usando Dialogs.InputQuery y la ventana resultante que se mostrará:

bResult, sAnswer = Dialogs.InputQuery("Autenticación", "Por favor ingrese su nombre:", false, "Juan")

if bResult == true then
  Dialogs.MessageBox("¡Hola " .. sAnswer .. "!", "¡Bienvenido!", 0x0040)
end

(Volver arriba)

3.5. Biblioteca UTF-8

Esta biblioteca proporciona soporte básico para la codificación UTF-8.

Proporciona todas las funciones en la tabla LazUtf8.

-- Imprimir pares de valores en formato "posición : carácter"
for iPos, sChar in LazUtf8.Next(String) do
  DC.LogWrite(iPos .. " : " .. sChar)
end

(Volver arriba)

3.6. Biblioteca de caracteres

Esta biblioteca contiene funciones para verificar si un carácter pertenece a una categoría Unicode específica y para obtener la categoría de un carácter.

Lista de funciones disponibles en esta biblioteca:

Además, estas funciones admiten el uso de dos parámetros: podemos especificar una cadena y la posición de un carácter en esa cadena en lugar de un solo carácter.

(Volver arriba)

3.7. Biblioteca del sistema operativo

Esta biblioteca contiene funciones relacionadas con el sistema operativo en el que se ejecuta Double Commander.

A continuación se muestra la lista de funciones disponibles en esta biblioteca:

(Volver arriba)

4. Índice

(Volver arriba)   Caja de herramientas it365