Changes between Initial Version and Version 1 of HemlockUser/EditingLisp


Ignore:
Timestamp:
Nov 5, 2007, 5:36:28 PM (12 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