1 ;;; skeleton.el --- Lisp language extension for writing statement skeletons
3 ;; Copyright (C) 1993, 1994, 1995, 1996, 2003 by Free Software Foundation, Inc.
5 ;; Author: Daniel Pfeiffer <occitan@esperanto.org>
7 ;; Keywords: extensions, abbrev, languages, tools
9 ;; This file is part of GNU Emacs.
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)
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.
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.
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
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
41 (defvar skeleton-transformation 'identity
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'.")
47 ; this should be a fourth argument to defvar
48 (put 'skeleton-transformation 'variable-interactive
49 "aTransformation function: ")
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
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
63 (defvar skeleton-end-newline t
64 "If non-nil, make sure that the skeleton inserted ends with a newline.
65 This just influences the way the default `skeleton-end-hook' behaves.")
67 (defvar skeleton-end-hook
69 (or (eolp) (not skeleton-end-newline) (newline-and-indent)))
70 "Hook called at end of skeleton but before going to point of interest.
71 By default this moves out anything following to next line,
72 unless `skeleton-end-newline' is set to nil.
73 The variables `v1' and `v2' are still set when calling this.")
77 (defvar skeleton-filter 'identity
78 "Function for transforming a skeleton proxy's aliases' variable value.")
80 (defvar skeleton-untabify t
81 "When non-nil untabifies when deleting backwards with element -ARG.")
83 (defvar skeleton-newline-indent-rigidly nil
84 "When non-nil, indent rigidly under current line for element `\\n'.
85 Else use mode's `indent-line-function'.")
87 (defvar skeleton-further-elements ()
88 "A buffer-local varlist (see `let') of mode specific skeleton elements.
89 These variables are bound while interpreting a skeleton. Their value may
90 in turn be any valid skeleton element if they are themselves to be used as
92 (make-variable-buffer-local 'skeleton-further-elements)
95 (defvar skeleton-subprompt
96 (substitute-command-keys
97 "RET, \\<minibuffer-local-map>\\[abort-recursive-edit] or \\[help-command]")
98 "*Replacement for %s in prompts of recursive subskeletons.")
101 (defvar skeleton-abbrev-cleanup nil
102 "Variable used to delete the character that led to abbrev expansion.")
105 (defvar skeleton-debug nil
106 "*If non-nil `define-skeleton' will override previous definition.")
108 (defvar skeleton-positions nil
109 "List of positions marked with @, after skeleton insertion.
110 The list describes the most recent skeleton insertion, and its elements
111 are integer buffer positions in the reverse order of the insertion order.")
113 ;; reduce the number of compiler warnings
115 (defvar skeleton-modified)
116 (defvar skeleton-point)
117 (defvar skeleton-regions)
120 (defmacro define-skeleton (command documentation &rest skeleton)
121 "Define a user-configurable COMMAND that enters a statement skeleton.
122 DOCUMENTATION is that of the command.
123 SKELETON is as defined under `skeleton-insert'."
125 (set command skeleton))
127 ;; Tell self-insert-command that this function, if called by an
128 ;; abbrev, should cause the self-insert to be skipped.
129 (put ',command 'no-self-insert t)
130 (defun ,command (&optional str arg)
131 ,(concat documentation
132 (if (string-match "\n\\'" documentation)
135 "This is a skeleton command (see `skeleton-insert').
136 Normally the skeleton text is inserted at point, with nothing \"inside\".
137 If there is a highlighted region, the skeleton text is wrapped
138 around the region text.
140 A prefix argument ARG says to wrap the skeleton around the next ARG words.
141 A prefix argument of -1 says to wrap around region, even if not highlighted.
142 A prefix argument of zero says to wrap around zero words---that is, nothing.
143 This is a way of overriding the use of a highlighted region.")
144 (interactive "*P\nP")
145 (skeleton-proxy-new ',skeleton str arg))))
148 (defun skeleton-proxy-new (skeleton &optional str arg)
150 Prefix ARG allows wrapping around words or regions (see `skeleton-insert').
151 If no ARG was given, but the region is visible, ARG defaults to -1 depending
152 on `skeleton-autowrap'. An ARG of M-0 will prevent this just for once.
153 This command can also be an abbrev expansion (3rd and 4th columns in
154 \\[edit-abbrevs] buffer: \"\" command-name).
156 Optional first argument STR may also be a string which will be the value
157 of `str' whereas the skeleton's interactor is then ignored."
158 (skeleton-insert (funcall skeleton-filter skeleton)
159 ;; Pretend C-x a e passed its prefix arg to us
160 (if (or arg current-prefix-arg)
161 (prefix-numeric-value (or arg
163 (and skeleton-autowrap
164 (or (eq last-command 'mouse-drag-region)
165 (and transient-mark-mode mark-active))
169 ;; Return non-nil to tell expand-abbrev that expansion has happened.
170 ;; Otherwise the no-self-insert is ignored.
173 ;; This command isn't meant to be called, only its aliases with meaningful
176 (defun skeleton-proxy (&optional str arg)
177 "Insert skeleton defined by variable of same name (see `skeleton-insert').
178 Prefix ARG allows wrapping around words or regions (see `skeleton-insert').
179 If no ARG was given, but the region is visible, ARG defaults to -1 depending
180 on `skeleton-autowrap'. An ARG of M-0 will prevent this just for once.
181 This command can also be an abbrev expansion (3rd and 4th columns in
182 \\[edit-abbrevs] buffer: \"\" command-name).
184 When called as a function, optional first argument STR may also be a string
185 which will be the value of `str' whereas the skeleton's interactor is then
187 (interactive "*P\nP")
188 (let ((function (nth 1 (backtrace-frame 1))))
189 (if (eq function 'nth) ; uncompiled Lisp function
190 (setq function (nth 1 (backtrace-frame 5)))
191 (if (eq function 'byte-code) ; tracing byte-compiled function
192 (setq function (nth 1 (backtrace-frame 2)))))
193 (if (not (setq function (funcall skeleton-filter (symbol-value function))))
194 (if (memq this-command '(self-insert-command
195 skeleton-pair-insert-maybe
197 (setq buffer-undo-list (primitive-undo 1 buffer-undo-list)))
198 (skeleton-insert function
199 (if (setq skeleton-abbrev-cleanup
200 (or (eq this-command 'self-insert-command)
202 'skeleton-pair-insert-maybe)))
204 ;; Pretend C-x a e passed its prefix arg to us
205 (if (or arg current-prefix-arg)
206 (prefix-numeric-value (or arg
208 (and skeleton-autowrap
209 (or (eq last-command 'mouse-drag-region)
210 (and transient-mark-mode mark-active))
214 (and skeleton-abbrev-cleanup
215 (setq skeleton-abbrev-cleanup (point))
216 (add-hook 'post-command-hook 'skeleton-abbrev-cleanup nil t)))))
219 (defun skeleton-abbrev-cleanup (&rest list)
220 "Value for `post-command-hook' to remove char that expanded abbrev."
221 (if (integerp skeleton-abbrev-cleanup)
223 (delete-region skeleton-abbrev-cleanup (point))
224 (setq skeleton-abbrev-cleanup)
225 (remove-hook 'post-command-hook 'skeleton-abbrev-cleanup t))))
229 (defun skeleton-insert (skeleton &optional regions str)
230 "Insert the complex statement skeleton SKELETON describes very concisely.
232 With optional second argument REGIONS, wrap first interesting point
233 \(`_') in skeleton around next REGIONS words, if REGIONS is positive.
234 If REGIONS is negative, wrap REGIONS preceding interregions into first
235 REGIONS interesting positions \(successive `_'s) in skeleton.
237 An interregion is the stretch of text between two contiguous marked
238 points. If you marked A B C [] (where [] is the cursor) in
239 alphabetical order, the 3 interregions are simply the last 3 regions.
240 But if you marked B A [] C, the interregions are B-A, A-[], []-C.
242 The optional third argument STR, if specified, is the value for the
243 variable `str' within the skeleton. When this is non-nil, the
244 interactor gets ignored, and this should be a valid skeleton element.
246 SKELETON is made up as (INTERACTOR ELEMENT ...). INTERACTOR may be nil if
247 not needed, a prompt-string or an expression for complex read functions.
249 If ELEMENT is a string or a character it gets inserted (see also
250 `skeleton-transformation'). Other possibilities are:
252 \\n go to next line and indent according to mode
253 _ interesting point, interregion here
254 - interesting point, no interregion interaction, overrides
255 interesting point set by _
256 > indent line (or interregion if > _) according to major mode
257 @ add position to `skeleton-positions'
258 & do next ELEMENT iff previous moved point
259 | do next ELEMENT iff previous didn't move point
260 -num delete num preceding characters (see `skeleton-untabify')
261 resume: skipped, continue here if quit is signaled
264 After termination, point will be positioned at the last occurrence of -
265 or at the first occurrence of _ or at the end of the inserted text.
267 Further elements can be defined via `skeleton-further-elements'. ELEMENT may
268 itself be a SKELETON with an INTERACTOR. The user is prompted repeatedly for
269 different inputs. The SKELETON is processed as often as the user enters a
270 non-empty string. \\[keyboard-quit] terminates skeleton insertion, but
271 continues after `resume:' and positions at `_' if any. If INTERACTOR in such
272 a subskeleton is a prompt-string which contains a \".. %s ..\" it is
273 formatted with `skeleton-subprompt'. Such an INTERACTOR may also be a list of
274 strings with the subskeleton being repeated once for each string.
276 Quoted Lisp expressions are evaluated for their side-effects.
277 Other Lisp expressions are evaluated and the value treated as above.
278 Note that expressions may not return t since this implies an
279 endless loop. Modes can define other symbols by locally setting them
280 to any valid skeleton element. The following local variables are
283 str first time: read a string according to INTERACTOR
284 then: insert previously read string once more
285 help help-form during interaction with the user or nil
286 input initial input (string or cons with index) while reading str
287 v1, v2 local variables for memorizing anything you want
289 When done with skeleton, but before going back to `_'-point call
290 `skeleton-end-hook' if that is non-nil."
291 (let ((skeleton-regions regions))
292 (and skeleton-regions
293 (setq skeleton-regions
294 (if (> skeleton-regions 0)
295 (list (copy-marker (point) t)
296 (save-excursion (forward-word skeleton-regions)
298 (setq skeleton-regions (- skeleton-regions))
299 ;; copy skeleton-regions - 1 elements from `mark-ring'
300 (let ((l1 (cons (mark-marker) mark-ring))
301 (l2 (list (copy-marker (point) t))))
302 (while (and l1 (> skeleton-regions 0))
303 (push (copy-marker (pop l1) t) l2)
304 (setq skeleton-regions (1- skeleton-regions)))
306 (goto-char (car skeleton-regions))
307 (setq skeleton-regions (cdr skeleton-regions)))
309 skeleton-modified skeleton-point resume: help input v1 v2)
310 (setq skeleton-positions nil)
312 (eval `(let ,skeleton-further-elements
313 (skeleton-internal-list skeleton str)))
314 (run-hooks 'skeleton-end-hook)
316 (or (pos-visible-in-window-p beg)
321 (goto-char skeleton-point))))))
323 (defun skeleton-read (prompt &optional initial-input recursive)
324 "Function for reading a string from the minibuffer within skeletons.
326 PROMPT must be a string or a form that evaluates to a string.
327 It may contain a `%s' which will be replaced by `skeleton-subprompt'.
328 If non-nil second arg INITIAL-INPUT or variable `input' is a string or
329 cons with index to insert before reading. If third arg RECURSIVE is non-nil
330 i.e. we are handling the iterator of a subskeleton, returns empty string if
331 user didn't modify input.
332 While reading, the value of `minibuffer-help-form' is variable `help' if that
333 is non-nil or a default string."
334 (let ((minibuffer-help-form (or (if (boundp 'help) (symbol-value 'help))
336 As long as you provide input you will insert another subskeleton.
338 If you enter the empty string, the loop inserting subskeletons is
339 left, and the current one is removed as far as it has been entered.
341 If you quit, the current subskeleton is removed as far as it has been
342 entered. No more of the skeleton will be inserted, except maybe for a
343 syntactically necessary termination."
345 You are inserting a skeleton. Standard text gets inserted into the buffer
346 automatically, and you are prompted to fill in the variable parts.")))
348 ;; since Emacs doesn't show main window's cursor, do something noticeable
352 (setq prompt (if (stringp prompt)
353 (read-string (format prompt skeleton-subprompt)
356 (symbol-value 'input))))
363 (equal prompt initial-input)
364 (equal prompt (car-safe initial-input))))
368 (defun skeleton-internal-list (skeleton &optional str recursive)
369 (let* ((start (save-excursion (beginning-of-line) (point)))
370 (column (current-column))
371 (line (buffer-substring start (line-end-position)))
374 (setq str `(setq str (skeleton-read ',(car skeleton) nil ,recursive))))
375 (when (and (eq (cadr skeleton) '\n) (not recursive)
376 (save-excursion (skip-chars-backward " \t") (bolp)))
377 (setq skeleton (cons nil (cons '> (cddr skeleton)))))
378 (while (setq skeleton-modified (eq opoint (point))
380 skeleton (cdr skeleton))
382 (skeleton-internal-1 (car skeleton) nil recursive)
384 (if (eq (cdr quit) 'recursive)
385 (setq recursive 'quit
386 skeleton (memq 'resume: skeleton))
387 ;; Remove the subskeleton as far as it has been shown
388 ;; the subskeleton shouldn't have deleted outside current line.
390 (delete-region start (point))
392 (move-to-column column)
396 (signal 'quit 'recursive)))))))
397 ;; maybe continue loop or go on to next outer resume: section
398 (if (eq recursive 'quit)
399 (signal 'quit 'recursive)
402 (defun skeleton-internal-1 (element &optional literal recursive)
404 ((char-or-string-p element)
405 (if (and (integerp element) ; -num
407 (if skeleton-untabify
408 (backward-delete-char-untabify (- element))
409 (delete-backward-char (- element)))
410 (insert (if (not literal)
411 (funcall skeleton-transformation element)
413 ((or (eq element '\n) ; actually (eq '\n 'n)
414 ;; The sequence `> \n' is handled specially so as to indent the first
415 ;; line after inserting the newline (to get the proper indentation).
416 (and (eq element '>) (eq (nth 1 skeleton) '\n) (pop skeleton)))
417 (let ((pos (if (eq element '>) (point))))
419 ((and skeleton-regions (eq (nth 1 skeleton) '_))
420 (or (eolp) (newline))
421 (if pos (save-excursion (goto-char pos) (indent-according-to-mode)))
422 (indent-region (line-beginning-position)
423 (car skeleton-regions) nil))
424 ;; \n as last element only inserts \n if not at eol.
425 ((and (null (cdr skeleton)) (not recursive) (eolp))
426 (if pos (indent-according-to-mode)))
427 (skeleton-newline-indent-rigidly
430 (indent-to (save-excursion
432 (if pos (indent-according-to-mode))
433 (current-indentation)))))
434 (t (if pos (reindent-then-newline-and-indent)
436 (indent-according-to-mode))))))
438 (if (and skeleton-regions (eq (nth 1 skeleton) '_))
439 (indent-region (line-beginning-position)
440 (car skeleton-regions) nil)
441 (indent-according-to-mode)))
445 (goto-char (pop skeleton-regions))
446 (and (<= (current-column) (current-indentation))
447 (eq (nth 1 skeleton) '\n)
450 (setq skeleton-point (point)))))
452 (setq skeleton-point (point)))
454 (when skeleton-modified (pop skeleton)))
456 (unless skeleton-modified (pop skeleton)))
458 (push (point) skeleton-positions))
459 ((eq 'quote (car-safe element))
460 (eval (nth 1 element)))
461 ((or (stringp (car-safe element))
462 (consp (car-safe element)))
463 (if (symbolp (car-safe (car element)))
464 (while (skeleton-internal-list element nil t))
465 (setq literal (car element))
467 (skeleton-internal-list element (car literal))
468 (setq literal (cdr literal)))))
470 (t (skeleton-internal-1 (eval element) t recursive))))
472 ;; Maybe belongs into simple.el or elsewhere
474 ;; (define-skeleton local-variables-section
475 ;; "Insert a local variables section. Use current comment syntax if any."
476 ;; (completing-read "Mode: " obarray
478 ;; (if (commandp symbol)
479 ;; (string-match "-mode$" (symbol-name symbol))))
482 ;; (if (re-search-forward page-delimiter nil t)
483 ;; (error "Not on last page")))
484 ;; comment-start "Local Variables:" comment-end \n
485 ;; comment-start "mode: " str
486 ;; & -5 | '(kill-line 0) & -1 | comment-end \n
487 ;; ( (completing-read (format "Variable, %s: " skeleton-subprompt)
490 ;; (or (eq symbol 'eval)
491 ;; (user-variable-p symbol)))
493 ;; comment-start str ": "
494 ;; (read-from-minibuffer "Expression: " nil read-expression-map nil
495 ;; 'read-expression-history) | _
498 ;; comment-start "End:" comment-end \n)
500 ;; Variables and command for automatically inserting pairs like () or "".
502 (defvar skeleton-pair nil
503 "*If this is nil pairing is turned off, no matter what else is set.
504 Otherwise modes with `skeleton-pair-insert-maybe' on some keys
505 will attempt to insert pairs of matching characters.")
508 (defvar skeleton-pair-on-word nil
509 "*If this is nil, paired insertion is inhibited before or inside a word.")
512 (defvar skeleton-pair-filter (lambda () nil)
513 "Attempt paired insertion if this function returns nil, before inserting.
514 This allows for context-sensitive checking whether pairing is appropriate.")
517 (defvar skeleton-pair-alist ()
518 "An override alist of pairing partners matched against `last-command-char'.
519 Each alist element, which looks like (ELEMENT ...), is passed to
520 `skeleton-insert' with no interactor. Variable `str' does nothing.
522 Elements might be (?` ?` _ \"''\"), (?\\( ? _ \" )\") or (?{ \\n > _ \\n ?} >).")
526 (defun skeleton-pair-insert-maybe (arg)
527 "Insert the character you type ARG times.
529 With no ARG, if `skeleton-pair' is non-nil, pairing can occur. If the region
530 is visible the pair is wrapped around it depending on `skeleton-autowrap'.
531 Else, if `skeleton-pair-on-word' is non-nil or we are not before or inside a
532 word, and if `skeleton-pair-filter' returns nil, pairing is performed.
533 Pairing is also prohibited if we are right after a quoting character
536 If a match is found in `skeleton-pair-alist', that is inserted, else
537 the defaults are used. These are (), [], {}, <> and `' for the
538 symmetrical ones, and the same character twice for the others."
540 (let ((mark (and skeleton-autowrap
541 (or (eq last-command 'mouse-drag-region)
542 (and transient-mark-mode mark-active))))
546 (memq (char-syntax (preceding-char)) '(?\\ ?/))
549 (if (not skeleton-pair-on-word) (looking-at "\\w"))
550 (funcall skeleton-pair-filter))))
551 (self-insert-command (prefix-numeric-value arg))
552 (setq last-command-char (logand last-command-char 255))
553 (or skeleton-abbrev-cleanup
555 (cons nil (or (assq last-command-char skeleton-pair-alist)
556 (assq last-command-char '((?( _ ?))
561 `(,last-command-char _ ,last-command-char)))
565 ;; A more serious example can be found in sh-script.el
566 ;;; (defun mirror-mode ()
567 ;; "This major mode is an amusing little example of paired insertion.
568 ;;All printable characters do a paired self insert, while the other commands
571 ;; (kill-all-local-variables)
572 ;; (make-local-variable 'skeleton-pair)
573 ;; (make-local-variable 'skeleton-pair-on-word)
574 ;; (make-local-variable 'skeleton-pair-filter)
575 ;; (make-local-variable 'skeleton-pair-alist)
576 ;; (setq major-mode 'mirror-mode
577 ;; mode-name "Mirror"
578 ;; skeleton-pair-on-word t
579 ;; ;; in the middle column insert one or none if odd window-width
580 ;; skeleton-pair-filter (lambda ()
581 ;; (if (>= (current-column)
582 ;; (/ (window-width) 2))
583 ;; ;; insert both on next line
585 ;; ;; insert one or both?
586 ;; (= (* 2 (1+ (current-column)))
588 ;; ;; mirror these the other way round as well
589 ;; skeleton-pair-alist '((?) _ ?()
597 ;; ;; in this mode we exceptionally ignore the user, else it's no fun
599 ;; (let ((map (make-vector 256 'skeleton-pair-insert-maybe))
601 ;; (use-local-map `(keymap ,map))
604 ;; (aset map (+ i 128) nil)
606 ;; (run-hooks 'mirror-mode-hook))
610 ;;; skeleton.el ends here