Styling & Highlighting mit spring-shell-jline

ReadCommand färbt seine Ausgabe heute mit elf handgeschriebenen ANSI-Escape-Konstanten. Das funktioniert — und lässt genau die Fähigkeiten liegen, für die spring-shell-jline überhaupt als eigene Dependency in der pom.xml steht. Dieser Report zeigt fünf Ausbaustufen, jede als Before/After am gleichen Code.

Ausgangslage: elf Konstanten und ein String.format

/**
 * Optionally for coloring the output in the terminal. ANSI escape codes are used for text formatting and coloring.
 */
private static final String RESET      = "\u001B[0m";
private static final String BOLD       = "\u001B[1m";
private static final String DIM        = "\u001B[2m";
private static final String ITALIC     = "\u001B[3m";
private static final String UNDERLINE  = "\u001B[4m";

private static final String RED        = "\u001B[31m";
private static final String GREEN      = "\u001B[32m";
private static final String BLUE       = "\u001B[34m";
private static final String MAGENTA    = "\u001B[35m";
private static final String GRAY       = "\u001B[90m";
private static final String DARK_BLUE_256 = "\u001B[38;5;18m";

sb.append(String.format(
        "\n%s | %s | %s | %s | erstellt: %s | von: %s%n",
        BOLD + DARK_BLUE_256 + fileName + RESET,
        ITALIC + MAGENTA + reversedContentType + RESET,
        GREEN + sizeBytes + GRAY + " bytes",
        DIM + RED + sysId + RESET,
        UNDERLINE + BLUE + createdOn + RESET,
        BOLD + DARK_BLUE_256 + createdBy + RESET));

Im Terminal sieht das so aus:

1. S1Wartung
   Die Farbwahl ist einkompiliert. Eine Farbanpassung ist ein Code-Change plus Build plus Deployment.
2. S2Portabilität
   \u001B[38;5;18m setzt ein 256-Farb-Terminal voraus. Auf einem 16-Farben-TERM wird das nicht heruntergerechnet, sondern ignoriert oder falsch dargestellt.
3. S3Pipe-Ausgabe
   Die Escapes werden bedingungslos geschrieben — auch wenn die Ausgabe in eine Datei oder durch grep läuft. Genau das ist im nicht-interaktiven CI/CD-Modus dieses Projekts der Normalfall.

Warum das JAR überhaupt separat in der pom.xml steht

Die Verdrahtung nimmt einem Spring Boot ab. ThemingAutoConfiguration stellt vier Beans bereit — man injiziert sie einfach in den Command:

// aus ThemingAutoConfiguration, per javap ausgelesen:
public ThemeActive      themeActive();
public ThemeRegistry    themeRegistry(ObjectProvider<Theme> themes);
public ThemeResolver    shellThemeResolver(ThemeRegistry, SpringShellProperties, ThemeActive);
public TemplateExecutor templateExecutor(ThemeResolver);

Stufe 1 — AttributedString statt Escape-Literalen

BOLD + DARK_BLUE_256 + fileName + RESET

AttributedStyle.DEFAULT
    .bold()
    .foreground(AttributedStyle.BLUE)

import org.jline.utils.AttributedStringBuilder;
import org.jline.utils.AttributedStyle;

private static final AttributedStyle S_FILE    = AttributedStyle.DEFAULT.bold().foreground(AttributedStyle.BLUE);
private static final AttributedStyle S_TYPE    = AttributedStyle.DEFAULT.italic().foreground(AttributedStyle.MAGENTA);
private static final AttributedStyle S_SIZE    = AttributedStyle.DEFAULT.foreground(AttributedStyle.GREEN);
private static final AttributedStyle S_UNIT    = AttributedStyle.DEFAULT.faint();
private static final AttributedStyle S_SYSID   = AttributedStyle.DEFAULT.faint().foreground(AttributedStyle.RED);
private static final AttributedStyle S_CREATED = AttributedStyle.DEFAULT.underline().foreground(AttributedStyle.BLUE);

AttributedStringBuilder asb = new AttributedStringBuilder();
asb.styled(S_FILE, fileName)
   .append(" | ")
   .styled(S_TYPE, reversedContentType)
   .append(" | ")
   .styled(S_SIZE, sizeBytes)
   .styled(S_UNIT, " bytes")
   .append(" | ")
   .styled(S_SYSID, sysId)
   .append(" | erstellt: ")
   .styled(S_CREATED, createdOn)
   .append(" | von: ")
   .styled(S_FILE, createdBy);

return asb.toAnsi();   // NICHT toString() -- siehe Falle 1

1. FALLE 1scheitert lautlos

   Ein @Command-Rückgabewert wird von MethodInvokerCommandAdapter mit PrintWriter.println(Object) ausgegeben — also über String.valueOf(…) und damit toString().

   AttributedString.toString() liefert den Klartext ohne jede Formatierung. Wer ein AttributedString direkt zurückgibt, bekommt eine korrekte, aber völlig farblose Ausgabe — ohne Fehlermeldung, ohne Warnung. Richtig ist .toAnsi() oder, terminal-bewusst, .toAnsi(terminal).

// echte RGB-Farbe statt 256er-Index -- JLine rechnet auf die Terminal-Palette herunter
AttributedStyle.DEFAULT.foreground(0x1a, 0x3a, 0x8f);   // foreground(int r, int g, int b)
AttributedStyle.DEFAULT.foregroundRgb(0x1a3a8f);        // dieselbe Farbe als ein int

// helle Variante einer Basisfarbe
AttributedStyle.DEFAULT.foreground(AttributedStyle.CYAN | AttributedStyle.BRIGHT);

// weitere Attribute
.bold() .faint() .italic() .underline() .blink() .inverse() .conceal() .crossedOut()
.background(int) .backgroundRgb(int) .foregroundDefault() .boldOff()

// Regex-basiertes nachtraegliches Faerben -- z.B. Suchtreffer in der Ausgabe markieren
asb.styleMatches(Pattern.compile("(?i)" + Pattern.quote(filter)),
                 AttributedStyle.DEFAULT.inverse());

// terminal-bewusstes Rendern: JLine kennt Farbtiefe und Palette des Ziels
return asb.toAnsi(terminal);

Stufe 2 — ThemeResolver und benannte Style-Tags

Die Stil-Sprache selbst ist die von JLine — kommagetrennte Attribute:

bold, faint, italic, underline, blink, inverse, conceal, crossed-out
fg:red   fg:bright-cyan   bg:black   default

import org.springframework.shell.jline.tui.style.StyleSettings;
import org.springframework.shell.jline.tui.style.ThemeResolver;

private final ThemeResolver themeResolver;   // Bean aus ThemingAutoConfiguration

public ReadCommand(AuthService authService,
                   ServiceNowService serviceNowService,
                   ThemeResolver themeResolver) {
    this.authService = authService;
    this.serviceNowService = serviceNowService;
    this.themeResolver = themeResolver;
}

// Tag -> Stil-Ausdruck ("bold,fg:green") -> AttributedStyle
AttributedStyle fileStyle = themeResolver.resolveStyle(
        themeResolver.resolveStyleTag(StyleSettings.TAG_LIST_VALUE));

AttributedStringBuilder asb = new AttributedStringBuilder();
asb.styled(fileStyle, fileName);

Bequemer ist der Ausdrucks-Modus. evaluateExpression reicht intern an JLines StyleExpression weiter — Syntax @{stil text}:

AttributedString line = themeResolver.evaluateExpression(
        "@{bold,fg:blue " + fileName + "} | " +
        "@{italic,fg:magenta " + reversedContentType + "} | " +
        "@{fg:green " + sizeBytes + "}@{faint  bytes}");

return line.toAnsi();

Stufe 3 — TemplateExecutor: Layout aus dem Code holen

sb.append(String.format(
        "\n%s | %s | %s | %s | erstellt: %s | von: %s%n",
        BOLD + DARK_BLUE_256 + fileName + RESET, /* ... */ ));

import org.springframework.shell.jline.tui.style.TemplateExecutor;

private static final String ROW_TEMPLATE =
        "<fileName; format=\"style-list-value\"> | " +
        "<contentType; format=\"style-value\"> | " +
        "<size; format=\"style-level-info\"> bytes | " +
        "<sysId; format=\"style-item-disabled\"> | " +
        "erstellt: <createdOn; format=\"style-value\"> | " +
        "von: <createdBy; format=\"style-title\">";

private final TemplateExecutor templateExecutor;   // Bean aus ThemingAutoConfiguration

Map<String, Object> attrs = Map.of(
        "fileName",    fileName,
        "contentType", reversedContentType,
        "size",        sizeBytes,
        "sysId",       sysId,
        "createdOn",   createdOn,
        "createdBy",   createdBy);

return templateExecutor.render(ROW_TEMPLATE, attrs).toAnsi();

<fileName; format="truncate-width:24">
<sysId;    format="truncate-width:12-prefix:6">

Stufe 4 — Eigenes Theme, umschaltbar per application.yaml

import org.springframework.shell.jline.tui.style.StyleSettings;
import org.springframework.shell.jline.tui.style.Theme;
import org.springframework.shell.jline.tui.style.ThemeSettings;

@Configuration
class ShellThemeConfig {

    @Bean
    Theme tinaTheme() {
        StyleSettings styles = new StyleSettings() {
            @Override public String listValue()      { return "bold,fg:cyan"; }
            @Override public String value()          { return "fg:bright-blue"; }
            @Override public String listLevelInfo()  { return "fg:green"; }
            @Override public String listLevelWarn()  { return "bold,fg:yellow"; }
            @Override public String listLevelError() { return "bold,fg:bright-red"; }
            @Override public String itemDisabled()   { return "faint"; }
        };
        return Theme.of("tina", new ThemeSettings(styles) { });
    }
}

spring:
  main:
    web-application-type: none
  shell:
    interactive:
      enabled: false   # Nicht-interaktiver Modus fuer CI/CD-Nutzung
    theme:
      name: tina       # -> ThemeRegistry.get("tina")

Stufe 5 — TableBuilder statt Pipe-Zeichen

import org.springframework.shell.jline.tui.table.*;

TableModelBuilder<String> model = new TableModelBuilder<>();
model.addRow().addValue("Datei").addValue("Typ").addValue("Groesse")
     .addValue("sys_id").addValue("erstellt").addValue("von");

for (Map<String, Object> a : sortedAttachments) {
    model.addRow()
         .addValue((String) a.get("file_name"))
         .addValue(serviceNowService.getExtensionForContentType((String) a.get("content_type")))
         .addValue(String.valueOf(a.get("size_bytes")))
         .addValue((String) a.get("sys_id"))
         .addValue(String.valueOf(a.get("sys_created_on")))
         .addValue(String.valueOf(a.get("sys_created_by")));
}

Table table = new TableBuilder(model.build())
        .addHeaderBorder(BorderStyle.fancy_light)
        .on(CellMatchers.column(2)).addAligner(SimpleHorizontalAligner.right).and()
        .on(CellMatchers.column(0)).addSizer(new AbsoluteWidthSizeConstraints(32)).and()
        .build();

return table.render(120);   // 120 = verfuegbare Terminalbreite

Bonus — Prompt und Eingabe-Highlighting

// eigener Prompt: ein Bean, das AttributedString liefert
@Bean
PromptProvider tinaPrompt(ThemeResolver themeResolver) {
    return () -> themeResolver.evaluateExpression("@{bold,fg:cyan tina-snow}@{faint  > }");
}

CommandHighlighter implementiert JLines Highlighter und färbt beim Tippen den erkannten Command-Namen gegen die CommandRegistry ein. Es ist bereits verdrahtet — ersetzen lässt es sich durch ein eigenes Highlighter-Bean.

Entscheidungshilfe

1. E1Empfehlung
   Für ReadCommand konkret: Stufe 5 plus Stufe 2. Die Attachment-Liste ist eine Tabelle, und ein TableBuilder löst das Spaltenproblem, das reine Farbgebung gar nicht adressiert. Die Stufen 3 und 4 sind erst dann dran, wenn ein zweiter Command dieselbe Formatierung braucht.
2. E2offen
   Keine der fünf Stufen löst S3 aus der Ausgangslage von allein: Auch toAnsi() ohne Terminal-Argument schreibt Escapes bedingungslos. Im nicht-interaktiven Modus dieses Projekts ist das der Regelfall. Die Variante toAnsi(Terminal) behält die Terminal-Fähigkeiten im Blick — ob sie bei umgeleiteter Ausgabe vollständig auf Klartext schaltet, ist für diesen Report nicht verifiziert und gehört vor einer Umstellung gegen die CI-Pipeline getestet.

Anhang: Verifikations-Log

M2=~/.m2/repository/org/springframework/shell
J=$M2/spring-shell-jline/4.0.3/spring-shell-jline-4.0.3.jar

# Welche Style-Klassen liefert das jline-JAR ueberhaupt?
unzip -l $J | grep "tui/style/"

# Tag-Namen als Konstantenwerte
javap -constants -classpath $J org.springframework.shell.jline.tui.style.StyleSettings

# Default-Stile ("bold", "fg:green", ...) stehen im Bytecode der Basisklasse
javap -c -p -classpath $J org.springframework.shell.jline.tui.style.StyleSettings

# Beweis, dass core KEINE Style-Klasse enthaelt
unzip -l $M2/spring-shell-core/4.0.3/spring-shell-core-4.0.3.jar | grep -Ei "style|theme|table"

# Die Beans, die das alles verdrahten
javap -classpath $M2/spring-shell-core-autoconfigure/4.0.3/spring-shell-core-autoconfigure-4.0.3.jar \
      org.springframework.shell.core.autoconfigure.ThemingAutoConfiguration

# Falle 1: wie der Rueckgabewert eines @Command ausgegeben wird
javap -c -p org/springframework/shell/core/command/adapter/MethodInvokerCommandAdapter.class | grep PrintWriter

Zielbild — dieselbe Liste, zwei business-taugliche Ausgaben

import org.jline.utils.AttributedStringBuilder;
import org.jline.utils.AttributedStyle;

// Stil einmal als Objekt -- JLine rechnet beim Rendern auf die Terminal-Palette herunter
private static final AttributedStyle NAME = AttributedStyle.DEFAULT.bold().foreground(AttributedStyle.BLUE);
private static final AttributedStyle META = AttributedStyle.DEFAULT.faint();
private static final AttributedStyle SIZE = AttributedStyle.DEFAULT.foreground(AttributedStyle.GREEN);

AttributedStringBuilder asb = new AttributedStringBuilder();
asb.styled(META, "%s \u203a %d Anhaenge".formatted(articleNumber, rows.size())).append("\n");

for (Attachment a : rows) {                       // rows: bereits nach Datum sortiert
    asb.styled(NAME, rpad(a.fileName(), 29))
       .styled(META, rpad(a.type(), 5))
       .styled(SIZE, lpad(humanSize(a.sizeBytes()), 7)).append("  ")
       .styled(META, rpad(relativeDate(a.createdOn()), 13))
       .append(rpad(a.createdBy(), 8))
       .styled(META, "\u00b7" + a.sysId().substring(0, 6))
       .append("\n");
}
return asb.toAnsi(terminal);                      // NICHT toString() -- Falle 1

import org.springframework.shell.jline.tui.table.*;
import org.springframework.shell.jline.tui.style.ThemeResolver;

private final ThemeResolver themeResolver;   // Bean aus ThemingAutoConfiguration

TableModelBuilder<String> model = new TableModelBuilder<>();
model.addRow().addValue("Datei").addValue("Typ").addValue("Groesse")
     .addValue("erstellt").addValue("von").addValue("sys_id");
for (Attachment a : rows) {
    model.addRow()
         .addValue(a.fileName())
         .addValue(a.type())
         .addValue(humanSize(a.sizeBytes()))        // 184320 -> "180 KB"
         .addValue(relativeDate(a.createdOn()))     // -> "vor 13 Tagen"
         .addValue(a.createdBy())
         .addValue("\u00b7" + a.sysId().substring(0, 6));
}

// Rahmen dezent (fancy_light), Dateiname pro Zelle ueber den ThemeResolver gefaerbt -- Stufe 3
Formatter accent = v -> new String[]{
        themeResolver.evaluateExpression("@{bold,fg:blue " + v + "}").toAnsi() };

Table table = new TableBuilder(model.build())
        .addFullBorder(BorderStyle.fancy_light)
        .on(CellMatchers.column(0)).addFormatter(accent)
              .addSizer(new AbsoluteWidthSizeConstraints(29)).and()   // Escapes zaehlen mit -> feste Breite
        .on(CellMatchers.column(2)).addAligner(SimpleHorizontalAligner.right).and()
        .build();
return table.render(84);