Package org.beryx.textio

Interface TextTerminal<T extends TextTerminal<T>>

    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method 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.
      default void executeWithPropertiesPrefix​(java.lang.String prefix, java.util.function.Consumer<TextTerminal<T>> action)
      A convenience method that calls executeWithPropertiesConfigurator(Consumer, Consumer) with a configurator that takes all terminal properties with the given prefix and applies them after stripping the prefix from their keys.
      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.lang.String message)
      Prints a message that possibly contains line separators.
      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 printf​(java.lang.String format, java.lang.Object... args)
      Prints a formatted string using the default locale and the specified format string and arguments.
      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.
      void println()
      Terminates the current line by writing the line separator string.
      default void println​(java.lang.String message)
      Prints a message that possibly contains line separators and subsequently prints a line separator.
      default void println​(java.util.List<java.lang.String> messages)
      Prints each message in the list, inserting the line separator string between messages.
      void rawPrint​(java.lang.String message)
      Prints the message in its raw form.
      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.
      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.

      • 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.

      • 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.

      • 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.

      • executeWithPropertiesPrefix

        default void executeWithPropertiesPrefix​(java.lang.String prefix,
                                         java.util.function.Consumer<TextTerminal<T>> action)
        A convenience method that calls executeWithPropertiesConfigurator(Consumer, Consumer) with a configurator that takes all terminal properties with the given prefix and applies them after stripping the prefix from their keys.
        For example, if textio.properties contains: 
           textio.prompt.color = green
   textio.error.prompt.color = red
        then the following statement: 
           textTerminal.executeWithPropertiesPrefix("error", t -> t.println("Connection failed."));
        will display the message in red.
        Parameters:
        prefix - the prefix of the terminal properties whose values will be temporarily used.
        action - the action to be performed on the TextTerminal.