Skip to content

Commit 0d51d1c

Browse files
stalepstalep
committed
Updated docs for ANSIBuilder and TerminalCapability to reflect the latest changes
1 parent c139778 commit 0d51d1c

2 files changed

Lines changed: 261 additions & 25 deletions

File tree

‎content/docs/readline/color-detection.md‎

Lines changed: 91 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -93,11 +93,63 @@ int errorText = cap.getSuggestedErrorCode(); // 31 or 91 (red variants)
9393
int successText = cap.getSuggestedSuccessCode(); // 32 or 92 (green variants)
9494
int warningText = cap.getSuggestedWarningCode(); // 33 or 93 (yellow variants)
9595
int infoText = cap.getSuggestedInfoCode(); // 34 or 94 (blue variants)
96+
int timestampText = cap.getSuggestedTimestampCode(); // 36 or 96 (cyan variants)
97+
int messageText = cap.getSuggestedMessageCode(); // 35 or 95 (magenta variants)
9698

9799
// Use in ANSI escape sequences
98100
connection.write("\u001B[" + errorText + "mError: Something went wrong\u001B[0m\n");
99101
```
100102

103+
### All Suggested Colors
104+
105+
| Method | Dark Theme | Light Theme | Use Case |
106+
|--------|------------|-------------|----------|
107+
| `getSuggestedForegroundCode()` | 37 (white) | 30 (black) | Normal text |
108+
| `getSuggestedErrorCode()` | 91 (bright red) | 31 (red) | Error messages |
109+
| `getSuggestedSuccessCode()` | 92 (bright green) | 32 (green) | Success messages |
110+
| `getSuggestedWarningCode()` | 93 (bright yellow) | 33 (yellow) | Warnings |
111+
| `getSuggestedInfoCode()` | 94 (bright blue) | 34 (blue) | Info messages |
112+
| `getSuggestedTimestampCode()` | 96 (bright cyan) | 36 (cyan) | Timestamps in logs |
113+
| `getSuggestedMessageCode()` | 95 (bright magenta) | 35 (magenta) | Highlighted messages |
114+
115+
### Customizing Suggested Colors
116+
117+
You can override the default suggested colors using the `Builder`:
118+
119+
```java
120+
// Start with detected capability and customize specific colors
121+
TerminalColorCapability detected = TerminalColorDetector.detect(connection);
122+
TerminalColorCapability custom = TerminalColorCapability.builder(detected)
123+
.errorCode(196) // Custom 256-color bright red
124+
.successCode(46) // Custom 256-color green
125+
.timestampCode(244) // Custom 256-color gray for timestamps
126+
.build();
127+
128+
// Now getSuggestedErrorCode() returns 196 instead of theme-based default
129+
int error = custom.getSuggestedErrorCode(); // Returns 196
130+
```
131+
132+
Or build from scratch:
133+
134+
```java
135+
TerminalColorCapability custom = TerminalColorCapability.builder()
136+
.colorDepth(ColorDepth.COLORS_256)
137+
.theme(TerminalTheme.DARK)
138+
.errorCode(196)
139+
.successCode(46)
140+
.warningCode(208)
141+
.infoCode(39)
142+
.timestampCode(244)
143+
.messageCode(255)
144+
.foregroundCode(252)
145+
.build();
146+
```
147+
148+
This is useful when:
149+
- You have specific brand colors to use
150+
- User preferences should override theme-based defaults
151+
- You need 256-color or RGB codes instead of basic ANSI colors
152+
101153
## ColorDepth
102154

103155
The `ColorDepth` enum represents terminal color capabilities:
@@ -385,12 +437,14 @@ import org.aesh.terminal.utils.TerminalColorCapability;
385437
TerminalColorCapability cap = TerminalColorDetector.detect(connection);
386438

387439
// These methods automatically choose appropriate colors for the theme
388-
TerminalColor error = TerminalColor.forError(cap); // Red, bright on dark
389-
TerminalColor success = TerminalColor.forSuccess(cap); // Green, bright on dark
390-
TerminalColor warning = TerminalColor.forWarning(cap); // Yellow, bright on dark
391-
TerminalColor info = TerminalColor.forInfo(cap); // Cyan/Blue, bright on dark
440+
TerminalColor error = TerminalColor.forError(cap); // Red, bright on dark
441+
TerminalColor success = TerminalColor.forSuccess(cap); // Green, bright on dark
442+
TerminalColor warning = TerminalColor.forWarning(cap); // Yellow, bright on dark
443+
TerminalColor info = TerminalColor.forInfo(cap); // Cyan/Blue, bright on dark
392444
TerminalColor highlight = TerminalColor.forHighlight(cap); // Emphasized text
393-
TerminalColor muted = TerminalColor.forMuted(cap); // Secondary/dim text
445+
TerminalColor muted = TerminalColor.forMuted(cap); // Secondary/dim text
446+
TerminalColor timestamp = TerminalColor.forTimestamp(cap); // Cyan, for log timestamps
447+
TerminalColor message = TerminalColor.forMessage(cap); // Magenta, for highlighted messages
394448
```
395449

396450
On **dark themes**, these return bright variants for readability. On **light themes**, they use normal intensity to avoid glaring colors.
@@ -415,6 +469,38 @@ connection.write(okMsg.toString() + "\n");
415469
connection.write(infoMsg.toString() + "\n");
416470
```
417471

472+
### Example: Log Output with Timestamps
473+
474+
Use `ANSIBuilder` for rich log-style output with timestamps:
475+
476+
```java
477+
TerminalColorCapability cap = TerminalColorDetector.detect(connection);
478+
ANSIBuilder builder = ANSIBuilder.builder(cap);
479+
480+
// Log line with timestamp, level, and message
481+
connection.write(builder
482+
.timestamp("2024-01-15 10:30:45").append(" ")
483+
.success("[INFO]").append(" ")
484+
.message("Application started successfully")
485+
.toLine());
486+
487+
builder.reset();
488+
connection.write(builder
489+
.timestamp("2024-01-15 10:30:46").append(" ")
490+
.warning("[WARN]").append(" ")
491+
.append("Low memory condition detected")
492+
.toLine());
493+
494+
builder.reset();
495+
connection.write(builder
496+
.timestamp("2024-01-15 10:30:47").append(" ")
497+
.error("[ERROR]").append(" ")
498+
.append("Connection to database failed")
499+
.toLine());
500+
```
501+
502+
Output adapts automatically to the terminal theme - bright colors on dark backgrounds, normal colors on light backgrounds.
503+
418504
### Color Depth Adaptation
419505

420506
When using RGB colors on terminals with limited color support, use `forCapability()` to automatically downgrade:

‎content/docs/readline/terminal-colors.md‎

Lines changed: 170 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -127,24 +127,28 @@ import org.aesh.terminal.utils.TerminalColorCapability;
127127
TerminalColorCapability cap = TerminalColorDetector.detect(connection);
128128

129129
// Get theme-appropriate colors
130-
TerminalColor error = TerminalColor.forError(cap); // Red
131-
TerminalColor success = TerminalColor.forSuccess(cap); // Green
132-
TerminalColor warning = TerminalColor.forWarning(cap); // Yellow
133-
TerminalColor info = TerminalColor.forInfo(cap); // Cyan/Blue
130+
TerminalColor error = TerminalColor.forError(cap); // Red
131+
TerminalColor success = TerminalColor.forSuccess(cap); // Green
132+
TerminalColor warning = TerminalColor.forWarning(cap); // Yellow
133+
TerminalColor info = TerminalColor.forInfo(cap); // Cyan/Blue
134134
TerminalColor highlight = TerminalColor.forHighlight(cap); // Emphasized
135-
TerminalColor muted = TerminalColor.forMuted(cap); // Dimmed
135+
TerminalColor muted = TerminalColor.forMuted(cap); // Dimmed
136+
TerminalColor timestamp = TerminalColor.forTimestamp(cap); // Cyan (for log timestamps)
137+
TerminalColor message = TerminalColor.forMessage(cap); // Magenta (for highlighted messages)
136138
```
137139

138140
### How Theme Adaptation Works
139141

140-
| Method | Dark Theme | Light Theme |
141-
|--------|------------|-------------|
142-
| `forError()` | Bright red | Normal red |
143-
| `forSuccess()` | Bright green | Normal green |
144-
| `forWarning()` | Bright yellow | Normal yellow |
145-
| `forInfo()` | Bright cyan | Normal blue |
146-
| `forHighlight()` | Bright white | Black |
147-
| `forMuted()` | Normal white | Normal black |
142+
| Method | Dark Theme | Light Theme | Use Case |
143+
|--------|------------|-------------|----------|
144+
| `forError()` | Bright red | Normal red | Error messages |
145+
| `forSuccess()` | Bright green | Normal green | Success messages |
146+
| `forWarning()` | Bright yellow | Normal yellow | Warnings |
147+
| `forInfo()` | Bright cyan | Normal blue | Info messages |
148+
| `forHighlight()` | Bright white | Black | Emphasized text |
149+
| `forMuted()` | Normal white | Normal black | Secondary text |
150+
| `forTimestamp()` | Bright cyan | Normal cyan | Log timestamps |
151+
| `forMessage()` | Bright magenta | Normal magenta | Highlighted messages |
148152

149153
These methods ensure readable colors on any background. On dark themes, bright colors stand out. On light themes, normal intensity prevents eye strain.
150154

@@ -235,22 +239,166 @@ connection.write(colored.toString());
235239

236240
## Using with ANSIBuilder
237241

238-
For more complex formatting, use `ANSIBuilder`:
242+
For more complex formatting, use `ANSIBuilder`. It provides a fluent API for building ANSI-formatted strings with support for basic colors, 256-color palette, true color RGB, and theme-aware semantic colors.
243+
244+
### Basic Usage
239245

240246
```java
241-
import org.aesh.readline.util.ANSIBuilder;
247+
import org.aesh.terminal.utils.ANSIBuilder;
242248

243249
String output = ANSIBuilder.builder()
244-
.red().text("Error: ").reset()
245-
.text("Something went wrong")
250+
.redText("Error: ")
251+
.append("Something went wrong")
246252
.toString();
247253

248-
// With RGB (where supported)
249-
String rgbOutput = ANSIBuilder.builder()
250-
.trueColor(255, 87, 51).text("Orange text").reset()
254+
// Bold and colors
255+
String styled = ANSIBuilder.builder()
256+
.bold("Title: ").append("Some text")
251257
.toString();
252258
```
253259

260+
### Theme-Aware Builder
261+
262+
Create a builder with detected terminal capabilities for automatic theme adaptation:
263+
264+
```java
265+
TerminalColorCapability cap = TerminalColorDetector.detect(connection);
266+
ANSIBuilder builder = ANSIBuilder.builder(cap);
267+
268+
// Semantic colors adapt to the terminal theme
269+
String output = builder
270+
.timestamp("2024-01-15 10:30:45").append(" ")
271+
.success("[INFO]").append(" ")
272+
.message("Application started")
273+
.toString();
274+
```
275+
276+
### Semantic Color Methods
277+
278+
The builder provides theme-aware semantic colors:
279+
280+
```java
281+
ANSIBuilder builder = ANSIBuilder.builder(cap);
282+
283+
builder.error("Error message"); // Red (bright on dark, normal on light)
284+
builder.success("Success message"); // Green
285+
builder.warning("Warning message"); // Yellow
286+
builder.info("Info message"); // Blue
287+
builder.timestamp("10:30:45"); // Cyan (subdued, for log timestamps)
288+
builder.message("Highlighted"); // Magenta (for highlighted messages)
289+
```
290+
291+
### Extended Color Support
292+
293+
#### 256-Color Palette
294+
295+
```java
296+
// Foreground color from 256-color palette
297+
builder.color256(208).append("Orange text");
298+
299+
// Background color from 256-color palette
300+
builder.bg256(17).append("Blue background");
301+
302+
// With text directly
303+
builder.color256(196, "Red text");
304+
```
305+
306+
#### True Color (24-bit RGB)
307+
308+
```java
309+
// RGB foreground
310+
builder.rgb(255, 87, 51).append("Orange text");
311+
312+
// RGB background
313+
builder.bgRgb(30, 30, 30).append("Dark background");
314+
315+
// From hex string
316+
builder.hex("#FF5733").append("Coral text");
317+
builder.bgHex("#1E1E1E").append("Dark background");
318+
```
319+
320+
#### Bright Colors
321+
322+
```java
323+
// Enable bright mode for the next color
324+
builder.bright().redText().append("Bright red");
325+
326+
// Turn off bright mode
327+
builder.brightOff();
328+
```
329+
330+
### Convenience Methods
331+
332+
```java
333+
// toLine() - returns string with newline appended
334+
connection.write(builder.error("Error occurred").toLine());
335+
336+
// appendLine() - appends text with newline, returns builder
337+
builder.appendLine("Line 1").appendLine("Line 2");
338+
339+
// reset() or clear() - clears builder for reuse
340+
builder.reset();
341+
builder.success("New content");
342+
```
343+
344+
### Reusing the Builder
345+
346+
For efficiency, reuse a single builder instance:
347+
348+
```java
349+
ANSIBuilder builder = ANSIBuilder.builder(cap);
350+
351+
// First message
352+
connection.write(builder.error("Error occurred").toLine());
353+
354+
// Reset and reuse for next message
355+
builder.reset();
356+
connection.write(builder.success("Operation completed").toLine());
357+
358+
// Reset and reuse again
359+
builder.reset();
360+
connection.write(builder
361+
.timestamp("10:30:45").append(" ")
362+
.info("[INFO]").append(" ")
363+
.message("Processing...")
364+
.toLine());
365+
```
366+
367+
### Complete Example
368+
369+
```java
370+
TerminalColorCapability cap = TerminalColorDetector.detect(connection);
371+
ANSIBuilder builder = ANSIBuilder.builder(cap);
372+
373+
// Log-style output with timestamps
374+
connection.write(builder
375+
.timestamp("2024-01-15 10:30:45").append(" ")
376+
.success("[INFO]").append(" ")
377+
.message("Application started")
378+
.toLine());
379+
380+
builder.reset();
381+
connection.write(builder
382+
.timestamp("2024-01-15 10:30:46").append(" ")
383+
.warning("[WARN]").append(" ")
384+
.append("Low memory condition")
385+
.toLine());
386+
387+
builder.reset();
388+
connection.write(builder
389+
.timestamp("2024-01-15 10:30:47").append(" ")
390+
.error("[ERROR]").append(" ")
391+
.append("Connection failed")
392+
.toLine());
393+
394+
// Using 256-color for custom branding
395+
builder.reset();
396+
connection.write(builder
397+
.color256(208, "MyApp").append(": ")
398+
.append("Custom colored branding")
399+
.toLine());
400+
```
401+
254402
## Complete Example
255403

256404
```java
@@ -327,6 +475,8 @@ public class ColorfulApp {
327475
| `forInfo(cap)` | Theme-aware cyan/blue for info |
328476
| `forHighlight(cap)` | Theme-aware emphasis color |
329477
| `forMuted(cap)` | Theme-aware secondary text color |
478+
| `forTimestamp(cap)` | Theme-aware cyan for log timestamps |
479+
| `forMessage(cap)` | Theme-aware magenta for highlighted messages |
330480

331481
### Instance Methods
332482

0 commit comments

Comments
 (0)