QEF home page
26. QSG: The primary script generator

This page briefly introduces qsg, QEF's primary script generator.

Table of Contents
Previous Page

qsg is the primary QEF script generator. Its major purpose is to convert simple statements of intent into the input to the specified backend. Extensive documentation of the syntax, semantics and available qsg scripts may be accessed using x-qsg.
Note: The default input to qsg is the contents of the directory's qeffile following the Begin line.
The Components of the QSG System

The qsg system consists of an interpreter (qsg), a compiler (qsgcomp), a utility to view an object file (qsgdump), an x_db database describing qsg (x-qsg), a library of standard scripts (std.qsl).

qsg is usually applied to a source file. That source is compiled internally and interpreted. The input will usually invoke scripts from a qsg library, such as std.qsl or another similar archive library of qsg scripts. Such libraries are constructed using compiler to create qsg object files which are then archived using arupdate. qsgdump can be used to view the compiled code of qsg script or library member.

The following is the source code for one of the standard library scripts, presented as an illustration of some of qsg's capabilities.

summary [-p] [-] file OR shell-command
return list read from argument file or pipeline

-p              read from a pipeline
arguments ...   file or pipe-line to be read

This routine opens the argument file or pipe-line (if -p) for
reading, reads the contained words and returns the result as
the value of the call.

if @argv~v
        fatal @(script): no argument file specified
elif @argv~l != 1 && !@pFlag
        fatal @(script): multiple files specified
if @pFlag
        open Fin r| @argv
        open Fin r @argv
while @[word @(readword Fin)]~n
        append list @word
close Fin
returnval @list
The following describes some of the features of the above:
summary ... endsummary
The first line identifies the flags supported by the script. Subsequent lines up to the endsummary document the script and may be converted into an x_db item for inclusion in the documentation.
The @ character is used as a pre-cursor escape. A list of the @ sequences is given in the reference card's Special @ Sequences in QSG. The ~v, ~l, and ~n are post-fix operators that modify the expression. A list of all the list operators is in the specialist's reference card's QSG ListOps. The @argv above is the list of arguments to the script itself. @pflag is a boolean that is set if the --p flag was specified in the call.
if, fatal, else, ...
The first word of a qsg line should be either a qsg keyword, listed in QSG Keywords, a proc defined within the script, or a script such as one in the standard library std.qsl.
@(readword Fin)
This is a call to the qsg function readword. Other functions are listed in QSG Functions. In this particular instance @[word @(readword Fin)]~n reads a single word from the open file Fin, set the variable word to the value read. The post-fix ~n operator converts its argument list (i.e., @word) to 1 if the list is not empty and 0 if it is.
>, <\#>, << ... >>
Not illustrated in the above example are the three keywords used for output >, <\#>, and << as in:
>This output after expression, (e.g., @argv) substitution.
<\1>This line output after expression substitution @
	splitting long lines at white space with \ newline @
	escapes and a 1 tab indent.
Lines up to >> output after expression substitution.

For your information, the source files for this Cook's Tour are actually qsg scripts, which when interpreted produce html pages. There is a general purpose html qsg library that provides the normal html tags, although in more convenient ways than offered by raw html. There is also a Cook's Tour specific qsg library that provides the page epilogue and its prologue, an example of which immediately follows this statement.

cook75.qh - 1.13 - 03/10/24 QEF home page Table of Contents Previous Page