org-tempo.el 6.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189
  1. ;;; org-tempo.el --- Template expansion for Org structures -*- lexical-binding: t; -*-
  2. ;; Copyright (C) 2017-2019 Free Software Foundation, Inc.
  3. ;;
  4. ;; Author: Rasmus Pank Roulund <emacs at pank dot eu>
  5. ;; Keywords: outlines, hypermedia, calendar, wp
  6. ;; Homepage: http://orgmode.org
  7. ;;
  8. ;; This file is part of GNU Emacs.
  9. ;;
  10. ;; GNU Emacs is free software: you can redistribute it and/or modify
  11. ;; it under the terms of the GNU General Public License as published by
  12. ;; the Free Software Foundation, either version 3 of the License, or
  13. ;; (at your option) any later version.
  14. ;; GNU Emacs is distributed in the hope that it will be useful,
  15. ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  16. ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  17. ;; GNU General Public License for more details.
  18. ;; You should have received a copy of the GNU General Public License
  19. ;; along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>.
  20. ;;
  21. ;;; Commentary:
  22. ;;
  23. ;; Org Tempo reimplements completions of structure template before
  24. ;; point like `org-try-structure-completion' in Org v9.1 and earlier.
  25. ;; For example, strings like "<e" at the beginning of the line will be
  26. ;; expanded to an example block.
  27. ;;
  28. ;; All blocks defined in `org-structure-template-alist' are added as
  29. ;; Org Tempo shortcuts, in addition to keywords defined in
  30. ;; `org-tempo-keywords-alist'.
  31. ;;
  32. ;; `tempo' can also be used to define more sophisticated keywords
  33. ;; completions. See the section "Additional keywords" below for
  34. ;; examples.
  35. ;;
  36. ;;; Code:
  37. (require 'tempo)
  38. (require 'cl-lib)
  39. (require 'org)
  40. (defvar org-structure-template-alist)
  41. (defgroup org-tempo nil
  42. "Template expansion of Org structures."
  43. :tag "Org structure"
  44. :group 'org)
  45. (defvar org-tempo-tags nil
  46. "Tempo tags for Org mode.")
  47. (defcustom org-tempo-keywords-alist
  48. '(("L" . "latex")
  49. ("H" . "html")
  50. ("A" . "ascii")
  51. ("i" . "index"))
  52. "Keyword completion elements.
  53. This is an alist of KEY characters and corresponding KEYWORDS,
  54. just like `org-structure-template-alist'. The tempo snippet
  55. \"<KEY\" will be expanded using the KEYWORD value. For example
  56. \"<L\" at the beginning of a line is expanded to \"#+latex:\".
  57. Do not use \"I\" as a KEY, as it it reserved for expanding
  58. \"#+include\"."
  59. :group 'org-tempo
  60. :type '(repeat (cons (string :tag "Key")
  61. (string :tag "Keyword")))
  62. :package-version '(Org . "9.2"))
  63. ;;; Org Tempo functions and setup.
  64. (defun org-tempo-setup ()
  65. "Setup tempo tags and match finder for the current buffer."
  66. (org-tempo--update-maybe)
  67. (tempo-use-tag-list 'org-tempo-tags)
  68. (setq-local tempo-match-finder "^ *\\(<[[:word:]]+\\)\\="))
  69. (defun org-tempo--keys ()
  70. "Return a list of all Org Tempo expansion strings, like \"<s\"."
  71. (mapcar (lambda (pair) (format "<%s" (car pair)))
  72. (append org-structure-template-alist
  73. org-tempo-keywords-alist)))
  74. (defun org-tempo--update-maybe ()
  75. "Check and add new Org Tempo templates if necessary.
  76. In particular, if new entries were added to
  77. `org-structure-template-alist' or `org-tempo-keywords-alist', new
  78. Tempo templates will be added."
  79. (unless (cl-every (lambda (key) (assoc key org-tempo-tags))
  80. (org-tempo--keys))
  81. (org-tempo-add-templates)))
  82. (defun org-tempo-add-templates ()
  83. "Update all Org Tempo templates.
  84. Go through `org-structure-template-alist' and
  85. `org-tempo-keywords-alist' and update tempo templates."
  86. (mapc 'org--check-org-structure-template-alist '(org-structure-template-alist
  87. org-tempo-keywords-alist))
  88. (let ((keys (org-tempo--keys)))
  89. ;; Check for duplicated snippet keys and warn if any are found.
  90. (when (> (length keys) (length (delete-dups keys)))
  91. (warn
  92. "Duplicated keys in `org-structure-template-alist' and `org-tempo-keywords-alist'"))
  93. ;; Remove any keys already defined in case they have been updated.
  94. (setq org-tempo-tags
  95. (cl-remove-if (lambda (tag) (member (car tag) keys)) org-tempo-tags))
  96. (mapc #'org-tempo-add-block org-structure-template-alist)
  97. (mapc #'org-tempo-add-keyword org-tempo-keywords-alist)))
  98. (defun org-tempo-add-block (entry)
  99. "Add block entry from `org-structure-template-alist'."
  100. (let* ((key (format "<%s" (car entry)))
  101. (name (cdr entry))
  102. (special (member name '("src" "export"))))
  103. (tempo-define-template (format "org-%s" (replace-regexp-in-string " " "-" name))
  104. `(,(format "#+begin_%s%s" name (if special " " ""))
  105. ,(when special 'p) '> n '> ,(unless special 'p) n
  106. ,(format "#+end_%s" (car (split-string name " ")))
  107. >)
  108. key
  109. (format "Insert a %s block" name)
  110. 'org-tempo-tags)))
  111. (defun org-tempo-add-keyword (entry)
  112. "Add keyword entry from `org-tempo-keywords-alist'."
  113. (let* ((key (format "<%s" (car entry)))
  114. (name (cdr entry)))
  115. (tempo-define-template (format "org-%s" (replace-regexp-in-string " " "-" name))
  116. `(,(format "#+%s: " name) p '>)
  117. key
  118. (format "Insert a %s keyword" name)
  119. 'org-tempo-tags)))
  120. (defun org-tempo-complete-tag (&rest _)
  121. "Look for a tag and expand it silently.
  122. Unlike to `tempo-complete-tag', do not give a signal if a partial
  123. completion or no match at all is found. Return nil if expansion
  124. didn't succeed."
  125. (org-tempo--update-maybe)
  126. ;; `tempo-complete-tag' returns its SILENT argument when there is no
  127. ;; completion available at all.
  128. (not (eq 'fail (tempo-complete-tag 'fail))))
  129. ;;; Additional keywords
  130. (defun org-tempo--include-file ()
  131. "Add #+include: and a file name."
  132. (let ((inhibit-quit t))
  133. (unless (with-local-quit
  134. (prog1 t
  135. (insert
  136. (format "#+include: %S "
  137. (file-relative-name
  138. (read-file-name "Include file: "))))))
  139. (insert "<I")
  140. (setq quit-flag nil))))
  141. (tempo-define-template "org-include"
  142. '((org-tempo--include-file)
  143. p >)
  144. "<I"
  145. "Include keyword"
  146. 'org-tempo-tags)
  147. ;;; Setup of Org Tempo
  148. ;;
  149. ;; Org Tempo is set up with each new Org buffer and potentially in the
  150. ;; current Org buffer.
  151. (add-hook 'org-mode-hook 'org-tempo-setup)
  152. (add-hook 'org-tab-before-tab-emulation-hook 'org-tempo-complete-tag)
  153. ;; Enable Org Tempo in all open Org buffers.
  154. (dolist (b (org-buffer-list 'files))
  155. (with-current-buffer b (org-tempo-setup)))
  156. (provide 'org-tempo)
  157. ;;; org-tempo.el ends here