anchor.diff:  with those few characters. The user can type more characters and press TAB again to see a new, narrowed-down
   list if the typed characters are still ambiguous, or else complete the subcommand or option.
   
  -=== Example
  +== Example
  +Assume we have a command line application with subcommands, all of which have some options. Below is an example:
   
  +[source,java]
  +----
  +@Command(name = "hierarchy")
  +public static class MainCommand {
  +    @Option(names = {"-V", "--version"}, help = true) boolean versionRequested;
  +    @Option(names = {"-h", "--help"},    help = true) boolean helpRequested;
  +}
  +
  +@Command(name = "sub1", description = "subcommand 1")
  +public static class Subcommand1 {
  +    @Option(names = {"--directory", "-d"}, description = "a directory") File directory;
  +    @Option(names = {"-h", "--host"},      description = "a host")      InetAddress host;
  +}
  +
  +@Command(name = "sub2", description = "subcommand 2")
  +public static class Subcommand2 {
  +    @Option(names = {"-u", "--timeUnit"}) private TimeUnit timeUnit;
  +    @Option(names = {"-t", "--timeout"})  private long timeout;
  +}
  +----
  +
  +Assume we <<Generating the Completion Script,generated>> and <<Installing the Completion Script,installed>> a completion script for this application. Assume the command script to run the application is called `hierarchy`.
  +
  +=== Options and Subcommands
  +After the command name, press the TAB key to trigger autocomplete. The shell will show all options and all subcommands for the `hierarchy` main command:
  +
  +[source,bash]
  +----
  +$ hierarchy <TAB><TAB>
  +-h         --help     sub1       sub2       -V         --version
  +----
  +
  +=== Partial Input
  +If the option or subcommand is partially specified, a narrowed-down list is shown. For example, after typing 's' and triggering autocomplete, only the completion options starting with 's' are shown:
  +[source,bash]
  +----
  +$ hierarchy s<TAB><TAB>
  +sub1  sub2
  +----
  +
  +=== Context-sensitive
  +
  +Picocli autocomplete is context-sensitive to the selected subcommand and the selected option.
  +
  +After selecting a subcommand, the user can hit <TAB><TAB> again to see what options are available on that subcommand. Only the options for the selected subcommand are shown:
  +
  +[source,bash]
  +----
  +$ hierarchy sub1 <TAB><TAB>
  +-d           --directory  --h       --host
  +----
  +
  +=== Nested sub-subcommands
  +There is no restriction to the number of levels for nested subcommands. The completion script generated by picocli will show context-sensitive matches for the most specific (deepest) subcommand.
  +
  +=== Option Values
  +In addition to showing a list of option _names_, tab completion can also generate possible option _values_. The type of the field annotated with `@Option` determines the generated values.
  +
  +Picocli can generate completion matches for the following types:
  +
  +* `java.io.File`
  +* `java.nio.file.Path`
  +* `java.net.InetAddress`
  +* any java `enum`
  +
  +==== Files and Directories
  +In the above example, `Subcommand1` has a `java.io.File` field annotated with `@Option(names = {"--directory", "-d"}`. Generating autocomplete matches for that option will display a list of all files and directories in the current directory.
  +[source,bash]
  +----
  +$ hierarchy sub1 -d <TAB><TAB>
  +basic.bash              hierarchy               nestedSubcommands.bash
  +----
  +
  +The same tab completion matches are shown for fields of type `java.nio.file.Path` annotated with `@Option`.
  +
  +==== Host Names
  +In the above example, `Subcommand1` has a `java.net.InetAddress` field annotated with `@Option(names = {"-h", "--host"}`. Generating autocomplete matches for that option will display a list of known hosts.
  +[source,bash]
  +----
  +$ hierarchy sub1 --host <TAB><TAB>
  +cluster-p-1                          openvpn-client.myvpn.picocli.com
  +cluster-p-2                          picop1
  +cluster-p-3                          picop2
  +cluster-p-4                          picop3
  +cluster-scm-1                        picop4
  +client.openvpn.net                   picoscm1
  +----
  +
  +==== Java `enum` Values
  +In the above example, `Subcommand2` has a field of type `java.util.concurrent.TimeUnit`, which is a Java `enum`.  Generating autocomplete matches for that option will display the list of enum values.
  +
  +[source,bash]
  +----
  +$ hierarchy sub2 --timeUnit <TAB><TAB>
  +DAYS     HOURS     MICROSECONDS  MILLISECONDS  MINUTES    NANOSECONDS   SECONDS
  +----
   
   == Generating the Completion Script
   
  +Create a `CommandLine` instance with the full hierarchy of nested subcommands.
  +```
  +CommandLine hierarchy = new CommandLine(new TopLevel())
  +        .addSubcommand("sub1", new Subcommand1())
  +        .addSubcommand("sub2", new Subcommand2());
  +```
  +
  +Pass this `CommandLine` instance and the name of the script to the `picocli.AutoComplete::bash` method. The method will return the source code of a completion script. Save the source code to a file and install it.
  +
  +CAUTION: *_The AutoComplete class is not yet in master but can be checked out from the https://github.com/remkop/picocli/tree/%23121-autocomplete[autocomplete branch]._*
  +
  +```
  +String script = AutoComplete.bash("hierarchy", hierarchy);
  +// save to file
  +```
  +
  +TODO 1) Save the generated completion script to a file
  +
  +TODO 2) generate the accompanying `hierarchy` command script to run the application. This is the script that Bash will recognize and generate completion matches for. It needs to contain something like
  +
  +```
  +// file: 'hierarchy'
  +#!/usr/bin/env bash
  +
  +HIERARCHY_DIR=path/to/libs
  +HIERARCHY_CP="${HIERARCHY_DIR}/myApp.jar"
  +java -cp "${HIERARCHY_CP}" 'com.myorg.myproject.MainClass' $@
  +```
  +
   == Installing the Completion Script
  +
  +Place the completion script file in a `bash_completion.d` folder:
  +
  +* /etc/bash_completion.d
  +* /usr/local/etc/bash_completion.d
  +* ~/bash_completion.d
  +
  +TODO Test this.
   
   == Supported Platforms
   
  +TODO Special instructions for ZSH, Cygwin and Babun.
   
   == Picocli User Manual
   The http://picocli.info[picocli user manual] explains how to build Java command line applications with picocli.
   
   == GitHub Project
   The https://github.com/remkop/picocli[GitHub project] has the source code, tests, build scripts, etc.
  +
  +*_The AutoComplete class is not yet in master but can be checked out from the https://github.com/remkop/picocli/tree/%23121-autocomplete[autocomplete branch]._*
   
   Star icon:star-o[] or fork icon:code-fork[] this project on GitHub if you like it!
   (Projects with many icon:code-fork[] forks are easier to find on GitHub Search.)
  
positive.code: Every main method deserves picocli!
  
  == Introduction
  Picocli-based applications can now have command line completion in the Unix Bash or Zsh shell.
  Picocli can generate an autocompletion script tailored to your application.
  
  With this script installed, users can type the first few letters of a subcommand or an option,
  
negative.code: = Autocomplete for Java command line applications
  //:author: Remko Popma
  //:email: rpopma@apache.org
  :revnumber: 0.9.8-SNAPSHOT
  :revdate: 2017-06-08
  :toc: left
  :numbered:
  :toclevels: 3
  :toc-title: Table of Contents
  :source-highlighter: coderay
  :icons: font
  