lisp/org-tempo.el

   1 ;;; org-tempo.el --- Template expansion for Org structures -*- lexical-binding: t; -*-
   2
   3 ;; Copyright (C) 2017 Free Software Foundation, Inc.
   4 ;;
   5 ;; Author: Rasmus Pank Roulund <emacs at pank dot eu>
   6 ;; Keywords: outlines, hypermedia, calendar, wp
   7 ;; Homepage: http://orgmode.org
   8 ;;
   9 ;; This file is part of GNU Emacs.
  10 ;;
  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.
  15
  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.
  20
  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/>.
  23 ;;
  24 ;;; Commentary:
  25 ;;
  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.
  30 ;;
  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'.
  34 ;;
  35 ;; `tempo' can also be used to define more sophisticated keywords
  36 ;; completions.  See the section "Additional keywords" below for
  37 ;; additional details.
  38 ;;
  39 ;;; Code:
  40
  41 (require 'tempo)
  42 (require 'cl-lib)
  43
  44 \f
  45 (defgroup org-tempo nil
  46   "Options for template expansion of Org structures"
  47   :tag "Org structure"
  48   :group 'org)
  49
  50 (defvar org-tempo-tags nil
  51   "Tempo tags for org-mode")
  52
  53 (defcustom org-tempo-keywords-alist
  54   '((?L . "latex")
  55     (?H . "html")
  56     (?A . "ascii")
  57     (?i . "index"))
  58   "Keyword completion elements.
  59
  60 Like `org-structure-template-alist' this alist of KEY characters
  61 and KEYWORD.  The tempo snippet \"<KEY\" is expand to the KEYWORD
  62 value.
  63
  64 For example \"<l\" at the beginning of a line is expanded to
  65 #+latex:"
  66   :group 'org-tempo
  67   :type '(repeat (cons (character :tag "Key")
  68                        (string :tag "Keyword")))
  69   :package-version '(Org . "9.2"))
  70
  71
  72 \f
  73 ;;; Org Tempo functions and setup.
  74
  75 (defun org-tempo-setup ()
  76   (org-tempo-add-templates)
  77   (tempo-use-tag-list 'org-tempo-tags)
  78   (setq-local tempo-match-finder "^ *\\(<[[:word:]]\\)\\="))
  79
  80 (defun org-tempo-add-templates ()
  81   "Update all Org Tempo templates.
  82
  83 Goes through `org-structure-template-alist' and
  84 `org-tempo-keywords-alist'."
  85   (let ((keys (mapcar (lambda (pair) (format "<%c" (car pair)))
  86                       (append org-structure-template-alist
  87                               org-tempo-keywords-alist))))
  88     ;; Check for duplicated snippet keys and warn if any are found.
  89     (when (> (length keys) (length (delete-dups keys)))
  90       (warn
  91        "Duplicated keys in `org-structure-template-alist' and `org-tempo-keywords-alist'"))
  92
  93     ;; Remove any keys already defined in case they have been updated.
  94     (mapc (lambda (key)
  95             (if (assoc-string key org-tempo-tags)
  96                 (setq org-tempo-tags
  97                       (delete (assoc-string key org-tempo-tags)
  98                               org-tempo-tags))))
  99           keys)
 100     (mapc #'org-tempo-add-block org-structure-template-alist)
 101     (mapc #'org-tempo-add-keyword org-tempo-keywords-alist)))
 102
 103 (defun org-tempo-add-block (entry)
 104   "Add block entry from `org-structure-template-alist'."
 105   (let* ((key (format "<%c" (car entry)))
 106          (name (cdr entry)))
 107     (tempo-define-template (format "org-%s" (replace-regexp-in-string " " "-" name))
 108                            `(,(format "#+begin_%s " name) p '> n n
 109                              ,(format "#+end_%s" (car (split-string name " ")))
 110                              >)
 111                            key
 112                            (format "Insert a %s block" name)
 113                            'org-tempo-tags)))
 114
 115 (defun org-tempo-add-keyword (entry)
 116   "Add keyword entry from `org-tempo-keywords-alist'."
 117   (let* ((key (format "<%c" (car entry)))
 118          (name (cdr entry)))
 119     (tempo-define-template (format "org-%s" (replace-regexp-in-string " " "-" name))
 120                            `(,(format "#+%s: " name) p '>)
 121                            key
 122                            (format "Insert a %s keyword" name)
 123                            'org-tempo-tags)))
 124
 125 ;;; Additional keywords
 126
 127 (defun org-tempo--include-file ()
 128   "Ask for file name and take care of quit"
 129   (let* ((inhibit-quit t))
 130     (unless (with-local-quit
 131               (prog1 t
 132                 (insert
 133                  (format "#+include: \"%s\" " (file-relative-name
 134                                     (read-file-name "Include file: "))))))
 135       (insert "<I")
 136       (setq quit-flag nil))))
 137
 138 (tempo-define-template "org-include"
 139                        '((org-tempo--include-file)
 140                          p >)
 141                        "<I"
 142                        "Include keyword"
 143                        'org-tempo-tags)
 144
 145 \f
 146 ;;; Setup of Org Tempo
 147 ;;
 148 ;; Org Tempo is set up with each new Org buffer and potentially in the
 149 ;; current Org buffer.
 150 ;;
 151 ;; Tempo templates can only be added after Org is loaded as
 152 ;; `org-structure-template-alist' must be loaded.
 153
 154 (add-hook 'org-mode-hook 'org-tempo-setup)
 155 (add-hook 'org-tab-before-tab-emulation-hook
 156           'tempo-complete-tag)
 157 (when (eq major-mode 'org-mode) (org-tempo-setup))
 158
 159 (eval-after-load 'org
 160   '(org-tempo-add-templates))
 161
 162 (provide 'org-tempo)
 163
 164 ;;; org-tempo.el ends here