bug#81624: New command: xref-find-by-kind

On 17/08/2026 13:14, João Távora wrote:

>> I would expect these commands to stay around for a while, but
>> delegating them to the current xref backend seems wrong?
> 
> I see, but not sure aout that.  Not sure other backends would have the
> particulra LSP kinds.  If they did, it was probably intentional setup by
> the user (who setup up eglot-stay-out to leave xref alone).  And in that
> case, probably fine to use the non-LSP versio.  Probably fine either
> way.  There's nothing of the kind I've heard off, so a moot problem for
> now.

Using the same kinds is very likely (could be lsp-mode, or could even be 
etags backend augmented to detect declarations/implementations), but 
overall the combined scenario seems rare enough, no argument there.

>> If they *were* made generic, we might want them renamed to proper
>> xref-find-*, and IIRC you argued against having built-in commands
>> encoding the list of kinds in xref core. So for the below examples
>> with 'xref-define-finder', do you envision them living in the user
>> init scripts?
> 
> Except for "definition" and "reference" I don't think,
> xref-find-<lsp-specific-thing> or xref-find-<language-x-specific-thing>
> should exist, no :-).

Let's keep that in mind. :)

>> to define them early. Here's what these definitions would look like,
>> in all their plan function glory:
> 
>> (defun eglot-find-declaration (identifier)
>>    "Find declarations for IDENTIFIER."
>>    (interactive (list (xref--read-identifier "Find declarations of: ")))
>>    (xref-find-by-kind identifier '(:kind declaration :name "declaration")))
> 
> That works perfectly, and I can do the macro in Eglot if useful.  Except
> for the use of the '--' function.  Can you export it?  I can bend the
> rules a little bit and use your private function anyway, wouldn't be the
> first time.

Okay! I've pushed the rename to without '--' just now. People seem to 
want to use it, and it hasn't changed for some time.

>> A bit longer. But if the list of kinds does not grow, and stays at
>> three elements for years for the vast majority of people (I've checked
>> out updates to LSP and new servers, and no new kinds have appeared in
>> the last 3 years), then maybe the saving won't be large.
> 
> It's fine.  And if the list does grow, I'll make the macro myself.

Very good.

In any case, I think the key is to decide on the functional interface. 
Any macros can be added on top afterwards.

>> Happy to discuss the options in both directions.
>>
>> My personal feeling though is that the command xref-find-by-kind can
>> serve as a good replacement for a submap, with dispatch taking the
>> same number of keys, so the need for additional commands would be
>> limited to exceptional cases. Or would many users not group them in a
>> submap anyway?
> 
> I haven't tried it but it looks fine in general. It seems to be backward
> compatible to everything Eglot does and adds a resonable small amount of
> code to it, and that code is legible.

Thanks.

>>> :format key entry in the kind
>>>      (:kind declaration :name "declaration" :key ?d :prompt-format
>>> "Find %s of")
>>> Not sure it's worth it, but not very hard to do either, I suppose.
>> That should work, thanks! I'm not sure about the tradeoffs, but it's a
>> good solution if the problem really bites.
> 
> Probably no drawbacks other than a small amount of complexity.  But no
> gigantic gain either.  I don't think anyone will ever complain, if you
> do it it'll just read a little nicer.
Fair enough - added.

Speaking of minor complexities and gains. I've deliberated on whether 
the second argument to xref-find-by-kind should be KIND-DESC like now, 
or just KIND (symbol). It was originally the latter which reads nicer, 
but then both the interactive form and the function body have to 
traverse the list of plists, and that felt wasteful.

Couldn't really decide, flipped a coin. But if we flip it back, the 
command definitions get even smaller:

   (defun eglot-find-declaration (identifier)
     "Find declarations for IDENTIFIER."
     (interactive (list (xref-read-identifier "Find declarations of: ")))
     (xref-find-by-kind identifier 'declaration))