1Q(1) General Commands Manual Q(1)
2
6 Q - The equational programming language
7
9 q [ options ] [ file | - ] [ argument ... ]
10 qc [ options ] [ file | - ] ...
11
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 For instance, here is a little Q script featuring a recursive defini‐
19 tion of the well-known factorial function:
20 fact 0 = 1;
22 fact N = N*fact(N-1) if N>0;
23 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 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 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 q foo.q
43 (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 You can also execute compiler and interpreter separately, like this:
49 qc foo.q
51 q q.out
52 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 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 The script name can also be a single hyphen `-' to indicate that the
66 script should be read from standard input.
67 Script and bytecode files are searched for on the ``Q library path''
69 which usually defaults to something like
70 .:/usr/share/q/lib:/usr/lib/q
72 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
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 -- Stops option processing (remaining parameters will be treated as
86 ordinary command arguments even if they start with `-').
87 -c command
89 Execute the given interpreter command (batch mode).
90 -d Invoke the symbolic debugger built into the interpreter.
92 -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 -o output-file
98 Specify the name of the bytecode file created by the compiler
99 (default is q.out).
100 -q Quiet startup (suppress the sign-on message).
102 -s command-file
104 Source file with interpreter commands (batch mode).
105 -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
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 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 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 #!/usr/local/bin/q -cfoo
146 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 #!/usr/local/bin/q
153 #! -w
154 #! -cfoo
155 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
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
173 QPATH A colon-separated list of directories to be searched for source
174 and code files.
175 QWARN The default warning level (overridden with the -wn option; zero
177 if not set).
178 EDITOR Editor used by the built-in edit command of the interpreter
180 (default: vi).
181 INFO_PROGRAM
183 Program used to read online documentation with the built-in help
184 command of the interpreter (default: info).
185 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
192 q.out Default code file name.
193 .q_vars
195 Default file name for loading and saving variable definitions
196 (load and save commands).
197 ~/.q_history
199 File used to store the command history when the interpreter is
200 run interactively.
201 ~/.qinitrc
203 Initialization file containing interpreter commands to be exe‐
204 cuted at startup when running interactively.
205 ~/.qexitrc
207 Termination file containing interpreter commands to be executed
208 when the interpreter exits.
209
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 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
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 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 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
270 The Q Programming Language, by Albert Graef, Johannes Gutenberg-Univer‐
271 sity Mainz, Germany. (Also available online, see info qdoc.)
272 http://q-lang.sourceforge.net
274Q Version 7.x September 2007 Q(1)