The Java-Readline Library, Version 0.7.0

org.gnu.readline
Class Readline

java.lang.Object
  |
  +--org.gnu.readline.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.18 $
Author:
$Author: Bablokb $

Constructor Summary
Readline()
           
 
Method Summary
static void cleanup()
          Reset the readline library and with it, the terminal.
static ReadlineCompleter getCompleter()
          Query current completer function.
static java.lang.String getLineBuffer()
          Query the current line buffer.
static boolean getThrowExceptionOnUnsupportedMethod()
          Query behavior in case an unsupported method is called.
static java.lang.String getWordBreakCharacters()
          Query word break characters.
static void initReadline(java.lang.String applicationName)
          Initialize the GNU-Readline library.
static void load(ReadlineLibrary lib)
          Load an implementing backing library.
static boolean parseAndBind(java.lang.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(java.lang.String filename)
          Reads a history file into memory
static void readInitFile(java.lang.String filename)
          Read keybindings and variable assignments from a file.
static java.lang.String readline(java.lang.String prompt)
          Display a prompt on standard output and read a string from standard input.
static void setCompleter(ReadlineCompleter rlc)
          Set your completer implementation.
static void setThrowExceptionOnUnsupportedMethod(boolean flag)
          Configure behavior in case an unsupported method is called.
static void setWordBreakCharacters(java.lang.String wordBreakCharacters)
          Set word break characters.
static void writeHistoryFile(java.lang.String filename)
          Writes a history file to disc
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Readline

public Readline()
Method Detail

load

public static final void load(ReadlineLibrary lib)
                       throws java.lang.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
Throws:
java.lang.UnsatisfiedLinkError - if the shared library could not be found. Add it to your LD_LIBRARY_PATH.
See Also:
ReadlineLibrary

initReadline

public static void initReadline(java.lang.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.
Parameters:
applicationName - Name of application in initialization file

readline

public static java.lang.String readline(java.lang.String prompt)
                                 throws java.io.EOFException,
                                        java.io.IOException,
                                        java.io.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
Returns:
The string the user entered or 'null' if there was no input.
Throws:
java.io.EOFException - on end-of-file, i.e. CTRL-d input.

readInitFile

public static void readInitFile(java.lang.String filename)
                         throws java.io.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.
Parameters:
filename - Name of file to read bindings from
Returns:
void

parseAndBind

public static boolean parseAndBind(java.lang.String line)
Parse argument string as if it had been read from `inputrc' file and perform key bindings and variable assignments found.
Parameters:
line - Simulated line from inputrc file
Returns:
boolean False in case of error

readHistoryFile

public static void readHistoryFile(java.lang.String filename)
                            throws java.io.EOFException,
                                   java.io.UnsupportedEncodingException
Reads a history file into memory
Parameters:
filename - Name of history file to read

writeHistoryFile

public static void writeHistoryFile(java.lang.String filename)
                             throws java.io.EOFException,
                                    java.io.UnsupportedEncodingException
Writes a history file to disc
Parameters:
filename - Name of history file to write

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.
Parameters:
rlc - An object implementing the ReadlineCompleter interface

getCompleter

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

cleanup

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

getWordBreakCharacters

public static java.lang.String getWordBreakCharacters()
Query word break characters.

getLineBuffer

public static java.lang.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.

setWordBreakCharacters

public static void setWordBreakCharacters(java.lang.String wordBreakCharacters)
                                   throws java.io.UnsupportedEncodingException
Set word break characters.
Parameters:
wordBreakCharacters - A string of word break characters

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

getThrowExceptionOnUnsupportedMethod

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

The Java-Readline Library, Version 0.7.0

Released under the LGPL, (c) Bernhard Bablok 1998-2001
Homepage: http://www.bablokb.de/java/readline.html