tempel
- Description
- Tempo templates/snippets with in-buffer field editing
- Latest
- tempel-1.3.tar (.sig), 2024-Dec-22, 110 KiB
- Maintainer
- Daniel Mendler <mail@daniel-mendler.de>
- Website
- https://github.com/minad/tempel
- Browse ELPA's repository
- CGit or Gitweb
- Badge
- Manual
- tempel
To install this package from Emacs, use package-install
or list-packages
.
Full description
Tempel is a tiny template package for Emacs, which uses the syntax of the Emacs
Tempo library. Tempo is an ancient temple of the church of Emacs. It is 30 years
old, but still in good shape since it successfully resisted change over the
decades. However it may look a bit dusty here and there. Therefore we present
Tempel, a new implementation of Tempo with inline expansion and integration with
recent Emacs facilities. Tempel takes advantage of the standard
completion-at-point-functions
mechanism which is used by Emacs for in-buffer
completion.
Table of Contents
1. Template expansion
Tempel comes with three commands for template expansion:
tempel-complete
completes a template name at point in the buffer and subsequently expands the template. If called non-interactively the function behaves like a Capf and can be added tocompletion-at-point-functions
. The Capf returns a list of templates names which are presented by the completion UI for selection.tempel-expand
expands an exactly matching template name at point in the buffer. If called non-interactively the function behaves like a Capf and can be added tocompletion-at-point-functions
. This Capf returns only the single exactly matching template name, such that no selection in the completion UI is possible.tempel-insert
selects a template by name viacompleting-read
and insert it into the current buffer.
For the commands tempel-complete
and tempel-expand
, you may want to give my
Corfu completion at point popup UI a try. After inserting the template you can
move between the visible template fields with the keys M-{
, M-}
or C-up/down
which are normally bound to forward/backward-paragraph
. Tempel temporarily
remaps these commands to tempel-next/previous
. As soon as you move before
(behind) the first (last) field, the fields are finalized. The key bindings are
defined in the tempel-map
keymap. I recommend that you inspect the tempel-map
and look at the provided key bindings. You can customize the key bindings there.
2. Configuration
The package is available on GNU ELPA and MELPA and can be installed with
package-install
. The following example configuration relies on use-package
. For
some ready-made templates check out the package tempel-collection. The
collection is not comprehensive yet, but will certainly grow thanks to
contributions.
;; Configure Tempel (use-package tempel ;; Require trigger prefix before template name when completing. ;; :custom ;; (tempel-trigger-prefix "<") :bind (("M-+" . tempel-complete) ;; Alternative tempel-expand ("M-*" . tempel-insert)) :init ;; Setup completion at point (defun tempel-setup-capf () ;; Add the Tempel Capf to `completion-at-point-functions'. ;; `tempel-expand' only triggers on exact matches. Alternatively use ;; `tempel-complete' if you want to see all matches, but then you ;; should also configure `tempel-trigger-prefix', such that Tempel ;; does not trigger too often when you don't expect it. NOTE: We add ;; `tempel-expand' *before* the main programming mode Capf, such ;; that it will be tried first. (setq-local completion-at-point-functions (cons #'tempel-expand completion-at-point-functions))) (add-hook 'conf-mode-hook 'tempel-setup-capf) (add-hook 'prog-mode-hook 'tempel-setup-capf) (add-hook 'text-mode-hook 'tempel-setup-capf) ;; Optionally make the Tempel templates available to Abbrev, ;; either locally or globally. `expand-abbrev' is bound to C-x '. ;; (add-hook 'prog-mode-hook #'tempel-abbrev-mode) ;; (global-tempel-abbrev-mode) ) ;; Optional: Add tempel-collection. ;; The package is young and doesn't have comprehensive coverage. (use-package tempel-collection) ;; Optional: Use the Corfu completion UI (use-package corfu :init (global-corfu-mode))
3. Template file format
The templates are defined in a Lisp data file configured by tempel-path
. Lisp
data files are files containing Lisp s-expressions (see lisp-data-mode
). By
default the file templates
in the user-emacs-directory
is used, e.g.,
~/.config/emacs/templates
. The templates are grouped by major mode with
an optional :when
condition. Each template is a list in the concise form of the
Emacs Tempo syntax. The first element of each list is the name of the template.
I recommend to use avoid special letters for the template names, since special
letters may carry meaning during completion filtering and as such make it harder
to select the desired template. Thus the name lett
is better than let*
. Behind
the name, the Tempo syntax elements follow.
In addition, each template may specify a :pre
and/or :post
key with a FORM that
is evaluated before the template is expanded or after it is finalized,
respectively. The :post
form is evaluated in the lexical scope of the template,
which means that it can access the template's named fields.
The following examples are written on a single line, but this is is of course not a requirement. Strings can even contain line breaks, which can be useful if you want to write complex templates.
;; ~/.config/emacs/templates fundamental-mode ;; Available everywhere (today (format-time-string "%Y-%m-%d")) prog-mode (fixme (if (derived-mode-p 'emacs-lisp-mode) ";; " comment-start) "FIXME ") (todo (if (derived-mode-p 'emacs-lisp-mode) ";; " comment-start) "TODO ") (bug (if (derived-mode-p 'emacs-lisp-mode) ";; " comment-start) "BUG ") (hack (if (derived-mode-p 'emacs-lisp-mode) ";; " comment-start) "HACK ") latex-mode (abstract "\\begin{abstract}\n" r> n> "\\end{abstract}") (align "\\begin{align}\n" r> n> "\\end{align}") (alignn "\\begin{align*}\n" r> n> "\\end{align*}") (gather "\\begin{gather}\n" r> n> "\\end{gather}") (gatherr "\\begin{gather*}\n" r> n> "\\end{gather*}") (appendix "\\begin{appendix}\n" r> n> "\\end{appendix}") (begin "\\begin{" (s env) "}" r> n> "\\end{" (s env) "}") (center "\\begin{center}\n" r> n> "\\end{center}") (displaymath "\\begin{displaymath}\n" r> n> "\\end{displaymath}") (document "\\begin{document}\n" r> n> "\\end{document}") (enumerate "\\begin{enumerate}\n\\item " r> n> "\\end{enumerate}") (equation "\\begin{equation}" r> n> "\\end{equation}") (flushleft "\\begin{flushleft}" r> n> "\\end{flushleft}") (flushright "\\begin{flushright}" r> n> "\\end{flushright}") (frac "\\frac{" p "}{" q "}") (fussypar "\\begin{fussypar}" r> n> "\\end{fussypar}") (itemize "\\begin{itemize}\n\\item " r> n> "\\end{itemize}") (letter "\\begin{letter}\n" r> n> "\\end{letter}") (math "\\begin{math}\n" r> n> "\\end{math}") (minipage "\\begin{minipage}[t]{0.5\linewidth}\n" r> n> "\\end{minipage}") (quotation "\\begin{quotation}\n" r> n> "\\end{quotation}") (quote "\\begin{quote}\n" r> n> "\\end{quote}") (sloppypar "\\begin{sloppypar}\n" r> n> "\\end{sloppypar}") (theindex "\\begin{theindex}\n" r> n> "\\end{theindex}") (trivlist "\\begin{trivlist}\n" r> n> "\\end{trivlist}") (verbatim "\\begin{verbatim}\n" r> n> "\\end{verbatim}") (verbatimm "\\begin{verbatim*}\n" r> n> "\\end{verbatim*}") (matrix (p (read-number "Rows: ") rows noinsert) (p (read-number "Cols: ") cols noinsert) "\\begin{" (p "pmatrix" type) "}" n (* (1- rows) (p " ") (* (1- cols) " & " (p " ")) "\\\\" n) (p " ") (* (1- cols) " & " (p " ")) n "\\end{" type "}") texinfo-mode (defmac "@defmac " p n> r> "@end defmac") (defun "@defun " p n> r> "@end defun") (defvar "@defvar " p n> r> "@end defvar") (example "@example " p n> r> "@end example") (lisp "@lisp " p n> r> "@end lisp") (bullet "@itemize @bullet{}" n> r> "@end itemize") (code "@code{" p "}") (var "@var{" p "}") lisp-mode emacs-lisp-mode ;; Specify multiple modes (lambda "(lambda (" p ")" n> r> ")") emacs-lisp-mode (autoload ";;;###autoload") (pt "(point)") (var "(defvar " p "\n \"" p "\")") (local "(defvar-local " p "\n \"" p "\")") (const "(defconst " p "\n \"" p "\")") (custom "(defcustom " p "\n \"" p "\"" n> ":type '" p ")") (face "(defface " p " '((t :inherit " p "))\n \"" p "\")") (group "(defgroup " p " nil\n \"" p "\"" n> ":group '" p n> ":prefix \"" p "-\")") (macro "(defmacro " p " (" p ")\n \"" p "\"" n> r> ")") (alias "(defalias '" p " '" p ")") (fun "(defun " p " (" p ")\n \"" p "\"" n> r> ")") (iflet "(if-let (" p ")" n> r> ")") (whenlet "(when-let (" p ")" n> r> ")") (whilelet "(while-let (" p ")" n> r> ")") (andlet "(and-let* (" p ")" n> r> ")") (cond "(cond" n "(" q "))" >) (pcase "(pcase " (p "scrutinee") n "(" q "))" >) (let "(let (" p ")" n> r> ")") (lett "(let* (" p ")" n> r> ")") (pcaselet "(pcase-let (" p ")" n> r> ")") (pcaselett "(pcase-let* (" p ")" n> r> ")") (rec "(letrec (" p ")" n> r> ")") (dotimes "(dotimes (" p ")" n> r> ")") (dolist "(dolist (" p ")" n> r> ")") (loop "(cl-loop for " p " in " p " do" n> r> ")") (command "(defun " p " (" p ")\n \"" p "\"" n> "(interactive" p ")" n> r> ")") (advice "(defun " (p "adv" name) " (&rest app)" n> p n> "(apply app))" n> "(advice-add #'" (p "fun") " " (p ":around") " #'" (s name) ")") (header ";;; " (file-name-nondirectory (or (buffer-file-name) (buffer-name))) " --- " p " -*- lexical-binding: t -*-" n ";;; Commentary:" n ";;; Code:" n n) (provide "(provide '" (file-name-base (or (buffer-file-name) (buffer-name))) ")" n ";;; " (file-name-nondirectory (or (buffer-file-name) (buffer-name))) " ends here" n) (package (i header) r n n (i provide)) eshell-mode (for "for " (p "i") " in " p " { " q " }") (while "while { " p " } { " q " }") (until "until { " p " } { " q " }") (if "if { " p " } { " q " }") (ife "if { " p " } { " p " } { " q " }") (unl "unless { " p " } { " q " }") (unle "unless { " p " } { " p " } { " q " }") text-mode (box "┌─" (make-string (length str) ?─) "─┐" n "│ " (s str) " │" n "└─" (make-string (length str) ?─) "─┘" n) (abox "+-" (make-string (length str) ?-) "-+" n "| " (s str) " |" n "+-" (make-string (length str) ?-) "-+" n) (cut "--8<---------------cut here---------------start------------->8---" n r n "--8<---------------cut here---------------end--------------->8---" n) (rot13 (p "plain text" text) n "----" n (rot13 text)) (calc (p "taylor(sin(x),x=0,3)" formula) n "----" n (format "%s" (calc-eval formula))) (table (p (read-number "Rows: ") rows noinsert) (p (read-number "Cols: ") cols noinsert) "| " (p " ") (* (1- cols) " | " (p " ")) " |" n "|" (* cols "----|") n (* rows "| " (p " ") (* (1- cols) " | " (p " ")) " |" n)) rst-mode (title (make-string (length title) ?=) n (p "Title: " title) n (make-string (length title) ?=) n) java-mode (class "public class " (p (file-name-base (or (buffer-file-name) (buffer-name)))) " {" n> r> n "}") c-mode :when (re-search-backward "^\\S-*$" (line-beginning-position) 'noerror) (inc "#include <" (p (concat (file-name-base (or (buffer-file-name) (buffer-name))) ".h")) ">") (incc "#include \"" (p (concat (file-name-base (or (buffer-file-name) (buffer-name))) ".h")) "\"") org-mode (caption "#+caption: ") (drawer ":" p ":" n r ":end:") (begin "#+begin_" (s name) n> r> n "#+end_" name) (quote "#+begin_quote" n> r> n "#+end_quote") (sidenote "#+begin_sidenote" n> r> n "#+end_sidenote") (marginnote "#+begin_marginnote" n> r> n "#+end_marginnote") (example "#+begin_example" n> r> n "#+end_example") (center "#+begin_center" n> r> n "#+end_center") (ascii "#+begin_export ascii" n> r> n "#+end_export") (html "#+begin_export html" n> r> n "#+end_export") (latex "#+begin_export latex" n> r> n "#+end_export") (comment "#+begin_comment" n> r> n "#+end_comment") (verse "#+begin_verse" n> r> n "#+end_verse") (src "#+begin_src " q n r n "#+end_src") (gnuplot "#+begin_src gnuplot :var data=" (p "table") " :file " (p "plot.png") n r n "#+end_src" :post (org-edit-src-code)) (elisp "#+begin_src emacs-lisp" n r n "#+end_src" :post (org-edit-src-code)) (inlsrc "src_" p "{" q "}") (title "#+title: " p n "#+author: Daniel Mendler" n "#+language: en") ;; Local Variables: ;; mode: lisp-data ;; outline-regexp: "[a-z]" ;; End:
4. Template syntax
All the Tempo syntax elements are fully supported. The syntax elements are
described in detail in the docstring of tempo-define-template
in tempo.el. We
document the important ones here:
- "string" Inserts a string literal.
p
Inserts an unnamed placeholder field.n
Inserts a newline.>
Indents withindent-according-to-mode
.r
Inserts the current region. If no region is active, quits the containing template when jumped to.r>
Acts liker
, but indent region.n>
Inserts a newline and indents.&
Insert newline unless there is only whitespace between line start and point.%
Insert newline unless there is only whitespace between point and line end.o
Like%
but leaves the point before newline.(s NAME)
Inserts a named field.(p PROMPT <NAME> <NOINSERT>)
Insert an optionally named field with a prompt. ThePROMPT
is displayed directly in the buffer as default value. IfNOINSERT
is non-nil, no field is inserted. Then the minibuffer is used for prompting and the value is bound toNAME
.(r PROMPT <NAME> <NOINSERT>)
Insert region or act like(p ...)
.(r> PROMPT <NAME> <NOINSERT>)
Act like(r ...)
, but indent region.
Furthermore Tempel supports syntax extensions:
(p FORM <NAME> <NOINSERT>)
Likep
described above, butFORM
is evaluated.(FORM ...)
Other Lisp forms are evaluated. Named fields are lexically bound.q
Quits the containing template when jumped to.
Use caution with templates which execute arbitrary code!
5. Defining custom elements
Tempel supports custom user elements via the configuration variable
tempel-user-elements
. As a demonstration we add the element (i template)
to
include templates by name in another template.
(defun tempel-include (elt) (when (eq (car-safe elt) 'i) (if-let (template (alist-get (cadr elt) (tempel--templates))) (cons 'l template) (message "Template %s not found" (cadr elt)) nil))) (add-to-list 'tempel-user-elements #'tempel-include)
The following example templates uses the newly defined include element.
(header ";;; " (file-name-nondirectory (or (buffer-file-name) (buffer-name))) " --- " p " -*- lexical-binding: t -*-" n ";;; Commentary:" n ";;; Code:" n n) (provide "(provide '" (file-name-base (or (buffer-file-name) (buffer-name))) ")" n ";;; " (file-name-nondirectory (or (buffer-file-name) (buffer-name))) " ends here" n) (package (i header) r n n (i provide))
If a custom user element needs an access to named fields, the hook function
should take the second argument fields
, which refers to an alist that maps the
field name to its value in the current template. For example here we define a
custom element *
to repeat a template a number of times:
(defun tempel-repeat (elt fields) (pcase elt (`(* ,count . ,rest) (cons 'l (cl-loop for i below (eval count fields) append rest))))) (add-to-list 'tempel-user-elements #'tempel-repeat)
The *
custom element can be used to expand dynamic tables or LaTeX matrices:
(table (p (read-number "Rows: ") rows noinsert) (p (read-number "Cols: ") cols noinsert) "| " (p " ") (* (1- cols) " | " (p " ")) " |" n "|" (* cols "----|") n (* rows "| " (p " ") (* (1- cols) " | " (p " ")) " |" n)) (matrix (p (read-number "Rows: ") rows noinsert) (p (read-number "Cols: ") cols noinsert) "\\begin{" (p "pmatrix" type) "}" n (* (1- rows) (p " ") (* (1- cols) " & " (p " ")) "\\\\" n) (p " ") (* (1- cols) " & " (p " ")) n "\\end{" type "}")
6. Adding template sources
Tempel offers a flexible mechanism for providing the templates, which are
applicable to the current context. The variable tempel-template-sources
specifies a list of sources or a single source. A source can either be a
function, which should return a list of applicable templates, or the symbol of a
variable, which holds a list of templates, which apply to the current context.
By default, Tempel configures only the source tempel-path-templates
. You may
want to add global or local template variables to your user configuration:
(defvar my-global-templates '((example "Global example template")) "My global templates.") (defvar-local my-local-templates nil "Buffer-local templates.") (add-to-list 'tempel-template-sources 'my-global-templates) (add-to-list 'tempel-template-sources 'my-local-templates)
7. Hooking into the Abbrev mechanism
Tempel can hook into Abbrev by enabling the tempel-abbrev-mode
in a buffer or by
enabling the global-tempel-abbrev-mode
. Then the Tempel templates will be
available via expand-abbrev
which is usually bound to C-x '
.
8. Binding important templates to a key
Important templates can be bound to a key with the small utility macro
tempel-key
which accepts three arguments, a key, a template or name and
optionally a map.
(tempel-key "C-c t f" fun emacs-lisp-mode-map) (tempel-key "C-c t d" ("DATE: " (format-time-string "%Y-%m-%d")))
Internally tempel-key
uses tempel-insert
to trigger the insertion. Depending on
the style of your user configuration you may want to write your own helper
macros, which allow you to conveniently bind templates via use-package, general
or similar keybinding packages.
9. Alternatives
There are plenty of alternative packages which provide abbreviation or snippet expansion. Try Tempel if you like small and simple packages. With Tempel you write your templates in Lisp syntax, which from my perspective fits well to the hackable nature of Emacs. Tempel took inspiration from the Tempo-Snippets package by Nikolaj Schumacher (GitHub link).
List of alternatives (built-in or separate packages):
- abbrev.el: Abbreviation expansion, builtin
- expand.el: Abbreviation expansion, builtin
- skeleton.el: Lisp syntax for templates, builtin
- tempo.el: Lisp syntax for templates, builtin
- srecode.el: CEDET template manager and code generator, builtin
- aas.el: Auto activating snippets
- cdlatex.el: Fast LaTeX insertion
- laas.el: Latex auto activating snippets
- muban.el: Lightweight template expansion
- placeholder.el: Treat buffers as templates
- tempo-abbrev.el: Abbrev integration for Tempo
- snippet.el: Original snippet mode, with inline expansion
- tempo-snippets.el: Interface like snippet.el for Tempo
- yasnippet.el: Template system inspired by Textmate snippets
10. Contributions
Since this package is part of GNU ELPA contributions require a copyright assignment to the FSF.
Old versions
tempel-1.2.tar.lz | 2024-Jul-24 | 18.9 KiB |
tempel-1.1.tar.lz | 2024-Mar-31 | 18.9 KiB |
tempel-1.0.tar.lz | 2023-Dec-01 | 18.8 KiB |
tempel-0.8.tar.lz | 2023-Jul-02 | 18.5 KiB |
tempel-0.7.tar.lz | 2023-Feb-15 | 28.4 KiB |
tempel-0.6.tar.lz | 2022-Dec-28 | 27.3 KiB |
tempel-0.5.tar.lz | 2022-Oct-16 | 26.5 KiB |
tempel-0.4.tar.lz | 2022-Jul-09 | 24.2 KiB |
tempel-0.3.tar.lz | 2022-Mar-08 | 21.5 KiB |
tempel-0.2.tar.lz | 2022-Jan-11 | 20.1 KiB |
News
1. Version 1.3 (2024-12-22)
- Require Emacs 28.1.
- Optional named field argument for custom user element hooks.
- Support
:when
intempel-abbrev-mode
via the abbrev:enable-function
.
2. Version 1.2 (2024-07-24)
- Bugfixes.
- Bump Compat dependency to Compat 30.
3. Version 1.1 (2024-02-16)
- Respect
major-mode-remap-alist
on Emacs 29 when looking up templates.
4. Version 1.0 (2023-12-01)
- Bugfix: Fix
no-self-insert
oftempel-abbrev-mode
. - Bugfix: Only replace default field if not modifying a region.
5. Version 0.8 (2023-07-02)
- Ensure that modification hooks are never inhibited during field modification, which is needed for lsp-mode in order to keep the server synchronized.
6. Version 0.7 (2023-02-15)
- Start of changelog.