Dynamic completion for Nushell

[chklauser]

Please complete the following tasks

• I have searched the discussions
• I have searched the open and rejected issues

Clap Version

master

Describe your use case

Bash, zsh, fish, etc. have very cool support for dynamic completion. Dynamic completion is a huge boost to the usability of a tool.

The clap_complete_nushell crate doesn't support dynamic completion yet. While the "external" completion story in Nushell is still a bit shaky, it's nonetheless possible for Nushell to get completions from external programs. We just need to implement it.

Describe the solution you'd like

The source <(COMPLETE=nushell some-clap-binary --) pattern fundamentally won't work in Nushell. Nushell requires all code to be statically available in the file system before configuration gets loaded. This makes it a bit tricky to make installation of the dynamic completion support both convenient and "auto-updating" (in case a new version of a clap-based CLI gets installed).

Additionally, and unlike every other shell that we support, Nushell only supports a single, globally registered "external completer". For users, who want to have more than one external completer, the suggestion is to have a "meta-completer" that looks at the command line (first arg, which is the binary name) and dispatches the completion request to an appropriate completer.

A solution could look like this:
(1) The user asks the clap-based CLI tool to generate a "completion generator" source file

COMPLETE=nushell some-clap-tool -- | save --raw ~/.config/nushell/generate-some-clap-tool-completions.nu

This "completion generator" needs to be as stable and minimal as possible. It could look something like this:

COMPLETE=nushell COMPLETE_nu=module some-clap-tool -- | save --raw ($env.NU_LIB_DIRS.0 | path join some-clap-tool-completer.nu)

Each time env.nu is loaded, this writes an updated version of the actual completion hook. The additional COMPLETE_nu=module environment variable signals that the clap-based tool should generate the completion hook and not the "completion generator" file.

(2) The user (manually) includes this source file in their env.nu

# env.nu
source ./generate-some-clap-tool-completions.nu

(3) The user (manually) uses the regularly re-generated module in their config.nu

# config.nu
use some-clap-tool-completer
# and then EITHER
some-clap-tool-completer install
# OR
$env.config.completions.external.completer = { |spans| 
  if (some-clap-tool-completer handles $spans) {
    some-clap-tool-completer complete $spans
  } else {
    # other completers that the user wants to dispatch to
  }
}

Alternatives, if applicable

Autoload Directories
A hidden feature of Nushell. It will be officially documented in version 0.101. Files in those autoload directories get loaded after config.nu. They sound like a good target for completions except for the issue that there can only be one global completer. If we just plonk the clap-generated file into an autoload directory, we take away the user's control over how external completion works in their shell.

There are some upcoming changes to Nushell configuration.

Additional Context

Nushell docs

• External Completions
• Suggestion for the case of multiple completers
• Configuration (env.nu vs config.nu)

[epage]

Nushell requires all code to be statically available in the file system before configuration gets loaded. This makes it a bit tricky to make installation of the dynamic completion support both convenient and "auto-updating" (in case a new version of a clap-based CLI gets installed).

In #5668 (comment) there is discussion of lazy loading. Unsure if that would be sufficient for nushell.

Additionally, and unlike every other shell that we support, Nushell only supports a single, globally registered "external completer". For users, who want to have more than one external completer, the suggestion is to have a "meta-completer" that looks at the command line (first arg, which is the binary name) and dispatches the completion request to an appropriate completer.

Ouch, this sounds like a big limitation.

If I'm understanding correctly, we basically require users to hook us into their hand-written meta-completer? Not too ideal. Is there any talk about fixing this so custom completers can better coordinate and have a good out-of-the-box experience?