Skip to content

Commit 35e57dc

Browse files
gnodetgnodet
committed
Improve docs
1 parent 749ccd5 commit 35e57dc

File tree

7 files changed

+619
-93
lines changed

7 files changed

+619
-93
lines changed

‎jline-docs/docs/architecture.md

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
---
2+
sidebar_position: 2
3+
---
4+
5+
# JLine Architecture
6+
7+
This page provides a high-level overview of JLine's architecture and how its components interact with each other.
8+
9+
## Component Overview
10+
11+
JLine is organized into several core components that work together to provide a complete terminal handling and line editing solution:
12+
13+
```
14+
┌─────────────────────────────────────────────────────────────────┐
15+
│ JLine Architecture │
16+
└─────────────────────────────────────────────────────────────────┘
17+
│
18+
▼
19+
┌─────────────────────────────────────────────────────────────────┐
20+
│ Terminal │
21+
│ │
22+
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────┐ │
23+
│ │ Jansi │ │ JNA │ │ FFM │ │ Exec │ │
24+
│ │ Provider │ │ Provider │ │ Provider │ │ Provider│ │
25+
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────┘ │
26+
└─────────────────────────────────────────────────────────────────┘
27+
│
28+
▼
29+
┌─────────────────────────────────────────────────────────────────┐
30+
│ LineReader │
31+
│ │
32+
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────┐ │
33+
│ │ Parser │ │ Completer │ │ History │ │ Widgets │ │
34+
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────┘ │
35+
└─────────────────────────────────────────────────────────────────┘
36+
│
37+
▼
38+
┌─────────────────────────────────────────────────────────────────┐
39+
│ Higher-Level APIs │
40+
│ │
41+
│ ┌─────────────┐ ┌─────────────┐ ┌────────────┐ ┌──────────┐ │
42+
│ │ Style │ │ Builtins │ │ Console │ │Console UI│ │
43+
│ └─────────────┘ └─────────────┘ └────────────┘ └──────────┘ │
44+
└─────────────────────────────────────────────────────────────────┘
45+
```
46+
47+
## Core Components
48+
49+
### Terminal
50+
51+
The `Terminal` component is the foundation of JLine. It provides:
52+
53+
- Access to the underlying terminal device
54+
- Raw mode for character-by-character input
55+
- ANSI escape sequence handling
56+
- Terminal size information
57+
- Signal handling (e.g., window resize, Ctrl+C)
58+
59+
The Terminal layer uses different providers (Jansi, JNA, FFM, etc.) to interact with the native terminal capabilities on different platforms.
60+
61+
### LineReader
62+
63+
The `LineReader` builds on top of the Terminal to provide:
64+
65+
- Line editing capabilities
66+
- History management
67+
- Tab completion
68+
- Key binding
69+
- Widget system for custom functionality
70+
- Multi-line editing
71+
- Syntax highlighting
72+
73+
### Higher-Level APIs
74+
75+
JLine includes several higher-level modules that provide additional functionality:
76+
77+
- **Style**: Styling API for terminal output
78+
- **Builtins**: Ready-to-use commands and utilities
79+
- **Console**: Framework for building interactive console applications
80+
- **Console UI**: UI components like progress bars, tables, and forms
81+
82+
## Data Flow
83+
84+
Here's how data flows through the JLine system:
85+
86+
1. The `Terminal` captures raw input from the user
87+
2. Input is processed through key bindings and widgets
88+
3. The `LineReader` applies editing operations based on the input
89+
4. When the user presses Enter, the `LineReader` returns the completed line
90+
5. The application processes the line and may use higher-level APIs for output
91+
92+
## Module Dependencies
93+
94+
The modules have the following dependency relationships:
95+
96+
```
97+
jline-terminal
98+
↑
99+
jline-reader
100+
↑
101+
jline-style
102+
↑
103+
jline-builtins
104+
↑
105+
jline-console
106+
↑
107+
jline-console-ui
108+
```
109+
110+
## Key Interfaces
111+
112+
JLine defines several key interfaces that you'll work with:
113+
114+
- `Terminal`: Represents the terminal device
115+
- `LineReader`: Reads lines of input with editing capabilities
116+
- `Completer`: Provides tab completion suggestions
117+
- `History`: Manages command history
118+
- `Parser`: Parses input lines into tokens
119+
- `Widget`: Implements custom functionality for the line reader
120+
121+
## Customization Points
122+
123+
JLine is highly customizable through several extension points:
124+
125+
- **Terminal Providers**: Choose or implement different terminal backends
126+
- **Completers**: Create custom completion logic
127+
- **Widgets**: Add new editing functions
128+
- **Key Bindings**: Map keys to specific actions
129+
- **Highlighters**: Implement syntax highlighting
130+
- **History**: Customize history storage and retrieval
131+
132+
## Common Usage Patterns
133+
134+
### Basic Terminal and LineReader
135+
136+
```java
137+
// Create a terminal
138+
Terminal terminal = TerminalBuilder.builder()
139+
.system(true)
140+
.build();
141+
142+
// Create a line reader
143+
LineReader reader = LineReaderBuilder.builder()
144+
.terminal(terminal)
145+
.build();
146+
147+
// Read input
148+
String line = reader.readLine("prompt> ");
149+
```
150+
151+
### Adding Tab Completion
152+
153+
```java
154+
// Create a completer
155+
Completer completer = new StringsCompleter("command1", "command2", "help", "quit");
156+
157+
// Create a line reader with completion
158+
LineReader reader = LineReaderBuilder.builder()
159+
.terminal(terminal)
160+
.completer(completer)
161+
.build();
162+
```
163+
164+
### Using History
165+
166+
```java
167+
// Create a history file
168+
Path historyFile = Paths.get(System.getProperty("user.home"), ".myapp_history");
169+
170+
// Create a line reader with history
171+
LineReader reader = LineReaderBuilder.builder()
172+
.terminal(terminal)
173+
.variable(LineReader.HISTORY_FILE, historyFile)
174+
.build();
175+
```
176+
177+
## Conclusion
178+
179+
JLine's architecture provides a flexible and powerful foundation for building command-line applications. By understanding how the components interact, you can leverage JLine's capabilities to create sophisticated terminal interfaces.
180+
181+
For more detailed information about each component, refer to the specific documentation pages.

‎jline-docs/docs/intro.md

Lines changed: 47 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -57,27 +57,40 @@ import java.io.IOException;
5757
public class JLineExample {
5858
public static void main(String[] args) {
5959
try {
60-
// highlight-start
61-
// Setup the terminal
60+
// Create a terminal
6261
Terminal terminal = TerminalBuilder.builder()
6362
.system(true)
6463
.build();
6564

66-
// Create the line reader
67-
LineReader lineReader = LineReaderBuilder.builder()
65+
// Create a line reader
66+
LineReader reader = LineReaderBuilder.builder()
6867
.terminal(terminal)
6968
.build();
70-
// highlight-end
7169

72-
// Read a line
73-
String line = lineReader.readLine("JLine > ");
74-
System.out.println("You entered: " + line);
70+
// Read lines from the user
71+
while (true) {
72+
String line = reader.readLine("prompt> ");
73+
74+
// Exit if requested
75+
if ("exit".equalsIgnoreCase(line)) {
76+
break;
77+
}
78+
79+
// Echo the line back to the user
80+
terminal.writer().println("You entered: " + line);
81+
terminal.flush();
82+
}
83+
84+
terminal.writer().println("Goodbye!");
85+
terminal.close();
7586

7687
} catch (IOException e) {
7788
System.err.println("Error creating terminal: " + e.getMessage());
7889
}
7990
}
8091
}
92+
93+
8194
```
8295

8396
This simple example demonstrates how to:
@@ -88,4 +101,29 @@ This simple example demonstrates how to:
88101

89102
## Next Steps
90103

91-
Explore the documentation to learn more about JLine's advanced features:
104+
Now that you have a basic understanding of JLine, here's a recommended learning path:
105+
106+
1. **Terminal Handling**: Learn how to [create and configure terminals](./terminal.md) for different environments
107+
108+
2. **Line Reading**: Explore the [LineReader](./line-reader.md) capabilities for advanced input handling
109+
110+
3. **Tab Completion**: Add [tab completion](./tab-completion.md) to provide suggestions as users type
111+
112+
4. **Command History**: Implement [history](./history.md) to allow users to recall previous commands
113+
114+
5. **Advanced Features**: Dive into advanced topics like:
115+
- [Syntax highlighting](./advanced/syntax-highlighting.md)
116+
- [Key bindings](./advanced/key-bindings.md)
117+
- [Attributed strings](./advanced/attributed-strings.md)
118+
- [Mouse support](./advanced/mouse-support.md)
119+
120+
6. **Modules**: Explore JLine's specialized modules:
121+
- [Terminal providers](./modules/terminal-providers.md)
122+
- [Builtins](./modules/builtins.md)
123+
- [Style](./modules/style.md)
124+
- [Console](./modules/console.md)
125+
- [Console UI](./modules/console-ui.md)
126+
127+
7. **Troubleshooting**: Refer to the [troubleshooting guide](./troubleshooting.md) if you encounter issues
128+
129+
JLine offers a rich set of features to create sophisticated command-line interfaces. The examples in this documentation will help you leverage these capabilities in your applications.

‎jline-docs/docs/modules/terminal-providers.md

Lines changed: 25 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -73,10 +73,10 @@ Here's a comparison of the different terminal providers:
7373
JLine uses a discovery mechanism to find and select the appropriate terminal provider. The selection process follows this order:
7474

7575
1. Check for explicitly specified provider via system property or builder method
76-
2. Try FFM provider if running on Java 22+
77-
3. Try JNI provider
78-
4. Try JNA provider if JNA is available
79-
5. Try Jansi provider if Jansi is available
76+
2. Try FFM provider if running on Java 22+ (recommended)
77+
3. Try JNI provider (recommended)
78+
4. Try JNA provider if JNA is available (deprecated)
79+
5. Try Jansi provider if Jansi is available (deprecated)
8080
6. Fall back to Exec provider
8181

8282
### Provider Selection Methods
@@ -162,6 +162,8 @@ java -Dorg.jline.terminal.provider=exec -jar myapp.jar
162162

163163
The `jline-terminal-jna` module provides terminal implementations using the Java Native Access (JNA) library. JNA allows Java code to access native shared libraries without writing JNI code.
164164

165+
**Note: The JNA provider is deprecated. It is recommended to use JNI or FFM providers instead.**
166+
165167
### Features
166168

167169
- Dynamic loading of native libraries
@@ -202,6 +204,8 @@ public class JnaTerminalExample {
202204

203205
The `jline-terminal-jansi` module provides terminal implementations using the Jansi library. Jansi is particularly useful for Windows systems, where it provides ANSI escape sequence support.
204206

207+
**Note: The Jansi provider is deprecated. It is recommended to use JNI or FFM providers instead.**
208+
205209
### Features
206210

207211
- Cross-platform ANSI support
@@ -242,7 +246,7 @@ public class JansiTerminalExample {
242246

243247
## JLine Terminal-FFM
244248

245-
The `jline-terminal-ffm` module provides terminal implementations leveraging the Foreign Function & Memory API introduced in Java 21. This is the most modern approach and is recommended for applications running on Java 21 or later.
249+
The `jline-terminal-ffm` module provides terminal implementations leveraging the Foreign Function & Memory API introduced in Java 22. This is the most modern approach and is recommended for applications running on Java 22 or later.
246250

247251
### Features
248252

@@ -416,7 +420,7 @@ When working with JLine terminal providers, consider these best practices:
416420

417421
4. **Test on Different Platforms**: Test your application on different platforms to ensure it works with different terminal providers.
418422

419-
5. **Consider Java Version**: Use the FFM provider for Java 22+ applications for the best integration with modern Java.
423+
5. **Consider Java Version**: Use the FFM provider for Java 22+ applications for the best integration with modern Java. JNI is recommended for Java versions below 22.
420424

421425
6. **Check Terminal Capabilities**: Use the terminal's capabilities to determine what features are available.
422426

@@ -437,35 +441,29 @@ This error occurs when JLine cannot find a suitable terminal provider. To resolv
437441
3. Fall back to a dumb terminal if necessary
438442

439443
```java
440-
Terminal terminal;
441-
try {
442-
terminal = TerminalBuilder.builder()
443-
.system(true)
444-
.build();
445-
} catch (IOException e) {
446-
System.err.println("Unable to create a system terminal: " + e.getMessage());
447-
terminal = TerminalBuilder.builder()
448-
.dumb(true)
449-
.build();
450-
}
444+
// Simply enable dumb mode if you need a fallback
445+
Terminal terminal = TerminalBuilder.builder()
446+
.system(true)
447+
.dumb(true) // Falls back to dumb if system terminal can't be created
448+
.build();
451449
```
452450

453-
#### JNA/Jansi not found
451+
#### Recommended provider dependencies
454452

455-
If you see errors about JNA or Jansi not being found, make sure you've included the appropriate dependencies:
453+
It's recommended to use the JNI or FFM providers:
456454

457455
```xml
458-
<!-- For JNA support -->
456+
<!-- For JNI support (recommended for Java < 22) -->
459457
<dependency>
460458
<groupId>org.jline</groupId>
461-
<artifactId>jline-terminal-jna</artifactId>
459+
<artifactId>jline-terminal-jni</artifactId>
462460
<version>3.29.0</version>
463461
</dependency>
464462

465-
<!-- For Jansi support -->
463+
<!-- For FFM support (recommended for Java 22+) -->
466464
<dependency>
467465
<groupId>org.jline</groupId>
468-
<artifactId>jline-terminal-jansi</artifactId>
466+
<artifactId>jline-terminal-ffm</artifactId>
469467
<version>3.29.0</version>
470468
</dependency>
471469
```
@@ -474,9 +472,10 @@ If you see errors about JNA or Jansi not being found, make sure you've included
474472

475473
When using JNA or Jansi on newer Java versions, you might see warnings about illegal reflective access. These are generally harmless but can be addressed by:
476474

477-
1. Using the FFM provider on Java 21+
478-
2. Adding appropriate `--add-opens` JVM arguments
479-
3. Suppressing the warnings if they don't affect functionality
475+
1. Using the FFM provider on Java 22+
476+
2. Using the JNI provider on Java versions below 22
477+
3. Adding appropriate `--add-opens` JVM arguments if you must use JNA/Jansi
478+
4. Suppressing the warnings if they don't affect functionality
480479

481480
#### Terminal size issues
482481

0 commit comments

Comments
 (0)