CGILua: geração de scripts para a Web usando Lua

Introdução

O CGILua usa Lua como a linguagem de scripts do servidor para criar páginas Web dinâmicas. O CGILua oferece suporte a Lua Scripts puros e a Lua Pages (.lp). Um Lua Script é, basicamente, um programa em Lua que cria todo o conteúdo de uma página Web e o retorna para o cliente. Uma Lua Page é um arquivo de texto com marcações (HTML, XML etc.) que incorpora código Lua usando algumas tags especiais. Essas tags são processadas pelo CGILua e a página resultante é retornada para o cliente.

Os Lua Scripts e as Lua Pages são igualmente fáceis de usar e a opção por um deles depende, primariamente, das características da página resultante. Enquanto as Lua Pages são mais convenientes para separar a lógica e o formato, os Lua Scripts são mais adequados para criar páginas de estrutura mais simples, mas que requeiram uma quantidade significativamente maior de processamento interno.

Ao permitir a combinação desses dois métodos, o CGILua dá aos desenvolvedores de aplicativos Web uma maior flexibilidade quando os dois requisitos estão presentes. Para obter uma descrição detalhada de ambos os métodos de criação de scripts e alguns exemplos práticos, consulte Lua Scripts e Lua Pages.

A arquitetura do CGILua é dividida em duas camadas. O nível inferior é representado pela API do servidor (SAPI) e o mais alto, pela API do próprio CGILua. SAPI é a interface entre o servidor Web e a API do CGILua, precisando portanto ser implementada em cada servidor Web e método de disparo empregado.

O CGILua e a API do CGILua são implementados usando-se apenas a SAPI e são totalmente transportáveis entre disparadores e os servidores Web compatíveis. Dessa maneira, qualquer Lua Script ou Lua Page pode ser usada por qualquer disparador.

Instalação

O CGILua segue o modelo de pacotes de Lua 5.1 e, conseqüentemente, precisa ser "instalado". Consulte a seção Configuração do Compat-5.1 para obter informações sobre como instalar corretamente o módulo.

Configuração

O CGILua 5.0 oferece um único arquivo de configuração, chamado config.lua, e um conjunto de funções para alterar a configuração padrão do CGILua. Esse arquivo pode ser colocado em qualquer lugar em LUA_PATH para facilitar a atualização do CGILua sem a substituição do config.lua existente.

Alguns usos do config.lua são:

Tratadores de scripts: Você pode adicionar novos tratadores de CGILua usando cgilua.addscripthandler (consulte também cgilua.buildplainhandler e cgilua.buildprocesshandler para obter as funções que criam tratadores simples).
Tamanhos de dados POST: Altere os limites de tamanho dos dados POST usando cgilua.setmaxinput e cgilua.setmaxfilesize.
Abertura e fechamento de funções: Você pode adicionar suas funções ao ciclo de vida útil do CGILua usando cgilua.addopenfunction e cgilua.addclosefunction. Essas funções são executadas imediatamente antes e depois da execução do script, mesmo quando ocorrer um erro no processamento do script.

Tratamento de erros

Há três funções para tratamento de erros no CGILua:

A função cgilua.seterrorhandler define o tratador de erro, uma função chamada pela Lua logo após ocorrer um erro. O tratador de erro tem acesso à pilha de execução antes da ocorrência do erro, assim, ele pode gerar uma mensagem de erro usando as informações da pilha. Lua também possui uma função para fazer isso: debug.traceback.

A função cgilua.seterroroutput define a função que decide o que deve ser feito com a mensagem de erro. Ele pode ser enviado para o cliente, gravado em um arquivo de log ou enviado para um endereço de email (com a ajuda do LuaSocket ou do LuaLogging, por exemplo).

A função cgilua.errorlog é fornecida para gravar diretamente no arquivo de log de erros do servidor HTTP.

Lua Scripts

Os Lua Scripts são arquivos de texto que contêm código Lua válido. Esse estilo de uso adota uma forma de programação para Web mais "rústica", na qual um programa é responsável pela geração da página resultante. Os Lua Scripts têm a extensão padrão .lua.

Para gerar um documento Web (HTML, XML, WML, CSS etc.) válido, o Lua Script deve obedecer a uma ordem esperada pelo HTTP para produzir a saída, primeiro enviando os cabeçalhos corretos e, depois, enviando o conteúdo real do documento.

O CGILua tem algumas funções que facilitam essas tarefas, por exemplo, cgilua.htmlheader para produzir o cabeçalho de um documento HTML e cgilua.put para enviar o conteúdo do documento (ou parte dele).

Por exemplo, um documento HTML que exiba a frase "Olá mundo!" pode ser gerado com este Lua Script:

cgilua.htmlheader()
cgilua.put([[
<html>
<head>
  <title>Olá mundo</title>
</head>
<body>
  <strong>Olá mundo!</strong>
</body>
</html>]])

Observe que o exemplo acima gera uma página "fixa": embora ela seja gerada no momento da execução, a página não contém informações "variáveis". Isso significa que o mesmo documento poderia ser gerado diretamente com um simples arquivo HTML estático. No entanto, os Lua Scripts são especialmente úteis quando o documento contém informações que não sejam conhecidas de antemão ou que mudem de acordo com os parâmetros passados. Nesse caso, é necessário gerar uma página "dinâmica".

Outro exemplo fácil pode ser mostrado, desta vez, usando uma estrutura de controle Lua, variáveis e o operador de concatenação:

cgilua.htmlheader()

if cgi.language == 'english' then
  greeting = 'Hello World!'
elseif cgi.language == 'portuguese' then
  greeting = 'Olá Mundo!'
else
  greeting = '[unknown language]'
end

cgilua.put('<html>')  
cgilua.put('<head>')
cgilua.put('  <title>'..greeting..'</title>')
cgilua.put('</head>')
cgilua.put('<body>')
cgilua.put('  <strong>'..greeting..'</strong>')
cgilua.put('</body>')
cgilua.put('</html>')

No exemplo acima, o uso de cgi.language indica que language foi passado para o Lua Script como um parâmetro do CGILua, oriundo de um campo de formulário HTML (via POST) ou da URL usada para ativá-lo (via GET). O CGILua decodifica automaticamente esses parâmetros para que você possa usá-los à vontade em Lua Scripts e Lua Pages.

Lua Pages

Uma Lua Page é um arquivo de modelo (template) com texto que será processado pelo CGILua antes de o servidor HTTP enviá-lo para o cliente. O CGILua não processa o texto, ele procura algumas marcações especiais que inserem o código Lua no arquivo. Depois que essas marcações são processadas e mescladas no arquivo de template, os resultados são enviados para o cliente.

As Lua Pages têm a extensão padrão .lp. Elas são uma maneira mais simples de criar uma página dinâmica porque eliminam a necessidade de enviar os cabeçalhos HTTP. Em geral, Lua Pages são páginas HTML, portanto, o CGILua envia automaticamente o cabeçalho HTML.

Como há algumas restrições quanto aos usos de cabeçalhos HTTP, ocasionalmente, será preciso usar um Lua Script em vez de uma Lua Page.

As marcações fundamentais de uma Lua Page são:

<?lua chunk ?>: Processa e mescla os resultados da execução do chunk Lua, no qual a marcação está localizada no template. A forma alternativa <% chunk %> também pode ser usada.
<?lua= expression ?>: Processa e mescla a avaliação de uma expression em Lua, na qual a marcação está localizada no template. A forma alternativa <%= expression %> também pode ser usada.

Observe que a marcação de término não pode estar dentro de um chunk de código ou uma expressão Lua, mesmo que esteja entre aspas. O pré-processador de Lua Pages apenas faz substituições globais no template, procurando um par correspondente de marcações e gerando o código Lua correspondente para obter o mesmo resultado que o Lua Script equivalente.

O segundo exemplo da seção anterior pode ser escrito usando uma Lua Page como esta:

<html>
<?lua
if cgi.language == 'english' then
  greeting = 'Hello World!'
elseif cgi.language == 'portuguese' then
  greeting = 'Olá Mundo!'
else
  greeting = '[unknown language]'
end
?>
<head>
  <title><%= greeting %></title>
</head>
<body>
  <>strong<%= greeting %></strong>
</body>
</html>

As tags HTML e as tags de Lua Page podem ser livremente intercambiadas. Porém, como ocorre em outras linguagens de template, considera-se uma boa prática não usar lógica Lua explícita em templates. A abordagem recomendada é usar apenas chamadas de funções que retornam chunks de conteúdo, dessa forma, nesse exemplo, pressupondo-se que a função getGreeting tenha sido definida em outro ponto como

function getGreeting()
  local greeting
  if cgi.language == 'english' then
    greeting = 'Hello World!'
  elseif cgi.language == 'portuguese' then
    greeting = 'Olá Mundo!'
  else
    greeting = '[unknown language]'
  end
  return greeting
end

a Lua Page poderia ser reescrita desta maneira:

<html>
<head>
  <title><%= getGreeting() %></title>
</head>
<body>
  <strong><%= getGreeting() %></strong>
</body>
</html>

Recebimento de parâmetros: a tabela `cgi`

O CGILua oferece uma maneira unificada de acessar dados passados para os scripts no método HTTP usado (GET ou POST). Independentemente do método usado no cliente, todos os parâmetros serão fornecidos dentro da tabela cgi.

Normalmente, todos os tipos de parâmetros estarão disponíveis como strings. Se o valor de um parâmetro for um número, ele será convertido na representação de string correspondente.

Há apenas duas exceções nas quais o valor será uma tabela Lua. O primeiro caso ocorre em uploads de arquivos, no qual a tabela correspondente terá estes campos:

filename: o nome do arquivo como fornecido pelo cliente.
filesize: o tamanho do arquivo em bytes.
file: o handler do arquivo temporário. O arquivo deve ser copiado porque o CGILua o removerá após a conclusão do script.

O outro caso que usa tabelas Lua ocorre quando há mais de um valor associado ao mesmo nome de parâmetro. Isso acontece no caso de uma lista de seleção com vários valores; mas também ocorre quando o formulário tiver dois ou mais elementos com o mesmo atributo name (possivelmente porque um estava em um formulário e o outro, na query string). Todos os valores serão inseridos em uma tabela indexada, na ordem em que foram tratados.

CGILua