Bash Completion Help Generators

The Bash Completion help generator is provided by the airline-help-bash library. It generates Bash completion scripts for CLIs which can be used to provide Bash completion to users of the Bash shell. This differs from the other help generators in that the output is not intended for reading by end users.

Available Implementations

The following implementations are available:

• BashCompletionGenerator - Generates Bash completion script for the CLI

Example Usage

Global Help

Using BashCompletionGenerator:

   Cli<ExampleRunnable> cli = new Cli<ExampleRunnable>(ShipItCli.class);
        
   GlobalUsageGenerator<ExampleRunnable> helpGenerator = new BashCompletionGenerator<>();
   try {
       helpGenerator.usage(cli.getMetadata(), System.out);
   } catch (IOException e) {
       e.printStackTrace();
   }

Customising Completions

By default the generator will create completions based on various standard Airline metadata annotations:

• @Cli
• @ParserConfiguration
• @Command
• @Option
• @Arguments
• @AllowedRawValues

However in some cases it may be desirable to customise how things are completed further, you can do this using the @BashCompletion annotation provided by the airline-help-bash library e.g.

@Command(name = "file-info", description = "Returns information about the given files")
public class FileInfo implements ExampleRunnable {
    
    @Arguments(description = "Files to get info for")
    @Required
    @BashCompletion(behaviour = CompletionBehaviour.FILENAMES)
    private List<String> files;

    @Override
    public int run() {
        for (String file : files) {
            File f = new File(file);
            System.out.printf("File: %s\n", file);
            System.out.printf("Absolute Path: %s\n", f.getAbsolutePath());
            System.out.printf("Is Directory? %s\n", f.isDirectory() ? "Yes" : "No");
            System.out.printf("Size: %,d\n", f.length());
            System.out.println();
        }
        
        return 0;
    }

}

Here the behaviour field is used to specify that the arguments should be completed with filenames.

The following completion behaviours are available:

Using the Output

To use the output from this help generator you need to capture it in a file and then use the source command to load it into your Bash environment. Once sourced you will be able to use tab completion for your CLI.

For example:

   Cli<ExampleRunnable> cli = new Cli<ExampleRunnable>(ShipItCli.class);
        
   GlobalUsageGenerator<ExampleRunnable> helpGenerator = new BashCompletionGenerator<>();
   try {
       helpGenerator.usage(cli.getMetadata(), new FileOutputStream("completions.bash"));
   } catch (IOException e) {
       e.printStackTrace();
   }

Then source the output file:

> source completions.bash

Then start using your CLI and you will now have tab completion available for it.

Improving this Documentation

This documentation is itself open source and lives in GitHub under the docs/ directory.

I am not a professional technical writer and as the developer of this software I can often make assumptions of knowledge that you as a user reading this may not have. Improvements to the documentation are always welcome, if you have suggestions for the documentation please submit pull requests to the main branch.