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

  • Method Details

    • defaultKeyMaps

      Map<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

      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)
      IOError - in case of other i/o errors
    • readLine

      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)
      IOError - in case of other i/o errors
    • readLine

      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)
      IOError - in case of other i/o errors
    • readLine

      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)
      IOError - in case of other i/o errors
    • readLine

      String readLine(String prompt, Character mask, 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)
      IOError - in case of other i/o errors
    • readLine

      String readLine(String prompt, String rightPrompt, Character mask, 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)
      IOError - in case of other i/o errors
    • readLine

      String readLine(String prompt, String rightPrompt, MaskingCallback maskingCallback, 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)
      IOError - in case of other i/o errors
    • printAbove

      void printAbove(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

      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:
    • 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(String name, 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(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

      Map<String,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

      Object getVariable(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(String name, 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

      org.jline.terminal.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

      Map<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

      Map<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

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

      void runMacro(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:
    • 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:
    • 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

      Map<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

      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(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

      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(Collection<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(File file) throws 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:
      Exception - if an error occurs while editing the file
      See Also:
    • editAndAddInBuffer

      void editAndAddInBuffer(Path file) throws 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:
      Exception - if an error occurs while editing the file
    • getLastBinding

      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

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