                                     JLine

   (c) 2002, 2003, 2004, 2005 Marc Prud'hommeaux

     ----------------------------------------------------------------------

   JLine Manual

                Introduction

                License and Terms of Use

                Obtaining JLine

                Installation

                Supported Platforms

                Features

                             Command History

                             Tab completion

                             Line editing

                             Custom Keybindings

                             Character masking

                API

                             Reading a password from the console

                Frequently Asked Questions

                             Can I disable JLine if it isn't working on my
                             platform?

                             How do I customize the key bindings?

                             Can I use JLine as the default console input
                             stream for all applications?

                             Can I use JLine as the input handler for
                             BeanShell?

                             Can I use JLine as the input handler for jdb
                             (the java debugger)?

                             Is JLine 100% pure Java(TM)?

                             How do I make it so password characters are no
                             echoed to the screen?

                             Is JLine a full-featured curses implementation?

   Known Bugs

   Future enhancements

   Change Log

                                  JLine Manual

   Introduction

   License and Terms of Use

   Obtaining JLine

   Installation

   Supported Platforms

   Features

                Command History

                Tab completion

                Line editing

                Custom Keybindings

                Character masking

   API

                Reading a password from the console

   Frequently Asked Questions

                Can I disable JLine if it isn't working on my platform?

                How do I customize the key bindings?

                Can I use JLine as the default console input stream for all
                applications?

                Can I use JLine as the input handler for BeanShell?

                Can I use JLine as the input handler for jdb (the java
                debugger)?

                Is JLine 100% pure Java(TM)?

                How do I make it so password characters are no echoed to the
                screen?

                Is JLine a full-featured curses implementation?

   JLine is a Java library for handling console input. It is similar in
   functionality to BSD editline and GNU readline. People familiar with the
   readline/editline capabilities for modern shells (such as bash and tcsh)
   will find most of the command editing features of JLine to be familiar.

   JLine is distributed under the BSD license, meaning that you are
   completely free to redistribute, modify, or sell it with almost no
   restrictins. For more information on the BSD license, see
   http://www.opensource.org/licenses/bsd-license.php.

   For information on obtaining the software under another license, contact
   the copyright holder: mwp1@cornell.edu.

   JLine is hosted on SourceForge, and is located at http://jline.sf.net. The
   latest release can be downloaded from
   http://sourceforge.net/project/showfiles.php?group_id=64033. API
   documentation can be found in the javadoc directory.

   JLine has no library dependencies, aside from a JVM of version 1.2 or
   higher. To install JLine, download the jline.jar file, and either place it
   in the system-wide java extensions directory, or manually add it to your
   CLASSPATH. The extensions directory is dependent on your operating system.
   Some few examples are:
     o Macintosh OS X: /Library/Java/Extensions or
       /System/Library/Java/Extensions

     o Microsoft Windows: JAVAHOME\jre\lib\ext (example:
       C:\j2sdk1.4.1_03\jre\lib\ext)

     o UNIX Systems: JAVAHOME/jre/lib/ext (example:
       /usr/local/java/jre/lib/ext)

   JLine is not 100% pure Java. On Windows, it relies on a .dll file to
   initialize the terminal to be able to accept unbuffered input. However, no
   installation is necessary for this: when initialized, JLine will
   dynamically extract the DLL to a temporary directory and load it. For more
   details, see the documentation for the jline.WindowsTerminal class.

   On UNIX systems (including Macintosh OS X), JLine will execute the stty
   command to initialize the terminal to allow unbuffered input. For more
   details, see the documentation for the jline.UnixTerminal class.

   For both Windows and UNIX systems, JLine will fail to initialize if it is
   run inside a strict security manager that does not allow the loading of
   libraries, writing to the file system, or executing external programs.
   However, for most console applications, this is usually not the case.

   JLine should work on any Windows system, or any minimally compliant POSIX
   system (includling Linux and Macintosh OS X).

   The platforms on which JLine has been confirmed to work are:
     o Microsoft Windows XP

     o RedHat Linux 9.0

     o Debian Linux 3.0

     o Macintosh OS X 10.3

   Please report successes or failures to the author: mwp1@cornell.edu.

   Command History

   Tab completion

   Line editing

   Custom Keybindings

   Character masking

   You can create your own keybindings by creating a
   HOME/.jlinebindings.properties" file. You can override the location of
   this file with the "jline.keybindings" system property.

   The default keybindings are as follows:

 # Keybinding mapping for JLine. The format is:
 #    [key code]: [logical operation]

 # CTRL-B: move to the previous character
 2: PREV_CHAR

 # CTRL-G: move to the previous word
 7: PREV_WORD

 # CTRL-F: move to the next character
 6: NEXT_CHAR

 # CTRL-A: move to the beginning of the line
 1: MOVE_TO_BEG

 # CTRL-D: close out the input stream
 4: EXIT

 # CTRL-E: move the cursor to the end of the line
 5: MOVE_TO_END

 # CTRL-H: delete the previous character
 8: DELETE_PREV_CHAR

 # TAB, CTRL-I: signal that console completion should be attempted
 9: COMPLETE

 # CTRL-J, CTRL-M: newline
 10: NEWLINE

 # CTRL-K: erase the current line
 11: KILL_LINE

 # ENTER: newline
 13: NEWLINE

 # CTRL-L: clear screem
 12: CLEAR_SCREEN

 # CTRL-N: scroll to the next element in the history buffer
 14: NEXT_HISTORY

 # CTRL-P: scroll to the previous element in the history buffer
 16: PREV_HISTORY

 # CTRL-R: redraw the current line
 18: REDISPLAY

 # CTRL-U: delete all the characters before the cursor position
 21: KILL_LINE_PREV

 # CTRL-V: paste the contents of the clipboard (useful for Windows terminal)
 22: PASTE

 # CTRL-W: delete the word directly before the cursor
 23: DELETE_PREV_WORD

 # CTRL-?: delete the previous character
 127: DELETE_PREV_CHAR

                                        

   Reading a password from the console

   This section discusses some common usages of the JLine API. For in-depth
   usage of the JLine API, see the javadoc.

   A common task that console applications need to do is read in a password.
   While it is standard for software to not echo password strings as they are
   typed, the Java core APIs surprisingly do not provide any means to do
   this.

   JLine can read a password with the following code:

 String password = new jline.ConsoleReader().readLine(new Character('*'));
                                        

   This will replace every character types on the console with a star
   character.

   Alternately, you can have it not echo password character at all:

 String password = new jline.ConsoleReader().readLine(new Character(0));
                                        

   The jline-demo.jar file contains a sample application that reads the
   password. To run the sample, execute:

 java -cp jline-demo.jar jline.example.PasswordReader "*"
                                        

   Can I disable JLine if it isn't working on my platform?

   How do I customize the key bindings?

   Can I use JLine as the default console input stream for all applications?

   Can I use JLine as the input handler for BeanShell?

   Can I use JLine as the input handler for jdb (the java debugger)?

   Is JLine 100% pure Java(TM)?

   How do I make it so password characters are no echoed to the screen?

   Is JLine a full-featured curses implementation?

   You can disable JLine by setting the System property "jline.terminal" to
   "jline.UnsupportedTerminal". For example:

 java -Djline.terminal=jline.UnsupportedTerminal jline.example.Example simple
                                

   You can create your own keybindings by creating a
   HOME/.jlinebindings.properties" file. You can override the location of
   this file with the "jline.keybindings" system property. To examine the
   format to use, see the src/jline/keybindings.properties file in the source
   distribution.

   No, but you can use the jline.ConsoleRunner application to set up the
   system input stream and continue on the launch another program. For
   example, to use JLine as the input handler for the popular BeanShell
   console application, you can run:

 java jline.ConsoleRunner bsh.Interpreter
                                

   Yes. Try running:

 java jline.ConsoleRunner bsh.Interpreter
                                

   Yes. Try running:

 java jline.ConsoleRunner com.sun.tools.example.debug.tty.TTY args
                                

   No: JLine uses a couple small native methods in the Windows platform. On
   Unix, it is technically pure java, but relies on the execution of external
   (non-java) programs. See the installation section for more details.

   See ???.

   No: JLine has no ability to position the cursor on the console. It might
   someday evolve into a plausible Java curses implementation.

     o Clearing the screen (CTRL-L) doesn't currently work on Windows.

     o Add localization for all strings.

     o Create a BNFCompletor that can handle any BNF.

     o Add support for arrow keys on Windows.

     o Fixed problem with the 0.9.0 distribution that failed to include the
       Windows jline.dll in the jline.jar, rendering it inoperable on
       Windows.

     o Implemented proper interception or arrow keys on Windows, meaning that
       history can now be navigated with the UP and DOWN keys, and line
       editing can take place with the LEFT and RIGHT arrow keys.

     o Changed license from GPL to BSD.

     o Made "CTRL-L" map to clearing the screen.

     o Fixed accidental dependency on JVM 1.4.

     o Windows support using a native .dll

     o A new ClassNameCompletor

     o Many doc improvements

     o Many bugfixes

     o Better release system

     o Automatically set terminal property by issuing stty on UNIX systems

     o Additional tab-completion handlers

     o Tested on Debian Linux and Mac OS 10.2

     o Example includes dictionary, filename, and simple completion

     o Initial release
