-
Notifications
You must be signed in to change notification settings - Fork 219
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.
Completer
s 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 combines zero or more completers.
completer = new AggregateCompleter(completer1, completer2);
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.
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());
The EnumCompleter returns a list of candidates based on an Enum
names.
completer = new EnumCompleter(MyEnum.class);
The NullCompleter returns no candidates.
completer = NullCompleter.INSTANCE;
The StringsCompleter returns a list of candidates based on a static list of strings.
completer = new StringsCompleter("foo", "bar", "baz");
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);
The TreeCompleter completes commands based on a tree structure.
completer = new TreeCompleter(
node("Command1",
node("Option1",
node("Param1", "Param2")),
node("Option2"),
node("Option3")));
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).
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
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.
-
INSERT_TAB specifies if hitting
<tab>
at the beginning of the line will insert a tab or trigger completion - COMPLETE_IN_WORD
- AUTO_GROUP
- AUTO_MENU
- AUTO_LIST
- RECOGNIZE_EXACT
- GROUP
- CASE_SENSITIVE
- LIST_AMBIGUOUS
- LIST_PACKED
- LIST_ROWS_FIRST
- MENU_COMPLETE