Changes between Initial Version and Version 1 of HemlockUser/EditingLisp

Timestamp:

Nov 5, 2007, 5:36:28 PM (12 years ago)

Author:

rme

Comment:

--

HemlockUser/EditingLisp

@@ +1 @@
+[[PageOutline]]
+
+= 8 Editing Lisp =
+
+Hemlock provides a large number of powerful commands for editing Lisp
+code. It is possible for a text editor to provide a much higher level
+of support for editing Lisp than ordinary programming languages, since
+its syntax is much simpler.
+
+== 8.1 Lisp Mode ==
+
+Lisp mode is a major mode used for editing Lisp code. Although most
+Lisp specific commands are globally bound, Lisp mode is necessary to
+enable Lisp indentation, commenting, and
+parenthesis-matching. Whenever the user or some Hemlock mechanism
+turns on Lisp mode, the mode's setup includes locally setting Current
+Package (see section 9.3) in that buffer if its value is non-existent
+there; the value used is "USER".
+
+Lisp Mode                [Command]
+
+This command sets the major mode of the current buffer to Lisp.
+
+
+== 8.2 Form Manipulation ==
+
+These commands manipulate Lisp forms, the printed representations of
+Lisp objects. A form is either an expression balanced with respect to
+parentheses or an atom such as a symbol or string.
+
+Forward Form    (bound to C-M-f)         [Command]
+
+Backward Form   (bound to C-M-b)         [Command]
+
+Forward Form moves to the end of the current or next form, while
+Backward Form moves to the beginning of the current or previous
+form. A prefix argument is treated as a repeat count.
+
+
+
+Forward Kill Form       (bound to C-M-k)         [Command]
+
+Backward Kill Form      (bound to C-M-Delete, C-M-Backspace)     [Command]
+
+Forward Kill Form kills text from the point to the end of the current
+form. If at the end of a list, but inside the close parenthesis, then
+kill the close parenthesis. Backward Kill Form is the same, except it
+goes in the other direction. A prefix argument is treated as a repeat
+count.
+
+
+
+Mark Form       (bound to C-M-@)         [Command]
+
+This command sets the mark at the end of the current or next form.
+
+
+Transpose Forms         (bound to C-M-t)         [Command]
+
+This command transposes the forms before and after the point and moves
+forward. A prefix argument is treated as a repeat count. If the prefix
+argument is negative, then the point is moved backward after the
+transposition is done, reversing the effect of the equivalent positive
+argument.
+
+
+
+Insert ()       (bound to M-()   [Command]
+
+This command inserts an open and a close parenthesis, leaving the
+point inside the open parenthesis. If a prefix argument is supplied,
+then the close parenthesis is put at the end of the form that many
+forms from the point.
+
+
+
+Extract Form             [Command]
+
+This command replaces the current containing list with the next
+form. The entire affected area is pushed onto the kill ring. If an
+argument is supplied, that many upward levels of list nesting is
+replaced by the next form. This is similar to Extract List, but this
+command is more generally useful since it works on any kind of form;
+it is also more intuitive since it operates on the next form as many
+Lisp mode commands do.
+
+== 8.3 List Manipulation ==
+
+List commands are similar to form commands, but they only pay
+attention to lists, ignoring any atomic objects that may appear. These
+commands are useful because they can skip over many symbols and move
+up and down in the list structure.
+
+Forward List    (bound to C-M-n)         [Command]
+
+Backward List   (bound to C-M-p)         [Command]
+
+Forward List moves the point to immediately after the end of the next
+list at the current level of list structure. If there is not another
+list at the current level, then it moves up past the end of the
+containing list. Backward List is identical, except that it moves
+backward and leaves the point at the beginning of the list. The prefix
+argument is used as a repeat count.
+
+
+Forward Up List         (bound to C-M-))         [Command]
+
+Backward Up List        (bound to C-M-(, C-M-u)  [Command]
+
+Forward Up List moves to after the end of the enclosing list. Backward
+Up List moves to the beginning. The prefix argument is used as a
+repeat count.
+
+
+
+Down List       (bound to C-M-d)         [Command]
+
+This command moves to just after the beginning of the next list. The
+prefix argument is used as a repeat count.
+
+
+
+Extract List    (bound to C-M-x)         [Command]
+
+This command "extracts" the current list from the list which contains
+it. The outer list is deleted, leaving behind the current list. The
+entire affected area is pushed on the kill ring, so that this possibly
+catastrophic operation can be undone. The prefix argument is used as a
+repeat count.
+
+== 8.4 Defun Manipulation ==
+
+A defun is a list whose open parenthesis is against the left
+margin. It is called this because an occurrence of the defun top level
+form usually satisfies this definition, but other top level forms such
+as a defstruct and defmacro work just as well.
+
+End of Defun    (bound to C-M-e, C-M-])  [Command]
+
+Beginning of Defun      (bound to C-M-a, C-M-[)  [Command]
+
+End of Defun moves to the end of the current or next defun. Beginning
+of Defun moves to the beginning of the current or previous defun. End
+of Defun will not work if the parentheses are not balanced.
+
+
+Mark Defun      (bound to C-M-h)         [Command]
+
+This command puts the point at the beginning and the mark at the end
+of the current or next defun.
+
+== 8.5 Indentation ==
+
+One of the most important features provided by Lisp mode is automatic
+indentation of Lisp code. Since unindented Lisp is unreadable, poorly
+indented Lisp is hard to manage, and inconsistently indented Lisp is
+subtly misleading. See section 7.2 for a description of the
+general-purpose indentation commands. Lisp mode uses these indentation
+rules:
+
+ * If in a semicolon (;) comment, then use the standard comment
+   indentation rules. See page 7.1.
+
+ * If in a quoted string, then indent to the column one greater than
+   the column containing the opening double quote. This is exactly
+   what you want in function documentation strings and wrapping error
+   strings.
+
+ * If there is no enclosing list, then use no indentation.
+
+ * If enclosing list resembles a call to a known macro or
+   special-form, then the first few arguments are given greater
+   indentation and the first body form is indented two spaces. If the
+   first special argument is on the same line as the beginning of the
+   form, then following special arguments will be indented to the
+   start of the first special argument, otherwise all special
+   arguments are indented four spaces.
+
+ * If the previous form starts on its own line, then the indentation
+   is copied from that form. This rule allows the default indentation
+   to be overridden: once a form has been manually indented to the
+   user's satisfaction, subsequent forms will be indented in the same
+   way.
+
+ * If the enclosing list has some arguments on the same line as the
+   form start, then subsequent arguments will be indented to the start
+   of the first argument.
+
+ * If the enclosing list has no argument on the same line as the form
+   start, then arguments will be indented one space.
+
+Indent Form     (bound to C-M-q)         [Command]
+
+This command indents all the lines in the current form, leaving the
+point unmoved. This is undo-able.
+
+
+
+Fill Lisp Comment Paragraph              [Command]
+
+Fill Lisp Comment Paragraph Confirm     (initial value t)        [Variable]
+
+This fills a flushleft or indented Lisp comment. This also fills Lisp
+string literals using the proper indentation as a filling prefix. When
+invoked outside of a comment or string, this tries to fill all
+contiguous lines beginning with the same initial, non-empty
+blankspace. When filling a comment, the current line is used to
+determine a fill prefix by taking all the initial whitespace on the
+line, the semicolons, and any whitespace following the
+semicolons.
+
+When invoked outside of a comment or string, this command prompts for
+confirmation before filling. It is useful to use this for filling long
+export lists or other indented text or symbols, but since this is a
+less common use, this command tries to make sure that is what you
+wanted. Setting Fill Lisp Comment Paragraph Confirm to nil inhibits
+the confirmation prompt.
+
+
+
+Defindent       (bound to C-M-#)         [Command]
+
+This command prompts for the number of special arguments to associate
+with the symbol at the beginning of the current or containing
+list.
+
+
+
+Indent Defanything      (initial value 2)        [Variable]
+
+This is the number of special arguments implicitly assumed to be
+supplied in calls to functions whose names begin with "def". If set to
+nil, this feature is disabled.
+
+
+Move Over )     (bound to M-))   [Command]
+
+This command moves past the next close parenthesis and then does the
+equivalent of Indent New Line.
+
+== 8.6 Parenthesis Matching ==
+
+Another very important facility provided by Lisp mode is parenthesis
+matching. Two different styles of parenthesis matching are supported:
+highlighting and pausing.
+
+Highlight Open Parens   (initial value t)        [Variable]
+
+Open Paren Highlighting Font    (initial value nil)      [Variable]
+
+When Highlight Open Parens is true, and a close paren is immediately
+before the point, then Hemlock displays the matching open paren in
+Open Paren Highlighting Font.
+
+Open Paren Highlighting Font is the string name of the font used for
+paren highlighting. Only the "(" character is used in this font. If
+null, then a reasonable default is chosen. The highlighting font is
+read at initialization time, so this variable must be set before the
+editor is first entered to have any effect.
+
+
+
+Lisp Insert )            [Command]
+
+Paren Pause Period      (initial value 0.5)      [Variable]
+
+This command inserts a close parenthesis and then attempts to display
+the matching open parenthesis by placing the cursor on top of it for
+Paren Pause Period seconds. If there is no matching parenthesis then
+beep. If the matching parenthesis is off the top of the screen, then
+the line on which it appears is displayed in the echo area. Paren
+pausing may be disabled by setting Paren Pause Period to
+nil.
+
+
+The initial values shown for Highlight Open Parens and Paren Pause
+Period are only approximately correct. Since paren highlighting is
+only meaningful in Lisp mode, Highlight Open Parens is false globally,
+and has a mode-local value of t in Lisp mode. It it redundant to do
+both kinds of paren matching, so there is also a binding of Paren
+Pause Period to nil in Lisp mode.
+
+Paren highlighting is only supported under X windows, so the above
+defaults are conditional on the device type. If Hemlock is started on
+a terminal, the initialization code makes Lisp mode bindings of nil
+and 0.5 for Highlight Open Parens and Paren Pause Period. Since these
+alternate default bindings are made at initialization time, the only
+way to affect them is to use the after-editor-initializations
+macro.
+
+== 8.7 Parsing Lisp ==
+
+Lisp mode has a fairly complete knowledge of Lisp syntax, but since it
+does not use the reader, and must work incrementally, it can be
+confused by legal constructs. Lisp mode totally ignores the
+read-table, so user-defined read macros have no effect on the
+editor. In some cases, the values the Lisp Syntax character attribute
+can be changed to get a similar effect.
+
+Lisp commands consistently treat semicolon (;) style comments as
+whitespace when parsing, so a Lisp command used in a comment will
+affect the next (or previous) form outside of the comment. Since #|
+... |# comments are not recognized, they can used to comment out code,
+while still allowing Lisp editing commands to be used.
+
+Strings are parsed similarly to symbols. When within a string, the
+next form is after the end of the string, and the previous form is the
+beginning of the string.
+
+Defun Parse Goal        (initial value 2)        [Variable]
+
+Maximum Lines Parsed    (initial value 500)      [Variable]
+
+Minimum Lines Parsed    (initial value 50)       [Variable]
+
+In order to save time, Lisp mode does not parse the entire buffer
+every time a Lisp command is used. Instead, it uses a heuristic to
+guess the region of the buffer that is likely to be interesting. These
+variables control the heuristic.
+
+Normally, parsing begins and ends on defun boundaries (an open
+parenthesis at the beginning of a line). Defun Parse Goal specifies
+the number of defuns before and after the point to parse. If this
+parses fewer lines than Minimum Lines Parsed, then parsing continues
+until this lower limit is reached. If we cannot find enough defuns
+within Maximum Lines Parsed lines then we stop on the farthest defun
+found, or at the point where we stopped if no defuns were
+found.
+
+When the heuristic fails, and does not parse enough of the buffer,
+then commands usually act as though a syntax error was detected. If
+the parse starts in a bad place (such as in the middle of a string),
+then Lisp commands will be totally confused. Such problems can usually
+be eliminated by increasing the values of some of these
+variables.
+
+
+Parse Start Function    (initial value start-of-parse-block)     [Variable]
+
+Parse End Function      (initial value end-of-parse-block)       [Variable]
+
+These variables determine the region of the buffer parsed. The values
+are functions that take a mark and move it to the start or end of the
+parse region. The default values implement the heuristic described
+above.
+