Skip to content

Completion

Jump to bottom
mattirn edited this page Jan 20, 2021 · 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 three options Option.AUTO_PARAM_SLASH (true), Option.AUTO_REMOVE_SLASH (true) and Option.USE_FORWARD_SLASH (false). Options default values are shown in parenthesis.

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

OptionCompleter

The OptionCompleter completes command's arguments and options. It is meant to use as a child completer of the ArgumentCompleter.

completer = new ArgumentCompleter(
    new StringsCompleter("Command1"),
    new OptionCompleter(Arrays.asList(
                            new StringsCompleter("p1", "p11"),  // first arg completer
                            new StringsCompleter("p2", "p22"),  // second arg completer
                            NullCompleter.INSTANCE)),
                        this::commandOptions                    // option descriptions
                        1));   // OptionCompleter position in ArgumentCompleter List

where this::commandOptions is Java functional interface Function<String,Collection<OptDesc>>. The function String parameter is command name and it will return command option descriptions (OptDesc).

SystemCompleter

The SystemCompleter is an other completer aggregate.

Builtins builtins = new Builtins(workDir, configPath, widgetCreator);
SystemCompleter systemCompleter = builtins.compileCompletor(); // builtins commands completers
systemCompleter.add("command1", command1Completer);            // add command1 completer
systemCompleter.add(appSystemCompleter);		       // add other app commands completers
systemCompleter.compile();                                     // prepare it for LineReader
LineReader reader = LineReaderBuilder.builder()
                    .terminal(terminal).parser(parser)
                    .completer(systemCompleter)
                    .build();
builtins.setLineReader(reader);                                // to complite set builtins lineReader

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