completion-all-completions-with-base-size

completion-all-completions-with-base-size

[Eli Zaretskii]

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'.  Only
`completion-all-completions' and a couple of internal functions
consult that variable.  But `completion-all-completions' is not
documented in the ELisp manual, as are most of other APIs in
minibuffer.el (should they be documented?), so it sounds like the
above NEWS entry does not warrant any documentation in the manuals?
Why then it was added to NEWS?

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: 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.

> 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, ...

> 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).

I hope to be able to find the time to revisit this specific
completion-all-completions-with-base-size before the release, because
I believe that with the `boundaries' thingy I added later,
completion-all-completions-with-base-size might have become unnecessary.


        Stefan

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

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: emacs-devel@gnu.org
> Date: Sat, 18 Oct 2008 15:31:18 -0400
> 
> > 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?

> 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?

> > 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.

> > 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.

Thanks.

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

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

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: emacs-devel@gnu.org
> Date: Sat, 18 Oct 2008 17:55:14 -0400
> 
> >> > 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.

If these are the only situations, then I don't think
completion-all-completions-with-base-size warrants to be documented in
the ELisp manual.  Whoever uses functions from minibuffer.el for
completion tables ought to know about this variable and its role.

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

[Stefan Monnier]

>> >> > 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.

> If these are the only situations, then I don't think
> completion-all-completions-with-base-size warrants to be documented in
> the ELisp manual.  Whoever uses functions from minibuffer.el for
> completion tables ought to know about this variable and its role.

As mentioned, I hope it'll actually disappear.  But in the mean time,
the effect of completion-all-completions-with-base-size can sometimes be
exposed to code which knows nothing about the new minibuffer.el code.


        Stefan

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

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: emacs-devel@gnu.org
> Date: Sat, 18 Oct 2008 21:59:37 -0400
> 
> >> 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.
> 
> > If these are the only situations, then I don't think
> > completion-all-completions-with-base-size warrants to be documented in
> > the ELisp manual.  Whoever uses functions from minibuffer.el for
> > completion tables ought to know about this variable and its role.
> 
> As mentioned, I hope it'll actually disappear.  But in the mean time,
> the effect of completion-all-completions-with-base-size can sometimes be
> exposed to code which knows nothing about the new minibuffer.el code.

The ELisp manual does not need to mention every subtlety of every
obscure variable.