Q(1)

NAME
q - eQuational programming language

SYNOPSIS
q [options ] [ script-or-code-file [argument ...] ]
qc [options] script-file ...
qcc [options] c-or-object-file ... [-- cc-options ... [--link ld-options ...]]
qld --help | --version | -o progname [-dlopen module ...]
qcwrap script-file

DESCRIPTION
These programs are used to compile and execute scripts written in the Q programming language. To run a script named foo.q you usually invoke the interpreter just as:

        q foo.q

(The script name can also be followed by other parameters which are passed to the script and can be accessed through the built-in ARGS variable of the interpreter.)

You can also execute compiler and interpreter separately, like so:

        qc foo.q
        q q.out

The compiler will then compile the source script foo.q to a ``bytecode'' file q.out which will then be loaded by the interpreter. Note that if you run a source script through the interpreter, then the compilation step is handled automatically (using a unique temporary code file name in order to prevent clashes between different interpreter processes which happen to be started simultaneously in the same directory). Furthermore, the bytecode file is removed automatically as soon as it has been loaded by the interpreter.

Script and code files are searched for on the ``Q library path'' which usually defaults to something like

        .:/usr/share/q/lib:/usr/lib/q

You can override this default by setting the QPATH environment variable or by using the -p command line option.

Both compiler and interpreter can also be invoked without arguments, in which case only the built-in functions and any definitions in the script prelude.q are loaded. Note that the prelude script, which is searched for on the library path as well, is always included as the first file in a compilation, which makes it possible to extend the built-in functions of the interpreter with your own ``preloaded'' definitions. The distributed prelude script simply includes all scripts in Q's standard library. The automatic inclusion of the prelude script can also be suppressed with the --no-prelude compiler option.

The interpreter also provides an interface to ``extern'' functions written in C, which are loaded (at runtime, if possible) from ``external'' modules. Modules are searched for on the library path as usual, but also in other system-dependent locations where ``shared libraries'' are looked for. To create an external module from a collection of C or object files, you can invoke the qcc program with these files as arguments. The first filename usually specifies the basename of the module to build, but this can be overridden with the -o option. Any extra options for compiler and linker should be placed at the end of the parameter list, after the -- option which tells qcc to end its option parsing and pass the remaining options on to the compiler and, for options following the --link option, the linker.

If your system does not support dynamic loading of modules, or if you want to debug a module, you have to create a custom interpreter which has the relevant modules statically linked in. The qld program creates such a ``preloaded'' executable which has the given ``dlopen'' modules linked into the interpreter, using libtool in link mode. The given options are simply passed on to libtool which does all the real work (see the libtool info manual for details).

A closer description of the options of the qcc and qld programs and the C interface in general can be found in the Q info file.

Last but not least, the qcwrap program creates a C wrapper from a Q script, which can then be compiled to a self-contained, binary executable. This is described in more detail in the Q info file.

OPTIONS
Compiler and interpreter support both short and long (GNU style) options. A brief descriptive message showing the version number can be obtained with the --version or -V option. You can also invoke compiler and interpreter with the --help or -h option to print a summary of the command line syntax and the available options. Other important options are listed below (see the Q info file for more).

--  Stops option processing (remaining parameters will be treated as ordinary command arguments even if they start with `-').

-c command
    Execute the given interpreter command (batch mode).

-d  Invoke the symbolic debugger built into the interpreter.

-i  Run interactively (print sign-on and prompt) even when input or output is redirected. Also cause any -c and -s options to be ignored.

-o output-file
    Specify the name of the bytecode file created by the compiler (default is q.out).

-q  Quiet startup (suppress the sign-on message).

-s command-file
    Source file with interpreter commands (batch mode).

USAGE
Unless one of the -c and -s options is specified, or if invoked with the -i option, the interpreter starts up in interactive mode, in which the user is repeatedly prompted to enter an expression to be evaluated, and the interpreter answers with the corresponding ``normal form.'' If the interpreter runs in interactive mode and is connected to a tty, the interpreter supports command line editing and history using the GNU readline library. The quit function causes the interpreter to be exited. End-of-file and Ctl-C are also handled (more or less) gracefully.

The value of the last expression can be referred to using the ``anonymous'' variable, denoted by an underscore (`_'). Moreover, the interpreter understands a number of special commands which allow you to inspect and adjust various parameters, edit and run scripts and command source files, read online info, load and save variables, etc. Please refer to the Q info page for a description of these. You can also put such commands into the .qinitrc and .qexitrc files in your home directory which are sourced when the interpreter starts up and is exited in interactive mode, respectively. This provides a convenient means, e.g., to customize parameters of the interpreter according to your taste, and to automatically reload and save variable values.

On UNIX systems, you can also run Q scripts directly from the shell using the #! symbol to specify the q program as a command language processor. For instance, use the following as the first line of your script to invoke q with the option -cfoo:

        #!/usr/local/bin/q -cfoo

Such lines will be treated as comments by the compiler and interpreter. It is also possible to specify compiler and interpreter options at the beginning of the main script using the notation `#! option'. For instance:

        #!/usr/local/bin/q
        #! -d
        #! -cfoo

Instead of directly running the script file, you can also use the qcwrap program to translate the script to a C file which can then be compiled to a binary executable, see the Q info file for details. This is useful if your shell does not support the #! notation, or if the script is to be distributed in a self-contained, binary form.

DEBUGGING
The --debug or -d option causes activation of a simple symbolic debugger built into the interpreter. (The debugger can also be invoked directly from a Q script, by means of the built-in break function; this allows you to set breakpoints in a script. Furthermore, the debug on command can be used to activate the debugger interactively in the interpreter.) The debugger allows you to trace the reductions performed by the Q interpreter in the course of an expression evaluation. You can also step over reductions, abort the evaluation, and print a list of activated rules. Use the command ? or help to print a list of debugger commands.

ENVIRONMENT

QPATH
    A colon-separated list of directories to be searched for source and code files.

EDITOR
    Editor used by the built-in edit command of the interpreter (default: vi).

INFO_PROGRAM
    Program used to read online documentation with the built-in help command of the interpreter (default: info).

GNUCLIENT_PROGRAM
    Program used to communicate with emacs(1) when running as a client of gnuserv(1), which is triggered with the interpreter's --gnuclient option.

FILES

q.out
    Default code file name.

.q_vars
    Default file name for loading and saving variable definitions (load and save commands).

~/.q_history
    File used to store the command history when the interpreter is run interactively.

~/.qinitrc
    Initialization file containing interpreter commands to be executed at startup when running interactively.

~/.qexitrc
    Termination file containing interpreter commands to be executed when the interpreter exits.

BUGS
The only major issue I am aware of is memory requirements. The actual data of an expression is only 12 bytes, but memory management, type tags and other book-keeping information sum up to another 12 bytes. There is no easy way around this in the current implementation, so don't expect this to change anytime soon.

Another limitation is that special argument patterns and paths to left-hand side variables are currently encoded as bit vectors to save memory space. Thus functions cannot be declared with more than 32 special parameters, and the left-hand side of a rule or local variable definition may not be more than 32 levels deep. There are also some hardcoded limits in the compiler for the sizes of the expression and code table for a single rule. The default table sizes are fairly large and shouldn't be a problem in practice. If you do run into an ``expression too complex'' or ``code table overflow'' error then it is probably time to restructure your program anyway. ;-)

SEE ALSO
The Q Programming Language, by Albert Graef, Johannes Gutenberg-University Mainz, Germany. (Also available online, see info qdoc.)