slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

;doc: shell-completion/README: update [#986]

Browse Source
This commit is contained in:
Simon Michael 2024-09-17 10:54:57 -07:00
parent 9589941bb4
commit 2a054a3cc8
1 changed files with 47 additions and 98 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

147
hledger/shell-completion/README.md
View File

@ -1,121 +1,70 @@
Shell completion for CLI # hledger shell completions
========================
This code generates shell completion scripts for hledger's command line This code generates shell completion scripts for hledger's command line interface.
interface. Context-sensitive completions are usually triggered by pressing the tab key once or twice after typing the command `hledger ` (or `hledger-ui` or `hledger-web`).
Shell completion is usually triggered by pressing the tab key once or twice Currently only Bash is supported, but Zsh or Fish could be added.
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.
[![asciicast](https://asciinema.org/a/227935.svg)](https://asciinema.org/a/227935) [![asciicast](https://asciinema.org/a/227935.svg)](https://asciinema.org/a/227935)
The completions can handle hledger's CLI: To use hledger's bash shell completions, these must be installed on your system:
- bash
- the [bash-completion](https://salsa.debian.org/debian/bash-completion) package
- hledger's bash completion script
- hledger, hledger-ui, and/or hledger-web
- commands and generic options For full setup instructions, see [Install > Shell completions](https://hledger.org/install.html#shell-completions).
- command-specific options
- most option arguments
- account names, tags, payees, etc. from journal files
- query filter keywords like `status:`, `tag:`, or `amt:`
Installation for end users To test your setup: at a bash shell prompt, try typing
-------------------------- `hledger<SPACE><TAB><TAB>` (should list all hledger commands)
or `hledger reg acct:<TAB><TAB>` (should list your top-level account names).
Completions are currently only implemented for the Bash shell. The bash completion script can handle:
Please check first if the completions for hledger are already installed on your - hledger's command argument
distribution. Refer to the last paragraph of this section for how to test that. - general flags
- command-specific flags, after the command argument
- flag values, for flags that have standard values
- query prefixes
- account names from the journal, after an account name prefix
- appropriate data from the journal, after these query prefixes: `acct:`, `code:`, `cur:`, `desc:`, `note:`, `payee:`, `real:`, `status:`, `tag:`
- amount comparison operators, after `amt:`.
To install from the repository, do: ## Generating the shell completion script
```sh In the main hledger repo,
cd /path-to-repo/shell-completion first build and install an up-to-date version of hledger in PATH,
make install then run make to detect its commands and options and generate the `hledger-completion.bash` script.
``` GNU make and GNU m4 are required.
Completions installed this way will be loaded dynamically after you use the hledger stack install hledger
command. Upon the first invocation of a command that has no predefined completion cd hledger/shell-completion
bash looks for a file with the same name in a set of predefined locations in this order:
- `$BASH_COMPLETION_USER_DIR/completions`
- `$XDG_DATA_HOME/bash-completion/completions`
- `$HOME/.local/share/bash-completion/completions`
- etc.
You can manually achieve the effects of `make install` by copying
`shell-completion/hledger-completion.bash` to one of the above, and renaming it
to `hledger`, `_hledger` or `hledger.bash`. For the gory details, type this in a
bash shell:
```sh
type __load_completion
```
To install the completions manually, you can also just download and copy
`shell-completion/hledger-completion.bash` to a directory of your choosing, and
source it from your shell start up files. This way completions are loaded
eagerly and that adds a delay to shell start up time.
Example:
```sh
cp hledger-completion.bash ~/.bash_completion.d/hledger
echo 'source ~/.bash_completion.d/hledger' >> ~/.bashrc
# Restart shell
exec bash
# Confirm that completion is loaded
complete -p hledger
```
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:
```sh
# change into this folder:
cd shell-completion/
make make
```
Hint: GNU make and GNU m4 must be installed to call `make`. This is normally done at release time.
These are present on most systems anyway. The makefile runs `hledger`, `hledger -h`, and `hledger CMD -h` for each command,
Additionally the build will run a lot faster with parallell jobs. to detect (built-in) command names, flag names and flag values,
Use `make -j$(nproc)` for best effect. and it combines these with a stub script to form the final completion script.
You can add `-jNUMPROCS` to make it run faster.
The generated completion script must be installed. The package maintainer for Data from the journal (account names, payee names etc.) is not gathered here;
your distribution should be responsible for this. the script detects those dynamically at completion time.
For now, or to live-test the script, you can use these two commands: ## Installing the generated shell completion script
```sh (If you want a released version of the completion script, use the Install page link above instead.)
ln -s hledger-completion.bash ~/.hledger-completion.bash
echo 'source ~/.hledger-completion.bash' >> ~/.bashrc
```
After that, you have to start a new Bash, e.g. by typing `bash` on the current To install the dev completion script, also regenerating it if needed:
shell.
Now, try it by typing `hledger` (with a space after the command) and press the make install
tab key twice. You know how completions work – if not, see above in the
Installation section.
Completion scripts for other shells (e.g. Fish or Zsh) This will copy `hledger-completion.bash` to `$XDG_DATA_HOME/bash-completion/completions/hledger`.
------------------------------------------------------ (See bash-completion's docs for other places you can install the script if needed.)
bash will use it when completing command lines beginning with "hledger" or "hledger-ui" or "hledger-web".
You can also just source the script it in your shell startup; this will load completions eagerly, adding a delay to your shell start up time.
Or you can source it in your current bash session for testing.
## Completion scripts for other shells
You're welcome to add completion scripts for other shells. It should not be too 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 hard! All available hledger options and commands are already there (generated by