ILISP User Manual

A GNU Emacs Interface for Interacting with Lisp

Edition 0.13, October 1996

For ILISP Version 5.8

Setting up the emacs-lisp interface

Before you start, you must set up your emacs to know where to find the emacs-lisp interface code. At the unix prompt type
cp ~c415/emacs.orig ~/.emacs
Note the period at the beginning of the second ".emacs". You only need to do this once.

How to run a Lisp process using ILISP

Run emacs and then type M-x allegro. This will create a buffer called *allegro* in which lisp will be run. Once you've done this, you can edit lisp files and have functions you type in be sent directly to the lisp process.

ILISP Commands

Most of these key bindings work in both Lisp Mode and ILISP mode. There are a few additional and-go bindings found in Lisp Mode.

Eval and compile functions

In LISP, the major unit of interest is a form, which is anything between two matching parentheses. Some of the commands here also refer to "defun," which is a list that starts at the left margin in a LISP buffer, or after a prompt in the ILISP buffer. These commands refer to the "defun" that contains the point.

"A call" refers to a reference to a function call for a function or macro, or a reference to a variable. Commands which "insert a call" in the ILISP buffer will bring up the last command which matches it or else will insert a template for a call.

When an eval is done of a single form matching ilisp-defvar-regexp the corresponding symbol will be unbound and the value assigned again.

When you send a form to LISP, the status light will reflect the progress of the command. In a lisp mode buffer the light will reflect the status of the currently selected inferior LISP unless lisp-show-status is nil. If you want to find out what command is currently running, use the command C-c s (status-lisp). If you call it with a prefix, the pending commands will be displayed as well.

Note that in this table as elsewhere, the key C-c (ilisp-prefix) is used as a prefix character for ILISP commands, though this may be changed. For a full list of key-bindings, use M-x describe-mode or M-x describe-bindings while in an ILISP-mode buffer.

The eval/compile commands verify that their expressions are balanced and then send the form to the inferior LISP. If called with a positive prefix, the result of the operation will be inserted into the buffer after the form that was just sent.

For commands which operate on a region, the result of the compile or eval is the last form in the region.

The `and-go' versions will perform the operation and then immediately switch to the ILISP buffer where you will see the results of executing your form. If eval-defun-and-go-lisp or compile-defun-and-go-lisp is called with a prefix, a call for the form will be inserted as well.

C-c

The prefix-key for most ILISP commands. This can be changed by setting the variable ilisp-prefix.

RET (return-ilisp)

In ILISP-mode buffer, sends the current form to lisp if complete, otherwise creates a new line and indents. If you edit old input, the input will be copied to the end of the buffer first and then sent.

C-] (close-and-send-lisp)

Closes the current sexp, indents it, and then sends it to the current inferior LISP.

LFD (newline-and-indent-lisp)

Insert a new line and then indent to the appropriate level. If called at the end of the inferior LISP buffer and an sexp, the sexp will be sent to the inferior LISP without a trailing newline.

C-c e (eval-defun-lisp)

M-C-x (eval-defun-lisp)

C-c C-e (eval-defun-and-go-lisp)

Send the defun to lisp.

C-c r (eval-region-lisp)

C-c C-r (eval-region-and-go-lisp)

C-c n (eval-next-sexp-lisp)

C-c C-n (eval-next-sexp-and-go-lisp)

C-c c (compile-defun-lisp)

C-c C-c (compile-defun-lisp-and-go)

When compile-defun-lisp is called in an inferior LISP buffer with no current form, the last form typed to the top-level will be compiled.

C-c w (compile-region-lisp)

C-c C-w (compile-region-and-go-lisp)

If any of the forms contain an interactive command, then the command will never return. To get out of this state, you need to use abort-commands-lisp (C-c g). If lisp-wait-p is t, then EMACS will display the result of the command in the minibuffer or a pop-up window. If lisp-wait-p is nil, (the default) the send is done asynchronously and the results will be brought up only if there is more than one line or there is an error. In this case, you will be given the option of ignoring the error, keeping it in another buffer or keeping it and aborting all pending sends. If there is not a command already running in the inferior LISP, you can preserve the break loop. If called with a negative prefix, the sense of lisp-wait-p will be inverted for the next command.

Documentation functions

describe-lisp, inspect-lisp, arglist-lisp, and documentation-lisp switch whether they prompt for a response or use a default when called with a negative prefix. If they are prompting, there is completion through the inferior LISP by using TAB or M-TAB. When entering an expression in the minibuffer, all of the normal ilisp commands like arglist-lisp also work.

Commands that work on a function will use the nearest previous function symbol. This is either a symbol after a `#'' or the symbol at the start of the current list.

C-c a (arglist-lisp)

Return the arglist of the current function. With a numeric prefix, the leading paren will be removed and the arglist will be inserted into the buffer.

C-c d (documentation-lisp)

Infers whether function or variable documentation is desired. With a negative prefix, you can specify the type of documentation as well. With a positive prefix the documentation of the current function call is inserted into the buffer.

C-c i (describe-lisp)

Describe the previous sexp (it is evaluated). If there is no previous sexp and if called from inside an ILISP buffer, the previous result will be described.

C-c i (describe-lisp)

Describe the previous sexp (it is evaluated). If there is no previous sexp and if called from inside an ILISP buffer, the previous result will be described.

C-c I (inspect-lisp)

Switch to the current inferor LISP and inspect the previous sexp (it is evaluated). If there is no previous sexp and if called from inside an ILISP buffer, the previous result will be inspected.

C-c D (fi:clman)

C-c A (fi:clman-apropos)

If the Franz online Common LISP manual is available, get information on a specific symbol. fi:clman-apropos will get information apropos a specific string. Some of the documentation is specific to the allegro dialect, but most of it is for standard Common LISP.

Source Code Commands

The following commands all deal with finding things in source code. The first time that one of these commands is used, there may be some delay while the source module is loaded. When searching files, the first applicable rule is used:

• try the inferior LISP,
• try a tags file if defined,
• try all buffers in one of lisp-source-modes or all files defined using lisp-directory.

M-x lisp-directory defines a set of files to be searched by the source code commands. It prompts for a directory and sets the source files to be those in the directory that match entries in auto-mode-alist for modes in lisp-source-modes. With a positive prefix, the files are appended. With a negative prefix, all current buffers that are in one of lisp-source-modes will be searched. This is also what happens by default. Using this command stops using a tags file.

edit-definitions-lisp, who-calls-lisp, and edit-callers-lisp will switch whether they prompt for a response or use a default when called with a negative prefix. If they are prompting, there is completion through the inferior LISP by using TAB or M-TAB. When entering an expression in the minibuffer, all of the normal ILISP commands like arglist-lisp also work.

edit-definitions-lisp (M-.) will find a particular type of definition for a symbol. It tries to use the rules described above. The files to be searched are listed in the buffer *Edit-Definitions*. If lisp-edit-files is nil, no search will be done if not found through the inferior LISP. The variable ilisp-locator contains a function that when given the name and type should be able to find the appropriate definition in the file. There is often a flag to cause your LISP to record source files that you will need to set in the initialization file for your LISP. The variable is *record-source-files* in both allegro and lucid. Once a definition has been found, next-definition-lisp (M-,) will find the next definition (or the previous definition with a prefix).

search-lisp (M-?) will search the current tags files, lisp-directory files or buffers in one of lisp-source-modes for a string or a regular expression when called with a prefix. next-definition-lisp (M-,) will find the next definition (or the previous definition with a prefix).

replace-lisp (M-") will replace a string (or a regexp with a prefix) in the current tags files, lisp-directory files or buffers in one of lisp-source-modes.

Here is a summary of the above commands (behavior when given prefix argument is given in parentheses):

M-x lisp-directory

Define a set of files to be used by the source code commands.

M-. (edit-definitions-lisp)

Find definition of a symbol.

M-, (next-definition-lisp)

Find next (previous) definition.

M-x who-calls-lisp

List all the callers of a function.

M-? (search-lisp)

Search for string (regular expression) in current tags, lisp-directory files or buffers. Use next-definition-lisp to find next occurence.

M-" (replace-lisp)

Replace a string (regular expression) in files.

Switching buffers

Commands to make switching between buffers easier.

C-c b (switch-to-lisp)

will pop to the current ILISP buffer or if already in an ILISP buffer, it will return to the buffer that last switched to an ILISP buffer. With a prefix, it will also go to the end of the buffer. If you do not want it to pop, set pop-up-windows to nil.

M-C-l (previous-buffer-lisp)

will switch to the last visited buffer in the current window or the Nth previous buffer with a prefix.

Command history

ILISP mode is built on top of comint-mode, the general command-interpreter-in-a-buffer mode. As such, it inherits many commands and features from this, including a command history mechanism.

Each ILISP buffer has a command history associated with it. Commands that do not match ilisp-filter-regexp and that are longer than ilisp-filter-length and that do not match the immediately prior command will be added to this history.

M-n (comint-next-input)

M-p (comint-previous-input)

Cycle through the input history.

M-s (comint-previous-similar-input)

Cycle through input that has the string typed so far as a prefix.

M-N (comint-psearch-input)

Search forwards for prompt.

M-P (comint-msearch-input)

Search backwards for prompt.

C-c R (comint-msearch-input-matching)

Search backwards for occurrence of prompt followed by string which is prompted for (not a regular expression).

See comint-mode documentation for more information on `comint' commands.

Completion

Commands to reduce number of keystrokes.

M-TAB (complete-lisp)

will try to complete the previous symbol in the current inferior LISP. Partial completion is supported unless ilisp-prefix-match is set to t. (If you set it to t, inferior LISP completions will be faster.) With partial completion, `p--n' would complete to `position-if-not' in Common LISP. If the symbol follows a left paren or a `#'', only symbols with function cells will be considered. If the symbol starts with a `*' or you call with a positive prefix all possible completions will be considered. Only external symbols are considered if there is a package qualification with only one colon. The first time you try to complete a string the longest common substring will be inserted and the cursor will be left on the point of ambiguity. If you try to complete again, you can see the possible completions. If you are in a string, then filename completion will be done instead. And if you try to complete a filename twice, you will see a list of possible completions. Filename components are completed individually, so `/u/mi/' could expand to `/usr/misc/'. If you complete with a negative prefix, the most recent completion (symbol or filename) will be undone.

M-RET (complete)

will complete the current symbol to the most recently seen symbol in Emacs that matches what you have typed so far. Executing it repeatedly will cycle through potential matches. This is from the TMC completion package and there may be some delay as it is initially loaded.

Miscellany

Indentation, parenthesis balancing, and comment commands.

TAB (indent-line-ilisp)

indents for LISP. With prefix, shifts rest of expression rigidly with the current line.

M-C-q (indent-sexp-ilisp)

will indent each line in the next sexp.

M-q (reindent-lisp)

will reindent the current paragraph if in a comment or string. Otherwise it will close the containing defun and reindent it.

C-c ; (comment-region-lisp)

will put prefix copies of comment-start before and comment-end's after the lines in region. To uncomment a region, use a minus prefix.

C-c ) (find-unbalanced-lisp)

will find unbalanced parens in the current buffer. When called with a prefix it will look in the current region.

] (close-all-lisp)

will close all outstanding parens back to the containing form, or a previous left bracket which will be converted to a left parens. If there are too many parens, they will be deleted unless there is text between the last paren and the end of the defun. If called with a prefix, all open left brackets will be closed.

Batch commands

The following commands all deal with making a number of changes all at once. The first time one of these commands is used, there may be some delay as the module is loaded. The eval/compile versions of these commands are always executed asynchronously.

mark-change-lisp (C-c SPC) marks the current defun as being changed. A prefix causes it to be unmarked. clear-changes-lisp (C-c * 0) will clear all of the changes. list-changes-lisp (C-c * l) will show the forms currently marked.

eval-changes-lisp (C-c * e), or compile-changes-lisp (C-c * c) will evaluate or compile these changes as appropriate. If called with a positive prefix, the changes will be kept. If there is an error, the process will stop and show the error and all remaining changes will remain in the list. All of the results will be kept in the buffer *Last-Changes*.

Summary:

C-c SPC (mark-change-lisp)

Mark (unmark) current defun as changed.

C-c * e (eval-changes-lisp)

C-c * c (compile-changes-lisp)

Call with a positive prefix to keep changes.

C-c * 0 (clear-changes-lisp)

C-c * l (list-changes-lisp)

Files and directories

File commands in lisp-source-mode buffers keep track of the last used directory and file. If the point is on a string, that will be the default if the file exists. If the buffer is one of lisp-source-modes, the buffer file will be the default. Otherwise, the last file used in a lisp-source-mode will be used.

C-x C-f (find-file-lisp)

will find a file. If it is in a string, that will be used as the default if it matches an existing file. Symbolic links are expanded so that different references to the same file will end up with the same buffer.

C-c l (load-file-lisp)

will load a file into the inferior LISP. You will be given the opportunity to save the buffer if it has changed and to compile the file if the compiled version is older than the current version.

C-c k (compile-file-lisp)

will compile a file in the current inferior LISP.

C-c ! (default-directory-lisp)

sets the default inferior LISP directory to the directory of the current buffer. If called in an inferior LISP buffer, it sets the Emacs default-directory to the LISP default directory.

Interrupts, aborts, and errors

If you want to abort the last command you can use C-g.

If you want to abort all commands, you should use the command abort-commands-lisp (C-c g). Commands that are aborted will be put in the buffer *Aborted Commands* so that you can see what was aborted. If you want to abort the currently running top-level command, use interrupt-subjob-ilisp (C-c C-c). As a last resort, M-x panic-lisp will reset the ILISP state without affecting the inferior LISP so that you can see what is happening.

delete-char-or-pop-ilisp (C-d) will delete prefix characters unless you are at the end of an ILISP buffer in which case it will pop one level in the break loop.

reset-ilisp, (C-c z) will reset the current inferior LISP's top-level so that it will no longer be in a break loop.

Summary:

C-c C-c (interrupt-subjob-ilisp)

Send a keyboard interrupt signal to lisp.

C-c g (abort-commands-lisp)

Abort all running or unsent commands.

M-x panic-lisp (panic-lisp)

Reset the ILISP process state.

C-c z (reset-ilisp)

Reset lisp to top-level.

C-d (delete-char-or-pop-ilisp)

If at end of buffer, pop a level in break loop.

If lisp-wait-p is nil (the default), all sends are done asynchronously and the results will be brought up only if there is more than one line or there is an error. In case, you will be given the option of ignoring the error, keeping it in another buffer or keeping it and aborting all pending sends. If there is not a command already running in the inferior LISP, you can preserve the break loop. If called with a negative prefix, the sense of lisp-wait-p will be inverted for the next command.

Concept Index

*

.

a

b

c

d

e

f

g

h

i

l

m

n

p

r

s

t

u

w

Key Index

]

c

l

m

r

t

Command Index

Commands available via M-x prefix.

a

c

d

e

f

i

k

l

m

n

o

p

r

s

t

w

Variable Index

Variables and hooks of ILISP.

*

a

c

d

i

l

p

Function Index

Internal functions of ILISP which can be used to write new commands.

c

d

e

i

l

Introduction

ILISP is an interface from GNU Emacs to an inferior LISP. It has the following features:

• Runs under Emacs-18, Emacs-19, and XEmacs-19.
• Support for multiple LISP dialects including Lucid, Allegro and CMU on multiple machines even at the same time.
• Dynamically sized pop-up windows that can be buried and scrolled from any window.
• Packages are properly handled including the distinction between exported and internal symbols.
• Synchronous, asynchronous or batch eval and compile of files, regions, definitions and sexps with optional switching and automatic calling.
• Arglist, documentation, describe, inspect and macroexpand.
• Completion of filename components and LISP symbols including partial matches.
• Find source both with and without help from the inferior LISP, including CLOS methods, multiple definitions and multiple files.
• Edit the callers of a function with and without help from the inferior LISP.
• Trace/untrace a function.
• M-q ("Fill-paragraph") works properly on paragraphs in comments, strings and code.
• Find unbalanced parentheses.
• Super brackets.
• Handles editing, entering and indenting full LISP expressions.
• Next, previous, and similar history mechanism compatible with comint.
• Handles LISP errors.
• Result histories are maintained in the inferior LISP.
• Does not create spurious symbols and handles case issues.
• Online manuals for ILISP and Common LISP.

Acknowledgements

ILISP replaces the standard inferior LISP mode. ILISP is based on comint mode and derived from a number of different interfaces including Symbolics, CMU Common Lisp, and Thinking Machines.

There are many people that have taken the time to report bugs, make suggestions and even better send code to fix bugs or implement new features.

Thanks to Guido Bosch, David Braunegg, Tim Bradshaw, Thomas M. Breuel, Hans Chalupsky, Kimball Collins, Brian Dennis, David Duff, Tom Emerson, Michael Ernst, Scott Fahlman, David Gadbois, Robert P. Goldman, Marty Hall, Richard Harris, Jim Healy, Christopher Hoover, Larry Hunter, Ben Hyde, Chuck Irvine, Michael Kashket, Mark Kantrowitz, Qiegang Long, Erik Naggum, Dan Pierson, Yusuf Pisan, Frank Ritter, Jeffrey Mark Siskind, Neil Smithline, Richard Stallman, Larry Stead, Jason Trenouth, Christof Ullwer, Bjorn Victor, Fred White, Ben Wing, Matsuo Yoshihiro, Jamie Zawinski, Paul Fuqua (for the CMU-CL GC display code) and Marco Antoniotti for bug reports, suggestions and code. Our apologies to anyone we may have forgotten.

Special thanks to Todd Kaufmann for the texinfo file, work on bridge, epoch-pop and for really exercising everything.

Please send bug reports, fixes and extensions to ilisp@naggum.no so that they can be merged into the master source.

--Chris McConnell                     18-Mar-91 
--Ivan Vazquez                        27-Jun-93
--Marco Antoniotti and Rick Campbell  25-Oct-96

This document was generated on 26 October 1996 using the texi2html translator version 1.51.