Skip to content

Completion

Jump to bottom
Guillaume Nodet edited this page Jan 10, 2018 · 12 revisions

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.

Builtin completers

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"));

Each completer will be used to complete the n-th word on the command line. Whether the first completers do need to match or not is controlled by the setStrict method. The last completer is used if the index of the word being completer is greater than the number of completers. In order to not complete the last words, the NullCompleter can be used.

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")));

Completer

The Completer can be used to provide a full-blown completer based on a CompletionEnvironment implementation which itself associate a command with a CompletionData object.

An example of the Completer usage can be found in the gogo/jline integration which allows adding completion easily at runtime using the built-in scripting langage.

Customization

Completion options

Completion variables

Clone this wiki locally