net.minecraftforge.server.terminalconsole

Class TerminalConsoleAppender

java.lang.Object

AbstractAppender

net.minecraftforge.server.terminalconsole.TerminalConsoleAppender

public class TerminalConsoleAppender
extends AbstractAppender

An Appender that uses the JLine 3.x Terminal to print messages to the console.

The JLine Terminal extends the regular console output with support for Ansi escape codes on Windows. Additionally, it's LineReader interface can be used to implement enhanced console input, with an persistent input line, as well as command history and command completion.

The TerminalConsole appender replaces the default Console appender in your log4j configuration. By default, log4j will automatically close the standard output when the original Console appender is removed. Consequently, it is necessary to keep an unused Console appender.

Example usage:

  <TerminalConsole>
     <PatternLayout pattern="[%d{HH:mm:ss} %level]: %msg%n"/>
 </TerminalConsole>

 <Console name="SysOut" target="SYSTEM_OUT"/>

To use the enhanced console input it is necessary to set the LineReader using setReader(LineReader). The appender will then automatically redraw the current prompt. When creating the LineReader it's important to use the Terminal returned by getTerminal(). Additionally, the reader should be removed from the appender as soon as it's no longer accepting input (for example when the user interrupted input using CTRL + C.

By default, the JLine Terminal is enabled when the application is started with an attached terminal session. Usually, this is only the case if the application is started from the command line, not if it gets started by another application.

In some cases, it might be possible to support a subset of the features in these unsupported environments (e.g. only ANSI color codes). In these cases, the system properties may be used to override the default behaviour:

• JLINE_OVERRIDE_PROPERTY - To enable the extended JLine input. By default this will also enable the ANSI escape codes.
• ANSI_OVERRIDE_PROPERTY - To enable the output of ANSI escape codes. May be used to force the use of ANSI escape codes if JLine is disabled or to disable them if it is enabled.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.Boolean	ANSI_OVERRIDE
static java.lang.String	ANSI_OVERRIDE_PROPERTY System property that allows overriding the use of ANSI escape codes for console formatting even though running in an unsupported environment.
static java.lang.String	JLINE_OVERRIDE_PROPERTY System property that allows overriding the default detection of the console to force enable or force disable the use of JLine.
static java.lang.String	PLUGIN_NAME
static java.lang.String	PROPERTY_PREFIX The prefix used for all system properties in TerminalConsoleAppender.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	TerminalConsoleAppender(java.lang.String name, Filter filter, <any> layout, boolean ignoreExceptions) Constructs a new TerminalConsoleAppender.

Method Summary

Modifier and Type	Method and Description
void	append(LogEvent event)
static void	close() Closes the JLine Terminal (if available) and restores the original terminal settings.
static TerminalConsoleAppender	createAppender(java.lang.String name, Filter filter, <any> layout, boolean ignoreExceptions) Creates a new TerminalConsoleAppender.
static LineReader	getReader() Returns the currently configured LineReader that is used to read input from the console.
static Terminal	getTerminal() Returns the Terminal that is used to print messages to the console.
static boolean	isAnsiSupported() Returns whether ANSI escapes codes should be written to the console output.
static void	setReader(LineReader newReader) Sets the LineReader that is used to read input from the console.

Methods inherited from class java.lang.Object

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

Field Detail

PLUGIN_NAME

public static final java.lang.String PLUGIN_NAME

See Also:

Constant Field Values

PROPERTY_PREFIX

public static final java.lang.String PROPERTY_PREFIX

The prefix used for all system properties in TerminalConsoleAppender.

See Also:

Constant Field Values

JLINE_OVERRIDE_PROPERTY

public static final java.lang.String JLINE_OVERRIDE_PROPERTY

System property that allows overriding the default detection of the console to force enable or force disable the use of JLine. In some environments the automatic detection might not work properly.

If this system property is not set, or set to an invalid value (neither true nor false) then we will attempt to detect the best option automatically.

See Also:

Constant Field Values

ANSI_OVERRIDE_PROPERTY

public static final java.lang.String ANSI_OVERRIDE_PROPERTY

System property that allows overriding the use of ANSI escape codes for console formatting even though running in an unsupported environment. By default, ANSI color codes are only enabled if JLine is enabled. Some systems might be able to handle ANSI escape codes but are not capable of JLine's extended input mechanism.

If this system property is not set, or set to an invalid value (neither true nor false) then we will attempt to detect the best option automatically.

See Also:

Constant Field Values

ANSI_OVERRIDE

public static final java.lang.Boolean ANSI_OVERRIDE

Constructor Detail

TerminalConsoleAppender

protected TerminalConsoleAppender(java.lang.String name,
                                  Filter filter,
                                  <any> layout,
                                  boolean ignoreExceptions)

Constructs a new TerminalConsoleAppender.

Parameters:

name - The name of the appender

filter - The filter, can be null

layout - The layout to use

ignoreExceptions - If true exceptions encountered when appending events are logged, otherwise they are propagated to the caller

Method Detail

getTerminal

public static Terminal getTerminal()

Returns the Terminal that is used to print messages to the console. Returns null in unsupported environments, unless overridden using the JLINE_OVERRIDE_PROPERTY system property.

Returns:

The terminal, or null if not supported

See Also:

TerminalConsoleAppender

getReader

public static LineReader getReader()

Returns the currently configured LineReader that is used to read input from the console. May be null if no LineReader was configured by the environment.

Returns:

The current line reader, or null if none

setReader

public static void setReader(LineReader newReader)

Sets the LineReader that is used to read input from the console. Setting the LineReader will allow the appender to automatically redraw the input line when a new log message is added.

Note: The specified LineReader must be created with the terminal returned by getTerminal().

Parameters:

newReader - The new line reader

isAnsiSupported

public static boolean isAnsiSupported()

Returns whether ANSI escapes codes should be written to the console output.

The return value is true by default if the JLine terminal is enabled and false otherwise. It may be overridden using the ANSI_OVERRIDE_PROPERTY system property.

Returns:

true if ANSI escapes codes should be written to the console

append

public void append(LogEvent event)

close

public static void close()
                  throws java.io.IOException

Closes the JLine Terminal (if available) and restores the original terminal settings.

Throws:

java.io.IOException - If an I/O error occurs

createAppender

public static TerminalConsoleAppender createAppender(java.lang.String name,
                                                     Filter filter,
                                                     <any> layout,
                                                     boolean ignoreExceptions)

Creates a new TerminalConsoleAppender.

Parameters:

name - The name of the appender

filter - The filter, can be null

layout - The layout, can be null

ignoreExceptions - If true exceptions encountered when appending events are logged, otherwise they are propagated to the caller

Returns:

The new appender