2.15. Scripts Lua

Conteúdo

1. Introdução

2. DLLs necessárias

3. Bibliotecas de funções do Double Commander

3.1. Biblioteca DC

3.1.1. Exemplo de uso de DC.ExecuteCommand

3.2. Biblioteca do Sistema

3.2.1. Detalhes dos valores de retorno de SysUtils.FileGetAttr

3.2.2. Exemplo de uso de SysUtils.FileGetAttr

3.2.3. Exemplo de uso de FindFirst, FindNext e FindClose

3.3. Biblioteca da Área de Transferência

3.3.1. Exemplo de uso da biblioteca da Área de Transferência

3.4. Biblioteca de Diálogos

3.4.1. Botões exibidos em Dialogs.MessageBox

3.4.2. Estilos de janela de Dialogs.MessageBox

3.4.3. Botão padrão ativo de Dialogs.MessageBox

3.4.4. Valores de retorno de Dialogs.MessageBox

3.4.5. Exemplo de uso de Dialogs.MessageBox

3.4.6. Exemplo de uso de Dialogs.InputQuery

3.5. Biblioteca UTF-8

3.6. Biblioteca de Caracteres

3.7. Biblioteca do Sistema Operacional

4. Índice

1. Introdução

Para informações detalhadas sobre a linguagem de programação de scripts Lua, visite o site da Lua.

O Double Commander pode executar scripts Lua através do comando cm_ExecuteScript.
Os parâmetros do script devem ser passados como estão, sem escape (sem aspas ou "\"), para isso precisamos usar a variável %"0: por exemplo, para o arquivo sob o cursor use %"0%p0 em vez de %p0, para o diretório atual use %"0%D em vez de %D. Caso contrário, se o Double Commander adicionar aspas automaticamente, elas serão passadas como parte do parâmetro e você terá que considerar isso.
Para obter uma lista de todos os arquivos selecionados, podemos usar variáveis (%LU, %FU ou %RU) ou comandos internos (cm_SaveSelectionToFile, cm_SaveFileDetailsToFile, cm_CopyFullNamesToClip ou cm_CopyFileDetailsToClip). Por exemplo, podemos usar %p: neste caso, o Double Commander passará os nomes de todos os arquivos selecionados em uma única linha, separados por espaços.

Também é possível escrever plugins de conteúdo usando scripts Lua; exemplos podem ser encontrados na pasta do programa (plugins/wdx/scripts). Existe uma página dedicada ao desenvolvimento de plugins no Wiki. Limitação: apenas os seguintes tipos de dados são suportados:

• ft_numeric_32 (1) – número inteiro de 32 bits com sinal;
• ft_numeric_64 (2) – número inteiro de 64 bits com sinal;
• ft_numeric_floating (3) – número de ponto flutuante;
• ft_boolean (6) – tipo booleano: true ou false;
• ft_multiplechoice (7) – permite um número limitado de escolhas de valores;
• ft_string (8) – string de texto;
• ft_fulltext (9) – texto completo (múltiplas strings de texto), usado apenas para busca em plugins;
• ft_datetime (10) – data/hora: a data retornada será convertida em uma string formatada de data e hora (o valor depende das suas configurações regionais).
  A data deve estar no formato Windows, mas as funções fornecidas pela Lua e pelo Double Commander para busca de arquivos usam o formato de hora Unix. Para converter, você pode usar a seguinte fórmula:
  = UnixTime * 10000000 + 116444736000000000
  Este é um número grande, então você precisará da versão de 64 bits do Double Commander ou Lua 5.3+.

A lista acima contém os nomes nos arquivos de cabeçalho; nos scripts Lua devemos usar os valores numéricos especificados entre parênteses.

Sobre a codificação de texto

Todas as funções adicionais descritas abaixo aceitam argumentos de string codificados em UTF-8 e retornam strings nesta codificação (exceto a função LazUtf8.ConvertEncoding).

Algumas funções das bibliotecas padrão Lua foram substituídas por funções do Double Commander ou Free Pascal/Lazarus (ou novas funções foram escritas), o que fornece suporte a UTF-8.

Ao escrever plugins, também devemos usar UTF-8 para dados de texto (ft_multiplechoice, ft_string e ft_fulltext).

Ao salvar scripts, use a codificação UTF-8 sem BOM.

Notas de cautela

O uso de Lua para automação oferece grandes possibilidades, mas em alguns casos pode ser necessário prestar atenção a alguns detalhes. Vamos tentar reunir esses itens nesta subseção.

1. Se as opções Atualização automática e Carregar listas de arquivos em uma thread separada estiverem habilitadas, a função de atualização funcionará de forma assíncrona. Ao mesmo tempo, o script é executado na thread principal do Double Commander, portanto, em alguns casos, tudo isso pode afetar a execução do seu script. Por exemplo, às vezes a execução consecutiva de comandos de navegação pode não funcionar (por exemplo, diretórios grandes, discos lentos), neste caso tente desabilitar Carregar listas de arquivos em uma thread separada ou procure por soluções alternativas.

Se o seu script cria novos arquivos ou renomeia os existentes no painel atual, mas depois não termina e executa algumas ações adicionais (por exemplo, selecionar arquivos ou mover o cursor), em alguns casos essas ações não surtirão efeito: nem todos os arquivos podem já estar no painel e você precisa chamar o comando cm_Refresh primeiro. Sob as condições descritas, cm_Refresh também será executado de forma assíncrona e o Double Commander pode não ter tempo de atualizar completamente a lista de arquivos após as suas alterações.

A atualização automática e o carregamento de listas de arquivos em uma thread separada são funções convenientes do gerenciador de arquivos, então um método de trabalho estável foi encontrado através de experimentação, ou seja, retornar temporariamente o controle ao programa e permitir que a lista de arquivos seja completamente atualizada:

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

2. A função Lua io.open usa a função C padrão fopen: no modo de texto, esta função pode converter tipos de final de linha (CRLF, LF ou CR) ao ler e escrever, o que pode levar a resultados inesperados. Se você encontrar arquivos com diferentes tipos de finais de linha ou estiver escrevendo scripts multiplataforma, deve considerar isso ou, o que é mais prático, preferir o uso do modo binário.

3. No Linux e outros sistemas operacionais tipo Unix, para o diálogo de Propriedades do arquivo, a função ContentGetValue é chamada com a flag CONTENT_DELAYIFSLOW (o quarto parâmetro, valor igual a 1), o que evita atrasos ao abrir janelas: se a recuperação de dados for lenta, podemos excluir esses dados simplesmente adicionando uma verificação do valor da flag e retornando nil para esses campos ou plugins.

4. Se o plugin deve retornar uma string vazia, passar nil é mais rápido do que passar "".

(Voltar ao topo)

2. DLLs necessárias

Para poder interpretar arquivos de script Lua, precisamos de um arquivo DLL Lua, o Double Commander suporta as versões 5.1 - 5.4.

Podemos usar arquivos DLL do projeto LuaJIT. O LuaJIT combina um interpretador de alta velocidade escrito em assembler com um compilador JIT avançado. Além disso, obtemos a biblioteca FFI, que permite chamar funções C externas e usar estruturas de dados C a partir de código Lua puro.

As versões Windows do DC incluem a DLL Lua por padrão (a partir do DC 0.9.7 do projeto LuaJIT), em outros casos podemos encontrá-la e instalá-la via gerenciador de pacotes ou compilá-la nós mesmos. Se estivermos usando a versão de 64 bits do DC, a DLL também deve ser de 64 bits.

Por padrão, o DC procurará nos seus diretórios e diretórios do sistema por arquivos chamados lua5.1.dll (Windows), liblua5.1.so.0 (Unix ou GNU/Linux) ou liblua5.1.dylib (macOS). Podemos alterar o nome do arquivo (e o caminho) no parâmetro Arquivo de biblioteca Lua a ser usado.

(Voltar ao topo)

3. Bibliotecas de funções do Double Commander

O Double Commander fornece algumas bibliotecas de funções para nossos scripts Lua.

Abaixo está a lista dessas bibliotecas.

(Voltar ao topo)

3.1. Biblioteca DC

Esta biblioteca contém funções específicas do Double Commander.

Ela fornece todas as funções na tabela DC.

Além dos comandos internos, nos scripts também podemos usar o comando especial cm_ExecuteToolBarItem, que permite chamar um botão da barra de ferramentas através de um identificador (no programa, este recurso fornece a funcionalidade de usar atalhos para botões da barra de ferramentas). O comando é usado de forma semelhante a um comando interno normal (veja exemplo abaixo) e possui os seguintes parâmetros:

O identificador único é armazenado na tag ID, temos várias formas de obtê-lo: o botão pode ser encontrado no arquivo doublecmd.xml, no arquivo de backup da barra de ferramentas ou simplesmente copiar o botão para a área de transferência e colar seu código em um editor de texto.

Nota: Identificadores são gerados automaticamente e não precisam corresponder a identificadores de botões semelhantes em outra cópia do programa, mas podemos definir nossos próprios valores manualmente, se necessário.

(Voltar ao topo)

3.1.1. Exemplo de uso de DC.ExecuteCommand

Neste exemplo, escrevemos um script simples que fará o seguinte:

1. Focar no painel direito
2. Fechar todas as abas abertas
3. Mudar para uma pasta específica
4. Focar no painel esquerdo
5. Fechar todas as abas abertas
6. Mudar para uma pasta específica
7. Abrir uma nova aba
8. Mudar para uma pasta específica

-- 1. Focar no painel direito.
DC.ExecuteCommand("cm_FocusSwap", "side=right")

-- 2. Fechar todas as abas.
DC.ExecuteCommand("cm_CloseAllTabs")

-- 3. Mudar para um diretório específico.
DC.ExecuteCommand("cm_ChangeDir", "E:\\FakeKey\\Documents\\Music")

-- 4. Focar no painel esquerdo.
DC.ExecuteCommand("cm_FocusSwap", "side=left")

-- 5. Fechar todas as abas.
DC.ExecuteCommand("cm_CloseAllTabs")

-- 6. Mudar para um diretório específico.
DC.ExecuteCommand("cm_ChangeDir", "C:\\Users\\Public\\Music")

-- 7. Abrir uma nova aba.
DC.ExecuteCommand("cm_NewTab")

-- 8. Mudar para um diretório específico.
DC.ExecuteCommand("cm_ChangeDir", "E:\\VirtualMachines\\ShareFolder")

Usando o comando interno cm_ExecuteScript, podemos configurar um botão na barra de ferramentas para executar nosso script.

Supondo que este arquivo de script seja E:\scripts\lua\music.lua, poderíamos configurar o botão desta forma:

Além disso, também podemos usar o editor interno do Double Commander para editar scripts. Se o nome do arquivo tiver a extensão .lua, o editor interno o reconhecerá e fornecerá realce de sintaxe para a linguagem Lua:

(Voltar ao topo)

3.2. Biblioteca do Sistema

Esta biblioteca contém várias funções do sistema.

Ela fornece todas as funções na tabela SysUtils.

(Voltar ao topo)

3.2.1. Detalhes dos valores de retorno de SysUtils.FileGetAttr

FileGetAttr retorna as configurações de atributos para o arquivo sFileName.

Os atributos são uma combinação OR das seguintes constantes:

Veja o exemplo na próxima seção.

(Voltar ao topo)

3.2.2. Exemplo de uso de SysUtils.FileGetAttr

O seguinte script é um exemplo do uso de SysUtils.FileGetAttr.

Quando detectado que o argumento é um diretório, ele abrirá uma nova aba no painel ativo e mudará para esse diretório.

local params = {...}
local iAttr

if #params == 1 then -- obtivemos pelo menos um argumento?
  iAttr = SysUtils.FileGetAttr(params[1])
  if iAttr > 0 then -- obtivemos um atributo válido?
    if math.floor(iAttr / 0x00000010) % 2 ~= 0 then
      -- O 4º bit está definido? Então é um diretório.
      DC.ExecuteCommand("cm_NewTab")
      DC.ExecuteCommand("cm_ChangeDir", params[1])
    end
  end
end

No exemplo acima, params[1] é o primeiro argumento passado para o script.

Ao usar o comando interno cm_ExecuteScript, ele será o primeiro parâmetro passado após o nome do arquivo do script.

Portanto, no nosso exemplo, poderíamos configurar um botão na barra de ferramentas como abaixo:

Neste exemplo, o parâmetro %"0%p será passado para o script. Isso representará o nome do arquivo do item atualmente sob o cursor no painel ativo sem aspas.

(Voltar ao topo)

3.2.3. Exemplo de uso de FindFirst, FindNext e FindClose

No exemplo de script abaixo, vamos escanear o conteúdo do diretório recebido como parâmetro e armazenar os dados resultantes em um arquivo de texto com o nome passado como segundo parâmetro.

Isso nos dará uma boa ideia do uso de FindFirst, FindNext e FindClose.

local params = {...}

if #params == 2 then -- obtivemos dois argumentos?
  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

No exemplo acima, precisamos passar dois parâmetros para o script:

1. params[1] - o diretório cujo conteúdo queremos
2. params[2] - o nome do arquivo de saída para armazenar o resultado

Portanto, é muito fácil fazer tudo isso configurando um botão na barra de ferramentas com o comando interno cm_ExecuteScript e passando os parâmetros.

Neste exemplo, o parâmetro %"0%Ds será passado para o script como o primeiro argumento. Isso representará o diretório exibido pelo painel ativo sem aspas.

(Voltar ao topo)

3.3. Biblioteca da Área de Transferência

O Double Commander pode fornecer funcionalidade de área de transferência externa para nossos scripts Lua.

A tabela abaixo apresenta as funções relacionadas:

(Voltar ao topo)

3.3.1. Exemplo de uso da biblioteca da Área de Transferência

O seguinte exemplo utiliza as três funções relacionadas à área de transferência: Clear, GetAsText e SetAsText.

É um script relativamente longo, mas combina bem algumas das funções que vimos acima.

Assume que nosso painel ativo está atualmente localizado em um diretório que contém muitos arquivos de texto de origem.

Também assume que temos atualmente uma palavra na área de transferência e que receberá a pasta ativa atual como parâmetro único.

O script escaneará os arquivos no nível atual do diretório e lerá seu conteúdo um por um para detectar as linhas de texto que contêm a palavra que estava na área de transferência.

Então, o nome do arquivo que contém pelo menos uma linha com essa palavra será colocado na área de transferência.

O script então usará o comando interno cm_LoadSelectionFromClip e os arquivos que contêm a palavra serão selecionados.

Além disso, ao final, colocaremos a palavra original que precisávamos pesquisar de volta na área de transferência.

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 -- obtivemos o parâmetro?
  sSearchString = Clipbrd.GetAsText() -- obter a expressão a ser pesquisada.
  Clipbrd.Clear() -- certificar que não há nada na área de transferência.
  DC.ExecuteCommand("cm_MarkUnmarkAll") -- certificar que nada está selecionado.

  -- vamos escanear todos os arquivos do diretório um por um.
  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 -- obtivemos um atributo válido?
        -- precisamos de arquivos, não diretórios!
        if math.floor(iAttr / 0x00000010) % 2 == 0 then

          -- agora vamos ler o arquivo linha por linha até o fim ou encontrar.
          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 encontramos algo, selecione!
  if sFileToSelect ~= "" then
    Clipbrd.SetAsText(sFileToSelect)
    DC.ExecuteCommand("cm_LoadSelectionFromClip")
  end

  Clipbrd.SetAsText(sSearchString) -- restaurar o que tínhamos na área de transferência.
end

(Voltar ao topo)

3.4. Biblioteca de Diálogos

Esta biblioteca permite que nossos scripts interajam com o usuário, exibindo mensagens, solicitando respostas, etc.

A tabela abaixo lista as funções relacionadas:

(Voltar ao topo)

3.4.1. Botões exibidos em Dialogs.MessageBox

Os botões exibidos pela função Dialogs.MessageBox são controlados pelos valores bitwise OR das seguintes constantes:

Constantes ButFlags para exibição de botões em Dialogs.MessageBox
Valor da constante	Botões exibidos, da esquerda para a direita
0x0000 MB_OK
0x0001 MB_OKCANCEL
0x0002 MB_ABORTRETRYIGNORE
0x0003 MB_YESNOCANCEL
0x0004 MB_YESNO
0x0005 MB_RETRYCANCEL

(Voltar ao topo)

3.4.2. Estilos de janela de Dialogs.MessageBox

Os estilos de janela exibidos pela função Dialogs.MessageBox são controlados pelos valores bitwise OR das seguintes constantes:

Constantes ButFlags para ícones e estilos de Dialogs.MessageBox
Valor da constante	Estilo da janela
0x0040 MB_ICONINFORMATION	Janela de informação
0x0030 MB_ICONWARNING	Janela de aviso
0x0020 MB_ICONQUESTION	Janela de confirmação
0x0010 MB_ICONERROR	Janela de erro

(Voltar ao topo)

3.4.3. Botão padrão ativo de Dialogs.MessageBox

O botão padrão ativo exibido pela função Dialogs.MessageBox é controlado pelos valores bitwise OR das seguintes constantes:

(Voltar ao topo)

3.4.4. Valores de retorno de Dialogs.MessageBox

O número retornado pela função Dialogs.MessageBox indica o botão que o usuário pressionou, conforme abaixo:

Valores ButPressed retornados ao pressionar botões em Dialogs.MessageBox
Valor da constante	Botão pressionado
0x0000 mrNone	Nenhum botão pressionado
0x0001 mrOK
0x0002 mrCancel
0x0003 mrAbort
0x0004 mrRetry
0x0005 mrIgnore
0x0006 mrYes
0x0007 mrNo

Nota: se você fechar a janela pressionando o "x" no canto superior direito ou pressionando Esc, o valor do botão "Cancelar" será retornado.

(Voltar ao topo)

3.4.5. Exemplo de uso de Dialogs.MessageBox

Abaixo está um pequeno script usando Dialogs.MessageBox e a janela resultante que será exibida:

-- Botões exibidos
MB_OK = 0x0000
MB_OKCANCEL = 0x0001
MB_ABORTRETRYIGNORE = 0x0002
MB_YESNOCANCEL = 0x0003
MB_YESNO = 0x0004
MB_RETRYCANCEL = 0x0005

-- Estilo da janela
MB_ICONINFORMATION = 0x0040
MB_ICONWARNING = 0x0030
MB_ICONQUESTION = 0x0020
MB_ICONERROR = 0x0010

-- Botão padrão
MB_DEFBUTTON1 = 0x0000
MB_DEFBUTTON2 = 0x0100
MB_DEFBUTTON3 = 0x0200

-- Retorno do botão pressionado
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("Você deseja sair?", "Questão", iFlags)

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

(Voltar ao topo)

3.4.6. Exemplo de uso de Dialogs.InputQuery

Abaixo está um pequeno script usando Dialogs.InputQuery e a janela resultante que será exibida:

bResult, sAnswer = Dialogs.InputQuery("Autenticação", "Por favor, insira seu nome:", false, "João")

if bResult == true then
  Dialogs.MessageBox("Olá " .. sAnswer .. "!", "Bem-vindo!", 0x0040)
end

(Voltar ao topo)

3.5. Biblioteca UTF-8

Esta biblioteca fornece suporte básico para codificação UTF-8.

Ela fornece todas as funções na tabela LazUtf8.

-- imprimir pares de valores na forma "posição : caractere"
for iPos, sChar in LazUtf8.Next(String) do
  DC.LogWrite(iPos .. " : " .. sChar)
end

(Voltar ao topo)

3.6. Biblioteca de Caracteres

Esta biblioteca contém funções para verificar se os caracteres pertencem a certas categorias Unicode, bem como funções para obter a categoria do caractere.

Lista de funções disponíveis nesta biblioteca:

Além disso, essas funções suportam o uso de dois parâmetros: podemos especificar uma string e a posição do caractere nessa string, em vez de um único caractere.

(Voltar ao topo)

3.7. Biblioteca do Sistema Operacional

Esta biblioteca contém funções relacionadas ao sistema operacional no qual o Double Commander está sendo executado.

Abaixo está a lista de funções disponíveis nesta biblioteca:

(Voltar ao topo)

4. Índice

(Voltar ao topo)   Caixa de ferramentas it365