Package org.jline.console

Interface ConsoleEngine

All Superinterfaces:

CommandRegistry

All Known Implementing Classes:

ConsoleEngineImpl

public interface ConsoleEngine
extends CommandRegistry

Interface for managing console variables, commands, and script execution in a console application.

The ConsoleEngine extends CommandRegistry to provide additional functionality for:

• Managing console variables and their values
• Executing scripts and commands
• Handling command line expansion and parameter substitution
• Managing aliases and pipes
• Post-processing command execution results

Implementations of this interface can be used to create custom console engines for specific scripting languages or execution environments.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	ConsoleEngine.ExecutionResult	Class representing the result of executing a command.
static class	ConsoleEngine.WidgetCreator	Class for creating widgets from console functions.

Nested classes/interfaces inherited from interface org.jline.console.CommandRegistry

CommandRegistry.CommandSession

Field Summary

Fields

Modifier and Type	Field	Description
static final String	VAR_NANORC	Console string variable containing the full path to the nanorc configuration file.

Method Summary

Modifier and Type	Method	Description
<T> T	consoleOption(String option, T defval)	Reads a console option value with a default value if the option doesn't exist.
default Object	execute(File script)	Executes either a JLine script or a ScriptEngine script.
default Object	execute(File script, String rawLine, String[] args)	Executes either a JLine script or a ScriptEngine script with the specified arguments.
Object	execute(String name, String rawLine, String[] args)	Executes a command line that does not contain a command known by the system registry.
Object	execute(Path script, String rawLine, String[] args)	Executes either a JLine script or a ScriptEngine script with the specified arguments.
boolean	executeWidget(Object function)	Executes a widget function.
String	expandCommandLine(String line)	Substitutes a command line with a system registry invoke method call.
Object[]	expandParameters(String[] args)	Substitutes argument references with their values.
String	expandToList(List<String> params)	Expands a list of script parameters to a string representation.
String	getAlias(String name)	Returns the value of the alias with the specified name.
List<String>	getNamedPipes()	Returns the names of all named pipes.
Map<String,List<String>>	getPipes()	Returns all defined pipes.
Object	getVariable(String name)	Gets the value of a console variable.
boolean	hasAlias(String name)	Checks if an alias with the specified name exists.
boolean	hasVariable(String name)	Tests if a variable with the specified name exists.
boolean	isExecuting()	Checks if the console engine is currently executing a script.
void	persist(Path file, Object object)	Persists an object to a file.
static String	plainCommand(String command)	Removes the first character of the command name if it is a colon.
ConsoleEngine.ExecutionResult	postProcess(Object result)	Post-processes the result of executing a command.
ConsoleEngine.ExecutionResult	postProcess(String line, Object result, String output)	Post-processes the result of executing a command.
void	println(Object object)	Prints an object to the console.
void	purge()	Deletes temporary console variables.
void	putVariable(String name, Object value)	Creates or updates a console variable.
List<org.jline.reader.Completer>	scriptCompleters()	Returns completers for scripts and variables.
Map<String,Boolean>	scripts()	Returns all scripts found in the PATH environment variable.
void	setConsoleOption(String name, Object value)	Sets a console option value.
void	setLineReader(org.jline.reader.LineReader reader)	Sets the LineReader instance to be used by this console engine.
void	setScriptExtension(String extension)	Sets the file name extension used by console scripts.
void	setSystemRegistry(SystemRegistry systemRegistry)	Sets the SystemRegistry instance to be used by this console engine.
Object	slurp(Path file)	Reads an object from a file.
void	trace(Object object)	Prints an object if tracing is enabled.

Methods inherited from interface org.jline.console.CommandRegistry

commandAliases, commandDescription, commandInfo, commandNames, compileCompleters, hasCommand, invoke, name

Field Details

VAR_NANORC

static final String VAR_NANORC

Console string variable containing the full path to the nanorc configuration file. This variable can be used to customize the nano editor's behavior when used within the console.

See Also:

• Constant Field Values

Method Details

plainCommand

static String plainCommand(String command)

Removes the first character of the command name if it is a colon.

This method is used to normalize command names that may be prefixed with a colon, which is a common convention in some command-line interfaces.

Parameters:

command - the name of the command to normalize

Returns:

the command name without the starting colon, or the original command name if it doesn't start with a colon

setLineReader

void setLineReader(org.jline.reader.LineReader reader)

Sets the LineReader instance to be used by this console engine.

The LineReader is used for reading input from the user and providing features like command history, tab completion, and line editing.

Parameters:

reader - the LineReader instance to use

setSystemRegistry

void setSystemRegistry(SystemRegistry systemRegistry)

Sets the SystemRegistry instance to be used by this console engine.

The SystemRegistry is used for executing commands and managing the console environment. It provides access to registered commands and handles command execution.

Parameters:

systemRegistry - the SystemRegistry instance to use

expandParameters

Object[] expandParameters(String[] args)
                   throws Exception

Substitutes argument references with their values.

This method expands arguments that reference variables or other values, replacing them with their actual values. For example, a reference like "$VAR" might be replaced with the value of the variable "VAR".

Parameters:

args - the arguments to be expanded

Returns:

the expanded arguments with references replaced by their values

Throws:

Exception - if an error occurs during expansion

expandCommandLine

String expandCommandLine(String line)

Substitutes a command line with a system registry invoke method call.

This method expands a command line by replacing it with a call to the system registry's invoke method. This is used to handle command execution through the system registry.

Parameters:

line - the command line to be expanded

Returns:

the expanded command line with the system registry invoke method call

expandToList

String expandToList(List<String> params)

Expands a list of script parameters to a string representation.

This method converts a list of script parameters into a string that can be used in script execution. The parameters may be expanded or formatted according to the console engine's rules.

Parameters:

params - the list of script parameters to expand

Returns:

a string representation of the expanded parameters list

scripts

Map<String,Boolean> scripts()

Returns all scripts found in the PATH environment variable.

This method searches for scripts in the directories specified by the PATH environment variable and returns a map of script names to a boolean indicating whether each script is a console script.

Returns:

a map where keys are script file names and values are true if the script is a console script

setScriptExtension

void setScriptExtension(String extension)

Sets the file name extension used by console scripts.

This method configures the file extension that the console engine will recognize as indicating a console script. Files with this extension will be treated as console scripts when executing scripts.

Parameters:

extension - the file extension to use for console scripts (e.g., ".jsh")

hasAlias

boolean hasAlias(String name)

Checks if an alias with the specified name exists.

This method determines whether an alias has been defined for the specified name. Aliases can be used to create shortcuts for commands or command sequences.

Parameters:

name - the alias name to check

Returns:

true if an alias with the specified name exists, false otherwise

getAlias

String getAlias(String name)

Returns the value of the alias with the specified name.

This method retrieves the command or command sequence that the specified alias is defined to represent. Aliases can be used to create shortcuts for commands or command sequences.

Parameters:

name - the alias name

Returns:

the value of the alias, or null if no alias with the specified name exists

getPipes

Map<String,List<String>> getPipes()

Returns all defined pipes.

This method retrieves a map of all pipes defined in the console engine. Pipes are used to connect the output of one command to the input of another.

Returns:

a map of defined pipes, where keys are pipe names and values are pipe definitions

getNamedPipes

List<String> getNamedPipes()

Returns the names of all named pipes.

This method retrieves a list of all named pipes defined in the console engine. Named pipes are pipes that have been given a specific name for easier reference.

Returns:

a list of named pipe names

scriptCompleters

List<org.jline.reader.Completer> scriptCompleters()

Returns completers for scripts and variables.

This method retrieves a list of completers that can be used for tab completion of script names and variable names in the console.

Returns:

a list of completers for scripts and variables

persist

void persist(Path file,
 Object object)

Persists an object to a file.

This method serializes the specified object and writes it to the specified file. The object can later be read back using the slurp(Path) method.

Parameters:

file - the file to write the object to

object - the object to persist

slurp

Object slurp(Path file)
      throws IOException

Reads an object from a file.

This method reads and deserializes an object from the specified file. The object should have been written using the persist(Path, Object) method.

Parameters:

file - the file to read the object from

Returns:

the deserialized object

Throws:

IOException - if an I/O error occurs while reading the file

consoleOption

<T> T consoleOption(String option,
 T defval)

Reads a console option value with a default value if the option doesn't exist.

This method retrieves the value of a console option, returning a default value if the option doesn't exist. Console options are used to configure the behavior of the console engine and its components.

Type Parameters:

T - the type of the option value

Parameters:

option - the name of the option to read

defval - the default value to return if the option doesn't exist

Returns:

the value of the option, or the default value if the option doesn't exist

setConsoleOption

void setConsoleOption(String name,
 Object value)

Sets a console option value.

This method sets the value of a console option. Console options are used to configure the behavior of the console engine and its components.

Parameters:

name - the name of the option to set

value - the value to assign to the option

execute

Object execute(String name,
 String rawLine,
 String[] args)
        throws Exception

Executes a command line that does not contain a command known by the system registry.

This method handles the execution of command lines that are not recognized as commands by the system registry. If the line is neither a JLine script nor a ScriptEngine script, it will be evaluated as a ScriptEngine statement.

Parameters:

name - the parsed command or script name

rawLine - the raw command line as entered by the user

args - the parsed arguments of the command

Returns:

the result of executing the command line

Throws:

Exception - if an error occurs during execution

execute

default Object execute(File script)
                throws Exception

Executes either a JLine script or a ScriptEngine script.

This method executes the specified script file, determining whether it is a JLine script or a ScriptEngine script based on its extension or content. This is a convenience method that calls execute(Path, String, String[]) with an empty raw line and no arguments.

Parameters:

script - the script file to execute

Returns:

the result of executing the script

Throws:

Exception - if an error occurs during execution

execute

default Object execute(File script,
 String rawLine,
 String[] args)
                throws Exception

Executes either a JLine script or a ScriptEngine script with the specified arguments.

This method executes the specified script file with the specified arguments, determining whether it is a JLine script or a ScriptEngine script based on its extension or content. This is a convenience method that calls execute(Path, String, String[]) with the script file converted to a Path.

Parameters:

script - the script file to execute

rawLine - the raw command line as entered by the user

args - the arguments to pass to the script

Returns:

the result of executing the script

Throws:

Exception - if an error occurs during execution

execute

Object execute(Path script,
 String rawLine,
 String[] args)
        throws Exception

Executes either a JLine script or a ScriptEngine script with the specified arguments.

This method executes the specified script file with the specified arguments, determining whether it is a JLine script or a ScriptEngine script based on its extension or content.

Parameters:

script - the script file to execute

rawLine - the raw command line as entered by the user

args - the arguments to pass to the script

Returns:

the result of executing the script

Throws:

Exception - if an error occurs during execution

postProcess

ConsoleEngine.ExecutionResult postProcess(String line,
 Object result,
 String output)

Post-processes the result of executing a command.

This method processes the result of executing a command, handling any special cases such as assigning the result to a console variable. If the result is to be assigned to a console variable, this method will return null.

Parameters:

line - the command line that was executed

result - the result of executing the command

output - the redirected output of the command, if any

Returns:

the processed result, or null if the result was assigned to a console variable

postProcess

ConsoleEngine.ExecutionResult postProcess(Object result)

Post-processes the result of executing a command.

This method processes the result of executing a command, handling any special cases. This is a convenience method that calls postProcess(String, Object, String) with a null command line and output.

Parameters:

result - the result of executing the command

Returns:

the processed result

trace

void trace(Object object)

Prints an object if tracing is enabled.

This method prints the specified object to the console if tracing is enabled. Tracing can be used for debugging or logging purposes.

Parameters:

object - the object to print

println

void println(Object object)

Prints an object to the console.

This method prints the specified object to the console, regardless of whether tracing is enabled.

Parameters:

object - the object to print

putVariable

void putVariable(String name,
 Object value)

Creates or updates a console variable.

This method creates a new console variable with the specified name and value, or updates an existing variable if one with the specified name already exists.

Parameters:

name - the name of the variable to create or update

value - the value to assign to the variable

getVariable

Object getVariable(String name)

Gets the value of a console variable.

This method retrieves the value of the console variable with the specified name.

Parameters:

name - the name of the variable to get

Returns:

the value of the variable, or null if no variable with the specified name exists

hasVariable

boolean hasVariable(String name)

Tests if a variable with the specified name exists.

This method determines whether a console variable with the specified name exists.

Parameters:

name - the name of the variable to check

Returns:

true if a variable with the specified name exists, false otherwise

purge

void purge()

Deletes temporary console variables.

This method removes all temporary console variables, which are typically created during command execution and are not meant to persist between commands.

executeWidget

boolean executeWidget(Object function)

Executes a widget function.

This method executes the specified widget function, which can be used to perform custom actions in the console.

Parameters:

function - the widget function to execute

Returns:

true if the function was executed successfully, false otherwise

isExecuting

boolean isExecuting()

Checks if the console engine is currently executing a script.

This method determines whether the console engine is in the process of executing a script, as opposed to processing interactive commands.

Returns:

true if the console engine is executing a script, false otherwise