org.gnu.readline

Class Readline


public class Readline
extends java.lang.Object

This class implements basic functionality of the GNU-readline interface. It uses native method calls if available, otherwise it defaults to normal I/O using a BufferedReader.

A typical implementation could look like:

try {
Readline.load(ReadlineLibrary.GnuReadline);
}
catch (UnsatisfiedLinkError ignore_me) {
System.err.println("couldn't load readline lib. Using simple stdin.");
}
Readline.initReadline("myapp");
Runtime.getRuntime()                       // if your version supports
.addShutdownHook(new Thread() {          // addShutdownHook (since 1.3)
public void run() {
Readline.cleanup();
}
});
while (true) {
try {
line = Readline.readline("myprompt> ");
if (line == null)
System.out.println("no input");
else
processLine();
} 
catch (EOFException e) {
break;
} 
catch (Exception e) {
doSomething();
}
}
Readline.cleanup();  // see note above about addShutdownHook
Version:
$Revision: 1.27 $
Author:
$Author: bablokb $

Method Summary

static void
addToHistory(String line)
Add a line to the in-memory history.
static void
cleanup()
Reset the readline library and with it, the terminal.
static void
clearHistory()
Clear the history buffer.
static ReadlineCompleter
getCompleter()
Query current completer function.
static String
getEncoding()
Query current encoding of fallback BufferedReader.
static void
getHistory(Collection collection)
Get the history buffer in a supplied Collection.
static String
getHistoryLine(int i)
Get the specified entry from the history buffer.
static int
getHistorySize()
Get the size, in elements (lines), of the history buffer.
static String
getLineBuffer()
Query the current line buffer.
static boolean
getThrowExceptionOnUnsupportedMethod()
Query behavior in case an unsupported method is called.
static String
getWordBreakCharacters()
Query word break characters.
static boolean
hasTerminal()
Return if we have a terminal.
static void
initReadline(String applicationName)
Initialize the GNU-Readline library.
static void
load(ReadlineLibrary lib)
Load an implementing backing library.
static boolean
parseAndBind(String line)
Parse argument string as if it had been read from `inputrc' file and perform key bindings and variable assignments found.
static void
readHistoryFile(String filename)
Reads a history file into memory

Supporting implementations:

  • GNU-Readline
  • Editline
static void
readInitFile(String filename)
Read keybindings and variable assignments from a file.
static String
readline(String prompt)
Display a prompt on standard output and read a string from standard input.
static String
readline(String prompt, boolean addToHist)
Display a prompt on standard output and read a string from standard input.
static void
setCompleter(ReadlineCompleter rlc)
Set your completer implementation.
static void
setEncoding(String encoding)
Set current encoding of fallback BufferedReader.
static void
setThrowExceptionOnUnsupportedMethod(boolean flag)
Configure behavior in case an unsupported method is called.
static void
setWordBreakCharacters(String wordBreakCharacters)
Set word break characters.
static void
writeHistoryFile(String filename)
Writes a history file to disc

Supporting implementations:

  • GNU-Readline
  • Editline

Method Details

addToHistory

public static void addToHistory(String line)
Add a line to the in-memory history.

Supporting implementations:

  • GNU-Readline
  • Editline
  • Getline
Parameters:
line - The line to add to the history

cleanup

public static void cleanup()
Reset the readline library and with it, the terminal.

Supporting implementations:

  • GNU-Readline
  • Editline

clearHistory

public static void clearHistory()
Clear the history buffer.

Supporting implementations:

  • GNU-Readline
  • Editline

getCompleter

public static ReadlineCompleter getCompleter()
Query current completer function.
Returns:
Current ReadlineCompleter object

getEncoding

public static String getEncoding()
Query current encoding of fallback BufferedReader.
Returns:
current encoding

getHistory

public static void getHistory(Collection collection)
Get the history buffer in a supplied Collection.

Supporting implementations:

  • GNU-Readline
  • Editline
Parameters:
collection - where to store the history

getHistoryLine

public static String getHistoryLine(int i)
Get the specified entry from the history buffer. History buffer entries are numbered from 0 through (getHistorySize() - 1), with the oldest entry at index 0.

Supporting implementations:

  • GNU-Readline
  • Editline
Parameters:
i - the index of the entry to return
Returns:
the line at the specified index in the history buffer

getHistorySize

public static int getHistorySize()
Get the size, in elements (lines), of the history buffer.

Supporting implementations:

  • GNU-Readline
  • Editline
Returns:
the number of lines in the history buffer

getLineBuffer

public static String getLineBuffer()
Query the current line buffer. This returns the current content of the internal line buffer. You might need this in a ReadlineCompleter implementation to access the full text given so far.

Supporting implementations:

  • GNU-Readline
  • Editline

getThrowExceptionOnUnsupportedMethod

public static boolean getThrowExceptionOnUnsupportedMethod()
Query behavior in case an unsupported method is called.
Returns:
configuration flag

getWordBreakCharacters

public static String getWordBreakCharacters()
Query word break characters.

Supporting implementations:

  • GNU-Readline
  • Editline

hasTerminal

public static boolean hasTerminal()
Return if we have a terminal. This requires, that any of the native libraries have been loaded yet (so call Readline.load(ReadlineLibrary)()) first, otherwise this will always return true.

Supporting implementations:

  • GNU-Readline
  • Editline

initReadline

public static void initReadline(String applicationName)
Initialize the GNU-Readline library. This will also set the application name, which can be used in the initialization files of Readline (usually /etc/inputrc and ~/.inputrc) to define application specific keys. See the file ReadlineTest.java int the test subdir of the distribution for an example.

Supporting implementations:

  • GNU-Readline
  • Editline
  • Getline
Parameters:
applicationName - Name of application in initialization file

load

public static final void load(ReadlineLibrary lib)
            throws UnsatisfiedLinkError
Load an implementing backing library. This method might throw an UnsatisfiedLinkError in case the native libary is not found in the library path. If you want to have portable program, just catch and ignore that error. JavaReadline will then just use the pure Java fallback solution.
Parameters:
lib - An object (constant) of type ReadlineLibrary

parseAndBind

public static boolean parseAndBind(String line)
Parse argument string as if it had been read from `inputrc' file and perform key bindings and variable assignments found.

Supporting implementations:

  • GNU-Readline
Parameters:
line - Simulated line from inputrc file
Returns:
boolean False in case of error

readHistoryFile

public static void readHistoryFile(String filename)
            throws EOFException,
                   UnsupportedEncodingException
Reads a history file into memory

Supporting implementations:

  • GNU-Readline
  • Editline
Parameters:
filename - Name of history file to read

readInitFile

public static void readInitFile(String filename)
            throws IOException
Read keybindings and variable assignments from a file. This method is a wrapper to rl_read_init_file(char *filename). Throws IOException if something goes wrong.

Supporting implementations:

  • GNU-Readline
Parameters:
filename - Name of file to read bindings from

readline

public static String readline(String prompt)
            throws EOFException,
                   IOException,
                   UnsupportedEncodingException
Display a prompt on standard output and read a string from standard input. This method returns 'null', if there has been an empty input (user pressed just [RETURN]) and throws an EOFException on end-of-file (C-d). This versino of readline() automatically adds the line to the in-memory history; use the other version of readline() if you want explicit control over that feature.

Supporting implementations:

  • GNU-Readline
  • Editline
  • Getline
  • PureJava
Parameters:
prompt - Prompt to display
Returns:
The string the user entered or 'null' if there was no input.

readline

public static String readline(String prompt,
                              boolean addToHist)
            throws EOFException,
                   IOException,
                   UnsupportedEncodingException
Display a prompt on standard output and read a string from standard input. This method returns 'null', if there has been an empty input (user pressed just [RETURN]) and throws an EOFException on end-of-file (C-d).
Parameters:
prompt - Prompt to display
addToHist - true to add the line to the history automatically; false to refrain from adding the line to the history. (You can manually add the line to the history by calling addHistory().)
Returns:
The string the user entered or 'null' if there was no input.

setCompleter

public static void setCompleter(ReadlineCompleter rlc)
Set your completer implementation. Setting this to null will result in the default behaviour of readline which is filename completion.

Supporting implementations:

  • GNU-Readline
  • Editline
Parameters:
rlc - An object implementing the ReadlineCompleter interface

setEncoding

public static void setEncoding(String encoding)
Set current encoding of fallback BufferedReader.
Parameters:
encoding - encoding to use

setThrowExceptionOnUnsupportedMethod

public static void setThrowExceptionOnUnsupportedMethod(boolean flag)
Configure behavior in case an unsupported method is called. If argument is true, unsupported methods throw an UnsupportedOperationException.
Parameters:
flag - configuration flag

setWordBreakCharacters

public static void setWordBreakCharacters(String wordBreakCharacters)
            throws UnsupportedEncodingException
Set word break characters.

Supporting implementations:

  • GNU-Readline
  • Editline
Parameters:
wordBreakCharacters - A string of word break characters

writeHistoryFile

public static void writeHistoryFile(String filename)
            throws EOFException,
                   UnsupportedEncodingException
Writes a history file to disc

Supporting implementations:

  • GNU-Readline
  • Editline
Parameters:
filename - Name of history file to write

Released under the LGPL, (c) Bernhard Bablok, Henner Zeller 1998-2002
Homepage:
http://java-readline.sourceforge.net/