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.27 $

Author:

$Author: bablokb $

Constructor Summary

Readline()

Method Summary

static void	addToHistory(java.lang.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 java.lang.String	getEncoding() Query current encoding of fallback BufferedReader.
static void	getHistory(java.util.Collection collection) Get the history buffer in a supplied Collection.
static java.lang.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 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 boolean	hasTerminal() Return if we have a terminal.
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 java.lang.String	readline(java.lang.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(java.lang.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(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.

Supporting implementations:

• GNU-Readline
• Editline
• Getline

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). 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.

Throws:

java.io.EOFException - on end-of-file, i.e. CTRL-d input.

java.io.IOException

java.io.UnsupportedEncodingException

See Also:

readline(String,boolean), #addHistory()

readline

public static java.lang.String readline(java.lang.String prompt,
                                        boolean addToHist)
                                 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

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.

Throws:

java.io.EOFException - on end-of-file, i.e. CTRL-d input.

java.io.IOException

java.io.UnsupportedEncodingException

See Also:

readline(String), #addHistory()

addToHistory

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

Throws:

UnsupportOperationException - if underlying library doesn't support a history

getHistory

public static void getHistory(java.util.Collection collection)

Get the history buffer in a supplied Collection.

Supporting implementations:

• GNU-Readline
• Editline

Parameters:

collection - where to store the history

Throws:

UnsupportOperationException - if underlying library doesn't support a history

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

clearHistory

public static void clearHistory()

Clear the history buffer.

Supporting implementations:

• GNU-Readline
• Editline

getHistoryLine

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

Throws:

java.lang.ArrayIndexOutOfBoundsException - index out of range

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.

Supporting implementations:

• GNU-Readline

Parameters:

filename - Name of file to read bindings from

Returns:

void

Throws:

java.io.IOException

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.

Supporting implementations:

• GNU-Readline

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

Supporting implementations:

• GNU-Readline
• Editline

Parameters:

filename - Name of history file to read

Throws:

java.io.EOFException

java.io.UnsupportedEncodingException

writeHistoryFile

public static void writeHistoryFile(java.lang.String filename)
                             throws java.io.EOFException,
                                    java.io.UnsupportedEncodingException

Writes a history file to disc

Supporting implementations:

• GNU-Readline
• Editline

Parameters:

filename - Name of history file to write

Throws:

java.io.EOFException

java.io.UnsupportedEncodingException

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

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.

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

getWordBreakCharacters

public static java.lang.String getWordBreakCharacters()

Query word break characters.

Supporting implementations:

• GNU-Readline
• Editline

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.

Supporting implementations:

• GNU-Readline
• Editline

setWordBreakCharacters

public static void setWordBreakCharacters(java.lang.String wordBreakCharacters)
                                   throws java.io.UnsupportedEncodingException

Set word break characters.

Supporting implementations:

• GNU-Readline
• Editline

Parameters:

wordBreakCharacters - A string of word break characters

Throws:

java.io.UnsupportedEncodingException

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

setEncoding

public static void setEncoding(java.lang.String encoding)

Set current encoding of fallback BufferedReader.

Parameters:

encoding - encoding to use

getEncoding

public static java.lang.String getEncoding()

Query current encoding of fallback BufferedReader.

Returns:

current encoding