Changes between Initial Version and Version 1 of HemlockUser/EditingLisp


Ignore:
Timestamp:
11/05/07 17:36:28 (7 years ago)
Author:
rme
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • HemlockUser/EditingLisp

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