Function: skeleton-insert
skeleton-insert is an autoloaded and byte-compiled function defined in
skeleton.el.gz.
Signature
(skeleton-insert SKELETON &optional REGIONS STR)
Documentation
Insert the complex statement skeleton SKELETON describes very concisely.
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
REGIONS interesting positions (successive _s) in skeleton.
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.
When done with skeleton, but before going back to _-point, add
a newline (unless skeleton-end-newline is nil) and run the hook
skeleton-end-hook.
SKELETON is made up as (INTERACTOR ELEMENT ...). INTERACTOR may be nil if not needed, a prompt-string or an expression for complex read functions.
If ELEMENT is a string or a character it gets inserted (see also
skeleton-transformation-function). Other possibilities are:
\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
_ interesting point, interregion here
- interesting point, no interregion interaction, overrides
interesting point set by _
> indent line (or interregion if > _) according to major mode
@ add position to skeleton-positions
& do next ELEMENT if previous moved point
| do next ELEMENT if previous didn't move point
-NUM delete NUM preceding characters (see skeleton-untabify)
resume: skipped, continue here if quit is signaled
nil skipped
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.
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 at the end of the skeleton, use "\\n" instead. Likewise with \n as the first element when at bol.
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. C-g (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.
Quoted Lisp expressions are evaluated for their side-effects. Other Lisp expressions are evaluated and the value treated as above. Note that expressions may not return t since this implies an endless loop. Modes can define other symbols by locally setting them to any valid skeleton element. The following local variables are available:
str first time: read a string according to INTERACTOR
then: insert previously read string once more
help help-form during interaction with the user or nil
input initial input (string or cons with index) while reading str
v1, v2 local variables for memorizing anything you want
Probably introduced at or before Emacs version 22.1.
Source Code
;; Defined in /usr/src/emacs/lisp/skeleton.el.gz
;;;###autoload
(defun skeleton-insert (skeleton &optional regions str)
"Insert the complex statement skeleton SKELETON describes very concisely.
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
REGIONS interesting positions (successive `_'s) in skeleton.
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.
When done with skeleton, but before going back to `_'-point, add
a newline (unless `skeleton-end-newline' is nil) and run the hook
`skeleton-end-hook'.
SKELETON is made up as (INTERACTOR ELEMENT ...). INTERACTOR may be nil if
not needed, a prompt-string or an expression for complex read functions.
If ELEMENT is a string or a character it gets inserted (see also
`skeleton-transformation-function'). Other possibilities are:
\\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
_ interesting point, interregion here
- interesting point, no interregion interaction, overrides
interesting point set by _
> indent line (or interregion if > _) according to major mode
@ add position to `skeleton-positions'
& do next ELEMENT if previous moved point
| do next ELEMENT if previous didn't move point
-NUM delete NUM preceding characters (see `skeleton-untabify')
resume: skipped, continue here if quit is signaled
nil skipped
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.
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
at the end of the skeleton, use \"\\n\" instead. Likewise with \\n
as the first element when at bol.
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.
Quoted Lisp expressions are evaluated for their side-effects.
Other Lisp expressions are evaluated and the value treated as above.
Note that expressions may not return t since this implies an
endless loop. Modes can define other symbols by locally setting them
to any valid skeleton element. The following local variables are
available:
str first time: read a string according to INTERACTOR
then: insert previously read string once more
help help-form during interaction with the user or nil
input initial input (string or cons with index) while reading str
v1, v2 local variables for memorizing anything you want"
(let ((skeleton-regions regions))
(and skeleton-regions
(setq skeleton-regions
(if (> skeleton-regions 0)
(list (copy-marker (point) t)
(save-excursion (forward-word-strictly
skeleton-regions)
(point-marker)))
(setq skeleton-regions (- skeleton-regions))
;; copy skeleton-regions - 1 elements from `mark-ring'
(let ((l1 (cons (mark-marker) mark-ring))
(l2 (list (copy-marker (point) t))))
(while (and l1 (> skeleton-regions 0))
(push (copy-marker (pop l1) t) l2)
(setq skeleton-regions (1- skeleton-regions)))
(sort l2 '<))))
(goto-char (car skeleton-regions))
(setq skeleton-regions (cdr skeleton-regions)))
(let ((beg (point))
skeleton-modified skeleton-point) ;; resume:
(with-suppressed-warnings ((lexical help input v1 v2))
(dlet (help input v1 v2)
(setq skeleton-positions nil)
(unwind-protect
(cl-progv
(mapcar #'car skeleton-further-elements)
(mapcar (lambda (x) (eval (cadr x) t)) skeleton-further-elements)
(skeleton-internal-list skeleton str))
(or (eolp) (not skeleton-end-newline) (newline-and-indent))
(run-hooks 'skeleton-end-hook)
(sit-for 0)
(or (not (eq (window-buffer) (current-buffer)))
(pos-visible-in-window-p beg)
(progn
(goto-char beg)
(recenter 0)))
(if skeleton-point
(goto-char skeleton-point))))))))