Package jline.console

Class ConsoleReader

java.lang.Object
jline.console.ConsoleReader
All Implemented Interfaces:
Closeable, AutoCloseable

public class ConsoleReader extends Object implements Closeable
A reader for console applications. It supports custom tab-completion, saveable command history, and command line editing. On some platforms, platform-specific commands will need to be issued before the reader will function properly. See Terminal.init() for convenience methods for issuing platform-specific setup commands.
Author:
Marc Prud'hommeaux, Jason Dillon, Guillaume Nodet
  • Field Details

  • Constructor Details

  • Method Details

    • getInputRc

      public static URL getInputRc() throws IOException
      Retrieve the URL for the inputrc configuration file in effect. Intended use is for instantiating ConsoleKeys, to read inputrc variables.
      Throws:
      IOException
    • getKeys

      public KeyMap getKeys()
    • close

      public void close()
      Shuts the console reader down. This method should be called when you have completed using the reader as it shuts down and cleans up resources that would otherwise be "leaked".
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
    • shutdown

      @Deprecated public void shutdown()
      Deprecated.
      Use close() instead.
      Shuts the console reader down. The same as close().
    • finalize

      protected void finalize() throws Throwable
      Shuts down the ConsoleReader if the JVM attempts to clean it up.
      Overrides:
      finalize in class Object
      Throws:
      Throwable
    • getInput

      public InputStream getInput()
    • getOutput

      public Writer getOutput()
    • getTerminal

      public Terminal getTerminal()
    • getCursorBuffer

      public CursorBuffer getCursorBuffer()
    • setExpandEvents

      public void setExpandEvents(boolean expand)
    • getExpandEvents

      public boolean getExpandEvents()
    • setCopyPasteDetection

      public void setCopyPasteDetection(boolean onoff)
      Enables or disables copy and paste detection. The effect of enabling this this setting is that when a tab is received immediately followed by another character, the tab will not be treated as a completion, but as a tab literal.
      Parameters:
      onoff - true if detection is enabled
    • isCopyPasteDetectionEnabled

      public boolean isCopyPasteDetectionEnabled()
      Returns:
      true if copy and paste detection is enabled.
    • setBellEnabled

      public void setBellEnabled(boolean enabled)
      Set whether the console bell is enabled.
      Parameters:
      enabled - true if enabled; false otherwise
      Since:
      2.7
    • getBellEnabled

      public boolean getBellEnabled()
      Get whether the console bell is enabled
      Returns:
      true if enabled; false otherwise
      Since:
      2.7
    • setHandleUserInterrupt

      public void setHandleUserInterrupt(boolean enabled)
      Set whether user interrupts (ctrl-C) are handled by having JLine throw UserInterruptException from readLine(). Otherwise, the JVM will handle SIGINT as normal, which usually causes it to exit. The default is false.
      Since:
      2.10
    • getHandleUserInterrupt

      public boolean getHandleUserInterrupt()
      Get whether user interrupt handling is enabled
      Returns:
      true if enabled; false otherwise
      Since:
      2.10
    • setHandleLitteralNext

      public void setHandleLitteralNext(boolean handleLitteralNext)
      Set wether literal next are handled by JLine.
      Since:
      2.13
    • getHandleLitteralNext

      public boolean getHandleLitteralNext()
      Get wether literal next are handled by JLine.
      Since:
      2.13
    • setCommentBegin

      public void setCommentBegin(String commentBegin)
      Sets the string that will be used to start a comment when the insert-comment key is struck.
      Parameters:
      commentBegin - The begin comment string.
      Since:
      2.7
    • getCommentBegin

      public String getCommentBegin()
      Returns:
      the string that will be used to start a comment when the insert-comment key is struck.
      Since:
      2.7
    • setPrompt

      public void setPrompt(String prompt)
    • getPrompt

      public String getPrompt()
    • setEchoCharacter

      public void setEchoCharacter(Character c)
      Set the echo character. For example, to have "*" entered when a password is typed:
       myConsoleReader.setEchoCharacter(new Character('*'));
       
      Setting the character to null will restore normal character echoing.

      Setting the character to Character.valueOf(0) will cause nothing to be echoed.

      Parameters:
      c - the character to echo to the console in place of the typed character.
    • getEchoCharacter

      public Character getEchoCharacter()
      Returns the echo character.
    • resetLine

      protected final boolean resetLine() throws IOException
      Erase the current line.
      Returns:
      false if we failed (e.g., the buffer was empty)
      Throws:
      IOException
    • setCursorPosition

      public boolean setCursorPosition(int position) throws IOException
      Move the cursor position to the specified absolute index.
      Throws:
      IOException
    • drawLine

      public void drawLine() throws IOException
      Output put the prompt + the current buffer
      Throws:
      IOException
    • redrawLine

      public void redrawLine() throws IOException
      Clear the line and redraw it.
      Throws:
      IOException
    • expandEvents

      protected String expandEvents(String str) throws IOException
      Expand event designator such as !!, !#, !3, etc... See http://www.gnu.org/software/bash/manual/html_node/Event-Designators.html
      Throws:
      IOException
    • putString

      public void putString(CharSequence str) throws IOException
      Write out the specified string to the buffer and the output stream.
      Throws:
      IOException
    • back

      protected void back(int num) throws IOException
      Move the visual cursor backward without modifying the buffer cursor.
      Throws:
      IOException
    • flush

      public void flush() throws IOException
      Flush the console output stream. This is important for printout out single characters (like a backspace or keyboard) that we want the console to handle immediately.
      Throws:
      IOException
    • backspace

      public boolean backspace() throws IOException
      Issue a backspace.
      Returns:
      true if successful
      Throws:
      IOException
    • moveToEnd

      protected boolean moveToEnd() throws IOException
      Throws:
      IOException
    • setParenBlinkTimeout

      public void setParenBlinkTimeout(int timeout)
    • isKeyMap

      public boolean isKeyMap(String name)
    • accept

      public String accept() throws IOException
      The equivalent of hitting <RET>. The line is considered complete and is returned.
      Returns:
      The completed line of text.
      Throws:
      IOException
    • moveCursor

      public int moveCursor(int num) throws IOException
      Move the cursor where characters.
      Parameters:
      num - If less than 0, move abs(where) to the left, otherwise move where to the right.
      Returns:
      The number of spaces we moved
      Throws:
      IOException
    • readCharacter

      public int readCharacter() throws IOException
      Read a character from the console.
      Returns:
      the character, or -1 if an EOF is received.
      Throws:
      IOException
    • readCharacter

      public int readCharacter(boolean checkForAltKeyCombo) throws IOException
      Read a character from the console. If boolean parameter is "true", it will check whether the keystroke was an "alt-" key combination, and if so add 1000 to the value returned. Better way...?
      Returns:
      the character, or -1 if an EOF is received.
      Throws:
      IOException
    • readCharacter

      public int readCharacter(char... allowed) throws IOException
      Throws:
      IOException
    • readCharacter

      public int readCharacter(boolean checkForAltKeyCombo, char... allowed) throws IOException
      Throws:
      IOException
    • readBinding

      public Object readBinding(KeyMap keys) throws IOException
      Read from the input stream and decode an operation from the key map. The input stream will be read character by character until a matching binding can be found. Characters that can't possibly be matched to any binding will be discarded.
      Parameters:
      keys - the KeyMap to use for decoding the input stream
      Returns:
      the decoded binding or null if the end of stream has been reached
      Throws:
      IOException
    • getLastBinding

      public String getLastBinding()
    • readLine

      public String readLine() throws IOException
      Read the next line and return the contents of the buffer.
      Throws:
      IOException
    • readLine

      public String readLine(Character mask) throws IOException
      Read the next line with the specified character mask. If null, then characters will be echoed. If 0, then no characters will be echoed.
      Throws:
      IOException
    • readLine

      public String readLine(String prompt) throws IOException
      Throws:
      IOException
    • readLine

      public String readLine(String prompt, Character mask) throws IOException
      Read a line from the in InputStream, and return the line (without any trailing newlines).
      Parameters:
      prompt - The prompt to issue to the console, may be null.
      Returns:
      A line that is read from the terminal, or null if there was null input (e.g., CTRL-D was pressed).
      Throws:
      IOException
    • setKeyMap

      public boolean setKeyMap(String name)
      Sets the current keymap by name. Supported keymaps are "emacs", "vi-insert", "vi-move".
      Parameters:
      name - The name of the keymap to switch to
      Returns:
      true if the keymap was set, or false if the keymap is not recognized.
    • getKeyMap

      public String getKeyMap()
      Returns the name of the current key mapping.
      Returns:
      the name of the key mapping. This will be the canonical name of the current mode of the key map and may not reflect the name that was used with setKeyMap(String).
    • readLine

      public String readLine(String prompt, Character mask, String buffer) throws IOException
      Read a line from the in InputStream, and return the line (without any trailing newlines).
      Parameters:
      prompt - The prompt to issue to the console, may be null.
      Returns:
      A line that is read from the terminal, or null if there was null input (e.g., CTRL-D was pressed).
      Throws:
      IOException
    • addCompleter

      public boolean addCompleter(Completer completer)
      Add the specified Completer to the list of handlers for tab-completion.
      Parameters:
      completer - the Completer to add
      Returns:
      true if it was successfully added
    • removeCompleter

      public boolean removeCompleter(Completer completer)
      Remove the specified Completer from the list of handlers for tab-completion.
      Parameters:
      completer - The Completer to remove
      Returns:
      True if it was successfully removed
    • getCompleters

      public Collection<Completer> getCompleters()
      Returns an unmodifiable list of all the completers.
    • setCompletionHandler

      public void setCompletionHandler(CompletionHandler handler)
    • getCompletionHandler

      public CompletionHandler getCompletionHandler()
    • complete

      protected boolean complete() throws IOException
      Use the completers to modify the buffer with the appropriate completions.
      Returns:
      true if successful
      Throws:
      IOException
    • printCompletionCandidates

      protected void printCompletionCandidates() throws IOException
      Throws:
      IOException
    • setAutoprintThreshold

      public void setAutoprintThreshold(int threshold)
      Parameters:
      threshold - the number of candidates to print without issuing a warning.
    • getAutoprintThreshold

      public int getAutoprintThreshold()
      Returns:
      the number of candidates to print without issuing a warning.
    • setPaginationEnabled

      public void setPaginationEnabled(boolean enabled)
      Whether to use pagination when the number of rows of candidates exceeds the height of the terminal.
    • isPaginationEnabled

      public boolean isPaginationEnabled()
      Whether to use pagination when the number of rows of candidates exceeds the height of the terminal.
    • setHistory

      public void setHistory(History history)
    • getHistory

      public History getHistory()
    • setHistoryEnabled

      public void setHistoryEnabled(boolean enabled)
      Whether or not to add new commands to the history buffer.
    • isHistoryEnabled

      public boolean isHistoryEnabled()
      Whether or not to add new commands to the history buffer.
    • print

      public void print(CharSequence s) throws IOException
      Output the specified string to the output stream (but not the buffer).
      Throws:
      IOException
    • println

      public void println(CharSequence s) throws IOException
      Throws:
      IOException
    • println

      public void println() throws IOException
      Output a platform-dependant newline.
      Throws:
      IOException
    • delete

      public boolean delete() throws IOException
      Issue a delete.
      Returns:
      true if successful
      Throws:
      IOException
    • killLine

      public boolean killLine() throws IOException
      Kill the buffer ahead of the current cursor position.
      Returns:
      true if successful
      Throws:
      IOException
    • yank

      public boolean yank() throws IOException
      Throws:
      IOException
    • yankPop

      public boolean yankPop() throws IOException
      Throws:
      IOException
    • clearScreen

      public boolean clearScreen() throws IOException
      Clear the screen by issuing the ANSI "clear screen" code.
      Throws:
      IOException
    • beep

      public void beep() throws IOException
      Issue an audible keyboard bell.
      Throws:
      IOException
    • paste

      public boolean paste() throws IOException
      Paste the contents of the clipboard into the console buffer
      Returns:
      true if clipboard contents pasted
      Throws:
      IOException
    • addTriggeredAction

      public void addTriggeredAction(char c, ActionListener listener)
      Adding a triggered Action allows to give another curse of action if a character passed the pre-processing.

      Say you want to close the application if the user enter q. addTriggerAction('q', new ActionListener(){ System.exit(0); }); would do the trick.

    • printColumns

      public void printColumns(Collection<? extends CharSequence> items) throws IOException
      Output the specified Collection in proper columns.
      Throws:
      IOException
    • resetPromptLine

      public void resetPromptLine(String prompt, String buffer, int cursorDest) throws IOException
      Erases the current line with the existing prompt, then redraws the line with the provided prompt and buffer
      Parameters:
      prompt - the new prompt
      buffer - the buffer to be drawn
      cursorDest - where you want the cursor set when the line has been drawn. -1 for end of line.
      Throws:
      IOException
    • printSearchStatus

      public void printSearchStatus(String searchTerm, String match) throws IOException
      Throws:
      IOException
    • printForwardSearchStatus

      public void printForwardSearchStatus(String searchTerm, String match) throws IOException
      Throws:
      IOException
    • restoreLine

      public void restoreLine(String originalPrompt, int cursorDest) throws IOException
      Throws:
      IOException
    • searchBackwards

      public int searchBackwards(String searchTerm, int startIndex)
      Search backward in history from a given position.
      Parameters:
      searchTerm - substring to search for.
      startIndex - the index from which on to search
      Returns:
      index where this substring has been found, or -1 else.
    • searchBackwards

      public int searchBackwards(String searchTerm)
      Search backwards in history from the current position.
      Parameters:
      searchTerm - substring to search for.
      Returns:
      index where the substring has been found, or -1 else.
    • searchBackwards

      public int searchBackwards(String searchTerm, int startIndex, boolean startsWith)
    • searchForwards

      public int searchForwards(String searchTerm, int startIndex)
      Search forward in history from a given position.
      Parameters:
      searchTerm - substring to search for.
      startIndex - the index from which on to search
      Returns:
      index where this substring has been found, or -1 else.
    • searchForwards

      public int searchForwards(String searchTerm)
      Search forwards in history from the current position.
      Parameters:
      searchTerm - substring to search for.
      Returns:
      index where the substring has been found, or -1 else.
    • searchForwards

      public int searchForwards(String searchTerm, int startIndex, boolean startsWith)