Re: dynamic-completion-table

[Roland Winkler]

On Fri Jun 20 2003 Richard Stallman wrote:
>       "Turn a function FUN returning a completion table, into a completion 
> table.
> 
> That sentence is very confusing--you need to say it a different
> way.

I suggest the following. I hope that the new docstring is less
confusing.

Note also that I modified the code: FUN is called with one argument,
the string for which completion is required. Furthermore, in order
to avoid name conflicts make-symbol is used to create local
variables.

(defmacro dynamic-completion-table (fun)
  "Use function FUN as a dynamic completion table.
FUN is called with one argument, the string for which completion is required,
and it should return an alist containing all the intended possible
completions. If completion is performed in the minibuffer, FUN will be called
in the buffer from which the minibuffer was entered.
`dynamic-completion-table' then computes the completion, see Info
node `(elisp)Programmed Completion'."
  ;; (declare (debug t))
  (let ((win (make-symbol "window"))
        (string (make-symbol "string"))
        (predicate (make-symbol "predicate"))
        (mode (make-symbol "mode")))
    `(lambda (,string ,predicate ,mode)
       (with-current-buffer (let ((,win (minibuffer-selected-window)))
                              (if (window-live-p ,win) (window-buffer ,win)
                                (current-buffer)))
         (cond
          ((eq ,mode t) (all-completions ,string (,fun ,string) ,predicate))
          ((not ,mode) (try-completion ,string (,fun ,string) ,predicate))
          (t (test-completion ,string (,fun ,string) ,predicate)))))))

>     I use dynamic-completion-table to define the global initial values
>     of buffer-local variables that contain completion lists. The idea is
>     that if the user hits tab, FUN calculates the completion list and
>     stores it in the buffer-local variables.
> 
> Should this macro produce the code to do that?
> It might be more useful that way.

I think it is conceptually cleaner to create lazy completion tables
by means of a second macro that uses dynamic-completion-table. My
suggestion is the following:

(defmacro lazy-completion-table (var fun &rest args)
  "Initialize variable VAR as a lazy completion table.
If the completion table VAR is used for the first time (e.g., by passing VAR
as an argument to `try-completion'), the function FUN is called with arguments
ARGS. FUN must return the completion table that will be stored in VAR. If
completion is requested in the minibuffer, FUN will be called in the buffer
from which the minibuffer was entered. The return value of
`lazy-completion-table' must be used to initialize the value of VAR."
  (let ((str (make-symbol "string")))
    `(dynamic-completion-table
      (lambda (,str)
        (unless (listp ,var)
          (setq ,var (funcall ',fun ,@args)))
        ,var))))

Then a typical application of lazy-completion-table is the following:

(defvar bibtex-reference-keys
  (lazy-completion-table bibtex-reference-keys bibtex-parse-keys nil nil t)
  "Completion table for BibTeX reference keys.")
(make-variable-buffer-local 'bibtex-reference-keys)


Is this code useful for other packages, too so that the above macros
should be made available, e.g., in simple.el?

Suggestions welcome!

Roland