Readline (The Java-Readline Library)

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

Constructors
Constructor and Description

Readline()

Constructors
Constructor and Description
`Readline()`

Method Summary

Methods
Modifier and Type	Method and Description
`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
    
    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

Class Readline

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Readline

Method Detail

load

initReadline

readline

readline

addToHistory

getHistory

getHistorySize

clearHistory

getHistoryLine

readInitFile

parseAndBind

readHistoryFile

writeHistoryFile

setCompleter

getCompleter

cleanup

hasTerminal

getWordBreakCharacters

getLineBuffer

setWordBreakCharacters

setThrowExceptionOnUnsupportedMethod

getThrowExceptionOnUnsupportedMethod

setEncoding

getEncoding