CGILua: Building Web Scripts with Lua

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 paht" 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

Valid XHTML 1.0!

$Id: reference.html,v 1.46 2007/12/05 19:41:13 carregal Exp $