1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<title>CGILua: geração de scripts para a Web usando Lua</title>
<link rel="stylesheet" href="http://www.keplerproject.org/doc.css" type="text/css"/>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
</head>
<body>
<div id="container">
<div id="product">
<div id="product_logo"><a href="http://www.keplerproject.org"><img alt="Logotipo do CGILua" src="cgi-128.gif"/></a></div>
<div id="product_name"><big><strong>CGILua</strong></big></div>
<div id="product_description">Geração de scripts para a Web usando Lua</div>
</div> <!-- id="product" -->
<div id="main">
<div id="navigation">
<h1>CGILua</h1>
<ul>
<li><a href="index.html">Início</a>
<ul>
<li><a href="index.html#overview">Visão geral</a></li>
<li><a href="index.html#status">Status</a></li>
<li><a href="index.html#download">Download</a></li>
<li><a href="index.html#history">Histórico</a></li>
<li><a href="index.html#incompatibility">Incompatibilidades</a></li>
<li><a href="index.html#credits">Créditos</a></li>
<li><a href="index.html#contact">Fale conosco</a></li>
</ul>
</li>
<li><strong>Manual</strong>
<ul>
<li><a href="manual.html#intro">Introdução</a></li>
<li><a href="manual.html#installation">Instalação</a></li>
<li><a href="manual.html#config">Configuração</a></li>
<li><a href="manual.html#scripts">Lua Scripts</a></li>
<li><a href="manual.html#templates">Lua Pages</a></li>
<li><a href="manual.html#parameters">Parâmetros</a></li>
</ul>
</li>
<li><a href="reference.html">Referência</a>
<ul>
<li><a href="reference.html#headers">Cabeçalhos</a></li>
<li><a href="reference.html#contents">Geração de conteúdo</a></li>
<li><a href="reference.html#prep">Lua Pages</a></li>
<li><a href="reference.html#variables">Variáveis do CGILua</a></li>
<li><a href="reference.html#error_handling">Tratamento de erros</a></li>
<li><a href="reference.html#behavior">Comportamento do CGILua</a></li>
<li><a href="reference.html#urlcode">Codificação de URL</a></li>
<li><a href="reference.html#auxiliar">Funções auxiliares</a></li>
<li><a href="reference.html#index">Índice alfabético</a></li>
</ul>
</li>
<li><a href="libraries.html">Bibliotecas</a>
<ul>
<li><a href="libraries.html#cookies">Cookies</a></li>
<li><a href="libraries.html#serialize">Serialize</a></li>
<li><a href="libraries.html#session">Session</a></li>
</ul>
</li>
<li><a href="sapi.html">SAPI</a></li>
<li><a href="license.html">Licenças</a></li>
</ul>
</div> <!-- id="navigation" -->
<div id="content">
<h2><a name="intro"></a>Introdução</h2>
<p>O CGILua usa <a href="http://www.lua.org">Lua</a> como a linguagem de scripts do servidor para criar páginas Web dinâmicas. O CGILua oferece suporte a <a href="manual.html#scripts">Lua Scripts</a> puros e a <a href="manual.html#templates">Lua Pages</a> (.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.</p>
<p>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.</p>
<p>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 <a href="#scripts">Lua Scripts</a> e <a href="#templates">Lua Pages</a>.</p>
<p>A arquitetura do CGILua é dividida em duas camadas. O nível inferior é representado pela API do servidor (<a href="sapi.html">SAPI</a>) 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.</p>
<p>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.</p>
<h2><a name="installation"></a>Instalação</h2>
<p>O CGILua segue o <a href="http://www.keplerproject.org/compat/">modelo de pacotes</a> de Lua 5.1 e, conseqüentemente, precisa ser "instalado". Consulte a seção <a href="http://www.keplerproject.org/compat/manual.html#configuration">Configuração do Compat-5.1</a> para obter informações sobre como instalar corretamente o módulo.</p>
<h2><a name="config"></a>Configuração</h2>
<p>O CGILua 5.0 oferece um único arquivo de configuração, chamado <code>config.lua</code>, e um conjunto de funções para alterar a configuração padrão do CGILua. Esse arquivo pode ser colocado em qualquer lugar em <code>LUA_PATH</code> para facilitar a atualização do CGILua sem a substituição do <code>config.lua</code> existente.</p>
<p>Alguns usos do <code>config.lua</code> são:</p>
<dl>
<dt><strong>Tratadores de scripts</strong></dt>
<dd>Você pode adicionar novos tratadores de CGILua usando <a href="reference.html#addscripthandler"><code>cgilua.addscripthandler</code></a> (consulte também <a href="reference.html#buildplainhandler"><code>cgilua.buildplainhandler</code></a> e <a href="reference.html#buildprocesshandler"><code>cgilua.buildprocesshandler</code></a> para obter as funções que criam tratadores simples).
</dd>
<dt><strong>Tamanhos de dados POST</strong></dt>
<dd>Altere os limites de tamanho dos dados POST usando <a href="reference.html#setmaxinput"><code>cgilua.setmaxinput</code></a> e <a href="reference.html#setmaxfilesize"><code>cgilua.setmaxfilesize</code></a>.
</dd>
<dt><strong>Abertura e fechamento de funções</strong></dt>
<dd>Você pode adicionar suas funções ao ciclo de vida útil do CGILua usando <a href="reference.html#addopenfunction"><code>cgilua.addopenfunction</code></a> e <a href="reference.html#addclosefunction"><code>cgilua.addclosefunction</code></a>. Essas funções são executadas imediatamente antes e depois da execução do script, mesmo quando ocorrer um erro no processamento do script.</dd>
</dl>
<h2><a name="error_handling"></a>Tratamento de erros</h2>
<p>Há três funções para tratamento de erros no CGILua:</p>
<p>A função <a href="reference.html#seterrorhandler"><code>cgilua.seterrorhandler</code></a> define o <em>tratador de erro</em>, 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: <code>debug.traceback</code>.</p>
<p>A função <a href="reference.html#seterroroutput"><code>cgilua.seterroroutput</code></a> 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 <a href="http://luasocket.luaforge.net/">LuaSocket</a> ou do <a href="http://www.keplerproject.org/lualogging/">LuaLogging</a>, por exemplo).</p>
<p>A função <a href="reference.html#errorlog"><code>cgilua.errorlog</code></a> é fornecida para gravar diretamente no arquivo de log de erros do servidor HTTP.</p>
<h2><a name="scripts"></a>Lua Scripts</h2>
<p>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 <code>.lua</code>.</p>
<p>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 <a href="reference.html#headers">cabeçalhos</a> corretos e, depois, enviando o <a href="reference.html#contents">conteúdo</a> real do documento.</p>
<p>O CGILua tem algumas funções que facilitam essas tarefas, por exemplo, <a href="reference.html#htmlheader"><code>cgilua.htmlheader</code></a> para produzir o cabeçalho de um documento HTML e <a href="reference.html#put"><code>cgilua.put</code></a> para enviar o conteúdo do documento (ou parte dele).</p>
<p>Por exemplo, um documento HTML que exiba a frase "Olá mundo!" pode ser gerado com este Lua Script:</p>
<pre class="example">
cgilua.htmlheader()
cgilua.put([[
<html>
<head>
<title>Olá mundo</title>
</head>
<body>
<strong>Olá mundo!</strong>
</body>
</html>]])
</pre>
<p>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".</p>
<p>Outro exemplo fácil pode ser mostrado, desta vez, usando uma estrutura de controle Lua, variáveis e o operador de concatenação:</p>
<pre class="example">
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>')
</pre>
<p>No exemplo acima, o uso de <code><em>cgi.language</em></code> indica que <em>language</em> foi passado para o Lua Script como um <a href="manual.html#parameters">parâmetro do CGILua</a>, 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.</p>
<h2><a name="templates"></a>Lua Pages</h2>
<p>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.</p>
<p>As Lua Pages têm a extensão padrão <code>.lp</code>. 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.</p>
<p>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.</p>
<p>As marcações fundamentais de uma Lua Page são:</p>
<dl>
<dt><strong><code><?lua <em>chunk</em> ?></code></strong></dt>
<dd>Processa e mescla os resultados da execução do <em>chunk</em> Lua, no qual a marcação está localizada no template. A forma alternativa <code><% <em>chunk</em> %></code> também pode ser usada.</dd>
<dt><strong><code><?lua= <em>expression</em> ?></code></strong></dt>
<dd>Processa e mescla a avaliação de uma <em>expression</em> em Lua, na qual a marcação está localizada no template. A forma alternativa <code><%= <em>expression</em> %></code> também pode ser usada.</dd>
</dl>
<p>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.</p>
<p>O segundo exemplo da seção anterior pode ser escrito usando uma Lua Page como esta:</p>
<pre class="example">
<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>
</pre>
<p>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 <code>getGreeting</code> tenha sido definida em outro ponto como</p>
<pre class="example">
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
</pre>
<p>a Lua Page poderia ser reescrita desta maneira:</p>
<pre class="example">
<html>
<head>
<title><%= getGreeting() %></title>
</head>
<body>
<strong><%= getGreeting() %></strong>
</body>
</html>
</pre>
<h2><a name="parameters"></a>Recebimento de parâmetros: a tabela <code>cgi</code></h2>
<p>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 <code>cgi</code>.</p>
<p>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.</p>
<p>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:</p>
<dl>
<dt><strong>filename</strong></dt>
<dd>o nome do arquivo como fornecido pelo cliente.</dd>
<dt><strong>filesize</strong></dt>
<dd>o tamanho do arquivo em bytes.</dd>
<dt><strong>file</strong></dt>
<dd>o <em>handler</em> do arquivo temporário. O arquivo deve ser copiado porque o CGILua o removerá após a conclusão do script.</dd>
</dl>
<p>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 <code>name</code> (possivelmente porque um estava em um formulário e o outro, na <em>query string</em>). Todos os valores serão inseridos em uma tabela indexada, na ordem em que foram tratados.</p>
</div> <!-- id="content" -->
</div> <!-- id="main" -->
<div id="about">
<p><a href="http://validator.w3.org/check?uri=referer">valid</a></p>
<p><small>$Id: manual.html,v 1.3 2005/11/03 18:48:57 carregal Exp $</small></p>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>
</html>
|
