LuaCheia Reference Manual

cgi

Synopsis

cheia.load “cgi”

data = cgi.process()

cgi.put_header()

Description

This module provides functions helpful for writing CGI (Common Gateway Interface) web applications. CGI is a de facto standard supported by almost all web servers which allows web pages to be generated on request by a program. Communication between the web server and the CGI program is via environment variables and the standard input and output streams.

Typically, a web browser provides parameters to a CGI program using a query URL of the form "http://www.example.com/cgi-bin/example.lua?key1=value1&key2=value2". The web server in this case will execute "example.lua", using the LuaCheia interpreter if it is set up to do so (e.g. using a ‘#!’ line under UNIX), and pass the portion of the URL following the ‘?’ to it in the QUERY_STRING environment variable. The program acts on this information and sends back an HTML page, preceded by an HTTP header, to stdout.

The cgi module provides the cgi.process function to decode the query string (or data sent using the alternative POST method) into a Lua table, and the cgi.put_header function to output a standard HTTP header, or a customised one based on a table. It also provides helper functions for encoding and decoding data in URL format (i.e. containing ‘%xx’ sequences to represent special characters using their ASCII hexadecimal form), etc.

Examples

Typically, the following program could be placed in the "cgi-bin" directory of a UNIX web server. It simply provides a form with a text box, and repeats back anything entered.

#!/usr/local/bin/luacheia5

-- Load the cgi module
cheia.load “cgi”

-- Read the submitted data into the 'data' table
data = cgi.process()

-- Start writing the output page
cgi.put_header()
print(“<html><body>”)

-- If the form was submitted, print the result
if data.out then
print(“<p>You submitted: ” .. data.out .. “</p>”)
end

-- Print the form
print [[
<form method="GET" action="test.cgi">
Enter something: <input name="out" type="text"></input>
<input type="submit"></input>
</form>
</body>
</html>
]]

Reference

cgi.put_header([header], [fd])

Writes out an HTTP header. This function must be called before any text is sent. If the header parameter is specified, it should be a table of header entries. Currently, the following keys are supported:

Table key	HTTP header entry
content	Content-type
redirect	Location

The default header is simply ‘Content-type: text/html’.

Parameters:
header : table	Specifies the header to use. If absent, the default header is used.
fd : file	The file descriptor to write to. Defaults to io.stdout.

cgi.url_decode(text, [use_plus])

Decodes a URL-encoded string.

Parameters:
text : string	The text to decode.
use_plus : boolean	If true or absent, allows a ‘`+`’ to represent a space in the input.
Returns:
string	The decoded string.

cgi.url_encode(text, [use_plus])

URL-encodes a string.

Parameters:
text : string	The text to encode.
use_plus : boolean	If true or absent, uses ‘`+`’ rather than ‘`%20`’ to represent a space.
Returns:
string	The encoded string.

cgi.encode_qs(tbl)

Encodes a table for use in a query URL. The returned string does not include the leading ‘?’ character.

Parameters:
tbl : table	The key/value pairs to encode.
Returns:
string	The equivalent query string.

cgi.process([fd])

Detects the request type and processes the data sent in the request appropriately. Returns a table of the parameters. Also sets the following variables based on the environment:

cgi.QUERY_STRING	The part of the URL following the ‘?’ in a GET request, if any.
cgi.PATH_INFO	The part of the URL path following the script name, if any (used if the CGI program is treated as a ‘virtual directory’).
cgi.REQUEST_METHOD	The type of request, e.g. GET, HEAD, POST...
cgi.CONTENT_TYPE	The encoding used to send data in the body of e.g. a POST request. Usually either "application/x-www-form-urlencoded" or "multipart/form-data".

Parameters:
fd : file	The file descriptor to read POST requests from. Defaults to io.stdin.
Returns:
table	The decoded key/value pairs.

Additional Functions

These functions are primarily for internal use.

cgi.strip_rr(text)

Strips CR characters from a string.

Parameters:
text : string	Input.
Returns:
string	Result.

cgi.strip_nn(text)

Strips LF characters from a string.

Parameters:
text : string	Input.
Returns:
string	Result.

cgi.strip_rn(text)

Strips CR and LF characters from a string.

Parameters:
text : string	Input.
Returns:
string	Result.

cgi.process_multipart_post([fd])

Reads the body of an HTTP POST request which has been encoded using multipart/form-data.

Parameters:
fd : file	The file descriptor to read from. Defaults to io.stdin.
Returns:
table	The decoded key/value pairs.

cgi.decode_qs(qs, [tbl])

Decodes a query string into a table.

Parameters:
qs : string	The query string.
tbl : table	The output table. If absent, a new one is created.
Returns:
table	A table containing the decoded key/value pairs.

cgi.process_urlenc_post([fd])

Reads the body of an HTTP POST request which has been encoded using "application/x-www-form-urlencoded" (the default).

Parameters:
fd : file	The file descriptor to read from. Defaults to io.stdin.
Returns:
table	The decoded key/value pairs.

cgi.process_get()

Reads and decodes the QUERY_STRING envirnment variable, as supplied by an HTTP GET request.

Returns:
table	The decoded key/value pairs.

Issues

Does not handle multiple values for the same key.

Is this thing portable? Seems to assume we want UNIX line-endings.

URL encoding looks broken to me (plus sign handling).

__header_items seems like unnecessary obfuscation.

Revision history

Added in LuaCheia 5.0.

Credits

Written by Adrián Pérez de Castro.

Documentation for LuaCheia by Jamie Webb.

Return to main site

Introduction

» Writing LuaCheia modules

Module Reference

» bit
» cgi
» fuzzy
» md5
» pack
» rex
» SDL
» shelve
» sqlite

Appendices

» Module path conventions
» Module names
» Application Binary Interface
» Credits