jline
Class ConsoleReader

java.lang.Object
  jline.ConsoleReader

All Implemented Interfaces:

ConsoleOperations

public class ConsoleReader

extends 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

(package private) CursorBuffer	buf
(package private) List	completors
static String	CR
(package private) static PrintWriter	debugger
(package private) History	history
(package private) InputStream	in
static SortedMap	KEYMAP_NAMES Map that contains the operation name to keymay operation mapping.
(package private) Writer	out
(package private) String	prompt

Fields inherited from interface jline.ConsoleOperations

ADD, BACKSPACE, CHANGE_CASE, CHANGE_META, CLEAR_SCREEN, COMPLETE, CTRL_A, CTRL_B, CTRL_C, CTRL_D, CTRL_E, CTRL_F, CTRL_N, CTRL_P, DELETE_META, DELETE_NEXT_CHAR, DELETE_PREV_CHAR, DELETE_PREV_WORD, 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, 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.
boolean	backspace() Issue a backspace.
void	beep() Issue an audible keyboard bell, if getBellEnabled() return true.
(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.
(package private) int	countEchoCharacters(char c)
static void	debug(String str) debug.
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()
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	killLine() Kill the buffer ahead of the current cursor position.
boolean	paste() Paste the contents of the clipboard into the console 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).
void	putString(String str) Write out the specified string to the buffer and the output stream.
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).
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.
(package private) boolean	resetLine() Erase the current line.
void	setAutoprintThreshhold(int autoprintThreshhold)
void	setBellEnabled(boolean bellEnabled)
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	setEchoCharacter(Character echoCharacter) Set the echo character.
void	setHistory(History history)
void	setInput(InputStream in) Set the stream to be used for console input.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

prompt

String prompt

CR

public static final String CR

KEYMAP_NAMES

public static SortedMap KEYMAP_NAMES

Map that contains the operation name to keymay operation mapping.

in

InputStream in

out

final Writer out

buf

final CursorBuffer buf

debugger

static PrintWriter debugger

history

History history

completors

final List completors

Constructor Detail

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 Detail

getTerminal

public Terminal getTerminal()

setDebug

public void setDebug(PrintWriter debugger)

Set the stream for debugging. Development use only.

setInput

public void setInput(InputStream in)

Set the stream to be used for console input.

getInput

public InputStream getInput()

Returns the stream used for console input.

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

setBellEnabled

public void setBellEnabled(boolean bellEnabled)

Parameters:

bellEnabled - if true, enable audible keyboard bells if an alert is required.

getBellEnabled

public boolean getBellEnabled()

Returns:

true is audible keyboard bell is enabled.

getTermwidth

public int getTermwidth()

Query the terminal to find the current width;

Returns:

the width of the current terminal.

See Also:

Terminal.getTerminalWidth()

getTermheight

public int getTermheight()

Query the terminal to find the current width;

Returns:

the height of the current terminal.

See Also:

Terminal.getTerminalHeight()

setAutoprintThreshhold

public void setAutoprintThreshhold(int autoprintThreshhold)

Parameters:

autoprintThreshhold - the number of candidates to print without issuing a warning.

getAutoprintThreshhold

public int getAutoprintThreshhold()

Returns:

the number of candidates to print without issing a warning.

getKeyForAction

int getKeyForAction(short logicalAction)

clearEcho

int clearEcho(int c)
        throws IOException

Clear the echoed characters for the specified character code.

Throws:

IOException

countEchoCharacters

int countEchoCharacters(char c)

getPrintableCharacters

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.

getCursorPosition

int getCursorPosition()

readLine

public String readLine(String prompt)
                throws IOException

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

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

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

getCursorBuffer

public CursorBuffer getCursorBuffer()

printColumns

public void printColumns(Collection stuff)
                  throws IOException

Output the specified Collection in proper columns.

Parameters:

stuff - the stuff to print

Throws:

IOException

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

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

getCompletors

public Collection getCompletors()

Returns an unmodifiable list of all the completors.

resetLine

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

redrawLine

public final void redrawLine()
                      throws IOException

Clear the line and redraw it.

Throws:

IOException

drawLine

public final void drawLine()
                    throws IOException

Output put the prompt + the current buffer

Throws:

IOException

printNewline

public final void printNewline()
                        throws IOException

Output a platform-dependant newline.

Throws:

IOException

finishBuffer

final String finishBuffer()

Clear the buffer and add its contents to the history.

Returns:

the former contents of the buffer.

putString

public final void putString(String str)
                     throws IOException

Write out the specified string to the buffer and the output stream.

Throws:

IOException

printString

public final void printString(String str)
                       throws IOException

Output the specified string to the output stream (but not the buffer).

Throws:

IOException

beep

public final void beep()
                throws IOException

Issue an audible keyboard bell, if getBellEnabled() return true.

Throws:

IOException

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.

Throws:

IOException

backspace

public final boolean backspace()
                        throws IOException

Issue a backspace.

Returns:

true if successful

Throws:

IOException

debug

public static void debug(String str)

debug.

Parameters:

str - the message to issue.

readVirtualKey

public final int readVirtualKey()
                         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

setHistory

public void setHistory(History history)

getHistory

public History getHistory()

setCompletionHandler

public void setCompletionHandler(CompletionHandler completionHandler)

getCompletionHandler

public CompletionHandler getCompletionHandler()

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.

getEchoCharacter

public Character getEchoCharacter()

Returns the echo character.