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