lisp/org-tempo.el

   1 ;;; org-tempo.el --- Template expansion for Org structures -*- lexical-binding: t; -*-
   2
   3 ;; Copyright (C) 2017-2018 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 ;; examples.
  38 ;;
  39 ;;; Code:
  40
  41 (require 'tempo)
  42 (require 'cl-lib)
  43 (require 'org)
  44
  45 (defvar org-structure-template-alist)
  46
  47 \f
  48 (defgroup org-tempo nil
  49   "Options for template expansion of Org structures"
  50   :tag "Org structure"
  51   :group 'org)
  52
  53 (defvar org-tempo-tags nil
  54   "Tempo tags for Org mode")
  55
  56 (defcustom org-tempo-keywords-alist
  57   '(("L" . "latex")
  58     ("H" . "html")
  59     ("A" . "ascii")
  60     ("i" . "index"))
  61   "Keyword completion elements.
  62
  63 Like `org-structure-template-alist' this alist of KEY characters
  64 and KEYWORD.  The tempo snippet \"<KEY\" is expand to the KEYWORD
  65 value.
  66
  67 For example \"<l\" at the beginning of a line is expanded to
  68 \"#+latex:\".
  69
  70 Note: the tempo function for \"#+include\" is defined elsewhere."
  71   :group 'org-tempo
  72   :type '(repeat (cons (string :tag "Key")
  73                        (string :tag "Keyword")))
  74   :package-version '(Org . "9.2"))
  75
  76
  77 \f
  78 ;;; Org Tempo functions and setup.
  79
  80 (defun org-tempo-setup ()
  81   (org-tempo--update-maybe)
  82   (tempo-use-tag-list 'org-tempo-tags)
  83   (setq-local tempo-match-finder "^ *\\(<[[:word:]]+\\)\\="))
  84
  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)))
  90
  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))
  97                     (org-tempo--keys))
  98     (org-tempo-add-templates)))
  99
 100 (defun org-tempo-add-templates ()
 101   "Update all Org Tempo templates.
 102
 103 Goes through `org-structure-template-alist' and
 104 `org-tempo-keywords-alist'."
 105   (let ((keys (org-tempo--keys)))
 106     ;; Check for duplicated snippet keys and warn if any are found.
 107     (when (> (length keys) (length (delete-dups keys)))
 108       (warn
 109        "Duplicated keys in `org-structure-template-alist' and `org-tempo-keywords-alist'"))
 110     ;; Remove any keys already defined in case they have been updated.
 111     (setq org-tempo-tags
 112           (cl-remove-if (lambda (tag) (member (car tag) keys)) org-tempo-tags))
 113     (mapc #'org-tempo-add-block org-structure-template-alist)
 114     (mapc #'org-tempo-add-keyword org-tempo-keywords-alist)))
 115
 116 (defun org-tempo-add-block (entry)
 117   "Add block entry from `org-structure-template-alist'."
 118   (let* ((key (format "<%s" (car entry)))
 119          (name (cdr entry))
 120          (special (member name '("src" "export"))))
 121     (tempo-define-template (format "org-%s" (replace-regexp-in-string " " "-" name))
 122                            `(,(format "#+begin_%s%s" name (if special " " ""))
 123                              ,(when special 'p) '> n '> ,(unless special 'p) n
 124                              ,(format "#+end_%s" (car (split-string name " ")))
 125                              >)
 126                            key
 127                            (format "Insert a %s block" name)
 128                            'org-tempo-tags)))
 129
 130 (defun org-tempo-add-keyword (entry)
 131   "Add keyword entry from `org-tempo-keywords-alist'."
 132   (let* ((key (format "<%s" (car entry)))
 133          (name (cdr entry)))
 134     (tempo-define-template (format "org-%s" (replace-regexp-in-string " " "-" name))
 135                            `(,(format "#+%s: " name) p '>)
 136                            key
 137                            (format "Insert a %s keyword" name)
 138                            'org-tempo-tags)))
 139
 140 (defun org-tempo-complete-tag (&rest _)
 141   "Look for a tag and expand it silently.
 142 Unlike to `tempo-complete-tag', do not give a signal if a partial
 143 completion or no match at all is found.  Return nil if expansion
 144 didn't succeed."
 145   (org-tempo--update-maybe)
 146   ;; `tempo-complete-tag' returns its SILENT argument when there is no
 147   ;; completion available at all.
 148   (not (eq 'fail (tempo-complete-tag 'fail))))
 149
 150 \f
 151 ;;; Additional keywords
 152
 153 (defun org-tempo--include-file ()
 154   "Ask for file name and take care of quit"
 155   (let ((inhibit-quit t))
 156     (unless (with-local-quit
 157               (prog1 t
 158                 (insert
 159                  (format "#+include: %S "
 160                          (file-relative-name
 161                           (read-file-name "Include file: "))))))
 162       (insert "<I")
 163       (setq quit-flag nil))))
 164
 165 (tempo-define-template "org-include"
 166                        '((org-tempo--include-file)
 167                          p >)
 168                        "<I"
 169                        "Include keyword"
 170                        'org-tempo-tags)
 171
 172 \f
 173 ;;; Setup of Org Tempo
 174 ;;
 175 ;; Org Tempo is set up with each new Org buffer and potentially in the
 176 ;; current Org buffer.
 177
 178 (add-hook 'org-mode-hook 'org-tempo-setup)
 179 (add-hook 'org-tab-before-tab-emulation-hook 'org-tempo-complete-tag)
 180
 181 ;; Enable Org Tempo in all open Org buffers.
 182 (dolist (b (org-buffer-list 'files))
 183   (with-current-buffer b (org-tempo-setup)))
 184
 185 (provide 'org-tempo)
 186
 187 ;;; org-tempo.el ends here