lisp/tempo.el

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