CGILua: Building Web Scripts with Lua

Headers

Headers functions are used to change the HTTP response headers and consist of:

cgilua.contentheader (type, subtype): Sends a Content-type header with the given values of type and sub-type.
Both arguments are strings: type is the header type; subtype is the header sub-type.
Returns nothing.
cgilua.header (header, value): Sends a generic header. This function should not be used to generate a Content-type nor a Location header because some launchers/web-servers use different functions for this purpose.
Both arguments are strings: header is the name of the header; value is its value.
Returns nothing.
cgilua.htmlheader (): Sends the header of an HTML file (Content-type: text/html).
Returns nothing.
cgilua.redirect (url, args): Sends the header to force a redirection to the given URL adding the parameters in table args to the new URL.
The first argument (url) is the URL the browser should be redirected to; the second one (args) is an optional table which could have pairs name = value that will be encoded to form a valid URL (see function cgilua.urlcode.encodetable).
Returns nothing.

Content Generation

Content generation functions are used to output text to the response and to generate URLs in the CGILua format. They consist of:

cgilua.mkabsoluteurl (path): Creates an absolute URL containing the given URL path.
Returns the resulting absolute URL.
cgilua.mkurlpath (script [, args]): Creates an URL path to be used as a link to a CGILua script using the optional table of arguments (args). The arguments are used in the URL as query string parameters.
Returns the resulting URL.
cgilua.print (...): 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 cgilua.put.
Returns nothing.
cgilua.put (...): Sends the given arguments to the client. This function should always be used; do not use Lua's print or io.write for output otherwise your script may not work for every launching method.
Returns nothing.

Lua Pages

Lua Pages functions are used to process Lua Pages templates and to define the behavior of this processing. They consist of:

cgilua.handlelp (filename[, env]): Equivalent to cgilua.lp.include but sends the HTML header before the pre-processed file.
Returns nothing.
cgilua.lp.compile (string): Compile a piece of code given as a string into a Lua function. The string is translated with cgilua.lp.translate into another string which is transformed into a function with loadstring. The resulting function is cached internaly and reused if the same piece of code is given.
Returns a function.
cgilua.lp.include (filename[, env]): Pre-processes a Lua Page template (given by filename) and sends the results to the client. The file content is processed by cgilua.lp.compile 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.
Returns nothing.
cgilua.lp.setcompatmode (boolean): Turns on or off the compatibility mode. Turning it on will make the Lua Pages preprocessor understand the expression fields and code fields structures used by previous versions of CGILua.
Default value: true
Returns nothing.
cgilua.lp.setoutfunc (funcname): Defines the name of the output function for templates. The Lua Pages preprocessor will generate calls to the function with the given funcname (a string).
Returns nothing.
cgilua.lp.translate (string): 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 string.
Returns a string with the resulting Lua code.

CGILua Variables

CGILua Variables offers information about the script being processed and the CGI environment variables depending on the Web server and launcher used. They consist of both atributes and functions:

cgilua.script_file: The file name of the running script. Obtained from cgilua.script_path.
cgilua.script_path: The complete path of the running script. This variable is usually the same as the CGI environment variable PATH_TRANSLATED.
cgilua.script_pdir: The directory of the running script. Obtained from cgilua.script_path.
cgilua.script_vdir: The virtual directory of the running script. Obtained from cgilua.script_vpath.
cgilua.script_vpath: The complete virtual path of the running script. Equivalent to the CGI environment variable PATH_INFO.
cgilua.servervariable (varname): Returns a string with the value of the CGI environment variable correspoding to varname. For a list of CGI variables please refer to SAPI.Request.servervariable
cgilua.tmp_path: The directory used by cgilua.tmpfile. Obtained by checking os.getenv("TEMP"), os.getenv ("TMP") and "/tmp" in that order.
cgilua.urlpath: The name of the script. Equivalent to the CGI environment variable SCRIPT_NAME.

Error Handling

CGILua error handling functions allow the redefinition of how errors are handled and presented to the user. The consist of:

cgilua.errorlog (string): Sends the given string to the error log file.
Returns nothing.
cgilua.seterrorhandler (func): Sets the error handler function to func. 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.
Returns nothing.
cgilua.seterroroutput (func): Sets the error output function to func. This function is called by Lua to generate the error output itself.
Returns nothing.

CGILua behavior

The behavior of CGILua can be configured using this set of functions:

cgilua.addclosefunction (func): Defines a function (func) to be called after the execution of the script requested.
Returns nothing.
cgilua.addopenfunction (func): Defines a function (func) to be called before the execution of the script requested.
Returns nothing.
cgilua.addscripthandler (ext, func): Defines a function (func) to pre-process files with a certain extension (ext). The default configuration uses cgilua.doscript to process Lua Scripts (.lua files) and cgilua.handlelp to process Lua Pages (.lp files).
Returns nothing.
cgilua.buildplainhandler (type, subtype): Creates a script handler that sends the given header and the plain file requested. The Content-type header is formed by the two arguments; the created function will receive a filename as its only argument and will return the given filename untouched.
Returns a function.
cgilua.buildprocesshandler (type, subtype): Creates a script handler that sends the given header and the processed file requested. The Content-type header is formed by the two arguments; the created function will receive a filename as its only argument and will return the given filename pre-processed by the function cgilua.lp.include.
Returns a function.
cgilua.setmaxfilesize (size): Sets the maximum size (in bytes) for each uploaded file. This value is bounded by the maximum total input size (see cgilua.setmaxinput). This function only takes effect if used before POST data is processed, therefore its use in scripts are meaningless.
Returns nothing.
cgilua.setmaxinput (size): Sets the maximum total input size allowed (in bytes). This function only takes efect if used before POST data is processed, therefore its use in scripts are meaningless.
Returns nothing.

URL encoding functions

CGILua enconding functions allow the processing of URL strings in a simple way:

cgilua.urlcode.encodetable (table): URL-encode the elements of a table creating a string to be used as a URL for passing data/parameters to another script.
Returns a string representing the encoded argument table.
cgilua.urlcode.escape (string): URL-encode a string.
Returns the encoded string.
cgilua.urlcode.insertfield (args, name, value): Adds the given value to the field indexed by name in the args table. If the field already has a value, it is transformed into a table with this value at index 1 and the new value at index 2. Other values will be added at the end of the array-part of the created table.
Returns nothing.
cgilua.urlcode.parsequery (query, args): Parse URL-encoded request data. This could be the query part of the script URL or URL-encoded POST data. Each decoded name = value pair is inserted into the args table.
Returns nothing.
cgilua.urlcode.unescape (string): URL-decodes a string.
Returns the decoded string.

Auxiliar functions

cgilua.doif (filepath): Executes a file (given by filepath) if it exists. Returns the values returned by the execution, or nil followed by an error message if the file does not exists.
cgilua.doscript (filepath): Executes a file (given by filepath). Raises an error if it occurs. In case of success, returns the values returned by the execution.
cgilua.pack (...): Returns a new table with all the passed arguments stored in it.
cgilua.splitfirst (path): Returns two strings with the "first directory" and the "remaining path" of the given path string splitted on the first separator ("/" or "\").
cgilua.splitonlast (path): Returns two strings with the "directory path" and "file" parts of the given path string splitted on the last separator ("/" or "\"). This function used to be called cgilua.splitpath and still can be accessed by this name for compatibility reasons. cgilua.splitpath may be deprecated in future versions.
cgilua.tmpfile (dir[, namefunction]): Returns a temporary file in the cgilua.tmp_path directory using an optional name generator. If the name generator function is not passed, cgilua.tmpname is used. The file is removed by CGILua after the request has been processed.
cgilua.tmpname (): Returns a temporary name using an adjusted version of os.tmpname.

Alphabetic Index

addclosefunction
addopenfunction
addscripthandler
buildplainhandler
buildprocesshandler
contentheader
doif
doscript
encodetable (urlcode)
errorlog
escape (urlcode)
header
htmlheader
include (lp)
insertfield (urlcode)
mkabsoluteurl
mkurlpath
pack
parsequery (urlcode)
handlelp
lp
print
put
redirect
script_file
script_path
script_pdir
script_vdir
script_vpath
servervariable
setcompatmode (lp)
seterrorhandler
seterroroutput
setlibdir
setmaxfilesize
setmaxinput
setoutfunc (lp)
splitonfirst
splitonlast
tmpfile
tmpname
tmp_path
urlcode
unescape (urlcode)
urlpath