# Shell Completions
RSConstruct generates shell completion scripts that provide tab-completion for commands, subcommands, flags, and argument values.
## Generating Completions
```bash
# Generate for the default shell (configured in rsconstruct.toml)
rsconstruct complete
# Generate for a specific shell
rsconstruct complete bash
rsconstruct complete zsh
rsconstruct complete fish
```
To install, source the output in your shell profile:
```bash
# Bash (~/.bashrc)
eval "$(rsconstruct complete bash)"
# Zsh (~/.zshrc)
eval "$(rsconstruct complete zsh)"
# Fish (~/.config/fish/config.fish)
rsconstruct complete fish | source
```
## Configuration
The default shell(s) for `rsconstruct complete` (with no argument) are configured in `rsconstruct.toml`:
```toml
[completions]
shells = ["bash"]
```
## What Gets Completed
### Commands and subcommands
All top-level commands (`build`, `processor`, `analyzer`, `tool`, etc.) and their subcommands complete automatically via clap, in every shell.
### Processor type names (pnames)
Arguments that take a processor type name complete with the full names from the plugin registry (`processor.checker.ruff`, `processor.generator.cc_single_file`, ...):
- `rsconstruct processor add <TAB>`
- `rsconstruct processor defconfig <TAB>`
- `rsconstruct processor info <TAB>`
These arguments carry `#[arg(value_parser = crate::registries::processor_name_parser())]`, a `PossibleValuesParser` built from the registry when the completion script is generated, so clap embeds the list in the script itself. The bash and zsh scripts complete them; the fish script that clap generates carries possible values only for options, not positionals, so pnames do not complete there. Because the list is a `value_parser`, an unknown pname is also rejected at parse time with the list of valid ones.
### Processor instance names (inames)
Arguments that take a processor instance name complete with the section headers declared in the current directory's `rsconstruct.toml` (`processor.checker.ruff`, `processor.checker.ruff.core`, ...):
- `rsconstruct processor config <TAB>`
- `rsconstruct processor delete <TAB>`
- `rsconstruct processor disable <TAB>`
- `rsconstruct processor enable <TAB>`
- `rsconstruct processor files <TAB>`
- `rsconstruct build --processor <TAB>` / `rsconstruct build -p <TAB>`
- `rsconstruct build --exclude-processor <TAB>` / `rsconstruct build -x <TAB>`
- `rsconstruct watch --processor <TAB>` / `rsconstruct watch -p <TAB>`
- `rsconstruct watch --exclude-processor <TAB>` / `rsconstruct watch -x <TAB>`
`build`/`watch` `-p` and `-x` complete inames, not pnames: you can only build a processor that the project declares. Instance names are extracted from every `[processor.…]` heading in `rsconstruct.toml` at tab-completion time by a shell helper (`_rsconstruct_inames`) that the generated script carries; sub-tables that are config fields (`[processor.generator.tags.field_types]`) come out too, and the build rejects them with a clear message. Requires a `rsconstruct.toml` in the current directory. **Bash only** — zsh and fish get clap's default completion for these arguments.
### Analyzer type names (pnames)
- `rsconstruct analyzer add <TAB>`
- `rsconstruct analyzer defconfig <TAB>`
These carry `#[arg(value_parser = crate::registries::analyzer_name_parser())]`, a `PossibleValuesParser` over every registered analyzer (as listed by `rsconstruct analyzer list`), with the same per-shell behaviour as processor pnames.
### Analyzer instance names (inames)
- `rsconstruct analyzer delete <TAB>`
- `rsconstruct analyzer disable <TAB>`
- `rsconstruct analyzer enable <TAB>`
Instance names are read from the `[analyzer.NAME]` and `[analyzer.NAME.SUB]` headings in `rsconstruct.toml` at tab-completion time by the `_rsconstruct_analyzer_inames` helper. Bash only.
`analyzer config <INAME>` and `analyzer clean --analyzer <INAME>` have no completion of their values: their arguments are plain strings without a `value_parser` and are not injection targets.
### Flags and options
All `--flags` and `-f` short flags complete in all shells via clap's built-in generation, as do the values of `value_enum` options (`--color`, `-O`, `-I`, `-P`, `--stop-after`, `graph show --format`, ...).
## Implementation
Completions are generated by `clap_complete` in `src/cli.rs` (`generate_completion_script`). Two mechanisms provide argument-value completions:
### 1. clap `value_parser`
For a set of values that is known when the script is generated, the field carries `#[arg(value_parser = ...)]` and clap embeds the values in the script. The processor and analyzer registries are built by `inventory` at runtime, so their parsers are constructed from the registry rather than written as a literal list:
```rust
/// Show default configuration for a processor type by pname (no config needed)
Defconfig {
#[arg(value_parser = crate::registries::processor_name_parser())]
pname: String,
},
```
`processor_name_parser()` (`src/registries/processor.rs`) and `analyzer_name_parser()` (`src/registries/analyzer.rs`) return a `clap::builder::PossibleValuesParser` over every registered name.
### 2. Bash post-processing (instance names)
Instance names cannot be known when the script is generated — they live in whichever `rsconstruct.toml` the user is in when they press TAB. `inject_bash_processor_completions()` in `src/cli.rs` post-processes the generated bash script: it prepends the `_rsconstruct_inames` and `_rsconstruct_analyzer_inames` helper functions, then patches the `COMPREPLY` line of these case sections so that a positional (anything not starting with `-`) completes from the helper instead of the static `opts`:
- `rsconstruct__subcmd__processor__subcmd__config)`
- `rsconstruct__subcmd__processor__subcmd__delete)`
- `rsconstruct__subcmd__processor__subcmd__disable)`
- `rsconstruct__subcmd__processor__subcmd__enable)`
- `rsconstruct__subcmd__processor__subcmd__files)`
- `rsconstruct__subcmd__analyzer__subcmd__delete)`
- `rsconstruct__subcmd__analyzer__subcmd__disable)`
- `rsconstruct__subcmd__analyzer__subcmd__enable)`
It also replaces the `compgen -f` (file-name) completion that clap emits for the `--processor`/`-p` and `--exclude-processor`/`-x` option values with `_rsconstruct_inames`, wherever those options occur (`build` and `watch`).
`processor defconfig` is not an injection target: it is handled by its `value_parser`.
The function errors if any injection point is missing from the script — clap-complete owns the script format (the labels were once `rsconstruct__processor__files` and are now `rsconstruct__subcmd__processor__subcmd__files`), so a miss means its output changed and the labels or needles must be updated. The unit test `bash_iname_injection_matches_clap_complete_output` round-trips the real generated script, so a format change fails `cargo test` instead of surfacing when a user sources their completions.
This only works for bash. Other shells get the base clap completions without instance-name injection.
## Adding Completions for New Arguments
- **Set known at generation time** (processor or analyzer pnames, other registry-backed names): use `#[arg(value_parser = ...)]` with a `PossibleValuesParser` built from the registry. Works in bash and zsh; fish only for options.
- **Enum types**: use `#[arg(value_enum)]` on a clap-derived enum. Works in all shells.
- **Instance names from `rsconstruct.toml`**: add the case label (`rsconstruct__subcmd__<cmd>__subcmd__<sub>)`) to the target list in `inject_bash_processor_completions()`. Bash only.