CGILua: Building Web Scripts with Lua

CGILua
Building Web Scripts with Lua

## Overview

CGILua includes a set of external libraries that allows the handling of authentication, cookies, dispatching, serialized data and sessions. To use these libraries just `require` them in your CGILua `config.lua` or script file.

## Authentication

`cgilua.authentication.check (username, passwd)`
  Checks if the pair `username`/`passwd` is authenticated by the configured method.
  Returns true if succesfull or `nil` plus an error message if not.
`cgilua.authentication.checkURL ()`
  Returns the URL for the checking script. The checking script receives the current URL as the `ref` parameter. It is up to the checking script to ask for user credentials, check if the user has the expected credentials (using `cgilua.authentication.check (username, passwd)` if implementing the checking script using CGILua), and redirect to the original URL (using the `ref` parameter or `cgilua.authentication.refURL()` if implementing the checking script using CGILua).
`cgilua.authentication.configure (options, methods)`
  Configures the authentication framework (see `/examples/authentication_conf.lua` in CVS for more information).
`cgilua.authentication.logoutURL ()`
  Returns the URL for the logout script.
`cgilua.authentication.refURL ()`
  Returns the URL for the page that orignally required authentication. Used in checking scripts that use CGILua. Other checking scripts can use the `ref` parameter.
`cgilua.authentication.username ()`
  Returns the authenticated user or `nil` if no user is currently authenticated.

## Cookies

`cgilua.cookies.get (name)`
  Gets the value of the cookie with the given `name`.
  Returns a string with the value of the cookie.
`cgilua.cookies.set (name, value[, options])`
  Sets the `value` of the cookie with a given `name`. The optional table `options` is used togive the values of the cookies attributes: expires, path, domain, secure. This function should be called before the HTTP headers are sent and before any output is generated, so it must not be used inside a Lua Page.
  This function sends a cookie with the response. If you need to create a cookie inside the generated response or if the cookie needs to be set inside the client, use `cgilua.cookies.sethtml` instead.
  Returns nothing.
`cgilua.cookies.sethtml (name, value[, options])`
  Sets the `value` of the cookie with a given `name`. The optional table `options` is used to give the values of the cookies attributes: expires, path, domain, secure.
  This function generates a `<meta>` HTML element so it should be called after the `<head>` HTML tag and before the corresponding `</head>`.
  This function creates a cookie in the client, if you need to send the cookie with the response use `cgilua.cookies.set` instead.
  Returns nothing.
`cgilua.cookies.delete (name[, options])`
  Deletes a cookie with a given `name` (setting its value to `xxx`). This function should be called before the HTTP headers are sent and before any output is generated.
  Returns nothing.

## Dispatcher

`cgilua.dispatch.route (urlmaps)`
  Defines the routing using a table of URLs maps or a single map. A map defines a URL mask using $name patterns to extract parameters, a function to be called with the extracted parameters and a name for the map when used with `cgilua.dispatch.route_url`.
`cgilua.dispatch.route_url (mapname, parameters, query)`
  Returns an URL for a named route map. mapname defines the name associated with the map in the original routed URL table sent to `cgilua.dispatch.route`. params defines a table of named parameters used to fill the URL pattern. query defines an optional table of named parameters used for the QUERY part of the URL.

## Serialize

`cgilua.serialize (table, outfunc[, indent[, prefix]])`
  Serializes a `table` using `outfunc` as the function to be used to generate the output; `indent` as an optional string with the indentation pattern; `prefix` as an optional string with the indentation prefix (it is used to store the actual indentation between the recursion calls).
  Some restrictions must be noted: values of types function and userdata are not serialized; tables with cycles are not serialized.
  Returns nothing.

## Session

`cgilua.session.close ()`
  Closes the user session. Saves all data in `cgilua.session.data` to the storage system being used (usually the filesystem). This function should be called after the end of the script execution. A recommended way to ensure that is to use addclosefunction in the configuration file.
  Returns nothing.
`cgilua.session.data`
  Table which holds the user session data.
`cgilua.session.delete (id)`
  Deletes a session. The argument `id` is the session identifier.
  Returns nothing.
`cgilua.session.destroy ()`
  Destroys the current session.
  Returns nothing.
`cgilua.session.load (id)`
  Loads data from a session. The argument `id` is the session identifier.
  Returns a table with session data or `nil` followed by an error message.
`cgilua.session.new ()`
  Creates a new session identifier.
  Returns the new session identifier.
`cgilua.session.open ()`
  Opens the user session. Creates the table `cgilua.session.data`. This function should be called just before the execution of the script, but after the processing of the request's headers. A recommended way to ensure that is to use addopenfunction in the configuration file.
  Returns nothing.
`cgilua.session.save (id, data)`
  Saves `data` to a session with an `id`.
  Returns nothing.
`cgilua.session.setsessiondir (path)`
  Defines the session temporary directory. Argument `path` is a string with the new directory.
  Returns nothing.

Valid XHTML 1.0!

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