Package jline.console

Class ConsoleReader

  • All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable
    public class ConsoleReader
extends java.lang.Object
implements java.io.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

    • Constructor Summary

      Constructors 
      Constructor Description
      ConsoleReader()  
      ConsoleReader​(java.io.InputStream in, java.io.OutputStream out)  
      ConsoleReader​(java.io.InputStream in, java.io.OutputStream out, Terminal term)  
      ConsoleReader​(java.lang.String appName, java.io.InputStream in, java.io.OutputStream out, Terminal term)  
      ConsoleReader​(java.lang.String appName, java.io.InputStream in, java.io.OutputStream out, Terminal term, java.lang.String encoding)  

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      java.lang.String accept()
      The equivalent of hitting <RET>.
      boolean addCompleter​(Completer completer)
      Add the specified Completer to the list of handlers for tab-completion.
      void addTriggeredAction​(char c, java.awt.event.ActionListener listener)
      Adding a triggered Action allows to give another curse of action if a character passed the pre-processing.
      protected void back​(int num)
      Move the visual cursor backward without modifying the buffer cursor.
      boolean backspace()
      Issue a backspace.
      void beep()
      Issue an audible keyboard bell.
      boolean clearScreen()
      Clear the screen by issuing the ANSI "clear screen" code.
      void close()
      Shuts the console reader down.
      protected boolean complete()
      Use the completers to modify the buffer with the appropriate completions.
      boolean delete()
      Issue a delete.
      void drawLine()
      Output put the prompt + the current buffer
      protected java.lang.String expandEvents​(java.lang.String str)
      Expand event designator such as !!, !#, !3, etc...
      protected void finalize()
      Shuts down the ConsoleReader if the JVM attempts to clean it up.
      void flush()
      Flush the console output stream.
      int getAutoprintThreshold()  
      boolean getBellEnabled()
      Get whether the console bell is enabled
      java.lang.String getCommentBegin()  
      java.util.Collection<Completer> getCompleters()
      Returns an unmodifiable list of all the completers.
      CompletionHandler getCompletionHandler()  
      CursorBuffer getCursorBuffer()  
      java.lang.Character getEchoCharacter()
      Returns the echo character.
      boolean getExpandEvents()  
      boolean getHandleLitteralNext()
      Get wether literal next are handled by JLine.
      boolean getHandleUserInterrupt()
      Get whether user interrupt handling is enabled
      History getHistory()  
      java.io.InputStream getInput()  
      static java.net.URL getInputRc()
      Retrieve the URL for the inputrc configuration file in effect.
      java.lang.String getKeyMap()
      Returns the name of the current key mapping.
      KeyMap getKeys()  
      java.lang.String getLastBinding()  
      java.io.Writer getOutput()  
      java.lang.String getPrompt()  
      Terminal getTerminal()  
      boolean isCopyPasteDetectionEnabled()  
      boolean isHistoryEnabled()
      Whether or not to add new commands to the history buffer.
      boolean isKeyMap​(java.lang.String name)  
      boolean isPaginationEnabled()
      Whether to use pagination when the number of rows of candidates exceeds the height of the terminal.
      boolean killLine()
      Kill the buffer ahead of the current cursor position.
      int moveCursor​(int num)
      Move the cursor where characters.
      protected boolean moveToEnd()  
      boolean paste()
      Paste the contents of the clipboard into the console buffer
      void print​(java.lang.CharSequence s)
      Output the specified string to the output stream (but not the buffer).
      void printColumns​(java.util.Collection<? extends java.lang.CharSequence> items)
      Output the specified Collection in proper columns.
      protected void printCompletionCandidates()  
      void printForwardSearchStatus​(java.lang.String searchTerm, java.lang.String match)  
      void println()
      Output a platform-dependant newline.
      void println​(java.lang.CharSequence s)  
      void printSearchStatus​(java.lang.String searchTerm, java.lang.String match)  
      void putString​(java.lang.CharSequence str)
      Write out the specified string to the buffer and the output stream.
      java.lang.Object readBinding​(KeyMap keys)
      Read from the input stream and decode an operation from the key map.
      int readCharacter()
      Read a character from the console.
      int readCharacter​(boolean checkForAltKeyCombo)
      Read a character from the console.
      int readCharacter​(boolean checkForAltKeyCombo, char... allowed)  
      int readCharacter​(char... allowed)  
      java.lang.String readLine()
      Read the next line and return the contents of the buffer.
      java.lang.String readLine​(java.lang.Character mask)
      Read the next line with the specified character mask.
      java.lang.String readLine​(java.lang.String prompt)  
      java.lang.String readLine​(java.lang.String prompt, java.lang.Character mask)
      Read a line from the in InputStream, and return the line (without any trailing newlines).
      java.lang.String readLine​(java.lang.String prompt, java.lang.Character mask, java.lang.String buffer)
      Read a line from the in InputStream, and return the line (without any trailing newlines).
      void redrawLine()
      Clear the line and redraw it.
      boolean removeCompleter​(Completer completer)
      Remove the specified Completer from the list of handlers for tab-completion.
      protected boolean resetLine()
      Erase the current line.
      void resetPromptLine​(java.lang.String prompt, java.lang.String buffer, int cursorDest)
      Erases the current line with the existing prompt, then redraws the line with the provided prompt and buffer
      void restoreLine​(java.lang.String originalPrompt, int cursorDest)  
      int searchBackwards​(java.lang.String searchTerm)
      Search backwards in history from the current position.
      int searchBackwards​(java.lang.String searchTerm, int startIndex)
      Search backward in history from a given position.
      int searchBackwards​(java.lang.String searchTerm, int startIndex, boolean startsWith)  
      int searchForwards​(java.lang.String searchTerm)
      Search forwards in history from the current position.
      int searchForwards​(java.lang.String searchTerm, int startIndex)
      Search forward in history from a given position.
      int searchForwards​(java.lang.String searchTerm, int startIndex, boolean startsWith)  
      void setAutoprintThreshold​(int threshold)  
      void setBellEnabled​(boolean enabled)
      Set whether the console bell is enabled.
      void setCommentBegin​(java.lang.String commentBegin)
      Sets the string that will be used to start a comment when the insert-comment key is struck.
      void setCompletionHandler​(CompletionHandler handler)  
      void setCopyPasteDetection​(boolean onoff)
      Enables or disables copy and paste detection.
      boolean setCursorPosition​(int position)
      Move the cursor position to the specified absolute index.
      void setEchoCharacter​(java.lang.Character c)
      Set the echo character.
      void setExpandEvents​(boolean expand)  
      void setHandleLitteralNext​(boolean handleLitteralNext)
      Set wether literal next are handled by JLine.
      void setHandleUserInterrupt​(boolean enabled)
      Set whether user interrupts (ctrl-C) are handled by having JLine throw UserInterruptException from readLine().
      void setHistory​(History history)  
      void setHistoryEnabled​(boolean enabled)
      Whether or not to add new commands to the history buffer.
      boolean setKeyMap​(java.lang.String name)
      Sets the current keymap by name.
      void setPaginationEnabled​(boolean enabled)
      Whether to use pagination when the number of rows of candidates exceeds the height of the terminal.
      void setParenBlinkTimeout​(int timeout)  
      void setPrompt​(java.lang.String prompt)  
      void shutdown()
      Deprecated.
      Use close() instead.
      boolean yank()  
      boolean yankPop()  

      • Methods inherited from class java.lang.Object

        clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • ConsoleReader

        public ConsoleReader()
              throws java.io.IOException
        Throws:
        java.io.IOException

      • ConsoleReader

        public ConsoleReader​(java.io.InputStream in,
                     java.io.OutputStream out)
              throws java.io.IOException
        Throws:
        java.io.IOException

      • ConsoleReader

        public ConsoleReader​(java.io.InputStream in,
                     java.io.OutputStream out,
                     Terminal term)
              throws java.io.IOException
        Throws:
        java.io.IOException

      • ConsoleReader

        public ConsoleReader​(@Nullable
                     java.lang.String appName,
                     java.io.InputStream in,
                     java.io.OutputStream out,
                     @Nullable
                     Terminal term)
              throws java.io.IOException
        Throws:
        java.io.IOException

      • ConsoleReader

        public ConsoleReader​(@Nullable
                     java.lang.String appName,
                     java.io.InputStream in,
                     java.io.OutputStream out,
                     @Nullable
                     Terminal term,
                     @Nullable
                     java.lang.String encoding)
              throws java.io.IOException
        Throws:
        java.io.IOException

    • Method Detail

      • getInputRc

        public static java.net.URL getInputRc()
                               throws java.io.IOException
        Retrieve the URL for the inputrc configuration file in effect. Intended use is for instantiating ConsoleKeys, to read inputrc variables.
        Throws:
        java.io.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 java.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable

      • shutdown

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

      • finalize

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

      • getInput

        public java.io.InputStream getInput()

      • getOutput

        public java.io.Writer getOutput()

      • getTerminal

        public Terminal getTerminal()

      • 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​(java.lang.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 java.lang.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​(java.lang.String prompt)

      • getPrompt

        public java.lang.String getPrompt()

      • setEchoCharacter

        public void setEchoCharacter​(java.lang.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 java.lang.Character getEchoCharacter()
        Returns the echo character.

      • resetLine

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

      • setCursorPosition

        public boolean setCursorPosition​(int position)
                          throws java.io.IOException
        Move the cursor position to the specified absolute index.
        Throws:
        java.io.IOException

      • drawLine

        public void drawLine()
              throws java.io.IOException
        Output put the prompt + the current buffer
        Throws:
        java.io.IOException

      • redrawLine

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

      • expandEvents

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

      • putString

        public void putString​(java.lang.CharSequence str)
               throws java.io.IOException
        Write out the specified string to the buffer and the output stream.
        Throws:
        java.io.IOException

      • back

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

      • flush

        public void flush()
           throws java.io.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:
        java.io.IOException

      • backspace

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

      • moveToEnd

        protected boolean moveToEnd()
                     throws java.io.IOException
        Throws:
        java.io.IOException

      • setParenBlinkTimeout

        public void setParenBlinkTimeout​(int timeout)

      • isKeyMap

        public boolean isKeyMap​(java.lang.String name)

      • accept

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

      • moveCursor

        public int moveCursor​(int num)
               throws java.io.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:
        java.io.IOException

      • readCharacter

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

      • readCharacter

        public int readCharacter​(boolean checkForAltKeyCombo)
                  throws java.io.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:
        java.io.IOException

      • readCharacter

        public int readCharacter​(char... allowed)
                  throws java.io.IOException
        Throws:
        java.io.IOException

      • readCharacter

        public int readCharacter​(boolean checkForAltKeyCombo,
                         char... allowed)
                  throws java.io.IOException
        Throws:
        java.io.IOException

      • readBinding

        public java.lang.Object readBinding​(KeyMap keys)
                             throws java.io.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:
        java.io.IOException

      • getLastBinding

        public java.lang.String getLastBinding()

      • readLine

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

      • readLine

        public java.lang.String readLine​(java.lang.Character mask)
                          throws java.io.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:
        java.io.IOException

      • readLine

        public java.lang.String readLine​(java.lang.String prompt)
                          throws java.io.IOException
        Throws:
        java.io.IOException

      • readLine

        public java.lang.String readLine​(java.lang.String prompt,
                                 java.lang.Character mask)
                          throws java.io.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:
        java.io.IOException

      • setKeyMap

        public boolean setKeyMap​(java.lang.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 java.lang.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 java.lang.String readLine​(java.lang.String prompt,
                                 java.lang.Character mask,
                                 java.lang.String buffer)
                          throws java.io.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:
        java.io.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 java.util.Collection<Completer> getCompleters()
        Returns an unmodifiable list of all the completers.

      • setCompletionHandler

        public void setCompletionHandler​(CompletionHandler handler)

      • complete

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

      • printCompletionCandidates

        protected void printCompletionCandidates()
                                  throws java.io.IOException
        Throws:
        java.io.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​(java.lang.CharSequence s)
           throws java.io.IOException
        Output the specified string to the output stream (but not the buffer).
        Throws:
        java.io.IOException

      • println

        public void println​(java.lang.CharSequence s)
             throws java.io.IOException
        Throws:
        java.io.IOException

      • println

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

      • delete

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

      • killLine

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

      • yank

        public boolean yank()
             throws java.io.IOException
        Throws:
        java.io.IOException

      • yankPop

        public boolean yankPop()
                throws java.io.IOException
        Throws:
        java.io.IOException

      • clearScreen

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

      • beep

        public void beep()
          throws java.io.IOException
        Issue an audible keyboard bell.
        Throws:
        java.io.IOException

      • paste

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

      • addTriggeredAction

        public void addTriggeredAction​(char c,
                               java.awt.event.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​(java.util.Collection<? extends java.lang.CharSequence> items)
                  throws java.io.IOException
        Output the specified Collection in proper columns.
        Throws:
        java.io.IOException

      • resetPromptLine

        public void resetPromptLine​(java.lang.String prompt,
                            java.lang.String buffer,
                            int cursorDest)
                     throws java.io.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:
        java.io.IOException

      • printSearchStatus

        public void printSearchStatus​(java.lang.String searchTerm,
                              java.lang.String match)
                       throws java.io.IOException
        Throws:
        java.io.IOException

      • printForwardSearchStatus

        public void printForwardSearchStatus​(java.lang.String searchTerm,
                                     java.lang.String match)
                              throws java.io.IOException
        Throws:
        java.io.IOException

      • restoreLine

        public void restoreLine​(java.lang.String originalPrompt,
                        int cursorDest)
                 throws java.io.IOException
        Throws:
        java.io.IOException

      • searchBackwards

        public int searchBackwards​(java.lang.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​(java.lang.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​(java.lang.String searchTerm,
                           int startIndex,
                           boolean startsWith)

      • searchForwards

        public int searchForwards​(java.lang.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​(java.lang.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​(java.lang.String searchTerm,
                          int startIndex,
                          boolean startsWith)