jline
Class ConsoleReader

java.lang.Object
  extended byjline.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
static String CR
           
static SortedMap KEYMAP_NAMES
          Map that contains the operation name to keymay operation mapping.
 
Fields inherited from interface jline.ConsoleOperations
ADD, BACKSPACE, CHANGE_CASE, CHANGE_META, CLEAR_LINE, CLEAR_SCREEN, COMPLETE, 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.
 boolean backspace()
          Issue a backspace.
 void beep()
          Issue an audible keyboard bell, if getBellEnabled() return true.
 boolean clearScreen()
          Clear the screen by issuing the ANSI "clear screen" code.
static void debug(String str)
          debug.
 boolean delete()
          Issue a delete.
 void drawLine()
          Output put the prompt + the current buffer
 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()
           
 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.
 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.
 boolean killLine()
          Kill the buffer ahead of the current cursor position.
 int moveCursor(int num)
          Move the cursor where characters.
 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.
 boolean replace(int num, String replacement)
           
 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 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.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CR

public static final String CR

KEYMAP_NAMES

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

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

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 -

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.

readLine

public String readLine(String prompt)
                throws IOException
Throws:
IOException

setDefaultPrompt

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


getDefaultPrompt

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


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.


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

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

moveCursor

public final int moveCursor(int num)
                     throws IOException
Move the cursor where characters.

Returns:
the number of spaces we moved
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

replace

public final boolean replace(int num,
                             String replacement)

delete

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

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


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.


setUsePagination

public void setUsePagination(boolean usePagination)
Whether to use pagination when the number of rows of candidates exceeds the height of the temrinal.


getUsePagination

public boolean getUsePagination()
Whether to use pagination when the number of rows of candidates exceeds the height of the temrinal.



Copyright 2002-2008. All Rights Reserved.