Changes to completing-read

Changes to completing-read

[Phil Hagelberg]

I've been building a couple tools that use the completing-read function
for more advanced completions, and I've got some questions about how it
behaves when a function is passed as the "collection" argument.

From the completing-read docstring:

> collection can also be a function to do the completion itself.
> predicate limits completion to a subset of collection.
> See `try-completion' and `all-completions' for more details
>  on completion, collection, and predicate.

It looks like the function gets called four times when the user presses
TAB, and the only difference between the four calls is the last
argument. t, nil, 'lambda, and the cons (boundaries . "") are
passed. According to the docstrings of try-completion and
all-completions, t and nil should be passed to the collection function
when those two functions get called as part of the completion process
somehow. But I have no idea where 'lambda or (boundaries . "") are
coming from.

From the try-completion docstring:

> Return common substring of all completions of string in collection.
> Test each possible completion specified by collection
> to see if it begins with string.

From the all-completions docstring:

> Search for partial matches to string in collection.
> Test each of the possible completions specified by collection
> to see if it begins with string.

It's rather unclear from the docstrings, but from what I can piece
together, the "collection" function should act totally differently based
on the value of the third argument.

So it seems there are really three problems:

* The description overall behaviour of the "collection" function is spread
  out over three separate docstrings and is even then not very clear.

* One function (collection) is supposed to perform four distinct tasks
  based on the value of one of its arguments. (Though this is probably
  justified for backwards-compatibility reasons; seems fairly
  understandable.)

* Only two of the four tasks that the function is supposed to perform are
  documented at all.

Is this accurate? Could someone explain the meaning of the mystery
arguments? I would like to submit a documentation patch, but I feel that
my understanding of the subject is very sketchy, and the implementation
is in C, so I can't just dive in and understand it.

thanks,
Phil

Re: Changes to completing-read

[Eli Zaretskii]

> From: Phil Hagelberg <phil@hagelb.org>
> Date: Sat, 18 Oct 2008 21:31:21 -0700
> 
> Is this accurate? Could someone explain the meaning of the mystery
> arguments?

Does it help to read the "Programmed Completion" node in the ELisp
manual?

In general, when writing Lisp programs, it is not recommended (and is
not enough) to read only the doc strings.  The ELisp manual is a
required reading as well.

Re: Changes to completing-read

[Phil Hagelberg]

Eli Zaretskii <eliz@gnu.org> writes:

>> Is this accurate? Could someone explain the meaning of the mystery
>> arguments?
>
> Does it help to read the "Programmed Completion" node in the ELisp
> manual?
>
> In general, when writing Lisp programs, it is not recommended (and is
> not enough) to read only the doc strings.  The ELisp manual is a
> required reading as well.

Yes, of course. I should have checked there first, but I've had
surprisingly good luck sticking with docstrings and source in the
past. The manual is missing the meaning of the "boundaries" argument,
but that's understandable as the release of version 23 is still several
months away.

-Phil

Re: Changes to completing-read

[Stefan Monnier]

> It looks like the function gets called four times when the user presses
> TAB, and the only difference between the four calls is the last
> argument. t, nil, 'lambda, and the cons (boundaries . "") are
> passed. According to the docstrings of try-completion and
> all-completions, t and nil should be passed to the collection function
> when those two functions get called as part of the completion process
> somehow. But I have no idea where 'lambda or (boundaries . "") are
> coming from.

The `lambda' is when the function is called by `test-completion'.
The `boundaries' is a new functionality, still undocumented.

> It's rather unclear from the docstrings, but from what I can piece
> together, the "collection" function should act totally differently based
> on the value of the third argument.

That's right.  A better way to think of it might be that the "function"
is an object (in the OO sense), and the last arg is the method to
be executed.


        Stefan

Re: Changes to completing-read

[Phil Hagelberg]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> The `lambda' is when the function is called by `test-completion'.
> The `boundaries' is a new functionality, still undocumented.

Thanks. I guess this will be documented before the release?

Could someone explain the meaning of `boundaries' please?

>> It's rather unclear from the docstrings, but from what I can piece
>> together, the "collection" function should act totally differently based
>> on the value of the third argument.
>
> That's right.  A better way to think of it might be that the "function"
> is an object (in the OO sense), and the last arg is the method to
> be executed.

That sounds reasonable. If that way of explaining it could be used in
the documentation I think it could be very helpful.

-Phil

Re: Changes to completing-read

[Stefan Monnier]

>> The `lambda' is when the function is called by `test-completion'.
>> The `boundaries' is a new functionality, still undocumented.

> Thanks. I guess this will be documented before the release?

Of course.

> Could someone explain the meaning of `boundaries' please?

There's an attempt in the comment at the top of lisp/minibuffer.el.
And here's another attempt:

Consider a completion table such as the one used for file names, where
the string to complete is conceptually divided into several subparts.
In such a case the *Completions* buffer may only want to show the
relevant affected subparts rather than complete copies.  I.e. if you
complete /usr/s, all-completions may prefer to return '("sbin" "share" "src")
rather than ("/usr/sbin" "/usr/share" "/usr/src").

In order for the completion functions to be able to know how to
correctly interpret this abbreviated list (e.g. such that when you
middle-click in the *Completions* buffer, the "share" string only
replaces the "s" rather than the whole "/usr/s"), there needs to be
a way to know the position of the boundary between the prefix that's
elided and the subpart whose possible completions are returned by
`all-completions'.  Calling the completion table with (boundaries
. SUFFIX) should return that boundary info.

Now "what's this SUFFIX thingy", you'll say.  Here's the deal:
all-completions will return all the relevant completions for the
relevant subpart, but the relevant subpart may not be the end of
the completion.  E.g. all-completions on "/usr/s" will only return
"share" and not "share/zoneinfo/Canada/Eastern".  So calling the
file completion table with (boundary . "e/zoneinfo") will indicate that
the returned values only cover the "e" part of the SUFFIX.


        Stefan