Re: Updating *Completions* as you type

[Spencer Baugh <sbaugh@janestreet.com>]

Juri Linkov <juri@linkov.net> writes:
>> For buffers, for example, sorting by the buffer-list can be done by just
>> setting display-sort-function to identity, but we probably shouldn't
>> expose that fact to the user.  (We could expose a generic "sort by
>> defaults" but that would be less efficient.)
>
> It should be fine to use 'identity' as a value when the Customization UI
> will show a more meaningful tag like "Unsorted".

Yes, that's fine.  But "Unsorted" is different from "Sorted by
buffer-list", which is the behavior one gets with read-buffer.  In other
words, the documentation can be more specific for read-buffer-sort.

>> The sorting style might even require the sorting option to actually
>> change the completion table's behavior.  File name completion could be
>> sorted by mtime, for example, by having the completion table include
>> mtime as a text property when read-file-name-sort=mtime, and then
>> setting display-sort-function to something which reads that property.  I
>> think that can only work if we have separate sorting options.
>
> Also a separate option might be needed when a completion table
> supports a non-standard sorting order such as
> 'mule--ucs-names-sort-by-code' when 'read-char-by-name-sort'
> is customized to 'code'.  But the users still should have freedom
> to override all metadata: display-sort-function, affixation-function,
> group-function, etc.
>
>>>   (setopt completion-category-overrides
>>>     '((buffer (display-sort-function . minibuffer-sort-by-history))
>>>       (project-file (display-sort-function . minibuffer-sort-by-history))
>>>
>>> And default values could be specified in completion-category-defaults.
>>
>> I think the default values would be part of the completion table itself;
>> a completion table can just set display-sort-function itself, it doesn't
>> need completion-category-defaults to do that.
>
> OTOH, the completion table needs only to return its category in metadata.
> Otherwise every completion table of the same category would need to
> duplicate display-sort-function in its completing-read.

Interesting point.  In some sense, the category gives us an inheritance
mechanism for completion tables, where a completion table can just use
the defaults for its category rather than specifying all the details.
But if the completion table has some specific sorting function it wants,
it can provide that by explicitly returning it in the metadata.

And completion-category-overrides gives the user a way to do
customization of the category defaults.

So perhaps, for a given metadata, display-sort-function would be:

(or
 (alist-get 'display-sort-function metadata)
 (alist-get 'display-sort-function (alist-get category completion-category-overrides))
 (alist-get 'display-sort-function (alist-get category completion-category-defaults))
 completions-sort)

That makes sense to me.

And (alist-get 'display-sort-function metadata) is configurable with
separate completion-table-specific options, like read-buffer-sort.

If we do this, completions-sort acts like a "default" entry in
completion-category-defaults, which acts for categories which aren't
otherwise matched.  Which makes a lot of sense, and makes it behave like
completion-styles and completion-cycle-threshold.

I expect some disagreement about the following question: should
completion-category-overrides override the display-sort-function
returned by the completion table?  That is, should it instead be:

(or
 (alist-get 'display-sort-function (alist-get category completion-category-overrides))
 (alist-get 'display-sort-function metadata)
 (alist-get 'display-sort-function (alist-get category completion-category-defaults))
 completions-sort)

I think no.  The most specific customization (customizing an individual
completion table) should override more broad customizations (customizing
an entire category).  I don't think there's a reasonable use-case for
overriding a display-sort-function explicitly returned by a table - we
can just make that display-sort-function configurable directly.

We probably will want to make this clear in the documentation, of
course.

>> Maybe we should decide what things are supposed to be configured by
>> category and what things are supposed to be configured by the table
>> itself.  Because in theory we could allow setting completion-styles and
>> completion-cycle-threshold with completion table metadata, and I'm not
>> sure why we didn't do it that way - it could even be nice to have a
>> completion style which is specific to an individual completion table.
>
> I guess when an individual completion table needs to use metadata
> slightly different from other similar cases then it should provide
> a different category/subcategory.

Or the individual completion table just returns that slightly different
metadata itself, and it overrides the metadata pulled from its category.