ANSI-Ausgabe

Als Markdown anzeigen Auf GitHub bearbeiten Dokumentation zu 22946a5

Setze lang auf 'ansi', um Terminalausgaben hervorzuheben – Text mit ANSI-Escape-Sequenzen – statt sie mit einer Grammatik zu tokenisieren. shikiphp analysiert die Escape-Codes und färbt den Text mit der ANSI-Palette des Themes. Es ist eine Portierung von Shikis lang: 'ansi'-Tokenizer. Vier Oracle-Szenarien prüfen dessen HTML anhand von Shiki 3.23.0.

PHP

use Shikiphp\Shikiphp;

echo Shikiphp::codeToHtml("\e[31merror\e[0m: something broke", [
    'lang'  => 'ansi',
    'theme' => 'github-dark',
]);

So lassen sich aufgezeichnete CLI-Ausgaben – etwa von Testläufen, Build-Protokollen oder git-Ausgaben – natürlich mit den ursprünglichen Farben darstellen. Die Escape-Sequenzen werden aus der Ausgabe entfernt; nur der Text bleibt, umschlossen von farbigen Spans.

Beachte den doppelt in Anführungszeichen gesetzten PHP-String: "\e" ist das Escape-Zeichen. Wenn du die Ausgabe eines Prozesses renderst (zum Beispiel mit shell_exec oder proc_open), sind die Escape-Zeichen bereits im String enthalten.

Erkannte Sequenzen

Der Tokenizer liest SGR-Sequenzen (Select Graphic Rendition), ESC [ … m, mit beliebig vielen durch ; getrennten Codes:

Codes	Wirkung
`0`	setzt alle Farben und Attribute zurück
`1`, `3`, `4`, `9`	fett, kursiv, unterstrichen, durchgestrichen
`2`	gedimmt: der Vordergrund wird mit halber Deckkraft gezeichnet
`7`	invertiert: Vorder- und Hintergrund werden vertauscht
`21`, `23`, `24`, `27`, `29`	deaktivieren das entsprechende Attribut
`22`	normale Intensität: deaktiviert gedimmt und fett
`30`–`37`, `90`–`97`	Vordergrund: die 8 Standardfarben und 8 hellen Farben
`40`–`47`, `100`–`107`	Hintergrund: die 8 Standardfarben und 8 hellen Farben
`38;5;n`, `48;5;n`	Vorder- oder Hintergrund aus der 256-Farben-Tabelle
`38;2;r;g;b`, `48;2;r;g;b`	24-Bit-Echtfarben für Vorder- oder Hintergrund
`39`, `49`	Standardfarbe für Vorder- oder Hintergrund

Versteckt (8) und überstrichen (53) werden verarbeitet, ändern die Ausgabe aber nicht. Andere Codes werden ignoriert. Formatierungen gelten über Zeilenumbrüche hinweg weiter, bis sie zurückgesetzt werden – wie in einem Terminal.

Farben

Die 16 benannten Farben stammen aus den terminal.ansi*-Farben des Themes (terminal.ansiRed, terminal.ansiBrightBlue usw.). Wenn das Theme eine Farbe nicht definiert, wird die Standardpalette von VS Code verwendet (#cd3131 für Rot, #2472C8 für Blau usw.). Text ohne festgelegte Farbe erhält die Vordergrundfarbe des Themes, der Blockhintergrund dessen Hintergrundfarbe – wie bei grammatikbasierter Hervorhebung. In der 256-Farben-Tabelle sind die Einträge 0–15 dieselben 16 benannten Farben. Die Einträge 16–255 (der 6×6×6-Farbwürfel und die Graustufenpalette) sowie Echtfarbwerte sind nicht vom Theme abhängig.

colorReplacements gelten auch für ANSI-Farben.

Duale Themes

ANSI berücksichtigt die Zuordnung themes wie die grammatikbasierte Hervorhebung und gibt für die Themes außer dem Standard-Theme CSS-Varianten aus:

PHP

use Shikiphp\Shikiphp;

$log = "\e[32mPASS\e[0m tests/Unit\n\e[31mFAIL\e[0m tests/Integration";

echo Shikiphp::codeToHtml($log, [
    'lang'   => 'ansi',
    'themes' => ['light' => 'github-light', 'dark' => 'github-dark'],
]);

Jede benannte Farbe wird anhand der Palette des jeweiligen Themes aufgelöst. Daher kann Rot im hellen Theme anders aussehen als im dunklen.

Kein Grammatikzustand

Da ANSI keine TextMate-Grammatik verwendet, muss kein Grammatikzustand beibehalten werden. getLastGrammarState löst für lang: 'ansi' einen Fehler aus, und codeToTokensResult gibt ein null grammarState zurück.