Re: completion-all-completions-with-base-size

[Stefan Monnier]

>> > This NEWS entry:
>> >     *** `all-completions' may now return the base size in the last cdr.
>> >     Since this means the returned list is not properly nil-terminated, this
>> >     is an incompatible change and is thus enabled by the new variable
>> >     completion-all-completions-with-base-size.
>> 
>> > is inaccurate: `all-completions' does not take into account the value
>> > of `completion-all-completions-with-base-size'.
>> 
>> IIUC, this is not relevant:

> Sorry, I'm not following: what isn't relevant, and to what?

Whether or not all-completions looks at
completion-all-completions-with-base-size is not relevant.  What is
relevant is that its return value may depend on this variable.

>> the base-size is always 0 (in which case
>> it's not necessary to add it) for all completion tables except
>> functional ones.  So of course all-completions doesn't take it into
>> account: only the functional completion tables do.
>> 
>> Still, the value returned by all-completions can contains such `cdr's
>> and it depends on completion-all-completions-with-base-size.
>> 
>> > Only `completion-all-completions' and a couple of internal functions
>> > consult that variable.
>> 
>> `completion-all-completions' does not consult it: it sets it.

> Now you lost me completely.  Could you please describe one scenario
> and the corresponding sequence of function calls which would cause
> all-completions (either what it does or the values it returns) to
> depend on completion-all-completions-with-base-size?

completion-all-completions sets the var so as to all functional table to
use the expanded calling convention, which means for example that
completion-table-with-context (which is a helper function to write
functional completion tables and for that reason is usually called
from/via try-completion, all-completions, test-completion) will include
the base-size in the cdr.

>> > But `completion-all-completions' is not documented in the ELisp
>> > manual, as are most of other APIs in minibuffer.el (should they be
>> > documented?),
>> 
>> I don't see why they should be documented there.  The entry points are
>> the same as before (and are documented): minibuffer-complete,
>> minibuffer-complete-word, ...

> Yes, but all-completions _is_ described, as are try-completion and
> test-completion.  The ELisp manual describes not only high-level entry
> points, but also the low-level primitives, where that may help a Lisp
> programmer to write yet another higher-level completion function.

I agree.  We may want to expose more of the internals, but I don't think
it's indispensible for now.  If you have specific suggestions of
functions in minibuffer.el which we should expose, we could
consider them.

>> > so it sounds like the above NEWS entry does not warrant any
>> > documentation in the manuals?  Why then it was added to NEWS?
>> 
>> Because some functions may call all-completions in a context where
>> someone has set completion-all-completions-with-base-size
>> (e.g. when all-completions is used internally by a functional
>> completion table), in which case it may be surprised by the extra `cdr'
>> (which could cause `length' or `mapcar' to signal an error).

> Well, I'm probably missing something, because I couldn't see how what
> all-completions returns could depend on
> completion-all-completions-with-base-size.  Please help me
> understand that.

Again, it's only in the case where the completion table is a function,
and only if that function depends on
completion-all-completions-with-base-size.


        Stefan