1Q(1)                        General Commands Manual                       Q(1)
2
3
4

NAME

6       Q - The equational programming language
7

SYNOPSIS

9       q  [ options ] [ file | - ] [ argument ... ]
10       qc [ options ] [ file | - ] ...
11

DESCRIPTION

13       These programs are used to compile and execute scripts written in the Q
14       programming language. Q is an interpreted, dynamically typed functional
15       programming language based on term rewriting which allows you to define
16       functions using symbolic equations.
17
18       For instance, here is a little Q script featuring a  recursive  defini‐
19       tion of the well-known factorial function:
20
21               fact 0 = 1;
22               fact N = N*fact(N-1) if N>0;
23
24       This  definition tells the interpreter that the term (function applica‐
25       tion) `fact 0' should evaluate to the integer  constant  1,  while  any
26       other  term  `fact N' with N>0 evaluates to the value of the expression
27       N*fact(N-1).
28
29       A closer description of the language is well outside the scope of  this
30       manual page, but you can find some further notes about Q below, and you
31       should also take a look at the Q info file (available online using info
32       qdoc  or with the help command of the interpreter) for details and many
33       more examples.
34
35       The primary interface to the Q language is the interpreter  program  q.
36       The  qc  program  is  a compiler for Q scripts which is usually invoked
37       automatically by the interpreter to translate the source  script  to  a
38       bytecode  format  which  is  suitable for efficient execution. To run a
39       script stored in a file foo.q you usually invoke the  interpreter  just
40       as:
41
42               q foo.q
43
44       (The  script  name  can  also be followed by other parameters which are
45       passed to the script and can be  accessed  through  the  built-in  ARGS
46       variable of the interpreter.)
47
48       You can also execute compiler and interpreter separately, like this:
49
50               qc foo.q
51               q q.out
52
53       The  compiler will then compile the source script foo.q to the bytecode
54       file q.out which can be loaded by the interpreter. Note that if you run
55       a  source  script through the interpreter, then the compilation step is
56       handled automatically and the bytecode file is removed automatically as
57       soon as it has been loaded by the interpreter.
58
59       Both compiler and interpreter can also be invoked without arguments, or
60       with an empty script name, in which case only  the  built-in  functions
61       and  definitions in the script prelude.q (which by default includes the
62       standard Q library) are loaded. The automatic inclusion of the  prelude
63       script can also be suppressed with the --no-prelude compiler option.
64
65       The  script  name  can also be a single hyphen `-' to indicate that the
66       script should be read from standard input.
67
68       Script and bytecode files are searched for on the  ``Q  library  path''
69       which usually defaults to something like
70
71               .:/usr/share/q/lib:/usr/lib/q
72
73       You  can  override  this default by setting the QPATH environment vari‐
74       able, by using the -p command line option, and with the path command of
75       the interpreter.
76

OPTIONS

78       Compiler  and  interpreter  support  both  short  and  long (GNU style)
79       options. A brief descriptive message showing the version number can  be
80       obtained  with the --version or -V option. You can also invoke compiler
81       and interpreter with the --help or -h option to print a summary of  the
82       command  line syntax and the available options. Other important options
83       are listed below (see the Q info file for more).
84
85       --     Stops option processing (remaining parameters will be treated as
86              ordinary command arguments even if they start with `-').
87
88       -c command
89              Execute the given interpreter command (batch mode).
90
91       -d     Invoke the symbolic debugger built into the interpreter.
92
93       -i     Run  interactively (print sign-on and prompt) even when input or
94              output is redirected. Also cause any -c and  -s  options  to  be
95              ignored.
96
97       -o output-file
98              Specify  the  name  of the bytecode file created by the compiler
99              (default is q.out).
100
101       -q     Quiet startup (suppress the sign-on message).
102
103       -s command-file
104              Source file with interpreter commands (batch mode).
105
106       -w     Prints warnings about possibly undefined function symbols.  This
107              gives  you  a  moderate level of confidence for small or medium-
108              sized programs.  -w2 or --pedantic prints even more diagnostics,
109              and  might  be  useful  for  larger projects.  -w3 or --paranoid
110              prints an excessive amount of  diagnostics  even  for  perfectly
111              legal  scripts.  This  is not intended to be used regularly, but
112              may occasionally be useful to check your script for missing dec‐
113              larations or mistyped identifiers.
114

USAGE

116       Unless  one  of  the -c and -s options is specified, or if invoked with
117       the -i option, the interpreter starts up in interactive mode, in  which
118       the user is repeatedly prompted to enter an expression to be evaluated,
119       and the interpreter answers with the corresponding ``normal form.''  If
120       the interpreter runs in interactive mode and is connected to a tty, the
121       interpreter supports command line editing and  history  using  the  GNU
122       readline  library.  The  quit  function  causes  the  interpreter to be
123       exited. End-of-file and Ctl-C are also handled (more  or  less)  grace‐
124       fully.
125
126       On  the  interactive command line, the value of the last expression can
127       be referred to using the ``anonymous'' variable, denoted by  an  under‐
128       score  (`_'). Moreover, the interpreter understands a number of special
129       commands which allow you to define variables, inspect and adjust  vari‐
130       ous  system  parameters, edit and run scripts and command source files,
131       read online info, load and save variables values, etc. Please refer  to
132       the  Q info page for a description of these. You can also put such com‐
133       mands into the .qinitrc and .qexitrc files in your home directory which
134       are sourced when the interpreter starts up and is exited in interactive
135       mode, respectively. This provides a convenient means, e.g., to  custom‐
136       ize parameters of the interpreter according to your taste, and to auto‐
137       matically reload and save variable values.
138
139       On UNIX systems, you can also run Q scripts  directly  from  the  shell
140       using the ``shebang'' #! to specify the q program as a command language
141       processor. For instance, use the following as the first  line  of  your
142       script  to invoke q with the option -cfoo which causes the function foo
143       to be evaluated at startup:
144
145               #!/usr/local/bin/q -cfoo
146
147       Such lines will be treated as comments by the compiler and interpreter.
148       It  is also possible to specify compiler and interpreter options at the
149       beginning of the main  script  using  the  notation  `#!  option'.  For
150       instance:
151
152               #!/usr/local/bin/q
153               #! -w
154               #! -cfoo
155
156       Instead  of  directly  running  the  script  file, you can also use the
157       qcwrap program to translate the script to a C file. This is  useful  if
158       your  shell does not support the #! notation, or if the script is to be
159       distributed in a self-contained, binary form.  The  qcwrap  program  is
160       available as an optional addon, see the Q info file for details.
161

DEBUGGING

163       The --debug or -d option causes activation of a symbolic debugger built
164       into the interpreter.  The debugger can also be  invoked  interactively
165       and  you  can set breakpoints using the debug and break commands on the
166       command line. The debugger allows you to trace the reductions performed
167       by the Q interpreter in the course of an expression evaluation. You can
168       also step over reductions, abort the evaluation, and print  a  list  of
169       activated  rules.  Use the command ? or help in the debugger to print a
170       list of debugger commands.
171

ENVIRONMENT

173       QPATH  A colon-separated list of directories to be searched for  source
174              and code files.
175
176       QWARN  The  default warning level (overridden with the -wn option; zero
177              if not set).
178
179       EDITOR Editor used by the built-in  edit  command  of  the  interpreter
180              (default: vi).
181
182       INFO_PROGRAM
183              Program used to read online documentation with the built-in help
184              command of the interpreter (default: info).
185
186       GNUCLIENT_PROGRAM
187              Program used to communicate with  emacs(1)  when  running  as  a
188              client  of gnuserv(1), which is triggered with the interpreter's
189              --gnuclient option.
190

FILES

192       q.out  Default code file name.
193
194       .q_vars
195              Default file name for loading and  saving  variable  definitions
196              (load and save commands).
197
198       ~/.q_history
199              File  used  to store the command history when the interpreter is
200              run interactively.
201
202       ~/.qinitrc
203              Initialization file containing interpreter commands to  be  exe‐
204              cuted at startup when running interactively.
205
206       ~/.qexitrc
207              Termination  file containing interpreter commands to be executed
208              when the interpreter exits.
209

ABOUT Q

211       Q may have started out as an academic research project, but  it  should
212       not  be  mistaken  for  a toy language. Q has a modern syntax featuring
213       both user-definable infix operators and curried function  applications,
214       and provides many goodies of modern-style functional languages, such as
215       higher-order functions (including lambdas), support for both eager  and
216       lazy  evaluation,  and  OOP-style  polymorphic  algebraic  types. The Q
217       interpreter goes to great lengths to implement  term  rewriting  in  an
218       efficient manner, so that Q programs are executed reasonably fast, more
219       or less comparable to other interpreted languages.  Moreover,  Q  comes
220       with an extensive software library, which makes it a practical program‐
221       ming tool and in many areas surpasses what is available for its  bigger
222       cousins like ML and Haskell.
223
224       The Q interpreter is extensible using ``external'' modules written in C
225       or C++ (which are loaded at runtime, if possible), and  can  itself  be
226       used  as  an  extension  language for other C/C++ applications. Q has a
227       fairly complete POSIX system interface and a  comprehensive  collection
228       of  addon  modules which interface to various popular open source soft‐
229       ware packages including, e.g., GNU Octave, various GUI, graphics,  mul‐
230       timedia,  database  and  web-related  libraries,  and  a module for the
231       Apache web server. There is a language mode for emacs, which provides a
232       convenient  environment  for  editing and running Q scripts, and syntax
233       files for the vim and kate text editors are also available. All this is
234       described in much more detail in the Q info file and in the other docu‐
235       mentation available on the Q website.
236

CAVEATS AND BUGS

238       The only major issue I am aware of is memory requirements.  The  actual
239       data  of  an  expression  node is only 12 bytes, but memory management,
240       type tags and other book-keeping  information  sum  up  to  another  12
241       bytes.  There is no easy way around this in the current implementation,
242       so don't expect this to change anytime soon. Fortunately,  main  memory
243       gets  cheaper and bigger all the time, so this should rarely be a prob‐
244       lem in practice.
245
246       The Q interpreter uses a special pattern-matching technique  to  deter‐
247       mine  matching equations quickly and during a single left-to-right scan
248       of each potential redex. This usually works very well,  but  there  are
249       some  pathological configurations of left-hand sides of equations which
250       cause an exponential blow-up of the tables of the pattern-matching  au‐
251       tomaton;  fortunately,  they  are  rare. You can tell that you have run
252       into such a situation when the interpreter needs a long time  to  start
253       up  or appears to hang during bytecode compilation. The only way around
254       this currently is to rewrite your script so that the amount of  overlap
255       between equations is reduced.
256
257       Another  limitation of the current implementation is that special argu‐
258       ment patterns and paths  to  left-hand  side  variables  are  currently
259       encoded  as  bit vectors to save memory space. Thus functions cannot be
260       declared with more than 32 special parameters, and the  left-hand  side
261       of  a  rule or local variable definition may not be more than 32 levels
262       deep. There are also some hardcoded limits  in  the  compiler  for  the
263       sizes  of  the expression and code table for a single rule. The default
264       table sizes are fairly large and, so far, this has never been a problem
265       in practice. If you do run into an ``expression too complex'' or ``code
266       table overflow'' error then it is probably  time  to  restructure  your
267       program anyway. ;-)
268

SEE ALSO

270       The Q Programming Language, by Albert Graef, Johannes Gutenberg-Univer‐
271       sity Mainz, Germany. (Also available online, see info qdoc.)
272
273       http://q-lang.sourceforge.net
274
275
276
277Q Version 7.x                   September 2007                            Q(1)
Impressum