JLine


Table of Contents

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™?
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

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.

License and Terms of Use

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.

Obtaining JLine

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.

Installation

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:

  • Macintosh OS X: /Library/Java/Extensions or /System/Library/Java/Extensions

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

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

Supported Platforms

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:

  • Microsoft Windows XP

  • RedHat Linux 9.0

  • Debian Linux 3.0

  • Macintosh OS X 10.3

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

Features

Command History

Tab completion

Line editing

Custom Keybindings

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

					

Character masking

API

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

Reading a password from the console

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 "*"
					

Frequently Asked Questions

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

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
				

How do I customize the key bindings?

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.

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

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
				

Can I use JLine as the input handler for BeanShell?

Yes. Try running:

java jline.ConsoleRunner bsh.Interpreter
				

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

Yes. Try running:

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

Is JLine 100% pure Java™?

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.

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

See ???.

Is JLine a full-featured curses implementation?

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

Known Bugs

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

Future enhancements

  • Add localization for all strings.

  • Create a BNFCompletor that can handle any BNF.

Change Log

0.9.5 2006-03-08

  • Fixed problem with "stty" on Solaris, which doesn't understand "stty size" to query the terminal size. It now uses "stty -a", which supposedly outputs a POSIX standard format.

  • Support HOME and END keys, thanks to a patch by Dale Kemp.

0.9.1 2005-01-29

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

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

0.9.0 2005-01-23

  • Changed license from GPL to BSD.

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

0.8.1 2003-11-18

  • Fixed accidental dependency on JVM 1.4.

0.8.0 2003-11-17

  • Windows support using a native .dll

  • A new ClassNameCompletor

  • Many doc improvements

0.6.0 2003-07-08

  • Many bugfixes

  • Better release system

  • Automatically set terminal property by issuing stty on UNIX systems

  • Additional tab-completion handlers

  • Tested on Debian Linux and Mac OS 10.2

  • Example includes dictionary, filename, and simple completion

0.3.0 2002-10-05

  • Initial release