lisp/tempo.el

   1 ;;; tempo.el --- Flexible template insertion
   2
   3 ;; Copyright (C) 1994, 1995 Free Software Foundation, Inc.
   4
   5 ;; Author: David K}gedal <davidk@lysator.liu.se >
   6 ;; Created: 16 Feb 1994
   7 ;; K}gedal's last version number: 1.2.4
   8 ;; Keywords: extensions, languages, tools
   9
  10 ;; This file is part of GNU Emacs.
  11
  12 ;; GNU Emacs is free software; you can redistribute it and/or modify
  13 ;; it under the terms of the GNU General Public License as published by
  14 ;; the Free Software Foundation; either version 2, or (at your option)
  15 ;; any later version.
  16
  17 ;; GNU Emacs is distributed in the hope that it will be useful,
  18 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  19 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20 ;; GNU General Public License for more details.
  21
  22 ;; You should have received a copy of the GNU General Public License
  23 ;; along with GNU Emacs; see the file COPYING.  If not, write to the
  24 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  25 ;; Boston, MA 02111-1307, USA.
  26
  27 ;;; Commentary:
  28
  29 ;; This file provides a simple way to define powerful templates, or
  30 ;; macros, if you wish. It is mainly intended for, but not limited to,
  31 ;; other programmers to be used for creating shortcuts for editing
  32 ;; certain kind of documents. It was originally written to be used by
  33 ;; a HTML editing mode written by Nelson Minar <nelson@santafe.edu>,
  34 ;; and his html-helper-mode.el is probably the best example of how to
  35 ;; use this program.
  36
  37 ;; A template is defined as a list of items to be inserted in the
  38 ;; current buffer at point. Some of the items can be simple strings,
  39 ;; while other can control formatting or define special points of
  40 ;; interest in the inserted text.
  41
  42 ;; If a template defines a "point of interest" that point is inserted
  43 ;; in a buffer-local list of "points of interest" that the user can
  44 ;; jump between with the commands `tempo-backward-mark' and
  45 ;; `tempo-forward-mark'. If the template definer provides a prompt for
  46 ;; the point, and the variable `tempo-interactive' is non-nil, the
  47 ;; user will be prompted for a string to be inserted in the buffer,
  48 ;; using the minibuffer.
  49
  50 ;; The template can also define one point to be replaced with the
  51 ;; current region if the template command is called with a prefix (or
  52 ;; a non-nil argument).
  53
  54 ;; More flexible templates can be created by including lisp symbols,
  55 ;; which will be evaluated as variables, or lists, which will will be
  56 ;; evaluated as lisp expressions.
  57
  58 ;; See the documentation for tempo-define-template for the different
  59 ;; items that can be used to define a tempo template.
  60
  61 ;; One of the more powerful features of tempo templates are automatic
  62 ;; completion. With every template can be assigned a special tag that
  63 ;; should be recognized by `tempo-complete-tag' and expanded to the
  64 ;; complete template. By default the tags are added to a global list
  65 ;; of template tags, and are matched against the last word before
  66 ;; point. But if you assign your tags to a specific list, you can also
  67 ;; specify another method for matching text in the buffer against the
  68 ;; tags. In the HTML mode, for instance, the tags are matched against
  69 ;; the text between the last `<' and point.
  70
  71 ;; When defining a template named `foo', a symbol named
  72 ;; `tempo-template-foo' will be created whose value as a variable will
  73 ;; be the template definition, and its function value will be an
  74 ;; interactive function that inserts the template at the point.
  75
  76 ;; The latest tempo.el distribution can be fetched from
  77 ;; ftp.lysator.liu.se in the directory /pub/emacs
  78
  79 ;; There is also a WWW page at
  80 ;; http://www.lysator.liu.se/~davidk/elisp/ which has some information
  81
  82 ;;; Known bugs:
  83
  84 ;; If the 'o is the first element in a template, strange things can
  85 ;; happen when the template is inserted at the beginning of a
  86 ;; line. This is due to strange behaviour in open-line. But it should
  87 ;; be easily avoided.
  88
  89 ;; The 'o tag is also a problem when including the region. This will
  90 ;; be looked into.
  91
  92 ;; Clicking mouse-2 in the completion buffer gives strange results.
  93
  94 ;; There is a bug in some emacs versions that prevents completion from
  95 ;; working. If it doesn't work for you, send me a note indicating your
  96 ;; emacs version and your problems.
  97
  98 ;;; Contributors:
  99
 100 ;; These people have given me important feedback and new ideas for
 101 ;; tempo.el. Thanks.
 102
 103 ;; Nelson Minar <nelson@santafe.edu>
 104 ;; Richard Stallman <rms@gnu.ai.mit.edu>
 105 ;; Lars Lindberg <Lars.Lindberg@sypro.cap.se>
 106 ;; Glen Whitney <Glen.Whitney@math.lsa.umich.edu>
 107
 108 ;;; Code:
 109
 110 ;; (provide 'tempo)
 111
 112 ;;; User options
 113
 114 (defgroup tempo nil
 115   "Flexible template insertion."
 116   :prefix "tempo-"
 117   :group 'tools)
 118
 119 (defcustom tempo-interactive nil
 120   "*Prompt user for strings in templates.
 121 If this variable is non-nil, `tempo-insert' prompts the
 122 user for text to insert in the templates"
 123   :type 'boolean
 124   :group 'tempo)
 125
 126 (defcustom tempo-insert-region nil
 127   "*Automatically insert current region when there is a `r' in the template
 128 If this variable is NIL, `r' elements will be treated just like `p'
 129 elements, unless the template function is given a prefix (or a non-nil
 130 argument). If this variable is non-NIL, the behaviour is reversed.
 131
 132 In Transient Mark mode, this option is unused."
 133   :type 'boolean
 134   :group 'tempo)
 135
 136 (defcustom tempo-show-completion-buffer t
 137   "*If non-NIL, show a buffer with possible completions, when only
 138 a partial completion can be found"
 139   :type 'boolean
 140   :group 'tempo)
 141
 142 (defcustom tempo-leave-completion-buffer nil
 143   "*If NIL, a completion buffer generated by \\[tempo-complete-tag]
 144 disappears at the next keypress; otherwise, it remains forever."
 145   :type 'boolean
 146   :group 'tempo)
 147
 148 ;;; Internal variables
 149
 150 (defvar tempo-insert-string-functions nil
 151   "List of functions to run when inserting a string.
 152 Each function is called with a single arg, STRING and should return
 153 another string. This could be used for making all strings upcase by
 154 setting it to '(upcase), for example.")
 155
 156 (defvar tempo-tags nil
 157   "An association list with tags and corresponding templates")
 158
 159 (defvar tempo-local-tags '((tempo-tags . nil))
 160   "A list of locally installed tag completion lists.
 161 It is a association list where the car of every element is a symbol
 162 whose variable value is a template list. The cdr part, if non-nil, is a
 163 function or a regexp that defines the string to match. See the
 164 documentation for the function `tempo-complete-tag' for more info.
 165
 166 `tempo-tags' is always in the last position in this list.")
 167
 168 (defvar tempo-collection nil
 169   "A collection of all the tags defined for the current buffer.")
 170
 171 (defvar tempo-dirty-collection t
 172   "Indicates if the tag collection needs to be rebuilt.")
 173
 174 (defvar tempo-marks nil
 175   "A list of marks to jump to with `\\[tempo-forward-mark]' and `\\[tempo-backward-mark]'.")
 176
 177 (defvar tempo-match-finder "\\b\\([^\\b]+\\)\\="
 178   "The regexp or function used to find the string to match against tags.
 179
 180 If `tempo-match-finder is a string, it should contain a regular
 181 expression with at least one \\( \\) pair. When searching for tags,
 182 `tempo-complete-tag' calls `re-search-backward' with this string, and
 183 the string between the first \\( and \\) is used for matching against
 184 each string in the tag list. If one is found, the whole text between
 185 the first \\( and the point is replaced with the inserted template.
 186
 187 You will probably want to include \\ \= at the end of the regexp to
 188 make sure that the string is matched only against text adjacent to the
 189 point.
 190
 191 If `tempo-match-finder' is a symbol, it should be a function that
 192 returns a pair of the form (STRING . POS), where STRING is the string
 193 used for matching and POS is the buffer position after which text
 194 should be replaced with a template.")
 195
 196 (defvar tempo-user-elements nil
 197   "Element handlers for user-defined elements.
 198 A list of symbols which are bound to functions that take one argument.
 199 This function should return something to be sent to `tempo-insert' if
 200 it recognizes the argument, and NIL otherwise")
 201
 202 (defvar tempo-named-insertions nil
 203   "Temporary storage for named insertions")
 204
 205 (defvar tempo-region-start (make-marker)
 206   "Region start when inserting around the region")
 207
 208 (defvar tempo-region-stop (make-marker)
 209   "Region stop when inserting around the region")
 210
 211 ;; Make some variables local to every buffer
 212
 213 (make-variable-buffer-local 'tempo-marks)
 214 (make-variable-buffer-local 'tempo-local-tags)
 215 (make-variable-buffer-local 'tempo-match-finder)
 216 (make-variable-buffer-local 'tempo-collection)
 217 (make-variable-buffer-local 'tempo-dirty-collection)
 218
 219 ;;; Functions
 220
 221 ;;; First some useful functions and macros
 222
 223 (defun tempo-mapc (fun lst)
 224   (if (null lst) nil
 225     (funcall fun (car lst))
 226     (tempo-mapc fun (cdr lst))))
 227
 228 (defmacro tempo-dolist (il &rest forms)
 229   (let ((i (car il))
 230         (l (car (cdr il))))
 231     (list 'tempo-mapc
 232           (list 'function (append (list 'lambda
 233                                         (list i))
 234                                   forms))
 235           l)))
 236 (put 'tempo-dolist 'lisp-indent-function 1)
 237
 238 ;;
 239 ;; tempo-define-template
 240
 241 (defun tempo-define-template (name elements &optional tag documentation taglist)
 242   "Define a template.
 243 This function creates a template variable `tempo-template-NAME' and an
 244 interactive function `tempo-template-NAME' that inserts the template
 245 at the point.  The created function is returned.
 246
 247 NAME is a string that contains the name of the template, ELEMENTS is a
 248 list of elements in the template, TAG is the tag used for completion,
 249 DOCUMENTATION is the documentation string for the insertion command
 250 created, and TAGLIST (a symbol) is the tag list that TAG (if provided)
 251 should be added to).  If TAGLIST is nil and TAG is non-nil, TAG is
 252 added to `tempo-tags'
 253
 254 The elements in ELEMENTS can be of several types:
 255
 256  - A string. It is sent to the hooks in `tempo-insert-string-functions',
 257    and the result is inserted.
 258  - The symbol 'p. This position is saved in `tempo-marks'.
 259  - The symbol 'r. If `tempo-insert' is called with ON-REGION non-nil
 260    the current region is placed here. Otherwise it works like 'p.
 261  - (p PROMPT <NAME> <NOINSERT>) If `tempo-interactive' is non-nil, the
 262    user is prompted in the minbuffer with PROMPT for a string to be
 263    inserted. If the optional parameter NAME is non-nil, the text is
 264    saved for later insertion with the `s' tag. If there already is
 265    something saved under NAME that value is used instead and no
 266    prompting is made. If NOINSERT is provided and non-nil, nothing is
 267    inserted, but text is still saved when a NAME is provided. For
 268    clarity, the symbol 'noinsert should be used as argument.
 269  - (P PROMPT <NAME> <NOINSERT>) Works just like the previous tag, but
 270    forces tempo-interactive to be true.
 271  - (r PROMPT <NAME> <NOINSERT>) like the previous, but if
 272    `tempo-interactive' is nil and `tempo-insert' is called with
 273    ON-REGION non-nil, the current region is placed here. This usually
 274    happens when you call the template function with a prefix argument.
 275  - (s NAME) Inserts text previously read with the (p ..) construct.
 276    Finds the insertion saved under NAME and inserts it. Acts like 'p
 277    if tempo-interactive is nil.
 278  - '& If there is only whitespace between the line start and point,
 279    nothing happens. Otherwise a newline is inserted.
 280  - '% If there is only whitespace between point and end-of-line
 281    nothing happens. Otherwise a newline is inserted.
 282  - 'n inserts a newline.
 283  - '> The line is indented using `indent-according-to-mode'. Note that
 284    you often should place this item after the text you want on the
 285    line.
 286  - 'r> Like r, but it also indents the region.
 287  - 'n> Inserts a newline and indents line.
 288  - 'o Like '% but leaves the point before the newline.
 289  - nil. It is ignored.
 290  - Anything else. It is evaluated and the result is treated as an
 291    element to be inserted. One additional tag is useful for these
 292    cases. If an expression returns a list '(l foo bar), the elements
 293    after 'l will be inserted according to the usual rules. This makes
 294    it possible to return several elements from one expression."
 295
 296   (let* ((template-name (intern (concat "tempo-template-"
 297                                        name)))
 298          (command-name template-name))
 299     (set template-name elements)
 300     (fset command-name (list 'lambda (list '&optional 'arg)
 301                              (or documentation
 302                                  (concat "Insert a " name "."))
 303                              (list 'interactive "*P")
 304                              (list 'tempo-insert-template (list 'quote
 305                                                                 template-name)
 306                                    (list 'if 'tempo-insert-region
 307                                          (list 'not 'arg) 'arg))))
 308     (and tag
 309          (tempo-add-tag tag template-name taglist))
 310     command-name))
 311
 312 ;;;
 313 ;;; tempo-insert-template
 314
 315 (defun tempo-insert-template (template on-region)
 316   "Insert a template.
 317 TEMPLATE is the template to be inserted.  If ON-REGION is non-nil the
 318 `r' elements are replaced with the current region. In Transient Mark
 319 mode, ON-REGION is ignored and assumed true if the region is active."
 320   (unwind-protect
 321       (progn
 322         (if (or (and (boundp 'transient-mark-mode) ; For Emacs
 323                      transient-mark-mode
 324                      mark-active)
 325                 (and (boundp 'zmacs-regions) ; For XEmacs
 326                      zmacs-regions (mark)))
 327             (setq on-region t))
 328         (and on-region
 329              (set-marker tempo-region-start (min (mark) (point)))
 330              (set-marker tempo-region-stop (max (mark) (point))))
 331         (if on-region
 332             (goto-char tempo-region-start))
 333         (save-excursion
 334           (tempo-insert-mark (point-marker))
 335           (mapcar (function (lambda (elt)
 336                               (tempo-insert elt on-region)))
 337                   (symbol-value template))
 338           (tempo-insert-mark (point-marker)))
 339         (tempo-forward-mark))
 340     (tempo-forget-insertions)
 341     ;; Should I check for zmacs here too???
 342     (and (boundp 'transient-mark-mode)
 343          transient-mark-mode
 344          (deactivate-mark))))
 345
 346 ;;;
 347 ;;; tempo-insert
 348
 349 (defun tempo-insert (element on-region)
 350   "Insert a template element.
 351 Insert one element from a template. If ON-REGION is non-nil the `r'
 352 elements are replaced with the current region.
 353
 354 See documentation for `tempo-define-template' for the kind of elements
 355 possible."
 356   (cond ((stringp element) (tempo-process-and-insert-string element))
 357         ((and (consp element)
 358               (eq (car element) 'p)) (tempo-insert-prompt-compat
 359                                       (cdr element)))
 360         ((and (consp element)
 361               (eq (car element) 'P)) (let ((tempo-interactive t))
 362                                        (tempo-insert-prompt-compat
 363                                         (cdr element))))
 364 ;;;     ((and (consp element)
 365 ;;;           (eq (car element) 'v)) (tempo-save-named
 366 ;;;                                   (nth 1 element)
 367 ;;;                                   nil
 368 ;;;                                   (nth 2 element)))
 369         ((and (consp element)
 370               (eq (car element) 'r)) (if on-region
 371                                          (goto-char tempo-region-stop)
 372                                        (tempo-insert-prompt-compat
 373                                         (cdr element))))
 374         ((and (consp element)
 375               (eq (car element) 's)) (tempo-insert-named (car (cdr element))))
 376         ((and (consp element)
 377               (eq (car element) 'l)) (mapcar (function
 378                                               (lambda (elt)
 379                                                 (tempo-insert elt on-region)))
 380                                              (cdr element)))
 381         ((eq element 'p) (tempo-insert-mark (point-marker)))
 382         ((eq element 'r) (if on-region
 383                              (goto-char tempo-region-stop)
 384                            (tempo-insert-mark (point-marker))))
 385         ((eq element 'r>) (if on-region
 386                               (progn
 387                                 (goto-char tempo-region-stop)
 388                                 (indent-region (mark) (point) nil))
 389                             (tempo-insert-mark (point-marker))))
 390         ((eq element '>) (indent-according-to-mode))
 391         ((eq element '&) (if (not (or (= (current-column) 0)
 392                                       (save-excursion
 393                                         (re-search-backward
 394                                          "^\\s-*\\=" nil t))))
 395                              (insert "\n")))
 396         ((eq element '%) (if (not (or (eolp)
 397                                       (save-excursion
 398                                         (re-search-forward
 399                                          "\\=\\s-*$" nil t))))
 400                              (insert "\n")))
 401         ((eq element 'n) (insert "\n"))
 402         ((eq element 'n>) (insert "\n") (indent-according-to-mode))
 403         ;; Bug: If the 'o is the first element in a template, strange
 404         ;; things can happen when the template is inserted at the
 405         ;; beginning of a line.
 406         ((eq element 'o) (if (not (or on-region
 407                                       (eolp)
 408                                       (save-excursion
 409                                         (re-search-forward
 410                                          "\\=\\s-*$" nil t))))
 411                              (open-line 1)))
 412         ((null element))
 413         (t (tempo-insert (or (tempo-is-user-element element)
 414                              (eval element))
 415                          on-region))))
 416
 417 ;;;
 418 ;;; tempo-insert-prompt
 419
 420 (defun tempo-insert-prompt-compat (prompt)
 421   "Compatibility hack for tempo-insert-prompt.
 422 PROMPT can be either a prompt string, or a list of arguments to
 423 tempo-insert-prompt, or nil."
 424   (if (consp prompt)                    ; not NIL either
 425       (apply 'tempo-insert-prompt prompt)
 426     (tempo-insert-prompt prompt)))
 427
 428 (defun tempo-insert-prompt (prompt &optional save-name no-insert)
 429   "Prompt for a text string and insert it in the current buffer.
 430 If the variable `tempo-interactive' is non-nil the user is prompted
 431 for a string in the minibuffer, which is then inserted in the current
 432 buffer. If `tempo-interactive' is nil, the current point is placed on
 433 `tempo-mark'.
 434
 435 PROMPT is the prompt string, SAVE-NAME is a name to save the inserted
 436 text under. If the optional argument NO-INSERT is non-nil, no text i
 437 inserted. This can be useful when there is a SAVE-NAME.
 438
 439 If there already is a value for SAVE-NAME, it is used and the user is
 440 never prompted."
 441   (let (insertion
 442         (previous (and save-name
 443                        (tempo-lookup-named save-name))))
 444     (cond
 445      ;; Insert  previous value, unless no-insert is non-nil
 446      ((and previous
 447            (not no-insert))
 448       (tempo-insert-named save-name)) ; A double lookup here, but who
 449                                       ; cares
 450      ;; If no-insert is non-nil, don't insert the previous value. Just
 451      ;; keep it
 452      (previous
 453       nil)
 454      ;; No previous value. Prompt or insert mark
 455      (tempo-interactive
 456       (if (not (stringp prompt))
 457           (error "tempo: The prompt (%s) is not a string" prompt))
 458       (setq insertion (read-string prompt))
 459       (or no-insert
 460           (insert insertion))
 461       (if save-name
 462           (tempo-save-named save-name insertion)))
 463      (t
 464       (tempo-insert-mark (point-marker))))))
 465
 466 ;;;
 467 ;;; tempo-is-user-element
 468
 469 (defun tempo-is-user-element (element)
 470   "Tries all the user-defined element handlers in
 471 `tempo-user-elements'"
 472   ;; Sigh... I need (some list)
 473   (catch 'found
 474     (mapcar (function (lambda (handler)
 475                         (let ((result (funcall handler element)))
 476                           (if result (throw 'found result)))))
 477             tempo-user-elements)
 478     (throw 'found nil)))
 479
 480 ;;;
 481 ;;; tempo-forget-insertions
 482
 483 (defun tempo-forget-insertions ()
 484   "Forget all the saved named insertions."
 485   (setq tempo-named-insertions nil))
 486
 487 ;;;
 488 ;;; tempo-save-named
 489
 490 (defun tempo-save-named (name data)     ; Had an optional prompt for 'v
 491   "Save some data for later insertion
 492 The contents of DATA is saved under the name NAME.
 493
 494 The data can later be retrieved with `tempo-lookup-named'.
 495
 496 This function returns nil, so it can be used in a template without
 497 inserting anything."
 498   (setq tempo-named-insertions
 499         (cons (cons name data)
 500               tempo-named-insertions))
 501   nil)
 502
 503 ;;;
 504 ;;; tempo-lookup-named
 505
 506 (defun tempo-lookup-named (name)
 507   "Lookup some saved data under the name NAME.
 508 Returns the data if NAME was found, and nil otherwise."
 509   (cdr (assq name tempo-named-insertions)))
 510
 511 ;;;
 512 ;;; tempo-insert-named
 513
 514 (defun tempo-insert-named (name)
 515   "Insert the previous insertion saved under a named specified in NAME.
 516 If there is no such name saved, a tempo mark is inserted.
 517
 518 Note that if the data is a string, it will not be run through the string
 519 processor."
 520   (let* ((insertion (tempo-lookup-named name)))
 521     (cond ((null insertion)
 522            (tempo-insert-mark (point-marker)))
 523           ((stringp insertion)
 524            (insert insertion))
 525           (t
 526            (tempo-insert insertion nil)))))
 527
 528
 529 ;;;
 530 ;;; tempo-process-and-insert-string
 531
 532 (defun tempo-process-and-insert-string (string)
 533   "Insert a string from a template.
 534 Run a string through the preprocessors in `tempo-insert-string-functions'
 535 and insert the results."
 536   (cond ((null tempo-insert-string-functions)
 537          nil)
 538         ((symbolp tempo-insert-string-functions)
 539          (setq string
 540                (funcall tempo-insert-string-functions string)))
 541         ((listp tempo-insert-string-functions)
 542          (tempo-dolist (fn tempo-insert-string-functions)
 543            (setq string (funcall fn string))))
 544         (t
 545          (error "Bogus value in tempo-insert-string-functions: %s"
 546                 tempo-insert-string-functions)))
 547   (insert string))
 548
 549 ;;;
 550 ;;; tempo-insert-mark
 551
 552 (defun tempo-insert-mark (mark)
 553   "Insert a mark `tempo-marks' while keeping it sorted"
 554   (cond ((null tempo-marks) (setq tempo-marks (list mark)))
 555         ((< mark (car tempo-marks)) (setq tempo-marks (cons mark tempo-marks)))
 556         (t (let ((lp tempo-marks))
 557              (while (and (cdr lp)
 558                          (<= (car (cdr lp)) mark))
 559                (setq lp (cdr lp)))
 560              (if (not (= mark (car lp)))
 561                  (setcdr lp (cons mark (cdr lp))))))))
 562
 563 ;;;
 564 ;;; tempo-forward-mark
 565
 566 (defun tempo-forward-mark ()
 567   "Jump to the next mark in `tempo-forward-mark-list'."
 568   (interactive)
 569   (let ((next-mark (catch 'found
 570                      (mapcar
 571                       (function
 572                        (lambda (mark)
 573                          (if (< (point) mark)
 574                              (throw 'found mark))))
 575                       tempo-marks)
 576                      ;; return nil if not found
 577                      nil)))
 578     (if next-mark
 579         (goto-char next-mark))))
 580
 581 ;;;
 582 ;;; tempo-backward-mark
 583
 584 (defun tempo-backward-mark ()
 585   "Jump to the previous mark in `tempo-back-mark-list'."
 586   (interactive)
 587   (let ((prev-mark (catch 'found
 588                      (let (last)
 589                        (mapcar
 590                         (function
 591                          (lambda (mark)
 592                            (if (<= (point) mark)
 593                                (throw 'found last))
 594                            (setq last mark)))
 595                         tempo-marks)
 596                        last))))
 597     (if prev-mark
 598         (goto-char prev-mark))))
 599
 600 ;;;
 601 ;;; tempo-add-tag
 602
 603 (defun tempo-add-tag (tag template &optional tag-list)
 604   "Add a template tag.
 605 Add the TAG, that should complete to TEMPLATE to the list in TAG-LIST,
 606 or to `tempo-tags' if TAG-LIST is nil."
 607
 608   (interactive "sTag: \nCTemplate: ")
 609   (if (null tag-list)
 610       (setq tag-list 'tempo-tags))
 611   (if (not (assoc tag (symbol-value tag-list)))
 612       (set tag-list (cons (cons tag template) (symbol-value tag-list))))
 613   (tempo-invalidate-collection))
 614
 615 ;;;
 616 ;;; tempo-use-tag-list
 617
 618 (defun tempo-use-tag-list (tag-list &optional completion-function)
 619   "Install TAG-LIST to be used for template completion in the current buffer.
 620 TAG-LIST is a symbol whose variable value is a tag list created with
 621 `tempo-add-tag'.
 622
 623 COMPLETION-FUNCTION is an obsolete option for specifying an optional
 624 function or string that is used by `\\[tempo-complete-tag]' to find a
 625 string to match the tag against. It has the same definition as the
 626 variable `tempo-match-finder'. In this version, supplying a
 627 COMPLETION-FUNCTION just sets `tempo-match-finder' locally."
 628   (let ((old (assq tag-list tempo-local-tags)))
 629     (if old
 630         (setcdr old completion-function)
 631       (setq tempo-local-tags (cons (cons tag-list completion-function)
 632                                    tempo-local-tags))))
 633   (if completion-function
 634       (setq tempo-match-finder completion-function))
 635   (tempo-invalidate-collection))
 636
 637 ;;;
 638 ;;; tempo-invalidate-collection
 639
 640 (defun tempo-invalidate-collection ()
 641   "Marks the tag collection as obsolete.
 642 Whenever it is needed again it will be rebuilt."
 643   (setq tempo-dirty-collection t))
 644
 645 ;;;
 646 ;;; tempo-build-collection
 647
 648 (defun tempo-build-collection ()
 649   "Build a collection of all the tags and return it.
 650 If `tempo-dirty-collection' is NIL, the old collection is reused."
 651   (prog1
 652       (or (and (not tempo-dirty-collection)
 653                tempo-collection)
 654           (setq tempo-collection
 655                 (apply (function append)
 656                        (mapcar (function (lambda (tag-list)
 657                                         ; If the format for
 658                                         ; tempo-local-tags changes,
 659                                         ; change this
 660                                            (eval (car tag-list))))
 661                                tempo-local-tags))))
 662     (setq tempo-dirty-collection nil)))
 663
 664 ;;;
 665 ;;; tempo-find-match-string
 666
 667 (defun tempo-find-match-string (finder)
 668   "Find a string to be matched against a tag list.
 669 FINDER is a function or a string. Returns (STRING . POS), or nil
 670 if no reasonable string is found."
 671   (cond ((stringp finder)
 672          (let (successful)
 673            (save-excursion
 674              (or (setq successful (re-search-backward finder nil t))
 675                  0))
 676            (if successful
 677                (cons (buffer-substring (match-beginning 1)
 678                                        (match-end 1)) ; This seems to be a
 679                                         ; bug in emacs
 680                      (match-beginning 1))
 681              nil)))
 682         (t
 683          (funcall finder))))
 684
 685 ;;;
 686 ;;; tempo-complete-tag
 687
 688 (defun tempo-complete-tag (&optional silent)
 689   "Look for a tag and expand it.
 690 All the tags in the tag lists in `tempo-local-tags'
 691 \(this includes `tempo-tags') are searched for a match for the text
 692 before the point.  The way the string to match for is determined can
 693 be altered with the variable `tempo-match-finder'. If
 694 `tempo-match-finder' returns nil, then the results are the same as
 695 no match at all.
 696
 697 If a single match is found, the corresponding template is expanded in
 698 place of the matching string.
 699
 700 If a partial completion or no match at all is found, and SILENT is
 701 non-NIL, the function will give a signal.
 702
 703 If a partial completion is found and `tempo-show-completion-buffer' is
 704 non-NIL, a buffer containing possible completions is displayed."
 705
 706   ;; This function may look like a hack, but this is how I want it to
 707   ;; work.
 708   (interactive "*")
 709   (let* ((collection (tempo-build-collection))
 710          (match-info (tempo-find-match-string tempo-match-finder))
 711          (match-string (car match-info))
 712          (match-start (cdr match-info))
 713          (exact (assoc match-string collection))
 714          (compl (or (car exact)
 715                     (and match-info (try-completion match-string collection)))))
 716     (if compl (delete-region match-start (point)))
 717     (cond ((null match-info) (or silent (ding)))
 718           ((null compl) (or silent (ding)))
 719           ((eq compl t) (tempo-insert-template
 720                          (cdr (assoc match-string
 721                                      collection))
 722                          nil))
 723           (t (if (setq exact (assoc compl collection))
 724                  (tempo-insert-template (cdr exact) nil)
 725                (insert compl)
 726                (or silent (ding))
 727                (if tempo-show-completion-buffer
 728                    (tempo-display-completions match-string
 729                                               collection)))))))
 730
 731
 732 ;;;
 733 ;;; tempo-display-completions
 734
 735 (defun tempo-display-completions (string tag-list)
 736   "Show a buffer containing possible completions for STRING."
 737   (if tempo-leave-completion-buffer
 738       (with-output-to-temp-buffer "*Completions*"
 739         (display-completion-list
 740          (all-completions string tag-list)))
 741     (save-window-excursion
 742       (with-output-to-temp-buffer "*Completions*"
 743         (display-completion-list
 744          (all-completions string tag-list)))
 745       (sit-for 32767))))
 746
 747 ;;;
 748 ;;; tempo-expand-if-complete
 749
 750 (defun tempo-expand-if-complete ()
 751   "Expand the tag before point if it is complete.
 752 Returns non-nil if an expansion was made and nil otherwise.
 753
 754 This could as an example be used in a command that is bound to the
 755 space bar, and looks something like this:
 756
 757 (defun tempo-space ()
 758   (interactive \"*\")
 759   (or (tempo-expand-if-complete)
 760       (insert \" \")))"
 761
 762   (interactive "*")
 763   (let* ((collection (tempo-build-collection))
 764          (match-info (tempo-find-match-string tempo-match-finder))
 765          (match-string (car match-info))
 766          (match-start (cdr match-info))
 767          (exact (assoc match-string collection)))
 768     (if exact
 769         (progn
 770           (delete-region match-start (point))
 771           (tempo-insert-template (cdr exact) nil)
 772           t)
 773       nil)))
 774
 775 (provide 'tempo)
 776
 777 ;;; tempo.el ends here