E. Running Scripts in Emacs

The Q programming system also includes an Emacs Lisp program which lets you edit and run Q scripts in GNU Emacs or XEmacs. The program implements two major modes q-mode and q-eval-mode for Q source scripts and Q interpreter processes, respectively. The following discussion is rather terse and incomplete, but if you know Emacs then it should provide enough information to get you started.

To install Q mode on your system, copy the file q-mode.el from prefix/share/q/etc (where prefix is the installation prefix you selected at installation time) to your Emacs site-lisp directory and paste the following lines into your Emacs startup file:

(require 'q-mode)
(setq auto-mode-alist (cons '("\\.q$" . q-mode) auto-mode-alist))

If you want syntactic fontification (font-lock mode), you also have to add the following lines:

(add-hook 'q-mode-hook 'turn-on-font-lock)
(add-hook 'q-eval-mode-hook 'turn-on-font-lock)

More installation options are described at the beginning of the q-mode.el file. Once Q mode is installed and loaded, you can also customize it in Emacs; see the description of the Customize option below.

Q mode is used for editing Q scripts. With the startup configuration described above, it is invoked automatically on all files having the .q extension. Q mode provides auto-indentation and filling, as well as syntactic fontification of keywords, strings, comments, and variable and type symbols using the font-lock mode which is part of the Emacs library.

The indentation rules for Q scripts are somewhat unusual for a programming language, so we briefly summarize them here:

• Declarations start in the first column, with continuation lines being indented by a certain (configurable) amount. Moreover, initial `=', `|' and `;' symbols are all aligned in data type declarations.
• Inside rules, an initial `=' is aligned with the most recent equation. The default amount of `=' indentation can be configured. Auto indentation is also provided for the right-hand side and qualifier part of a rule. Qualifiers (introduced with if, otherwise and where) use an extra amount of indentation which can be configured as well.
• In addition, expressions are indented according to their parenthetical structure, as in Lisp mode.

As usual, indentation of a line is performed with the Tab key. There also is a menu command for indenting a selected region. Moreover, you can use Esc-Tab at the end of a line to move the cursor to the indentation position for the = symbol in an equation, and certain "electric" delimiter symbols like `=' will automatically perform indentation when typed at the beginning of a line.

The q-run-script command (usually bound to C-c C-c) compiles and runs the script in the current buffer; you can also use the run-q command (which has no keybinding by default) to invoke the interpreter without a script. Both commands create a new buffer named *q-eval* (if that buffer does not already exist) in which it runs the interpreter. The *q-eval* buffer is also used to display error messages from the compiler, if any. The interpreter is used in this buffer as usual, with the only difference that input and output is done through the buffer. Since this is an ordinary Emacs buffer, you can also save the buffer to some file to obtain a transcript of your interpreter session.

The *q-eval* buffer uses q-eval-mode as its major mode which is based on comint-mode, a generic command language interpreter mode which is also part of the Emacs library. In addition to the facilities provided by Comint mode (such as cycling through a history of recent commands), Q-Eval mode provides fontification of some special items (strings, comments and source file references printed by the interpreter), as well as some commands for locating the source lines referenced by compiler or debugger messages from the interpreter. In particular, pressing the return key (or the middle mouse button, when running under X-Windows) on such a message visits the corresponding source file with the cursor positioned at the line indicated by the message. You can also scan through the messages found in the buffer with the following commands:

q-next-msg (C-c C-n), q-prev-msg (C-c C-p)

Show the next/previous compiler/debugger message and visit the corresponding source line in another window. An optional prefix argument may be used to specify the number of messages to advance.

q-first-msg (C-c C-a), q-last-msg (C-c C-e)

Show the first/last line in a contiguous sequence of compiler/debugger messages above/below the current message and visit the corresponding source line.

The above commands can be invoked in both Q and Q-Eval mode, and they are also accessible from the corresponding Q and Q-Eval menus in the menubar (or the buffer popup menu obtained with the right mouse button). Some other commands are provided as well, but you can easily find out about these using the online help facilities of Emacs. In particular, you should try the describe-mode (C-h m) command which describes the currently active mode. Another useful command is describe-key (C-h k). You can also invoke the online version of this manual with C-c C-h.

The Customize option in the Q/Q-Eval menus can be used to set various options of the interpreter in the Q customization group, which belongs to Emacs' "Programming Languages" group. In particular, you should enable the q-gnuclient option in the "Options" subgroup which synchronizes Emacs with the Q interpreter; e.g., this option allows you to edit files and read online help using the interpreter's edit and help commands directly in Emacs. (For this to work, you must have the gnuserv package, which can be obtained from the usual elisp archives; see the q-mode.el file for details.)

This document was generated by Albert Gräf on February, 23 2008 using texi2html 1.76.