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 $
    • Constructor Summary

      Constructors 
      Constructor Description
      Readline()  
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method 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