| 1 | [[PageOutline]] |
| 2 | |
| 3 | = 8 Editing Lisp = |
| 4 | |
| 5 | Hemlock provides a large number of powerful commands for editing Lisp |
| 6 | code. It is possible for a text editor to provide a much higher level |
| 7 | of support for editing Lisp than ordinary programming languages, since |
| 8 | its syntax is much simpler. |
| 9 | |
| 10 | == 8.1 Lisp Mode == |
| 11 | |
| 12 | Lisp mode is a major mode used for editing Lisp code. Although most |
| 13 | Lisp specific commands are globally bound, Lisp mode is necessary to |
| 14 | enable Lisp indentation, commenting, and |
| 15 | parenthesis-matching. Whenever the user or some Hemlock mechanism |
| 16 | turns on Lisp mode, the mode's setup includes locally setting Current |
| 17 | Package (see section 9.3) in that buffer if its value is non-existent |
| 18 | there; the value used is "USER". |
| 19 | |
| 20 | Lisp Mode [Command] |
| 21 | |
| 22 | This command sets the major mode of the current buffer to Lisp. |
| 23 | |
| 24 | |
| 25 | == 8.2 Form Manipulation == |
| 26 | |
| 27 | These commands manipulate Lisp forms, the printed representations of |
| 28 | Lisp objects. A form is either an expression balanced with respect to |
| 29 | parentheses or an atom such as a symbol or string. |
| 30 | |
| 31 | Forward Form (bound to C-M-f) [Command] |
| 32 | |
| 33 | Backward Form (bound to C-M-b) [Command] |
| 34 | |
| 35 | Forward Form moves to the end of the current or next form, while |
| 36 | Backward Form moves to the beginning of the current or previous |
| 37 | form. A prefix argument is treated as a repeat count. |
| 38 | |
| 39 | |
| 40 | |
| 41 | Forward Kill Form (bound to C-M-k) [Command] |
| 42 | |
| 43 | Backward Kill Form (bound to C-M-Delete, C-M-Backspace) [Command] |
| 44 | |
| 45 | Forward Kill Form kills text from the point to the end of the current |
| 46 | form. If at the end of a list, but inside the close parenthesis, then |
| 47 | kill the close parenthesis. Backward Kill Form is the same, except it |
| 48 | goes in the other direction. A prefix argument is treated as a repeat |
| 49 | count. |
| 50 | |
| 51 | |
| 52 | |
| 53 | Mark Form (bound to C-M-@) [Command] |
| 54 | |
| 55 | This command sets the mark at the end of the current or next form. |
| 56 | |
| 57 | |
| 58 | Transpose Forms (bound to C-M-t) [Command] |
| 59 | |
| 60 | This command transposes the forms before and after the point and moves |
| 61 | forward. A prefix argument is treated as a repeat count. If the prefix |
| 62 | argument is negative, then the point is moved backward after the |
| 63 | transposition is done, reversing the effect of the equivalent positive |
| 64 | argument. |
| 65 | |
| 66 | |
| 67 | |
| 68 | Insert () (bound to M-() [Command] |
| 69 | |
| 70 | This command inserts an open and a close parenthesis, leaving the |
| 71 | point inside the open parenthesis. If a prefix argument is supplied, |
| 72 | then the close parenthesis is put at the end of the form that many |
| 73 | forms from the point. |
| 74 | |
| 75 | |
| 76 | |
| 77 | Extract Form [Command] |
| 78 | |
| 79 | This command replaces the current containing list with the next |
| 80 | form. The entire affected area is pushed onto the kill ring. If an |
| 81 | argument is supplied, that many upward levels of list nesting is |
| 82 | replaced by the next form. This is similar to Extract List, but this |
| 83 | command is more generally useful since it works on any kind of form; |
| 84 | it is also more intuitive since it operates on the next form as many |
| 85 | Lisp mode commands do. |
| 86 | |
| 87 | == 8.3 List Manipulation == |
| 88 | |
| 89 | List commands are similar to form commands, but they only pay |
| 90 | attention to lists, ignoring any atomic objects that may appear. These |
| 91 | commands are useful because they can skip over many symbols and move |
| 92 | up and down in the list structure. |
| 93 | |
| 94 | Forward List (bound to C-M-n) [Command] |
| 95 | |
| 96 | Backward List (bound to C-M-p) [Command] |
| 97 | |
| 98 | Forward List moves the point to immediately after the end of the next |
| 99 | list at the current level of list structure. If there is not another |
| 100 | list at the current level, then it moves up past the end of the |
| 101 | containing list. Backward List is identical, except that it moves |
| 102 | backward and leaves the point at the beginning of the list. The prefix |
| 103 | argument is used as a repeat count. |
| 104 | |
| 105 | |
| 106 | Forward Up List (bound to C-M-)) [Command] |
| 107 | |
| 108 | Backward Up List (bound to C-M-(, C-M-u) [Command] |
| 109 | |
| 110 | Forward Up List moves to after the end of the enclosing list. Backward |
| 111 | Up List moves to the beginning. The prefix argument is used as a |
| 112 | repeat count. |
| 113 | |
| 114 | |
| 115 | |
| 116 | Down List (bound to C-M-d) [Command] |
| 117 | |
| 118 | This command moves to just after the beginning of the next list. The |
| 119 | prefix argument is used as a repeat count. |
| 120 | |
| 121 | |
| 122 | |
| 123 | Extract List (bound to C-M-x) [Command] |
| 124 | |
| 125 | This command "extracts" the current list from the list which contains |
| 126 | it. The outer list is deleted, leaving behind the current list. The |
| 127 | entire affected area is pushed on the kill ring, so that this possibly |
| 128 | catastrophic operation can be undone. The prefix argument is used as a |
| 129 | repeat count. |
| 130 | |
| 131 | == 8.4 Defun Manipulation == |
| 132 | |
| 133 | A defun is a list whose open parenthesis is against the left |
| 134 | margin. It is called this because an occurrence of the defun top level |
| 135 | form usually satisfies this definition, but other top level forms such |
| 136 | as a defstruct and defmacro work just as well. |
| 137 | |
| 138 | End of Defun (bound to C-M-e, C-M-]) [Command] |
| 139 | |
| 140 | Beginning of Defun (bound to C-M-a, C-M-[) [Command] |
| 141 | |
| 142 | End of Defun moves to the end of the current or next defun. Beginning |
| 143 | of Defun moves to the beginning of the current or previous defun. End |
| 144 | of Defun will not work if the parentheses are not balanced. |
| 145 | |
| 146 | |
| 147 | Mark Defun (bound to C-M-h) [Command] |
| 148 | |
| 149 | This command puts the point at the beginning and the mark at the end |
| 150 | of the current or next defun. |
| 151 | |
| 152 | == 8.5 Indentation == |
| 153 | |
| 154 | One of the most important features provided by Lisp mode is automatic |
| 155 | indentation of Lisp code. Since unindented Lisp is unreadable, poorly |
| 156 | indented Lisp is hard to manage, and inconsistently indented Lisp is |
| 157 | subtly misleading. See section 7.2 for a description of the |
| 158 | general-purpose indentation commands. Lisp mode uses these indentation |
| 159 | rules: |
| 160 | |
| 161 | * If in a semicolon (;) comment, then use the standard comment |
| 162 | indentation rules. See page 7.1. |
| 163 | |
| 164 | * If in a quoted string, then indent to the column one greater than |
| 165 | the column containing the opening double quote. This is exactly |
| 166 | what you want in function documentation strings and wrapping error |
| 167 | strings. |
| 168 | |
| 169 | * If there is no enclosing list, then use no indentation. |
| 170 | |
| 171 | * If enclosing list resembles a call to a known macro or |
| 172 | special-form, then the first few arguments are given greater |
| 173 | indentation and the first body form is indented two spaces. If the |
| 174 | first special argument is on the same line as the beginning of the |
| 175 | form, then following special arguments will be indented to the |
| 176 | start of the first special argument, otherwise all special |
| 177 | arguments are indented four spaces. |
| 178 | |
| 179 | * If the previous form starts on its own line, then the indentation |
| 180 | is copied from that form. This rule allows the default indentation |
| 181 | to be overridden: once a form has been manually indented to the |
| 182 | user's satisfaction, subsequent forms will be indented in the same |
| 183 | way. |
| 184 | |
| 185 | * If the enclosing list has some arguments on the same line as the |
| 186 | form start, then subsequent arguments will be indented to the start |
| 187 | of the first argument. |
| 188 | |
| 189 | * If the enclosing list has no argument on the same line as the form |
| 190 | start, then arguments will be indented one space. |
| 191 | |
| 192 | Indent Form (bound to C-M-q) [Command] |
| 193 | |
| 194 | This command indents all the lines in the current form, leaving the |
| 195 | point unmoved. This is undo-able. |
| 196 | |
| 197 | |
| 198 | |
| 199 | Fill Lisp Comment Paragraph [Command] |
| 200 | |
| 201 | Fill Lisp Comment Paragraph Confirm (initial value t) [Variable] |
| 202 | |
| 203 | This fills a flushleft or indented Lisp comment. This also fills Lisp |
| 204 | string literals using the proper indentation as a filling prefix. When |
| 205 | invoked outside of a comment or string, this tries to fill all |
| 206 | contiguous lines beginning with the same initial, non-empty |
| 207 | blankspace. When filling a comment, the current line is used to |
| 208 | determine a fill prefix by taking all the initial whitespace on the |
| 209 | line, the semicolons, and any whitespace following the |
| 210 | semicolons. |
| 211 | |
| 212 | When invoked outside of a comment or string, this command prompts for |
| 213 | confirmation before filling. It is useful to use this for filling long |
| 214 | export lists or other indented text or symbols, but since this is a |
| 215 | less common use, this command tries to make sure that is what you |
| 216 | wanted. Setting Fill Lisp Comment Paragraph Confirm to nil inhibits |
| 217 | the confirmation prompt. |
| 218 | |
| 219 | |
| 220 | |
| 221 | Defindent (bound to C-M-#) [Command] |
| 222 | |
| 223 | This command prompts for the number of special arguments to associate |
| 224 | with the symbol at the beginning of the current or containing |
| 225 | list. |
| 226 | |
| 227 | |
| 228 | |
| 229 | Indent Defanything (initial value 2) [Variable] |
| 230 | |
| 231 | This is the number of special arguments implicitly assumed to be |
| 232 | supplied in calls to functions whose names begin with "def". If set to |
| 233 | nil, this feature is disabled. |
| 234 | |
| 235 | |
| 236 | Move Over ) (bound to M-)) [Command] |
| 237 | |
| 238 | This command moves past the next close parenthesis and then does the |
| 239 | equivalent of Indent New Line. |
| 240 | |
| 241 | == 8.6 Parenthesis Matching == |
| 242 | |
| 243 | Another very important facility provided by Lisp mode is parenthesis |
| 244 | matching. Two different styles of parenthesis matching are supported: |
| 245 | highlighting and pausing. |
| 246 | |
| 247 | Highlight Open Parens (initial value t) [Variable] |
| 248 | |
| 249 | Open Paren Highlighting Font (initial value nil) [Variable] |
| 250 | |
| 251 | When Highlight Open Parens is true, and a close paren is immediately |
| 252 | before the point, then Hemlock displays the matching open paren in |
| 253 | Open Paren Highlighting Font. |
| 254 | |
| 255 | Open Paren Highlighting Font is the string name of the font used for |
| 256 | paren highlighting. Only the "(" character is used in this font. If |
| 257 | null, then a reasonable default is chosen. The highlighting font is |
| 258 | read at initialization time, so this variable must be set before the |
| 259 | editor is first entered to have any effect. |
| 260 | |
| 261 | |
| 262 | |
| 263 | Lisp Insert ) [Command] |
| 264 | |
| 265 | Paren Pause Period (initial value 0.5) [Variable] |
| 266 | |
| 267 | This command inserts a close parenthesis and then attempts to display |
| 268 | the matching open parenthesis by placing the cursor on top of it for |
| 269 | Paren Pause Period seconds. If there is no matching parenthesis then |
| 270 | beep. If the matching parenthesis is off the top of the screen, then |
| 271 | the line on which it appears is displayed in the echo area. Paren |
| 272 | pausing may be disabled by setting Paren Pause Period to |
| 273 | nil. |
| 274 | |
| 275 | |
| 276 | The initial values shown for Highlight Open Parens and Paren Pause |
| 277 | Period are only approximately correct. Since paren highlighting is |
| 278 | only meaningful in Lisp mode, Highlight Open Parens is false globally, |
| 279 | and has a mode-local value of t in Lisp mode. It it redundant to do |
| 280 | both kinds of paren matching, so there is also a binding of Paren |
| 281 | Pause Period to nil in Lisp mode. |
| 282 | |
| 283 | Paren highlighting is only supported under X windows, so the above |
| 284 | defaults are conditional on the device type. If Hemlock is started on |
| 285 | a terminal, the initialization code makes Lisp mode bindings of nil |
| 286 | and 0.5 for Highlight Open Parens and Paren Pause Period. Since these |
| 287 | alternate default bindings are made at initialization time, the only |
| 288 | way to affect them is to use the after-editor-initializations |
| 289 | macro. |
| 290 | |
| 291 | == 8.7 Parsing Lisp == |
| 292 | |
| 293 | Lisp mode has a fairly complete knowledge of Lisp syntax, but since it |
| 294 | does not use the reader, and must work incrementally, it can be |
| 295 | confused by legal constructs. Lisp mode totally ignores the |
| 296 | read-table, so user-defined read macros have no effect on the |
| 297 | editor. In some cases, the values the Lisp Syntax character attribute |
| 298 | can be changed to get a similar effect. |
| 299 | |
| 300 | Lisp commands consistently treat semicolon (;) style comments as |
| 301 | whitespace when parsing, so a Lisp command used in a comment will |
| 302 | affect the next (or previous) form outside of the comment. Since #| |
| 303 | ... |# comments are not recognized, they can used to comment out code, |
| 304 | while still allowing Lisp editing commands to be used. |
| 305 | |
| 306 | Strings are parsed similarly to symbols. When within a string, the |
| 307 | next form is after the end of the string, and the previous form is the |
| 308 | beginning of the string. |
| 309 | |
| 310 | Defun Parse Goal (initial value 2) [Variable] |
| 311 | |
| 312 | Maximum Lines Parsed (initial value 500) [Variable] |
| 313 | |
| 314 | Minimum Lines Parsed (initial value 50) [Variable] |
| 315 | |
| 316 | In order to save time, Lisp mode does not parse the entire buffer |
| 317 | every time a Lisp command is used. Instead, it uses a heuristic to |
| 318 | guess the region of the buffer that is likely to be interesting. These |
| 319 | variables control the heuristic. |
| 320 | |
| 321 | Normally, parsing begins and ends on defun boundaries (an open |
| 322 | parenthesis at the beginning of a line). Defun Parse Goal specifies |
| 323 | the number of defuns before and after the point to parse. If this |
| 324 | parses fewer lines than Minimum Lines Parsed, then parsing continues |
| 325 | until this lower limit is reached. If we cannot find enough defuns |
| 326 | within Maximum Lines Parsed lines then we stop on the farthest defun |
| 327 | found, or at the point where we stopped if no defuns were |
| 328 | found. |
| 329 | |
| 330 | When the heuristic fails, and does not parse enough of the buffer, |
| 331 | then commands usually act as though a syntax error was detected. If |
| 332 | the parse starts in a bad place (such as in the middle of a string), |
| 333 | then Lisp commands will be totally confused. Such problems can usually |
| 334 | be eliminated by increasing the values of some of these |
| 335 | variables. |
| 336 | |
| 337 | |
| 338 | Parse Start Function (initial value start-of-parse-block) [Variable] |
| 339 | |
| 340 | Parse End Function (initial value end-of-parse-block) [Variable] |
| 341 | |
| 342 | These variables determine the region of the buffer parsed. The values |
| 343 | are functions that take a mark and move it to the start or end of the |
| 344 | parse region. The default values implement the heuristic described |
| 345 | above. |
| 346 | |