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.
ConsoleReader
public ConsoleReader()
throws 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.
ConsoleReader
public ConsoleReader(InputStream in,
Writer out)
throws IOException
Create a new reader using the specified InputStream
for input and
the specific writer for output, using the default keybindings resource.
ConsoleReader
public ConsoleReader(InputStream in,
Writer out,
InputStream bindings)
throws IOException
ConsoleReader
public ConsoleReader(InputStream in,
Writer out,
InputStream bindings,
Terminal term)
throws IOException
Create a new reader.
in
- the inputout
- the outputbindings
- the key bindings to useterm
- the terminal to use
addCompletor
public boolean addCompletor(Completor completor)
Add the specified
Completor
to the list of handlers for
tab-completion.
- true if it was successfully added
addTriggeredAction
public void addTriggeredAction(char c,
ActionListener listener)
Adding a triggered Action allows to give another curse 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.
backspace
public final boolean backspace()
throws IOException
Issue a backspace.
beep
public final void beep()
throws IOException
clearScreen
public boolean clearScreen()
throws IOException
Clear the screen by issuing the ANSI "clear screen" code.
debug
public static void debug(String str)
debug.
str
- the message to issue.
delete
public final boolean delete()
throws IOException
Issue a delete.
drawLine
public final void drawLine()
throws IOException
Output put the prompt + the current buffer
flushConsole
public final void flushConsole()
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 immedately.
getAutoprintThreshhold
public int getAutoprintThreshhold()
- the number of candidates to print without issing a warning.
getBellEnabled
public boolean getBellEnabled()
- true is audible keyboard bell is enabled.
getCompletors
public Collection getCompletors()
Returns an unmodifiable list of all the completors.
getDefaultPrompt
public String getDefaultPrompt()
The default prompt that will be issued.
getEchoCharacter
public Character getEchoCharacter()
Returns the echo character.
getHistory
public History getHistory()
getInput
public InputStream getInput()
Returns the stream used for console input.
getTermheight
public int getTermheight()
Query the terminal to find the current width;
- the height of the current terminal.
getTerminal
public Terminal getTerminal()
getTermwidth
public int getTermwidth()
Query the terminal to find the current width;
- the width of the current terminal.
getUseHistory
public boolean getUseHistory()
Whether or not to add new commands to the history buffer.
getUsePagination
public boolean getUsePagination()
Whether to use pagination when the number of rows of candidates exceeds
the height of the temrinal.
killLine
public boolean killLine()
throws IOException
Kill the buffer ahead of the current cursor position.
moveCursor
public final int moveCursor(int num)
throws IOException
Move the cursor where characters.
- the number of spaces we moved
paste
public boolean paste()
throws IOException
Paste the contents of the clipboard into the console buffer
- true if clipboard contents pasted
printColumns
public void printColumns(Collection stuff)
throws IOException
Output the specified Collection
in proper columns.
stuff
- the stuff to print
printNewline
public final void printNewline()
throws IOException
Output a platform-dependant newline.
printString
public final void printString(String str)
throws IOException
Output the specified string to the output stream (but not the buffer).
putString
public final void putString(String str)
throws IOException
Write out the specified string to the buffer and the output stream.
readCharacter
public final int readCharacter(char[] allowed)
throws IOException
readLine
public String readLine()
throws IOException
Read the next line and return the contents of the buffer.
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.
readLine
public String readLine(String prompt)
throws IOException
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).
prompt
- the prompt to issue to the console, may be null.
- a line that is read from the terminal, or null if there was null
input (e.g., CTRL-D was pressed).
readVirtualKey
public final int readVirtualKey()
throws IOException
Read a character from the console.
- the character, or -1 if an EOF is received.
redrawLine
public final void redrawLine()
throws IOException
Clear the line and redraw it.
removeCompletor
public boolean removeCompletor(Completor completor)
Remove the specified
Completor
from the list of handlers for
tab-completion.
- true if it was successfully removed
replace
public final boolean replace(int num,
String replacement)
setAutoprintThreshhold
public void setAutoprintThreshhold(int autoprintThreshhold)
autoprintThreshhold
- the number of candidates to print without issuing a warning.
setBellEnabled
public void setBellEnabled(boolean bellEnabled)
bellEnabled
- if true, enable audible keyboard bells if an alert is
required.
setCompletionHandler
public void setCompletionHandler(CompletionHandler completionHandler)
setCursorPosition
public final boolean setCursorPosition(int position)
throws IOException
Move the cursor position to the specified absolute index.
setDebug
public void setDebug(PrintWriter debugger)
Set the stream for debugging. Development use only.
setDefaultPrompt
public void setDefaultPrompt(String prompt)
The default prompt that will be issued.
setEchoCharacter
public void setEchoCharacter(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.
echoCharacter
- the character to echo to the console in place of the typed
character.
setHistory
public void setHistory(History history)
setInput
public void setInput(InputStream in)
Set the stream to be used for console input.
setUseHistory
public void setUseHistory(boolean useHistory)
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.