0
|
1 ;;; -*- Mode: Emacs-Lisp -*-
|
|
2
|
|
3 ;;; ilisp-doc.el --
|
|
4
|
|
5 ;;; This file is part of ILISP.
|
|
6 ;;; Version: 5.7
|
|
7 ;;;
|
|
8 ;;; Copyright (C) 1990, 1991, 1992, 1993 Chris McConnell
|
|
9 ;;; 1993, 1994 Ivan Vasquez
|
|
10 ;;; 1994, 1995 Marco Antoniotti and Rick Busdiecker
|
|
11 ;;;
|
|
12 ;;; Other authors' names for which this Copyright notice also holds
|
|
13 ;;; may appear later in this file.
|
|
14 ;;;
|
|
15 ;;; Send mail to 'ilisp-request@lehman.com' to be included in the
|
|
16 ;;; ILISP mailing list. 'ilisp@lehman.com' is the general ILISP
|
|
17 ;;; mailing list were bugs and improvements are discussed.
|
|
18 ;;;
|
|
19 ;;; ILISP is freely redistributable under the terms found in the file
|
|
20 ;;; COPYING.
|
|
21
|
|
22
|
|
23 ;;;
|
|
24 ;;; ILISP mode documentation
|
|
25 ;;;
|
|
26
|
|
27 (defconst ilisp-documentation
|
|
28 "Major mode for interacting with an inferior LISP process. Runs a
|
|
29 LISP interpreter as a subprocess of Emacs, with LISP I/O through an
|
|
30 Emacs buffer. If you have problems, use M-x ilisp-bug in the buffer
|
|
31 where you are having a problem to send a bug report.
|
|
32
|
|
33 To start a LISP use M-x run-ilisp, or a specific dialect like M-x
|
|
34 allegro. If called with a prefix you will be prompted for a buffer
|
|
35 name and a program to run. The default buffer name is the name of the
|
|
36 dialect. The default program for a dialect will be the value of
|
|
37 DIALECT-program or the value of ilisp-program inherited from a less
|
|
38 specific dialect. If there are multiple LISP's, use the dialect name
|
|
39 or select-ilisp \(\\[select-ilisp]) to select the current ILISP
|
|
40 buffer.
|
|
41
|
|
42 Currently supported LISP dialects include:
|
|
43 clisp
|
|
44 allegro
|
|
45 lucid
|
|
46 kcl
|
|
47 akcl
|
|
48 ibcl
|
|
49 cmulisp
|
|
50 scheme
|
|
51 oaklisp
|
|
52
|
|
53 Customization: Starting a dialect runs the hooks on comint-mode-hook
|
|
54 and ilisp-mode-hook and then DIALECT-hooks specific to dialects in the
|
|
55 nesting order above. On the very first prompt in the inferior LISP,
|
|
56 the hooks on ilisp-init-hook are run. For more information on
|
|
57 creating a new dialect or variables to set in hooks, see ilisp.el.
|
|
58
|
|
59 Most of these key bindings work in both Lisp Mode and ILISP mode.
|
|
60 There are a few additional and-go bindings found in Lisp Mode.
|
|
61 \\{ilisp-use-map}
|
|
62 There are also a few bindings found in global-map including:
|
|
63 \\[ilisp-bury-output] ilisp-bury-output
|
|
64 \\[ilisp-scroll-output] ilisp-scroll-output
|
|
65 \\[previous-buffer-lisp] previous-buffer-lisp
|
|
66 \\[switch-to-lisp] switch-to-lisp
|
|
67
|
|
68 ILISP has a very flexible means for displaying output from the underlying lisp.
|
|
69 All output is funneled through the function bound to ilisp-display-output-function.
|
|
70 That function gets a single argument, the string to display, and should make it
|
|
71 visible to the user. The default display function, ilisp-display-output-default,
|
|
72 displays one-line output in the echo area and longer output in a shrink-wrapped
|
|
73 typeout window. This typeout window can be manipulated with \\[ilisp-bury-output]
|
|
74 ilisp-bury-output, \\[ilisp-scroll-output] ilisp-scroll-output, and \\[ilisp-grow-output]
|
|
75 ilisp-grow-output.
|
|
76
|
|
77 An alternative to typeout windows is to always have the inferior LISP
|
|
78 buffer visible and have all output go there. If your are using the default
|
|
79 display function, then setting lisp-no-popper to T will cause all output to go
|
|
80 to the inferior LISP buffer. Setting comint-always-scroll to T will cause
|
|
81 process output to always be visible. If a command gets an error, you will be
|
|
82 left in the break loop.
|
|
83
|
|
84 Here are the supplied display functions:
|
|
85 ilisp-display-output-default
|
|
86 ilisp-display-output-adaptively
|
|
87 ilisp-display-output-in-echo-area
|
|
88 ilisp-display-output-in-typeout-window
|
|
89 ilisp-display-output-in-lisp-listener
|
|
90
|
|
91 Each ILISP buffer has a command history associated with it. Commands
|
|
92 that do not match ilisp-filter-regexp and that are longer than
|
|
93 ilisp-filter-length and that do not match the immediately prior
|
|
94 command will be added to this history. comint-previous-input
|
|
95 \(\\[comint-previous-input]) and comint-next-input
|
|
96 \(\\[comint-next-input]) cycle through the input history.
|
|
97 comint-previous-similar-input \(\\[comint-previous-similar-input])
|
|
98 cycles through input that has the string typed so far as a prefix.
|
|
99
|
|
100 See comint-mode documentation for more information on comint commands.
|
|
101
|
|
102 A number of commands refer to \"defun\". A \"defun\" is a list that
|
|
103 starts at the left margin in a LISP buffer, or after a prompt in the
|
|
104 ILISP buffer. So the commands refer to the \"defun\" that contains
|
|
105 point.
|
|
106
|
|
107 There are two keyboard modes for interacting with the inferior LISP,
|
|
108 \"interactive\" and \"raw\". Normally you are in interactive mode
|
|
109 where keys are interpreted as commands to EMACS and nothing is sent to
|
|
110 the inferior LISP unless a specific command does so. In raw mode, all
|
|
111 characters are passed directly to the inferior LISP without any
|
|
112 interpretation as EMACS commands. Keys will not be echoed unless
|
|
113 ilisp-raw-echo is T. Raw mode can be turned on interactively by
|
|
114 raw-keys-ilisp \(\\[raw-keys-ilisp]) and will continue until you type
|
|
115 C-g. Raw mode can also be turned on/off by inferior LISP functions if
|
|
116 io-bridge-ilisp \(\\[io-bridge-ilisp]) has been executed in the
|
|
117 inferior LISP interactively or on a hook. To turn on raw mode, a
|
|
118 function should print ^[1^] and to turn it off should print ^[0^].
|
|
119
|
|
120 When you send something to LISP, the status light will reflect the
|
|
121 progress of the command. If you type top-level forms ahead of the
|
|
122 processing, the status may indicate ready when the LISP is actually
|
|
123 running. In a lisp mode buffer the light will reflect the status of
|
|
124 the currently selected inferior LISP unless lisp-show-status is nil.
|
|
125 If you want to find out what command is currently running, use the
|
|
126 command status-lisp \(\\[status-lisp]). If you call it with a prefix,
|
|
127 the pending commands will be displayed as well.
|
|
128
|
|
129 If you are want to abort the last command you can use
|
|
130 \(\\[keyboard-quit]). If you want to abort all commands, you should
|
|
131 use the command abort-commands-lisp \(\\[abort-commands-lisp]).
|
|
132 Commands that are aborted will be put in the buffer *Aborted Commands*
|
|
133 so that you can see what was aborted. If you want to abort the
|
|
134 currently running top-level command, use interrupt-subjob-ilisp
|
|
135 \(\\[interrupt-subjob-ilisp]). As a last resort, \\[panic-lisp] will
|
|
136 reset the ILISP state without affecting the inferior LISP so that you
|
|
137 can see what is happening. If you become totally frustrated, you can
|
|
138 also try \\[repair-ilisp].
|
|
139
|
|
140 bol-ilisp \(\\[bol-ilisp]) will go after the prompt as defined by
|
|
141 comint-prompt-regexp or ilisp-other-prompt or to the left margin with
|
|
142 a prefix.
|
|
143
|
|
144 return-ilisp \(\\[return-ilisp]) knows about prompts and sexps. If an
|
|
145 sexp is not complete, it will indent properly. When an entire sexp is
|
|
146 complete, it is sent to the inferior LISP together with a new line.
|
|
147 If you edit old input, the input will be copied to the end of the
|
|
148 buffer first.
|
|
149
|
|
150 close-and-send-lisp \(\\[close-and-send-lisp]) will close the current
|
|
151 sexp, indent it, then send it to the current inferior LISP.
|
|
152
|
|
153 indent-line-ilisp \(\\[indent-line-ilisp]) indents for LISP. With
|
|
154 prefix, shifts rest of expression rigidly with the current line.
|
|
155
|
|
156 newline-and-indent-lisp \(\\[newline-and-indent-lisp]) will insert a
|
|
157 new line and then indent to the appropriate level. If you are at the
|
|
158 end of the inferior LISP buffer and an sexp, the sexp will be sent to
|
|
159 the inferior LISP without a trailing newline.
|
|
160
|
|
161 indent-sexp-ilisp \(\\[indent-sexp-ilisp]) will indent each line in
|
|
162 the next sexp.
|
|
163
|
|
164 backward-delete-char-untabify \(\\[backward-delete-char-untabify])
|
|
165 converts tabs to spaces as it moves back.
|
|
166
|
|
167 delete-char-or-pop-ilisp \(\\[delete-char-or-pop-ilisp]) will delete
|
|
168 prefix characters unless you are at the end of an ILISP buffer in
|
|
169 which case it will pop one level in the break loop.
|
|
170
|
|
171 reset-ilisp, \(\\[reset-ilisp]) will reset the current inferior LISP's
|
|
172 top-level so that it will no longer be in a break loop.
|
|
173
|
|
174 switch-to-lisp \(\\[switch-to-lisp]) will pop to the current ILISP
|
|
175 buffer or if already in an ILISP buffer, it will return to the buffer
|
|
176 that last switched to an ILISP buffer. With a prefix, it will also go
|
|
177 to the end of the buffer. If you do not want it to pop, set
|
|
178 pop-up-windows to nil.
|
|
179
|
|
180 call-defun-lisp \(\\[call-defun-lisp]) will put a call to the current
|
|
181 defun in the inferior LISP and go there. If it is a \(def* name form,
|
|
182 it looks up reasonable forms of name in the input history unless
|
|
183 called with a prefix. If not found, \(name or *name* will be inserted.
|
|
184 If it is not a def* form, the whole defun will be put in the buffer.
|
|
185
|
|
186 reposition-window-lisp \(\\[reposition-window-lisp]) will scroll the
|
|
187 current window to show as much of the current defun and its
|
|
188 introductory comments as possible without moving the point. If called
|
|
189 with a prefix, the point will be moved if necessary to show the start
|
|
190 of the defun. If called more than once with the first line of the
|
|
191 defun showing, the introductory comments will be shown or suppressed.
|
|
192
|
|
193 previous-buffer-lisp \(\\[previous-buffer-lisp]) will switch to the
|
|
194 last visited buffer in the current window or the Nth previous buffer
|
|
195 with a prefix.
|
|
196
|
|
197 find-unbalanced-lisp \(\\[find-unbalanced-lisp]) will find unbalanced
|
|
198 parens in the current buffer. When called with a prefix it will look
|
|
199 in the current region.
|
|
200
|
|
201 close-all-lisp \(\\[close-all-lisp]) will close all outstanding
|
|
202 parens back to the containing form, or a previous left bracket
|
|
203 which will be converted to a left parens. If there are too many
|
|
204 parens, they will be deleted unless there is text between the
|
|
205 last paren and the end of the defun. If called with a prefix,
|
|
206 all open left brackets will be closed.
|
|
207
|
|
208 reindent-lisp \(\\[reindent-lisp]) will reindent the current paragraph
|
|
209 if in a comment or string. Otherwise it will close the containing
|
|
210 defun and reindent it.
|
|
211
|
|
212 comment-region-lisp \(\\[comment-region-lisp]) will put prefix copies of
|
|
213 comment-start before and comment-end's after the lines in region. To
|
|
214 uncomment a region, use a minus prefix.
|
|
215
|
|
216 The very first inferior LISP command executed may send some forms to
|
|
217 initialize the inferior LISP.
|
|
218
|
|
219 Each time an inferior LISP command is executed, the last form sent can be
|
|
220 seen in the \*ilisp-send* buffer.
|
|
221
|
|
222 The first time an inferior LISP mode command is executed in a Lisp
|
|
223 Mode buffer, the package will be determined by using the regular
|
|
224 expression ilisp-package-regexp to find a package sexp and then
|
|
225 passing that sexp to the inferior LISP through ilisp-package-command.
|
|
226 For the clisp dialect, this will find the first \(in-package PACKAGE)
|
|
227 form in the file. A buffer's package will be displayed in the mode
|
|
228 line. set-buffer-package-lisp \(\\[set-buffer-package-lisp]) will
|
|
229 update the current package from the buffer. If it is called with a
|
|
230 prefix, the package can be set manually. If a buffer has no
|
|
231 specification, forms will be evaluated in the current inferior LISP
|
|
232 package. package-lisp \(\\[package-lisp]) will show the current
|
|
233 package of the inferior LISP. set-package-lisp
|
|
234 \(\\[set-package-lisp]) will set the inferior LISP package to the
|
|
235 current buffer's package or to a manually entered package with a
|
|
236 prefix.
|
|
237
|
|
238 describe-lisp, inspect-lisp, arglist-lisp, documentation-lisp,
|
|
239 macroexpand-1-lisp, macroexpand-lisp, edit-definitions-lisp,
|
|
240 who-calls-lisp, edit-callers-lisp and trace-defun-lisp will switch
|
|
241 whether they prompt for a response or use a default when called with a
|
|
242 negative prefix. If they are prompting, there is completion through
|
|
243 the inferior LISP by using TAB or M-TAB. When you are entering an
|
|
244 expression in the minibuffer, all of the normal ilisp commands like
|
|
245 arglist-lisp also work.
|
|
246
|
|
247 Commands that work on a function will use the nearest previous
|
|
248 function symbol. This is either a symbol after a #' or the symbol at
|
|
249 the start of the current list.
|
|
250
|
|
251 describe-lisp \(\\[describe-lisp]) will describe the previous sexp.
|
|
252 inspect-lisp \(\\[inpsect-lisp]) will inspect the previous sexp.If
|
|
253 there is no previous-sexp and you are in an ILISP buffer, the previous
|
|
254 result will be described or inspected.
|
|
255
|
|
256 arglist-lisp \(\\[arglist-lisp]) will return the arglist of the
|
|
257 current function. With a numeric prefix, the leading paren will be
|
|
258 removed and the arglist will be inserted into the buffer.
|
|
259
|
|
260 documentation-lisp \(\\[documentation-lisp]) infers whether function
|
|
261 or variable documentation is desired. With a negative prefix, you can
|
|
262 specify the type of documentation as well. With a positive prefix the
|
|
263 documentation of the current function call is returned.
|
|
264
|
|
265 If the Franz online Common LISP manual is available, fi:clman
|
|
266 \(\\[fi:clman]) will get information on a specific symbol.
|
|
267 fi:clman-apropos \(\\[fi:clman-apropos]) will get information apropos
|
|
268 a specific string. Some of the documentation is specific to the
|
|
269 allegro dialect, but most of it is for standard Common LISP.
|
|
270
|
|
271 macroexpand-lisp \(\\[macroexpand-lisp]) and macroexpand-1-lisp
|
|
272 \(\\[macroexpand-1-lisp]) will be applied to the next sexp. They will
|
|
273 insert their result into the buffer if called with a numeric prefix.
|
|
274
|
|
275 complete-lisp \(\\[complete-lisp]) will try to complete the previous
|
|
276 symbol in the current inferior LISP. Partial completion is supported
|
|
277 unless ilisp-prefix-match is set to T. \(If you set it to T, inferior
|
|
278 LISP completions will be faster.) With partial completion, \"p--n\"
|
|
279 would complete to \"position-if-not\" in Common LISP. If the symbol
|
|
280 follows a left paren or a #', only symbols with function cells will be
|
|
281 considered. If the symbol starts with a \* or you call with a
|
|
282 positive prefix all possible completions will be considered. Only
|
|
283 external symbols are considered if there is a package qualification
|
|
284 with only one colon. The first time you try to complete a string the
|
|
285 longest common substring will be inserted and the cursor will be left
|
|
286 on the point of ambiguity. If you try to complete again, you can see
|
|
287 the possible completions. If you are in a string, then filename
|
|
288 completion will be done instead. And if you try to complete a
|
|
289 filename twice, you will see a list of possible completions. Filename
|
|
290 components are completed individually, so /u/mi/ could expand to
|
|
291 /usr/misc/. If you complete with a negative prefix, the most recent
|
|
292 completion \(symbol or filename) will be undone.
|
|
293
|
|
294 complete \(\\[complete]) will complete the current symbol to the most
|
|
295 recently seen symbol in Emacs that matches what you have typed so far.
|
|
296 Executing it repeatedly will cycle through potential matches. This is
|
|
297 from the TMC completion package and there may be some delay as it is
|
|
298 initially loaded.
|
|
299
|
|
300 trace-defun-lisp \(\\[trace-defun-lisp]) traces the current defun.
|
|
301 When called with a numeric prefix the function will be untraced.
|
|
302
|
|
303 trace-defun-lisp-break \(\\[trace-defun-lisp-break]) traces the
|
|
304 current defun but sets a breakpoint in the function if possible.
|
|
305 When called with a numeric prefix the function will be untraced.
|
|
306
|
|
307 default-directory-lisp \(\\[default-directory-lisp]\) sets the default
|
|
308 inferior LISP directory to the directory of the current buffer. If
|
|
309 called in an inferior LISP buffer, it sets the Emacs default-directory
|
|
310 the LISP default directory.
|
|
311
|
|
312 The eval/compile commands evaluate or compile the forms specified. If
|
|
313 any of the forms contain an interactive command, then the command will
|
|
314 never return. To get out of this state, you need to use
|
|
315 abort-commands-lisp \(\\[abort-commands-lisp]). The eval/compile
|
|
316 commands verify that their expressions are balanced and then send the
|
|
317 form to the inferior LISP. If called with a positive prefix, the
|
|
318 result of the operation will be inserted into the buffer after the
|
|
319 form that was just sent. If lisp-wait-p is t, then EMACS will display
|
|
320 the result of the command in the minibuffer or a pop-up window. If
|
|
321 lisp-wait-p is nil, (the default) the send is done asynchronously and
|
|
322 the results will be brought up only if there is more than one line or
|
|
323 there is an error. In this case, you will be given the option of
|
|
324 ignoring the error, keeping it in another buffer or keeping it and
|
|
325 aborting all pending sends. If there is not a command already running
|
|
326 in the inferior LISP, you can preserve the break loop. If called with
|
|
327 a negative prefix, the sense of lisp-wait-p will be inverted for the
|
|
328 next command. The and-go versions will perform the operation and then
|
|
329 immediately switch to the ILISP buffer where you will see the results
|
|
330 of executing your form. If eval-defun-and-go-lisp
|
|
331 \(\\[eval-defun-and-go-lisp]) or compile-defun-and-go-lisp
|
|
332 \(\\[compile-defun-and-go-lisp]) is called with a prefix, a call for
|
|
333 the form will be inserted as well.
|
|
334
|
|
335 When an eval is done of a single form matching ilisp-defvar-regexp,
|
|
336 the corresponding symbol will be unbound and the value assigned again.
|
|
337
|
|
338 When compile-defun-lisp \(\\[compile-defun-lisp]) is called in an
|
|
339 inferior LISP buffer with no current form, the last form typed to the
|
|
340 top-level will be compiled.
|
|
341
|
|
342 The following commands all deal with finding things in source code.
|
|
343 The first time that one of these commands is used, there may be some
|
|
344 delay while the source module is loaded. When searching files, the
|
|
345 first applicable rule is used: 1) try the inferior LISP, 2) try a tags
|
|
346 file if defined, 3) try all buffers in one of lisp-source-modes or all
|
|
347 files defined using lisp-directory.
|
|
348
|
|
349 lisp-directory \(\\[lisp-directory]) defines a set of files to be
|
|
350 searched by the source code commands. It prompts for a directory and
|
|
351 sets the source files to be those in the directory that match entries
|
|
352 in auto-mode-alist for modes in lisp-source-modes. With a positive
|
|
353 prefix, the files are appended. With a negative prefix, all current
|
|
354 buffers that are in one of lisp-source-modes will be searched. This
|
|
355 is also what happens by default. Using this command stops using a
|
|
356 tags file.
|
|
357
|
|
358 edit-definitions-lisp \(\\[edit-definitions-lisp]) will find a
|
|
359 particular type of definition for a symbol. It tries to use the rules
|
|
360 described above. The files to be searched are listed in the buffer
|
|
361 \*Edit-Definitions*. If lisp-edit-files is nil, no search will be
|
|
362 done if not found through the inferior LISP. The variable
|
|
363 ilisp-locator contains a function that when given the name and type
|
|
364 should be able to find the appropriate definition in the file. There
|
|
365 is often a flag to cause your LISP to record source files that you
|
|
366 will need to set in the initialization file for your LISP. The
|
|
367 variable is \*record-source-files* in both allegro and lucid. Once a
|
|
368 definition has been found, next-definition-lisp
|
|
369 \(\\[next-definition-lisp]) will find the next definition. \(Or the
|
|
370 previous definition with a prefix.)
|
|
371
|
|
372 edit-callers-lisp \(\\[edit-callers-lisp]) will generate a list of all
|
|
373 of the callers of a function in the current inferior LISP and edit the
|
|
374 first caller using edit-definitions-lisp. Each successive call to
|
|
375 next-caller-lisp \(\\[next-caller-lisp]) will edit the next caller.
|
|
376 \(Or the previous caller with a prefix.) The list is stored in the
|
|
377 buffer \*All-Callers*. You can also look at the callers by doing
|
|
378 who-calls-lisp \(\\[who-calls-lisp]).
|
|
379
|
|
380 search-lisp \(\\[search-lisp]) will search the current tags files,
|
|
381 lisp directory files or buffers in one of lisp-source-modes for a
|
|
382 string or a regular expression when called with a prefix.
|
|
383 \(\\[next-definition-lisp]) will find the next definition. \(Or the
|
|
384 previous definition with a prefix.)
|
|
385
|
|
386 replace-lisp \(\\[replace-lisp]) will replace a string (or a regexp
|
|
387 with a prefix) in the current tags files, lisp directory files or
|
|
388 buffers in one of lisp-source-modes.
|
|
389
|
|
390 The following commands all deal with making a number of changes all at
|
|
391 once. The first time one of these commands is used, there may be some
|
|
392 delay as the module is loaded. The eval/compile versions of these
|
|
393 commands are always executed asynchronously.
|
|
394
|
|
395 mark-change-lisp \(\\[mark-change-lisp]) marks the current defun as
|
|
396 being changed. A prefix causes it to be unmarked. clear-changes-lisp
|
|
397 \(\\[clear-changes-lisp]) will clear all of the changes.
|
|
398 list-changes-lisp \(\\[list-changes-lisp]) will show the forms
|
|
399 currently marked.
|
|
400
|
|
401 eval-changes-lisp \(\\[eval-changes-lisp]), or compile-changes-lisp
|
|
402 \(\\[compile-changes-lisp]) will evaluate or compile these changes as
|
|
403 appropriate. If called with a positive prefix, the changes will be
|
|
404 kept. If there is an error, the process will stop and show the error
|
|
405 and all remaining changes will remain in the list. All of the results
|
|
406 will be kept in the buffer *Last-Changes*.
|
|
407
|
|
408 File commands in lisp-source-mode buffers keep track of the last used
|
|
409 directory and file. If the point is on a string, that will be the
|
|
410 default if the file exists. If the buffer is one of
|
|
411 lisp-source-modes, the buffer file will be the default. Otherwise,
|
|
412 the last file used in a lisp-source-mode will be used.
|
|
413
|
|
414 find-file-lisp \(\\[find-file-lisp]) will find a file. If it is in a
|
|
415 string, that will be used as the default if it matches an existing
|
|
416 file. Symbolic links are expanded so that different references to the
|
|
417 same file will end up with the same buffer.
|
|
418
|
|
419 load-file-lisp \(\\[load-file-lisp]) will load a file into the inferior
|
|
420 LISP. You will be given the opportunity to save the buffer if it has
|
|
421 changed and to compile the file if the compiled version is older than
|
|
422 the current version.
|
|
423
|
|
424 compile-file-lisp \(\\[compile-file-lisp]) will compile a file in the
|
|
425 current inferior LISP.")
|