skeleton.el 22.5 KB
Newer Older
Stefan Monnier's avatar
Stefan Monnier committed
1
;;; skeleton.el --- Lisp language extension for writing statement skeletons -*- coding: utf-8 -*-
Erik Naggum's avatar
Erik Naggum committed
2

3
;; Copyright (C) 1993-1996, 2001-2014 Free Software Foundation, Inc.
Richard M. Stallman's avatar
Richard M. Stallman committed
4

Karl Heuer's avatar
Karl Heuer committed
5
;; Author: Daniel Pfeiffer <occitan@esperanto.org>
6
;; Maintainer: emacs-devel@gnu.org
Karl Heuer's avatar
Karl Heuer committed
7
;; Keywords: extensions, abbrev, languages, tools
Richard M. Stallman's avatar
Richard M. Stallman committed
8 9 10

;; This file is part of GNU Emacs.

11
;; GNU Emacs is free software: you can redistribute it and/or modify
Richard M. Stallman's avatar
Richard M. Stallman committed
12
;; it under the terms of the GNU General Public License as published by
13 14
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
Richard M. Stallman's avatar
Richard M. Stallman committed
15 16 17 18 19 20 21

;; GNU Emacs is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.

;; You should have received a copy of the GNU General Public License
22
;; along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
Richard M. Stallman's avatar
Richard M. Stallman committed
23 24 25

;;; Commentary:

Karl Heuer's avatar
Karl Heuer committed
26
;; A very concise language extension for writing structured statement
Richard M. Stallman's avatar
Richard M. Stallman committed
27 28 29 30 31 32 33
;; skeleton insertion commands for programming language modes.  This
;; originated in shell-script mode and was applied to ada-mode's
;; commands which shrunk to one third.  And these commands are now
;; user configurable.

;;; Code:

34 35
(eval-when-compile (require 'cl-lib))

Karl Heuer's avatar
Karl Heuer committed
36
;; page 1:	statement skeleton language definition & interpreter
Richard M. Stallman's avatar
Richard M. Stallman committed
37 38 39 40
;; page 2:	paired insertion
;; page 3:	mirror-mode, an example for setting up paired insertion


41
(defvar skeleton-transformation-function 'identity
42
  "If non-nil, function applied to literal strings before they are inserted.
Richard M. Stallman's avatar
Richard M. Stallman committed
43 44 45
It should take strings and characters and return them transformed, or nil
which means no transformation.
Typical examples might be `upcase' or `capitalize'.")
46
(defvaralias 'skeleton-transformation 'skeleton-transformation-function)
Richard M. Stallman's avatar
Richard M. Stallman committed
47 48

; this should be a fourth argument to defvar
49
(put 'skeleton-transformation-function 'variable-interactive
Richard M. Stallman's avatar
Richard M. Stallman committed
50 51 52
     "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 58 59 60 61 62
explicit ARG, then the ARG defaults to -1, i.e. wrapping around the visible
region.

We will probably delete this variable in a future Emacs version
unless we get a substantial number of complaints about the auto-wrap
feature.")
Richard M. Stallman's avatar
Richard M. Stallman committed
63

64 65 66 67
(defvar skeleton-end-newline t
  "If non-nil, make sure that the skeleton inserted ends with a newline.
This just influences the way the default `skeleton-end-hook' behaves.")

68 69
(defvar skeleton-end-hook
  (lambda ()
70
    (or (eolp) (not skeleton-end-newline) (newline-and-indent)))
71
  "Hook called at end of skeleton but before going to point of interest.
72 73
By default this moves out anything following to next line,
  unless `skeleton-end-newline' is set to nil.
74 75 76
The variables `v1' and `v2' are still set when calling this.")


Karl Heuer's avatar
Karl Heuer committed
77
;;;###autoload
78
(defvar skeleton-filter-function 'identity
79
  "Function for transforming a skeleton proxy's aliases' variable value.")
80
(defvaralias 'skeleton-filter 'skeleton-filter-function)
Karl Heuer's avatar
Karl Heuer committed
81

82
(defvar skeleton-untabify nil		; bug#12223
83
  "When non-nil untabifies when deleting backwards with element -ARG.")
Karl Heuer's avatar
Karl Heuer committed
84

85
(defvar skeleton-newline-indent-rigidly nil
86
  "When non-nil, indent rigidly under current line for element `\\n'.
87
Else use mode's `indent-line-function'.")
Karl Heuer's avatar
Karl Heuer committed
88

89
(defvar-local skeleton-further-elements ()
Karl Heuer's avatar
Karl Heuer committed
90 91 92 93 94
  "A buffer-local varlist (see `let') of mode specific skeleton elements.
These variables are bound while interpreting a skeleton.  Their value may
in turn be any valid skeleton element if they are themselves to be used as
skeleton elements.")

Richard M. Stallman's avatar
Richard M. Stallman committed
95 96 97
(defvar skeleton-subprompt
  (substitute-command-keys
   "RET, \\<minibuffer-local-map>\\[abort-recursive-edit] or \\[help-command]")
98
  "Replacement for %s in prompts of recursive subskeletons.")
Karl Heuer's avatar
Karl Heuer committed
99

Richard M. Stallman's avatar
Richard M. Stallman committed
100 101

(defvar skeleton-debug nil
102
  "If non-nil `define-skeleton' will override previous definition.")
Richard M. Stallman's avatar
Richard M. Stallman committed
103

104 105 106 107
(defvar skeleton-positions nil
  "List of positions marked with @, after skeleton insertion.
The list describes the most recent skeleton insertion, and its elements
are integer buffer positions in the reverse order of the insertion order.")
108

109
;; reduce the number of compiler warnings
110
(defvar skeleton-il)
111 112 113
(defvar skeleton-modified)
(defvar skeleton-point)
(defvar skeleton-regions)
Richard M. Stallman's avatar
Richard M. Stallman committed
114

115 116 117 118
(def-edebug-spec skeleton-edebug-spec
  ([&or null stringp (stringp &rest stringp) [[&not atom] def-form]]
   &rest &or "n" "_" "-" ">" "@" "&" "!" "resume:"
   ("quote" def-form) skeleton-edebug-spec def-form))
Richard M. Stallman's avatar
Richard M. Stallman committed
119
;;;###autoload
Karl Heuer's avatar
Karl Heuer committed
120
(defmacro define-skeleton (command documentation &rest skeleton)
Richard M. Stallman's avatar
Richard M. Stallman committed
121
  "Define a user-configurable COMMAND that enters a statement skeleton.
122 123
DOCUMENTATION is that of the command.
SKELETON is as defined under `skeleton-insert'."
124
  (declare (doc-string 2) (debug (&define name stringp skeleton-edebug-spec)))
Richard M. Stallman's avatar
Richard M. Stallman committed
125
  (if skeleton-debug
Karl Heuer's avatar
Karl Heuer committed
126
      (set command skeleton))
127
  `(progn
128 129 130
     ;; Tell self-insert-command that this function, if called by an
     ;; abbrev, should cause the self-insert to be skipped.
     (put ',command 'no-self-insert t)
131 132
     (defun ,command (&optional str arg)
       ,(concat documentation
133
		(if (string-match "\n\\'" documentation)
134 135 136 137 138 139 140 141
		    "" "\n")
		"\n"
  "This is a skeleton command (see `skeleton-insert').
Normally the skeleton text is inserted at point, with nothing \"inside\".
If there is a highlighted region, the skeleton text is wrapped
around the region text.

A prefix argument ARG says to wrap the skeleton around the next ARG words.
142
A prefix argument of -1 says to wrap around region, even if not highlighted.
143
A prefix argument of zero says to wrap around zero words---that is, nothing.
144
This is a way of overriding the use of a highlighted region.")
145 146
       (interactive "*P\nP")
       (skeleton-proxy-new ',skeleton str arg))))
Karl Heuer's avatar
Karl Heuer committed
147

148 149
;;;###autoload
(defun skeleton-proxy-new (skeleton &optional str arg)
150
  "Insert SKELETON.
151 152 153 154 155
Prefix ARG allows wrapping around words or regions (see `skeleton-insert').
If no ARG was given, but the region is visible, ARG defaults to -1 depending
on `skeleton-autowrap'.  An ARG of  M-0  will prevent this just for once.
This command can also be an abbrev expansion (3rd and 4th columns in
\\[edit-abbrevs]  buffer: \"\"  command-name).
Karl Heuer's avatar
Karl Heuer committed
156

157
Optional second argument STR may also be a string which will be the value
158
of `str' whereas the skeleton's interactor is then ignored."
159
  (skeleton-insert (funcall skeleton-filter-function skeleton)
160 161 162 163 164 165 166
		   ;; Pretend  C-x a e  passed its prefix arg to us
		   (if (or arg current-prefix-arg)
		       (prefix-numeric-value (or arg
						 current-prefix-arg))
		     (and skeleton-autowrap
			  (or (eq last-command 'mouse-drag-region)
			      (and transient-mark-mode mark-active))
167 168 169 170 171 172
			  ;; Deactivate the mark, in case one of the
			  ;; elements of the skeleton is sensitive
			  ;; to such situations (e.g. it is itself a
			  ;; skeleton).
			  (progn (deactivate-mark)
				 -1)))
173 174 175 176 177
		   (if (stringp str)
		       str))
  ;; Return non-nil to tell expand-abbrev that expansion has happened.
  ;; Otherwise the no-self-insert is ignored.
  t)
Richard M. Stallman's avatar
Richard M. Stallman committed
178 179

;;;###autoload
180
(defun skeleton-insert (skeleton &optional regions str)
Karl Heuer's avatar
Karl Heuer committed
181
  "Insert the complex statement skeleton SKELETON describes very concisely.
Richard M. Stallman's avatar
Richard M. Stallman committed
182

183 184 185
With optional second argument REGIONS, wrap first interesting point
\(`_') in skeleton around next REGIONS words, if REGIONS is positive.
If REGIONS is negative, wrap REGIONS preceding interregions into first
Juanma Barranquero's avatar
Juanma Barranquero committed
186
REGIONS interesting positions (successive `_'s) in skeleton.
Karl Heuer's avatar
Karl Heuer committed
187

188 189 190 191 192 193 194 195
An interregion is the stretch of text between two contiguous marked
points.  If you marked A B C [] (where [] is the cursor) in
alphabetical order, the 3 interregions are simply the last 3 regions.
But if you marked B A [] C, the interregions are B-A, A-[], []-C.

The optional third argument STR, if specified, is the value for the
variable `str' within the skeleton.  When this is non-nil, the
interactor gets ignored, and this should be a valid skeleton element.
196

Karl Heuer's avatar
Karl Heuer committed
197 198
SKELETON is made up as (INTERACTOR ELEMENT ...).  INTERACTOR may be nil if
not needed, a prompt-string or an expression for complex read functions.
Richard M. Stallman's avatar
Richard M. Stallman committed
199 200

If ELEMENT is a string or a character it gets inserted (see also
201
`skeleton-transformation-function').  Other possibilities are:
Richard M. Stallman's avatar
Richard M. Stallman committed
202

203 204 205
	\\n	go to next line and indent according to mode, unless
                this is the first/last element of a skeleton and point
                is at bol/eol
Stefan Monnier's avatar
Stefan Monnier committed
206
	_	interesting point, interregion here
207 208
	-	interesting point, no interregion interaction, overrides
		interesting point set by _
Karl Heuer's avatar
Karl Heuer committed
209
	>	indent line (or interregion if > _) according to major mode
210
	@	add position to `skeleton-positions'
211 212
	&	do next ELEMENT if previous moved point
	|	do next ELEMENT if previous didn't move point
Juanma Barranquero's avatar
Juanma Barranquero committed
213
	-NUM	delete NUM preceding characters (see `skeleton-untabify')
Richard M. Stallman's avatar
Richard M. Stallman committed
214 215 216
	resume:	skipped, continue here if quit is signaled
	nil	skipped

217 218
After termination, point will be positioned at the last occurrence of -
or at the first occurrence of _ or at the end of the inserted text.
Stefan Monnier's avatar
Stefan Monnier committed
219

220 221
Note that \\n as the last element of the skeleton only inserts a
newline if not at eol.  If you want to unconditionally insert a newline
222 223
at the end of the skeleton, use \"\\n\" instead.  Likewise with \\n
as the first element when at bol.
224

Juanma Barranquero's avatar
Juanma Barranquero committed
225 226 227 228 229 230 231 232
Further elements can be defined via `skeleton-further-elements'.
ELEMENT may itself be a SKELETON with an INTERACTOR.  The user is prompted
repeatedly for different inputs.  The SKELETON is processed as often as
the user enters a non-empty string.  \\[keyboard-quit] terminates skeleton insertion, but
continues after `resume:' and positions at `_' if any.  If INTERACTOR in
such a subskeleton is a prompt-string which contains a \".. %s ..\" it is
formatted with `skeleton-subprompt'.  Such an INTERACTOR may also be a list
of strings with the subskeleton being repeated once for each string.
Richard M. Stallman's avatar
Richard M. Stallman committed
233

234
Quoted Lisp expressions are evaluated for their side-effects.
235
Other Lisp expressions are evaluated and the value treated as above.
236
Note that expressions may not return t since this implies an
Karl Heuer's avatar
Karl Heuer committed
237 238 239
endless loop.  Modes can define other symbols by locally setting them
to any valid skeleton element.  The following local variables are
available:
Richard M. Stallman's avatar
Richard M. Stallman committed
240

Karl Heuer's avatar
Karl Heuer committed
241
	str	first time: read a string according to INTERACTOR
Richard M. Stallman's avatar
Richard M. Stallman committed
242
		then: insert previously read string once more
243
	help	help-form during interaction with the user or nil
244
	input	initial input (string or cons with index) while reading str
245
	v1, v2	local variables for memorizing anything you want
246 247

When done with skeleton, but before going back to `_'-point call
248
`skeleton-end-hook' if that is non-nil."
249 250 251 252
  (let ((skeleton-regions regions))
    (and skeleton-regions
	 (setq skeleton-regions
	       (if (> skeleton-regions 0)
253
		   (list (copy-marker (point) t)
254 255 256 257 258
			 (save-excursion (forward-word skeleton-regions)
					 (point-marker)))
		 (setq skeleton-regions (- skeleton-regions))
		 ;; copy skeleton-regions - 1 elements from `mark-ring'
		 (let ((l1 (cons (mark-marker) mark-ring))
259
		       (l2 (list (copy-marker (point) t))))
260
		   (while (and l1 (> skeleton-regions 0))
261 262
		     (push (copy-marker (pop l1) t) l2)
		     (setq skeleton-regions (1- skeleton-regions)))
263 264 265 266 267 268 269
		   (sort l2 '<))))
	 (goto-char (car skeleton-regions))
	 (setq skeleton-regions (cdr skeleton-regions)))
    (let ((beg (point))
	  skeleton-modified skeleton-point resume: help input v1 v2)
      (setq skeleton-positions nil)
      (unwind-protect
270 271 272 273
	  (cl-progv
              (mapcar #'car skeleton-further-elements)
              (mapcar (lambda (x) (eval (cadr x))) skeleton-further-elements)
            (skeleton-internal-list skeleton str))
274 275 276 277 278 279 280 281 282
	(run-hooks 'skeleton-end-hook)
	(sit-for 0)
	(or (pos-visible-in-window-p beg)
	    (progn
	      (goto-char beg)
	      (recenter 0)))
	(if skeleton-point
	    (goto-char skeleton-point))))))

283
(defun skeleton-read (prompt &optional initial-input recursive)
284
  "Function for reading a string from the minibuffer within skeletons.
285 286 287

PROMPT must be a string or a form that evaluates to a string.
It may contain a `%s' which will be replaced by `skeleton-subprompt'.
288 289
If non-nil second arg INITIAL-INPUT or variable `input' is a string or
cons with index to insert before reading.  If third arg RECURSIVE is non-nil
290 291 292
i.e. we are handling the iterator of a subskeleton, returns empty string if
user didn't modify input.
While reading, the value of `minibuffer-help-form' is variable `help' if that
293
is non-nil or a default string."
294 295
  (let ((minibuffer-help-form (or (if (boundp 'help) (symbol-value 'help))
				  (if recursive "\
Richard M. Stallman's avatar
Richard M. Stallman committed
296 297 298 299 300 301 302
As long as you provide input you will insert another subskeleton.

If you enter the empty string, the loop inserting subskeletons is
left, and the current one is removed as far as it has been entered.

If you quit, the current subskeleton is removed as far as it has been
entered.  No more of the skeleton will be inserted, except maybe for a
Karl Heuer's avatar
Karl Heuer committed
303
syntactically necessary termination."
304
				    "\
Karl Heuer's avatar
Karl Heuer committed
305
You are inserting a skeleton.  Standard text gets inserted into the buffer
306 307 308 309
automatically, and you are prompted to fill in the variable parts.")))
	(eolp (eolp)))
    ;; since Emacs doesn't show main window's cursor, do something noticeable
    (or eolp
310 311 312 313
        ;; We used open-line before, but that can do a lot more than we want,
	;; since it runs self-insert-command.  E.g. it may remove spaces
	;; before point.
        (save-excursion (insert "\n")))
314
    (unwind-protect
315 316 317 318 319 320
	(setq prompt (if (stringp prompt)
			 (read-string (format prompt skeleton-subprompt)
				      (setq initial-input
					    (or initial-input
						(symbol-value 'input))))
		       (eval prompt)))
321 322
      (or eolp
	  (delete-char 1))))
323
  (if (and recursive
324 325 326 327
	   (or (null prompt)
	       (string= prompt "")
	       (equal prompt initial-input)
	       (equal prompt (car-safe initial-input))))
Richard M. Stallman's avatar
Richard M. Stallman committed
328
      (signal 'quit t)
329
    prompt))
Richard M. Stallman's avatar
Richard M. Stallman committed
330

331
(defun skeleton-internal-list (skeleton-il &optional str recursive)
332
  (let* ((start (line-beginning-position))
Karl Heuer's avatar
Karl Heuer committed
333
	 (column (current-column))
334
	 (line (buffer-substring start (line-end-position)))
Karl Heuer's avatar
Karl Heuer committed
335
	 opoint)
336
    (or str
337 338 339
	(setq str `(setq str
			 (skeleton-read ',(car skeleton-il) nil ,recursive))))
    (when (and (eq (cadr skeleton-il) '\n) (not recursive)
340
	       (save-excursion (skip-chars-backward " \t") (bolp)))
341
      (setq skeleton-il (cons nil (cons '> (cddr skeleton-il)))))
342
    (while (setq skeleton-modified (eq opoint (point))
343
		 opoint (point)
344
		 skeleton-il (cdr skeleton-il))
345
      (condition-case quit
346
	  (skeleton-internal-1 (car skeleton-il) nil recursive)
347 348
	(quit
	 (if (eq (cdr quit) 'recursive)
349
	     (setq recursive 'quit
350
		   skeleton-il (memq 'resume: skeleton-il))
351 352
	   ;; Remove the subskeleton as far as it has been shown
	   ;; the subskeleton shouldn't have deleted outside current line.
353
	   (end-of-line)
354 355 356 357
	   (delete-region start (point))
	   (insert line)
	   (move-to-column column)
	   (if (cdr quit)
358
	       (setq skeleton-il ()
359 360 361 362 363 364
		     recursive nil)
	     (signal 'quit 'recursive)))))))
  ;; maybe continue loop or go on to next outer resume: section
  (if (eq recursive 'quit)
      (signal 'quit 'recursive)
    recursive))
Karl Heuer's avatar
Karl Heuer committed
365

366

367
(defun skeleton-internal-1 (element &optional literal recursive)
368
  (cond
369
   ((or (integerp element) (stringp element))
370 371 372 373
    (if (and (integerp element)		; -num
	     (< element 0))
	(if skeleton-untabify
	    (backward-delete-char-untabify (- element))
374
	  (delete-char element))
375
      (insert (if (not literal)
376
		  (funcall skeleton-transformation-function element)
377 378 379 380
		element))))
   ((or (eq element '\n)			; actually (eq '\n 'n)
	;; The sequence `> \n' is handled specially so as to indent the first
	;; line after inserting the newline (to get the proper indentation).
381
	(and (eq element '>) (eq (nth 1 skeleton-il) '\n) (pop skeleton-il)))
382 383
    (let ((pos (if (eq element '>) (point))))
      (cond
384
       ((and skeleton-regions (eq (nth 1 skeleton-il) '_))
385
	(or (eolp) (insert "\n"))
386 387 388 389
	(if pos (save-excursion (goto-char pos) (indent-according-to-mode)))
	(indent-region (line-beginning-position)
		       (car skeleton-regions) nil))
       ;; \n as last element only inserts \n if not at eol.
390
       ((and (null (cdr skeleton-il)) (not recursive) (eolp))
391 392 393
	(if pos (indent-according-to-mode)))
       (skeleton-newline-indent-rigidly
	(let ((pt (point)))
394
          (insert "\n")
395 396 397 398 399
	  (indent-to (save-excursion
		       (goto-char pt)
		       (if pos (indent-according-to-mode))
		       (current-indentation)))))
       (t (if pos (reindent-then-newline-and-indent)
400
	    (insert "\n")
401 402
	    (indent-according-to-mode))))))
   ((eq element '>)
403
    (if (and skeleton-regions (eq (nth 1 skeleton-il) '_))
404 405 406 407 408 409 410 411
	(indent-region (line-beginning-position)
		       (car skeleton-regions) nil)
      (indent-according-to-mode)))
   ((eq element '_)
    (if skeleton-regions
	(progn
	  (goto-char (pop skeleton-regions))
	  (and (<= (current-column) (current-indentation))
412
	       (eq (nth 1 skeleton-il) '\n)
413 414 415 416 417 418
	       (end-of-line 0)))
      (or skeleton-point
	  (setq skeleton-point (point)))))
   ((eq element '-)
    (setq skeleton-point (point)))
   ((eq element '&)
419
    (when skeleton-modified (pop skeleton-il)))
420
   ((eq element '|)
421
    (unless skeleton-modified (pop skeleton-il)))
422 423 424 425
   ((eq element '@)
    (push (point) skeleton-positions))
   ((eq 'quote (car-safe element))
    (eval (nth 1 element)))
426 427 428
   ((and (consp element)
	 (or (stringp (car element)) (listp (car element))))
    ;; Don't forget: `symbolp' is also true for nil.
429
    (if (symbolp (car-safe (car element)))
430 431 432
	(while (and (skeleton-internal-list element nil t)
		    ;; If the interactor is nil, don't infinite loop.
		    (car element)))
433 434 435 436 437
      (setq literal (car element))
      (while literal
	(skeleton-internal-list element (car literal))
	(setq literal (cdr literal)))))
   ((null element))
438
   (t (skeleton-internal-1 (eval element) t recursive))))
439

Karl Heuer's avatar
Karl Heuer committed
440
;; Maybe belongs into simple.el or elsewhere
441 442
;; ;;;###autoload
;; (define-skeleton local-variables-section
443 444 445 446 447 448 449 450
;;  "Insert a local variables section.  Use current comment syntax if any."
;;  (completing-read "Mode: " obarray
;;		   (lambda (symbol)
;;		     (if (commandp symbol)
;;			 (string-match "-mode$" (symbol-name symbol))))
;;		   t)
;;  '(save-excursion
;;     (if (re-search-forward page-delimiter nil t)
451
;;	 (error "Not on last page")))
452 453 454 455 456 457 458
;;  comment-start "Local Variables:" comment-end \n
;;  comment-start "mode: " str
;;  & -5 | '(kill-line 0) & -1 | comment-end \n
;;  ( (completing-read (format "Variable, %s: " skeleton-subprompt)
;;		     obarray
;;		     (lambda (symbol)
;;		       (or (eq symbol 'eval)
459
;;			   (custom-variable-p symbol)))
460 461 462 463 464 465
;;		     t)
;;    comment-start str ": "
;;    (read-from-minibuffer "Expression: " nil read-expression-map nil
;;			  'read-expression-history) | _
;;    comment-end \n)
;;  resume:
466
;;  comment-start "End:" comment-end \n)
Richard M. Stallman's avatar
Richard M. Stallman committed
467

468
;; Variables and command for automatically inserting pairs like () or "".
Richard M. Stallman's avatar
Richard M. Stallman committed
469

470
(defvar skeleton-pair nil
471
  "If this is nil pairing is turned off, no matter what else is set.
472 473
Otherwise modes with `skeleton-pair-insert-maybe' on some keys
will attempt to insert pairs of matching characters.")
Richard M. Stallman's avatar
Richard M. Stallman committed
474 475


476
(defvar skeleton-pair-on-word nil
477
  "If this is nil, paired insertion is inhibited before or inside a word.")
Richard M. Stallman's avatar
Richard M. Stallman committed
478 479


480
(defvar skeleton-pair-filter-function (lambda () nil)
481
  "Attempt paired insertion if this function returns nil, before inserting.
Richard M. Stallman's avatar
Richard M. Stallman committed
482 483 484
This allows for context-sensitive checking whether pairing is appropriate.")


485
(defvar skeleton-pair-alist ()
486
  "An override alist of pairing partners matched against `last-command-event'.
487 488
Each alist element, which looks like (ELEMENT ...), is passed to
`skeleton-insert' with no interactor.  Variable `str' does nothing.
Richard M. Stallman's avatar
Richard M. Stallman committed
489

Karl Heuer's avatar
Karl Heuer committed
490
Elements might be (?` ?` _ \"''\"), (?\\( ?  _ \" )\") or (?{ \\n > _ \\n ?} >).")
Richard M. Stallman's avatar
Richard M. Stallman committed
491

492 493 494 495
(defvar skeleton-pair-default-alist '((?( _ ?)) (?\))
				      (?[ _ ?]) (?\])
				      (?{ _ ?}) (?\})
				      (?< _ ?>) (?\>)
Stefan Monnier's avatar
Stefan Monnier committed
496
				      (?« _ ?») (?\»)
497
				      (?` _ ?')))
Richard M. Stallman's avatar
Richard M. Stallman committed
498 499

;;;###autoload
500
(defun skeleton-pair-insert-maybe (arg)
Richard M. Stallman's avatar
Richard M. Stallman committed
501 502
  "Insert the character you type ARG times.

503 504 505
With no ARG, if `skeleton-pair' is non-nil, pairing can occur.  If the region
is visible the pair is wrapped around it depending on `skeleton-autowrap'.
Else, if `skeleton-pair-on-word' is non-nil or we are not before or inside a
506
word, and if `skeleton-pair-filter-function' returns nil, pairing is performed.
507 508
Pairing is also prohibited if we are right after a quoting character
such as backslash.
Richard M. Stallman's avatar
Richard M. Stallman committed
509

510
If a match is found in `skeleton-pair-alist', that is inserted, else
Richard M. Stallman's avatar
Richard M. Stallman committed
511 512 513
the defaults are used.  These are (), [], {}, <> and `' for the
symmetrical ones, and the same character twice for the others."
  (interactive "*P")
514 515 516 517 518
  (if (or arg (not skeleton-pair))
      (self-insert-command (prefix-numeric-value arg))
    (let* ((mark (and skeleton-autowrap
		      (or (eq last-command 'mouse-drag-region)
			  (and transient-mark-mode mark-active))))
519
	   (char last-command-event)
520 521 522 523 524 525 526
	   (skeleton (or (assq char skeleton-pair-alist)
			 (assq char skeleton-pair-default-alist)
			 `(,char _ ,char))))
      (if (or (memq (char-syntax (preceding-char)) '(?\\ ?/))
	      (and (not mark)
		   (or overwrite-mode
		       (if (not skeleton-pair-on-word) (looking-at "\\w"))
527
		       (funcall skeleton-pair-filter-function))))
528
	  (self-insert-command (prefix-numeric-value arg))
529 530 531
	;; Newlines not desirable for inserting pairs.  See bug#16138.
	(let ((skeleton-end-newline nil))
	  (skeleton-insert (cons nil skeleton) (if mark -1)))))))
Richard M. Stallman's avatar
Richard M. Stallman committed
532 533


534
;; A more serious example can be found in sh-script.el
Stefan Monnier's avatar
Stefan Monnier committed
535
;; (defun mirror-mode ()
536 537 538 539 540
;;  "This major mode is an amusing little example of paired insertion.
;;All printable characters do a paired self insert, while the other commands
;;work normally."
;;  (interactive)
;;  (kill-all-local-variables)
541 542
;;  (make-local-variable 'skeleton-pair)
;;  (make-local-variable 'skeleton-pair-on-word)
543
;;  (make-local-variable 'skeleton-pair-filter-function)
544
;;  (make-local-variable 'skeleton-pair-alist)
545 546
;;  (setq major-mode 'mirror-mode
;;	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 551 552 553 554 555 556
;;			       (if (>= (current-column)
;;				       (/ (window-width) 2))
;;				   ;; insert both on next line
;;				   (next-line 1)
;;				 ;; insert one or both?
;;				 (= (* 2 (1+ (current-column)))
;;				    (window-width))))
557
;;	;; mirror these the other way round as well
558 559 560 561 562 563 564 565
;;	skeleton-pair-alist '((?) _ ?()
;;			      (?] _ ?[)
;;			      (?} _ ?{)
;;			      (?> _ ?<)
;;			      (?/ _ ?\\)
;;			      (?\\ _ ?/)
;;			      (?` ?` _ "''")
;;			      (?' ?' _ "``"))
566
;;	;; in this mode we exceptionally ignore the user, else it's no fun
567 568 569 570 571 572 573
;;	skeleton-pair t)
;;  (let ((map (make-vector 256 'skeleton-pair-insert-maybe))
;;	(i 0))
;;    (use-local-map `(keymap ,map))
;;    (while (< i ? )
;;      (aset map i nil)
;;      (aset map (+ i 128) nil)
574
;;      (setq i (1+ i))))
Lute Kamstra's avatar
Lute Kamstra committed
575
;;  (run-mode-hooks 'mirror-mode-hook))
Richard M. Stallman's avatar
Richard M. Stallman committed
576

Richard M. Stallman's avatar
Richard M. Stallman committed
577 578
(provide 'skeleton)

579
;;; skeleton.el ends here