.if n .ds - \%--
.if t .ds - \(em
.TH Q 1 "April 2004" "Q Version 6.x"
.SH NAME
q \- eQuational programming language
.SH SYNOPSIS
.B q
.RI [ options
.RI "] [" " script-or-code-file "
.RI [ "argument " .\|.\|.]\ ]
.br
.B qc
.RI [ options ] " script-file " .\|.\|.
.br
.B qcc
.RI [ options ] " c-or-object-file " ".\|.\|. [--" " cc-options " ".\|.\|. [--link" " ld-options " .\|.\|.]]
.br
.B qld
--help | --version | 
.RI -o " progname " [-dlopen " module " .\|.\|.]
.br
.B qcwrap
.I script-file
.br
.SH DESCRIPTION
These programs are used to compile and execute scripts written in the
Q programming language. To run a script named
.B foo.q
you usually invoke the interpreter just as:
.sp
.nf
        q foo.q
.fi
.sp
(The script name can also be followed by other parameters which are passed to
the script and can be accessed through the built-in
.B ARGS
variable of the interpreter.)
.PP
You can also execute compiler and interpreter separately, like so:
.sp
.nf
        qc foo.q
        q q.out
.fi
.sp
The compiler will then compile the source script
.B foo.q
to a ``bytecode'' file
.B 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.
.PP
Script and code files are searched for on the ``Q library path'' which usually
defaults to something like
.sp
.nf
        .:/usr/share/q/lib:/usr/lib/q
.fi
.sp
You can override this default by setting the
.B QPATH
environment variable or by using the
.B -p
command line option.
.PP
Both compiler and interpreter can also be invoked without arguments, in which
case only the built-in functions and any definitions in the script
.B 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
.B --no-prelude
compiler option.
.PP
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
.B 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
.B -o
option. Any extra options for compiler and linker should be placed at the end
of the parameter list, after the
.B --
option which tells
.B qcc
to end its option parsing and pass the remaining options on to the compiler
and, for options following the
.B --link
option, the linker.
.PP
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
.B qld
program creates such a ``preloaded'' executable which has the given ``dlopen''
modules linked into the interpreter, using
.B libtool
in link mode. The given options are simply passed on to
.B libtool
which does all the real work (see the
.B libtool
info manual for details).
.PP
A closer description of the options of the
.B qcc
and
.B qld
programs and the C interface in general can be found in the Q info file.
.PP
Last but not least, the
.B 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.
.SH 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
.B --version
or
.B -V
option. You can also invoke compiler and interpreter with the
.B --help
or
.B -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).
.TP
.B --
Stops option processing (remaining parameters will be treated as ordinary
command arguments even if they start with
.RB ` - ').
.TP
.BI -c " command"
Execute the given interpreter command (batch mode).
.TP
.B -d
Invoke the symbolic debugger built into the interpreter.
.TP
.B -i
Run interactively (print sign-on and prompt) even when input or output
is redirected. Also cause any
.B -c
and
.B -s
options to be ignored.
.TP
.BI -o " output-file"
Specify the name of the bytecode file created by the compiler (default is
.BR q.out ).
.TP
.B -q
Quiet startup (suppress the sign-on message).
.TP
.BI -s " command-file"
Source file with interpreter commands (batch mode).
.SH USAGE
Unless one of the
.B -c
and
.B -s
options is specified, or if invoked with the
.B -i
option, the interpreter starts up in
.IR "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
.B quit
function causes the interpreter to be exited. End-of-file and
.I Ctl-C
are also handled (more or less) gracefully.
.PP
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
.B .qinitrc
and
.B .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.
.PP
On UNIX systems, you can also run Q scripts directly from the shell using the
\fB#!\fP symbol to specify the \fBq\fP program as a command language
processor. For instance, use the following as the first line of your script to
invoke \fBq\fP with the option \fB-cfoo\fP:
.sp
.nf
        #!/usr/local/bin/q -cfoo
.fi
.sp
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 `\fB#!\fP \fIoption\fP'. For instance:
.sp
.nf
        #!/usr/local/bin/q
        #! -d
        #! -cfoo
.fi
.sp
Instead of directly running the script file, you can also use the
.B 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 \fB#!\fP notation, or if the script is to be
distributed in a self-contained, binary form.
.SH DEBUGGING
The
.B --debug
or
.B -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 \fBbreak\fP function; this allows you to set breakpoints
in a script. Furthermore, the
.B 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 \fB?\fP or \fBhelp\fP to print a list of debugger
commands.
.SH ENVIRONMENT
.TP
.B QPATH
A colon-separated list of directories to be searched for source and code
files.
.TP
.B EDITOR
Editor used by the built-in
.B edit
command of the interpreter (default: vi).
.TP
.B INFO_PROGRAM
Program used to read online documentation with the built-in
.B help
command of the interpreter (default: info).
.TP
.B GNUCLIENT_PROGRAM
Program used to communicate with
.BR emacs (1)
when running as a client of
.BR gnuserv (1),
which is triggered with the interpreter's
.B --gnuclient
option.
.SH FILES
.TP
.B q.out
Default code file name.
.TP
.B .q_vars
Default file name for loading and saving variable definitions
.RB ( load " and " save " commands)."
.TP
.B ~/.q_history
File used to store the command history when the interpreter is run
interactively.
.TP
.B ~/.qinitrc
Initialization file containing interpreter commands to be executed at startup
when running interactively.
.TP
.B ~/.qexitrc
Termination file containing interpreter commands to be executed when the
interpreter exits.
.SH 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.
.PP
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. ;-)
.SH SEE ALSO
.I The Q Programming Language,
by Albert Graef, Johannes Gutenberg-University Mainz, Germany. (Also available
online, see
.BR "info qdoc" .)