dorkbox/Console
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Updated readme to reflect name change + ANSI functionality

Browse Source
This commit is contained in:
nathan 2016-05-30 11:22:26 +02:00
parent d2a33b5a66
commit 71d7364008
1 changed files with 57 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

72
README.md
View File

@ -1,30 +1,64 @@
InputConsole
============
Console
=======
Unbuffered input on the console for java applications.
Unbuffered input and ANSI output support in consoles for linux, mac, windows. Java 6+
This small library is very similar to what JLine provides, however it does 4 things very differently:
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. 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
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 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.
- 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
```
<dependency>
<groupId>com.dorkbox</groupId>
<artifactId>InputConsole</artifactId>
<artifactId>Console</artifactId>
<version>2.9</version>
</dependency>
```
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/