lisp/skeleton.el

   1 ;;; skeleton.el --- Lisp language extension for writing statement skeletons
   2
   3 ;; Copyright (C) 1993, 1994, 1995, 1996 by Free Software Foundation, Inc.
   4
   5 ;; Author: Daniel.Pfeiffer@Informatik.START.dbp.de, fax (+49 69) 7588-2389
   6 ;; Maintainer: FSF
   7 ;; Keywords: extensions, abbrev, languages, tools
   8
   9 ;; This file is part of GNU Emacs.
  10
  11 ;; GNU Emacs is free software; you can redistribute it and/or modify
  12 ;; it under the terms of the GNU General Public License as published by
  13 ;; the Free Software Foundation; either version 2, or (at your option)
  14 ;; any later version.
  15
  16 ;; GNU Emacs is distributed in the hope that it will be useful,
  17 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  18 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19 ;; GNU General Public License for more details.
  20
  21 ;; You should have received a copy of the GNU General Public License
  22 ;; along with GNU Emacs; see the file COPYING.  If not, write to the
  23 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  24 ;; Boston, MA 02111-1307, USA.
  25
  26 ;;; Commentary:
  27
  28 ;; A very concise language extension for writing structured statement
  29 ;; skeleton insertion commands for programming language modes.  This
  30 ;; originated in shell-script mode and was applied to ada-mode's
  31 ;; commands which shrunk to one third.  And these commands are now
  32 ;; user configurable.
  33
  34 ;;; Code:
  35
  36 ;; page 1:      statement skeleton language definition & interpreter
  37 ;; page 2:      paired insertion
  38 ;; page 3:      mirror-mode, an example for setting up paired insertion
  39
  40
  41 (defvar skeleton-transformation nil
  42   "*If non-nil, function applied to literal strings before they are inserted.
  43 It should take strings and characters and return them transformed, or nil
  44 which means no transformation.
  45 Typical examples might be `upcase' or `capitalize'.")
  46
  47 ; this should be a fourth argument to defvar
  48 (put 'skeleton-transformation 'variable-interactive
  49      "aTransformation function: ")
  50
  51
  52 (defvar skeleton-autowrap t
  53   "Controls wrapping behaviour of functions created with `define-skeleton'.
  54 When the region is visible (due to `transient-mark-mode' or marking a region
  55 with the mouse) and this is non-`nil' and the function was called without an
  56 explicit ARG, then the ARG defaults to -1, i.e. wrapping around the visible
  57 region.
  58
  59 We will probably delete this variable in a future Emacs version
  60 unless we get a substantial number of complaints about the auto-wrap
  61 feature.")
  62
  63 (defvar skeleton-end-hook
  64   (lambda ()
  65     (or (eolp) (newline-and-indent)))
  66   "Hook called at end of skeleton but before going to point of interest.
  67 By default this moves out anything following to next line.
  68 The variables `v1' and `v2' are still set when calling this.")
  69
  70
  71 ;;;###autoload
  72 (defvar skeleton-filter 'identity
  73   "Function for transforming a skeleton proxy's aliases' variable value.")
  74
  75 (defvar skeleton-untabify t
  76   "When non-`nil' untabifies when deleting backwards with element -ARG.")
  77
  78 (defvar skeleton-newline-indent-rigidly nil
  79   "When non-`nil', indent rigidly under current line for element `\\n'.
  80 Else use mode's `indent-line-function'.")
  81
  82 (defvar skeleton-further-elements ()
  83   "A buffer-local varlist (see `let') of mode specific skeleton elements.
  84 These variables are bound while interpreting a skeleton.  Their value may
  85 in turn be any valid skeleton element if they are themselves to be used as
  86 skeleton elements.")
  87 (make-variable-buffer-local 'skeleton-further-elements)
  88
  89
  90 (defvar skeleton-subprompt
  91   (substitute-command-keys
  92    "RET, \\<minibuffer-local-map>\\[abort-recursive-edit] or \\[help-command]")
  93   "*Replacement for %s in prompts of recursive subskeletons.")
  94
  95
  96 (defvar skeleton-abbrev-cleanup nil
  97   "Variable used to delete the character that led to abbrev expansion.")
  98
  99
 100 (defvar skeleton-debug nil
 101   "*If non-nil `define-skeleton' will override previous definition.")
 102
 103 ;; reduce the number of compiler warnings
 104 (defvar skeleton)
 105 (defvar skeleton-modified)
 106 (defvar skeleton-point)
 107 (defvar skeleton-regions)
 108
 109 ;;;###autoload
 110 (defmacro define-skeleton (command documentation &rest skeleton)
 111   "Define a user-configurable COMMAND that enters a statement skeleton.
 112 DOCUMENTATION is that of the command, while the variable of the same name,
 113 which contains the skeleton, has a documentation to that effect.
 114 INTERACTOR and ELEMENT ... are as defined under `skeleton-insert'."
 115   (if skeleton-debug
 116       (set command skeleton))
 117   `(progn
 118      (defvar ,command ',skeleton ,documentation)
 119      (defalias ',command 'skeleton-proxy)))
 120
 121
 122
 123 ;; This command isn't meant to be called, only it's aliases with meaningful
 124 ;; names are.
 125 ;;;###autoload
 126 (defun skeleton-proxy (&optional str arg)
 127   "Insert skeleton defined by variable of same name (see `skeleton-insert').
 128 Prefix ARG allows wrapping around words or regions (see `skeleton-insert').
 129 If no ARG was given, but the region is visible, ARG defaults to -1 depending
 130 on `skeleton-autowrap'.  An ARG of  M-0  will prevent this just for once.
 131 This command can also be an abbrev expansion (3rd and 4th columns in
 132 \\[edit-abbrevs]  buffer: \"\"  command-name).
 133
 134 When called as a function, optional first argument STR may also be a string
 135 which will be the value of `str' whereas the skeleton's interactor is then
 136 ignored."
 137   (interactive "*P\nP")
 138   (let ((function (nth 1 (backtrace-frame 1))))
 139     (if (eq function 'nth)              ; uncompiled Lisp function
 140         (setq function (nth 1 (backtrace-frame 5)))
 141       (if (eq function 'byte-code)      ; tracing byte-compiled function
 142           (setq function (nth 1 (backtrace-frame 2)))))
 143     (if (not (setq function (funcall skeleton-filter (symbol-value function))))
 144         (if (memq this-command '(self-insert-command
 145                                  skeleton-pair-insert-maybe
 146                                  expand-abbrev))
 147             (setq buffer-undo-list (primitive-undo 1 buffer-undo-list)))
 148       (skeleton-insert function
 149                        (if (setq skeleton-abbrev-cleanup
 150                                  (or (eq this-command 'self-insert-command)
 151                                      (eq this-command
 152                                          'skeleton-pair-insert-maybe)))
 153                            ()
 154                          ;; Pretend  C-x a e  passed its prefix arg to us
 155                          (if (or arg current-prefix-arg)
 156                              (prefix-numeric-value (or arg
 157                                                        current-prefix-arg))
 158                            (and skeleton-autowrap
 159                                 (or (eq last-command 'mouse-drag-region)
 160                                     (and transient-mark-mode mark-active))
 161                                 -1)))
 162                        (if (stringp str)
 163                            str))
 164       (and skeleton-abbrev-cleanup
 165            (setq skeleton-abbrev-cleanup (point))
 166            (add-hook 'post-command-hook 'skeleton-abbrev-cleanup nil t)))))
 167
 168
 169 (defun skeleton-abbrev-cleanup (&rest list)
 170   "Value for `post-command-hook' to remove char that expanded abbrev."
 171   (if (integerp skeleton-abbrev-cleanup)
 172       (progn
 173         (delete-region skeleton-abbrev-cleanup (point))
 174         (setq skeleton-abbrev-cleanup)
 175         (remove-hook 'post-command-hook 'skeleton-abbrev-cleanup t))))
 176
 177
 178 ;;;###autoload
 179 (defun skeleton-insert (skeleton &optional skeleton-regions str)
 180   "Insert the complex statement skeleton SKELETON describes very concisely.
 181
 182 With optional third REGIONS wrap first interesting point (`_') in skeleton
 183 around next REGIONS words, if REGIONS is positive.  If REGIONS is negative,
 184 wrap REGIONS preceding interregions into first REGIONS interesting positions
 185 \(successive `_'s) in skeleton.  An interregion is the stretch of text between
 186 two contiguous marked points.  If you marked A B C [] (where [] is the cursor)
 187 in alphabetical order, the 3 interregions are simply the last 3 regions.  But
 188 if you marked B A [] C, the interregions are B-A, A-[], []-C.
 189
 190 Optional fourth STR is the value for the variable `str' within the skeleton.
 191 When this is non-`nil' the interactor gets ignored, and this should be a valid
 192 skeleton element.
 193
 194 SKELETON is made up as (INTERACTOR ELEMENT ...).  INTERACTOR may be nil if
 195 not needed, a prompt-string or an expression for complex read functions.
 196
 197 If ELEMENT is a string or a character it gets inserted (see also
 198 `skeleton-transformation').  Other possibilities are:
 199
 200         \\n     go to next line and indent according to mode
 201         _       interesting point, interregion here, point after termination
 202         >       indent line (or interregion if > _) according to major mode
 203         &       do next ELEMENT if previous moved point
 204         |       do next ELEMENT if previous didn't move point
 205         -num    delete num preceding characters (see `skeleton-untabify')
 206         resume: skipped, continue here if quit is signaled
 207         nil     skipped
 208
 209 Further elements can be defined via `skeleton-further-elements'.  ELEMENT may
 210 itself be a SKELETON with an INTERACTOR.  The user is prompted repeatedly for
 211 different inputs.  The SKELETON is processed as often as the user enters a
 212 non-empty string.  \\[keyboard-quit] terminates skeleton insertion, but
 213 continues after `resume:' and positions at `_' if any.  If INTERACTOR in such
 214 a subskeleton is a prompt-string which contains a \".. %s ..\" it is
 215 formatted with `skeleton-subprompt'.  Such an INTERACTOR may also a list of
 216 strings with the subskeleton being repeated once for each string.
 217
 218 Quoted Lisp expressions are evaluated evaluated for their side-effect.
 219 Other Lisp expressions are evaluated and the value treated as above.
 220 Note that expressions may not return `t' since this implies an
 221 endless loop.  Modes can define other symbols by locally setting them
 222 to any valid skeleton element.  The following local variables are
 223 available:
 224
 225         str     first time: read a string according to INTERACTOR
 226                 then: insert previously read string once more
 227         help    help-form during interaction with the user or `nil'
 228         input   initial input (string or cons with index) while reading str
 229         v1, v2  local variables for memorizing anything you want
 230
 231 When done with skeleton, but before going back to `_'-point call
 232 `skeleton-end-hook' if that is non-`nil'."
 233   (and skeleton-regions
 234        (setq skeleton-regions
 235              (if (> skeleton-regions 0)
 236                  (list (point-marker)
 237                        (save-excursion (forward-word skeleton-regions)
 238                                        (point-marker)))
 239                (setq skeleton-regions (- skeleton-regions))
 240                ;; copy skeleton-regions - 1 elements from `mark-ring'
 241                (let ((l1 (cons (mark-marker) mark-ring))
 242                      (l2 (list (point-marker))))
 243                  (while (and l1 (> skeleton-regions 0))
 244                    (setq l2 (cons (car l1) l2)
 245                          skeleton-regions (1- skeleton-regions)
 246                          l1 (cdr l1)))
 247                  (sort l2 '<))))
 248        (goto-char (car skeleton-regions))
 249        (setq skeleton-regions (cdr skeleton-regions)))
 250   (let ((beg (point))
 251         skeleton-modified skeleton-point resume: help input v1 v2)
 252     (unwind-protect
 253         (eval `(let ,skeleton-further-elements
 254                  (skeleton-internal-list skeleton str)))
 255       (run-hooks 'skeleton-end-hook)
 256       (sit-for 0)
 257       (or (pos-visible-in-window-p beg)
 258           (progn
 259             (goto-char beg)
 260             (recenter 0)))
 261       (if skeleton-point
 262           (goto-char skeleton-point)))))
 263
 264 (defun skeleton-read (str &optional initial-input recursive)
 265   "Function for reading a string from the minibuffer within skeletons.
 266 PROMPT may contain a `%s' which will be replaced by `skeleton-subprompt'.
 267 If non-`nil' second arg INITIAL-INPUT or variable `input' is a string or
 268 cons with index to insert before reading.  If third arg RECURSIVE is non-`nil'
 269 i.e. we are handling the iterator of a subskeleton, returns empty string if
 270 user didn't modify input.
 271 While reading, the value of `minibuffer-help-form' is variable `help' if that
 272 is non-`nil' or a default string."
 273   (let ((minibuffer-help-form (or (if (boundp 'help) (symbol-value 'help))
 274                                   (if recursive "\
 275 As long as you provide input you will insert another subskeleton.
 276
 277 If you enter the empty string, the loop inserting subskeletons is
 278 left, and the current one is removed as far as it has been entered.
 279
 280 If you quit, the current subskeleton is removed as far as it has been
 281 entered.  No more of the skeleton will be inserted, except maybe for a
 282 syntactically necessary termination."
 283                                          "\
 284 You are inserting a skeleton.  Standard text gets inserted into the buffer
 285 automatically, and you are prompted to fill in the variable parts.")))
 286         (eolp (eolp)))
 287     ;; since Emacs doesn't show main window's cursor, do something noticeable
 288     (or eolp
 289         (open-line 1))
 290     (unwind-protect
 291         (setq str (if (stringp str)
 292                       (read-string (format str skeleton-subprompt)
 293                                    (setq initial-input
 294                                          (or initial-input
 295                                              (symbol-value 'input))))
 296                     (eval str)))
 297       (or eolp
 298           (delete-char 1))))
 299   (if (and recursive
 300            (or (null str)
 301                (string= str "")
 302                (equal str initial-input)
 303                (equal str (car-safe initial-input))))
 304       (signal 'quit t)
 305     str))
 306
 307 (defun skeleton-internal-list (skeleton &optional str recursive)
 308   (let* ((start (save-excursion (beginning-of-line) (point)))
 309          (column (current-column))
 310          (line (buffer-substring start
 311                                  (save-excursion (end-of-line) (point))))
 312          opoint)
 313     (or str
 314         (setq str `(setq str (skeleton-read ',(car skeleton) nil ,recursive))))
 315     (while (setq skeleton-modified (eq opoint (point))
 316                  opoint (point)
 317                  skeleton (cdr skeleton))
 318       (condition-case quit
 319           (skeleton-internal-1 (car skeleton))
 320         (quit
 321          (if (eq (cdr quit) 'recursive)
 322              (setq recursive 'quit
 323                    skeleton (memq 'resume: skeleton))
 324            ;; remove the subskeleton as far as it has been shown
 325            ;; the subskeleton shouldn't have deleted outside current line
 326            (end-of-line)
 327            (delete-region start (point))
 328            (insert line)
 329            (move-to-column column)
 330            (if (cdr quit)
 331                (setq skeleton ()
 332                      recursive nil)
 333              (signal 'quit 'recursive)))))))
 334   ;; maybe continue loop or go on to next outer resume: section
 335   (if (eq recursive 'quit)
 336       (signal 'quit 'recursive)
 337     recursive))
 338
 339
 340 (defun skeleton-internal-1 (element &optional literal)
 341   (cond ((char-or-string-p element)
 342          (if (and (integerp element)    ; -num
 343                   (< element 0))
 344              (if skeleton-untabify
 345                  (backward-delete-char-untabify (- element))
 346                (delete-backward-char (- element)))
 347            (insert-before-markers (if (and skeleton-transformation
 348                                            (not literal))
 349                                       (funcall skeleton-transformation element)
 350                                     element))))
 351         ((eq element '\n)               ; actually (eq '\n 'n)
 352          (if (and skeleton-regions
 353                   (eq (nth 1 skeleton) '_))
 354              (progn
 355                (or (eolp)
 356                    (newline))
 357                (indent-region (point) (car skeleton-regions) nil))
 358            (if skeleton-newline-indent-rigidly
 359                (indent-to (prog1 (current-indentation)
 360                             (newline)))
 361              (newline)
 362              (indent-according-to-mode))))
 363         ((eq element '>)
 364          (if (and skeleton-regions
 365                   (eq (nth 1 skeleton) '_))
 366              (indent-region (point) (car skeleton-regions) nil)
 367            (indent-according-to-mode)))
 368         ((eq element '_)
 369          (if skeleton-regions
 370              (progn
 371                (goto-char (car skeleton-regions))
 372                (setq skeleton-regions (cdr skeleton-regions))
 373                (and (<= (current-column) (current-indentation))
 374                     (eq (nth 1 skeleton) '\n)
 375                     (end-of-line 0)))
 376            (or skeleton-point
 377                (setq skeleton-point (point)))))
 378         ((eq element '&)
 379          (if skeleton-modified
 380              (setq skeleton (cdr skeleton))))
 381         ((eq element '|)
 382          (or skeleton-modified
 383              (setq skeleton (cdr skeleton))))
 384         ((eq 'quote (car-safe element))
 385          (eval (nth 1 element)))
 386         ((or (stringp (car-safe element))
 387              (consp (car-safe element)))
 388          (if (symbolp (car-safe (car element)))
 389              (while (skeleton-internal-list element nil t))
 390            (setq literal (car element))
 391            (while literal
 392              (skeleton-internal-list element (car literal))
 393              (setq literal (cdr literal)))))
 394         ((null element))
 395         ((skeleton-internal-1 (eval element) t))))
 396
 397
 398 ;; Maybe belongs into simple.el or elsewhere
 399 ;; ;###autoload
 400 ;;; (define-skeleton local-variables-section
 401 ;;  "Insert a local variables section.  Use current comment syntax if any."
 402 ;;  (completing-read "Mode: " obarray
 403 ;;                 (lambda (symbol)
 404 ;;                   (if (commandp symbol)
 405 ;;                       (string-match "-mode$" (symbol-name symbol))))
 406 ;;                 t)
 407 ;;  '(save-excursion
 408 ;;     (if (re-search-forward page-delimiter nil t)
 409 ;;       (error "Not on last page.")))
 410 ;;  comment-start "Local Variables:" comment-end \n
 411 ;;  comment-start "mode: " str
 412 ;;  & -5 | '(kill-line 0) & -1 | comment-end \n
 413 ;;  ( (completing-read (format "Variable, %s: " skeleton-subprompt)
 414 ;;                   obarray
 415 ;;                   (lambda (symbol)
 416 ;;                     (or (eq symbol 'eval)
 417 ;;                         (user-variable-p symbol)))
 418 ;;                   t)
 419 ;;    comment-start str ": "
 420 ;;    (read-from-minibuffer "Expression: " nil read-expression-map nil
 421 ;;                        'read-expression-history) | _
 422 ;;    comment-end \n)
 423 ;;  resume:
 424 ;;  comment-start "End:" comment-end)
 425 \f
 426 ;; Variables and command for automatically inserting pairs like () or "".
 427
 428 (defvar skeleton-pair nil
 429   "*If this is nil pairing is turned off, no matter what else is set.
 430 Otherwise modes with `skeleton-pair-insert-maybe' on some keys
 431 will attempt to insert pairs of matching characters.")
 432
 433
 434 (defvar skeleton-pair-on-word nil
 435   "*If this is nil, paired insertion is inhibited before or inside a word.")
 436
 437
 438 (defvar skeleton-pair-filter (lambda ())
 439   "Attempt paired insertion if this function returns nil, before inserting.
 440 This allows for context-sensitive checking whether pairing is appropriate.")
 441
 442
 443 (defvar skeleton-pair-alist ()
 444   "An override alist of pairing partners matched against `last-command-char'.
 445 Each alist element, which looks like (ELEMENT ...), is passed to
 446 `skeleton-insert' with no interactor.  Variable `str' does nothing.
 447
 448 Elements might be (?` ?` _ \"''\"), (?\\( ?  _ \" )\") or (?{ \\n > _ \\n ?} >).")
 449
 450
 451 ;;;###autoload
 452 (defun skeleton-pair-insert-maybe (arg)
 453   "Insert the character you type ARG times.
 454
 455 With no ARG, if `skeleton-pair' is non-nil, pairing can occur.  If the region
 456 is visible the pair is wrapped around it depending on `skeleton-autowrap'.
 457 Else, if `skeleton-pair-on-word' is non-nil or we are not before or inside a
 458 word, and if `skeleton-pair-filter' returns nil, pairing is performed.
 459
 460 If a match is found in `skeleton-pair-alist', that is inserted, else
 461 the defaults are used.  These are (), [], {}, <> and `' for the
 462 symmetrical ones, and the same character twice for the others."
 463   (interactive "*P")
 464   (let ((mark (and skeleton-autowrap
 465                    (or (eq last-command 'mouse-drag-region)
 466                        (and transient-mark-mode mark-active))))
 467         (skeleton-end-hook))
 468     (if (or arg
 469             (not skeleton-pair)
 470             (and (not mark)
 471                  (or overwrite-mode
 472                      (if (not skeleton-pair-on-word) (looking-at "\\w"))
 473                      (funcall skeleton-pair-filter))))
 474         (self-insert-command (prefix-numeric-value arg))
 475       (setq last-command-char (logand last-command-char 255))
 476       (or skeleton-abbrev-cleanup
 477           (skeleton-insert
 478            (cons nil (or (assq last-command-char skeleton-pair-alist)
 479                          (assq last-command-char '((?( _ ?))
 480                                                    (?[ _ ?])
 481                                                    (?{ _ ?})
 482                                                    (?< _ ?>)
 483                                                    (?` _ ?')))
 484                          `(,last-command-char _ ,last-command-char)))
 485            (if mark -1))))))
 486
 487 \f
 488 ;; A more serious example can be found in sh-script.el
 489 ;;; (defun mirror-mode ()
 490 ;;  "This major mode is an amusing little example of paired insertion.
 491 ;;All printable characters do a paired self insert, while the other commands
 492 ;;work normally."
 493 ;;  (interactive)
 494 ;;  (kill-all-local-variables)
 495 ;;  (make-local-variable 'skeleton-pair)
 496 ;;  (make-local-variable 'skeleton-pair-on-word)
 497 ;;  (make-local-variable 'skeleton-pair-filter)
 498 ;;  (make-local-variable 'skeleton-pair-alist)
 499 ;;  (setq major-mode 'mirror-mode
 500 ;;      mode-name "Mirror"
 501 ;;      skeleton-pair-on-word t
 502 ;;      ;; in the middle column insert one or none if odd window-width
 503 ;;      skeleton-pair-filter (lambda ()
 504 ;;                             (if (>= (current-column)
 505 ;;                                     (/ (window-width) 2))
 506 ;;                                 ;; insert both on next line
 507 ;;                                 (next-line 1)
 508 ;;                               ;; insert one or both?
 509 ;;                               (= (* 2 (1+ (current-column)))
 510 ;;                                  (window-width))))
 511 ;;      ;; mirror these the other way round as well
 512 ;;      skeleton-pair-alist '((?) _ ?()
 513 ;;                            (?] _ ?[)
 514 ;;                            (?} _ ?{)
 515 ;;                            (?> _ ?<)
 516 ;;                            (?/ _ ?\\)
 517 ;;                            (?\\ _ ?/)
 518 ;;                            (?` ?` _ "''")
 519 ;;                            (?' ?' _ "``"))
 520 ;;      ;; in this mode we exceptionally ignore the user, else it's no fun
 521 ;;      skeleton-pair t)
 522 ;;  (let ((map (make-vector 256 'skeleton-pair-insert-maybe))
 523 ;;      (i 0))
 524 ;;    (use-local-map `(keymap ,map))
 525 ;;    (while (< i ? )
 526 ;;      (aset map i nil)
 527 ;;      (aset map (+ i 128) nil)
 528 ;;      (setq i (1+ i))))
 529 ;;  (run-hooks 'mirror-mode-hook))
 530
 531 (provide 'skeleton)
 532
 533 ;; skeleton.el ends here