code.delx.au - gnu-emacs/blob - lisp/tempo.el

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