Nushell completions pack

This is a system for generating extern defs (tab-completion) in nu.

Background

The fish shell project has a long, complicated script for parsing man pages to gather completions definitions. Fortunately for us, Fish completions are defined in simple command line arguments, which we parse here and use to generate completions for Nu.

Installation and basic usage

1. Download and optionally install this script. For a prebuilt binary, use cargo-binstall...

   cargo binstall nu-completion-script
   

   ...or if you don't have cargo-binstall, download the release from the releases page on Github.

   You may also build from source using cargo install, or cloning the repository and building with cargo install. See Development Process for instructions.

2. Have fish installed.

3. From a fish shell, run

   fish_update_completions
   

4. Generate the nu definitions.

   nu-completions ~/.local/share/fish/generated_completions/*.fish
   

5. Source the definitions

   nu-completions --install
   

Reporting bugs

If an error occurs, please run your command again with -vvvv, save the logs, and include them when submitting a Github Issue. For example, if an error occurs while running the above command to generate the definitions, run this command instead:

nu-completions -vvvv ~/.local/share/fish/generated_completions/*.fish | save log.json

And include the contents of log.json within a preformatted block, like this:

```json
{"level":30,"time":1677171831187,"msg":"beginning translation phase"}
{"level":30,"time":1677171831187,"msg":"processing file or directory","file":"../../../.local/share/fish/generated_completions/7z.fish"}
{"level":30,"time":1677171831187,"msg":"processing file","file":"../../../.local/share/fish/generated_completions/7z.fish"}
{"level":10,"time":1677171831187,"msg":"opened file for processing","file":"\"../../../.local/share/fish/generated_completions/7z.fish\""}

...

{"level":10,"time":1677171833182,"msg":"opened file for processing","file":"\"../../../.local/share/fish/generated_completions/java-openjdk8.fish\""}
{"level":50,"time":1677171833182,"msg":"error parsing shell words","line":"complete -c java-openjdk8 -o 'disablesystemassertions"}
{"level":50,"time":1677171833182,"msg":"failed to process completions at \"../../../.local/share/fish/generated_completions/java-openjdk8.fish\": missing closing quote"}
```

Development state

Since these definitions are auto-generated and incomplete, we need to modify the auto-generated output to provide additional application-specific functions to each definition. In order to provide a consistent workflow which smoothly (we hope) handles upstream man-page updates, these application-specific modifications take the form of a set of patches which are a part of this repository.

Development process

Note: These directions assume you're using Linux, and have git and cargo installed)

1. Fork this repository
2. Clone your fork and enter the directory

   git clone https://github.com/YOUR-GITHUB-USER/nu-completions.git
   cd nu-completions
   

3. Compile the binary

   cargo build --release
   

   Alternatively, install the latest release's prebuilt binary (requires cargo-binstall)...

   cargo binstall nu-completion-script
   

   ...or if you don't have cargo-binstall, download the release from the releases page on Github.
4. Have fish installed.
5. From a fish shell, run

   fish_update_completions
   

6. Generate the nu definitions.

   nu-completions ~/.local/share/fish/generated_completions/*.fish
   

7. Make the changes you want to whichever of the generated files you want.
8. Generate a patch (or patches) from your changes

   nu-completions --patch-dir=./patches patches generate ~/.local/share/fish/generated_completions/*.fish
   

9. Commit your changes, push them to your fork, and follow the link in your console to submit a pull request for the changes.