- java.lang.Object
-
- org.jline.terminal.TerminalBuilder
-
public final class TerminalBuilder extends java.lang.ObjectBuilder class to createTerminalinstances with flexible configuration options.TerminalBuilder provides a fluent API for creating and configuring terminals with various characteristics. It supports multiple implementation providers and handles the complexities of terminal creation across different platforms and environments.
Terminal Providers
JLine supports multiple terminal provider implementations:
- FFM - Foreign Function Memory (Java 22+) based implementation
- JNI - Java Native Interface based implementation
- Exec - Implementation using external commands
- Dumb - Fallback-only implementation with limited capabilities (not included in default provider order)
The provider selection can be controlled using the
provider(String)method or theorg.jline.terminal.providersystem property. By default, providers are tried in the order: FFM, JNI, Exec.Native Library Support
When using providers that require native libraries (such as JNI), the appropriate native library will be loaded automatically. The loading of these libraries is handled by
JLineNativeLoaderfor the JNI provider.The native library loading can be configured using system properties as documented in
JLineNativeLoader.System vs. Non-System Terminals
TerminalBuilder can create two types of terminals:
- System terminals - Connected to the actual system input/output streams
- Non-system terminals - Connected to custom input/output streams
System terminals are created using
system(boolean)with a value oftrue, while non-system terminals require specifying input and output streams usingstreams(InputStream, OutputStream).Usage Examples
Creating a default system terminal:
Terminal terminal = TerminalBuilder.builder() .system(true) .build();Creating a terminal with custom streams:
Terminal terminal = TerminalBuilder.builder() .name("CustomTerminal") .streams(inputStream, outputStream) .encoding(StandardCharsets.UTF_8) .build();Creating a terminal with a specific provider:
Terminal terminal = TerminalBuilder.builder() .system(true) .provider("jni") .build();Creating a dumb terminal (with limited capabilities):
Terminal terminal = TerminalBuilder.builder() .dumb(true) .build();- See Also:
Terminal,JLineNativeLoader,TerminalProvider
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static classTerminalBuilder.SystemOutput
-
Field Summary
Fields Modifier and Type Field Description static java.lang.StringPROP_CLOSE_MODESystem property to control terminal stream closure behavior.static java.lang.StringPROP_CODEPAGEstatic java.lang.StringPROP_COLOR_DISTANCEstatic java.lang.StringPROP_DEV_TTYSystem property to enable the/dev/ttyfallback for creating a terminal when no system stream is connected to a TTY.static java.lang.StringPROP_DISABLE_ALTERNATE_CHARSETstatic java.lang.StringPROP_DRAIN_TIMEOUTstatic java.lang.StringPROP_DUMBstatic java.lang.StringPROP_DUMB_COLORstatic java.lang.StringPROP_ENCODINGstatic java.lang.StringPROP_EXECstatic java.lang.StringPROP_FFMstatic java.lang.StringPROP_FILE_DESCRIPTOR_CREATION_MODEstatic java.lang.StringPROP_FILE_DESCRIPTOR_CREATION_MODE_DEFAULTstatic java.lang.StringPROP_FILE_DESCRIPTOR_CREATION_MODE_NATIVEstatic java.lang.StringPROP_FILE_DESCRIPTOR_CREATION_MODE_REFLECTIONstatic java.lang.StringPROP_GRAPHEME_CLUSTERstatic java.lang.StringPROP_JNIstatic java.lang.StringPROP_NON_BLOCKING_READSstatic java.lang.StringPROP_OUTPUTstatic java.lang.StringPROP_OUTPUT_ERRstatic java.lang.StringPROP_OUTPUT_ERR_OUTstatic java.lang.StringPROP_OUTPUT_FORCED_ERRstatic java.lang.StringPROP_OUTPUT_FORCED_OUTstatic java.lang.StringPROP_OUTPUT_OUTstatic java.lang.StringPROP_OUTPUT_OUT_ERRstatic java.lang.StringPROP_PROBE_TIMEOUTstatic java.lang.StringPROP_PROVIDERstatic java.lang.StringPROP_PROVIDER_DUMBstatic java.lang.StringPROP_PROVIDER_EXECstatic java.lang.StringPROP_PROVIDER_FFMstatic java.lang.StringPROP_PROVIDER_JNIstatic java.lang.StringPROP_PROVIDERSstatic java.lang.StringPROP_PROVIDERS_DEFAULTstatic java.lang.StringPROP_REDIRECT_PIPE_CREATION_MODEstatic java.lang.StringPROP_REDIRECT_PIPE_CREATION_MODE_DEFAULTstatic java.lang.StringPROP_REDIRECT_PIPE_CREATION_MODE_NATIVEstatic java.lang.StringPROP_REDIRECT_PIPE_CREATION_MODE_REFLECTIONstatic java.lang.StringPROP_SOFTWARE_SIGNALSWhentrue(the default), system terminals intercept signal control characters (VINTR, VQUIT, VSUSP) in software and raise the correspondingTerminal.Signalwhen ISIG is cleared (raw mode).static java.lang.StringPROP_STDERR_ENCODINGstatic java.lang.StringPROP_STDIN_ENCODINGstatic java.lang.StringPROP_STDOUT_ENCODINGstatic java.lang.StringPROP_TYPE
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description TerminalBuilderattributes(Attributes attributes)Attributes to use when creating a non system terminal, i.e.Terminalbuild()Create and configure a Terminal instance according to this builder's settings.TerminalbuildDeferred()Asynchronous variant ofbuild()that returns aDeferredTerminalimmediately.static TerminalBuilderbuilder()Creates a new terminal builder instance for configuring and creating terminals.TerminalBuilderclassLoader(java.lang.ClassLoader classLoader)Sets an explicit classloader for terminal provider discovery.TerminalBuildercolor(boolean color)java.nio.charset.CharsetcomputeEncoding()java.nio.charset.CharsetcomputeStderrEncoding()java.nio.charset.CharsetcomputeStdinEncoding()java.nio.charset.CharsetcomputeStdoutEncoding()TerminalBuilder.SystemOutputcomputeSystemOutput()java.lang.StringcomputeType()TerminalBuilderdevTty(boolean devTty)Enables or disables the/dev/ttyfallback for creating a terminal when no system stream is connected to a TTY (e.g., when stdin/stdout are pipes).TerminalBuilderdumb(boolean dumb)Enables or disables thePROP_PROVIDER_DUMB/dumbterminal provider.TerminalBuilderencoding(java.lang.String encoding)Set the encoding to use for reading/writing from the console.TerminalBuilderencoding(java.nio.charset.Charset encoding)Set theCharsetto use for reading/writing from the console.TerminalBuilderenv(java.util.function.UnaryOperator<java.lang.String> env)Sets a custom environment variable provider for the terminal.TerminalBuilderexec(boolean exec)Enables or disables thePROP_PROVIDER_EXEC/execterminal provider.TerminalBuilderffm(boolean ffm)Enables or disables thePROP_PROVIDER_FFM/ffmterminal provider.java.util.List<TerminalProvider>getProviders(java.lang.String provider, java.lang.IllegalStateException exception)Get the available terminal providers, short-circuiting after the first success.java.util.List<TerminalProvider>getProviders(java.lang.String provider, java.lang.IllegalStateException exception, boolean all)Get the available terminal providers.TerminalBuildergraphemeCluster(boolean graphemeCluster)Controls whether mode 2027 (grapheme cluster segmentation) should be enabled on the terminal after construction.TerminalBuilderjansi(boolean jansi)Deprecated.Jansi is no longer used in JLine 4.TerminalBuilderjna(boolean jna)Deprecated.JNA is no longer used in JLine 4.TerminalBuilderjni(boolean jni)Enables or disables thePROP_PROVIDER_JNI/jniterminal provider.TerminalBuildername(java.lang.String name)TerminalBuildernativeSignals(boolean nativeSignals)TerminalBuilderpaused(boolean paused)Initial paused state of the terminal (defaults to false).TerminalBuilderprovider(java.lang.String provider)Forces the usage of the give terminal provider.TerminalBuilderproviders(java.lang.String providers)Sets the list of providers to try when creating the terminal.static voidsetTerminalOverride(Terminal terminal)Deprecated.This method is deprecated to discourage its use.TerminalBuildersignalHandler(Terminal.SignalHandler signalHandler)Determines the default value for signal handlers.TerminalBuildersize(Size size)Initial size to use when creating a non system terminal, i.e.TerminalBuilderstderrEncoding(java.lang.String encoding)Set the encoding to use for writing to standard error.TerminalBuilderstderrEncoding(java.nio.charset.Charset encoding)Set theCharsetto use for writing to standard error.TerminalBuilderstdinEncoding(java.lang.String encoding)Set the encoding to use for reading from standard input.TerminalBuilderstdinEncoding(java.nio.charset.Charset encoding)Set theCharsetto use for reading from standard input.TerminalBuilderstdoutEncoding(java.lang.String encoding)Set the encoding to use for writing to standard output.TerminalBuilderstdoutEncoding(java.nio.charset.Charset encoding)Set theCharsetto use for writing to standard output.TerminalBuilderstreams(java.io.InputStream in, java.io.OutputStream out)TerminalBuildersystem(boolean system)TerminalBuildersystemOutput(TerminalBuilder.SystemOutput systemOutput)Indicates which standard stream should be used when displaying to the terminal.static Terminalterminal()Returns the default system terminal with automatic configuration.TerminalBuildertype(java.lang.String type)
-
-
-
Field Detail
-
PROP_ENCODING
public static final java.lang.String PROP_ENCODING
- See Also:
- Constant Field Values
-
PROP_STDIN_ENCODING
public static final java.lang.String PROP_STDIN_ENCODING
- See Also:
- Constant Field Values
-
PROP_STDOUT_ENCODING
public static final java.lang.String PROP_STDOUT_ENCODING
- See Also:
- Constant Field Values
-
PROP_STDERR_ENCODING
public static final java.lang.String PROP_STDERR_ENCODING
- See Also:
- Constant Field Values
-
PROP_CODEPAGE
public static final java.lang.String PROP_CODEPAGE
- See Also:
- Constant Field Values
-
PROP_TYPE
public static final java.lang.String PROP_TYPE
- See Also:
- Constant Field Values
-
PROP_PROVIDER
public static final java.lang.String PROP_PROVIDER
- See Also:
- Constant Field Values
-
PROP_PROVIDERS
public static final java.lang.String PROP_PROVIDERS
- See Also:
- Constant Field Values
-
PROP_PROVIDER_FFM
public static final java.lang.String PROP_PROVIDER_FFM
- See Also:
- Constant Field Values
-
PROP_PROVIDER_JNI
public static final java.lang.String PROP_PROVIDER_JNI
- See Also:
- Constant Field Values
-
PROP_PROVIDER_EXEC
public static final java.lang.String PROP_PROVIDER_EXEC
- See Also:
- Constant Field Values
-
PROP_PROVIDER_DUMB
public static final java.lang.String PROP_PROVIDER_DUMB
- See Also:
- Constant Field Values
-
PROP_PROVIDERS_DEFAULT
public static final java.lang.String PROP_PROVIDERS_DEFAULT
-
PROP_FFM
public static final java.lang.String PROP_FFM
- See Also:
- Constant Field Values
-
PROP_JNI
public static final java.lang.String PROP_JNI
- See Also:
- Constant Field Values
-
PROP_EXEC
public static final java.lang.String PROP_EXEC
- See Also:
- Constant Field Values
-
PROP_DUMB
public static final java.lang.String PROP_DUMB
- See Also:
- Constant Field Values
-
PROP_DUMB_COLOR
public static final java.lang.String PROP_DUMB_COLOR
- See Also:
- Constant Field Values
-
PROP_OUTPUT
public static final java.lang.String PROP_OUTPUT
- See Also:
- Constant Field Values
-
PROP_OUTPUT_OUT
public static final java.lang.String PROP_OUTPUT_OUT
- See Also:
- Constant Field Values
-
PROP_OUTPUT_ERR
public static final java.lang.String PROP_OUTPUT_ERR
- See Also:
- Constant Field Values
-
PROP_OUTPUT_OUT_ERR
public static final java.lang.String PROP_OUTPUT_OUT_ERR
- See Also:
- Constant Field Values
-
PROP_OUTPUT_ERR_OUT
public static final java.lang.String PROP_OUTPUT_ERR_OUT
- See Also:
- Constant Field Values
-
PROP_OUTPUT_FORCED_OUT
public static final java.lang.String PROP_OUTPUT_FORCED_OUT
- See Also:
- Constant Field Values
-
PROP_OUTPUT_FORCED_ERR
public static final java.lang.String PROP_OUTPUT_FORCED_ERR
- See Also:
- Constant Field Values
-
PROP_DEV_TTY
public static final java.lang.String PROP_DEV_TTY
System property to enable the/dev/ttyfallback for creating a terminal when no system stream is connected to a TTY.When set to
"true"and running on a POSIX system where stdin, stdout, and stderr are all pipes (not TTYs), JLine will attempt to open/dev/tty(the controlling terminal) directly and use it for terminal I/O. This allows interactive features to work even when the process was launched with redirected streams (e.g., via Maven'sexec-maven-pluginwith theexec:execgoal).Defaults to
false. Can also be set programmatically viadevTty(boolean).- See Also:
devTty(boolean), Constant Field Values
-
PROP_NON_BLOCKING_READS
public static final java.lang.String PROP_NON_BLOCKING_READS
- See Also:
- Constant Field Values
-
PROP_SOFTWARE_SIGNALS
public static final java.lang.String PROP_SOFTWARE_SIGNALS
Whentrue(the default), system terminals intercept signal control characters (VINTR, VQUIT, VSUSP) in software and raise the correspondingTerminal.Signalwhen ISIG is cleared (raw mode). This restoresterminal.handle(Signal.INT, ...)behavior that was lost whenenterRawMode()started clearing ISIG.Set to
falsefor pure native terminal behavior where no automatic signal translation occurs ? the application must handle raw bytes itself.The default may change to
falsein a future release (4.2 or later).- Since:
- 4.1.4
- See Also:
- Constant Field Values
-
PROP_COLOR_DISTANCE
public static final java.lang.String PROP_COLOR_DISTANCE
- See Also:
- Constant Field Values
-
PROP_DISABLE_ALTERNATE_CHARSET
public static final java.lang.String PROP_DISABLE_ALTERNATE_CHARSET
- See Also:
- Constant Field Values
-
PROP_CLOSE_MODE
public static final java.lang.String PROP_CLOSE_MODE
System property to control terminal stream closure behavior.This property controls what happens when code attempts to read from or write to terminal streams (reader, writer, input, output) after the terminal has been closed.
Two levels of closure enforcement:
- Terminal-level: Calling methods on the terminal itself after
close()always throwsIllegalStateException, regardless of this property. - Stream-level: Using held references to streams obtained before
close()is controlled by this property.
Property values:
"strict"(default in JLine 4.x): Accessing closed streams throwsClosedException"warn"(default in JLine 3.x): Accessing closed streams logs a warning but continues to operate"lenient": Accessing closed streams is silently allowed (no warning, no exception)
Example:
Terminal terminal = TerminalBuilder.terminal(); NonBlockingReader reader = terminal.reader(); // Get reference before close terminal.close(); // This always throws IllegalStateException (terminal-level): terminal.reader(); // throws IllegalStateException // This behavior depends on jline.terminal.closeMode (stream-level): reader.read(); // throws ClosedException in "strict" mode // logs warning in "warn" mode // silently continues in "lenient" mode - Terminal-level: Calling methods on the terminal itself after
-
PROP_FILE_DESCRIPTOR_CREATION_MODE
public static final java.lang.String PROP_FILE_DESCRIPTOR_CREATION_MODE
- See Also:
- Constant Field Values
-
PROP_FILE_DESCRIPTOR_CREATION_MODE_NATIVE
public static final java.lang.String PROP_FILE_DESCRIPTOR_CREATION_MODE_NATIVE
- See Also:
- Constant Field Values
-
PROP_FILE_DESCRIPTOR_CREATION_MODE_REFLECTION
public static final java.lang.String PROP_FILE_DESCRIPTOR_CREATION_MODE_REFLECTION
- See Also:
- Constant Field Values
-
PROP_FILE_DESCRIPTOR_CREATION_MODE_DEFAULT
public static final java.lang.String PROP_FILE_DESCRIPTOR_CREATION_MODE_DEFAULT
-
PROP_REDIRECT_PIPE_CREATION_MODE
public static final java.lang.String PROP_REDIRECT_PIPE_CREATION_MODE
- See Also:
- Constant Field Values
-
PROP_REDIRECT_PIPE_CREATION_MODE_NATIVE
public static final java.lang.String PROP_REDIRECT_PIPE_CREATION_MODE_NATIVE
- See Also:
- Constant Field Values
-
PROP_REDIRECT_PIPE_CREATION_MODE_REFLECTION
public static final java.lang.String PROP_REDIRECT_PIPE_CREATION_MODE_REFLECTION
- See Also:
- Constant Field Values
-
PROP_REDIRECT_PIPE_CREATION_MODE_DEFAULT
public static final java.lang.String PROP_REDIRECT_PIPE_CREATION_MODE_DEFAULT
-
PROP_GRAPHEME_CLUSTER
public static final java.lang.String PROP_GRAPHEME_CLUSTER
- See Also:
- Constant Field Values
-
PROP_PROBE_TIMEOUT
public static final java.lang.String PROP_PROBE_TIMEOUT
- See Also:
- Constant Field Values
-
PROP_DRAIN_TIMEOUT
public static final java.lang.String PROP_DRAIN_TIMEOUT
- See Also:
- Constant Field Values
-
-
Method Detail
-
terminal
public static Terminal terminal() throws java.io.IOException
Returns the default system terminal with automatic configuration.This method creates a terminal connected to the system's standard input and output streams, automatically detecting the appropriate terminal type and capabilities for the current environment. It's the simplest way to get a working terminal instance for most applications.
The terminal is created with default settings, which include:
- System streams for input and output
- Auto-detected terminal type
- System default encoding
- Native signal handling
This call is equivalent to:
builder().build()Important: Terminals should be closed properly using the
Closeable.close()method when they are no longer needed in order to restore the original terminal state.Example usage:
try (Terminal terminal = TerminalBuilder.terminal()) { terminal.writer().println("Hello, terminal!"); terminal.flush(); // Use terminal... }- Returns:
- the default system terminal, never
null - Throws:
java.io.IOException- if an error occurs during terminal creation- See Also:
builder()
-
builder
public static TerminalBuilder builder()
Creates a new terminal builder instance for configuring and creating terminals.This method returns a builder that can be used to configure various aspects of the terminal before creating it. The builder provides a fluent API for setting terminal properties such as name, type, encoding, input/output streams, and more.
Example usage:
Terminal terminal = TerminalBuilder.builder() .name("MyTerminal") .system(true) .encoding(StandardCharsets.UTF_8) .build();- Returns:
- a new terminal builder instance, never
null - See Also:
terminal()
-
name
public TerminalBuilder name(java.lang.String name)
-
streams
public TerminalBuilder streams(java.io.InputStream in, java.io.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(java.lang.String provider)
Forces the usage of the give terminal provider.- Parameters:
provider- TheTerminalProvider's name to use when creating the Terminal.- Returns:
- The builder.
-
providers
public TerminalBuilder providers(java.lang.String providers)
Sets the list of providers to try when creating the terminal. If not specified, the system propertyPROP_PROVIDERSwill be used if set. Else, the valuePROP_PROVIDERS_DEFAULTwill be used.- Parameters:
providers- The list ofTerminalProvider's names to check when creating the Terminal.- Returns:
- The builder.
-
classLoader
public TerminalBuilder classLoader(java.lang.ClassLoader classLoader)
Sets an explicit classloader for terminal provider discovery.When JLine is loaded through a custom classloader (e.g., OSGi containers, application servers, plugin systems), the default provider discovery may fail because the thread's context classloader cannot locate the provider resource files bundled in the JLine JARs. This method allows specifying the classloader that has access to those JARs.
The specified classloader is tried first during provider discovery, before falling back to the thread context classloader and JLine's own classloader. See
TerminalProvider.load(String, ClassLoader)for the full resolution order.Example ? plugin system where JLine is loaded at runtime:
Terminal terminal = TerminalBuilder.builder() .streams(inputStream, outputStream) .classLoader(getClass().getClassLoader()) .build();- Parameters:
classLoader- the classloader to use for provider discovery, ornullto use the default resolution strategy- Returns:
- this builder
- See Also:
TerminalProvider.load(String, ClassLoader)
-
jni
public TerminalBuilder jni(boolean jni)
Enables or disables thePROP_PROVIDER_JNI/jniterminal provider.The JNI provider uses the JLine native library loaded by
JLineNativeLoaderto access low-level terminal functionality. This provider generally offers the best performance and most complete terminal support.If not specified, the system property
PROP_JNIwill be used if set. If not specified, the provider will be checked for availability.The native library loading can be configured using system properties as documented in
JLineNativeLoader.- Parameters:
jni- true to enable the JNI provider, false to disable it- Returns:
- this builder
- See Also:
JLineNativeLoader
-
exec
public TerminalBuilder exec(boolean exec)
Enables or disables thePROP_PROVIDER_EXEC/execterminal provider. If not specified, the system propertyPROP_EXECwill be used if set. If not specified, the provider will be checked.
-
ffm
public TerminalBuilder ffm(boolean ffm)
Enables or disables thePROP_PROVIDER_FFM/ffmterminal provider. If not specified, the system propertyPROP_FFMwill be used if set. If not specified, the provider will be checked.
-
jansi
@Deprecated public TerminalBuilder jansi(boolean jansi)
Deprecated.Jansi is no longer used in JLine 4. Native support is provided automatically via FFM or JNI providers.No-op retained for backwards compatibility with JLine 3.In JLine 3, this method enabled native terminal support via Jansi. JLine 4 replaced Jansi with its own FFM/JNI providers that are used automatically, so this method is no longer needed.
- Parameters:
jansi- ignored- Returns:
- this builder
-
jna
@Deprecated public TerminalBuilder jna(boolean jna)
Deprecated.JNA is no longer used in JLine 4. Native support is provided automatically via FFM or JNI providers.No-op retained for backwards compatibility with JLine 3.In JLine 3, this method enabled native terminal support via JNA. JLine 4 replaced JNA with its own FFM/JNI providers that are used automatically, so this method is no longer needed.
- Parameters:
jna- ignored- Returns:
- this builder
-
dumb
public TerminalBuilder dumb(boolean dumb)
Enables or disables thePROP_PROVIDER_DUMB/dumbterminal provider. If not specified, the system propertyPROP_DUMBwill be used if set. If not specified, the provider will be checked.
-
devTty
public TerminalBuilder devTty(boolean devTty)
Enables or disables the/dev/ttyfallback for creating a terminal when no system stream is connected to a TTY (e.g., when stdin/stdout are pipes).When enabled and running on a POSIX system where no system stream (stdin, stdout, stderr) is connected to a terminal, JLine will attempt to open
/dev/tty(the controlling terminal) directly and use it for terminal I/O. This allows interactive features like tab completion, syntax highlighting, and history navigation to work even when the process was launched with redirected streams.A common use case is running a JLine application via Maven's
exec-maven-pluginwith theexec:execgoal, which forks a new JVM with piped stdin/stdout.If not specified, the system property
PROP_DEV_TTYwill be used. Defaults tofalse.- Parameters:
devTty- true to enable the /dev/tty fallback- Returns:
- this builder
-
type
public TerminalBuilder type(java.lang.String type)
-
color
public TerminalBuilder color(boolean color)
-
encoding
public TerminalBuilder encoding(java.lang.String encoding) throws java.nio.charset.UnsupportedCharsetException
Set the encoding to use for reading/writing from the console. Ifnull(the default value), JLine will automatically select aCharset, usually the default system encoding. However, on some platforms (e.g. Windows) it may use a different one depending on theTerminalimplementation.Use
Terminal.encoding()to get theCharsetthat should be used for aTerminal.This method sets a single encoding for all streams (stdin, stdout, stderr). To set separate encodings for each stream, use
stdinEncoding(Charset),stdoutEncoding(Charset), andstderrEncoding(Charset).- Parameters:
encoding- The encoding to use or null to automatically select one- Returns:
- The builder
- Throws:
java.nio.charset.UnsupportedCharsetException- If the given encoding is not supported- See Also:
Terminal.encoding()
-
encoding
public TerminalBuilder encoding(java.nio.charset.Charset encoding)
Set theCharsetto use for reading/writing from the console. Ifnull(the default value), JLine will automatically select aCharset, usually the default system encoding. However, on some platforms (e.g. Windows) it may use a different one depending on theTerminalimplementation.Use
Terminal.encoding()to get theCharsetthat should be used to read/write from aTerminal.This method sets a single encoding for all streams (stdin, stdout, stderr). To set separate encodings for each stream, use
stdinEncoding(Charset),stdoutEncoding(Charset), andstderrEncoding(Charset).- Parameters:
encoding- The encoding to use or null to automatically select one- Returns:
- The builder
- See Also:
Terminal.encoding()
-
stdinEncoding
public TerminalBuilder stdinEncoding(java.lang.String encoding) throws java.nio.charset.UnsupportedCharsetException
Set the encoding to use for reading from standard input. Ifnull(the default value), JLine will use the value from the "stdin.encoding" system property if set, or fall back to the general encoding.- Parameters:
encoding- The encoding to use or null to automatically select one- Returns:
- The builder
- Throws:
java.nio.charset.UnsupportedCharsetException- If the given encoding is not supported- See Also:
Terminal.inputEncoding()
-
stdinEncoding
public TerminalBuilder stdinEncoding(java.nio.charset.Charset encoding)
Set theCharsetto use for reading from standard input. Ifnull(the default value), JLine will use the value from the "stdin.encoding" system property if set, or fall back to the general encoding.- Parameters:
encoding- The encoding to use or null to automatically select one- Returns:
- The builder
- See Also:
Terminal.inputEncoding()
-
stdoutEncoding
public TerminalBuilder stdoutEncoding(java.lang.String encoding) throws java.nio.charset.UnsupportedCharsetException
Set the encoding to use for writing to standard output. Ifnull(the default value), JLine will use the value from the "stdout.encoding" system property if set, or fall back to the general encoding.- Parameters:
encoding- The encoding to use or null to automatically select one- Returns:
- The builder
- Throws:
java.nio.charset.UnsupportedCharsetException- If the given encoding is not supported- See Also:
Terminal.outputEncoding()
-
stdoutEncoding
public TerminalBuilder stdoutEncoding(java.nio.charset.Charset encoding)
Set theCharsetto use for writing to standard output. Ifnull(the default value), JLine will use the value from the "stdout.encoding" system property if set, or fall back to the general encoding.- Parameters:
encoding- The encoding to use or null to automatically select one- Returns:
- The builder
- See Also:
Terminal.outputEncoding()
-
stderrEncoding
public TerminalBuilder stderrEncoding(java.lang.String encoding) throws java.nio.charset.UnsupportedCharsetException
Set the encoding to use for writing to standard error. Ifnull(the default value), JLine will use the value from the "stderr.encoding" system property if set, or fall back to the general encoding.- Parameters:
encoding- The encoding to use or null to automatically select one- Returns:
- The builder
- Throws:
java.nio.charset.UnsupportedCharsetException- If the given encoding is not supported- See Also:
Terminal.outputEncoding()
-
stderrEncoding
public TerminalBuilder stderrEncoding(java.nio.charset.Charset encoding)
Set theCharsetto use for writing to standard error. Ifnull(the default value), JLine will use the value from the "stderr.encoding" system property if set, or fall back to the general encoding.- Parameters:
encoding- The encoding to use or null to automatically select one- Returns:
- The builder
- See Also:
Terminal.outputEncoding()
-
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 thestreams(InputStream, OutputStream)method or whensystem(boolean)has been explicitly called withfalse.- 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 thestreams(InputStream, OutputStream)method or whensystem(boolean)has been explicitly called withfalse.- 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()
-
graphemeCluster
public TerminalBuilder graphemeCluster(boolean graphemeCluster)
Controls whether mode 2027 (grapheme cluster segmentation) should be enabled on the terminal after construction.When enabled, the terminal uses UAX #29 grapheme cluster boundaries for cursor positioning, which allows multi-codepoint characters like ZWJ emoji sequences (e.g., family emoji) to be treated as single display units.
By default (
null), mode 2027 is automatically enabled if the terminal supports it. Set tofalseto explicitly disable grapheme cluster mode even on terminals that support it.This can also be controlled via the system property
PROP_GRAPHEME_CLUSTER.- Parameters:
graphemeCluster-trueto enable,falseto disable, or leave unset for auto-detection- Returns:
- The builder
- See Also:
Terminal.supportsGraphemeClusterMode(),Terminal.setGraphemeClusterMode(boolean, boolean)
-
env
public TerminalBuilder env(java.util.function.UnaryOperator<java.lang.String> env)
Sets a custom environment variable provider for the terminal.By default, terminals read environment variables from
System.getenv(String), which returns the JVM process's own environment. For remote terminals (e.g., SSH), the client's environment variables are different from the server JVM's. This method allows injecting the correct environment so that capability detection (true-color, graphics protocol, grapheme cluster mode, etc.) uses the remote client's values.Example ? SSH server passing the client's environment:
Map<String, String> sshEnv = sshSession.getEnvironment(); Terminal terminal = TerminalBuilder.builder() .system(false) .streams(in, out) .env(sshEnv::get) .build();- Parameters:
env- a function that returns the value of an environment variable given its name, ornullif not defined- Returns:
- this builder
- See Also:
Terminal.getenv(String)
-
build
public Terminal build() throws java.io.IOException
Create and configure a Terminal instance according to this builder's settings. If a global terminal override has been set, that instance is returned instead of creating a new one. The method also applies grapheme-cluster mode to the created terminal based on the builder setting or the `org.jline.terminal.graphemeCluster` system property: it may force-enable, disable, or probe-and-enable grapheme-cluster handling on the terminal.- Returns:
- the configured Terminal instance; never
null - Throws:
java.io.IOException- if terminal creation or configuration fails
-
buildDeferred
public Terminal buildDeferred()
Asynchronous variant ofbuild()that returns aDeferredTerminalimmediately.The real terminal is constructed on a daemon thread. The returned proxy provides optimistic defaults for most methods so callers can produce output without blocking:
Terminal.writer()? returns a buffering writer; output is replayed through the real terminal's writer once construction completes (no messages are lost)Terminal.getType()? returns theTERMenv var;"dumb"whenNO_COLORis set orTERM=dumb; on Windows, checksWT_SESSION,ConEmuANSI,ANSICON,TERM_PROGRAMfor ANSI support;"ansi"on non-Windows whenTERMis unsetTerminal.getSize(),Terminal.getColumns(),Terminal.getRows()? return values from theCOLUMNS/LINESenvironment variables, defaulting to 120×40Terminal.getNumericCapability(org.jline.utils.InfoCmp.Capability)formax_colors? detected fromCOLORTERM(truecolor/24bit ? 16M) andTERM(*-256color ? 256), defaulting to 256Terminal.getPalette()? returns a default palette (no terminal query)- Other capabilities ? return
false/null(no terminfo lookup)
These are heuristic defaults, not the result of real terminal detection. They work well for typical output rendering (colored log messages, version display) but may not match the actual terminal's capabilities. Methods that require the real terminal (input, signal handling, raw mode, cursor position queries) block until construction completes.
If the process exits before the terminal is ready,
Closeable.close()drains buffered output toSystem.out.- Returns:
- a terminal proxy that completes in the background
- Since:
- 4.7.0
-
computeSystemOutput
public TerminalBuilder.SystemOutput computeSystemOutput()
-
computeType
public java.lang.String computeType()
-
computeEncoding
public java.nio.charset.Charset computeEncoding()
-
computeStdinEncoding
public java.nio.charset.Charset computeStdinEncoding()
-
computeStdoutEncoding
public java.nio.charset.Charset computeStdoutEncoding()
-
computeStderrEncoding
public java.nio.charset.Charset computeStderrEncoding()
-
getProviders
public java.util.List<TerminalProvider> getProviders(java.lang.String provider, java.lang.IllegalStateException exception, boolean all)
Get the available terminal providers.Providers are tried in the order specified by the
PROP_PROVIDERSsystem property. Whenallisfalse, only the first provider that loads successfully is returned (short-circuit), avoiding the cost of loading later providers (e.g. JNI native lib extraction). Whenallistrue, all available providers are loaded for fallback.- Parameters:
provider- if notnull, only this provider will be checkedexception- if a provider throws an exception, it will be added to this exception as a suppressed exceptionall- iftrue, load all providers; iffalse, stop after the first success- Returns:
- the list of available terminal providers in preference order
-
getProviders
public java.util.List<TerminalProvider> getProviders(java.lang.String provider, java.lang.IllegalStateException exception)
Get the available terminal providers, short-circuiting after the first success.
-
setTerminalOverride
@Deprecated public static void setTerminalOverride(Terminal terminal)
Deprecated.This method is deprecated to discourage its use. It will remain available but users should avoid it when possible and use proper dependency injection instead.Allows an application to override the result ofbuild(). 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 theLineReaderof theTerminal. For example, the sbt build tool uses aLineReaderto implement an interactive shell. One of its supported commands isconsolewhich invokes the scala REPL. The scala REPL also uses aLineReaderand it is necessary to override theTerminalused by the the REPL to share the sameTerminalinstance used by sbt.When this method is called with a non-null
Terminal, all subsequent calls tobuild()will return the providedTerminalregardless of how theTerminalBuilderwas constructed. The default behavior ofTerminalBuildercan be restored by calling setTerminalOverride with a nullTerminalUsage 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- theTerminalto globally override
-
-