1 ;;; skeleton.el --- Lisp language extension for writing statement skeletons
3 ;; Copyright (C) 1993-1996, 2001-2018 Free Software Foundation, Inc.
5 ;; Author: Daniel Pfeiffer <occitan@esperanto.org>
6 ;; Maintainer: emacs-devel@gnu.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 3 of the License, or
14 ;; (at your option) any later version.
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. If not, see <https://www.gnu.org/licenses/>.
26 ;; A very concise language extension for writing structured statement
27 ;; skeleton insertion commands for programming language modes. This
28 ;; originated in shell-script mode and was applied to ada-mode's
29 ;; commands which shrunk to one third. And these commands are now
34 (eval-when-compile (require 'cl-lib
))
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
40 (defvaralias 'skeleton-transformation
'skeleton-transformation-function
)
42 (defvar skeleton-transformation-function
'identity
43 "If non-nil, function applied to literal strings before they are inserted.
44 It should take strings and characters and return them transformed, or nil
45 which means no transformation.
46 Typical examples might be `upcase' or `capitalize'.")
48 ; this should be a fourth argument to defvar
49 (put 'skeleton-transformation-function
'variable-interactive
50 "aTransformation function: ")
53 (defvar skeleton-autowrap t
54 "Controls wrapping behavior of functions created with `define-skeleton'.
55 When the region is visible (due to `transient-mark-mode' or marking a region
56 with the mouse) and this is non-nil and the function was called without an
57 explicit ARG, then the ARG defaults to -1, i.e. wrapping around the visible
59 (make-obsolete-variable 'skeleton-autowrap nil
"24.5")
61 (defvar skeleton-end-newline t
62 "If non-nil, make sure that the skeleton inserted ends with a newline.")
64 (defvar skeleton-end-hook nil
65 "Hook called at end of skeleton but before going to point of interest.
66 The variables `v1' and `v2' are still set when calling this.")
68 (defvaralias 'skeleton-filter
'skeleton-filter-function
)
71 (defvar skeleton-filter-function
'identity
72 "Function for transforming a skeleton proxy's aliases' variable value.")
74 (defvar skeleton-untabify nil
; bug#12223
75 "When non-nil untabifies when deleting backwards with element -ARG.")
77 (defvar skeleton-newline-indent-rigidly nil
78 "When non-nil, indent rigidly under current line for element `\\n'.
79 Else use mode's `indent-line-function'.")
81 (defvar-local skeleton-further-elements
()
82 "A buffer-local varlist (see `let') of mode specific skeleton elements.
83 These variables are bound while interpreting a skeleton. Their value may
84 in turn be any valid skeleton element if they are themselves to be used as
87 (defvar skeleton-subprompt
88 (substitute-command-keys
89 "RET, \\<minibuffer-local-map>\\[abort-recursive-edit] or \\[help-command]")
90 "Replacement for %s in prompts of recursive subskeletons.")
93 (defvar skeleton-debug nil
94 "If non-nil `define-skeleton' will override previous definition.")
96 (defvar skeleton-positions nil
97 "List of positions marked with @, after skeleton insertion.
98 The list describes the most recent skeleton insertion, and its elements
99 are integer buffer positions in the reverse order of the insertion order.")
101 ;; reduce the number of compiler warnings
103 (defvar skeleton-modified
)
104 (defvar skeleton-point
)
105 (defvar skeleton-regions
)
107 (def-edebug-spec skeleton-edebug-spec
108 ([&or null stringp
(stringp &rest stringp
) [[¬ atom
] def-form
]]
109 &rest
&or
"n" "_" "-" ">" "@" "&" "!" "resume:"
110 ("quote" def-form
) skeleton-edebug-spec def-form
))
112 (defmacro define-skeleton
(command documentation
&rest skeleton
)
113 "Define a user-configurable COMMAND that enters a statement skeleton.
114 DOCUMENTATION is that of the command.
115 SKELETON is as defined under `skeleton-insert'."
116 (declare (doc-string 2) (debug (&define name stringp skeleton-edebug-spec
)))
118 (set command skeleton
))
120 ;; Tell self-insert-command that this function, if called by an
121 ;; abbrev, should cause the self-insert to be skipped.
122 (put ',command
'no-self-insert t
)
123 (defun ,command
(&optional str arg
)
124 ,(concat documentation
125 (if (string-match "\n\\'" documentation
)
128 "This is a skeleton command (see `skeleton-insert').
129 Normally the skeleton text is inserted at point, with nothing \"inside\".
130 If there is a highlighted region, the skeleton text is wrapped
131 around the region text.
133 A prefix argument ARG says to wrap the skeleton around the next ARG words.
134 A prefix argument of -1 says to wrap around region, even if not highlighted.
135 A prefix argument of zero says to wrap around zero words---that is, nothing.
136 This is a way of overriding the use of a highlighted region.")
137 (interactive "*P\nP")
138 (skeleton-proxy-new ',skeleton str arg
))))
141 (defun skeleton-proxy-new (skeleton &optional str arg
)
143 Prefix ARG allows wrapping around words or regions (see `skeleton-insert').
144 If no ARG was given, but the region is visible, ARG defaults to -1 depending
145 on `skeleton-autowrap'. An ARG of M-0 will prevent this just for once.
146 This command can also be an abbrev expansion (3rd and 4th columns in
147 \\[edit-abbrevs] buffer: \"\" command-name).
149 Optional second argument STR may also be a string which will be the value
150 of `str' whereas the skeleton's interactor is then ignored."
151 (skeleton-insert (funcall skeleton-filter-function skeleton
)
152 ;; Pretend C-x a e passed its prefix arg to us
153 (if (or arg current-prefix-arg
)
154 (prefix-numeric-value (or arg
156 (and skeleton-autowrap
157 (or (eq last-command
'mouse-drag-region
)
158 (and transient-mark-mode mark-active
))
159 ;; Deactivate the mark, in case one of the
160 ;; elements of the skeleton is sensitive
161 ;; to such situations (e.g. it is itself a
163 (progn (deactivate-mark)
167 ;; Return non-nil to tell expand-abbrev that expansion has happened.
168 ;; Otherwise the no-self-insert is ignored.
172 (defun skeleton-insert (skeleton &optional regions str
)
173 "Insert the complex statement skeleton SKELETON describes very concisely.
175 With optional second argument REGIONS, wrap first interesting point
176 \(`_') in skeleton around next REGIONS words, if REGIONS is positive.
177 If REGIONS is negative, wrap REGIONS preceding interregions into first
178 REGIONS interesting positions (successive `_'s) in skeleton.
180 An interregion is the stretch of text between two contiguous marked
181 points. If you marked A B C [] (where [] is the cursor) in
182 alphabetical order, the 3 interregions are simply the last 3 regions.
183 But if you marked B A [] C, the interregions are B-A, A-[], []-C.
185 The optional third argument STR, if specified, is the value for the
186 variable `str' within the skeleton. When this is non-nil, the
187 interactor gets ignored, and this should be a valid skeleton element.
189 When done with skeleton, but before going back to `_'-point, add
190 a newline (unless `skeleton-end-newline' is nil) and run the hook
193 SKELETON is made up as (INTERACTOR ELEMENT ...). INTERACTOR may be nil if
194 not needed, a prompt-string or an expression for complex read functions.
196 If ELEMENT is a string or a character it gets inserted (see also
197 `skeleton-transformation-function'). Other possibilities are:
199 \\n go to next line and indent according to mode, unless
200 this is the first/last element of a skeleton and point
202 _ interesting point, interregion here
203 - interesting point, no interregion interaction, overrides
204 interesting point set by _
205 > indent line (or interregion if > _) according to major mode
206 @ add position to `skeleton-positions'
207 & do next ELEMENT if previous moved point
208 | do next ELEMENT if previous didn't move point
209 -NUM delete NUM preceding characters (see `skeleton-untabify')
210 resume: skipped, continue here if quit is signaled
213 After termination, point will be positioned at the last occurrence of -
214 or at the first occurrence of _ or at the end of the inserted text.
216 Note that \\n as the last element of the skeleton only inserts a
217 newline if not at eol. If you want to unconditionally insert a newline
218 at the end of the skeleton, use \"\\n\" instead. Likewise with \\n
219 as the first element when at bol.
221 Further elements can be defined via `skeleton-further-elements'.
222 ELEMENT may itself be a SKELETON with an INTERACTOR. The user is prompted
223 repeatedly for different inputs. The SKELETON is processed as often as
224 the user enters a non-empty string. \\[keyboard-quit] terminates skeleton insertion, but
225 continues after `resume:' and positions at `_' if any. If INTERACTOR in
226 such a subskeleton is a prompt-string which contains a \".. %s ..\" it is
227 formatted with `skeleton-subprompt'. Such an INTERACTOR may also be a list
228 of strings with the subskeleton being repeated once for each string.
230 Quoted Lisp expressions are evaluated for their side-effects.
231 Other Lisp expressions are evaluated and the value treated as above.
232 Note that expressions may not return t since this implies an
233 endless loop. Modes can define other symbols by locally setting them
234 to any valid skeleton element. The following local variables are
237 str first time: read a string according to INTERACTOR
238 then: insert previously read string once more
239 help help-form during interaction with the user or nil
240 input initial input (string or cons with index) while reading str
241 v1, v2 local variables for memorizing anything you want"
242 (let ((skeleton-regions regions
))
243 (and skeleton-regions
244 (setq skeleton-regions
245 (if (> skeleton-regions
0)
246 (list (copy-marker (point) t
)
247 (save-excursion (forward-word-strictly
250 (setq skeleton-regions
(- skeleton-regions
))
251 ;; copy skeleton-regions - 1 elements from `mark-ring'
252 (let ((l1 (cons (mark-marker) mark-ring
))
253 (l2 (list (copy-marker (point) t
))))
254 (while (and l1
(> skeleton-regions
0))
255 (push (copy-marker (pop l1
) t
) l2
)
256 (setq skeleton-regions
(1- skeleton-regions
)))
258 (goto-char (car skeleton-regions
))
259 (setq skeleton-regions
(cdr skeleton-regions
)))
261 skeleton-modified skeleton-point resume
: help input v1 v2
)
262 (setq skeleton-positions nil
)
265 (mapcar #'car skeleton-further-elements
)
266 (mapcar (lambda (x) (eval (cadr x
))) skeleton-further-elements
)
267 (skeleton-internal-list skeleton str
))
268 (or (eolp) (not skeleton-end-newline
) (newline-and-indent))
269 (run-hooks 'skeleton-end-hook
)
271 (or (not (eq (window-buffer) (current-buffer)))
272 (pos-visible-in-window-p beg
)
277 (goto-char skeleton-point
))))))
279 (defun skeleton-read (prompt &optional initial-input recursive
)
280 "Function for reading a string from the minibuffer within skeletons.
282 PROMPT must be a string or a function that evaluates to a string.
283 It may also be a form that evaluates to a string (deprecated).
284 It may contain a `%s' which will be replaced by `skeleton-subprompt'.
285 If non-nil second arg INITIAL-INPUT or variable `input' is a string or
286 cons with index to insert before reading. If third arg RECURSIVE is non-nil
287 i.e. we are handling the iterator of a subskeleton, returns empty string if
288 user didn't modify input.
289 While reading, the value of `minibuffer-help-form' is variable `help' if that
290 is non-nil or a default string."
291 (let ((minibuffer-help-form (or (if (boundp 'help
) (symbol-value 'help
))
293 As long as you provide input you will insert another subskeleton.
295 If you enter the empty string, the loop inserting subskeletons is
296 left, and the current one is removed as far as it has been entered.
298 If you quit, the current subskeleton is removed as far as it has been
299 entered. No more of the skeleton will be inserted, except maybe for a
300 syntactically necessary termination."
302 You are inserting a skeleton. Standard text gets inserted into the buffer
303 automatically, and you are prompted to fill in the variable parts.")))
305 ;; since Emacs doesn't show main window's cursor, do something noticeable
307 ;; We used open-line before, but that can do a lot more than we want,
308 ;; since it runs self-insert-command. E.g. it may remove spaces
310 (save-excursion (insert "\n")))
312 (setq prompt
(cond ((stringp prompt
)
313 (read-string (format prompt skeleton-subprompt
)
316 (symbol-value 'input
)))))
325 (equal prompt initial-input
)
326 (equal prompt
(car-safe initial-input
))))
330 (defun skeleton-internal-list (skeleton-il &optional str recursive
)
331 (let* ((start (line-beginning-position))
332 (column (current-column))
333 (line (buffer-substring start
(line-end-position)))
337 (skeleton-read ',(car skeleton-il
) nil
,recursive
))))
338 (when (and (eq (cadr skeleton-il
) '\n) (not recursive
)
339 (save-excursion (skip-chars-backward " \t") (bolp)))
340 (setq skeleton-il
(cons nil
(cons '> (cddr skeleton-il
)))))
341 (while (setq skeleton-modified
(eq opoint
(point))
343 skeleton-il
(cdr skeleton-il
))
345 (skeleton-internal-1 (car skeleton-il
) nil recursive
)
347 (if (eq (cdr quit
) 'recursive
)
348 (setq recursive
'quit
349 skeleton-il
(memq 'resume
: skeleton-il
))
350 ;; Remove the subskeleton as far as it has been shown
351 ;; the subskeleton shouldn't have deleted outside current line.
353 (delete-region start
(point))
355 (move-to-column column
)
359 (signal 'quit
'recursive
)))))))
360 ;; maybe continue loop or go on to next outer resume: section
361 (if (eq recursive
'quit
)
362 (signal 'quit
'recursive
)
366 (defun skeleton-internal-1 (element &optional literal recursive
)
368 ((or (integerp element
) (stringp element
))
369 (if (and (integerp element
) ; -num
371 (if skeleton-untabify
372 (backward-delete-char-untabify (- element
))
373 (delete-char element
))
374 (insert (if (not literal
)
375 (funcall skeleton-transformation-function element
)
377 ((or (eq element
'\n) ; actually (eq '\n 'n)
378 ;; The sequence `> \n' is handled specially so as to indent the first
379 ;; line after inserting the newline (to get the proper indentation).
380 (and (eq element
'>) (eq (nth 1 skeleton-il
) '\n) (pop skeleton-il
)))
381 (let ((pos (if (eq element
'>) (point))))
383 ((and skeleton-regions
(eq (nth 1 skeleton-il
) '_
))
384 (or (eolp) (insert "\n"))
385 (if pos
(save-excursion (goto-char pos
) (indent-according-to-mode)))
386 (indent-region (line-beginning-position)
387 (car skeleton-regions
) nil
))
388 ;; \n as last element only inserts \n if not at eol.
389 ((and (null (cdr skeleton-il
)) (not recursive
) (eolp))
390 (if pos
(indent-according-to-mode)))
391 (skeleton-newline-indent-rigidly
394 (indent-to (save-excursion
396 (if pos
(indent-according-to-mode))
397 (current-indentation)))))
398 (t (if pos
(reindent-then-newline-and-indent)
400 (indent-according-to-mode))))))
402 (if (and skeleton-regions
(eq (nth 1 skeleton-il
) '_
))
403 (indent-region (line-beginning-position)
404 (car skeleton-regions
) nil
)
405 (indent-according-to-mode)))
409 (goto-char (pop skeleton-regions
))
410 (and (<= (current-column) (current-indentation))
411 (eq (nth 1 skeleton-il
) '\n)
414 (setq skeleton-point
(point)))))
416 (setq skeleton-point
(point)))
418 (when skeleton-modified
(pop skeleton-il
)))
420 (unless skeleton-modified
(pop skeleton-il
)))
422 (push (point) skeleton-positions
))
423 ((eq 'quote
(car-safe element
))
424 (eval (nth 1 element
)))
425 ((and (consp element
)
426 (or (stringp (car element
)) (listp (car element
))))
427 ;; Don't forget: `symbolp' is also true for nil.
428 (if (symbolp (car-safe (car element
)))
429 (while (and (skeleton-internal-list element nil t
)
430 ;; If the interactor is nil, don't infinite loop.
432 (setq literal
(car element
))
434 (skeleton-internal-list element
(car literal
))
435 (setq literal
(cdr literal
)))))
437 (t (skeleton-internal-1 (eval element
) t recursive
))))
439 ;; Maybe belongs into simple.el or elsewhere
441 ;; (define-skeleton local-variables-section
442 ;; "Insert a local variables section. Use current comment syntax if any."
443 ;; (completing-read "Mode: " obarray
445 ;; (if (commandp symbol)
446 ;; (string-match "-mode$" (symbol-name symbol))))
449 ;; (if (re-search-forward page-delimiter nil t)
450 ;; (error "Not on last page")))
451 ;; comment-start "Local Variables:" comment-end \n
452 ;; comment-start "mode: " str
453 ;; & -5 | '(kill-line 0) & -1 | comment-end \n
454 ;; ( (completing-read (format "Variable, %s: " skeleton-subprompt)
457 ;; (or (eq symbol 'eval)
458 ;; (custom-variable-p symbol)))
460 ;; comment-start str ": "
461 ;; (read-from-minibuffer "Expression: " nil read-expression-map nil
462 ;; 'read-expression-history) | _
465 ;; comment-start "End:" comment-end \n)
467 ;; Variables and command for automatically inserting pairs like () or "".
469 (defvar skeleton-pair nil
470 "If this is nil pairing is turned off, no matter what else is set.
471 Otherwise modes with `skeleton-pair-insert-maybe' on some keys
472 will attempt to insert pairs of matching characters.")
475 (defvar skeleton-pair-on-word nil
476 "If this is nil, paired insertion is inhibited before or inside a word.")
479 (defvar skeleton-pair-filter-function
(lambda () nil
)
480 "Attempt paired insertion if this function returns nil, before inserting.
481 This allows for context-sensitive checking whether pairing is appropriate.")
484 (defvar skeleton-pair-alist
()
485 "An override alist of pairing partners matched against `last-command-event'.
486 Each alist element, which looks like (ELEMENT ...), is passed to
487 `skeleton-insert' with no interactor. Variable `str' does nothing.
489 Elements might be (?\\=` ?\\=` _ \"\\='\\='\"), (?\\( ? _ \" )\") or (?{ \\n > _ \\n ?} >).")
491 (defvar skeleton-pair-default-alist
'((?\
( _ ?\
)) (?\
))
499 (defun skeleton-pair-insert-maybe (arg)
500 "Insert the character you type ARG times.
502 With no ARG, if `skeleton-pair' is non-nil, pairing can occur. If the region
503 is visible the pair is wrapped around it depending on `skeleton-autowrap'.
504 Else, if `skeleton-pair-on-word' is non-nil or we are not before or inside a
505 word, and if `skeleton-pair-filter-function' returns nil, pairing is performed.
506 Pairing is also prohibited if we are right after a quoting character
509 If a match is found in `skeleton-pair-alist', that is inserted, else
510 the defaults are used. These are (), [], {}, <> and (grave
511 accent, apostrophe) for the paired ones, and the same character
512 twice for the others."
514 (if (or arg
(not skeleton-pair
))
515 (self-insert-command (prefix-numeric-value arg
))
516 (let* ((mark (and skeleton-autowrap
517 (or (eq last-command
'mouse-drag-region
)
518 (and transient-mark-mode mark-active
))))
519 (char last-command-event
)
520 (skeleton (or (assq char skeleton-pair-alist
)
521 (assq char skeleton-pair-default-alist
)
523 (if (or (memq (char-syntax (preceding-char)) '(?
\\ ?
/))
526 (if (not skeleton-pair-on-word
) (looking-at "\\w"))
527 (funcall skeleton-pair-filter-function
))))
528 (self-insert-command (prefix-numeric-value arg
))
529 ;; Newlines not desirable for inserting pairs. See bug#16138.
530 (let ((skeleton-end-newline nil
))
531 (skeleton-insert (cons nil skeleton
) (if mark -
1)))))))
534 ;; A more serious example can be found in sh-script.el
535 ;; (defun mirror-mode ()
536 ;; "This major mode is an amusing little example of paired insertion.
537 ;;All printable characters do a paired self insert, while the other commands
540 ;; (kill-all-local-variables)
541 ;; (make-local-variable 'skeleton-pair)
542 ;; (make-local-variable 'skeleton-pair-on-word)
543 ;; (make-local-variable 'skeleton-pair-filter-function)
544 ;; (make-local-variable 'skeleton-pair-alist)
545 ;; (setq major-mode 'mirror-mode
546 ;; mode-name "Mirror"
547 ;; skeleton-pair-on-word t
548 ;; ;; in the middle column insert one or none if odd window-width
549 ;; skeleton-pair-filter-function (lambda ()
550 ;; (if (>= (current-column)
551 ;; (/ (window-width) 2))
552 ;; ;; insert both on next line
554 ;; ;; insert one or both?
555 ;; (= (* 2 (1+ (current-column)))
557 ;; ;; mirror these the other way round as well
558 ;; skeleton-pair-alist '((?) _ ?()
566 ;; ;; in this mode we exceptionally ignore the user, else it's no fun
568 ;; (let ((map (make-vector 256 'skeleton-pair-insert-maybe))
570 ;; (use-local-map `(keymap ,map))
573 ;; (aset map (+ i 128) nil)
575 ;; (run-mode-hooks 'mirror-mode-hook))
579 ;;; skeleton.el ends here