CGILua is a tool for developing dynamic HTML pages and manipulating input data from forms. It uses the interpreted language Lua for codifying the commands which will be executed at the time the page is viewed.

CGILua is simple but powerful, and it enables complex tasks to be carried out with minimum effort. The most frequent type of applications built with CGILua are WWW information systems based on external data (such as databases) and WWW gateways to existing systems.

Technically, CGILua is a CGI program which runs on the server and receives files to be interpreted. CGILua acts as intermediary for scripts being submitted to the HTTP server, doing all the basic processing, like decoding input data. It also offers additional resources, such as automatic handling of uploaded files, cryptography functions, state-keeping facilities, and database access.

Characteristics

• CGILua is an interpreted language. No compilation is necessary, thus eliminating this step and assuring high portability to the systems based on this tool.

• CGILua enables the use of embedded codes in normal HTML files, allowing the interaction with HTML editors, such as Front Page© and Hot Dog©. This way, it is possible to use the resources offered by these programs for page layout, instead of being limited to edit all the HTML codes by hand. Normal scripting, of course, is also allowed, and the mixing of both methods can provide great power.

• CGILua has minimum learning requirements, because the Lua language has very simple syntax and constructs. Even non-programmers can learn enough to write CGILua scripts in a short time.

• CGILua sets up security mechanisms in a configuration file, which eliminates the need for the Webmaster to scrutinize the scripts individually, or place arbitrary limits on the available resources. Scripts written in C, C++, sh, or Perl are potentially insecure, since they do not restrict the access to commands that can cause undesired effects.

• CGILua is readily extendable, accepting additional libraries, which means that additional resources can easily be made available. Many extensions for CGILua have already been developed, such as libraries to control occurences in file writes, communication with data bases, and communication cryptography. Some of them are included in the default distribution and are described in section Libraries.

• CGILua automatically decodes data from forms or passed as parameters, which simplifies the manipulation of URL and FORM information.

• CGILua is available for all platforms for HTTP servers, Unix and Windows 9x/NT. Scripts do not need to be altered to enable migration between sites.

Please refer to the published articles described in More information for a deeper presentation of CGILua's characteristics and its differences to other similar tools.

CGILua scripts

Documents can be created in CGILua in two ways: one is by writing pure Lua scripts, in which the contents are entirely made up of valid sentences in the Lua language; the other is by writing HTML template files, in which Lua instructions and CGILua directives are inserted into conventional HTML documents.

Deciding which type of script to use is really a matter of taste, but a good guideline is to choose according to the type of page which is to be generated. The two ways are equally easy to write, but one or the other can be more convenient depending on what functionality is desired. If the page is to be graphically sophisticated, with intensive use of HTML tags, it is probably better to use an HTML template. It is thus possible to disassociate the development of the graphic layout from the code to be written, so that the structure of the page can be made with the help of an HTML editor. If the page is simple in terms of its HTML structure but requires a substantial amount of internal processing, it can be more convenient to write the commands directly, making a Lua script. The advantage here lies in the clarity of the script's purposes. If the generation of HTML tags is just a secondary objective in the processing of the script, then it is reasonable that the Lua code should be the content of the script itself instead of being dispersed as comments in HTML.

In fact, these two script types can be used together: separate pure Lua files can be written to carry out specific tasks, and these modules can be called by mixed HTML files. These HTML files centralize the processing and are responsible for the layout of the pages.

CGILua recognizes the kind of usage by the extension name of the file which is submitted. For pure Lua scripts the extension to be used is .lua, and for HTML template files the extension .html or .htm should be used. The section Usage contains a detailed description of each of these types.

Where to start

This manual is a reference to the tool CGILua. For those who want to develop websites using this tool, the first step is to read sections Usage and CGILua Reference. When more sophisticated needs arise, sections Lua Reference and Libraries should be consulted, since they describe useful resources used in development.

The following references provide further information on HTML, CGI, and Lua:

HTML	http://www.w3.org/pub/WWW/MarkUp/Wilbur/ http://www2.wvitcoe.wvnet.edu/~sbolt/html3/
CGI	http://www.w3.org/pub/WWW/CGI/
Lua	http://www.tecgraf.puc-rio.br/lua

More information

There is a mailing list at cgilua-l. Questions and suggestions can be posted there. To subscribe to this list, send a mail to listproc@tecgraf.puc-rio.br with "subscribe cgilua-l YOUR-NAME" in the body of the message (not in the subject). To unsubscribe, send "unsubscribe cgilua-l" to listproc@tecgraf.puc-rio.br.

Other documentation is avaliable:

Papers:

Anna Hester, Renato Borges and Roberto Ierusalimschy.
Building flexible and extensible Web applications with Lua.
Journal of Universal Computer Science, 4(9):748-762, 1998.
(also in Webnet '98 World Conference of the WWW, Internet, & Intranet, pages 427-432, Orlando, FL, USA, Nov. 1998. Top paper.)

Anna Hester, Renato Borges and Roberto Ierusalimschy.
CGILua: A multi-paradigmatic tool for creating dynamic WWW pages.
in XI Simpósio Brasileiro de Engenharia de Software, páginas 347-360, Fortaleza, CE, 1997.

CGILua has been developed completely at Tecgraf/PUC-Rio and some libraries were developed with sponsorship of PETROBRAS.

We would like to thank the following groups or companies for their continuous feedback and contribution:

• CENPES/SEPROC, SEGEN/COEMA, SERINF/DIRTEL, CEN-SUD (PETROBRAS)
• OOHDM Group (Object-Oriented Hipermedia Design Model group, DI/PUC-Rio)
• LES (Software Engineering Lab, DI/PUC-Rio)
• Fabrica Digital (Web development company)
• RPA@PUC (Academic Profile Network, PUC-Rio)

We would also like to thank Martin Hester for the original version of this manual in english.

Copyright

The authors do not provide any guarantees whatsoever including, but not restricted to, guarantees implied by commercial use and adaptation to personal use. The software hereby distributed is in its original form without modifications, and the authors are not obliged to supply maintenance, support, upgrades, improvements, or modifications. TeCGraf/PUC-Rio or the authors cannot be held responsible by any person for any damage whether direct, indirect, special, incidental, consequential, or accidental arising from the use of the software or its documentation.

Download

If this "change user" mechanism is not activated, any CGILua script will be executed with the user rights with which the HTTP server is executed, usually corresponding to the user nobody or www.

Windows 9x/NT

The installation procedure consists simply in opening the zip file (preserving information in subdirectories) in a directory with permission to execute CGI scripts. Once this is done, the tool is ready to be used.

Testing

With the script test.html

This script can be used to test the functioning of CGILua. It can be copied to a directory served by the Web server (normally C:\InetPub\wwwroot\ or ~/public_html), and a browser can be used to execute it via CGILua.

The URL to be used should be something like:

In UNIX environments:

Physical path: /home/anna/public_html/test.html      URL: http://servidor/scripts/cgilua/~anna/test.html

In Windows 95/NT environments:

Physical path: C:\InetPub\wwwroot\test.html      URL: http://servidor/scripts/cgilua.exe/test.html

The correct functioning of the script can be checked by the link: test