Language

3q uses a three phase approach to process a request:

1. Read the input file (the 3q script), split it up on XML tag level and include all files as requested ("<?pp include ... ?>").

2. Go trough the tags: convert HTML into printf() calls, pass awk code as-is and handle #header and #use directives.

3. Quote the script as shell command line argument, run it, read it's output, detect and handle additional HTTP response header.

Preprocessing

During preprocessing 3q reads its input file and handles includes of further files:

<? pp include filename ?>

inserts filename at the current input position into the input stream. filename may contains HTML and/or awk code and there is no default about its content. If 3q expects code or HTML depends on the context in which the include tag appears. filename must be enclosed in double quotes and relative to the directory of the script file.

Code Compilation

3q's programming language is gawk.

<? awk awk-code ?>

Inside an awk tag any gawk code can be used that is valid for a BEGIN block. Functions must be put into "library files" that are loaded with the #use directive (see below).

In addition 3q supports inside an awk tag the following directives which must appear at the beginning of a line:

#header name value

sets an additional HTTP response header.

#use filename

add filename as additional gawk source file on the command line of the executing gawk command. filename is expected to contain additional function definitions. filename must be enclosed into double quotes and is expected to be relative to the directory of the script file.

Everything outside awk tags is treated as HTML content and coded into printf() statements.

Script Execution

3q provides a set of environment variables to the script. These are:

_CONFIG

name of the 3q configuation with `main' being the default and empty value in apache action handler mode.

_FILENAME

the requested file's basename.

_PATH

rewritten PATH_INFO variable (3q rewrites PATH_INFO to not rely on the web server but usually they are the same).

_WORKDIR

directory of the requested file.

CGI_varname

CGI variable as found in the request. If the request is multipart/form-data the CGI data is not decoded.

CGIVARS

space separated list of all CGI variables.

Additionally the current working directory is the directory of the requested file.

The script may return issue HTTP compliant header before the content data:

status num

sets the HTTP status to num, the default is `200'.

content-type type

sets the content-type to type, the default is `text-html'.

Any other header is passed on an is.