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
addToHistory
public static void addToHistory(String line)
Add a line to the in-memory history.
Supporting implementations:
- GNU-Readline
- Editline
- Getline
line
- The line to add to the history
cleanup
public static void cleanup()
Reset the readline library and with it, the terminal.
Supporting implementations:
clearHistory
public static void clearHistory()
Clear the history buffer.
Supporting implementations:
getCompleter
public static ReadlineCompleter getCompleter()
Query current completer function.
- Current ReadlineCompleter object
getEncoding
public static String getEncoding()
Query current encoding of fallback BufferedReader.
getHistory
public static void getHistory(Collection collection)
Get the history buffer in a supplied
Collection.
Supporting implementations:
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:
i
- the index of the entry to return
- 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:
- 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:
getThrowExceptionOnUnsupportedMethod
public static boolean getThrowExceptionOnUnsupportedMethod()
Query behavior in case an unsupported method is called.
getWordBreakCharacters
public static String getWordBreakCharacters()
Query word break characters.
Supporting implementations:
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:
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
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.
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:
line
- Simulated line from inputrc file
- boolean False in case of error
readHistoryFile
public static void readHistoryFile(String filename)
throws EOFException,
UnsupportedEncodingException
Reads a history file into memory
Supporting implementations:
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:
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
prompt
- Prompt to display
- 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).
prompt
- Prompt to displayaddToHist
- 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().)
- 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:
rlc
- An object implementing the ReadlineCompleter interface
setEncoding
public static void setEncoding(String encoding)
Set current encoding of fallback BufferedReader.
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.
flag
- configuration flag
setWordBreakCharacters
public static void setWordBreakCharacters(String wordBreakCharacters)
throws UnsupportedEncodingException
Set word break characters.
Supporting implementations:
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:
filename
- Name of history file to write