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
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>CGILua: Building Web Scripts with 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="CGILua logo" src="cgi-128.gif"/>
</a></div>
<div id="product_name"><big><strong>CGILua</strong></big></div>
<div id="product_description">Building Web Scripts with Lua</div>
</div> <!-- id="product" -->
<div id="main">
<div id="navigation">
<h1>CGILua</h1>
<ul>
<li><a href="index.html">Home</a>
<ul>
<li><a href="index.html#overview">Overview</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">History</a></li>
<li><a href="index.html#incompatibility">Incompatibilities</a></li>
<li><a href="index.html#credits">Credits</a></li>
<li><a href="index.html#contact">Contact us</a></li>
</ul>
</li>
<li><a href="manual.html">Manual</a>
<ul>
<li><a href="manual.html#intro">Introduction</a></li>
<li><a href="manual.html#installation">Installation</a></li>
<li><a href="manual.html#config">Configuration</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">Parameters</a></li>
<li><a href="manual.html#dispatching">Dispatching</a></li>
<li><a href="manual.html#authentication">Authentication</a></li>
<li><a href="manual.html#error_handling">Error Handling</a></li>
</ul>
</li>
<li><strong>Reference</strong>
<ul>
<li><a href="reference.html#headers">Headers</a></li>
<li><a href="reference.html#contents">Content Generation</a></li>
<li><a href="reference.html#prep">Lua Pages</a></li>
<li><a href="reference.html#variables">CGILua Variables</a></li>
<li><a href="reference.html#error_handling">Error Handling</a></li>
<li><a href="reference.html#behavior">CGILua Behavior</a></li>
<li><a href="reference.html#urlcode">URL Encoding</a></li>
<li><a href="reference.html#auxiliar">Auxiliary functions</a></li>
<li><a href="reference.html#index">Alphabetic Index</a></li>
</ul>
</li>
<li><a href="libraries.html">Libraries</a>
<ul>
<li><a href="libraries.html#authentication">Authentication</a></li>
<li><a href="libraries.html#cookies">Cookies</a></li>
<li><a href="libraries.html#dispatcher">Dispatcher</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">License</a></li>
</ul>
</div> <!-- id="navigation" -->
<div id="content">
<h2><a name="headers"></a>Headers</h2>
<p>Headers functions are used to change the HTTP response headers and consist of:</p>
<dl class="reference">
<dt><a name="contentheader"></a><strong><code>cgilua.contentheader (type, subtype)</code></strong></dt>
<dd>Sends a <em>Content-type</em> header with the given values of type and
sub-type.<br/>
Both arguments are strings: <code>type</code> is the header type;
<code>subtype</code> is the header sub-type.<br/>
Returns nothing.</dd>
<dt><a name="header"></a><strong><code>cgilua.header (header, value)</code></strong></dt>
<dd>Sends a generic header. This function should <em>not</em> be used to
generate a <em>Content-type</em> nor a <em>Location</em> header because
some launchers/web-servers use different functions for this purpose.<br/>
Both arguments are strings: <code>header</code> is the name of the header;
<code>value</code> is its value.<br/>
Returns nothing.</dd>
<dt><a name="htmlheader"></a><strong><code>cgilua.htmlheader ()</code></strong></dt>
<dd>Sends the header of an HTML file (<em>Content-type: text/html</em>).<br/>
Returns nothing.</dd>
<dt><a name="redirect"></a><strong><code>cgilua.redirect (url, args)</code></strong></dt>
<dd>Sends the header to force a redirection to the given URL adding the
parameters in table <code>args</code> to the new URL.<br/>
The first argument (<code>url</code>) is the URL the browser should be
redirected to; the second one (<code>args</code>) is an optional table
which could have pairs <em>name = value</em> that will be encoded to form
a valid URL (see function <a href="#encodetable">cgilua.urlcode.encodetable</a>).<br/>
Returns nothing.</dd>
</dl>
<h2><a name="contents"></a>Content Generation</h2>
<p>Content generation functions are used to output text to the response and to
generate URLs in the CGILua format. They consist of:</p>
<dl class="reference">
<dt><a name="mkabsoluteurl"></a><strong><code>cgilua.mkabsoluteurl (path)</code></strong></dt>
<dd>Creates an absolute URL containing the given URL <code>path</code>.<br/>
Returns the resulting absolute URL.</dd>
<dt><a name="mkurlpath"></a><strong><code>cgilua.mkurlpath (script [, args])</code></strong></dt>
<dd>Creates an URL path to be used as a link to a CGILua <code>script</code>
using the optional table of arguments (<code>args</code>). The arguments are
used in the URL as query string parameters.<br/>
Returns the resulting URL.</dd>
<dt><a name="print"></a><strong><code>cgilua.print (...)</code></strong></dt>
<dd>Sends the given arguments to the client. This function converts all its
arguments to strings before sending them to the server thus it does not
raises errors like <a href="put">cgilua.put</a>.<br/>
Returns nothing.</dd>
<dt><a name="put"></a><strong><code>cgilua.put (...)</code></strong></dt>
<dd>Sends the given arguments to the client. This function should
always be used; do not use Lua's <code>print</code> or <code>io.write</code>
for output otherwise your script may not work for every launching method.<br/>
Returns nothing.</dd>
</dl>
<h2><a name="prep"></a>Lua Pages</h2>
<p>Lua Pages functions are used to process Lua Pages templates and to define the
behavior of this processing. They consist of:</p>
<dl class="reference">
<dt><a name="handlelp"></a><strong><code>cgilua.handlelp (filename[, env])</code></strong></dt>
<dd>Equivalent to <a href="include"><code>cgilua.lp.include</code></a> but
sends the HTML header before the pre-processed file.<br/>
Returns nothing.</dd>
<dt><a name="compile"></a><strong><code>cgilua.lp.compile (string)</code></strong></dt>
<dd>Compile a piece of code given as a string into a Lua function.
The string is translated with
<a href="#translate"><code>cgilua.lp.translate</code></a>
into another string which is transformed into a function with
<code>loadstring</code>.
The resulting function is cached internaly and reused if the same piece of
code is given.<br/>
Returns a function.</dd>
<dt><a name="include"></a><strong><code>cgilua.lp.include (filename[, env])</code></strong></dt>
<dd>Pre-processes a Lua Page template (given by <code>filename</code>) and sends the results
to the client. The file content is processed by <a href="#compile"><code>cgilua.lp.compile</code></a>
and no headers are sent. If an optional environment table is passed, the file is executed with this
environment instead of the global one. This can be used to sandbox your scripts.<br/>
Returns nothing.</dd>
<dt><a name="setcompatmode"></a><strong><code>cgilua.lp.setcompatmode (boolean)</code></strong></dt>
<dd>Turns on or off the compatibility mode. Turning it on will make the
Lua Pages preprocessor understand the <em>expression fields</em> and
<em>code fields</em> structures used by previous versions of CGILua.<br/>
Default value: <code>true</code><br/>
Returns nothing.</dd>
<dt><a name="setoutfunc"></a><strong><code>cgilua.lp.setoutfunc (funcname)</code></strong></dt>
<dd>Defines the name of the output function for templates. The Lua Pages
preprocessor will generate calls to the function with the given
<code>funcname</code> (a string).<br/>
Returns nothing.</dd>
<dt><a name="translate"></a><strong><code>cgilua.lp.translate (string)</code></strong></dt>
<dd>Uses the Lua Pages preprocessor to generate a string corresponding to
the Lua code that executes the Lua chunks and/or expressions inside the
given <code>string</code>.<br/>
Returns a string with the resulting Lua code.</dd>
</dl>
<h2><a name="variables"></a>CGILua Variables</h2>
<p>CGILua Variables offers information about the script being processed and
the <a href="sapi.html#servervariable">CGI environment variables</a> depending
on the Web server and launcher used.
They consist of both atributes and functions:</p>
<dl class="reference">
<dt><a name="script_file"></a><strong><code>cgilua.script_file</code></strong></dt>
<dd>The file name of the running script. Obtained from
<a href="#script_path"><code>cgilua.script_path</code></a>.</dd>
<dt><a name="script_path"></a><strong><code>cgilua.script_path</code></strong></dt>
<dd>The complete path of the running script. This variable is usually the
same as the <a href="sapi.html#servervariable">CGI environment variable</a>
<code>PATH_TRANSLATED</code>.</dd>
<dt><a name="script_pdir"></a><strong><code>cgilua.script_pdir</code></strong></dt>
<dd>The directory of the running script. Obtained from
<a href="#script_path"><code>cgilua.script_path</code></a>.</dd>
<dt><a name="script_vdir"></a><strong><code>cgilua.script_vdir</code></strong></dt>
<dd>The virtual directory of the running script. Obtained from
<a href="#script_vpath"><code>cgilua.script_vpath</code></a>.</dd>
<dt><a name="script_vpath"></a><strong><code>cgilua.script_vpath</code></strong></dt>
<dd>The complete virtual path of the running script. Equivalent to the
<a href="sapi.html#servervariable">CGI environment variable</a>
<code>PATH_INFO</code>.</dd>
<dt><a name="servervariable"></a><strong><code>cgilua.servervariable (varname)</code></strong></dt>
<dd>Returns a string with the value of the CGI environment variable
correspoding to <code>varname</code>. For a list of CGI variables please refer to
<a href="sapi.html#servervariable">SAPI.Request.servervariable</a></dd>
<dt><a name="tmp_path"></a><strong><code>cgilua.tmp_path</code></strong></dt>
<dd>The directory used by <a href="#tmpfile"><code>cgilua.tmpfile</code></a>.
Obtained by checking <code>os.getenv("TEMP")</code>, <code>os.getenv ("TMP")</code> and
<code>"/tmp"</code> in that order.</dd>
<dt><a name="urlpath"></a><strong><code>cgilua.urlpath</code></strong></dt>
<dd>The name of the script. Equivalent to the
<a href="sapi.html#servervariable">CGI environment variable</a>
<code>SCRIPT_NAME</code>.</dd>
</dl>
<h2><a name="error_handling"></a>Error Handling</h2>
<p>CGILua error handling functions allow the redefinition of how errors are
handled and presented to the user. The consist of:</p>
<dl class="reference">
<dt><a name="errorlog"></a><strong><code>cgilua.errorlog (string)</code></strong></dt>
<dd>Sends the given <code>string</code> to the error log file.<br/>
Returns nothing.</dd>
<dt><a name="seterrorhandler"></a><strong><code>cgilua.seterrorhandler (func)</code></strong></dt>
<dd>Sets the <em>error handler</em> function to <code>func</code>.
This function is called by Lua when an error occurs. It receives the error
message generated by Lua and it is responsible for generating and returning
the correct error message to be used by CGILua.<br/>
Returns nothing.</dd>
<dt><a name="seterroroutput"></a><strong><code>cgilua.seterroroutput (func)</code></strong></dt>
<dd>Sets the <em>error output</em> function to <code>func</code>.
This function is called by Lua to generate the error output itself.<br/>
Returns nothing.</dd>
</dl>
<h2><a name="behavior"></a>CGILua behavior</h2>
<p>The behavior of CGILua can be configured using this set of functions:</p>
<dl class="reference">
<dt><a name="addclosefunction"></a><strong><code>cgilua.addclosefunction (func)</code></strong></dt>
<dd>Defines a function (<code>func</code>) to be called after the execution
of the script requested.<br/>
Returns nothing.</dd>
<dt><a name="addopenfunction"></a><strong><code>cgilua.addopenfunction (func)</code></strong></dt>
<dd>Defines a function (<code>func</code>) to be called before the execution
of the script requested.<br/>
Returns nothing.</dd>
<dt><a name="addscripthandler"></a><strong><code>cgilua.addscripthandler (ext, func)</code></strong></dt>
<dd>Defines a function (<code>func</code>) to pre-process files with a
certain extension (<code>ext</code>). The default configuration uses
<a href="#doscript"><code>cgilua.doscript</code></a> to process Lua Scripts
(<code>.lua</code> files) and <a href="#handlelp"><code>cgilua.handlelp</code></a>
to process Lua Pages (<code>.lp</code> files).<br/>
Returns nothing.</dd>
<dt><a name="buildplainhandler"></a><strong><code>cgilua.buildplainhandler (type, subtype)</code></strong></dt>
<dd>Creates a <em>script handler</em> that sends the given header and the plain
file requested. The <em>Content-type</em> header is formed by the two arguments;
the created function will receive a <em>filename</em> as its only argument
and will return the given filename untouched.<br/>
Returns a function.</dd>
<dt><a name="buildprocesshandler"></a><strong><code>cgilua.buildprocesshandler (type, subtype)</code></strong></dt>
<dd>Creates a <em>script handler</em> that sends the given header and the
processed file requested. The <em>Content-type</em> header is formed by the
two arguments; the created function will receive a <em>filename</em> as its
only argument and will return the given filename pre-processed by the
function <a href="#include">cgilua.lp.include</a>.<br/>
Returns a function.</dd>
<dt><a name="setmaxfilesize"></a><strong><code>cgilua.setmaxfilesize (size)</code></strong></dt>
<dd>Sets the maximum <code>size</code> (in bytes) for each uploaded file.
This value is bounded by the <em>maximum total input size</em> (see
<a href="#setmaxinput">cgilua.setmaxinput</a>). This function only takes
effect if used before POST data is processed, therefore its use in scripts
are meaningless.<br/>
Returns nothing.</dd>
<dt><a name="setmaxinput"></a><strong><code>cgilua.setmaxinput (size)</code></strong></dt>
<dd>Sets the <em>maximum total input</em> <code>size</code> allowed (in bytes).
This function only takes efect if used before POST data is processed,
therefore its use in scripts are meaningless.<br/>
Returns nothing.</dd>
</dl>
<h2><a name="urlcode"></a>URL encoding functions</h2>
<p>CGILua enconding functions allow the processing of URL strings in a simple way:</p>
<dl class="reference">
<dt><a name="encodetable"></a><strong><code>cgilua.urlcode.encodetable (table)</code></strong></dt>
<dd><em>URL-encode</em> the elements of a <code>table</code> creating a
string to be used as a URL for passing data/parameters to another script.<br/>
Returns a string representing the encoded argument table.</dd>
<dt><a name="escape"></a><strong><code>cgilua.urlcode.escape (string)</code></strong></dt>
<dd><em>URL-encode</em> a <code>string</code>.<br/>
Returns the encoded string.</dd>
<dt><a name="insertfield"></a><strong><code>cgilua.urlcode.insertfield (args, name, value)</code></strong></dt>
<dd>Adds the given <code>value</code> to the field indexed by <code>name</code>
in the <code>args</code> table. If the field already has a value, it is
transformed into a table with this value at index <code>1</code> and
the new value at index <code>2</code>. Other values will be added at
the end of the <em>array-part</em> of the created table.<br/>
Returns nothing.</dd>
<dt><a name="parsequery"></a><strong><code>cgilua.urlcode.parsequery (query, args)</code></strong></dt>
<dd>Parse URL-encoded request data. This could be the <code>query</code>
part of the script URL or URL-encoded POST data. Each decoded
<em>name = value</em> pair is inserted into the <code>args</code> table.<br/>
Returns nothing.</dd>
<dt><a name="unescape"></a><strong><code>cgilua.urlcode.unescape (string)</code></strong></dt>
<dd><em>URL-decodes</em> a <code>string</code>.<br/>
Returns the decoded string.</dd>
</dl>
<h2><a name="auxiliar"></a>Auxiliar functions</h2>
<dl class="reference">
<dt><a name="doif"></a><strong><code>cgilua.doif (filepath)</code></strong></dt>
<dd>Executes a file (given by <code>filepath</code>) if it exists.
Returns the values returned by the execution, or
<tt>nil</tt> followed by an error message if the file does not exists.</dd>
<dt><a name="doscript"></a><strong><code>cgilua.doscript (filepath)</code></strong></dt>
<dd>Executes a file (given by <code>filepath</code>). Raises an error if it
occurs. In case of success, returns the values returned by the execution.</dd>
<dt><a name="pack"></a><strong><code>cgilua.pack (...)</code></strong></dt>
<dd>Returns a new table with all the passed arguments stored in it.</dd>
<dt><a name="splitonfirst"></a><strong><code>cgilua.splitfirst (path)</code></strong></dt>
<dd>Returns two strings with the "first directory" and the "remaining paht" of the given
<code>path</code> string splitted on the first separator ("/" or "\").</dd>
<dt><a name="splitonlast"></a><strong><code>cgilua.splitonlast (path)</code></strong></dt>
<dd>Returns two strings with the "directory path" and "file" parts of the given
<code>path</code> string splitted on the last separator ("/" or "\").
This function used to be called <code>cgilua.splitpath</code> and still can be accessed by
this name for compatibility reasons. <code>cgilua.splitpath</code> may be deprecated in future
versions.</dd>
<dt><a name="tmpfile"></a><strong><code>cgilua.tmpfile (dir[, namefunction])</code></strong></dt>
<dd>Returns a temporary file in the <code><a href="#tmp_path">cgilua.tmp_path</a></code> directory
using an optional name generator. If the name generator function is not passed,
<code>cgilua.tmpname</code> is used. The file is removed by CGILua after the request has been
processed.</dd>
<dt><a name="tmpname"></a><strong><code>cgilua.tmpname ()</code></strong></dt>
<dd>Returns a temporary name using an adjusted version of <code>os.tmpname</code>.</dd>
</dl>
<h2><a name="index"></a>Alphabetic Index</h2>
<a href="#addclosefunction">addclosefunction</a><br/>
<a href="#addopenfunction">addopenfunction</a><br/>
<a href="#addscripthandler">addscripthandler</a><br/>
<a href="#buildplainhandler">buildplainhandler</a><br/>
<a href="#buildprocesshandler">buildprocesshandler</a><br/>
<a href="#contentheader">contentheader</a><br/>
<a href="#doif">doif</a><br/>
<a href="#doscript">doscript</a><br/>
<a href="#encodetable">encodetable (urlcode)</a><br/>
<a href="#errorlog">errorlog</a><br/>
<a href="#escape">escape (urlcode)</a><br/>
<a href="#header">header</a><br/>
<a href="#htmlheader">htmlheader</a><br/>
<a href="#include">include (lp)</a><br/>
<a href="#insertfield">insertfield (urlcode)</a><br/>
<a href="#mkabsoluteurl">mkabsoluteurl</a><br/>
<a href="#mkurlpath">mkurlpath</a><br/>
<a href="#pack">pack</a><br/>
<a href="#parsequery">parsequery (urlcode)</a><br/>
<a href="#handlelp">handlelp</a><br/>
<a href="#lp">lp</a><br/>
<a href="#print">print</a><br/>
<a href="#put">put</a><br/>
<a href="#redirect">redirect</a><br/>
<a href="#script_file">script_file</a><br/>
<a href="#script_path">script_path</a><br/>
<a href="#script_pdir">script_pdir</a><br/>
<a href="#script_vdir">script_vdir</a><br/>
<a href="#script_vpath">script_vpath</a><br/>
<a href="#servervariable">servervariable</a><br/>
<a href="#setcompatmode">setcompatmode (lp)</a><br/>
<a href="#seterrorhandler">seterrorhandler</a><br/>
<a href="#seterroroutput">seterroroutput</a><br/>
<a href="#setlibdir">setlibdir</a><br/>
<a href="#setmaxfilesize">setmaxfilesize</a><br/>
<a href="#setmaxinput">setmaxinput</a><br/>
<a href="#setoutfunc">setoutfunc (lp)</a><br/>
<a href="#splitonfirst">splitonfirst</a><br/>
<a href="#splitonlast">splitonlast</a><br/>
<a href="#tmpfile">tmpfile</a><br/>
<a href="#tmpname">tmpname</a><br/>
<a href="#tmp_path">tmp_path</a><br/>
<a href="#urlcode">urlcode</a><br/>
<a href="#unescape">unescape (urlcode)</a><br/>
<a href="#urlpath">urlpath</a><br/>
</div> <!-- id="content" -->
</div> <!-- id="main" -->
<div id="about">
<p><a href="http://validator.w3.org/check?uri=referer">Valid XHTML 1.0!</a></p>
<p><small>$Id: reference.html,v 1.46 2007/12/05 19:41:13 carregal Exp $</small></p>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>
</html>
|
