Commit | Line | Data |
---|---|---|
977235e0 C |
1 | ." $Header: /na/franz/doc/RCS/ch16.n,v 1.1 83/01/31 07:08:55 jkf Exp $ |
2 | .Lc The\ LISP\ Editor 16 | |
3 | ||
4 | .sh 2 The\ Editors 16 | |
5 | ||
6 | It is quite possible to use VI, Emacs or other standard editors to edit your | |
7 | lisp programs, and many people do just that. | |
8 | However there is a lisp | |
9 | structure editor which is particularly good for the editing | |
10 | of lisp programs, and operates in a rather different fashion, namely | |
11 | within a lisp environment. | |
12 | application. It | |
13 | is handy to know how to use it for fixing problems without exiting | |
14 | from the lisp system (e.g. from the debugger | |
15 | so you can continue to execute rather than having to start over.) The | |
16 | editor is not quite like the top-level and debugger, in that it expects | |
17 | you to type editor commands to it. It will not evaluate whatever you | |
18 | happen to type. (There is an editor command to evaluate things, though.) | |
19 | ||
20 | The editor is available (assuming your system is set up correctly with | |
21 | a lisp library) by typing (load 'cmufncs) and (load 'cmuedit). | |
22 | ||
23 | The most frequent use of the editor is to change function | |
24 | definitions by starting the editor with one of the commands described in | |
25 | section 16.14. (see \fIeditf\fP), values (\fIeditv\fP), properties | |
26 | (\fIeditp\fP), and expressions (\fIedite\fP). The beginner is | |
27 | advised to start with the following (very basic) commands: \fIok, | |
28 | undo, p, #\fP, under which are explained two different basic commands | |
29 | which start with numbers, and f. | |
30 | ||
31 | This documentation, and the editor, were imported from PDP-10 CMULisp | |
32 | by Don Cohen. PDP-10 CMULisp is based on UCILisp, and the editor | |
33 | itself was derived from an early version of Interlisp. Lars | |
34 | Ericson, the author of this section, | |
35 | has provided this very concise summary. | |
36 | Tutorial examples and implementation details | |
37 | may be found in the Interlisp Reference Manual, | |
38 | where a similar editor is described. | |
39 | ||
40 | .sh 2 Scope\ of\ Attention | |
41 | ||
42 | Attention-changing commands allow you to look at a different | |
43 | part of a Lisp expression you are editing. | |
44 | The sub-structure upon which the editor's attention is | |
45 | centered is called "the current expression". Changing the | |
46 | current expression means shifting attention and not actually modifying | |
47 | any structure. | |
48 | .Fb | |
49 | .fi | |
50 | \fISCOPE OF ATTENTION COMMAND SUMMARY\fP | |
51 | ||
52 | \fIn (n>0) \fP. Makes the nth element of the current expression be the | |
53 | new current expression. | |
54 | ||
55 | \fI-n (n>0)\fP. Makes the nth element from the end of the current | |
56 | expression be the new current expression. | |
57 | ||
58 | \fI0\fP. Makes the next higher expression be the new correct | |
59 | expression. If the intention is to go back to the next higher left | |
60 | parenthesis, use the command !0. | |
61 | ||
62 | \fIup\ \fP. If a p command would cause the editor to | |
63 | type ... before typing the current expression, (the current | |
64 | expression is a tail of the next higher expression) then has no effect; | |
65 | else, up makes the old current expression the first element in the new | |
66 | current expression. | |
67 | ||
68 | \fI!0 \fP. Goes back to the next higher left parenthesis. | |
69 | ||
70 | \fI^\ \fP. | |
71 | Makes the top level expression be the current expression. | |
72 | ||
73 | \fInx\ \fP. | |
74 | Makes the current expression be the next expression. | |
75 | ||
76 | \fI(nx n)\fP equivalent to n nx commands. | |
77 | ||
78 | \fI!nx \fP. Makes current expression be the next | |
79 | expression at a higher level. Goes through any number of right | |
80 | parentheses to get to the next expression. | |
81 | ||
82 | \fI bk\ \fP. | |
83 | Makes the current expression be the previous expression in the next | |
84 | higher expression. | |
85 | ||
86 | \fI(nth n) n>0 \fP. Makes the list starting with | |
87 | the nth element of the current expression be the current expression. | |
88 | ||
89 | \fI(nth $) - generalized nth command.\fP nth locates $, and then backs | |
90 | up to the current level, where the new current expression is the tail | |
91 | whose first element contains, however deeply, the expression that was | |
92 | the terminus of the location operation. | |
93 | ||
94 | \fI:: \fP. (pattern :: . $) e.g., (cond :: | |
95 | return). finds a cond that contains a return, at any depth. | |
96 | ||
97 | \fI(below com x) \fP. The below command is useful for | |
98 | locating a substructure by specifying something it contains. (below | |
99 | cond) will cause the cond clause containing the current expression to | |
100 | become the new current expression. Suppose you are editing a list | |
101 | of lists, and want to find a sublist that contains a foo (at any | |
102 | depth). Then simply executes f foo (below \). | |
103 | ||
104 | \fI(nex x) \fP. same as \fI(below x)\fP followed by | |
105 | nx. For example, if you are deep inside of a selectq clause, you | |
106 | can advance to the next clause with \fI(nex selectq)\fP. | |
107 | ||
108 | \fInex\fP. The atomic form of \fInex\fP is useful | |
109 | if you will be performing repeated executions of \fI(nex x)\fP. By | |
110 | simply marking the chain corresponding to x, you can use \fInex\fP to step | |
111 | through the sublists. | |
112 | .Fe | |
113 | .br | |
114 | .sh 2 Pattern\ Matching\ Commands | |
115 | ||
116 | Many editor commands that search take patterns. | |
117 | A pattern \fIpat\fP matches with x if: | |
118 | .Fb | |
119 | .fi | |
120 | \fIPATTERN SPECIFICATION SUMMARY\fP | |
121 | ||
122 | - \fIpat\fP is \fIeq\fP to x. | |
123 | ||
124 | - \fIpat\fP is &. | |
125 | ||
126 | - \fIpat\fP is a number and equal to x. | |
127 | ||
128 | - if (car \fIpat\fP) is the atom *any*, (cdr \fIpat\fP) is a list of patterns, and | |
129 | \fIpat\fP matches x if and only if one of the patterns on (cdr \fIpat\fP) matches x. | |
130 | ||
131 | - if \fIpat\fP is a literal atom or string, and (nthchar \fIpat\fP -1) is @, then | |
132 | \fIpat\fP matches with any literal atom or string which has the same initial | |
133 | characters as \fIpat\fP, e.g. ver@ matches with verylongatom, as well as | |
134 | "verylongstring". | |
135 | ||
136 | - if (car \fIpat\fP) is the atom --, \fIpat\fP matches x if (a) (cdr \fIpat\fP)=nil, i.e. | |
137 | \fIpat\fP=(--), e.g., (a --) matches (a) (a b c) and (a . b) in other words, | |
138 | -- can match any tail of a list. (b) (cdr \fIpat\fP) matches with some tail | |
139 | of x, e.g. (a -- (&)) will match with (a b c (d)), but not (a b c d), | |
140 | or (a b c (d) e). however, note that (a -- (&) --) will match with (a b | |
141 | c (d) e). in other words, -- will match any interior segment of a list. | |
142 | ||
143 | - if (car \fIpat\fP) is the atom ==, \fIpat\fP matches x if and only if (cdr \fIpat\fP) | |
144 | is \fIeq\fP to x. (this pattern is for use by programs that call the editor | |
145 | as a subroutine, since any non-atomic expression in a command typed in | |
146 | by the user obviously cannot be \fIeq\fP to existing structure.) | |
147 | - otherwise if x is a list, \fIpat\fP matches x if (car \fIpat\fP) matches (car | |
148 | x), and (cdr \fIpat\fP) matches (cdr x). | |
149 | ||
150 | - when searching, the pattern matching routine is called only to match | |
151 | with elements in the structure, unless the pattern begins with :::, in | |
152 | which case cdr of the pattern is matched against tails in the | |
153 | structure. (in this case, the tail does not have to be a proper tail, | |
154 | e.g. (::: a --) will match with the element (a b c) as well as with cdr | |
155 | of (x a b c), since (a b c) is a tail of (a b c).) | |
156 | .Fe | |
157 | .sh 3 Commands\ That\ Search | |
158 | .Fb | |
159 | .fi | |
160 | \fISEARCH COMMAND SUMMARY\fP | |
161 | ||
162 | \fIf pattern \fP. f informs the editor that the next | |
163 | command is to be interpreted as a pattern. If no pattern is given on | |
164 | the same line as the f then the last pattern is used. f pattern means | |
165 | find the next instance of pattern. | |
166 | ||
167 | \fI(f pattern n)\fP. Finds the next instance of pattern. | |
168 | ||
169 | \fI(f pattern t)\fP. similar to f pattern, except, for example, if the | |
170 | current expression is (cond ..), f cond will look for the next cond, | |
171 | but (f cond t) will 'stay here'. | |
172 | ||
173 | \fI(f pattern n) n>0\fP. Finds the nth place that pattern matches. | |
174 | If the current expression is (foo1 foo2 foo3), (f f00@ 3) will find foo3. | |
175 | ||
176 | \fI(f pattern) or (f pattern nil)\fP. only matches with elements at | |
177 | the top level of the current expression. If the current expression is | |
178 | \fI(prog nil (setq x (cond & &)) (cond &) ...)\fP f (cond --) will find | |
179 | the cond inside the setq, whereas (f (cond --)) will find the top level | |
180 | cond, i.e., the second one. | |
181 | ||
182 | \fI(second . $) \fP. | |
183 | same as (lc . $) followed by another (lc . $) except that if the | |
184 | first succeeds and second fails, no change is made to the edit chain. | |
185 | ||
186 | \fI(third . $) \fP. Similar to second. | |
187 | ||
188 | \fI(fs pattern1 ... patternn) \fP. | |
189 | equivalent to f pattern1 followed by f pattern2 ... followed by f | |
190 | pattern n, so that if f pattern m fails, edit chain is left at place | |
191 | pattern m-1 matched. | |
192 | ||
193 | \fI(f= expression x) \fP. Searches for a structure eq | |
194 | to expression. | |
195 | ||
196 | \fI(orf pattern1 ... patternn) \fP. Searches for an | |
197 | expression that is matched by either pattern1 or ... patternn. | |
198 | ||
199 | \fIbf pattern \fP. backwards find. If the current | |
200 | expression is \fI(prog nil (setq x (setq y (list z))) (cond ((setq w | |
201 | --) --)) --)\fP f list followed by bf setq will leave the current | |
202 | expression as (setq y (list z)), as will f cond followed by bf setq | |
203 | ||
204 | \fI(bf pattern t)\fP. backwards find. Search always includes current | |
205 | expression, i.e., starts at end of current expression and works | |
206 | backward, then ascends and backs up, etc. | |
207 | .Fe | |
208 | .sh 4 Location\ Specifications | |
209 | . | |
210 | Many editor commands use a | |
211 | method of specifying position called a location specification. The | |
212 | meta-symbol $ is used to denote a location specification. $ is a | |
213 | list of commands interpreted as described above. $ can also be atomic, | |
214 | in which case it is interpreted as (list $). a location specification | |
215 | is a list of edit commands that are executed in the normal fashion with | |
216 | two exceptions. first, all commands not recognized by the editor are | |
217 | interpreted as though they had been preceded by f. | |
218 | The location specification | |
219 | (cond 2 3) specifies the 3rd element in the first clause of the next | |
220 | cond. | |
221 | ||
222 | the if command and the ## function provide a way of using in location | |
223 | specifications arbitrary predicates applied to elements in the current | |
224 | expression. | |
225 | ||
226 | In insert, delete, replace and change, if $ is nil (empty), the | |
227 | corresponding operation is performed on the current edit chain, i.e. | |
228 | (replace with (car x)) is equivalent to (:(car x)). for added | |
229 | readability, here is also permitted, e.g., (insert (print x) before | |
230 | here) will insert (print x) before the current expression (but not | |
231 | change the edit chain). It is perfectly legal to ascend to insert, | |
232 | replace, or delete. for example (insert (\fIreturn\fP) after ^ prog | |
233 | -1) will go to the top, find the first prog, and insert a | |
234 | (\fIreturn\fP) at its end, and not change the current edit chain. | |
235 | ||
236 | The a, b, and : commands all make special checks in e1 thru em for | |
237 | expressions of the form (## . coms). In this case, the expression used | |
238 | for inserting or replacing is a copy of the current expression after | |
239 | executing coms, a list of edit commands. (insert (## f cond -1 -1) | |
240 | after3) will make a copy of the last form in the last clause of the | |
241 | next cond, and insert it after the third element of the current | |
242 | expression. | |
243 | ||
244 | \fI$\fP. In descriptions of the editor, the meta-symbol $ is used to | |
245 | denote a location specification. $ is a list of commands interpreted | |
246 | as described above. $ can also be atomic. | |
247 | .Fb | |
248 | .fi | |
249 | \fILOCATION COMMAND SUMMARY\fP | |
250 | ||
251 | \fI(lc . $) \fP. | |
252 | Provides a way of explicitly invoking the location operation. | |
253 | (lc cond 2 3) will perform search. | |
254 | ||
255 | \fI(lcl . $) \fP. Same as lc except search is confined | |
256 | to current expression. To find a cond containing a \fIreturn\fP, one | |
257 | might use the location specification (cond (lcl \fIreturn\fP) \) where | |
258 | the \ would reverse the effects of the lcl command, and make the final | |
259 | current expression be the cond. | |
260 | .Fe | |
261 | .sh 3 The\ Edit\ Chain | |
262 | The edit-chain is a list of which the first element is the the one you | |
263 | are now editing ("current expression"), the next element is what would | |
264 | become the current expression if you were to do a 0, etc., until the | |
265 | last element which is the expression that was passed to the editor. | |
266 | .Fb | |
267 | .fi | |
268 | \fIEDIT CHAIN COMMAND SUMMARY\fP | |
269 | ||
270 | \fImark \fP. | |
271 | Adds the current edit chain to the front of the list marklst. | |
272 | ||
273 | \fI_ \fP. | |
274 | Makes the new edit chain be (car marklst). | |
275 | ||
276 | \fI(_ pattern) \fP. Ascends the edit chain looking for | |
277 | a link which matches pattern. for example: | |
278 | ||
279 | \fI__ \fP. | |
280 | Similar to _ but also erases the mark. | |
281 | ||
282 | \fI\\ \fP. Makes the edit chain be the value of unfind. | |
283 | unfind is set to the current edit chain by each command that makes a | |
284 | "big jump", i.e., a command that usually performs more than a single | |
285 | ascent or descent, namely ^, _, __, !nx, all commands that involve a | |
286 | search, e.g., f, lc, ::, below, et al and \ and \p themselves. if | |
287 | the user types f cond, and then f car, \ would take him back to the | |
288 | cond. another \ would take him back to the car, etc. | |
289 | ||
290 | \fI\\p \fP. Restores the edit chain to its state as of | |
291 | the last print operation. If the edit chain has not changed since the | |
292 | last printing, \\p restores it to its state as of the printing before | |
293 | that one. If the user types p followed by 3 2 1 p, \\p will return to | |
294 | the first p, i.e., would be equivalent to 0 0 0. Another \\p would | |
295 | then take him back to the second p. | |
296 | .Fe | |
297 | .sh 2 Printing\ Commands | |
298 | .Fb | |
299 | .fi | |
300 | \fIPRINTING COMMAND SUMMARY\fP | |
301 | ||
302 | \fIp \fP Prints current expression in abbreviated | |
303 | form. (p m) prints mth element of current expression in abbreviated | |
304 | form. (p m n) prints mth element of current expression as though | |
305 | printlev were given a depth of n. (p 0 n) prints current expression as | |
306 | though printlev were given a depth of n. (p cond 3) will work. | |
307 | ||
308 | \fI? \fP. prints the current expression as though | |
309 | printlev were given a depth of 100. | |
310 | ||
311 | \fIpp \fP. pretty-prints the current expression. | |
312 | ||
313 | \fIpp*\fP. is like pp, but forces comments to be shown. | |
314 | .Fe | |
315 | .sh 2 Structure\ Modification\ Commands | |
316 | ||
317 | All structure modification commands are undoable. See \fIundo\fP. | |
318 | ||
319 | .Fb | |
320 | .fi | |
321 | \fISTRUCTURE MODIFICATION COMMAND SUMMARY\fP | |
322 | ||
323 | \fI# [editor commands]\fP (n) n>1 deletes the | |
324 | corresponding element from the current expression. | |
325 | ||
326 | \fI(n e1 ... em) n,m>1\fP replaces the nth element in the current | |
327 | expression with e1 ... em. | |
328 | ||
329 | \fI(-n e1 ... em) n,m>1\fP inserts e1 ... em before the n element in the | |
330 | current expression. | |
331 | ||
332 | \fI(n e1 ... em)\fP (the letter "n" for "next" or "nconc", not a number) | |
333 | m>1 attaches e1 ... em at the end of the current expression. | |
334 | ||
335 | \fI(a e1 ... em) \fP. inserts e1 ... em after the | |
336 | current expression (or after its first element if it is a tail). | |
337 | ||
338 | \fI(b e1 ... em) \fP. inserts e1 ... em before the | |
339 | current expression. to insert foo before the last element in the | |
340 | current expression, perform -1 and then (b foo). | |
341 | ||
342 | \fI(: e1 ... em) \fP. replaces the current expression | |
343 | by e1 ... em. If the current expression is a tail then replace its | |
344 | first element. | |
345 | ||
346 | \fIdelete or (:) \fP. deletes the current expression, | |
347 | or if the current expression is a tail, deletes its first element. | |
348 | ||
349 | \fI(delete . $)\fP. does a (lc . $) followed by delete. current edit | |
350 | chain is not changed. | |
351 | ||
352 | \fI(insert e1 ... em before . $) \fP. similar to (lc. | |
353 | $) followed by (b e1 ... em). | |
354 | ||
355 | \fI(insert e1 ... em after . $)\fP. similar to insert before except | |
356 | uses a instead of b. | |
357 | ||
358 | \fI(insert e1 ... em for . $)\fP. similar to insert before except | |
359 | uses : for b. | |
360 | ||
361 | \fI(replace $ with e1 ... em) \fP. here $ is the | |
362 | segment of the command between replace and with. | |
363 | ||
364 | \fI(change $ to e1 ... em) \fP. same as replace with. | |
365 | .Fe | |
366 | .sh 2 Extraction\ and\ Embedding\ Commands | |
367 | .Fb | |
368 | .fi | |
369 | \fIEXTRACTION AND EMBEDDING COMMAND SUMMARY\fP | |
370 | ||
371 | \fI(xtr . $) \fP. replaces the original current | |
372 | expression with the expression that is current after performing (lcl . $). | |
373 | ||
374 | \fI(mbd x) \fP. x is a list, substitutes the current | |
375 | expression for all instances of the atom * in x, and replaces the | |
376 | current expression with the result of that substitution. (mbd x) : x | |
377 | atomic, same as (mbd (x *)). | |
378 | ||
379 | \fI(extract $1 from $2) \fP. extract is an editor | |
380 | command which replaces the current expression with one of its | |
381 | subexpressions (from any depth). ($1 is the segment between extract | |
382 | and from.) example: if the current expression is (print (cond | |
383 | ((null x) y) (t z))) then following (extract y from cond), the current | |
384 | expression will be (print y). (extract 2 -1 from cond), (extract y | |
385 | from 2), (extract 2 -1 from 2) will all produce the same result. | |
386 | ||
387 | \fI(embed $ in . x) \fP. embed replaces the current | |
388 | expression with a new expression which contains it as a subexpression. | |
389 | ($ is the segment between embed and in.) example: (embed print in | |
390 | setq x), (embed 3 2 in \fIreturn\fP), (embed cond 3 1 in (or * (null x))). | |
391 | .Fe | |
392 | .sh 2 Move\ and\ Copy\ Commands | |
393 | .Fb | |
394 | .fi | |
395 | \fIMOVE AND COPY COMMAND SUMMARY\fP | |
396 | ||
397 | \fI(move $1 to com . $2) \fP. ($1 is the segment | |
398 | between move and to.) where com is before, after, or the name of a | |
399 | list command, e.g., :, n, etc. If $2 is nil, or (here), the current | |
400 | position specifies where the operation is to take place. If $1 is nil, | |
401 | the move command allows the user to specify some place the current | |
402 | expression is to be moved to. if the current expression is (a b d c), | |
403 | (move 2 to after 4) will make the new current expression be (a c d b). | |
404 | ||
405 | \fI(mv com . $) \fP. is the same as (move here to com . $). | |
406 | ||
407 | \fI(copy $1 to com . $2)\fP is like move except that the source | |
408 | expression is not deleted. | |
409 | ||
410 | \fI(cp com . $)\fP. is like mv except that the source expression is | |
411 | not deleted. | |
412 | .Fe | |
413 | .sh 2 Parentheses\ Moving\ Commands | |
414 | The commands presented in this section permit modification of the | |
415 | list structure itself, as opposed to modifying components thereof. | |
416 | their effect can be described as inserting or removing a single left or | |
417 | right parenthesis, or pair of left and right parentheses. | |
418 | .Fb | |
419 | .fi | |
420 | \fIPARENTHESES MOVING COMMAND SUMMARY\fP | |
421 | ||
422 | \fI(bi n m) \fP. both in. inserts parentheses before | |
423 | the nth element and after the mth element in the current expression. | |
424 | example: if the current expression is (a b (c d e) f g), then (bi 2 4) | |
425 | will modify it to be (a (b (c d e) f) g). (bi n) : same as (bi n n). | |
426 | example: if the current expression is (a b (c d e) f g), then (bi -2) | |
427 | will modify it to be (a b (c d e) (f) g). | |
428 | ||
429 | \fI(bo n) \fP. both out. removes both parentheses | |
430 | from the nth element. example: if the current expression is (a b (c d | |
431 | e) f g), then (bo d) will modify it to be (a b c d e f g). | |
432 | ||
433 | \fI(li n) \fP. left in. inserts a left parenthesis | |
434 | before the nth element (and a matching right parenthesis at the end of | |
435 | the current expression). example: if the current expression is (a b | |
436 | (c d e) f g), then (li 2) will modify it to be (a (b (c d e) f g)). | |
437 | ||
438 | \fI(lo n) \fP. left out. removes a left | |
439 | parenthesis from the nth element. all elements following the nth | |
440 | element are deleted. example: if the current expression is (a b (c d | |
441 | e) f g), then (lo 3) will modify it to be (a b c d e). | |
442 | ||
443 | \fI(ri n m) \fP. right in. move the right | |
444 | parenthesis at the end of the nth element in to after the mth element. | |
445 | inserts a right parenthesis after the mth element of the nth | |
446 | element. The rest of the nth element is brought up to the level of | |
447 | the current expression. example: if the current expression is (a (b | |
448 | c d e) f g), (ri 2 2) will modify it to be (a (b c) d e f g). | |
449 | ||
450 | \fI(ro n) \fP. right out. move the right parenthesis | |
451 | at the end of the nth element out to the end of the current | |
452 | expression. removes the right parenthesis from the nth element, moving | |
453 | it to the end of the current expression. all elements following the | |
454 | nth element are moved inside of the nth element. example: if the | |
455 | current expression is (a b (c d e) f g), (ro 3) will modify it to | |
456 | be (a b (c d e f g)). | |
457 | ||
458 | \fI(r x y) \fP replaces all instances of x by y in | |
459 | the current expression, e.g., (r caadr cadar). x can be the | |
460 | s-expression (or atom) to be substituted for, or can be a pattern which | |
461 | specifies that s-expression (or atom). | |
462 | ||
463 | \fI(sw n m) \fP switches the nth and mth elements of | |
464 | the current expression. for example, if the current expression is | |
465 | (list (cons (car x) (car y)) (cons (cdr y))), (sw 2 3) will modify | |
466 | it to be (list (cons (cdr x) (cdr y)) (cons (car x) (car y))). (sw | |
467 | car cdr) would produce the same result. | |
468 | .Fe | |
469 | .sh 3 Using\ to\ and\ thru | |
470 | ||
471 | to, thru, extract, embed, delete, replace, and move can be made to | |
472 | operate on several contiguous elements, i.e., a segment of a list, by | |
473 | using the to or thru command in their respective location | |
474 | specifications. thru and to are intended to be used in conjunction | |
475 | with extract, embed, delete, replace, and move. to and thru can also | |
476 | be used directly with xtr (which takes after a location specification), | |
477 | as in (xtr (2 thru 4)) (from the current expression). | |
478 | .Fb | |
479 | .fi | |
480 | \fITO AND THRU COMMAND SUMMARY\fP | |
481 | ||
482 | \fI($1 to $2) \fP. same as thru except last element | |
483 | not included. | |
484 | ||
485 | \fI($1 to)\fP. same as ($1 thru -1) | |
486 | ||
487 | \fI($1 thru $2) \fP. If the current expression is (a | |
488 | (b (c d) (e) (f g h) i) j k), following (c thru g), the current | |
489 | expression will be ((c d) (e) (f g h)). If both $1 and $2 are numbers, | |
490 | and $2 is greater than $1, then $2 counts from the beginning of the | |
491 | current expression, the same as $1. in other words, if the current | |
492 | expression is (a b c d e f g), (3 thru 4) means (c thru d), not (c thru | |
493 | f). in this case, the corresponding bi command is (bi 1 $2-$1+1). | |
494 | ||
495 | \fI($1 thru)\fP. same as \fI($1 thru -1)\fP. | |
496 | .Fe | |
497 | .sh 2 Undoing\ Commands | |
498 | each command that causes structure modification automatically adds an | |
499 | entry to the front of undolst containing the information required to | |
500 | restore all pointers that were changed by the command. The undo | |
501 | command undoes the last, i.e., most recent such command. | |
502 | .Fb | |
503 | .fi | |
504 | \fIUNDO COMMAND SUMMARY\fP | |
505 | ||
506 | \fIundo \fP. the undo command undoes most recent, structure | |
507 | modification command that has not yet been undone, and prints the name | |
508 | of that command, e.g., mbd undone. The edit chain is then exactly what | |
509 | it was before the 'undone' command had been performed. | |
510 | ||
511 | \fI!undo \fP. undoes all modifications performed during this editing | |
512 | session, i.e., this call to the editor. | |
513 | ||
514 | \fIunblock \fP. removes an undo-block. If executed at a non-blocked | |
515 | state, i.e., if undo or !undo could operate, types not blocked. | |
516 | ||
517 | \fItest \fP. adds an undo-block at the front of undolst. note that | |
518 | test together with !undo provide a 'tentative' mode for editing, | |
519 | i.e., the user can perform a number of changes, and then undo all of | |
520 | them with a single !undo command. | |
521 | ||
522 | \fIundolst [value]\fP. each editor command that causes structure | |
523 | modification automatically adds an entry to the front of undolst | |
524 | containing the information required to restore all pointers that were | |
525 | changed by the command. | |
526 | ||
527 | \fI?? \fP prints the entries on undolst. The entries are listed most | |
528 | recent entry first. | |
529 | .Fe | |
530 | .sh 2 \Commands\ that\ Evaluate | |
531 | .Fb | |
532 | .fi | |
533 | \fIEVALUATION COMMAND SUMMARY\fP | |
534 | ||
535 | \fIe \fP. only when typed in, (i.e., (insert d before e) will treat | |
536 | e as a pattern) causes the editor to call the lisp interpreter | |
537 | giving it the next input as argument. | |
538 | ||
539 | \fI(e x)\fP evaluates x, and prints the result. (e x t) same as (e | |
540 | x) but does not print. | |
541 | ||
542 | \fI(i c x1 ... xn) \fP same as (c y1 ... yn) where yi=(eval xi). | |
543 | example: (i 3 (cdr foo)) will replace the 3rd element of the current | |
544 | expression with the cdr of the value of foo. (i n foo (car fie)) will | |
545 | attach the value of foo and car of the value of fie to the end of the | |
546 | current expression. (i f= foo t) will search for an expression eq to | |
547 | the value of foo. If c is not an atom, it is evaluated as well. | |
548 | ||
549 | \fI(coms x1 ... xn) \fP. each xi is evaluated and its value executed | |
550 | as a command. The i command is not very convenient for computing an | |
551 | entire edit command for execution, since it computes the command name | |
552 | and its arguments separately. also, the i command cannot be used to | |
553 | compute an atomic command. The coms and comsq commands provide | |
554 | more general ways of computing commands. (coms (cond (x (list 1 x)))) | |
555 | will replace the first element of the current expression with the value | |
556 | of x if non-nil, otherwise do nothing. (nil as a command is a nop.) | |
557 | ||
558 | \fI(comsq com1 ... comn) \fP. executes com1 ... comn. comsq is mainly | |
559 | useful in conjunction with the coms command. for example, suppose | |
560 | the user wishes to compute an entire list of commands for evaluation, | |
561 | as opposed to computing each command one at a time as does the coms | |
562 | command. he would then write (coms (cons (quote comsq) x)) where x | |
563 | computed the list of commands, e.g., (coms (cons (quote comsq) | |
564 | (get foo (quote commands)))) | |
565 | .Fe | |
566 | .sh 2 Commands\ that\ Test | |
567 | .Fb | |
568 | .fi | |
569 | \fITESTING COMMAND SUMMARY\fP | |
570 | ||
571 | \fI(if x) \fP generates an error unless the value of (eval x) is | |
572 | non-nil, i.e., if (eval x) causes an error or (eval x)=nil, if will | |
573 | cause an error. (if x coms1 coms2) if (eval x) is non-nil, execute | |
574 | coms1; if (eval x) causes an error or is equal to nil, execute coms2. | |
575 | (if x coms1) if (eval x) is non-nil, execute coms1; otherwise | |
576 | generate an error. | |
577 | ||
578 | \fI(lp . coms) \fP. repeatedly executes coms, a list of commands, | |
579 | until an error occurs. (lp f print (n t)) will attach a | |
580 | t at the end of every print expression. (lp f print (if (## 3) nil ((n | |
581 | t)))) will attach a t at the end of each print expression which does | |
582 | not already have a second argument. (i.e. the form (## 3) will cause | |
583 | an error if the edit command 3 causes an error, thereby selecting ((n | |
584 | t)) as the list of commands to be executed. The if could also be | |
585 | written as (if (cddr (##)) nil ((n t))).). | |
586 | ||
587 | \fI(lpq . coms) \fP same as lp but does not print n occurrences. | |
588 | ||
589 | \fI(orr coms1 ... comsn) \fP. orr begins by executing coms1, a list of | |
590 | commands. If no error occurs, orr is finished. otherwise, orr | |
591 | restores the edit chain to its original value, and continues by | |
592 | executing coms2, etc. If none of the command lists execute without | |
593 | errors, i.e., the orr "drops off the end", orr generates an error. | |
594 | otherwise, the edit chain is left as of the completion of the first | |
595 | command list which executes without error. | |
596 | .Fe | |
597 | .sh 2 Editor\ Macros | |
598 | ||
599 | Many of the more sophisticated branching commands in the editor, such | |
600 | as orr, if, etc., are most often used in conjunction with edit | |
601 | macros. The macro feature permits the user to define new commands and | |
602 | thereby expand the editor's repertoire. (however, built in commands | |
603 | always take precedence over macros, i.e., the editor's | |
604 | repertoire can be expanded, but not modified.) macros are defined by | |
605 | using the m command. | |
606 | ||
607 | \fI(m c . coms) \fP for c an atom, m defines c as an | |
608 | atomic command. (if a macro is redefined, its new definition | |
609 | replaces its old.) executing c is then the same as executing the list | |
610 | of commands coms. macros can also define list commands, i.e., | |
611 | commands that take arguments. (m (c) (arg[1] ... arg[n]) . coms) c an | |
612 | atom. m defines c as a list command. executing (c e1 ... en) is | |
613 | then performed by substituting e1 for arg[1], ... en for | |
614 | arg[n] throughout coms, and then executing coms. a list command can be | |
615 | defined via a macro so as to take a fixed or indefinite number | |
616 | of 'arguments'. The form given above specified a macro with a fixed | |
617 | number of arguments, as indicated by its argument list. if the | |
618 | 'argument list' is atomic, the command takes an indefinite number | |
619 | of arguments. (m (c) args . coms) c, args both atoms, defines c | |
620 | as a list command. executing (c e1 ... en) is performed by | |
621 | substituting (e1 ... en), i.e., cdr of the command, for args | |
622 | throughout coms, and then executing coms. | |
623 | ||
624 | (m bp bk up p) will define bp as an atomic command which does three | |
625 | things, a bk, an up, and a p. note that macros can use commands | |
626 | defined by macros as well as built in commands in their | |
627 | definitions. for example, suppose z is defined by (m z -1 (if | |
628 | (null (##)) nil (p))), i.e. z does a -1, and then if the current | |
629 | expression is not nil, a p. now we can define zz by (m zz -1 z), and | |
630 | zzz by (m zzz -1 -1 z) or (m zzz -1 zz). we could define a more | |
631 | general bp by (m (bp) (n) (bk n) up p). (bp 3) would perform (bk | |
632 | 3), followed by an up, followed by a p. The command second can be | |
633 | defined as a macro by (m (2nd) x (orr ((lc . x) (lc . x)))). | |
634 | ||
635 | Note that for all editor commands, 'built in' commands as well as | |
636 | commands defined by macros, atomic definitions and list | |
637 | definitions are completely independent. in other words, the | |
638 | existence of an atomic definition for c in no way affects the | |
639 | treatment of c when it appears as car of a list command, and the | |
640 | existence of a list definition for c in no way affects the treatment | |
641 | of c when it appears as an atom. in particular, c can be used as the | |
642 | name of either an atomic command, or a list command, or both. in the | |
643 | latter case, two entirely different definitions can be used. note | |
644 | also that once c is defined as an atomic command via a macro | |
645 | definition, it will not be searched for when used in a location | |
646 | specification, unless c is preceded by an f. (insert -- before | |
647 | bp) would not search for bp, but instead perform a bk, an up, and a p, | |
648 | and then do the insertion. The corresponding also holds true for list | |
649 | commands. | |
650 | ||
651 | \fI(bind . coms) \fP bind is an edit command which | |
652 | is useful mainly in macros. it binds three dummy variables #1, #2, #3, | |
653 | (initialized to nil), and then executes the edit commands coms. | |
654 | note that these bindings are only in effect while the commands are | |
655 | being executed, and that bind can be used recursively; it will rebind | |
656 | #1, #2, and #3 each time it is invoked. | |
657 | ||
658 | \fIusermacros [value]\fP. this variable contains the users editing | |
659 | macros . if you want to save your macros then you should save | |
660 | usermacros. you should probably also save editcomsl. | |
661 | ||
662 | \fIeditcomsl [value]\fP. | |
663 | editcomsl is the list of "list commands" recognized by the editor. (these | |
664 | are the ones of the form (command arg1 arg2 ...).) | |
665 | ||
666 | .sh 2 Miscellaneous\ Editor\ Commands | |
667 | .Fb | |
668 | .fi | |
669 | \fIMISCELLANEOUS EDITOR COMMAND SUMMARY\fP | |
670 | ||
671 | \fIok \fP. Exits from the editor. | |
672 | ||
673 | \fInil \fP. Unless preceded by f or bf, is always a null operation. | |
674 | ||
675 | \fItty: \fP. Calls the editor recursively. The user can then type | |
676 | in commands, and have them executed. The tty: command is completed | |
677 | when the user exits from the lower editor (with ok or stop). | |
678 | the tty: command is extremely useful. it enables the user to set up | |
679 | a complex operation, and perform interactive attention-changing | |
680 | commands part way through it. for example the command (move 3 to after | |
681 | cond 3 p tty:) allows the user to interact, in effect, within the | |
682 | move command. he can verify for himself that the correct location | |
683 | has been found, or complete the specification "by hand". in effect, | |
684 | tty: says "I'll tell you what you should do when you get there." | |
685 | ||
686 | \fIstop \fP. exits from the editor with an error. mainly for use in | |
687 | conjunction with tty: commands that the user wants to abort. since | |
688 | all of the commands in the editor are errset protected, the user must | |
689 | exit from the editor via a command. stop provides a way of | |
690 | distinguishing between a successful and unsuccessful (from the | |
691 | user's standpoint) editing session. | |
692 | ||
693 | \fItl \fP. tl calls (top-level). to return to the editor just use | |
694 | the \fIreturn\fP top-level command. | |
695 | ||
696 | \fIrepack \fP. permits the 'editing' of an atom or string. | |
697 | ||
698 | \fI(repack $)\fP does (lc . $) followed by repack, e.g. (repack this@). | |
699 | ||
700 | \fI(makefn form args n m) \fP. makes (car form) an expr with the nth | |
701 | through mth elements of the current expression with each | |
702 | occurrence of an element of (cdr form) replaced by the corresponding | |
703 | element of args. The nth through mth elements are replaced by form. | |
704 | ||
705 | \fI(makefn form args n)\fP. same as (makefn form args n n). | |
706 | ||
707 | \fI(s var . $) \fP. sets var (using setq) to the current expression | |
708 | after performing (lc . $). (s foo) will set foo to the current | |
709 | expression, (s foo -1 1) will set foo to the first element in the last | |
710 | element of the current expression. | |
711 | .Fe | |
712 | .sh 2 Editor\ Functions | |
713 | ||
714 | .Lf editf "s_x1 ..." | |
715 | .Se | |
716 | edits a function. s_x1 is the name of the function, | |
717 | any additional arguments are an optional list of commands. | |
718 | .Re | |
719 | s_x1. | |
720 | .No | |
721 | if s_x1 is not an editable function, editf generates an fn not editable error. | |
722 | ||
723 | .Lf edite "l_expr l_coms s_atm)" | |
724 | edits an expression. its value is the last element of (editl (list | |
725 | l_expr) l_coms s_atm nil nil). | |
726 | ||
727 | .Lf editracefn "s_com" | |
728 | is available to help the user debug complex edit macros, or subroutine | |
729 | calls to the editor. editracefn is to be defined by the user. | |
730 | whenever the value of editracefn is non-nil, the editor calls | |
731 | the function editracefn before executing each command (at any | |
732 | level), giving it that command as its argument. editracefn is | |
733 | initially equal to nil, and undefined. | |
734 | ||
735 | .Lf editv "s_var [ g_com1 ... ]" | |
736 | .Se | |
737 | similar to editf, for editing values. editv sets the variable to the value | |
738 | returned. | |
739 | .Re | |
740 | the name of the variable whose value was edited. | |
741 | ||
742 | .Lf editp "s_x" | |
743 | .Se | |
744 | similar to editf for editing property lists. | |
745 | used if x is nil. | |
746 | .Re | |
747 | the atom whose property list was edited. | |
748 | ||
749 | .Lf editl "coms atm marklst mess" | |
750 | .Se | |
751 | editl is the editor. its first argument is the edit chain, and its | |
752 | value is an edit chain, namely the value of l at the time editl is | |
753 | exited. (l is a special variable, and so can be examined or set by | |
754 | edit commands. ^ is equivalent to (e (setq l(last l)) t).) coms is | |
755 | an optional list of commands. for interactive editing, coms is nil. | |
756 | in this case, editl types edit and then waits for input from the | |
757 | teletype. (if mess is not nil editl types it instead of edit. for | |
758 | example, the tty: command is essentially (setq l (editl l nil nil nil | |
759 | (quote tty:))).) exit occurs only via an ok, stop, or save command. | |
760 | If coms is not nil, no message is typed, and each member of coms is | |
761 | treated as a command and executed. If an error occurs in the execution | |
762 | of one of the commands, no error message is printed , the rest of the | |
763 | commands are ignored, and editl exits with an error, i.e., the effect | |
764 | is the same as though a stop command had been executed. If all | |
765 | commands execute successfully, editl returns the current value of l. | |
766 | marklst is the list of marks. on calls from editf, atm is the name of | |
767 | the function being edited; on calls from editv, the name of the | |
768 | variable, and calls from editp, the atom of which some property of its | |
769 | property list is being edited. The property list of atm is used by the | |
770 | save command for saving the state of the edit. save will not save | |
771 | anything if atm=nil i.e., when editing arbitrary expressions via edite | |
772 | or editl directly. | |
773 | ||
774 | .Lf editfns "s_x [ g_coms1 ... ]" | |
775 | fsubr function, used to perform the same editing operations on | |
776 | several functions. | |
777 | editfns maps down the list of | |
778 | functions, prints the name of each function, and calls the editor (via | |
779 | editf) on that function. | |
780 | .Ex | |
781 | editfns foofns (r fie fum)) will change every fie to fum in | |
782 | each of the functions on foofns. | |
783 | .No | |
784 | the call to the editor is errset protected, so that if the editing of one | |
785 | function causes an error, editfns will proceed to the next function. in | |
786 | the above example, if one of the functions did not contain a fie, the r command | |
787 | would cause an error, but editing would continue with the next function. The | |
788 | value of editfns is nil. | |
789 | ||
790 | .Lf edit4e "pat y" | |
791 | .Se | |
792 | is the pattern match routine. | |
793 | .Re | |
794 | t if pat matches y. see edit-match for definition of 'match'. | |
795 | .No | |
796 | before each search operation in the editor begins, the entire pattern | |
797 | is scanned for atoms or strings that end in at-signs. These are replaced by | |
798 | patterns of the form (cons (quote /@) (explodec atom)). from the | |
799 | standpoint of edit4e, pattern type 5, atoms or strings ending in at-signs, is | |
800 | really "if car[pat] is the atom @ (at-sign), pat will match with any literal | |
801 | atom or string whose initial character codes (up to the @) are the same as | |
802 | those in cdr[pat]." | |
803 | if the user wishes to call edit4e directly, he must therefore convert any | |
804 | patterns which contain atoms or strings ending in at-signs to the form | |
805 | recognized by edit4e. this can be done via the function editfpat. | |
806 | .Lf editfpat "pat flg" | |
807 | makes a copy of pat with all patterns of type 5 (see edit-match) converted to | |
808 | the form expected by edit4e. flg should be passed as nil (flg=t is for internal | |
809 | use by the editor). | |
810 | ||
811 | .Lf editfindp "x pat flg" | |
812 | .No | |
813 | Allows a program to use the edit find command as a pure predicate | |
814 | from outside the editor. x is an expression, pat a pattern. The value | |
815 | of editfindp is t if the command f pat would succeed, nil otherwise. | |
816 | editfindp calls editfpat to convert pat to the form expected by edit4e, | |
817 | unless flg=t. if the program is applying editfindp to several | |
818 | different expressions using the same pattern, it will be more efficient | |
819 | to call editfpat once, and then call editfindp with the converted | |
820 | pattern and flg=t. | |
821 | ||
822 | .Lf ## "g_com1 ..." | |
823 | .Re | |
824 | what the current expression would be after executing the edit commands | |
825 | com1 ... starting from the present edit chain. generates an error | |
826 | if any of comi cause errors. The current edit chain is never | |
827 | changed. example: (i r (quote x) (## (cons ..z))) replaces all x's in | |
828 | the current expression by the first cons containing a z. |