jline

Class ConsoleReader

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

static String
CR
static SortedMap
KEYMAP_NAMES
Map that contains the operation name to keymay operation mapping.
private static Character
NULL_MASK
The null mask.
(package private) static int
TAB_WIDTH
private int
autoprintThreshhold
The number of tab-completion candidates above which a warning will be prompted before showing all the candidates.
private boolean
bellEnabled
If true, issue an audible keyboard bell when appropriate.
(package private) CursorBuffer
buf
private CompletionHandler
completionHandler
(package private) List
completors
(package private) static PrintWriter
debugger
private Character
echoCharacter
(package private) History
history
(package private) InputStream
in
private short[]
keybindings
The map for logical operations.
private static ResourceBundle
loc
private Character
mask
The current character mask.
(package private) Writer
out
(package private) String
prompt
private Terminal
terminal
The Terminal to use.
private Map
triggeredActions
private boolean
useHistory
private boolean
usePagination

Fields inherited from interface jline.ConsoleOperations

ADD, BACKSPACE, CHANGE_CASE, CHANGE_META, CLEAR_LINE, CLEAR_SCREEN, COMPLETE, CR, CTRL_A, CTRL_B, CTRL_C, CTRL_D, CTRL_E, CTRL_F, 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

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

Method Summary

boolean
addCompletor(Completor completor)
Add the specified Completor 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 preprocessing.
private void
back(int num)
Move the visual cursor backwards without modifying the buffer cursor.
boolean
backspace()
Issue a backspace.
private int
backspace(int num)
Issue num backspaces.
private int
backspaceAll()
void
beep()
Issue an audible keyboard bell, if getBellEnabled() return true.
private void
clearAhead(int num)
Clear ahead the specified number of characters without moving the cursor.
(package private) int
clearEcho(int c)
Clear the echoed characters for the specified character code.
boolean
clearScreen()
Clear the screen by issuing the ANSI "clear screen" code.
private boolean
complete()
Use the completors to modify the buffer with the appropriate completions.
private void
consumeException(Throwable e)
No-op for exceptions we want to silently consume.
(package private) int
countEchoCharacters(char c)
static void
debug(String str)
debug.
boolean
delete()
Issue a delete.
private int
delete(int num)
Issue num deletes.
private boolean
deleteCurrentCharacter()
Delete the character at the current position and redraw the remainder of the buffer.
private boolean
deletePreviousWord()
private void
drawBuffer()
Redraw the rest of the buffer from the cursor onwards.
private void
drawBuffer(int clear)
Redraw the rest of the buffer from the cursor onwards.
void
drawLine()
Output put the prompt + the current buffer
(package private) String
finishBuffer()
Clear the buffer and add its contents to the history.
void
flushConsole()
Flush the console output stream.
int
getAutoprintThreshhold()
boolean
getBellEnabled()
CompletionHandler
getCompletionHandler()
Collection
getCompletors()
Returns an unmodifiable list of all the completors.
CursorBuffer
getCursorBuffer()
(package private) int
getCursorPosition()
String
getDefaultPrompt()
The default prompt that will be issued.
Character
getEchoCharacter()
Returns the echo character.
History
getHistory()
InputStream
getInput()
Returns the stream used for console input.
(package private) int
getKeyForAction(short logicalAction)
(package private) StringBuffer
getPrintableCharacters(char ch)
Return the number of characters that will be printed when the specified character is echoed to the screen.
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.
private boolean
isDelimiter(char c)
Checks to see if the specified character is a delimiter.
boolean
killLine()
Kill the buffer ahead of the current cursor position.
int
moveCursor(int num)
Move the cursor where characters.
private boolean
moveHistory(boolean next)
Move up or down the history tree.
private void
moveInternal(int where)
Move the cursor where characters, withough checking the current buffer.
private boolean
moveToEnd()
private boolean
nextWord()
private void
pad(String toPad, int len, StringBuffer appendTo)
Append toPad to the specified appendTo, as well as (toPad.length () - len) spaces.
boolean
paste()
Paste the contents of the clipboard into the console buffer
private boolean
previousWord()
private void
printCharacter(int c)
Output the specified character to the output stream without manipulating the current buffer.
private void
printCharacters(char c, int num)
private void
printCharacters(char[] c)
Output the specified characters to the output stream without manipulating the current buffer.
void
printColumns(Collection stuff)
Output the specified Collection in proper columns.
void
printNewline()
Output a platform-dependant newline.
void
printString(String str)
Output the specified string to the output stream (but not the buffer).
private void
putChar(int c, boolean print)
Output the specified character, both to the buffer and the output stream.
void
putString(String str)
Write out the specified string to the buffer and the output stream.
private int[]
readBinding()
Reads the console input and returns an array of the form [raw, key binding].
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.
private String
readLine(InputStream in)
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).
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, String replacement)
(package private) boolean
resetLine()
Erase the current line.
void
setAutoprintThreshhold(int autoprintThreshhold)
void
setBellEnabled(boolean bellEnabled)
private void
setBuffer(String buffer)
Set the current buffer's content to the specified String.
void
setCompletionHandler(CompletionHandler completionHandler)
boolean
setCursorPosition(int position)
Move the cursor position to the specified absolute index.
void
setDebug(PrintWriter debugger)
Set the stream for debugging.
void
setDefaultPrompt(String prompt)
The default prompt that will be issued.
void
setEchoCharacter(Character echoCharacter)
Set the echo character.
void
setHistory(History history)
void
setInput(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.

Field Details

CR

public static final String CR

KEYMAP_NAMES

public static SortedMap KEYMAP_NAMES
Map that contains the operation name to keymay operation mapping.

NULL_MASK

private static final Character NULL_MASK
The null mask.

TAB_WIDTH

(package private) static final int TAB_WIDTH
Field Value:
4

autoprintThreshhold

private int autoprintThreshhold
The number of tab-completion candidates above which a warning will be prompted before showing all the candidates.

bellEnabled

private boolean bellEnabled
If true, issue an audible keyboard bell when appropriate.

buf

(package private) final CursorBuffer buf

completionHandler

private CompletionHandler completionHandler

completors

(package private) final List completors

debugger

(package private) static PrintWriter debugger

echoCharacter

private Character echoCharacter

history

(package private)  History history

in

(package private)  InputStream in

keybindings

private final short[] keybindings
The map for logical operations.

loc

private static ResourceBundle loc

mask

private Character mask
The current character mask.

out

(package private) final Writer out

prompt

(package private)  String prompt

terminal

private final Terminal terminal
The Terminal to use.

triggeredActions

private Map triggeredActions

useHistory

private boolean useHistory

usePagination

private boolean usePagination

Constructor Details

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.
Parameters:
in - the input
out - the output
bindings - the key bindings to use
term - the terminal to use

Method Details

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

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.
Parameters:
c -
listener -

back

private final void back(int num)
            throws IOException
Move the visual cursor backwards without modifying the buffer cursor.

backspace

public final boolean backspace()
            throws IOException
Issue a backspace.
Returns:
true if successful

backspace

private final int backspace(int num)
            throws IOException
Issue num backspaces.
Returns:
the number of characters backed up

backspaceAll

private final int backspaceAll()
            throws IOException

beep

public final void beep()
            throws IOException

clearAhead

private final void clearAhead(int num)
            throws IOException
Clear ahead the specified number of characters without moving the cursor.

clearEcho

(package private)  int clearEcho(int c)
            throws IOException
Clear the echoed characters for the specified character code.

clearScreen

public boolean clearScreen()
            throws IOException
Clear the screen by issuing the ANSI "clear screen" code.

complete

private final boolean complete()
            throws IOException
Use the completors to modify the buffer with the appropriate completions.
Returns:
true if successful

consumeException

private void consumeException(Throwable e)
No-op for exceptions we want to silently consume.

countEchoCharacters

(package private)  int countEchoCharacters(char c)

debug

public static void debug(String str)
debug.
Parameters:
str - the message to issue.

delete

public final boolean delete()
            throws IOException
Issue a delete.
Returns:
true if successful

delete

private final int delete(int num)
            throws IOException
Issue num deletes.
Returns:
the number of characters backed up

deleteCurrentCharacter

private final boolean deleteCurrentCharacter()
            throws IOException
Delete the character at the current position and redraw the remainder of the buffer.

deletePreviousWord

private final boolean deletePreviousWord()
            throws IOException

drawBuffer

private final void drawBuffer()
            throws IOException
Redraw the rest of the buffer from the cursor onwards. This is necessary for inserting text into the buffer.

drawBuffer

private final void drawBuffer(int clear)
            throws IOException
Redraw the rest of the buffer from the cursor onwards. This is necessary for inserting text into the buffer.
Parameters:
clear - the number of characters to clear after the end of the buffer

drawLine

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

finishBuffer

(package private) final String finishBuffer()
Clear the buffer and add its contents to the history.
Returns:
the former contents of the 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()
Returns:
the number of candidates to print without issing a warning.

getBellEnabled

public boolean getBellEnabled()
Returns:
true is audible keyboard bell is enabled.

getCompletionHandler

public CompletionHandler getCompletionHandler()

getCompletors

public Collection getCompletors()
Returns an unmodifiable list of all the completors.

getCursorBuffer

public CursorBuffer getCursorBuffer()

getCursorPosition

(package private)  int getCursorPosition()

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.

getKeyForAction

(package private)  int getKeyForAction(short logicalAction)

getPrintableCharacters

(package private)  StringBuffer getPrintableCharacters(char ch)
Return the number of characters that will be printed when the specified character is echoed to the screen. Adapted from cat by Torbjorn Granlund, as repeated in stty by David MacKenzie.

getTermheight

public int getTermheight()
Query the terminal to find the current width;
Returns:
the height of the current terminal.

getTerminal

public Terminal getTerminal()

getTermwidth

public int getTermwidth()
Query the terminal to find the current width;
Returns:
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.

isDelimiter

private boolean isDelimiter(char c)
Checks to see if the specified character is a delimiter. We consider a character a delimiter if it is anything but a letter or digit.
Parameters:
c - the character to test
Returns:
true if it is a delimiter

killLine

public boolean killLine()
            throws IOException
Kill the buffer ahead of the current cursor position.
Returns:
true if successful

moveCursor

public final int moveCursor(int num)
            throws IOException
Move the cursor where characters.
Parameters:
Returns:
the number of spaces we moved

moveHistory

private final boolean moveHistory(boolean next)
            throws IOException
Move up or down the history tree.
Parameters:

moveInternal

private final void moveInternal(int where)
            throws IOException
Move the cursor where characters, withough checking the current buffer.
Parameters:
where - the number of characters to move to the right or left.
See Also:
ConsoleReader

moveToEnd

private final boolean moveToEnd()
            throws IOException

nextWord

private final boolean nextWord()
            throws IOException

pad

private final void pad(String toPad,
                       int len,
                       StringBuffer appendTo)
Append toPad to the specified appendTo, as well as (toPad.length () - len) spaces.
Parameters:
toPad - the String to pad
len - the target length
appendTo - the StringBuffer to which to append the padded String.

paste

public boolean paste()
            throws IOException
Paste the contents of the clipboard into the console buffer
Returns:
true if clipboard contents pasted

previousWord

private final boolean previousWord()
            throws IOException

printCharacter

private final void printCharacter(int c)
            throws IOException
Output the specified character to the output stream without manipulating the current buffer.

printCharacters

private final void printCharacters(char c,
                                   int num)
            throws IOException

printCharacters

private final void printCharacters(char[] c)
            throws IOException
Output the specified characters to the output stream without manipulating the current buffer.

printColumns

public void printColumns(Collection stuff)
            throws IOException
Output the specified Collection in proper columns.
Parameters:
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).

putChar

private final void putChar(int c,
                           boolean print)
            throws IOException
Output the specified character, both to the buffer and the output stream.

putString

public final void putString(String str)
            throws IOException
Write out the specified string to the buffer and the output stream.

readBinding

private int[] readBinding()
            throws IOException
Reads the console input and returns an array of the form [raw, key binding].

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

private String readLine(InputStream in)
            throws IOException

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).
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).

readVirtualKey

public final int readVirtualKey()
            throws IOException
Read a character from the console.
Returns:
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.
Parameters:
completor - the Completor to remove
Returns:
true if it was successfully removed

replace

public final boolean replace(int num,
                             String replacement)

resetLine

(package private) final boolean resetLine()
            throws IOException
Erase the current line.
Returns:
false if we failed (e.g., the buffer was empty)

setAutoprintThreshhold

public void setAutoprintThreshhold(int autoprintThreshhold)
Parameters:
autoprintThreshhold - the number of candidates to print without issuing a warning.

setBellEnabled

public void setBellEnabled(boolean bellEnabled)
Parameters:
bellEnabled - if true, enable audible keyboard bells if an alert is required.

setBuffer

private final void setBuffer(String buffer)
            throws IOException
Set the current buffer's content to the specified String. The visual console will be modified to show the current buffer.
Parameters:
buffer - the new contents of the buffer.

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.
Parameters:
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.