GAP in emacs and xemacs

This html describes how to run GAP in emacs or xemacs. It first assumes that the user is running GAP on a linux/unix machine. The second part considers the windows case.

The gap mode file was written by Goetz Pfeiffer and Michael Smith. This webpage was written with help from Gary Zablackis, Nikos Apostolakis, Ric Crabbe, and Steve Linton.

Note that under emacs/xemacs you may lose the tab-completion (but see below for Nikos' fix for this) and the nice history features of GAP's built-in shell. However, as a small consolation, you can edit out any syntax mistakes in your session as you go and emacs has it's own search function, which serves as a replacement for GAP's history feature.

Gary Zablackis points out that the gap-help-filter code, given in the windows part below, is probably relevant to all users of Emacs with GAP 4.4.x (and possibly earlier), as the GAP output changed from "[space] more" to "[space] page, ..." at some point, and the *Help* buffer seems to be read-only without the addition I made.

LINUX/UNIX
- emacs
  1. In the standard distribution, emacs is a subdirectory in the etc subdirectory of GAP. If for some reason it is missing then go to the emacs-gap page and download emacs-gap-mode.readme and emacs-gap-mode-1.96.tar.gz. Place the uncompressed contents in the etc/emacs subdirectory of your GAP directory. The readme file describes how to edit your .emacs file in your home directory. I suggest slightly changing the readme file instructions to instead add the following lines to your .emacs file:
```
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

;; gap mode
(autoload 'gap-mode "gap-mode" "Gap editing mode" t)
(setq auto-mode-alist (append (list '("\\.g$" . gap-mode)
                                    '("\\.gap$" . gap-mode))
                              auto-mode-alist))
(autoload 'gap "gap-process" "Run GAP in emacs buffer" t)

(setq gap-executable "PATH1/gap.sh")
(setq gap-start-options (list ;; "-l PATH2/lib"
                              "-m 50m"))

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

(setq load-path (nconc '( "PATH2/etc/emacs") load-path) )
```
    Here:
    PATH1 is the path to the GAP script which you use to start GAP (for example, PATH1=/home/wdj/computer_algebra/gap4r4/bin)
    PATH2 is the path to the GAP directory (for example, PATH2=/home/wdj/computer_algebra/gap4r4).
    You must replace PATH1, PATH2 above to suit your setup.
    In the gap-completions-filter function (gap-process.el), adding
```
    (setq buffer-read-only nil)  ;; GEZ: so we can put completions into the buffer after (set-buffer "*Completions*")
```
    gets the tab completion to work.
  2. Now, on a command line, try:
    emacs & M-x gap
    (M-x is usually pressing the escape key and the x key almost simultaneously.) Wait a bit for GAP to start and load into emacs.
  Want to automate all this? Create a script emacs-gap with the following lines (I am using bash - I don't think this matters):
```
#!/bin/bash
#starts GAP in emacs
emacs -f gap
```
  Make it executable by typing chmod a+x emacs-gap. Now when you type emacs-gap on the command line it launches GAP inside emacs.
- xemacs: This is the simplest:
  xemacs M-x shell PATH1/gap.sh

WINDOWS

These instructions are thanks to Gary Zablackis (gzabl AT yahoo.com), who has given permission to reproduce his instructions.

GAP runs inside emacs with an emacs lisp function Gary wrote (see below), but not in gap mode. In other words. if you start emacs and do

    M-x shell
    gap

then GAP runs but is not running in "gap mode", so that function completion and help do not display in the emacs *Completions* and *Help* windows, respectively.

As for my other tests, the following table shows the results:

Version                   Completions     Help            C-u M-x gap         Miscellaneous
-------------------------------------------------------------------------------------------------------
NTEmacs (v21.3.1)         FAIL            WORKS           FAILS              NO FIRST LINE OF OUTPUT
                                                        (see change below 
                                                       to gap-process.el
                                                         for fix)
 

Singular   (v21.1.13)     WORK            WORKS           WORKS
(This is the emacs that comes with Singular v 2.0.5)

 
Cygwin    (v21.2.1)       WORK            WORKS           WORKS
      (both emacs and xemacs are the same version and require an X display)

Clarifying comments:

Version of emacs to use
1. The version of emacs included with Singular 2.0.5 appears to be the most appropriate version to use with GAP at this time
2. Use runemacs -f gap with this version of emacs.
.emacs: gap-start-options:
cannot use "-l e:/math/gap4r4" one must use "-l" "e:/math/gap4r4" instead i.e. if an option includes a parameter, both the option and the parameter must be quoted individually otherwise, one receives the following error message and GAP aborts: gap: sorry, options must not be grouped '-l e:/math/gap4r4'
gap.rc
1. Use gap.rc instead of .gaprc in Windows.
2. GAP will search for gap.rc in :
  1. the directory from which GAP is started if it is started from a "DOS" window command line
  2. the "Start in" directory if GAP is started from a desktop shortcut
  3. ~ if GAP is started from a bash shell
  4. the "gap-directory" if GAP is started via emacs, i.e. using any of the following:
```
             emacs -f gap  (or runemacs -f gap)
             M-x GAP from within emacs
             C-u M-x GAP from within emacs
```

Following is the code needed to replace gap-help-filter in gap-process.el to handle GAP v4.4.x.


(defun gap-help-filter (proc string)
  "This output filter pipes the output of a help command into a *Help* buffer.
It must handle the -- [space] page, [n] next line, [b] back, [p] back line, [q] quit -- prompts,    ;; GEZ: GAP 4.4.x
strip them and send spaces to continue                                                              ;; GEZ: GAP 4.4.x
the output until it is done."
  (let ((cbuf (current-buffer)))
    (set-buffer "*Help*")
    (setq buffer-read-only nil)                                     ;; GEZ: so we can put help info into the buffer
    (goto-char (point-max))
    (insert string)
    (beginning-of-line)
    (if (re-search-forward
         "  -- [space] page, [n] next line, [b] back, [p] back line, [q] quit --"
         nil t
        )                    ;;GEZ: Add to handle GAP 4.4.x output
        (progn
          (delete-region (match-beginning 0) (point))
          (comint-send-string proc " ")))                 ;;NOTE: tell GAP to continue with next page

     (if (looking-at (concat gap-prompt-regexp "$"))      ;;GEZ: make sure get the end of it all
        (progn
          (delete-region (point) (point-max))
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; NOTE: this section is only needed for NTEmacs
   (goto-char (point-min))
          (while (re-search-forward
                  "gap: 'ioctl' could not turn off raw mode!\n" nil t)
            (replace-match ""))
;; NOTE: end NTEmacs specific code
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
          (goto-char (point-min))
   (while (re-search-forward
                  "^\\( *\^H\\)\\|\\(\C-m\\)" nil t)              ;;GEZ: get rid of ^H and ^M
     (replace-match ""))
          (set-process-filter proc 'gap-output-filter)))
    (set-buffer cbuf)))

And the following is an example .emacs file:

        ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
        ;;NOTE: In the following there are pairs of lines that end
        ;;           "for NTEmacs" and "for others"
        ;;           If using NTEmacs the first of each pair of these lines should be
        ;;           uncommented (remove the semi-colon at the start of the line)
        ;;           and the second should be commented out (place a semi-colon
        ;;           at the beginning of the line)
        ;;           If using one of the other emacses, comment out the first of the lines
        ;;           and uncomment the second.
        ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;; make sure we can load our .el and .elc files
;(setq load-path (nconc '("PATH1/etc/emacs") load-path) ) ;;for NTEmacs
(setq load-path (nconc '("PATH2/etc/emacs") load-path) )  ;;for others
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;; emacs gap mode
(autoload 'gap-mode "gap-mode" "Gap editing mode" t)
(setq auto-mode-alist (append (list '("\\.g$"   . gap-mode)
                                    '("\\.gap$" . gap-mode))
                              auto-mode-alist))
(autoload 'gap "gap-process" "Run GAP in emacs buffer" t)
;(setq gap-executable "PATH1/EXEPATH/gap")              ;;for NTEmacs
(setq gap-executable "PATH2/EXEPATH/gap")               ;;for others
(setq gap-start-options (list
                               ;;"-b"
                               "-l" "PATH1"                                 ;;for NTEmacs
                               ;"-l" "PATH2"                                ;;for others
                               "-m" "32m" ))
;(setq gap-run "PATH1/EXEPATH/gap.exe -l PATH1 -m 32m")
(setq gap-run "PATH2/EXEPATH/gap.exe -l PATH2 -m 32m")
 
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;; gap working directory (gap.rc will be here and this is the root directory for file searches)
;(setq gap-directory "PATH1/work")                            ;;for NTEmacs
(setq gap-directory "PATH2/work")                             ;;for others
 
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;NOTES:
;;NOTE: PATH1:   (e.g. e:/math/gap4r4)           is root path for GAP 
;;NOTE: PATH2:   (e.g. /cygdrive/e/math/gap4r4)  is root path for GAP
;;NOTE: EXEPATH: (e.g. bin/i686-pc-cygwin-gcc)   is path of GAP executable relative to PATH1 or PATH2
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

wdj@usna.edu

Last updated 2009-6-19.

This page is at the url: http://www.usna.edu/Users/math/wdj/gap/gap_emacs.html