2019-01-10 21:38:52 +03:00
|
|
|
|
Shell completion for CLI
|
|
|
|
|
========================
|
|
|
|
|
|
|
|
|
|
This code generates shell completion scripts for hledger's command line
|
|
|
|
|
interface.
|
|
|
|
|
Shell completion is usually triggered by pressing the tab key once or twice
|
|
|
|
|
after typing the command `hledger `.
|
|
|
|
|
(The exact behavior may differ in shells other than Bash.)
|
|
|
|
|
|
|
|
|
|
Currently, only Bash is supported but Zsh or Fish can be added.
|
|
|
|
|
|
2019-02-16 11:43:37 +03:00
|
|
|
|
[![asciicast](https://asciinema.org/a/227935.svg)](https://asciinema.org/a/227935)
|
2019-01-10 21:38:52 +03:00
|
|
|
|
|
|
|
|
|
The completions can handle hledger's CLI:
|
|
|
|
|
|
|
|
|
|
- commands and generic options
|
|
|
|
|
- command-specific options
|
|
|
|
|
- filenames for options that take a filename as argument
|
2019-01-23 22:24:56 +03:00
|
|
|
|
- account names from journal files (but not yet for files named by `--file`)
|
|
|
|
|
- query filter keywords like `status:`, `tag:`, or `amt:`
|
2019-01-10 21:38:52 +03:00
|
|
|
|
|
2019-01-19 23:46:07 +03:00
|
|
|
|
Installation for end users
|
|
|
|
|
--------------------------
|
2019-01-10 21:38:52 +03:00
|
|
|
|
|
2019-01-19 23:46:07 +03:00
|
|
|
|
Completions are currently only implemented for the Bash shell.
|
|
|
|
|
|
|
|
|
|
Please check first if the completions for hledger are already installed on your
|
|
|
|
|
distribution. Refer to the last paragraph of this section for how to test that.
|
|
|
|
|
|
|
|
|
|
To install the completions manually, follow this steps:
|
|
|
|
|
|
|
|
|
|
- Download or copy the file `shell-completion/hledger-completion.bash` and save
|
|
|
|
|
it as `~/.hledger-completion.bash`.
|
|
|
|
|
|
2020-06-17 04:48:28 +03:00
|
|
|
|
- Add the command `source ~/.hledger-completion.bash` this to the end of your
|
2019-01-19 23:46:07 +03:00
|
|
|
|
`~/.bashrc` file.
|
|
|
|
|
|
|
|
|
|
- Then, you have to start a new Bash, e.g. by typing `bash` on the current
|
|
|
|
|
shell.
|
|
|
|
|
|
|
|
|
|
Example installation script:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
cp hledger-completion.bash ~/.hledger-completion.bash
|
|
|
|
|
echo 'source ~/.hledger-completion.bash' >> ~/.bashrc
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Now, try it by typing `hledger` (with a space after the command) and press the
|
|
|
|
|
tab key twice. You should see a list of appropriate completions for hledger.
|
|
|
|
|
Then you can type a part of one of the suggestions and press tab again to
|
|
|
|
|
complete it.
|
|
|
|
|
|
|
|
|
|
Background
|
|
|
|
|
----------
|
|
|
|
|
|
|
|
|
|
The Bash completion script is generated (GNU make) by parsing output of `hledger`,
|
|
|
|
|
`hledger -h`, and `hledger <cmd> -h`. The script also uses `hledger accounts` for
|
|
|
|
|
account name completion. I propose that the Makefile is not run at every built
|
|
|
|
|
but rather manually when the CLI changes.
|
|
|
|
|
|
|
|
|
|
Information for developers
|
|
|
|
|
--------------------------
|
|
|
|
|
|
|
|
|
|
Generate the completion script for Bash:
|
2019-01-10 21:38:52 +03:00
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
# change into this folder:
|
|
|
|
|
cd shell-completion/
|
|
|
|
|
make
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Hint: GNU make, GNU m4, and GNU parallel must be installed to call `make`.
|
|
|
|
|
The first two usually are.
|
|
|
|
|
|
2019-01-19 23:46:07 +03:00
|
|
|
|
The generated completion script must be installed. The package maintainer for
|
|
|
|
|
your distribution should be responsible for this.
|
|
|
|
|
|
|
|
|
|
For now, or to live-test the script, you can use these two commands:
|
2019-01-10 21:38:52 +03:00
|
|
|
|
|
|
|
|
|
```
|
2019-01-19 23:46:07 +03:00
|
|
|
|
ln -s hledger-completion.bash ~/.hledger-completion.bash
|
2019-01-10 21:38:52 +03:00
|
|
|
|
echo 'source ~/.hledger-completion.bash' >> ~/.bashrc
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
After that, you have to start a new Bash, e.g. by typing `bash` on the current
|
|
|
|
|
shell.
|
|
|
|
|
|
|
|
|
|
Now, try it by typing `hledger` (with a space after the command) and press the
|
2019-01-19 23:46:07 +03:00
|
|
|
|
tab key twice. You know how completions work – if not, see above in the
|
|
|
|
|
Installation section.
|
2019-01-12 14:44:47 +03:00
|
|
|
|
|
|
|
|
|
Completion scripts for other shells (e.g. Fish or Zsh)
|
|
|
|
|
------------------------------------------------------
|
|
|
|
|
|
|
|
|
|
You're welcome to add completion scripts for other shells. It should not be too
|
|
|
|
|
hard! All available hledger options and commands are already there (generated by
|
|
|
|
|
the Makefile).
|
|
|
|
|
|
|
|
|
|
The generated text files with options and commands are: `commands.txt`,
|
|
|
|
|
`generic-options.txt`, and `options-*.txt` where `*` is the subcommand.
|
|
|
|
|
|
|
|
|
|
Instructions to add support for another shell:
|
|
|
|
|
|
|
|
|
|
1. Create e.g. `hledger-completion.fish.m4` as a template file.
|
|
|
|
|
|
|
|
|
|
2. Add a Make rule to transform it to `hledger-completion.fish`.
|
|
|
|
|
|
|
|
|
|
3. Use m4 commands to include hledger options and commands into your script
|
|
|
|
|
template. See `hledger-completion.bash.m4` as a reference.
|
|
|
|
|
|
|
|
|
|
4. Use `make` and then `make hledger-completion.fish` to create and test the
|
|
|
|
|
completion script.
|
|
|
|
|
|
|
|
|
|
5. Finally, if everything is working, also add the generated artifact
|
|
|
|
|
`hledger-completion.fish` to the repo so that people can use it directly.
|