# ANSI-tuloste

Aseta `lang` arvoon `'ansi'` korostaaksesi päätteen tulostetta — tekstiä, joka sisältää ANSI-
escape-sekvenssejä — kieliopin jäsennyksen sijaan. shikiphp jäsentää
escape-koodit ja värittää tekstin teeman ANSI-paletin mukaan. Se on sovitus
Shiki-järjestelmän `lang: 'ansi'`-jäsentimestä, ja neljä oracle-skenaariota tarkistaa sen HTML-toiminnan suhteessa kohteeseen Shiki 3.23.0.

```php
use Shikiphp\Shikiphp;

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

Tämä on luonteva tapa esittää talteen otettu CLI-tuloste — testiajojen tulokset, koontiversioiden lokit ja `git`-tuloste — alkuperäiset värit säilyttäen. Escape-sekvenssit poistetaan tulosteesta; jäljelle jää vain teksti, joka kääritään värillisiin span-elementteihin.

Huomaa lainausmerkeissä oleva PHP-merkkijono: `"\e"` on escape-merkki. Kun esität prosessista talteen otettua tulostetta (esimerkiksi komennolla `shell_exec` tai `proc_open`), escape-merkit ovat jo merkkijonossa.

## Mitä se tunnistaa

Jäsennin lukee SGR-sekvenssejä (Select Graphic Rendition), `ESC [ … m`, joissa voi olla mikä tahansa määrä `;`-eroteltuja koodeja:

| Koodit | Vaikutus |
| --- | --- |
| `0` | nollaa kaikki värit ja määritteet |
| `1`, `3`, `4`, `9` | lihavointi, kursivointi, alleviivaus, yliviivaus |
| `2` | himmennys: etuala piirretään puolikkaalla peittävyydellä |
| `7` | käänteinen: etuala ja tausta vaihtavat paikkaa |
| `21`, `23`, `24`, `27`, `29` | poistaa vastaavan määritteen käytöstä |
| `22` | normaali voimakkuus: poistaa himmennyksen ja lihavoinnin käytöstä |
| `30`–`37`, `90`–`97` | etuala: 8 vakioväriä ja 8 kirkasta väriä |
| `40`–`47`, `100`–`107` | tausta: 8 vakioväriä ja 8 kirkasta väriä |
| `38;5;n`, `48;5;n` | etuala tai tausta 256 värin taulukosta |
| `38;2;r;g;b`, `48;2;r;g;b` | 24-bittinen aidon värin etuala tai tausta |
| `39`, `49` | oletusetuala tai -tausta |

Piilotus (`8`) ja yliviivausviiva (`53`) jäsennetään, mutta ne eivät muuta tulostetta, ja muut koodit ohitetaan. Tyylit säilyvät rivinvaihtojen yli, kunnes ne nollataan, kuten päätteessä.

## Värit

16 nimettyä väriä ovat teeman `terminal.ansi*`-värejä (`terminal.ansiRed`, `terminal.ansiBrightBlue` ja niin edelleen). Jos teemassa ei ole jotakin väriä määritelty, käytetään VS Code-oletuspalettia (`#cd3131` punaiselle, `#2472C8` siniselle ja niin edelleen). Värittömäksi määritetty teksti käyttää teeman etualaväriä, ja lohkon tausta on teeman tausta, kuten kielioppiin perustuvassa korostuksessa. 256 värin taulukon kohdat 0–15 ovat samat 16 nimettyä väriä; kohdat 16–255 (6×6×6-värikuutio ja harmaasävyliuku) ja aidot väriarvot eivät riipu teemasta.

[`colorReplacements`](https://shikiphp.inline0.dev/fi/docs/options#colorreplacements) koskevat myös ANSI-värejä.

## Kaksi teemaa

ANSI noudattaa `themes`-karttaa kuten kielioppiin perustuva korostus ja tuottaa CSS-kohtaisia muunnelmia muille kuin oletusteemoille:

```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'],
]);
```

Kukin nimetty väri ratkaistaan kunkin teeman oman paletin mukaan, joten vaalean ja tumman teeman punainen voivat olla erilaisia.

## Ei kielioppitilaa

Koska ANSI ei käytä TextMate-kielioppia, kielioppitilaa ei tarvitse säilyttää. `getLastGrammarState` heittää virheen arvolla `lang: 'ansi'`, ja `codeToTokensResult` palauttaa arvon `null` `grammarState`.