Package jline.console
Class ConsoleReader
- java.lang.Object
-
- jline.console.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. SeeTerminal.init()
for convenience methods for issuing platform-specific setup commands.- Author:
- Marc Prud'hommeaux, Jason Dillon, Guillaume Nodet
-
-
Field Summary
Fields Modifier and Type Field Description static char
BACKSPACE
static java.lang.String
DEFAULT_INPUT_RC
static java.lang.String
INPUT_RC
static java.lang.String
JLINE_COMPLETION_THRESHOLD
static java.lang.String
JLINE_ESC_TIMEOUT
static java.lang.String
JLINE_EXPAND_EVENTS
static java.lang.String
JLINE_INPUTRC
static java.lang.String
JLINE_NOBELL
static char
KEYBOARD_BELL
static char
NULL_MASK
static char
RESET_LINE
static int
TAB_WIDTH
-
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 specifiedCompleter
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 bufferprotected 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 enabledjava.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 enabledHistory
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 buffervoid
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 specifiedCollection
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 inInputStream
, 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 inInputStream
, and return the line (without any trailing newlines).void
redrawLine()
Clear the line and redraw it.boolean
removeCompleter(Completer completer)
Remove the specifiedCompleter
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 buffervoid
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 throwUserInterruptException
fromreadLine()
.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.Useclose()
instead.boolean
yank()
boolean
yankPop()
-
-
-
Field Detail
-
JLINE_NOBELL
public static final java.lang.String JLINE_NOBELL
- See Also:
- Constant Field Values
-
JLINE_ESC_TIMEOUT
public static final java.lang.String JLINE_ESC_TIMEOUT
- See Also:
- Constant Field Values
-
JLINE_INPUTRC
public static final java.lang.String JLINE_INPUTRC
- See Also:
- Constant Field Values
-
INPUT_RC
public static final java.lang.String INPUT_RC
- See Also:
- Constant Field Values
-
DEFAULT_INPUT_RC
public static final java.lang.String DEFAULT_INPUT_RC
- See Also:
- Constant Field Values
-
JLINE_EXPAND_EVENTS
public static final java.lang.String JLINE_EXPAND_EVENTS
- 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 java.lang.String JLINE_COMPLETION_THRESHOLD
- See Also:
- Constant Field Values
-
-
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
-
-
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 interfacejava.lang.AutoCloseable
- Specified by:
close
in interfacejava.io.Closeable
-
shutdown
@Deprecated public void shutdown()
Deprecated.Useclose()
instead.Shuts the console reader down. The same asclose()
.
-
finalize
protected void finalize() throws java.lang.Throwable
Shuts down the ConsoleReader if the JVM attempts to clean it up.- Overrides:
finalize
in classjava.lang.Object
- Throws:
java.lang.Throwable
-
getInput
public java.io.InputStream getInput()
-
getOutput
public java.io.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 throwUserInterruptException
fromreadLine()
. Otherwise, the JVM will handleSIGINT
as normal, which usually causes it to exit. The default isfalse
.- 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 tonull
will restore normal character echoing. Setting the character toCharacter.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 inInputStream
, 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 inInputStream
, 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 specifiedCompleter
to the list of handlers for tab-completion.- Parameters:
completer
- theCompleter
to add- Returns:
- true if it was successfully added
-
removeCompleter
public boolean removeCompleter(Completer completer)
Remove the specifiedCompleter
from the list of handlers for tab-completion.- Parameters:
completer
- TheCompleter
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)
-
getCompletionHandler
public CompletionHandler getCompletionHandler()
-
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 specifiedCollection
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 promptbuffer
- the buffer to be drawncursorDest
- 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)
-
-