120 lines
4.3 KiB
Markdown
120 lines
4.3 KiB
Markdown
---
|
||
title: Autocomplete for Java Command Line Applications
|
||
source: https://picocli.info/autocomplete.html
|
||
---
|
||
|
||
This tutorial uses the [CheckSum example application](https://picocli.info/index.html#CheckSum-application) from the picocli user manual. We created a class `com.myproject.CheckSum` and put it in a jar file, `myproject.jar`.
|
||
|
||
Follow these steps to give this application command line autocompletion.
|
||
|
||
### 2.1. Create Command
|
||
|
||
First, create an executable command that runs the main application class. For this tutorial, the command name is `jchecksum`.
|
||
|
||
We use an [alias](https://en.wikipedia.org/wiki/Alias_%28command%29) here to create the command (see [alternatives](#_alternative_ways_to_define_commands)):
|
||
|
||
```
|
||
alias jchecksum='java -cp "picocli-1.0.0.jar;myproject.jar" com.myproject.CheckSum'
|
||
```
|
||
|
||
Let’s test that the command works:
|
||
|
||
```
|
||
$ jchecksum --help
|
||
Usage: jchecksum [-h] [-a=<algorithm>] <file>
|
||
Prints the checksum (MD5 by default) of a file to STDOUT.
|
||
file The file whose checksum to calculate.
|
||
-a, --algorithm=<algorithm> MD5, SHA-1, SHA-256, ...
|
||
-h, --help Show this help message and exit.
|
||
```
|
||
|
||
### 2.2. Generate Completion Script
|
||
|
||
To generate the completion script, run the `picocli.AutoComplete` class as a java application. Pass it the command name and the fully qualified class name of the annotated command class. (See also [full description](#_completion_script_generation_details) for using `AutoComplete`.)
|
||
|
||
```
|
||
java -cp "picocli-1.0.0.jar;myproject.jar" picocli.AutoComplete -n jchecksum com.myproject.CheckSum
|
||
```
|
||
|
||
This generates a `jchecksum_completion` script in the current directory. To verify:
|
||
|
||
```
|
||
$ ls
|
||
jchecksum_completion myproject.jar picocli-1.0.0.jar
|
||
```
|
||
|
||
### 2.3. Install Completion Script
|
||
|
||
Finally, [source](https://tldp.org/HOWTO/Bash-Prompt-HOWTO/x237.html) the completion script:
|
||
|
||
…and you are done. The `jchecksum` command now has autocompletion:
|
||
|
||
```
|
||
$ jchecksum <TAB><TAB>
|
||
-a --algorithm -h --help
|
||
```
|
||
|
||
### 2.4. Permanent Installation
|
||
|
||
The above will last for the duration of your shell session. If you want to make this permanent you need to modify your ~/.bashrc or ~/.zshrc file to add a line that defines the command alias and a line that sources the completion script:
|
||
|
||
Bash
|
||
|
||
```
|
||
echo "alias jchecksum='java -cp \"picocli-1.0.0.jar;myproject.jar\" com.myproject.CheckSum'" >> ~/.bashrc
|
||
echo ". jchecksum_completion" >> ~/.bashrc
|
||
```
|
||
|
||
Make sure to use `>>` (append), using a single `>` would overwrite the file.
|
||
|
||
`~/.bashrc` indicates `.bashrc` is in your home directory.
|
||
|
||
### 2.5. Distribution
|
||
|
||
| | |
|
||
| --- | --- |
|
||
| | Have a subcommand that generates a completion script. |
|
||
|
||
You could generate completion scripts for your commands [during the build](#_generating_completion_scripts_during_the_build) and distribute them with your application, but an alternative is to give your application the ability to generate its own completion script on demand.
|
||
|
||
That allows end users to install completion for your application with a single command. For example, if your utility is called `mycommand`, users can install completion for it by running the following command:
|
||
|
||
Bash
|
||
|
||
```
|
||
$ source <(mycommand generate-completion)
|
||
```
|
||
|
||
This can be accomplished by registering the built-in `picocli.AutoComplete.GenerateCompletion` class as a subcommand of the top-level command.
|
||
|
||
For example:
|
||
|
||
```
|
||
import picocli.AutoComplete.GenerateCompletion;
|
||
import picocli.CommandLine;
|
||
import picocli.CommandLine.Command;
|
||
|
||
@Command(name = "mycommand", subcommands = GenerateCompletion.class)
|
||
public class MyApp implements Runnable {
|
||
|
||
@Override
|
||
public void run() { // top-level command business logic here
|
||
}
|
||
|
||
public static void main(String[] args) {
|
||
new CommandLine(new MyApp()).execute(args);
|
||
}
|
||
}
|
||
```
|
||
|
||
By default, the `generate-completion` command shows up as a subcommand in the usage help message of its parent command. Applications that want the completion subcommand to be hidden in the usage help message, can do the following:
|
||
|
||
```
|
||
public static void main(String... args) {
|
||
CommandLine cmd = new CommandLine(new MyApp());
|
||
CommandLine gen = cmd.getSubcommands().get("generate-completion");
|
||
gen.getCommandSpec().usageMessage().hidden(true);
|
||
int exitCode = cmd.execute(args);
|
||
// ...
|
||
}
|
||
``` |