jline
Class ConsoleReader

java.lang.Object
  |
  +--jline.ConsoleReader

public class ConsoleReader
extends Object

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.

TODO:

Author:
Marc Prud'hommeaux

Field Summary
static short ADD
          Operation that
static short ARROW_DOWN
           
static short ARROW_LEFT
           
static short ARROW_PREFIX
           
static short ARROW_RIGHT
           
static short ARROW_START
           
static short ARROW_UP
           
static char BACKSPACE
           
(package private)  CursorBuffer buf
           
static short CHANGE_CASE
          Operation that toggles between uppercase and lowercase.
static short CHANGE_META
          Operation that
static short CLEAR_SCREEN
          Operation that clears the screen.
static short COMPLETE
          Operation that performs completion operation on the current word.
(package private)  List completors
           
static String CR
           
(package private) static PrintWriter debugger
           
static short DELETE_META
          Operation that
static short DELETE_NEXT_CHAR
          Operation that deletes the previous character.
static short DELETE_PREV_CHAR
          Operation that
static short DELETE_PREV_WORD
          Operation that deletes the previous word in the buffer.
static short END_WORD
          Operation that
static short EXIT
          Operation that exits the command prompt.
(package private)  History history
           
(package private)  InputStream in
           
static short INSERT
          Operation that
static char KEYBOARD_BELL
           
static SortedMap KEYMAP_NAMES
          Map that contains the operation name to keymay operation mapping.
static short KILL_LINE
          Operation that deletes the buffer from the current character to the end.
static short KILL_LINE_PREV
          Operation that deletes the buffer from the cursor to the beginning.
static short MOVE_TO_BEG
          Operation that moves to the beginning of the buffer.
static short MOVE_TO_END
          Operation that moves to the end of the buffer.
static short NEWLINE
          Operation that issues a newline.
static short NEXT_CHAR
          Operation that moves to the next character in the buffer.
static short NEXT_HISTORY
          Operation that sets the buffer to the next history item.
static short NEXT_SPACE_WORD
          Operation that
static short NEXT_WORD
          Operation that moved to the next word.
(package private)  Writer out
           
static short PASTE_NEXT
          Operation that
static short PASTE_PREV
          Operation that
static short PREV_CHAR
          Operation that moved to the previous character in the buffer.
static short PREV_HISTORY
          Operation that sets the buffer to the previous history item.
static short PREV_SPACE_WORD
          Operation that moved to the previous whitespace.
static short PREV_WORD
          Operation that
(package private)  String prompt
           
static short REDISPLAY
          Operation that redisplays the current buffer.
static short REPEAT_NEXT_CHAR
          Operation that repeats the character.
static short REPEAT_PREV_CHAR
          Operation that moves to the previous character in the buffer.
static short REPEAT_SEARCH_NEXT
          Operation that
static short REPEAT_SEARCH_PREV
          Operation that
static short REPLACE_CHAR
          Operation that
static short REPLACE_MODE
          Operation that
static char RESET_LINE
           
static short SEARCH_NEXT
          Operation that searches forward in the command history.
static short SEARCH_PREV
          Operation that searches backwards in the command history.
static short SUBSTITUTE_CHAR
          Operation that
static short SUBSTITUTE_LINE
          Operation that
static short TO_END_WORD
          Operation that moved to the end of the current word.
static short TO_NEXT_CHAR
          Operation that
static short TO_PREV_CHAR
          Operation that
static short UNDO
          Operation that undoes the previous operation.
static short UNKNOWN
          Unknown operation.
 
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)
          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.
(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()
           
 boolean getEcho()
           
 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;
 int getTermwidth()
          Query the terminal to find the current width;
 boolean killLine()
          Kill the buffer ahead of the current cursor position.
 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()
          Read a character from the console.
 String readLine()
          Read the next line and return the contents of the buffer.
 String readLine(String prompt)
          Read a line from the in InputStream, and return the line (without any trailing newlines).
 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 setEcho(boolean echo)
           
 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

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

ARROW_START

public static final short ARROW_START
See Also:
Constant Field Values

ARROW_PREFIX

public static final short ARROW_PREFIX
See Also:
Constant Field Values

ARROW_LEFT

public static final short ARROW_LEFT
See Also:
Constant Field Values

ARROW_RIGHT

public static final short ARROW_RIGHT
See Also:
Constant Field Values

ARROW_UP

public static final short ARROW_UP
See Also:
Constant Field Values

ARROW_DOWN

public static final short ARROW_DOWN
See Also:
Constant Field Values

UNKNOWN

public static final short UNKNOWN
Unknown operation.

See Also:
Constant Field Values

MOVE_TO_BEG

public static final short MOVE_TO_BEG
Operation that moves to the beginning of the buffer.

See Also:
Constant Field Values

MOVE_TO_END

public static final short MOVE_TO_END
Operation that moves to the end of the buffer.

See Also:
Constant Field Values

PREV_CHAR

public static final short PREV_CHAR
Operation that moved to the previous character in the buffer.

See Also:
Constant Field Values

NEWLINE

public static final short NEWLINE
Operation that issues a newline.

See Also:
Constant Field Values

KILL_LINE

public static final short KILL_LINE
Operation that deletes the buffer from the current character to the end.

See Also:
Constant Field Values

CLEAR_SCREEN

public static final short CLEAR_SCREEN
Operation that clears the screen.

See Also:
Constant Field Values

NEXT_HISTORY

public static final short NEXT_HISTORY
Operation that sets the buffer to the next history item.

See Also:
Constant Field Values

PREV_HISTORY

public static final short PREV_HISTORY
Operation that sets the buffer to the previous history item.

See Also:
Constant Field Values

REDISPLAY

public static final short REDISPLAY
Operation that redisplays the current buffer.

See Also:
Constant Field Values

KILL_LINE_PREV

public static final short KILL_LINE_PREV
Operation that deletes the buffer from the cursor to the beginning.

See Also:
Constant Field Values

DELETE_PREV_WORD

public static final short DELETE_PREV_WORD
Operation that deletes the previous word in the buffer.

See Also:
Constant Field Values

NEXT_CHAR

public static final short NEXT_CHAR
Operation that moves to the next character in the buffer.

See Also:
Constant Field Values

REPEAT_PREV_CHAR

public static final short REPEAT_PREV_CHAR
Operation that moves to the previous character in the buffer.

See Also:
Constant Field Values

SEARCH_PREV

public static final short SEARCH_PREV
Operation that searches backwards in the command history.

See Also:
Constant Field Values

REPEAT_NEXT_CHAR

public static final short REPEAT_NEXT_CHAR
Operation that repeats the character.

See Also:
Constant Field Values

SEARCH_NEXT

public static final short SEARCH_NEXT
Operation that searches forward in the command history.

See Also:
Constant Field Values

PREV_SPACE_WORD

public static final short PREV_SPACE_WORD
Operation that moved to the previous whitespace.

See Also:
Constant Field Values

TO_END_WORD

public static final short TO_END_WORD
Operation that moved to the end of the current word.

See Also:
Constant Field Values

REPEAT_SEARCH_PREV

public static final short REPEAT_SEARCH_PREV
Operation that

See Also:
Constant Field Values

PASTE_PREV

public static final short PASTE_PREV
Operation that

See Also:
Constant Field Values

REPLACE_MODE

public static final short REPLACE_MODE
Operation that

See Also:
Constant Field Values

SUBSTITUTE_LINE

public static final short SUBSTITUTE_LINE
Operation that

See Also:
Constant Field Values

TO_PREV_CHAR

public static final short TO_PREV_CHAR
Operation that

See Also:
Constant Field Values

NEXT_SPACE_WORD

public static final short NEXT_SPACE_WORD
Operation that

See Also:
Constant Field Values

DELETE_PREV_CHAR

public static final short DELETE_PREV_CHAR
Operation that

See Also:
Constant Field Values

ADD

public static final short ADD
Operation that

See Also:
Constant Field Values

PREV_WORD

public static final short PREV_WORD
Operation that

See Also:
Constant Field Values

CHANGE_META

public static final short CHANGE_META
Operation that

See Also:
Constant Field Values

DELETE_META

public static final short DELETE_META
Operation that

See Also:
Constant Field Values

END_WORD

public static final short END_WORD
Operation that

See Also:
Constant Field Values

INSERT

public static final short INSERT
Operation that

See Also:
Constant Field Values

REPEAT_SEARCH_NEXT

public static final short REPEAT_SEARCH_NEXT
Operation that

See Also:
Constant Field Values

PASTE_NEXT

public static final short PASTE_NEXT
Operation that

See Also:
Constant Field Values

REPLACE_CHAR

public static final short REPLACE_CHAR
Operation that

See Also:
Constant Field Values

SUBSTITUTE_CHAR

public static final short SUBSTITUTE_CHAR
Operation that

See Also:
Constant Field Values

TO_NEXT_CHAR

public static final short TO_NEXT_CHAR
Operation that

See Also:
Constant Field Values

UNDO

public static final short UNDO
Operation that undoes the previous operation.

See Also:
Constant Field Values

NEXT_WORD

public static final short NEXT_WORD
Operation that moved to the next word.

See Also:
Constant Field Values

DELETE_NEXT_CHAR

public static final short DELETE_NEXT_CHAR
Operation that deletes the previous character.

See Also:
Constant Field Values

CHANGE_CASE

public static final short CHANGE_CASE
Operation that toggles between uppercase and lowercase.

See Also:
Constant Field Values

COMPLETE

public static final short COMPLETE
Operation that performs completion operation on the current word.

See Also:
Constant Field Values

EXIT

public static final short EXIT
Operation that exits the command prompt.

See Also:
Constant Field Values

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
Create a new reader.

Parameters:
in - the input
out - the output
bindings - the key bindings to use
Method Detail

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.

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.

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

killLine

public boolean killLine()
                 throws IOException
Kill the buffer ahead of the current cursor position.

Returns:
true if successful
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
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)
IOException

setCursorPosition

public final boolean setCursorPosition(int position)
                                throws IOException
Move the cursor position to the specified absolute index.

IOException

redrawLine

public final void redrawLine()
                      throws IOException
Clear the line and redraw it.

IOException

drawLine

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

IOException

printNewline

public final void printNewline()
                        throws IOException
Output a platform-dependant newline.

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.

IOException

printString

public final void printString(String str)
                       throws IOException
Output the specified string to the output stream (but not the buffer).

IOException

beep

public final void beep()
                throws IOException
Issue an audible keyboard bell, if getBellEnabled() return true.

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.

IOException

backspace

public final boolean backspace()
                        throws IOException
Issue a backspace.

Returns:
true if successful
IOException

debug

public static void debug(String str)
debug.

Parameters:
str - the message to issue.

readCharacter

public final int readCharacter()
                        throws IOException
Read a character from the console.

Returns:
the character, or -1 if an EOF is received.
IOException

setHistory

public void setHistory(History history)

getHistory

public History getHistory()

setEcho

public void setEcho(boolean echo)

getEcho

public boolean getEcho()

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.



Released under the terms of the GNU LGPL