ConsoleReader
Date: 2015-12-09

jline

## Class ConsoleReader

- java.lang.Object
- - jline.ConsoleReader

- All Implemented Interfaces:
    ConsoleOperations

      public class ConsoleReader
      extends java.lang.Object
      implements ConsoleOperations

  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.initializeTerminal()` for convenience methods for issuing platform-specific setup commands.
  Author:
    Marc Prud'hommeaux

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `CR`
    `static java.util.SortedMap` | `KEYMAP_NAMES` Map that contains the operation name to keymay operation mapping.

    - ### Fields inherited from interface jline.ConsoleOperations

      `ABORT, ADD, BACKSPACE, CHANGE_CASE, CHANGE_META, CLEAR_LINE, CLEAR_SCREEN, COMPLETE, CTRL_A, CTRL_B, CTRL_C, CTRL_D, CTRL_E, CTRL_F, CTRL_G, CTRL_K, CTRL_L, CTRL_N, CTRL_OB, CTRL_P, CTRL_QM, DELETE, DELETE_META, DELETE_NEXT_CHAR, DELETE_PREV_CHAR, DELETE_PREV_WORD, END_OF_HISTORY, END_WORD, EXIT, INSERT, KEYBOARD_BELL, KILL_LINE, KILL_LINE_PREV, MOVE_TO_BEG, MOVE_TO_END, NEWLINE, NEXT_CHAR, NEXT_HISTORY, NEXT_SPACE_WORD, NEXT_WORD, PASTE, PASTE_NEXT, PASTE_PREV, PREV_CHAR, PREV_HISTORY, PREV_SPACE_WORD, PREV_WORD, REDISPLAY, REPEAT_NEXT_CHAR, REPEAT_PREV_CHAR, REPEAT_SEARCH_NEXT, REPEAT_SEARCH_PREV, REPLACE_CHAR, REPLACE_MODE, RESET_LINE, SEARCH_NEXT, SEARCH_PREV, START_OF_HISTORY, SUBSTITUTE_CHAR, SUBSTITUTE_LINE, TO_END_WORD, TO_NEXT_CHAR, TO_PREV_CHAR, UNDO, UNKNOWN`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ConsoleReader()` Create a new reader using `FileDescriptor.in` for input and `System.out` for output.
    `ConsoleReader(java.io.InputStream in, java.io.Writer out)` Create a new reader using the specified `InputStream` for input and the specific writer for output, using the default keybindings resource.
    `ConsoleReader(java.io.InputStream in, java.io.Writer out, java.io.InputStream bindings)`
    `ConsoleReader(java.io.InputStream in, java.io.Writer out, java.io.InputStream bindings, Terminal term)` Create a new reader.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `addCompletor(Completor completor)` Add the specified `Completor` 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 course of action if a character passed the preprocessing.
    `boolean` | `backspace()` Issue a backspace.
    `void` | `beep()` Issue an audible keyboard bell, if `getBellEnabled()` return true.
    `boolean` | `clearScreen()` Clear the screen by issuing the ANSI "clear screen" code.
    `static void` | `debug(java.lang.String str)` debug.
    `boolean` | `delete()` Issue a delete.
    `void` | `drawLine()` Output put the prompt + the current buffer
    `void` | `flushConsole()` Flush the console output stream.
    `int` | `getAutoprintThreshhold()`
    `boolean` | `getBellEnabled()`
    `CompletionHandler` | `getCompletionHandler()`
    `java.util.Collection` | `getCompletors()` Returns an unmodifiable list of all the completors.
    `CursorBuffer` | `getCursorBuffer()`
    `java.lang.String` | `getDefaultPrompt()` The default prompt that will be issued.
    `java.lang.Character` | `getEchoCharacter()` Returns the echo character.
    `History` | `getHistory()`
    `java.io.InputStream` | `getInput()` Returns the stream used for console input.
    `int` | `getTermheight()` Query the terminal to find the current width;
    `Terminal` | `getTerminal()`
    `int` | `getTermwidth()` Query the terminal to find the current width;
    `boolean` | `getUseHistory()` Whether or not to add new commands to the history buffer.
    `boolean` | `getUsePagination()` Whether to use pagination when the number of rows of candidates exceeds the height of the temrinal.
    `boolean` | `killLine()` Kill the buffer ahead of the current cursor position.
    `int` | `moveCursor(int num)` Move the cursor where characters.
    `boolean` | `paste()` Paste the contents of the clipboard into the console buffer
    `void` | `printColumns(java.util.Collection stuff)` Output the specified `Collection` in proper columns.
    `void` | `printNewline()` Output a platform-dependant newline.
    `void` | `printSearchStatus(java.lang.String searchTerm, java.lang.String match)`
    `void` | `printString(java.lang.String str)` Output the specified string to the output stream (but not the buffer).
    `void` | `putString(java.lang.String str)` Write out the specified string to the buffer and the output stream.
    `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).
    `int` | `readVirtualKey()` Read a character from the console.
    `void` | `redrawLine()` Clear the line and redraw it.
    `boolean` | `removeCompletor(Completor completor)` Remove the specified `Completor` from the list of handlers for tab-completion.
    `boolean` | `replace(int num, java.lang.String replacement)`
    `void` | `restoreLine()`
    `void` | `setAutoprintThreshhold(int autoprintThreshhold)`
    `void` | `setBellEnabled(boolean bellEnabled)`
    `void` | `setCompletionHandler(CompletionHandler completionHandler)`
    `boolean` | `setCursorPosition(int position)` Move the cursor position to the specified absolute index.
    `void` | `setDebug(java.io.PrintWriter debugger)` Set the stream for debugging.
    `void` | `setDefaultPrompt(java.lang.String prompt)` The default prompt that will be issued.
    `void` | `setEchoCharacter(java.lang.Character echoCharacter)` Set the echo character.
    `void` | `setHistory(History history)`
    `void` | `setInput(java.io.InputStream in)` Set the stream to be used for console input.
    `void` | `setUseHistory(boolean useHistory)` Whether or not to add new commands to the history buffer.
    `void` | `setUsePagination(boolean usePagination)` Whether to use pagination when the number of rows of candidates exceeds the height of the temrinal.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### CR

          public static final java.lang.String CR

    - #### KEYMAP_NAMES

          public static java.util.SortedMap KEYMAP_NAMES

      Map that contains the operation name to keymay operation mapping.

  - ### Constructor Detail

    - #### ConsoleReader

          public ConsoleReader()
                        throws java.io.IOException

      Create a new reader using `FileDescriptor.in` for input and `System.out` for output. `FileDescriptor.in` is used because it has a better chance of being unbuffered.
      Throws:
        `java.io.IOException`

    - #### ConsoleReader

          public ConsoleReader(java.io.InputStream in,
                       java.io.Writer out)
                        throws java.io.IOException

      Create a new reader using the specified `InputStream` for input and the specific writer for output, using the default keybindings resource.
      Throws:
        `java.io.IOException`

    - #### ConsoleReader

          public ConsoleReader(java.io.InputStream in,
                       java.io.Writer out,
                       java.io.InputStream bindings)
                        throws java.io.IOException

      Throws:
        `java.io.IOException`

    - #### ConsoleReader

          public ConsoleReader(java.io.InputStream in,
                       java.io.Writer out,
                       java.io.InputStream bindings,
                       Terminal term)
                        throws java.io.IOException

      Create a new reader.
      Parameters:
        `in` - the input
        `out` - the output
        `bindings` - the key bindings to use
        `term` - the terminal to use
      Throws:
        `java.io.IOException`

  - ### Method Detail

    - #### addTriggeredAction

          public void addTriggeredAction(char c,
                                java.awt.event.ActionListener listener)

      Adding a triggered Action allows to give another course of action if a character passed the preprocessing. Say you want to close the application if the user enter q. addTriggerAction('q', new ActionListener(){ System.exit(0); }); would do the trick.
      Parameters:
        `c` -
        `listener` -

    - #### getTerminal

          public Terminal getTerminal()

    - #### setDebug

          public void setDebug(java.io.PrintWriter debugger)

      Set the stream for debugging. Development use only.

    - #### setInput

          public void setInput(java.io.InputStream in)

      Set the stream to be used for console input.

    - #### getInput

          public java.io.InputStream getInput()

      Returns the stream used for console input.

    - #### 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`

    - #### setBellEnabled

          public void setBellEnabled(boolean bellEnabled)

      Parameters:
        `bellEnabled` - if true, enable audible keyboard bells if an alert is required.

    - #### getBellEnabled

          public boolean getBellEnabled()

      Returns:
        true is audible keyboard bell is enabled.

    - #### getTermwidth

          public int getTermwidth()

      Query the terminal to find the current width;
      Returns:
        the width of the current terminal.
      See Also:
        `Terminal.getTerminalWidth()`

    - #### getTermheight

          public int getTermheight()

      Query the terminal to find the current width;
      Returns:
        the height of the current terminal.
      See Also:
        `Terminal.getTerminalHeight()`

    - #### setAutoprintThreshhold

          public void setAutoprintThreshhold(int autoprintThreshhold)

      Parameters:
        `autoprintThreshhold` - the number of candidates to print without issuing a warning.

    - #### getAutoprintThreshhold

          public int getAutoprintThreshhold()

      Returns:
        the number of candidates to print without issing a warning.

    - #### readLine

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

      Throws:
        `java.io.IOException`

    - #### setDefaultPrompt

          public void setDefaultPrompt(java.lang.String prompt)

      The default prompt that will be issued.

    - #### getDefaultPrompt

          public java.lang.String getDefaultPrompt()

      The default prompt that will be issued.

    - #### 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`

    - #### 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`

    - #### 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`

    - #### clearScreen

          public boolean clearScreen()
                              throws java.io.IOException

      Clear the screen by issuing the ANSI "clear screen" code.
      Throws:
        `java.io.IOException`

    - #### getCursorBuffer

          public CursorBuffer getCursorBuffer()

    - #### printColumns

          public void printColumns(java.util.Collection stuff)
                            throws java.io.IOException

      Output the specified `Collection` in proper columns.
      Parameters:
        `stuff` - the stuff to print
      Throws:
        `java.io.IOException`

    - #### addCompletor

          public boolean addCompletor(Completor completor)

      Add the specified `Completor` to the list of handlers for tab-completion.
      Parameters:
        `completor` - the `Completor` to add
      Returns:
        true if it was successfully added

    - #### removeCompletor

          public boolean removeCompletor(Completor completor)

      Remove the specified `Completor` from the list of handlers for tab-completion.
      Parameters:
        `completor` - the `Completor` to remove
      Returns:
        true if it was successfully removed

    - #### getCompletors

          public java.util.Collection getCompletors()

      Returns an unmodifiable list of all the completors.

    - #### setCursorPosition

          public final boolean setCursorPosition(int position)
                                          throws java.io.IOException

      Move the cursor position to the specified absolute index.
      Throws:
        `java.io.IOException`

    - #### redrawLine

          public final void redrawLine()
                                throws java.io.IOException

      Clear the line and redraw it.
      Throws:
        `java.io.IOException`

    - #### drawLine

          public final void drawLine()
                              throws java.io.IOException

      Output put the prompt + the current buffer
      Throws:
        `java.io.IOException`

    - #### printNewline

          public final void printNewline()
                                  throws java.io.IOException

      Output a platform-dependant newline.
      Throws:
        `java.io.IOException`

    - #### putString

          public final void putString(java.lang.String str)
                               throws java.io.IOException

      Write out the specified string to the buffer and the output stream.
      Throws:
        `java.io.IOException`

    - #### printString

          public final void printString(java.lang.String str)
                                 throws java.io.IOException

      Output the specified string to the output stream (but not the buffer).
      Throws:
        `java.io.IOException`

    - #### beep

          public final void beep()
                          throws java.io.IOException

      Issue an audible keyboard bell, if `getBellEnabled()` return true.
      Throws:
        `java.io.IOException`

    - #### flushConsole

          public final void flushConsole()
                                  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 immedately.
      Throws:
        `java.io.IOException`

    - #### backspace

          public final boolean backspace()
                                  throws java.io.IOException

      Issue a backspace.
      Returns:
        true if successful
      Throws:
        `java.io.IOException`

    - #### moveCursor

          public final int moveCursor(int num)
                               throws java.io.IOException

      Move the cursor where characters.
      Parameters:
        `num` - if less than 0, move abs(num) to the left, otherwise move num to the right.
      Returns:
        the number of spaces we moved
      Throws:
        `java.io.IOException`

    - #### debug

          public static void debug(java.lang.String str)

      debug.
      Parameters:
        `str` - the message to issue.

    - #### readVirtualKey

          public final int readVirtualKey()
                                   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 final int readCharacter(char[] allowed)
                                  throws java.io.IOException

      Throws:
        `java.io.IOException`

    - #### replace

          public final boolean replace(int num,
                        java.lang.String replacement)

    - #### delete

          public final boolean delete()
                               throws java.io.IOException

      Issue a delete.
      Returns:
        true if successful
      Throws:
        `java.io.IOException`

    - #### setHistory

          public void setHistory(History history)

    - #### getHistory

          public History getHistory()

    - #### setCompletionHandler

          public void setCompletionHandler(CompletionHandler completionHandler)

    - #### getCompletionHandler

          public CompletionHandler getCompletionHandler()

    - #### setEchoCharacter

          public void setEchoCharacter(java.lang.Character echoCharacter)

      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

           new Character(0)

      will cause nothing to be echoed.
      Parameters:
        `echoCharacter` - the character to echo to the console in place of the typed character.

    - #### getEchoCharacter

          public java.lang.Character getEchoCharacter()

      Returns the echo character.

    - #### setUseHistory

          public void setUseHistory(boolean useHistory)

      Whether or not to add new commands to the history buffer.

    - #### getUseHistory

          public boolean getUseHistory()

      Whether or not to add new commands to the history buffer.

    - #### setUsePagination

          public void setUsePagination(boolean usePagination)

      Whether to use pagination when the number of rows of candidates exceeds the height of the temrinal.

    - #### getUsePagination

          public boolean getUsePagination()

      Whether to use pagination when the number of rows of candidates exceeds the height of the temrinal.

    - #### printSearchStatus

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

      Throws:
        `java.io.IOException`

    - #### restoreLine

          public void restoreLine()
                           throws java.io.IOException

      Throws:
        `java.io.IOException`