| 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. |