Multi sources (like consult--multi, read multiple values (like consult-completing-read-multiple)?

[Hugo-Heagren]

I'm playing with the internal api, trying to build an interface to EMMS, and I have to say it's pretty comprehensive. I've had a look thougth, and there's one thing I can't find. The way I want to implement it is most natural with a function which allows both a list of multiple sources, like consult--multi does, and can admit of multiple selections like consult-completing-read-multiple. Does one of the commands do this already? (if so, it isn't very well documented, could this be improved?).

If not, would it be terribly hard to implement? I'd be happy to have a go and make a PR, though my elisp is still not massively advanced.

[minad]

The way I want to implement it is most natural with a function which allows both a list of multiple sources, like consult--multi does, and can admit of multiple selections like consult-completing-read-multiple. Does one of the commands do this already?

Such an API does not exist currently, since there is no need for it within Consult.

If not, would it be terribly hard to implement?

Probably it is not hard to implement this. One can either add a separate consult--read-many, which calls completing-read-multiple instead of completing-read, and a consult--multi-many on top of it. Or one can alternatively add a boolean flag argument :many to consult--read and consult--multi and adjust these functions accordingly to handle multiple selected candidates. But it may get a bit messy, completing-read-multiple is a messy and problematic API.

That being said, I generally want to avoid adding APIs which are not used by Consult itself. Furthermore completing-read-multiple is not a feature I generally encourage to use. It is not widely used within Emacs itself. It is maybe used ~10 times in comparison to completing-read which is used ~1000 times. The default implementation of completing-read-multiple does not work well with long candidate strings (which are typical of Consult) and the user interface offered by it is generally quite weak. Note that Consult comes with consult-completing-read-multiple which offers a better UI. But I am afraid that consult-completing-read-multiple wouldn't work too well with a hypothetical consult--read-many.

completing-read-multiple also doesn't integrate well with other packages like Embark. Ideally we figure out a better solution for multi-selections which relies on Embark and plain completing-read. This would be quite useful since it would allow normal completing-read commands like find-file to be used with multiple candidates. For example if you are in find-file you could select multiple files and then trigger Embark to open all of the selected files at once. Embark would then run find-file itself on each of the selected candidates in turn, simulating the multiple candidate command in that way. So what I want to say here - completing-read-multiple seems mostly like an unnecessary API. Just write a usual single-candidate completing-read command and use Embark for actions (and maybe in the future simulated multi selections). So far no work has been done in this direction - and it is difficult! It would involve changes in Embark and/or maybe also in the UI itself (like Vertico) to allow selecting multiple candidates there. Nevertheless this approach would be my preferred way forward. See oantolin/embark#166 and oantolin/embark#253 for existing issues about multiple candidate selections in Embark.

@bdarcus who made the Citar package, asked before about a consult--multi-completing-read-multiple variant. His Citar package is centered around completing-read-multiple. So in any case - for now it works if you don't rely on Consult for your implementation and just implement your package or command on top of completing-read(-multiple) directly as Citar is doing.