jline.console
Class ConsoleReader

java.lang.Object
  extended by jline.console.ConsoleReader

public class ConsoleReader
extends Object

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 Summary
static char BACKSPACE
           
static String CR
           
static String DEFAULT_INPUT_RC
           
static String INPUT_RC
           
static String JLINE_COMPLETION_THRESHOLD
           
static String JLINE_ESC_TIMEOUT
           
static String JLINE_INPUTRC
           
static String JLINE_NOBELL
           
static char KEYBOARD_BELL
           
static char NULL_MASK
           
static char RESET_LINE
           
static int TAB_WIDTH
           
 
Constructor Summary
ConsoleReader()
           
ConsoleReader(InputStream in, OutputStream out)
           
ConsoleReader(InputStream in, OutputStream out, Terminal term)
           
ConsoleReader(String appName, InputStream in, OutputStream out, Terminal term)
           
ConsoleReader(String appName, InputStream in, OutputStream out, Terminal term, String encoding)
           
 
Method Summary
 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, 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 backwards 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.
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  String expandEvents(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
 String getCommentBegin()
           
 Collection<Completer> getCompleters()
          Returns an unmodifiable list of all the completers.
 CompletionHandler getCompletionHandler()
           
 CursorBuffer getCursorBuffer()
           
 Character getEchoCharacter()
          Returns the echo character.
 boolean getExpandEvents()
           
 boolean getHandleUserInterrupt()
          Get whether user interrupt handling is enabled
 History getHistory()
           
 InputStream getInput()
           
 String getKeyMap()
          Returns the name of the current key mapping.
 KeyMap getKeys()
           
 Writer getOutput()
           
 String getPrompt()
           
 Terminal getTerminal()
           
 boolean isCopyPasteDetectionEnabled()
           
 boolean isHistoryEnabled()
          Whether or not to add new commands to the history buffer.
 boolean isKeyMap(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(CharSequence s)
          Output the specified string to the output stream (but not the buffer).
 void printColumns(Collection<? extends CharSequence> items)
          Output the specified Collection in proper columns.
protected  void printCompletionCandidates()
           
 void printForwardSearchStatus(String searchTerm, String match)
           
 void println()
          Output a platform-dependant newline.
 void println(CharSequence s)
           
 void printSearchStatus(String searchTerm, String match)
           
 void putString(CharSequence str)
          Write out the specified string to the buffer and the output stream.
 int readCharacter()
          Read a character from the console.
 int readCharacter(char... allowed)
           
 String readLine()
          Read the next line and return the contents of the buffer.
 String readLine(Character mask)
          Read the next line with the specified character mask.
 String readLine(String prompt)
           
 String readLine(String prompt, Character mask)
          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.
 boolean replace(int num, String replacement)
           
protected  boolean resetLine()
          Erase the current line.
 void resetPromptLine(String prompt, String buffer, int cursorDest)
          Erases the current line with the existing prompt, then redraws the line with the provided prompt and buffer
 void restoreLine(String originalPrompt, int cursorDest)
           
 int searchBackwards(String searchTerm)
          Search backwards in history from the current position.
 int searchBackwards(String searchTerm, int startIndex)
          Search backward in history from a given position.
 int searchBackwards(String searchTerm, int startIndex, boolean startsWith)
           
 int searchForwards(String searchTerm)
          Search forwards in history from the current position.
 int searchForwards(String searchTerm, int startIndex)
          Search forward in history from a given position.
 int searchForwards(String searchTerm, int startIndex, boolean startsWith)
           
 void setAutoprintThreshold(int threshold)
           
 void setBellEnabled(boolean enabled)
          Set whether the console bell is enabled.
 void setCommentBegin(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(Character c)
          Set the echo character.
 void setExpandEvents(boolean expand)
           
 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(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(String prompt)
           
 void shutdown()
          Shuts the console reader down.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

JLINE_NOBELL

public static final String JLINE_NOBELL
See Also:
Constant Field Values

JLINE_ESC_TIMEOUT

public static final String JLINE_ESC_TIMEOUT
See Also:
Constant Field Values

JLINE_INPUTRC

public static final String JLINE_INPUTRC
See Also:
Constant Field Values

INPUT_RC

public static final String INPUT_RC
See Also:
Constant Field Values

DEFAULT_INPUT_RC

public static final String DEFAULT_INPUT_RC
See Also:
Constant Field Values

BACKSPACE

public static final char BACKSPACE
See Also:
Constant Field Values

RESET_LINE

public static final char RESET_LINE
See Also:
Constant Field Values

KEYBOARD_BELL

public static final char KEYBOARD_BELL
See Also:
Constant Field Values

NULL_MASK

public static final char NULL_MASK
See Also:
Constant Field Values

TAB_WIDTH

public static final int TAB_WIDTH
See Also:
Constant Field Values

JLINE_COMPLETION_THRESHOLD

public static final String JLINE_COMPLETION_THRESHOLD
See Also:
Constant Field Values

CR

public static final String CR
Constructor Detail

ConsoleReader

public ConsoleReader()
              throws IOException
Throws:
IOException

ConsoleReader

public ConsoleReader(InputStream in,
                     OutputStream out)
              throws IOException
Throws:
IOException

ConsoleReader

public ConsoleReader(InputStream in,
                     OutputStream out,
                     Terminal term)
              throws IOException
Throws:
IOException

ConsoleReader

public ConsoleReader(@Nullable
                     String appName,
                     InputStream in,
                     OutputStream out,
                     @Nullable
                     Terminal term)
              throws IOException
Throws:
IOException

ConsoleReader

public ConsoleReader(@Nullable
                     String appName,
                     InputStream in,
                     OutputStream out,
                     @Nullable
                     Terminal term,
                     @Nullable
                     String encoding)
              throws IOException
Throws:
IOException
Method Detail

getKeys

public KeyMap getKeys()

shutdown

public void shutdown()
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".


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

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

 new Character(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 final boolean setCursorPosition(int position)
                                throws IOException
Move the cursor position to the specified absolute index.

Throws:
IOException

drawLine

public final void drawLine()
                    throws IOException
Output put the prompt + the current buffer

Throws:
IOException

redrawLine

public final 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 final 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 backwards 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

replace

public final boolean replace(int num,
                             String replacement)

readCharacter

public final int readCharacter()
                        throws IOException
Read a character from the console.

Returns:
the character, or -1 if an EOF is received.
Throws:
IOException

readCharacter

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

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

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)
                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 final void print(CharSequence s)
                 throws IOException
Output the specified string to the output stream (but not the buffer).

Throws:
IOException

println

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

println

public final void println()
                   throws IOException
Output a platform-dependant newline.

Throws:
IOException

delete

public final 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

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)


Copyright © 2013. All Rights Reserved.