JLine Documentation

JLine is a Java library for advanced console input handling, providing features similar to BSD editline and GNU readline. Key capabilities include:

• Editing: Rich command-line editing, multi-line editing, and advanced movement (cut/paste, word movement).
• Input/Output: Customizable tab completion, syntax highlighting, and Unicode support.
• Management: History management with search and flexible keyboard mapping.
• Environment: Platform-independent implementation.

The JLine Style module provides a framework for adding colors and formatting to command-line applications. It is built around three core components:

1. Style Expressions: Concise, string-based definitions of styles.
2. Style Resolver: A component that converts Style Expressions into AttributedStyle objects.
3. Styler: A high-level component that combines Style Expressions with text to apply styling.

This module allows you to move away from manual ANSI escape code management and toward a more declarative styling system.

Thread Safety

Most JLine classes are not thread-safe. To avoid undefined behavior:

• Call Terminal methods from a single dedicated thread.
• Call LineReader methods from a single dedicated thread.
• History can be accessed concurrently only if you implement your own synchronization.

API Stability

JLine follows semantic versioning:

• Major: May include breaking changes.
• Minor: Backward-compatible new functionality.
• Patch: Backward-compatible bug fixes.
• Note: Methods marked @Deprecated may be removed in future major versions.

The Highlighter interface allows you to apply visual styles to the text as the user types.

Key Classes:

• Highlighter: The main interface.
• DefaultHighlighter: The standard implementation.

JLine's API is built around a hierarchy of components that manage the lifecycle of a command-line interaction:

1. Terminal: The foundation. It handles the raw connection to the terminal device, reading/writing bytes, and managing terminal attributes like raw mode or window size.
2. LineReader: The high-level interaction layer. It uses a Terminal to provide an interactive editing experience, managing history, completion, and syntax highlighting.
3. Completer, History, Parser, and Highlighter: These are specialized components used by the LineReader to enhance the user experience (e.g., providing tab completion, remembering previous commands, or coloring text).

To build a CLI, you typically start by creating a Terminal via TerminalBuilder and then creating a LineReader via LineReaderBuilder using that terminal.

JLine supports syntax highlighting via the Highlighter interface. To use it, you must implement the highlight method, which is called during input. The method receives the current LineReader, the input buffer, and a list of candidates. You then add highlighted versions of the input to this list.

Basic Highlighting

The simplest implementation involves applying a single style to the entire input buffer.

Keyword Highlighting

You can use regular expressions within your highlight implementation to identify specific keywords (e.g., SQL commands) and apply distinct styles like bold or specific colors to them.

Full Syntax Highlighting

For complex languages, your implementation can use multiple regex patterns to differentiate between keywords, strings, numbers, and comments, applying unique styles to each category.

The REPL provides a variable system for storing and manipulating data. You can reference variables using the $ prefix.

Variable Expansion

• Simple expansion: prnt $user
• Object notation: prnt ${user}.name
• JSON/Groovy notation: Command parameters can be passed directly using JSON or Groovy object syntax.

Variable Naming Conventions

• Temporary variables: Names starting with an underscore _ (e.g., _args, _buffer) are temporary and deleted automatically at the end of the REPL loop.
• Persistent variables: Names in CAMEL_CASE are not deleted when using wildcard deletions like del *.