Package jline.console
Class ConsoleReader
java.lang.Object
jline.console.ConsoleReader
- All Implemented Interfaces:
Closeable
,AutoCloseable
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
Fields -
Constructor Summary
ConstructorsConstructorDescriptionConsoleReader
(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
Modifier and TypeMethodDescriptionaccept()
The equivalent of hitting <RET>.boolean
addCompleter
(Completer completer) Add the specifiedCompleter
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 backward without modifying the buffer cursor.boolean
Issue a backspace.void
beep()
Issue an audible keyboard bell.boolean
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 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
boolean
Get whether the console bell is enabledReturns an unmodifiable list of all the completers.Returns the echo character.boolean
boolean
Get wether literal next are handled by JLine.boolean
Get whether user interrupt handling is enabledgetInput()
static URL
Retrieve the URL for the inputrc configuration file in effect.Returns the name of the current key mapping.getKeys()
boolean
boolean
Whether or not to add new commands to the history buffer.boolean
boolean
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
boolean
paste()
Paste the contents of the clipboard into the console buffervoid
Output the specified string to the output stream (but not the buffer).void
printColumns
(Collection<? extends CharSequence> items) Output the specifiedCollection
in proper columns.protected void
void
printForwardSearchStatus
(String searchTerm, String match) void
println()
Output a platform-dependant newline.void
void
printSearchStatus
(String searchTerm, String match) void
putString
(CharSequence str) Write out the specified string to the buffer and the output stream.readBinding
(KeyMap keys) Read from the input stream and decode an operation from the key map.int
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) readLine()
Read the next line and return the contents of the buffer.Read the next line with the specified character mask.Read a line from the inInputStream
, and return the line (without any trailing newlines).Read a line from the inInputStream
, and return the line (without any trailing newlines).void
Clear the line and redraw it.boolean
removeCompleter
(Completer completer) Remove the specifiedCompleter
from the list of handlers for tab-completion.protected final boolean
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 buffervoid
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
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
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
void
shutdown()
Deprecated.boolean
yank()
boolean
yankPop()
-
Field Details
-
JLINE_NOBELL
- See Also:
-
JLINE_ESC_TIMEOUT
- See Also:
-
JLINE_INPUTRC
- See Also:
-
INPUT_RC
- See Also:
-
DEFAULT_INPUT_RC
- See Also:
-
JLINE_EXPAND_EVENTS
- See Also:
-
BACKSPACE
public static final char BACKSPACE- See Also:
-
RESET_LINE
public static final char RESET_LINE- See Also:
-
KEYBOARD_BELL
public static final char KEYBOARD_BELL- See Also:
-
NULL_MASK
public static final char NULL_MASK- See Also:
-
TAB_WIDTH
public static final int TAB_WIDTH- See Also:
-
JLINE_COMPLETION_THRESHOLD
- See Also:
-
-
Constructor Details
-
ConsoleReader
- Throws:
IOException
-
ConsoleReader
- Throws:
IOException
-
ConsoleReader
- 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 Details
-
getInputRc
Retrieve the URL for the inputrc configuration file in effect. Intended use is for instantiating ConsoleKeys, to read inputrc variables.- Throws:
IOException
-
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 interfaceAutoCloseable
- Specified by:
close
in interfaceCloseable
-
shutdown
Deprecated.Useclose()
instead.Shuts the console reader down. The same asclose()
. -
finalize
Shuts down the ConsoleReader if the JVM attempts to clean it up. -
getInput
-
getOutput
-
getTerminal
-
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
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
- Returns:
- the string that will be used to start a comment when the insert-comment key is struck.
- Since:
- 2.7
-
setPrompt
-
getPrompt
-
setEchoCharacter
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
Returns the echo character. -
resetLine
Erase the current line.- Returns:
- false if we failed (e.g., the buffer was empty)
- Throws:
IOException
-
setCursorPosition
Move the cursor position to the specified absolute index.- Throws:
IOException
-
drawLine
Output put the prompt + the current buffer- Throws:
IOException
-
redrawLine
Clear the line and redraw it.- Throws:
IOException
-
expandEvents
Expand event designator such as !!, !#, !3, etc... See http://www.gnu.org/software/bash/manual/html_node/Event-Designators.html- Throws:
IOException
-
putString
Write out the specified string to the buffer and the output stream.- Throws:
IOException
-
back
Move the visual cursor backward without modifying the buffer cursor.- Throws:
IOException
-
flush
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
Issue a backspace.- Returns:
- true if successful
- Throws:
IOException
-
moveToEnd
- Throws:
IOException
-
setParenBlinkTimeout
public void setParenBlinkTimeout(int timeout) -
isKeyMap
-
accept
The equivalent of hitting <RET>. The line is considered complete and is returned.- Returns:
- The completed line of text.
- Throws:
IOException
-
moveCursor
Move the cursor where characters.- Parameters:
num
- If less than 0, move abs(where) to the left, otherwise move where to the right.- Returns:
- The number of spaces we moved
- Throws:
IOException
-
readCharacter
Read a character from the console.- Returns:
- the character, or -1 if an EOF is received.
- Throws:
IOException
-
readCharacter
Read a character from the console. If boolean parameter is "true", it will check whether the keystroke was an "alt-" key combination, and if so add 1000 to the value returned. Better way...?- Returns:
- the character, or -1 if an EOF is received.
- Throws:
IOException
-
readCharacter
- Throws:
IOException
-
readCharacter
- Throws:
IOException
-
readBinding
Read from the input stream and decode an operation from the key map. The input stream will be read character by character until a matching binding can be found. Characters that can't possibly be matched to any binding will be discarded.- Parameters:
keys
- the KeyMap to use for decoding the input stream- Returns:
- the decoded binding or
null
if the end of stream has been reached - Throws:
IOException
-
getLastBinding
-
readLine
Read the next line and return the contents of the buffer.- Throws:
IOException
-
readLine
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
- Throws:
IOException
-
readLine
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:
IOException
-
setKeyMap
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
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
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:
IOException
-
addCompleter
Add the specifiedCompleter
to the list of handlers for tab-completion.- Parameters:
completer
- theCompleter
to add- Returns:
- true if it was successfully added
-
removeCompleter
Remove the specifiedCompleter
from the list of handlers for tab-completion.- Parameters:
completer
- TheCompleter
to remove- Returns:
- True if it was successfully removed
-
getCompleters
Returns an unmodifiable list of all the completers. -
setCompletionHandler
-
getCompletionHandler
-
complete
Use the completers to modify the buffer with the appropriate completions.- Returns:
- true if successful
- Throws:
IOException
-
printCompletionCandidates
- 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
-
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
Output the specified string to the output stream (but not the buffer).- Throws:
IOException
-
println
- Throws:
IOException
-
println
Output a platform-dependant newline.- Throws:
IOException
-
delete
Issue a delete.- Returns:
- true if successful
- Throws:
IOException
-
killLine
Kill the buffer ahead of the current cursor position.- Returns:
- true if successful
- Throws:
IOException
-
yank
- Throws:
IOException
-
yankPop
- Throws:
IOException
-
clearScreen
Clear the screen by issuing the ANSI "clear screen" code.- Throws:
IOException
-
beep
Issue an audible keyboard bell.- Throws:
IOException
-
paste
Paste the contents of the clipboard into the console buffer- Returns:
- true if clipboard contents pasted
- Throws:
IOException
-
addTriggeredAction
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
Output the specifiedCollection
in proper columns.- Throws:
IOException
-
resetPromptLine
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:
IOException
-
printSearchStatus
- Throws:
IOException
-
printForwardSearchStatus
- Throws:
IOException
-
restoreLine
- Throws:
IOException
-
searchBackwards
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
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
-
searchForwards
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
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
-
close()
instead.