diff --git a/README.md b/README.md index 7a50187..d7edf8e 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,64 @@ -InputConsole -============ +Console +======= -Unbuffered input on the console for java applications. - -This small library is very similar to what JLine provides, however it does 4 things very differently: - -1. Only provides unbuffered input. - - Backspace functionality for line input is preserved. - - Ctrl-C (SIGINT) is also preserved in windows -2. Uses native calls via JNA (instead of shell execution) for linux & mac terminal configuration -3. Supports unsupported terminals (for example, while in an IDE ), `in.read()` will still return (a line is split into chars, then fed to consumer). The enter key must still be pressed. -4. Multi-threaded, intelligent buffering of command input for simultaneous input readers on different threads - - -- This is for cross-platform use, specifically - linux 32/64, mac 32/64, and windows 32/64. Java 6+ -- ANSI output to console is also supported, and is required for backspace functionality to work if echo is enabled. +Unbuffered input and ANSI output support in consoles for linux, mac, windows. Java 6+ +This library is a optimized combination of [JLine](https://github.com/jline/jline2) and [JAnsi](https://github.com/fusesource/jansi). While it is very similar in functionality to what these libraries provide, there are several things that are significantly different. + 1. JNA *direct-mapping* instead of custom JNI/shell execution which is [slightly slower than JNI](https://github.com/java-native-access/jna/blob/master/www/DirectMapping.md) but significantly easier to read, modify, debug, and provide support for non-intel architectures. + 1. Complete implementation of common [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code) + 1. Automatically hooks into `System.err/out` for seamless integration in Java environments + 1. Automatically detects when an `IDE` is in use (and prevents issues with console corruption) + 1. Provides buffered and unbuffered input for windows/linux/mac + 1. Backspace functionality for line input is preserved (if ANSI is enabled). + 1. Controls `ECHO` on/off in the console + 1. Controls `Ctrl-C` (SIGINT) on/off in the console + 1. Supports unsupported terminals (for example, while in an IDE ), `in.read()` will still return (a line is split into chars, then fed to consumer) but the enter key must still be pressed. + 1. Multi-threaded, intelligent buffering of command input for simultaneous input readers on different threads + + +- This is for cross-platform use, specifically - linux arm/32/64, mac 32/64, and windows 32/64. Java 6+ + + ``` -Note: If you use the attached JNA/JAnsi libraries, you **MUST** load the respective - native libraries yourself, especially with JNA (as the loading logic has - been removed from the jar) +Customization parameters: +Console.ENABLE_ANSI (type boolean, default value 'true') + - If true, allows an ANSI output stream to be created on System.out/err, otherwise it will provide an ANSI aware PrintStream which strips out the ANSI escape sequences. + + +Console.FORCE_ENABLE_ANSI (type boolean, default value 'false') + - If true, then we always force the raw ANSI output stream to be enabled (even if the output stream is not aware of ANSI commands). + This can be used to obtain the raw ANSI escape codes for other color aware programs (ie: less -r) + + +Console.ENABLE_ECHO (type boolean, default value 'true') + - Enables or disables character echo to stdout in the console, should call Console.setEchoEnabled(boolean) after initialization. + + +Console.ENABLE_INTERRUPT (type boolean, default value 'false') + - Enables or disables CTRL-C behavior in the console, should call Console.setInterruptEnabled(boolean) after initialization. + + +Console.ENABLE_BACKSPACE (type boolean, default value 'true') + - Enables the backspace key to delete characters in the line buffer and (if ANSI is enabled) from the screen. + + + +Console.INPUT_CONSOLE_TYPE (type String, default value 'AUTO') + - Used to determine what console to use/hook when AUTO is not correctly working. + Valid options are: + - AUTO - automatically determine which OS/console type to use + - UNIX - try to control a UNIX console + - WINDOWS - try to control a WINDOWS console + - NONE - do not try to control anything, only line input is supported + ``` + + + ``` Note: This project was inspired (and some parts heavily modified) by the excellent - JLine library, and includes utility classes/methods from a variety of sources. + JLine and JAnsi libraries. Many thanks to their hard work. ``` @@ -36,14 +70,14 @@ This project is **kept in sync** with the utilities library, so "jar hell" is no ``` com.dorkbox - InputConsole + Console 2.9 ``` Or if you don't want to use Maven, you can access the files directly here: -https://oss.sonatype.org/content/repositories/releases/com/dorkbox/InputConsole/ -https://oss.sonatype.org/content/repositories/releases/com/dorkbox/InputConsole-Dorkbox-Util/ +https://oss.sonatype.org/content/repositories/releases/com/dorkbox/Console/ +https://oss.sonatype.org/content/repositories/releases/com/dorkbox/Console-Dorkbox-Util/ https://oss.sonatype.org/content/repositories/releases/com/dorkbox/ObjectPool/