Interface LineReader

  • All Known Implementing Classes:
    LineReaderImpl

    public interface LineReader
    Read lines from the console, with input editing.

    Thread safety

    The LineReader implementations are not thread safe, thus you should not attempt to use a single reader in several threads. Any attempt to call one of the readLine call while one is already executing in a different thread will immediately result in an IllegalStateException being thrown. Other calls may lead to unknown behaviors. There is one exception though: users are allowed to call printAbove(String) or printAbove(AttributedString) at any time to allow text to be printed above the current prompt.

    Prompt strings

    It is traditional for an interactive console-based program to print a short prompt string to signal that the user is expected to type a command. JLine supports 3 kinds of prompt string:
    • The normal prompt at the start (left) of the initial line of a command.
    • An optional right prompt at the right border of the initial line.
    • A start (left) prompt for continuation lines. I.e. the lines after the first line of a multi-line command.

    All of these are specified with prompt templates, which are similar to printf format strings, using the character '%' to indicate special functionality.

    The pattern may include ANSI escapes. It may include these template markers:
    %N
    A line number. This is the sum of getLineNumber() and a counter starting with 1 for the first continuation line.
    %M
    A short word explaining what is "missing". This is supplied from the EOFError.getMissing() method, if provided. Defaults to an empty string.
    %nPc
    Insert padding at this position, repeating the following character c as needed to bring the total prompt column width as specified by the digits n.
    %Pc
    As before, but use width from the initial prompt.
    %%
    A literal '%'.
    %{
    %}
    Text between a %{...%} pair is printed as part of a prompt, but not interpreted by JLine (except that '%'-escapes are processed). The text is assumed to take zero columns (not move the cursor). If it changes the style, you're responsible for changing it back. Standard ANSI escape sequences do not need to be within a %{...%} pair (though can be) since JLine knows how to deal with them. However, these delimiters are needed for unusual non-standard escape sequences.
    • Method Detail

      • defaultKeyMaps

        java.util.Map<java.lang.String,​KeyMap<Binding>> defaultKeyMaps()
      • readLine

        java.lang.String readLine()
                           throws UserInterruptException,
                                  EndOfFileException
        Read the next line and return the contents of the buffer. Equivalent to readLine(null, null, null).
        Returns:
        the line read
        Throws:
        UserInterruptException - if readLine was interrupted (using Ctrl-C for example)
        EndOfFileException - if an EOF has been found (using Ctrl-D for example)
        java.io.IOError - in case of other i/o errors
      • readLine

        java.lang.String readLine​(java.lang.Character mask)
                           throws UserInterruptException,
                                  EndOfFileException
        Read the next line with the specified character mask. If null, then characters will be echoed. If 0, then no characters will be echoed. Equivalent to readLine(null, mask, null)
        Parameters:
        mask - The mask character, null or 0.
        Returns:
        A line that is read from the terminal, can never be null.
        Throws:
        UserInterruptException - if readLine was interrupted (using Ctrl-C for example)
        EndOfFileException - if an EOF has been found (using Ctrl-D for example)
        java.io.IOError - in case of other i/o errors
      • readLine

        java.lang.String readLine​(java.lang.String prompt)
                           throws UserInterruptException,
                                  EndOfFileException
        Read the next line with the specified prompt. If null, then the default prompt will be used. Equivalent to readLine(prompt, null, null)
        Parameters:
        prompt - The prompt to issue to the terminal, may be null.
        Returns:
        A line that is read from the terminal, can never be null.
        Throws:
        UserInterruptException - if readLine was interrupted (using Ctrl-C for example)
        EndOfFileException - if an EOF has been found (using Ctrl-D for example)
        java.io.IOError - in case of other i/o errors
      • readLine

        java.lang.String readLine​(java.lang.String prompt,
                                  java.lang.Character mask)
                           throws UserInterruptException,
                                  EndOfFileException
        Read a line from the in InputStream, and return the line (without any trailing newlines). Equivalent to readLine(prompt, mask, null)
        Parameters:
        prompt - The prompt to issue to the terminal, may be null.
        mask - The mask character, null or 0.
        Returns:
        A line that is read from the terminal, can never be null.
        Throws:
        UserInterruptException - if readLine was interrupted (using Ctrl-C for example)
        EndOfFileException - if an EOF has been found (using Ctrl-D for example)
        java.io.IOError - in case of other i/o errors
      • readLine

        java.lang.String readLine​(java.lang.String prompt,
                                  java.lang.Character mask,
                                  java.lang.String buffer)
                           throws UserInterruptException,
                                  EndOfFileException
        Read a line from the in InputStream, and return the line (without any trailing newlines). Equivalent to readLine(prompt, null, mask, buffer)
        Parameters:
        prompt - The prompt to issue to the terminal, may be null. This is a template, with optional '%' escapes, as described in the class header.
        mask - The character mask, may be null.
        buffer - The default value presented to the user to edit, may be null.
        Returns:
        A line that is read from the terminal, can never be null.
        Throws:
        UserInterruptException - if readLine was interrupted (using Ctrl-C for example)
        EndOfFileException - if an EOF has been found (using Ctrl-D for example)
        java.io.IOError - in case of other i/o errors
      • readLine

        java.lang.String readLine​(java.lang.String prompt,
                                  java.lang.String rightPrompt,
                                  java.lang.Character mask,
                                  java.lang.String buffer)
                           throws UserInterruptException,
                                  EndOfFileException
        Read a line from the in InputStream, and return the line (without any trailing newlines).
        Parameters:
        prompt - The prompt to issue to the terminal, may be null. This is a template, with optional '%' escapes, as described in the class header.
        rightPrompt - The right prompt This is a template, with optional '%' escapes, as described in the class header.
        mask - The character mask, may be null.
        buffer - The default value presented to the user to edit, may be null.
        Returns:
        A line that is read from the terminal, can never be null.
        Throws:
        UserInterruptException - if readLine was interrupted (using Ctrl-C for example)
        EndOfFileException - if an EOF has been found (using Ctrl-D for example)
        java.io.IOError - in case of other i/o errors
      • readLine

        java.lang.String readLine​(java.lang.String prompt,
                                  java.lang.String rightPrompt,
                                  MaskingCallback maskingCallback,
                                  java.lang.String buffer)
                           throws UserInterruptException,
                                  EndOfFileException
        Read a line from the in InputStream, and return the line (without any trailing newlines).
        Parameters:
        prompt - The prompt to issue to the terminal, may be null. This is a template, with optional '%' escapes, as described in the class header.
        rightPrompt - The right prompt This is a template, with optional '%' escapes, as described in the class header.
        maskingCallback - The MaskingCallback to use when displaying lines and adding them to the line History
        buffer - The default value presented to the user to edit, may be null.
        Returns:
        A line that is read from the terminal, can never be null.
        Throws:
        UserInterruptException - if readLine was interrupted (using Ctrl-C for example)
        EndOfFileException - if an EOF has been found (using Ctrl-D for example)
        java.io.IOError - in case of other i/o errors
      • printAbove

        void printAbove​(java.lang.String str)
        Prints a line above the prompt and redraw everything. If the LineReader is not actually reading a line, the string will simply be printed to the terminal.
        Parameters:
        str - the string to print
        See Also:
        printAbove(AttributedString)
      • printAbove

        void printAbove​(org.jline.utils.AttributedString str)
        Prints a string before the prompt and redraw everything. If the LineReader is not actually reading a line, the string will simply be printed to the terminal.
        Parameters:
        str - the string to print
        See Also:
        printAbove(String)
      • isReading

        boolean isReading()
        Check if a thread is currently in a readLine() call.
        Returns:
        true if there is an ongoing readLine() call.
      • variable

        LineReader variable​(java.lang.String name,
                            java.lang.Object value)
      • callWidget

        void callWidget​(java.lang.String name)
      • getVariables

        java.util.Map<java.lang.String,​java.lang.Object> getVariables()
      • getVariable

        java.lang.Object getVariable​(java.lang.String name)
      • setVariable

        void setVariable​(java.lang.String name,
                         java.lang.Object value)
      • getTerminal

        org.jline.terminal.Terminal getTerminal()
      • getWidgets

        java.util.Map<java.lang.String,​Widget> getWidgets()
      • getBuiltinWidgets

        java.util.Map<java.lang.String,​Widget> getBuiltinWidgets()
      • getBuffer

        Buffer getBuffer()
      • getAppName

        java.lang.String getAppName()
      • runMacro

        void runMacro​(java.lang.String macro)
        Push back a key sequence that will be later consumed by the line reader. This method can be used after reading the cursor position using Terminal.getCursorPosition(IntConsumer).
        Parameters:
        macro - the key sequence to push back
        See Also:
        Terminal.getCursorPosition(IntConsumer), readMouseEvent()
      • readMouseEvent

        org.jline.terminal.MouseEvent readMouseEvent()
        Read a mouse event when the InfoCmp.Capability.key_mouse sequence has just been read on the input stream. Compared to Terminal.readMouseEvent(), this method takes into account keys that have been pushed back using runMacro(String).
        Returns:
        the mouse event
        See Also:
        runMacro(String), Terminal.getCursorPosition(IntConsumer)
      • getParser

        Parser getParser()
      • getKeyMaps

        java.util.Map<java.lang.String,​KeyMap<Binding>> getKeyMaps()
      • getKeyMap

        java.lang.String getKeyMap()
      • setKeyMap

        boolean setKeyMap​(java.lang.String name)
      • getSearchTerm

        java.lang.String getSearchTerm()
      • getRegionMark

        int getRegionMark()
      • addCommandsInBuffer

        void addCommandsInBuffer​(java.util.Collection<java.lang.String> commands)
      • editAndAddInBuffer

        default void editAndAddInBuffer​(java.io.File file)
                                 throws java.lang.Exception
        Throws:
        java.lang.Exception
      • editAndAddInBuffer

        void editAndAddInBuffer​(java.nio.file.Path file)
                         throws java.lang.Exception
        Throws:
        java.lang.Exception
      • getLastBinding

        java.lang.String getLastBinding()
      • getTailTip

        java.lang.String getTailTip()
      • setTailTip

        void setTailTip​(java.lang.String tailTip)
      • zeroOut

        void zeroOut()
        Clear any internal buffers.