Custom arguments completion for commands created by LLDB plugins

Is there a way to create custom argument completion handlers for
commands introduced by LLDB plugins? I want to add completion for some
commands on llnode (https://github.com/nodejs/llnode), but I couldn't
find a way to do so using the C++ public API.

Based on this comment
(https://github.com/llvm/llvm-project/blob/d420616313a3b4bc95a9effa00363cf3ad953e61/lldb/include/lldb/Interpreter/CommandCompletions.h#L44-L47)
I was expecting some API to add custom completion handlers, but I
guess the comment is intended for internal development only?

If there isn't a way to do that today, I'm thinking about adding it as
a new method to SBCommandPluginInterface, unless someone objects to
it.

To my knowledge there is no way to have completions for custom commands. If you just want completions for nested commands (e.g., having a “custom add” and “custom remove” commands and want completions for completing “add” and “remove”), then this should work if you build the nested command using the SBCommand::Add[Multiword]Command functions. However, that won’t allow you to provide arbitrary completions for arguments.

Regarding your planned change: Adding a new virtual method would break the ABI of SBCommandPluginInterface and the SBAPI is supposed to have a stable ABI. So I guess we have two options.
1. break the ABI for this class and somehow let people know they need to recompile their plugins for the next release.
2. add a new overload to the existing AddCommand methods and allow passing some kind of interface for completions. Custom command classes just inherit from both interfaces if they want to provide their own completions.

I’m fine with either option, but if we end up going for option 1, then IMHO we might as well change the API of this class as it’s current DoExecute function is just wrong. It returns an undocumented ‘bool’ value which seems to provide redundant information to the success status of the result parameter and we pass it a `char **` parameter which actually has `const char **` semantics as changing it corrupts LLDB’s internal `Args` data structure.

In any case I would prefer if we wait with landing this API until I fully cleaned up LLDB's completion logic and we got around to set in stone the new HandleCompletion API (which gives us an overview of what kind of completions clients want to receive and in what format). Both should happen for LLDB 10 if everything goes right, so this shouldn’t delay adding this feature.

- Raphael

(Resending this as my other email got blocked by lldb-dev somehow)

To my knowledge there is no way to have completions for custom commands. If you just want completions for nested commands (e.g., having a “custom add” and “custom remove” commands and want completions for completing “add” and “remove”), then this should work if you build the nested command using the SBCommand::Add[Multiword]Command functions. However, that won’t allow you to provide arbitrary completions for arguments.

Regarding your planned change: Adding a new virtual method would break the ABI of SBCommandPluginInterface and the SBAPI is supposed to have a stable ABI. So I guess we have two options.
1. break the ABI for this class and somehow let people know they need to recompile their plugins for the next release.
2. add a new overload to the existing AddCommand methods and allow passing some kind of interface for completions. Custom command classes just inherit from both interfaces if they want to provide their own completions.

I don't think that's the right way to handle completions for custom commands. Custom commands already suffer from the fact that they have to parse their own arguments and options, so they don't work like lldb commands. We can't do their help correctly because we don't know this info, and if they used any of the common completion types, they would have to reimplement them.

Instead of adding another ad hoc behavior that the builtin lldb commands don't use, we should really allow custom commands to be regular LLDB commands, by having some API the command can call when added to set up its arguments and options. The these could get built in the command table just like the built-in lldb commands, and lldb could handle the help and completions. For all the known completion types, you could then just say "This is a file" or "This is a symbol" etc. and lldb would handle the completion. And if you have a custom completion callback for some argument, you would just provide a function pointer to the "AddOption" or "AddArgument" API's.

Jim

Nested command completion works. I want to complete parameters of
commands based on information from the debugged process (attributes of
an object, etc.).

1. break the ABI for this class and somehow let people know they need to recompile their plugins for the next release.

I'd rather not break ABI just for this change.

2. add a new overload to the existing AddCommand methods and allow passing some kind of interface for completions. Custom command classes just inherit from both interfaces if they want to provide their own completions.

I like this idea. Multiple commands with same parameter types could
reuse the same completion class . We would need to overload AddCommand
on SBCommandInterpreter and SBCommand.

There are two other options similar to option two:

1. Add a new method to SBCommand to attach a completion class to it
(AddCompletion, for example).
2. Overload the constructor of SBCommandPluginInterface to receive a
pointer to a completion class instance, and save it as a private
member.

In any case I would prefer if we wait with landing this API until I fully cleaned up LLDB's completion logic and we got around to set in stone the new HandleCompletion API (which gives us an overview of what kind of completions clients want to receive and in what format). Both should happen for LLDB 10 if everything goes right, so this shouldn’t delay adding this feature.

I'm fine with waiting. I already have a POC adding a method to
SBCommandInterpreter, shouldn't be hard to change it to one of the
other options. If you don't mind, I can also send a patch with
whichever option we choose, the changes are non-intrusive and they
probably wouldn't get in the way of refactoring LLDB's completion
logic (if they do get in the way we can hold on landing it until
refactor is complete).

Jim just ninja’d the discussion with his point that we could add methods for adding command completions to existing commands and I actually agree that’s the better idea (especially since this is abstracting away the actual option parsing from the user and it can be better integrated into the current option infrastructure in the future). Having said that, I think we should still take another look at the SBCommandPluginInterface and at least document how the user is supposed to implement that interface.

- Raphael