Package org.jline.terminal

Class TerminalBuilder

java.lang.Object

org.jline.terminal.TerminalBuilder

public final class TerminalBuilder
extends Object

Builder class to create terminals.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	TerminalBuilder.SystemOutput

Field Summary

Fields

Modifier and Type	Field	Description
static final Set<String>	DEPRECATED_PROVIDERS
static final String	PROP_CODEPAGE
static final String	PROP_COLOR_DISTANCE
static final String	PROP_DISABLE_ALTERNATE_CHARSET
static final String	PROP_DISABLE_DEPRECATED_PROVIDER_WARNING
static final String	PROP_DUMB
static final String	PROP_DUMB_COLOR
static final String	PROP_ENCODING
static final String	PROP_EXEC
static final String	PROP_FFM
static final String	PROP_FILE_DESCRIPTOR_CREATION_MODE
static final String	PROP_FILE_DESCRIPTOR_CREATION_MODE_DEFAULT
static final String	PROP_FILE_DESCRIPTOR_CREATION_MODE_NATIVE
static final String	PROP_FILE_DESCRIPTOR_CREATION_MODE_REFLECTION
static final String	PROP_JANSI
static final String	PROP_JNA
static final String	PROP_JNI
static final String	PROP_NON_BLOCKING_READS
static final String	PROP_OUTPUT
static final String	PROP_OUTPUT_ERR
static final String	PROP_OUTPUT_ERR_OUT
static final String	PROP_OUTPUT_FORCED_ERR
static final String	PROP_OUTPUT_FORCED_OUT
static final String	PROP_OUTPUT_OUT
static final String	PROP_OUTPUT_OUT_ERR
static final String	PROP_PROVIDER
static final String	PROP_PROVIDER_DUMB
static final String	PROP_PROVIDER_EXEC
static final String	PROP_PROVIDER_FFM
static final String	PROP_PROVIDER_JANSI
static final String	PROP_PROVIDER_JNA
static final String	PROP_PROVIDER_JNI
static final String	PROP_PROVIDERS
static final String	PROP_PROVIDERS_DEFAULT
static final String	PROP_REDIRECT_PIPE_CREATION_MODE
static final String	PROP_REDIRECT_PIPE_CREATION_MODE_DEFAULT
static final String	PROP_REDIRECT_PIPE_CREATION_MODE_NATIVE
static final String	PROP_REDIRECT_PIPE_CREATION_MODE_REFLECTION
static final String	PROP_TYPE

Method Summary

Modifier and Type	Method	Description
TerminalBuilder	attributes(Attributes attributes)	Attributes to use when creating a non system terminal, i.e. when the builder has been given the input and output streams using the streams(InputStream, OutputStream) method or when system(boolean) has been explicitly called with false.
Terminal	build()	Builds the terminal.
static TerminalBuilder	builder()	Creates a new terminal builder instance.
TerminalBuilder	codepage(int codepage)	Deprecated. JLine now writes Unicode output independently from the selected code page.
TerminalBuilder	color(boolean color)
Charset	computeEncoding()
TerminalBuilder.SystemOutput	computeSystemOutput()
String	computeType()
TerminalBuilder	dumb(boolean dumb)	Enables or disables the PROP_PROVIDER_DUMB/dumb terminal provider.
TerminalBuilder	encoding(String encoding)	Set the encoding to use for reading/writing from the console.
TerminalBuilder	encoding(Charset encoding)	Set the Charset to use for reading/writing from the console.
TerminalBuilder	exec(boolean exec)	Enables or disables the PROP_PROVIDER_EXEC/exec terminal provider.
TerminalBuilder	ffm(boolean ffm)	Enables or disables the PROP_PROVIDER_FFM/ffm terminal provider.
List<TerminalProvider>	getProviders(String provider, IllegalStateException exception)	Get the list of available terminal providers.
TerminalBuilder	jansi(boolean jansi)	Enables or disables the PROP_PROVIDER_JANSI/jansi terminal provider.
TerminalBuilder	jna(boolean jna)	Enables or disables the PROP_PROVIDER_JNA/jna terminal provider.
TerminalBuilder	jni(boolean jni)	Enables or disables the PROP_PROVIDER_JNI/jni terminal provider.
TerminalBuilder	name(String name)
TerminalBuilder	nativeSignals(boolean nativeSignals)
TerminalBuilder	paused(boolean paused)	Initial paused state of the terminal (defaults to false).
TerminalBuilder	provider(String provider)	Forces the usage of the give terminal provider.
TerminalBuilder	providers(String providers)	Sets the list of providers to try when creating the terminal.
static void	setTerminalOverride(Terminal terminal)	Deprecated.
TerminalBuilder	signalHandler(Terminal.SignalHandler signalHandler)	Determines the default value for signal handlers.
TerminalBuilder	size(Size size)	Initial size to use when creating a non system terminal, i.e. when the builder has been given the input and output streams using the streams(InputStream, OutputStream) method or when system(boolean) has been explicitly called with false.
TerminalBuilder	streams(InputStream in, OutputStream out)
TerminalBuilder	system(boolean system)
TerminalBuilder	systemOutput(TerminalBuilder.SystemOutput systemOutput)	Indicates which standard stream should be used when displaying to the terminal.
static Terminal	terminal()	Returns the default system terminal.
TerminalBuilder	type(String type)

Methods inherited from class java.lang.Object

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

Field Details

PROP_ENCODING

public static final String PROP_ENCODING

See Also:

• Constant Field Values

PROP_CODEPAGE

public static final String PROP_CODEPAGE

See Also:

• Constant Field Values

PROP_TYPE

public static final String PROP_TYPE

See Also:

• Constant Field Values

PROP_PROVIDER

public static final String PROP_PROVIDER

See Also:

• Constant Field Values

PROP_PROVIDERS

public static final String PROP_PROVIDERS

See Also:

• Constant Field Values

PROP_PROVIDER_FFM

public static final String PROP_PROVIDER_FFM

See Also:

• Constant Field Values

PROP_PROVIDER_JNI

public static final String PROP_PROVIDER_JNI

See Also:

• Constant Field Values

PROP_PROVIDER_JANSI

public static final String PROP_PROVIDER_JANSI

See Also:

• Constant Field Values

PROP_PROVIDER_JNA

public static final String PROP_PROVIDER_JNA

See Also:

• Constant Field Values

PROP_PROVIDER_EXEC

public static final String PROP_PROVIDER_EXEC

See Also:

• Constant Field Values

PROP_PROVIDER_DUMB

public static final String PROP_PROVIDER_DUMB

See Also:

• Constant Field Values

PROP_PROVIDERS_DEFAULT

public static final String PROP_PROVIDERS_DEFAULT

PROP_FFM

public static final String PROP_FFM

See Also:

• Constant Field Values

PROP_JNI

public static final String PROP_JNI

See Also:

• Constant Field Values

PROP_JANSI

public static final String PROP_JANSI

See Also:

• Constant Field Values

PROP_JNA

public static final String PROP_JNA

See Also:

• Constant Field Values

PROP_EXEC

public static final String PROP_EXEC

See Also:

• Constant Field Values

PROP_DUMB

public static final String PROP_DUMB

See Also:

• Constant Field Values

PROP_DUMB_COLOR

public static final String PROP_DUMB_COLOR

See Also:

• Constant Field Values

PROP_OUTPUT

public static final String PROP_OUTPUT

See Also:

• Constant Field Values

PROP_OUTPUT_OUT

public static final String PROP_OUTPUT_OUT

See Also:

• Constant Field Values

PROP_OUTPUT_ERR

public static final String PROP_OUTPUT_ERR

See Also:

• Constant Field Values

PROP_OUTPUT_OUT_ERR

public static final String PROP_OUTPUT_OUT_ERR

See Also:

• Constant Field Values

PROP_OUTPUT_ERR_OUT

public static final String PROP_OUTPUT_ERR_OUT

See Also:

• Constant Field Values

PROP_OUTPUT_FORCED_OUT

public static final String PROP_OUTPUT_FORCED_OUT

See Also:

• Constant Field Values

PROP_OUTPUT_FORCED_ERR

public static final String PROP_OUTPUT_FORCED_ERR

See Also:

• Constant Field Values

PROP_NON_BLOCKING_READS

public static final String PROP_NON_BLOCKING_READS

See Also:

• Constant Field Values

PROP_COLOR_DISTANCE

public static final String PROP_COLOR_DISTANCE

See Also:

• Constant Field Values

PROP_DISABLE_ALTERNATE_CHARSET

public static final String PROP_DISABLE_ALTERNATE_CHARSET

See Also:

• Constant Field Values

PROP_FILE_DESCRIPTOR_CREATION_MODE

public static final String PROP_FILE_DESCRIPTOR_CREATION_MODE

See Also:

• Constant Field Values

PROP_FILE_DESCRIPTOR_CREATION_MODE_NATIVE

public static final String PROP_FILE_DESCRIPTOR_CREATION_MODE_NATIVE

See Also:

• Constant Field Values

PROP_FILE_DESCRIPTOR_CREATION_MODE_REFLECTION

public static final String PROP_FILE_DESCRIPTOR_CREATION_MODE_REFLECTION

See Also:

• Constant Field Values

PROP_FILE_DESCRIPTOR_CREATION_MODE_DEFAULT

public static final String PROP_FILE_DESCRIPTOR_CREATION_MODE_DEFAULT

PROP_REDIRECT_PIPE_CREATION_MODE

public static final String PROP_REDIRECT_PIPE_CREATION_MODE

See Also:

• Constant Field Values

PROP_REDIRECT_PIPE_CREATION_MODE_NATIVE

public static final String PROP_REDIRECT_PIPE_CREATION_MODE_NATIVE

See Also:

• Constant Field Values

PROP_REDIRECT_PIPE_CREATION_MODE_REFLECTION

public static final String PROP_REDIRECT_PIPE_CREATION_MODE_REFLECTION

See Also:

• Constant Field Values

PROP_REDIRECT_PIPE_CREATION_MODE_DEFAULT

public static final String PROP_REDIRECT_PIPE_CREATION_MODE_DEFAULT

DEPRECATED_PROVIDERS

public static final Set<String> DEPRECATED_PROVIDERS

PROP_DISABLE_DEPRECATED_PROVIDER_WARNING

public static final String PROP_DISABLE_DEPRECATED_PROVIDER_WARNING

See Also:

• Constant Field Values

Method Details

terminal

public static Terminal terminal()
                         throws IOException

Returns the default system terminal. Terminals should be closed properly using the Closeable.close() method in order to restore the original terminal state.

This call is equivalent to: builder().build()

Returns:

the default system terminal

Throws:

IOException - if an error occurs

builder

public static TerminalBuilder builder()

Creates a new terminal builder instance.

Returns:

a builder

name

public TerminalBuilder name(String name)

streams

public TerminalBuilder streams(InputStream in,
 OutputStream out)

system

public TerminalBuilder system(boolean system)

systemOutput

public TerminalBuilder systemOutput(TerminalBuilder.SystemOutput systemOutput)

Indicates which standard stream should be used when displaying to the terminal. The default is to use the system output stream. Building a system terminal will fail if one of the stream specified is not linked to the controlling terminal.

Parameters:

systemOutput - The mode to choose the output stream.

Returns:

The builder.

provider

public TerminalBuilder provider(String provider)

Forces the usage of the give terminal provider.

Parameters:

provider - The TerminalProvider's name to use when creating the Terminal.

Returns:

The builder.

providers

public TerminalBuilder providers(String providers)

Sets the list of providers to try when creating the terminal. If not specified, the system property PROP_PROVIDERS will be used if set. Else, the value PROP_PROVIDERS_DEFAULT will be used.

Parameters:

providers - The list of TerminalProvider's names to check when creating the Terminal.

Returns:

The builder.

jna

public TerminalBuilder jna(boolean jna)

Enables or disables the PROP_PROVIDER_JNA/jna terminal provider. If not specified, the system property PROP_JNA will be used if set. If not specified, the provider will be checked.

jansi

public TerminalBuilder jansi(boolean jansi)

Enables or disables the PROP_PROVIDER_JANSI/jansi terminal provider. If not specified, the system property PROP_JANSI will be used if set. If not specified, the provider will be checked.

jni

public TerminalBuilder jni(boolean jni)

Enables or disables the PROP_PROVIDER_JNI/jni terminal provider. If not specified, the system property PROP_JNI will be used if set. If not specified, the provider will be checked.

exec

public TerminalBuilder exec(boolean exec)

Enables or disables the PROP_PROVIDER_EXEC/exec terminal provider. If not specified, the system property PROP_EXEC will be used if set. If not specified, the provider will be checked.

ffm

public TerminalBuilder ffm(boolean ffm)

Enables or disables the PROP_PROVIDER_FFM/ffm terminal provider. If not specified, the system property PROP_FFM will be used if set. If not specified, the provider will be checked.

dumb

public TerminalBuilder dumb(boolean dumb)

Enables or disables the PROP_PROVIDER_DUMB/dumb terminal provider. If not specified, the system property PROP_DUMB will be used if set. If not specified, the provider will be checked.

type

public TerminalBuilder type(String type)

color

public TerminalBuilder color(boolean color)

encoding

public TerminalBuilder encoding(String encoding)
                         throws UnsupportedCharsetException

Set the encoding to use for reading/writing from the console. If null (the default value), JLine will automatically select a Charset, usually the default system encoding. However, on some platforms (e.g. Windows) it may use a different one depending on the Terminal implementation.

Use Terminal.encoding() to get the Charset that should be used for a Terminal.

Parameters:

encoding - The encoding to use or null to automatically select one

Returns:

The builder

Throws:

UnsupportedCharsetException - If the given encoding is not supported

See Also:

• Terminal.encoding()

encoding

public TerminalBuilder encoding(Charset encoding)

Set the Charset to use for reading/writing from the console. If null (the default value), JLine will automatically select a Charset, usually the default system encoding. However, on some platforms (e.g. Windows) it may use a different one depending on the Terminal implementation.

Use Terminal.encoding() to get the Charset that should be used to read/write from a Terminal.

Parameters:

encoding - The encoding to use or null to automatically select one

Returns:

The builder

See Also:

• Terminal.encoding()

codepage

@Deprecated
public TerminalBuilder codepage(int codepage)

Deprecated.

JLine now writes Unicode output independently from the selected code page. Using this option will only make it emulate the selected code page for Terminal.input() and Terminal.output().

Parameters:

codepage - the codepage

Returns:

The builder

attributes

public TerminalBuilder attributes(Attributes attributes)

Attributes to use when creating a non system terminal, i.e. when the builder has been given the input and output streams using the streams(InputStream, OutputStream) method or when system(boolean) has been explicitly called with false.

Parameters:

attributes - the attributes to use

Returns:

The builder

See Also:

• size(Size)
• system(boolean)

size

public TerminalBuilder size(Size size)

Initial size to use when creating a non system terminal, i.e. when the builder has been given the input and output streams using the streams(InputStream, OutputStream) method or when system(boolean) has been explicitly called with false.

Parameters:

size - the initial size

Returns:

The builder

See Also:

• attributes(Attributes)
• system(boolean)

nativeSignals

public TerminalBuilder nativeSignals(boolean nativeSignals)

signalHandler

public TerminalBuilder signalHandler(Terminal.SignalHandler signalHandler)

Determines the default value for signal handlers. All signals will be mapped to the given handler.

Parameters:

signalHandler - the default signal handler

Returns:

The builder

paused

public TerminalBuilder paused(boolean paused)

Initial paused state of the terminal (defaults to false). By default, the terminal is started, but in some cases, one might want to make sure the input stream is not consumed before needed, in which case the terminal needs to be created in a paused state.

Parameters:

paused - the initial paused state

Returns:

The builder

See Also:

• Terminal.pause()

build

public Terminal build()
               throws IOException

Builds the terminal.

Returns:

the newly created terminal, never null

Throws:

IOException - if an error occurs

computeSystemOutput

public TerminalBuilder.SystemOutput computeSystemOutput()

computeType

public String computeType()

computeEncoding

public Charset computeEncoding()

getProviders

public List<TerminalProvider> getProviders(String provider,
 IllegalStateException exception)

Get the list of available terminal providers. This list is sorted according to the PROP_PROVIDERS system property.

Parameters:

provider - if not null, only this provider will be checked

exception - if a provider throws an exception, it will be added to this exception as a suppressed exception

Returns:

a list of terminal providers

setTerminalOverride

@Deprecated
public static void setTerminalOverride(Terminal terminal)

Deprecated.

Allows an application to override the result of build(). The intended use case is to allow a container or server application to control an embedded application that uses a LineReader that uses Terminal constructed with TerminalBuilder.build but provides no public api for setting the LineReader of the Terminal. For example, the sbt build tool uses a LineReader to implement an interactive shell. One of its supported commands is console which invokes the scala REPL. The scala REPL also uses a LineReader and it is necessary to override the Terminal used by the the REPL to share the same Terminal instance used by sbt.

When this method is called with a non-null Terminal, all subsequent calls to build() will return the provided Terminal regardless of how the TerminalBuilder was constructed. The default behavior of TerminalBuilder can be restored by calling setTerminalOverride with a null Terminal

Usage of setTerminalOverride should be restricted to cases where it isn't possible to update the api of the nested application to accept a instance.

Parameters:

terminal - the Terminal to globally override