quisputil(1)(TDH)

Name
quisputil - command line QUISP interpreter

Synopsis
quisputil options scriptfile [varvalue-pairs]

Description
quisputil is a general purpose template processer / script interpreter. Like quisp, it understands QUISP markup. However, while quisp is specifically for producing web content, quisputil is a general command line utility, and any kind of text can be processed, not just HTML.

scriptfile should be a file containing some sort of content, plus QUISP markup. quisputil loads pagename, interprets any embedded QUISP markup, and writes the result to standard output. Since quisputil is a command line utility, it does not support CGI-specific directives such as #cookie or #optionlist.

quisputil may be used as a template processor to generate a document in one pass, or it may be used as a filter, to generate one result per input record.

The order of command line arguments matters; options should come first, then the scriptfile, then any varvalue-pairs.

Options

-dp

    Data processing mode. This is a convenience option which is equivalent to -f -u -n, often used when processing data (as opposed to producing a presentation document).

-f

    Filter mode. Read data records on stdin and execute the script repeatedly, once per incoming record. Script may reference incoming data fields using field numbers (e.g. ). Or, with -h or -H using field names from the field name header (e.g. @balance). Unless -u is used, Embedded underscores in data fields will be converted to space, except when -u is used. NULL fields will be converted to zero length strings, unless -n is used.

-u

    Leave embedded underscores in fields when reading data. Normally embedded underscores are converted to a space before interpreting the script.

-n

    Show NULL fields. Normally each null is converted to "" before interpreting the script.

-h

    Header mode. Implies -f. Incoming data records have fields named in the first non-comment non-blank line, separated by white space.

-H

    Same as -h but the field name header is copied to output. If no records are written then header is not written. This is only useful when output field format is same as input.

-o

    Output each data record to stdout after it is processed. Data records may be conditionally printed to stdout by using the internal variable _PRINTDATA (see below).

-s

    Show last line executed in the event of an error.

-d

    Hide directives that quisputil doesn't know about. Normally these are shown. A directive is considered to be any line having a first non-whitespace character of pound sign (#).

-ver or -?

    Print the software version number. The version number is also available to scripts in the quisp variable QUISP_VERSION.

Varvalue pairs

These may follow the scriptfile on the command line. The varvalue pair sets the given variable to the given value before invoking the script. Example: ID=0202

Exit code
The #exit directive may be used to generate a quisputil exit code which can be captured by the invoking shell.

Special variables and operators
The variable _PRINTDATA is pre-declared. Your script can set it to 1 if you wish to print the input record selectively.

If you are using quisputil to process data records, you can use constructs such as or to access incoming data fields. You can also set these fields, eg. #set 7 = hello.

The special operator <line> may be used to print an input data record verbatim. It must be used at the beginning of the line, and must be alone on the line. This may be useful when processing white-space formatted data, or when it is desired to print an entire data record to stdout, without having to enumerate all the fields. Normally, incoming data is parsed into fields which makes it impossible to preserve space formatting. The <line> operator gets around this problem.

Examples

1. Execute the script myfile.script. The variables ID and CLINIC would be defined and set to the given values before executing the script. The script retrieves related data (a name) for presentation, using $dba_get().

    quisputil myfile.script ID=02930 CLINIC=02 > out

2. Read a stream of records having field names in the first line (header), and produce a brief report for each record:

    cat data | quisputil -h myscript

Notes

Directives that are not recognized will be ignored and echoed to standard output, unless -d is used.

#cgivar variables may be set from the command line as var-value pairs.

Environment

SHSQL_DB = the full path name of the project directory containing a config file. This is generally optional.

See also

quisp(1) - quick server pages CGI process