Completion

Completion is one key feature of JLine. Completion is usually triggered by the tab key and can be used to complete commands, options or parameters. The LineReader can be given an implementation of the Completer interface which is responsible for returning list of completion Candidate. Completers can be combined into a hierarchy to actually form a complete completion system.

You can easily write your own completer, but JLine provides a few builtin completers that might be of use.

AggregateCompleter

AggregateCompleter combines zero or more completers.

completer = new AggregateCompleter(completer1, completer2);

ArgumentCompleter

ArgumentCompleter invokes a child completer, so individual completers do not need to know about argument parsing semantics.

completer = new ArgumentCompleter(
                new StringsCompleter("bar", "baz"),
                new StringsCompleter("foo"),
                new StringsCompleter("ree"));

File completers

FileNameCompleter – returns matching paths (directories or files) as a collection of Path. DirectoriesCompleter and FilesCompleter are specialized subclasses.

DirectoriesCompleter – returns matching directories as a collection of Path.

FilesCompleter – returns matching files as a collection of Path.

The file completers can be customized using the two options Option.AUTO_PARAM_SLASH and Option.AUTO_REMOVE_SLASH which both defaults to true.

completer = new DirectoriesCompleter(session.currentDir());

EnumCompleter

The EnumCompleter returns a list of candidates based on an Enum names.

completer = new EnumCompleter(MyEnum.class);

NullCompleter

The NullCompleter returns no candidates.

completer = NullCompleter.INSTANCE;

StringsCompleter

The StringsCompleter returns a list of candidates based on a static list of strings.

completer = new StringsCompleter("foo", "bar", "baz");

RegexCompleter

The RegexCompleter delegates to several other completers depending on a given regular expression.

Map<String, Completer> comp = new HashMap<>();
comp.put("C1", new StringsCompleter("cmd1"));
comp.put("C11", new StringsCompleter("--opt11", "--opt12"));
comp.put("C12", new StringsCompleter("arg11", "arg12", "arg13"));
comp.put("C2", new StringsCompleter("cmd2"));
comp.put("C21", new StringsCompleter("--opt21", "--opt22"));
comp.put("C22", new StringsCompleter("arg21", "arg22", "arg23"));
completer = new Completers.RegexCompleter("C1 C11* C12+ | C2 C21* C22+", comp::get);

TreeCompleter

The TreeCompleter completes commands based on a tree structure.

completer = new TreeCompleter(
    node("Command1",
        node("Option1",
            node("Param1", "Param2")),
        node("Option2"),
        node("Option3")));

Completion options

COMPLETE_IN_WORD AUTO_GROUP AUTO_MENU AUTO_LIST RECOGNIZE_EXACT GROUP CASE_SENSITIVE LIST_AMBIGUOUS LIST_PACKED LIST_ROWS_FIRST MENU_COMPLETE

Completion variables

• DISABLE_COMPLETION
• LIST_MAX

If you use a TreeCompleter, and you want all of the top-level node values to be displayed, thereby displaying the available commands, when the user's first keypress is a tab, call unsetOpt on the LineReader as shown:

LineReader reader = LineReaderBuilder().builder()
    .terminal(terminal)
    .completer(treeCompleter)
    .parser(parser)
    .build();

reader.unsetOpt(LineReader.Option.INSERT_TAB);