jline
Class ConsoleReader

java.lang.Object
  extended byjline.ConsoleReader
All 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
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)  java.util.List completors
           
static java.lang.String CR
           
(package private) static java.io.PrintWriter debugger
           
private  java.lang.Character echoCharacter
           
(package private)  History history
           
(package private)  java.io.InputStream in
           
private  short[] keybindings
          The map for logical operations.
static java.util.SortedMap KEYMAP_NAMES
          Map that contains the operation name to keymay operation mapping.
private  java.lang.Character mask
          The current character mask.
private static java.lang.Character NULL_MASK
          The null mask.
(package private)  java.io.Writer out
           
(package private)  java.lang.String prompt
           
private  Terminal terminal
          The Terminal to use.
private  boolean useHistory
           
 
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(java.io.InputStream in, java.io.Writer out)
          Create a new reader using the specified InputStream for input and the specific writer for output, using the default keybindings resource.
ConsoleReader(java.io.InputStream in, java.io.Writer out, java.io.InputStream bindings)
           
ConsoleReader(java.io.InputStream in, java.io.Writer out, java.io.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.
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(java.lang.Throwable e)
          No-op for exceptions we want to silently consume.
(package private)  int countEchoCharacters(char c)
           
static void debug(java.lang.String str)
          debug.
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)  java.lang.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()
           
 java.util.Collection getCompletors()
          Returns an unmodifiable list of all the completors.
 CursorBuffer getCursorBuffer()
           
(package private)  int getCursorPosition()
           
 java.lang.String getDefaultPrompt()
          The default prompt that will be issued.
 java.lang.Character getEchoCharacter()
          Returns the echo character.
 History getHistory()
           
 java.io.InputStream getInput()
          Returns the stream used for console input.
(package private)  int getKeyForAction(short logicalAction)
           
(package private)  java.lang.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.
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.
private  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(java.lang.String toPad, int len, java.lang.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)
          Output the specified characters to the output stream without manipulating the current buffer.
private  void printCharacters(char c, int num)
           
 void printColumns(java.util.Collection stuff)
          Output the specified Collection in proper columns.
 void printNewline()
          Output a platform-dependant newline.
 void printString(java.lang.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(java.lang.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)
           
 java.lang.String readLine()
          Read the next line and return the contents of the buffer.
 java.lang.String readLine(java.lang.Character mask)
          Read the next line with the specified character mask.
private  java.lang.String readLine(java.io.InputStream in)
           
 java.lang.String readLine(java.lang.String prompt)
           
 java.lang.String readLine(java.lang.String prompt, java.lang.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)
           
private  void setBuffer(java.lang.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(java.io.PrintWriter debugger)
          Set the stream for debugging.
 void setDefaultPrompt(java.lang.String prompt)
          The default prompt that will be issued.
 void setEchoCharacter(java.lang.Character echoCharacter)
           Set the echo character.
 void setHistory(History history)
           
 void setInput(java.io.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.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

prompt

java.lang.String prompt

useHistory

private boolean useHistory

CR

public static final java.lang.String CR

KEYMAP_NAMES

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


keybindings

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


bellEnabled

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


mask

private java.lang.Character mask
The current character mask.


NULL_MASK

private static final java.lang.Character NULL_MASK
The null mask.


autoprintThreshhold

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


terminal

private final Terminal terminal
The Terminal to use.


completionHandler

private CompletionHandler completionHandler

in

java.io.InputStream in

out

final java.io.Writer out

buf

final CursorBuffer buf

debugger

static java.io.PrintWriter debugger

history

History history

completors

final java.util.List completors

echoCharacter

private java.lang.Character echoCharacter
Constructor Detail

ConsoleReader

public ConsoleReader()
              throws java.io.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(java.io.InputStream in,
                     java.io.Writer out)
              throws java.io.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(java.io.InputStream in,
                     java.io.Writer out,
                     java.io.InputStream bindings)
              throws java.io.IOException

ConsoleReader

public ConsoleReader(java.io.InputStream in,
                     java.io.Writer out,
                     java.io.InputStream bindings,
                     Terminal term)
              throws java.io.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(java.io.PrintWriter debugger)
Set the stream for debugging. Development use only.


setInput

public void setInput(java.io.InputStream in)
Set the stream to be used for console input.


getInput

public java.io.InputStream getInput()
Returns the stream used for console input.


readLine

public java.lang.String readLine()
                          throws java.io.IOException
Read the next line and return the contents of the buffer.

Throws:
java.io.IOException

readLine

public java.lang.String readLine(java.lang.Character mask)
                          throws java.io.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:
java.io.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 java.io.IOException
Clear the echoed characters for the specified character code.

Throws:
java.io.IOException

countEchoCharacters

int countEchoCharacters(char c)

getPrintableCharacters

java.lang.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 java.lang.String readLine(java.lang.String prompt)
                          throws java.io.IOException
Throws:
java.io.IOException

setDefaultPrompt

public void setDefaultPrompt(java.lang.String prompt)
The default prompt that will be issued.


getDefaultPrompt

public java.lang.String getDefaultPrompt()
The default prompt that will be issued.


readLine

public java.lang.String readLine(java.lang.String prompt,
                                 java.lang.Character mask)
                          throws java.io.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:
java.io.IOException

readLine

private java.lang.String readLine(java.io.InputStream in)
                           throws java.io.IOException
Throws:
java.io.IOException

readBinding

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

Throws:
java.io.IOException

moveHistory

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

Throws:
java.io.IOException

paste

public boolean paste()
              throws java.io.IOException
Paste the contents of the clipboard into the console buffer

Returns:
true if clipboard contents pasted
Throws:
java.io.IOException

killLine

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

Returns:
true if successful
Throws:
java.io.IOException

clearScreen

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

Throws:
java.io.IOException

complete

private final boolean complete()
                        throws java.io.IOException
Use the completors to modify the buffer with the appropriate completions.

Returns:
true if successful
Throws:
java.io.IOException

getCursorBuffer

public CursorBuffer getCursorBuffer()

printColumns

public void printColumns(java.util.Collection stuff)
                  throws java.io.IOException
Output the specified Collection in proper columns.

Parameters:
stuff - the stuff to print
Throws:
java.io.IOException

pad

private final void pad(java.lang.String toPad,
                       int len,
                       java.lang.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.

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 java.util.Collection getCompletors()
Returns an unmodifiable list of all the completors.


resetLine

final boolean resetLine()
                 throws java.io.IOException
Erase the current line.

Returns:
false if we failed (e.g., the buffer was empty)
Throws:
java.io.IOException

setCursorPosition

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

Throws:
java.io.IOException

setBuffer

private final void setBuffer(java.lang.String buffer)
                      throws java.io.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.
Throws:
java.io.IOException

redrawLine

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

Throws:
java.io.IOException

drawLine

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

Throws:
java.io.IOException

printNewline

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

Throws:
java.io.IOException

finishBuffer

final java.lang.String finishBuffer()
Clear the buffer and add its contents to the history.

Returns:
the former contents of the buffer.

putString

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

Throws:
java.io.IOException

printString

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

Throws:
java.io.IOException

putChar

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

Throws:
java.io.IOException

drawBuffer

private final void drawBuffer(int clear)
                       throws java.io.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
Throws:
java.io.IOException

drawBuffer

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

Throws:
java.io.IOException

clearAhead

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

Throws:
java.io.IOException

back

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

Throws:
java.io.IOException

beep

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

Throws:
java.io.IOException

printCharacter

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

Throws:
java.io.IOException

printCharacters

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

Throws:
java.io.IOException

printCharacters

private final void printCharacters(char c,
                                   int num)
                            throws java.io.IOException
Throws:
java.io.IOException

flushConsole

public final void flushConsole()
                        throws java.io.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:
java.io.IOException

backspaceAll

private final int backspaceAll()
                        throws java.io.IOException
Throws:
java.io.IOException

backspace

private final int backspace(int num)
                     throws java.io.IOException
Issue num backspaces.

Returns:
the number of characters backed up
Throws:
java.io.IOException

backspace

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

Returns:
true if successful
Throws:
java.io.IOException

moveToEnd

private final boolean moveToEnd()
                         throws java.io.IOException
Throws:
java.io.IOException

deleteCurrentCharacter

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

Throws:
java.io.IOException

previousWord

private final boolean previousWord()
                            throws java.io.IOException
Throws:
java.io.IOException

nextWord

private final boolean nextWord()
                        throws java.io.IOException
Throws:
java.io.IOException

deletePreviousWord

private final boolean deletePreviousWord()
                                  throws java.io.IOException
Throws:
java.io.IOException

moveCursor

private final int moveCursor(int num)
                      throws java.io.IOException
Move the cursor where characters.

Returns:
the number of spaces we moved
Throws:
java.io.IOException

debug

public static void debug(java.lang.String str)
debug.

Parameters:
str - the message to issue.

moveInternal

private final void moveInternal(int where)
                         throws java.io.IOException
Move the cursor where characters, withough checking the current buffer.

Parameters:
where - the number of characters to move to the right or left.
Throws:
java.io.IOException
See Also:
#where

readVirtualKey

public final int readVirtualKey()
                         throws java.io.IOException
Read a character from the console.

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

readCharacter

public final int readCharacter(char[] allowed)
                        throws java.io.IOException
Throws:
java.io.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(java.lang.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 java.lang.Character getEchoCharacter()
Returns the echo character.


consumeException

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


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

setUseHistory

public void setUseHistory(boolean useHistory)
Whether or not to add new commands to the history buffer.


getUseHistory

public boolean getUseHistory()
Whether or not to add new commands to the history buffer.