Lua scripts

Lua scripts are files with the extension .lua which are made up entirely of sentences in the Lua language. This kind of usage adopts a "traditional" form of programming, in which a script is strictly limited to being a program.

When a document is created using a Lua script, two basic concepts of CGI must be remembered:

1. A script communicates with the server using the standard output (stdout), and any communication with the server must be sent by this channel.
2. At the beginning of the script the type of document which is being sent must be identified.

An HTML template file (extension .html or .htm) is an ordinary HTML file which incorporates Lua codes and special markings. CGILua processes the incorporated instructions so that the HTML file expands with information obtained in real time. HTML template files are very expressive templates, thus being versatile and well adapted to the situation in which it is necessary to quickly generate codes and parameterize HTML pages.

An important feature of HTML pages is that there is a clear separation between static and dynamic information: static information is coded in HTML, and dynamic information is in Lua code. Since the Lua code and special markings are in comments in HTML or in phrases of free text, it is assured that the file as a whole is a valid HTML document.

Since the HTML template file is a valid HTML document, there are two important consequences:

• The mixed HTML file can be regularly edited using conventional HTML editors.
• Design tasks can be separated from programming tasks.

These two facilities of CGILua lead to easier page maintenance and higher productivity, especially in large sites.

FORMAT:
$| lua-expression |$

This leads to the insertion of the result of lua-expression in the HTML document. If the result of the expression is nil, nothing is inserted.

This type of CGILua marking is widely used where values should be accessed, such as those stored in variables or resulting from functions. For example, the following lines of mixed HTML use this type of marking:

Good Morning, <b>$|firstname|$</b>      <input type="text" name="cor" value="$|cgi.cor|$">      <a href="$|cgilua.mkurl("ajuda.html", cgi )|$">Ajuda</a>

In the first line, the content of the previously defined variable firstname is printed in bold.

In the second line, the value cgi.cor, which is passed as a parameter to the document, is used to initialize a text input field. If no value for cgi.cor is effectively passed as a parameter to the document, then the field is left blank.

FORMAT:
<!--$$ lua-code $$-->

This leads to the interpretation of the lua-code contained between the marks <!--$$ and $$-->.

This type of marking places the Lua codes as HTML comments, allowing a large amount of Lua sentences to be introduced in a document without any possibility of interference with HTML syntax rules.

The use of a code field is recommended whenever the necessary processing is more elaborate than just printing Lua expressions, as is the case of defining Lua functions, reading a file, or consulting a database.

FORMAT:
<!--$$ LOOP start='cod_ini', test='cond_exec', action='cod_cycle' $$-->
[HTML code]
<!--$$ ENDLOOP $$-->

This type of marking repeats [lines-HTML] if and while cond_exec is true. Lua instructions can be executed before the start of the repetition and before the first test in cond_exec by using the control field start. The field action specifies Lua instructions which are to be executed at each cycle of the loop (cod_cycle).

The syntax of the control fields start, test, and action is similar to the construction for in C/C++. It is important to note that the other types of special markings (expression fields and code fields) can be used as normal markings in [lines-HTML]. LOOP markings can be nested as much as required.

The three examples below illustrate the use of this type of marking:

Example 1:

Table of numbers 1 to 9:<br>       <table border=1>       <tr>       <!--$$ LOOP start='i=1', test='i<10', action='i=i+1' $$-->       <td>$|i|$</td>       <!--$$ ENDLOOP $$-->       </tr>       </table>

Result of Example 1:
Table of numbers 1 to 9:

1

2

3

4

5

6

7

8

9

Example 2:

<!--$$       data = {       { "Renata", "20 years", "Brazilian" },       { "John", "22 years ", "English" },       { "Natalie", "19 years ", "Spanish" },       }       $$-->            <b>Data in our records:</b><br><br>       <!--$$ LOOP start='i=1', teste='data[i]', action='i=i+1' $$-->       Nome: $|dados[i][1]|$<br>       Age: $|dados[i][2]|$<br>       Nationality: $|dados[i][3]|$<br>       <br>       <!--$$ ENDLOOP $$-->

Result of Example 2:
Data in our records:

Nome: Renata
Age: 20 years
Nationality: Brazilian

Nome: John
Age: 22 years
Nationality: English

Nome: Natalie
Age: 19 years
Nationality: Spanish

Example 3:

Multiplication Table of numbers 1 to 10:<br><br>       <table border=1>       <tr>       <th>Number</th>       <!--$$ LOOP start='i=1', test='i<=10', action='i=i+1' $$-->       <th>x $|i|$</th>       <!--$$ ENDLOOP $$-->       </tr>       <!--$$ LOOP start='i=1', test='i<=10', action='i=i+1' $$-->       <tr>       <td><b>$|i|$</b></td>       <!--$$ LOOP start='j=1', test='j<=10', action='j=j+1' $$-->       <td align=right>$|i*j|$</td>       <!--$$ ENDLOOP $$-->       </tr>       <!--$$ ENDLOOP $$-->       </table>

FORMAT:
<!--$$ IF test='cond_exec' $$-->
[HTML code (true condition)]
(<!--$$ ELSE $$-->
[HTML code (false condition)])
<!--$$ ENDIF $$-->

This type of marking includes (and processes) [HTML code (true condition)] if cond_exec is true. Otherwise, it includes the code [HTML code (false condition)].

The two examples below illustrate the use of this type of marking:

Example 1:

<form ...>      User name:       <!--$$ IF test='cgi.editmode' $$-->       <input type="text" name="user" value="$|cgi.user|$">      <!--$$ ELSE $$-->       $|cgi.user|$      <!--$$ ENDIF $$-->       </form>

Suppose cgi.editmode is set to some value, and cgi.user has value "John";
the result would be:

Example 2:

<!--$$ IF test="cgi.draft" $$-->      This is a draft version of the manual.     <!--$$ ENDIF $$-->

To execute a CGILua script, it is necessary to use special URLs. URLs of CGILua scripts (both Lua scripts and HTML templates) have the following format:

http:://<web-server>/<path-cgilua>/<path-script>

The URL of a CGILua script therefore encompasses two types of information:

1. The virtual path (relative to the web server) in which CGILua is installed (<path-cgilua>).
2. The path (relative to the home - or root - directory of the server) to the script to be executed (<path-script>).

Item 1 is defined when CGILua is installed. For example, it is common to install CGILua in a virtual directory (with permission for execution) called /scripts/. Since the executable program is named cgilua or cgilua.exe, depending on whether the version is for UNIX or Windows 95/NT (respectively), the <path-cgilua> component of the URL will be /scripts/cgilua or /scripts/cgilua.exe.

Item 2 is the same (virtual) path it would be if the file were a normal HTML file, without CGILua processing. Care should be taken if some mapping is defined in the configuration file of CGILua called map.lua, because the mapping will predominate over the default behavior.

The trivial use of CGILua scripts is in processing data from HTML forms. CGILua facilitates this type of processing, automatically decoding the data received.

When a form is constructed in HTML, three components are important in processing the data:

• Which is the FORM method (field method of the tag form) which has been used in the form.
• Which is the script that will be executed to process the data (field action of the tag form).
• Which variables were defined in the form (fields name of the tags <input>).

For CGILua users, item 1 is straightforward: the methods POST and GET are both treated transparently by CGILua.

CGILua supports "file upload", an HTML 3.2 mechanism for transferring files from the client to the server by means of HTML forms, available through HTML form fields with the "FILE" type (<input type="file"> tag). The names of the files to be transferred are defined interactively by the user. When the user submits the form, the files are saved to a directory in the server. CGILua supports the transfering of any kind of file (binary or text).

The HTML form used for uploading purpose has to conform to some specific rules. The following attributes of the <FORM> HTML tag must be specified: method="POST" and enctype="multipart/form-data".

Mechanisms were implemented allowing the developer to specify the name with which and the directory in which the file will be saved in the server. The specification mechanism is very flexible, allowing the developer to define any naming rule for the files that will be sent to the server. Basically, this mechanism consists in defining rules using Lua regular expressions. These rules must be stored into a Lua table called cgilua.uploadrules (file cgilua.conf/map.lua), which is exemplified below:

cgilua.uploadrules = {      { pattern="(.*)%.doc", target="upload%.%1%.doc"},      { pattern="(.*)%.bmp", target="upload%.%1%.bmp"},      ; root_dir = "c:/temp/"     }

These rules specify that all files with be saved in the c:/temp/ directory, but the files with extension .doc and .bmp will have a "upload" prefix appended.

The cgilua.uploadrules table is the table used by default to define the naming and the transfer rules for the files. It is also possible to specify alternative rules tables, when is needed that a script use different rules than the default ones. Any rules table must necessarily contain the field root_dir, which defines the directory in which the files must be stored in the server. Apart from the root_dir field, the rules can be freely specified. Any number of rules can be specified, and there are tested until there is a match. Each rule must follow the format { pattern=pattern, target=target }, with an optional field func, as described above:

Environment variables

Scripts needed:

Scripts needed:

Scripts needed:

Scripts needed: