Package org.jline.shell

Class ShellBuilder

java.lang.Object

org.jline.shell.ShellBuilder

public class ShellBuilder
extends Object

Builder for creating Shell instances.

The builder provides a fluent API for configuring the shell:

 Shell shell = Shell.builder()
     .terminal(terminal)              // optional, auto-created if null
     .prompt("myapp> ")               // or .prompt(() -> dynamicPrompt)
     .dispatcher(dispatcher)          // optional, DefaultCommandDispatcher if null
     .groups(group1, group2)          // added to dispatcher
     .parser(parser)                  // optional, DefaultParser by default
     .historyFile(path)               // optional
     .variable(name, value)           // forwarded to LineReader
     .option(Option.X, true)          // forwarded to LineReader
     .onReaderReady((reader, dispatcher) -> { ... })// optional callback
     .build();
 

Since:

4.0

See Also:

• Shell

Method Summary

Modifier and Type	Method	Description
ShellBuilder	aliasManager(AliasManager aliasManager)	Sets the alias manager for the shell.
Shell	build()	Builds the Shell instance.
ShellBuilder	commandHighlighter(boolean enable)	Enables or disables the built-in command-aware syntax highlighter.
ShellBuilder	dispatcher(CommandDispatcher dispatcher)	Sets the command dispatcher.
ShellBuilder	groups(CommandGroup... groups)	Adds command groups to the dispatcher.
ShellBuilder	helpCommands(boolean enable)	Enables or disables built-in help commands (help).
ShellBuilder	highlighter(Highlighter highlighter)	Sets a custom highlighter for the shell's LineReader.
ShellBuilder	historyCommands(boolean enable)	Enables or disables built-in history commands (history).
ShellBuilder	historyFile(Path historyFile)	Sets the history file path.
ShellBuilder	initScript(File initScript)	Sets the initialization script to execute on startup.
ShellBuilder	jobManager(JobManager jobManager)	Sets the job manager for the shell.
ShellBuilder	lineExpander(LineExpander lineExpander)	Sets the line expander for variable expansion.
ShellBuilder	onReaderReady(BiConsumer<LineReader,CommandDispatcher> onReaderReady)	Sets a callback invoked after the LineReader is created but before Shell.run().
ShellBuilder	onReaderReady(Consumer<LineReader> onReaderReady)	Sets a callback invoked after the LineReader is created but before Shell.run().
ShellBuilder	option(LineReader.Option option, boolean value)	Sets a LineReader option.
ShellBuilder	optionCommands(boolean enable)	Enables or disables built-in option commands (setopt, unsetopt, setvar).
ShellBuilder	parser(Parser parser)	Sets the line parser.
ShellBuilder	pipelineParser(PipelineParser pipelineParser)	Sets a custom pipeline parser for the shell.
ShellBuilder	prompt(String prompt)	Sets a static prompt string.
ShellBuilder	prompt(Supplier<String> promptSupplier)	Sets a dynamic prompt supplier, called before each line read.
ShellBuilder	rightPrompt(String rightPrompt)	Sets a static right prompt string.
ShellBuilder	rightPrompt(Supplier<String> rightPromptSupplier)	Sets a dynamic right prompt supplier, called before each line read.
ShellBuilder	scriptCommands(boolean enable)	Enables or disables built-in script commands (source, .).
ShellBuilder	scriptRunner(ScriptRunner scriptRunner)	Sets the script runner for executing script files.
ShellBuilder	terminal(Terminal terminal)	Sets the terminal for the shell.
ShellBuilder	variable(String name, Object value)	Sets a LineReader variable.
ShellBuilder	variableCommands(boolean enable)	Enables or disables built-in variable commands (set, unset, export).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

terminal

public ShellBuilder terminal(Terminal terminal)

Sets the terminal for the shell. If not specified, a system terminal is created automatically.

Parameters:

terminal - the terminal

Returns:

this builder

prompt

public ShellBuilder prompt(String prompt)

Sets a static prompt string.

Parameters:

prompt - the prompt string

Returns:

this builder

prompt

public ShellBuilder prompt(Supplier<String> promptSupplier)

Sets a dynamic prompt supplier, called before each line read.

Parameters:

promptSupplier - the prompt supplier

Returns:

this builder

rightPrompt

public ShellBuilder rightPrompt(String rightPrompt)

Sets a static right prompt string.

Parameters:

rightPrompt - the right prompt string

Returns:

this builder

rightPrompt

public ShellBuilder rightPrompt(Supplier<String> rightPromptSupplier)

Sets a dynamic right prompt supplier, called before each line read.

Parameters:

rightPromptSupplier - the right prompt supplier

Returns:

this builder

dispatcher

public ShellBuilder dispatcher(CommandDispatcher dispatcher)

Sets the command dispatcher. If not specified, a DefaultCommandDispatcher is created.

Parameters:

dispatcher - the command dispatcher

Returns:

this builder

groups

public ShellBuilder groups(CommandGroup... groups)

Adds command groups to the dispatcher.

Parameters:

groups - the command groups

Returns:

this builder

parser

public ShellBuilder parser(Parser parser)

Sets the line parser. If not specified, a DefaultParser is used.

Parameters:

parser - the parser

Returns:

this builder

historyFile

public ShellBuilder historyFile(Path historyFile)

Sets the history file path.

Parameters:

historyFile - the path to the history file

Returns:

this builder

variable

public ShellBuilder variable(String name,
 Object value)

Sets a LineReader variable.

Parameters:

name - the variable name

value - the variable value

Returns:

this builder

option

public ShellBuilder option(LineReader.Option option,
 boolean value)

Sets a LineReader option.

Parameters:

option - the option

value - the option value

Returns:

this builder

onReaderReady

public ShellBuilder onReaderReady(Consumer<LineReader> onReaderReady)

Sets a callback invoked after the LineReader is created but before Shell.run().

This is useful for setting up post-reader customizations.

Parameters:

onReaderReady - the callback receiving the LineReader

Returns:

this builder

See Also:

• onReaderReady(BiConsumer)

onReaderReady

public ShellBuilder onReaderReady(BiConsumer<LineReader,CommandDispatcher> onReaderReady)

Sets a callback invoked after the LineReader is created but before Shell.run().

This is useful for setting up CommandTailTipWidgets or other post-reader customizations that need access to both the reader and the dispatcher.

 Shell.builder()
     .onReaderReady((reader, dispatcher) -> {
         new CommandTailTipWidgets(reader, dispatcher, 5).enable();
     })
     .build();
 

Parameters:

onReaderReady - the callback receiving the LineReader and CommandDispatcher

Returns:

this builder

initScript

public ShellBuilder initScript(File initScript)

Sets the initialization script to execute on startup.

Parameters:

initScript - the init script file

Returns:

this builder

jobManager

public ShellBuilder jobManager(JobManager jobManager)

Sets the job manager for the shell.

Parameters:

jobManager - the job manager

Returns:

this builder

pipelineParser

public ShellBuilder pipelineParser(PipelineParser pipelineParser)

Sets a custom pipeline parser for the shell.

This allows custom operator registration and subclass overrides of operator matching.

Parameters:

pipelineParser - the pipeline parser

Returns:

this builder

aliasManager

public ShellBuilder aliasManager(AliasManager aliasManager)

Sets the alias manager for the shell.

When set, aliases are expanded before pipeline parsing, and built-in alias/unalias commands are registered automatically.

Parameters:

aliasManager - the alias manager

Returns:

this builder

historyCommands

public ShellBuilder historyCommands(boolean enable)

Enables or disables built-in history commands (history).

Parameters:

enable - true to enable

Returns:

this builder

helpCommands

public ShellBuilder helpCommands(boolean enable)

Enables or disables built-in help commands (help).

Parameters:

enable - true to enable

Returns:

this builder

optionCommands

public ShellBuilder optionCommands(boolean enable)

Enables or disables built-in option commands (setopt, unsetopt, setvar).

Parameters:

enable - true to enable

Returns:

this builder

highlighter

public ShellBuilder highlighter(Highlighter highlighter)

Sets a custom highlighter for the shell's LineReader.

Parameters:

highlighter - the highlighter

Returns:

this builder

commandHighlighter

public ShellBuilder commandHighlighter(boolean enable)

Enables or disables the built-in command-aware syntax highlighter.

When enabled, known commands are highlighted in bold and unknown commands are highlighted in red.

Parameters:

enable - true to enable

Returns:

this builder

lineExpander

public ShellBuilder lineExpander(LineExpander lineExpander)

Sets the line expander for variable expansion.

The line expander is called after alias expansion and before pipeline parsing.

Parameters:

lineExpander - the line expander

Returns:

this builder

scriptRunner

public ShellBuilder scriptRunner(ScriptRunner scriptRunner)

Sets the script runner for executing script files.

Parameters:

scriptRunner - the script runner

Returns:

this builder

scriptCommands

public ShellBuilder scriptCommands(boolean enable)

Enables or disables built-in script commands (source, .).

Parameters:

enable - true to enable

Returns:

this builder

variableCommands

public ShellBuilder variableCommands(boolean enable)

Enables or disables built-in variable commands (set, unset, export).

Parameters:

enable - true to enable

Returns:

this builder

build

public Shell build()
            throws IOException

Builds the Shell instance.

If no terminal is provided, a system terminal is created. If no dispatcher is provided, a DefaultCommandDispatcher is created. All configured groups are added to the dispatcher.

Returns:

a new Shell

Throws:

IOException - if terminal creation fails