Package org.jline.reader

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()
        Returns the default key maps used by the LineReader.

        These key maps define the standard key bindings for different editing modes such as Emacs mode, Vi command mode, Vi insert mode, etc.

        Returns:
        a map of key map names to key maps

      • 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​(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)
        Sets a variable in the LineReader and returns the LineReader for method chaining.

        Variables control various aspects of the LineReader's behavior. See the various variable constants defined in this interface for available options.

        Parameters:
        name - the variable name
        value - the variable value
        Returns:
        this LineReader

      • option

        LineReader option​(LineReader.Option option,
                  boolean value)
        Sets an option in the LineReader and returns the LineReader for method chaining.

        Options control various aspects of the LineReader's behavior. See the LineReader.Option enum for available options.

        Parameters:
        option - the option to set
        value - the option value
        Returns:
        this LineReader

      • callWidget

        void callWidget​(java.lang.String name)
        Calls a widget by name.

        Widgets are functions that perform editing operations. This method allows invoking a widget programmatically rather than through a key binding.

        Parameters:
        name - the name of the widget to call

      • getVariables

        java.util.Map<java.lang.String,​java.lang.Object> getVariables()
        Returns a map of all variables set in the LineReader.

        Variables control various aspects of the LineReader's behavior. See the various variable constants defined in this interface for available options.

        Returns:
        a map of variable names to their values

      • getVariable

        java.lang.Object getVariable​(java.lang.String name)
        Returns the value of a variable.

        Variables control various aspects of the LineReader's behavior. See the various variable constants defined in this interface for available options.

        Parameters:
        name - the variable name
        Returns:
        the variable value, or null if the variable is not set

      • setVariable

        void setVariable​(java.lang.String name,
                 java.lang.Object value)
        Sets a variable in the LineReader.

        Variables control various aspects of the LineReader's behavior. See the various variable constants defined in this interface for available options.

        Parameters:
        name - the variable name
        value - the variable value

      • isSet

        boolean isSet​(LineReader.Option option)
        Checks if an option is set.

        Options control various aspects of the LineReader's behavior. See the LineReader.Option enum for available options.

        Parameters:
        option - the option to check
        Returns:
        true if the option is set, false otherwise

      • setOpt

        void setOpt​(LineReader.Option option)
        Sets an option to true.

        Options control various aspects of the LineReader's behavior. See the LineReader.Option enum for available options.

        Parameters:
        option - the option to set

      • unsetOpt

        void unsetOpt​(LineReader.Option option)
        Sets an option to false.

        Options control various aspects of the LineReader's behavior. See the LineReader.Option enum for available options.

        Parameters:
        option - the option to unset

      • getTerminal

        Terminal getTerminal()
        Returns the terminal associated with this LineReader.

        The terminal is used for input/output operations and provides information about the terminal capabilities and size.

        Returns:
        the terminal

      • getWidgets

        java.util.Map<java.lang.String,​Widget> getWidgets()
        Returns a map of all widgets registered with this LineReader.

        Widgets are functions that perform editing operations and can be bound to key sequences.

        Returns:
        a map of widget names to widgets

      • getBuiltinWidgets

        java.util.Map<java.lang.String,​Widget> getBuiltinWidgets()
        Returns a map of all built-in widgets provided by the LineReader.

        Built-in widgets implement standard editing operations like cursor movement, text deletion, history navigation, etc.

        Returns:
        a map of built-in widget names to widgets

      • getBuffer

        Buffer getBuffer()
        Returns the current line buffer.

        The buffer contains the text that the user is currently editing. It provides methods for manipulating the text and cursor position.

        Returns:
        the current line buffer

      • getAppName

        java.lang.String getAppName()
        Returns the application name associated with this LineReader.

        The application name is used for various purposes, such as naming history files and identifying the application in terminal titles.

        Returns:
        the application name

      • getHistory

        History getHistory()
        Returns the history associated with this LineReader.

        The history stores previously entered command lines and provides methods for navigating, searching, and managing history entries.

        Returns:
        the command history

      • getParser

        Parser getParser()
        Returns the parser associated with this LineReader.

        The parser is responsible for breaking command lines into tokens according to the syntax rules of the shell or application.

        Returns:
        the parser

      • getHighlighter

        Highlighter getHighlighter()
        Returns the highlighter associated with this LineReader.

        The highlighter is responsible for applying syntax highlighting to the command line as the user types.

        Returns:
        the highlighter

      • getExpander

        Expander getExpander()
        Returns the expander associated with this LineReader.

        The expander is responsible for expanding special syntax in the command line, such as history references (e.g., !!, !$) and variables (e.g., $HOME).

        Returns:
        the expander

      • getKeyMaps

        java.util.Map<java.lang.String,​KeyMap<Binding>> getKeyMaps()
        Returns all key maps registered with this LineReader.

        Key maps define the mappings from key sequences to actions for different editing modes (e.g., Emacs mode, Vi command mode, Vi insert mode).

        Returns:
        a map of key map names to key maps

      • getKeyMap

        java.lang.String getKeyMap()
        Returns the name of the currently active key map.

        The active key map determines how key presses are interpreted and which actions they trigger.

        Returns:
        the name of the active key map

      • setKeyMap

        boolean setKeyMap​(java.lang.String name)
        Sets the active key map by name.

        The active key map determines how key presses are interpreted and which actions they trigger.

        Parameters:
        name - the name of the key map to activate
        Returns:
        true if the key map was successfully set, false if the key map does not exist

      • getKeys

        KeyMap<Binding> getKeys()
        Returns the currently active key map.

        The active key map determines how key presses are interpreted and which actions they trigger.

        Returns:
        the active key map

      • getParsedLine

        ParsedLine getParsedLine()
        Returns the parsed representation of the current line.

        The parsed line contains the tokenized form of the current input line, broken down according to the syntax rules of the parser.

        Returns:
        the parsed line, or null if the line has not been parsed yet

      • getSearchTerm

        java.lang.String getSearchTerm()
        Returns the current search term when in history search mode.

        This is the string that the user is searching for in the command history.

        Returns:
        the current search term, or null if not in search mode

      • getRegionActive

        LineReader.RegionType getRegionActive()
        Returns the type of the currently active region selection.

        The region is a selected portion of text in the buffer, similar to a selection in a text editor.

        Returns:
        the type of the active region, or LineReader.RegionType.NONE if no region is active

      • getRegionMark

        int getRegionMark()
        Returns the mark position of the currently active region.

        The mark is one endpoint of the selected region, with the cursor being the other endpoint.

        Returns:
        the position of the mark, or -1 if no region is active

      • addCommandsInBuffer

        void addCommandsInBuffer​(java.util.Collection<java.lang.String> commands)
        Adds a collection of commands to the input buffer for execution.

        These commands will be executed one by one when the user accepts the current line. This is useful for implementing features like command scripts or macros.

        Parameters:
        commands - the commands to add to the buffer

      • editAndAddInBuffer

        default void editAndAddInBuffer​(java.io.File file)
                         throws java.lang.Exception
        Opens a file in an external editor and adds its contents to the input buffer.

        This method allows the user to edit a file in their preferred text editor and then have its contents added to the input buffer for execution.

        Parameters:
        file - the file to edit, or null to create a temporary file
        Throws:
        java.lang.Exception - if an error occurs while editing the file
        See Also:
        editAndAddInBuffer(Path)

      • editAndAddInBuffer

        void editAndAddInBuffer​(java.nio.file.Path file)
                 throws java.lang.Exception
        Opens a file in an external editor and adds its contents to the input buffer.

        This method allows the user to edit a file in their preferred text editor and then have its contents added to the input buffer for execution.

        Parameters:
        file - the file to edit, or null to create a temporary file
        Throws:
        java.lang.Exception - if an error occurs while editing the file

      • getLastBinding

        java.lang.String getLastBinding()
        Returns the last key binding that was processed.

        This is the string representation of the last key sequence that triggered an action.

        Returns:
        the last key binding, or null if no binding has been processed

      • getTailTip

        java.lang.String getTailTip()
        Returns the current tail tip text.

        The tail tip is a hint or suggestion displayed at the end of the current line, typically showing command syntax or parameter information.

        Returns:
        the current tail tip text, or null if no tail tip is set

      • setTailTip

        void setTailTip​(java.lang.String tailTip)
        Sets the tail tip text.

        The tail tip is a hint or suggestion displayed at the end of the current line, typically showing command syntax or parameter information.

        Parameters:
        tailTip - the tail tip text to display, or null to clear the tail tip

      • setAutosuggestion

        void setAutosuggestion​(LineReader.SuggestionType type)
        Sets the type of auto-suggestion to use.

        Auto-suggestions provide inline completion suggestions as the user types, based on history, completers, or other sources.

        Parameters:
        type - the type of auto-suggestion to use

      • getAutosuggestion

        LineReader.SuggestionType getAutosuggestion()
        Returns the current auto-suggestion type.

        Auto-suggestions provide inline completion suggestions as the user types, based on history, completers, or other sources.

        Returns:
        the current auto-suggestion type

      • zeroOut

        void zeroOut()
        Clears any internal buffers and sensitive data.

        This method is used to ensure that sensitive information, such as passwords or other confidential data, is removed from memory when it's no longer needed. It should be called when the LineReader is no longer in use or before reading sensitive information.