Plugin: support custom completions in command flags

[WindSoilder]

Closes: #15766

It's similar to #16383, but allows to generate completion dynamically, which can be useful for plugin commands.

To implement this, I added a new get_dynamic_completion method to Command trait, so nushell gets the ability to ask plugins for a completion. Here is how it goes when I type plugin-cmd --flag1 <tab>.

1. the completion logic detect it's behind a flag, and it should have a value, then it goes to ArgValueDynamicCompletion
2. inside ArgValueDynamicCompletion it calls get_dynamic_completion(ArgType::Flag(flag1)) on the command, which can be plugin command, and it will issue a get_dynamic_completion(ArgType::Flag(flag1)) call to the plugin
3. the plugin returns Some(Vec<DynamicSemanticSuggestion>) if there are available items.

It also supports dynamic completion for positional arguments, here is how it goes when I type plugin-cmd x<tab>.

1. the completion logic detect it's behind a flag, and it should have a value, then it goes to ArgValueDynamicCompletion
2. inside ArgValueDynamicCompletion it calls get_dynamic_completion(ArgType::Positional(0)) on the command, which can be plugin command, and it will issue a get_dynamic_completion(ArgType::Positional(0)) call to the plugin
3. the plugin returns Some(Vec<DynamicSemanticSuggestion>) if there are available items.

Release notes summary - What our users need to know

Plugin developer: auto completion is available for plugin command arguments.

User can define auto completions for plugin commands, here is the way to define this:

impl PluginCommand for FlagCompletion {
    type Plugin = ExamplePlugin;
    ...

    fn get_dynamic_completion(
        &self,
        _plugin: &Self::Plugin,
        _engine: &EngineInterface,
        arg_type: ArgType,
    ) -> Option<Vec<DynamicSemanticSuggestion>> {
        match arg_type {
            // enable completion for flag.
            ArgType::Flag(flag_name) => match flag_name {
                "flag1" => Some(vec!["flag_val1".to_string().into(), "flag_val2".to_string().into()]),
                "flag2" => Some(vec!["flag_val3".to_string().into(), "flag_val4".to_string().into()]),
                // for other flags don't need to provide a completion
                _ => None,
            },
            // enable completion for positional arguments.
            ArgType::Positional(index) => None,
        }
    }
}

For the detailed example, you can refer to get_dynamic_completion in crates/nu_plugin_example/src/commands/arg_completion.rs.

Tasks after submitting

• Update the documentation

[WindSoilder]

Looks good to me on the completions side, just some minor comments. Do you want someone else from the core team to review the plugin side?

Of course it's better if anyone is available, perhaps @devyn and @cptpiepmatz ?

[cptpiepmatz]

While reviewing this I wondered why this is even needed. We have custom completions for externals: https://www.nushell.sh/book/custom_completions.html#custom-completion-and-extern

I don't understand why we cannot use that in some smart way. Is it not dynamic or what is the issue here? Also even if we go with the direction of this PR (I like the impl so far, so I'm not against this PR itself), should we merge these two ideas?

I'm not sure if this was talked already in this PR in the comments somewhere, sorry if I overlooked that.

[WindSoilder]

Is it not dynamic or what is the issue here?

The main issue is that it's hard to get the internal state of a plugin, it may take a lot of effort to expose commands to query internal state.

[cptpiepmatz]

I see the issue. But how are the other completers implemented? Both feel to me as they try to solve very similar issues. Should we move the impl for them into this one, when this one lands?

[WindSoilder]

Not really, it's mainly for plugins, the plugin authors can add completion easily for there commands once it's landed

[ysthakur]

I don't understand why we cannot use that in some smart way. Is it not dynamic or what is the issue here?

The way custom completions work right now is, we parse a custom command whose parameters refer to some completers, and then we store the DeclId of the command for the custom completer with the parameter. But when defining a builtin command or a plugin command, there is no such DeclId available. So Commands can't use this existing mechanism to provide dynamic completions at the moment.

After this PR, builtins as well as plugin commands can provide dynamic completions, and then we can try having shared logic for this, the static completions added by Bahex (foo: string@[a b c]), and for custom completions.

[ysthakur]

Excited for this! Thanks for sticking with this @WindSoilder

[blindFS]

Actually @cptpiepmatz made me thinking that maybe it could/should be done at the Parameter level, instead of Command. If we need to call the command during dynamic completion, we can always resort to find_decl.

Anyways, I don't want to keep this PR on-hold for too long. We still get time to redesign it before the next release.

[WindSoilder]

Thanks for reviewing! I'm going to land it. Regards to this:

Hmm, I just realized that get_dynamic_completion doesn't get the buffer. Sorry to keep holding up this PR, but I think it'd be better if it also accepted the buffer/text typed by the user.
We don't need to pass in a span. Later, we can give plugins the ability to return spans, and then we would translate the span to a Reedline span with the right offset.

Let's keep the diff smaller, I can try to implement it in another pr.