org.beryx.textio

Interface TextTerminal<T extends TextTerminal<T>>

All Known Implementing Classes:

AbstractTextTerminal, ConsoleTextTerminal, JLineTextTerminal, MockTextTerminal, SwingTextTerminal, SystemTextTerminal, WebTextTerminal

public interface TextTerminal<T extends TextTerminal<T>>

Interface for text-based terminals capable of reading (optionally masking the input) and writing text.

Method Summary

Modifier and Type	Method and Description
default void	abort() This method is typically called when a text-based input/output session has been aborted by the user or when a severe error occurred.
default <R> R	applyWithPropertiesConfigurator(java.util.function.Consumer<TerminalProperties<?>> propertiesConfigurator, java.util.function.Function<TextTerminal<T>,R> action) Executes an action that returns a result, while temporarily modifying the terminal properties.
default void	dispose() Convenience method for disposing the terminal without providing information about the outcome of the input/output session.
default void	dispose(java.lang.String resultData) This method is typically called at the end of a text-based input/output session in order to allow the terminal to release its screen resources.
default void	executeWithPropertiesConfigurator(java.util.function.Consumer<TerminalProperties<?>> propertiesConfigurator, java.util.function.Consumer<TextTerminal<T>> action) Executes an action while temporarily modifying the terminal properties.
TerminalProperties<T>	getProperties()
default void	init() This method is typically called after the terminal has been created.
default boolean	moveToLineStart() Moves the cursor to the start of the current line of text in order to allow overwriting the current line.
default void	print(java.util.List<java.lang.String> messages) Prints each message in the list, inserting the line separator string between messages.
default void	print(java.lang.String message) Prints a message that possibly contains line separators.
default void	printf(java.util.Locale l, java.lang.String format, java.lang.Object... args) Prints a formatted string using the specified locale, format string and arguments.
default void	printf(java.lang.String format, java.lang.Object... args) Prints a formatted string using the default locale and the specified format string and arguments.
void	println() Terminates the current line by writing the line separator string.
default void	println(java.util.List<java.lang.String> messages) Prints each message in the list, inserting the line separator string between messages.
default void	println(java.lang.String message) Prints a message that possibly contains line separators and subsequently prints a line separator.
default void	rawPrint(java.util.List<java.lang.String> messages) Prints each message in the list in its raw form, inserting the line separator string between messages.
void	rawPrint(java.lang.String message) Prints the message in its raw form.
java.lang.String	read(boolean masking) Reads a line of text
default boolean	registerHandler(java.lang.String keyStroke, java.util.function.Function<T,ReadHandlerData> handler) Associates a key combination to a handler.
default boolean	registerUserInterruptHandler(java.util.function.Consumer<T> handler, boolean abortRead) Registers a handler that will be called in response to a user interrupt.
default boolean	resetLine() Clears the current line of text.
default boolean	resetToBookmark(java.lang.String bookmark) Clears the text after the given bookmark.
default boolean	setBookmark(java.lang.String bookmark) Sets a bookmark with the given name at the current position.

Method Detail

read

java.lang.String read(boolean masking)

Reads a line of text

Parameters:

masking - true, if the input should be masked (for example to enter a password)

Returns:

the entered text

rawPrint

void rawPrint(java.lang.String message)

Prints the message in its raw form. This method expects a single line of text. The behavior is undefined if the string contains line separators.

println

void println()

Terminates the current line by writing the line separator string.

getProperties

TerminalProperties<T> getProperties()

Returns:

the TerminalProperties of this text terminal.

registerUserInterruptHandler

default boolean registerUserInterruptHandler(java.util.function.Consumer<T> handler,
                                             boolean abortRead)

Registers a handler that will be called in response to a user interrupt. The event that triggers a user interrupt is usually Ctrl+C, but in general it is terminal specific. For example, a Swing based terminal may send a user interrupt when the X close button of its window is hit. Since not all terminals support this feature, the default implementation just returns false.

Parameters:

handler - the action to be performed in response to a user interrupt.

abortRead - true, if the current read operation should be aborted on user interrupt.

Returns:

true, if the terminal supports this feature and the handler has been registered; false, otherwise.

registerHandler

default boolean registerHandler(java.lang.String keyStroke,
                                java.util.function.Function<T,ReadHandlerData> handler)

Associates a key combination to a handler. Since not all terminals support this feature, the default implementation just returns false.

Parameters:

keyStroke - the key combination associated with the handler. It should have the same format as the argument of KeyStroke.getKeyStroke(String).

handler - the action to be performed when the keyStroke is detected during a read operation.

Returns:

true, if the terminal supports this feature and the handler has been associated with the given key combination; false, otherwise.

init

default void init()

This method is typically called after the terminal has been created. The default implementation does nothing.

dispose

default void dispose(java.lang.String resultData)

This method is typically called at the end of a text-based input/output session in order to allow the terminal to release its screen resources. The terminal should be able to rebuild the released resources when a print or read method is subsequently called. The default implementation does nothing.

Parameters:

resultData - stringified information about the outcome of the input/output session; may be null,

dispose

default void dispose()

Convenience method for disposing the terminal without providing information about the outcome of the input/output session. The default implementation calls dispose(String) with a null argument.

abort

default void abort()

This method is typically called when a text-based input/output session has been aborted by the user or when a severe error occurred. The default implementation does nothing.

resetLine

default boolean resetLine()

Clears the current line of text. Since not all terminals support this feature, the default implementation calls println() and returns false.

Returns:

true, if the terminal supports this feature and the current line has been successfully cleared.

moveToLineStart

default boolean moveToLineStart()

Moves the cursor to the start of the current line of text in order to allow overwriting the current line. Since not all terminals support this feature, the default implementation calls println() and returns false.

Returns:

true, if the terminal supports this feature and the cursor has been moved to the start of the current line.

setBookmark

default boolean setBookmark(java.lang.String bookmark)

Sets a bookmark with the given name at the current position. The bookmark name can be subsequently used in a call to resetToBookmark(String) in order to clear the text after this bookmark. If a bookmark with this name already exists, it will be overwritten. Since not all terminals support this feature, the default implementation does nothing and returns false.

Returns:

true, if the terminal supports bookmarking and the bookmark has been successfully set.

resetToBookmark

default boolean resetToBookmark(java.lang.String bookmark)

Clears the text after the given bookmark. The bookmark name can be subsequently used in a call to resetToBookmark(String) in order to clear the text after this bookmark. Since not all terminals support this feature, the default implementation calls println() and returns false.

Returns:

true, if the terminal supports bookmarking, the given bookmark exists and the text after it has been successfully cleared.

rawPrint

default void rawPrint(java.util.List<java.lang.String> messages)

Prints each message in the list in its raw form, inserting the line separator string between messages. No separator string is printed after the last message. The behavior is undefined if one or more strings in the list contain line separators.

print

default void print(java.lang.String message)

Prints a message that possibly contains line separators.

println

default void println(java.lang.String message)

Prints a message that possibly contains line separators and subsequently prints a line separator.

print

default void print(java.util.List<java.lang.String> messages)

Prints each message in the list, inserting the line separator string between messages. No separator string is printed after the last message. The messages in the list may contain line separators.

println

default void println(java.util.List<java.lang.String> messages)

Prints each message in the list, inserting the line separator string between messages. A separator string is also printed after the last message. The messages in the list may contain line separators.

printf

default void printf(java.lang.String format,
                    java.lang.Object... args)

Prints a formatted string using the default locale and the specified format string and arguments.

Parameters:

format - A format string as described in Formatter.

args - Arguments referenced by the format specifiers in the format string.

printf

default void printf(java.util.Locale l,
                    java.lang.String format,
                    java.lang.Object... args)

Prints a formatted string using the specified locale, format string and arguments.

Parameters:

l - The locale to apply during formatting. If l is null then no localization is applied.

format - A format string as described in Formatter.

args - Arguments referenced by the format specifiers in the format string.

executeWithPropertiesConfigurator

default void executeWithPropertiesConfigurator(java.util.function.Consumer<TerminalProperties<?>> propertiesConfigurator,
                                               java.util.function.Consumer<TextTerminal<T>> action)

Executes an action while temporarily modifying the terminal properties.

Parameters:

propertiesConfigurator - the task that is in charge of modifying the TerminalProperties. The configurator will be applied to the terminal properties before starting the action and the properties will be reverted to their previous values at the end of the action.

action - the action to be executed, usually consisting of a series of TextTerminal-related operations.

applyWithPropertiesConfigurator

default <R> R applyWithPropertiesConfigurator(java.util.function.Consumer<TerminalProperties<?>> propertiesConfigurator,
                                              java.util.function.Function<TextTerminal<T>,R> action)

Executes an action that returns a result, while temporarily modifying the terminal properties.

Parameters:

propertiesConfigurator - the task that is in charge of modifying the TerminalProperties. The configurator will be applied to the terminal properties before starting the action and the properties will be reverted to their previous values at the end of the action.

action - the action to be performed on the TextTerminal in order to obtain a result. Usually, the result is the return value of a read(boolean) operation.