https://github.com/ysthakur/gen-completions
Generate shell completions from manpages or KDL/JSON/YAML
https://github.com/ysthakur/gen-completions
cli manpages shell
Last synced: 4 months ago
JSON representation
Generate shell completions from manpages or KDL/JSON/YAML
- Host: GitHub
- URL: https://github.com/ysthakur/gen-completions
- Owner: ysthakur
- License: mit
- Created: 2023-08-05T15:39:57.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2024-03-20T00:13:29.000Z (over 2 years ago)
- Last Synced: 2024-04-24T04:27:16.273Z (about 2 years ago)
- Topics: cli, manpages, shell
- Language: Rust
- Homepage: https://crates.io/crates/gen-completions
- Size: 371 KB
- Stars: 3
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# gen-completions
[](https://github.com/ysthakur/gen-completions/actions)
[](https://github.com/ysthakur/gen-completions/actions)
[](https://crates.io/crates/gen-completions)
[](./LICENSE.md)
> [!warning]
> This project is a work in progress so it's extremely unstable and mostly broken.
This is a crate for parsing manpages to generate shell completions either by parsing
manpages or from KDL/JSON files. There's both a library and a binary, and if
you're looking for documentation on the library, see https://docs.rs/gen-completions/.
But you're probably here for the binary, and if you want information on that, read on.
Currently, it generates Bash, Zsh, and Nushell completions, although I've only
tested out Zsh and Nushell properly. If you're using another shell, it also generates
[Carapace](https://github.com/rsteube/carapace-bin) specs. In addition to that,
it generates KDL and JSON files so you can process the command information
to generate completions yourself or something else.
The manpage parsing has been mainly ported from [Fish's completions script](https://github.com/fish-shell/fish-shell/blob/master/share/tools/create_manpage_completions.py),
although this crate doesn't yet support every kind of manpage that the Fish script supports. In particular, MacOS man pages cannot yet be parsed. Any help with that would be greatly appreciated.
## Installation
- Using Cargo: `cargo install gen-completions`
- From the [Releases](https://github.com/ysthakur/gen-completions/releases) page:
Simply download the right executable for your platform from the latest release
- As a Nix flake: `github:ysthakur/gen-completions`
- Try it out with `nix shell github:ysthakur/gen-completions`
- Build it yourself:
- Download this repository (`git clone git@github.com:ysthakur/gen-completions.git`)
- `cd gen-completions && cargo build --release`
## Usage
You can periodically run `gen-completions` to generate completions for any commands you want.
For example, if you have a directory `~/generated-completions` for all your generated
completions, and you want to generate Zsh completions from the `ncdu` manpage, you can use:
```shell
gen-completions man zsh ~/generated-completions --cmds="ncdu"
```
If you have a config file to generate completions from, you can use:
```shell
gen-completions for zsh ncdu-completions.kdl ~/generated-completions
```
The CLI uses [`env_logger`](https://docs.rs/env_logger/) as the backend for logging,
so to configure that, set the `RUST_LOG` environment variable (the link has instructions).
See below for specific flags and whatnot.
### Generating from manpages
```
Usage: gen-completions man [OPTIONS]
Arguments:
Shell(s) to generate completions for
Possible values:
- zsh: Generate completions for Zsh
- bash: Generate completions for Bash
- nu: Generate completions for Nushell
- kdl: Output parsed options as KDL
- json: Output parsed options as JSON
- carapace: Output Carapace spec
Directory to output completions to
Options:
-d, --dirs
Directories to search for man pages in, e.g. `--dirs=/usr/share/man/man1,/usr/share/man/man6` Note that `--dirs` will search directly inside the given directories, not inside `/man1`, `/man2`, etc. If you want to search for man pages in a specific set of directories, set `$MANPATH` before running this command
-c, --cmds
Commands to generate completions for. If omitted, generates completions for all found commands. To match the whole name, use "^...$"
-C, --exclude-cmds
Commands to exclude (regex). To match the whole name, use "^...$"
--not-subcmds
Commands that should not be treated as subcommands, to help deal with false positives when detecting subcommands
--subcmds
Explicitly list which man pages are for which subcommands. e.g. `git-commit=git commit,foobar=foo bar`
-h, --help
Print help (see a summary with '-h')
```
### Generating from KDL/JSON/YAML
```
Usage: gen-completions for [OUT]
Arguments:
Shell(s) to generate completions for
Possible values:
- zsh: Generate completions for Zsh
- bash: Generate completions for Bash
- nu: Generate completions for Nushell
- kdl: Output parsed options as KDL
- json: Output parsed options as JSON
- carapace: Output Carapace spec
File to generate completions from
[OUT]
File to generate completions to. Outputted to stdout if not given
Options:
-h, --help
Print help (see a summary with '-h')
```
### Zsh
You can either generate completions to a directory that's already in `$fpath`, where
Zsh looks for functions, or you can make a new directory. If you choose to do the latter,
make sure to add it to your `$fpath` in your `~/.zshrc`:
```zsh
fpath=(path/to/my/directory $fpath)
```
> [!note]
> `fpath` must be updated **before** `compinit` is called.
After this, if your chosen directory is `~/generated-completions`, you can run
```zsh
gen-completions man zsh ~/generated-completions --cmds="^ncdu"
```
and when you try `ncdu `, you should see completions for all of ncdu's flags.
### Bash
TODO
### Nushell
TODO
## Contributing
Any and all contributions are welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) for information on what needs to be worked on.
### Details on how it works
For examples of the kinds of files this generates, look at the
[`expected`](./tests/resources/expected/) folder inside the [`tests`](./tests) folder.
For some example man pages, look at the [`samples`](/samples/) folder.
It has very basic subcommand detection. If a manpage is named `git-commit-tree`,
it will look for the text `git commit tree`, `git-commit tree`, and `git commit-tree` in
the file. When it finds the text `git commit-tree` in the man page, it will
assume that `commit-tree` is a subcommand of `git`. I'm not sure how the Fish
script generates subcommands--I've been too lazy to do anything but skim over it--but
I will eventually get around to porting Fish's subcommand detection.