minibuffer completion functions [was: iswitchb]

[Drew Adams]

> The completion package that I use (and that I ultimately would like to
> install as the default, tho it needs a lot of work or a rewrite) does
> the following:
> 1 - first try completion the old way.
> 2 - if that fails, try completion the partial-completion-mode way.
> 3 - if that fails, try it with a substring search.

I certainly hope that will _not_ be adopted as the default behavior. Add it
as another, alternative behavior, if you like, but please leave the default
behavior alone.

It is not necessarily the case that a user or a Lisp caller of
`completing-read' (or another completing function) _wants_
partial-completion or substring completion to occur when the standard prefix
completion fails. There must be a way to get today's default behavior (and
that way should remain the default behavior).


The change that I would like to see for minibuffer completion is just to
have `completing-read' and `read-file-name' do the following:

1. Retain their current signatures (arg lists) - no change.

2. Funcall the value of a global variable: `completing-read-fn' or
`read-file-name-fn', if non-nil, to perform the completion. Else call a
default completing function, `completing-read-default' or
`read-file-name-default'.

That is, move the current behavior of `completing-read' and `read-file-name'
to new functions that perform that behavior as the default case. Change the
current completion functions to be just wrappers that call either the value
of a variable or the default function.

This simple change would keep the behavior we have now as the default. But
it would also allow flexibility for packages and users that want to use
different completion mechanisms, and it would help such packages play better
together.


Example: Icicles (just an example that I'm familiar with) and Viper mode
each adapt `read-file-name', in different ways, for their own use. Icicles
does this by redefining `read-file-name' when in Icicle mode (it is restored
when you leave the mode). Viper does it by advising `read-file-name'. If you
load Icicles first, the two play well together; if you load Viper first,
they do not, obviously. Neither redefining nor advising is a great approach
here, IMO.

With what I propose, a package can define its own completion function. That
function would have the same signature as `read-file-name' (or
`completing-read'), and it would bind or set its completion function as the
value of `read-file-name-fn', for use in some context (e.g. a minor mode).

This function definition for a package could then, to do part of its job,
call either `read-file-name-default' or the function that was the current
value of `read-file-name-fn' at the time of the package's own definition of
that variable. Or it could just do its own thing altogether, from scratch.
That is, the package's completion function could reuse the existing
completion mechanism (default or current) in some way, or it could ignore it
altogether. This is similar to the various defadvice possibilities (before,
after, replace).

I think this would be a simple and clean way to provide flexibility for
minibuffer completion. It is an alternative to using advice that I think is
better, in this case.

You might ask why a package doesn't just define and then use its own
completion function - why have it make the standard `completing-read' or
`read-file-name' adopt the package's way of completing? The reason is that
by going through the standard Emacs completion functions as a dispatcher,
all code that calls `completing-read' or `read-file-name' can take advantage
of the package's completion mechanism.

This is why, for instance, Icicles redefines `completing-read', even though
its redefinition never calls the original `completing-read'. The idea is to
let users take advantage of Icicles completion everywhere that
`completing-read' (or `read-file-name') is used (while in Icicle mode). Your
code need not be rewritten to call `icicle-completing-read'; it is enough
that it calls `completing-read'.

I don't want to argue about this (but I'm willing to clarify or discuss it).
If you don't like such an approach, fine. But in that case, please at least
leave the signature and default behavior of `completing-read' and
`read-file-name' alone. Some users and some packages count on those
functions doing what they do now.

If you do adopt an approach like I suggest, then you can always write a mode
or package that does what you want (tries prefix-, then partial-, then
substring-completion), and your preferred behavior will be available to
users without altering the default behavior. Just like any other completion
package.