1 ;;; org-tempo.el --- Template expansion for Org structures -*- lexical-binding: t; -*-
3 ;; Copyright (C) 2017-2018 Free Software Foundation, Inc.
5 ;; Author: Rasmus Pank Roulund <emacs at pank dot eu>
6 ;; Keywords: outlines, hypermedia, calendar, wp
7 ;; Homepage: http://orgmode.org
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 ;; Org Tempo reimplements completions of structure template before
27 ;; point like `org-try-structure-completion' in Org v9.1 and earlier.
28 ;; For example, strings like "<e" at the beginning of the line will be
29 ;; expanded to an example block.
31 ;; All blocks defined in `org-structure-template-alist' are added as
32 ;; Org Tempo shortcuts, in addition to keywords defined in
33 ;; `org-tempo-keywords-alist'.
35 ;; `tempo' can also be used to define more sophisticated keywords
36 ;; completions. See the section "Additional keywords" below for
45 (defvar org-structure-template-alist
)
48 (defgroup org-tempo nil
49 "Template expansion of Org structures."
53 (defvar org-tempo-tags nil
54 "Tempo tags for Org mode.")
56 (defcustom org-tempo-keywords-alist
61 "Keyword completion elements.
63 This is an alist of KEY characters and corresponding KEYWORDS,
64 just like `org-structure-template-alist'. The tempo snippet
65 \"<KEY\" will be expanded using the KEYWORD value. For example
66 \"<L\" at the beginning of a line is expanded to \"#+latex:\".
68 Do not use \"I\" as a KEY, as it it reserved for expanding
71 :type
'(repeat (cons (string :tag
"Key")
72 (string :tag
"Keyword")))
73 :package-version
'(Org .
"9.2"))
77 ;;; Org Tempo functions and setup.
79 (defun org-tempo-setup ()
80 "Setup tempo tags and match finder for the current buffer."
81 (org-tempo--update-maybe)
82 (tempo-use-tag-list 'org-tempo-tags
)
83 (setq-local tempo-match-finder
"^ *\\(<[[:word:]]+\\)\\="))
85 (defun org-tempo--keys ()
86 "Return a list of all Org Tempo expansion strings, like \"<s\"."
87 (mapcar (lambda (pair) (format "<%s" (car pair
)))
88 (append org-structure-template-alist
89 org-tempo-keywords-alist
)))
91 (defun org-tempo--update-maybe ()
92 "Check and add new Org Tempo templates if necessary.
93 In particular, if new entries were added to
94 `org-structure-template-alist' or `org-tempo-keywords-alist', new
95 Tempo templates will be added."
96 (unless (cl-every (lambda (key) (assoc key org-tempo-tags
))
98 (org-tempo-add-templates)))
100 (defun org-tempo-add-templates ()
101 "Update all Org Tempo templates.
103 Go through `org-structure-template-alist' and
104 `org-tempo-keywords-alist' and update tempo templates."
105 (mapc 'org--check-org-structure-template-alist
'(org-structure-template-alist
106 org-tempo-keywords-alist
))
107 (let ((keys (org-tempo--keys)))
108 ;; Check for duplicated snippet keys and warn if any are found.
109 (when (> (length keys
) (length (delete-dups keys
)))
111 "Duplicated keys in `org-structure-template-alist' and `org-tempo-keywords-alist'"))
112 ;; Remove any keys already defined in case they have been updated.
114 (cl-remove-if (lambda (tag) (member (car tag
) keys
)) org-tempo-tags
))
115 (mapc #'org-tempo-add-block org-structure-template-alist
)
116 (mapc #'org-tempo-add-keyword org-tempo-keywords-alist
)))
118 (defun org-tempo-add-block (entry)
119 "Add block entry from `org-structure-template-alist'."
120 (let* ((key (format "<%s" (car entry
)))
122 (special (member name
'("src" "export"))))
123 (tempo-define-template (format "org-%s" (replace-regexp-in-string " " "-" name
))
124 `(,(format "#+begin_%s%s" name
(if special
" " ""))
125 ,(when special
'p
) '> n
'> ,(unless special
'p
) n
126 ,(format "#+end_%s" (car (split-string name
" ")))
129 (format "Insert a %s block" name
)
132 (defun org-tempo-add-keyword (entry)
133 "Add keyword entry from `org-tempo-keywords-alist'."
134 (let* ((key (format "<%s" (car entry
)))
136 (tempo-define-template (format "org-%s" (replace-regexp-in-string " " "-" name
))
137 `(,(format "#+%s: " name
) p
'>)
139 (format "Insert a %s keyword" name
)
142 (defun org-tempo-complete-tag (&rest _
)
143 "Look for a tag and expand it silently.
144 Unlike to `tempo-complete-tag', do not give a signal if a partial
145 completion or no match at all is found. Return nil if expansion
147 (org-tempo--update-maybe)
148 ;; `tempo-complete-tag' returns its SILENT argument when there is no
149 ;; completion available at all.
150 (not (eq 'fail
(tempo-complete-tag 'fail
))))
153 ;;; Additional keywords
155 (defun org-tempo--include-file ()
156 "Add #+include: and a file name."
157 (let ((inhibit-quit t
))
158 (unless (with-local-quit
161 (format "#+include: %S "
163 (read-file-name "Include file: "))))))
165 (setq quit-flag nil
))))
167 (tempo-define-template "org-include"
168 '((org-tempo--include-file)
174 ;;; Setup of Org Tempo
176 ;; Org Tempo is set up with each new Org buffer and potentially in the
177 ;; current Org buffer.
179 (add-hook 'org-mode-hook
'org-tempo-setup
)
180 (add-hook 'org-tab-before-tab-emulation-hook
'org-tempo-complete-tag
)
182 ;; Enable Org Tempo in all open Org buffers.
183 (dolist (b (org-buffer-list 'files
))
184 (with-current-buffer b
(org-tempo-setup)))
188 ;;; org-tempo.el ends here