Transzformátorok

A transzformátorok a kiemelt kimenetet minden szakaszban átalakíthatják: a nyers forrássztringtől a tokenrácson át a végső HAST-fáig és az HTML-ig. Az shikiphp hookról hookra veszi át a Shiki transzformátormodelljét, ezért a transzformátorok ugyanúgy működnek, mint a JavaScript megfelelőik.

Adja át őket a transformers beállításon keresztül:

use Shikiphp\Shikiphp;
use Shikiphp\Transformer\Notation\NotationHighlight;
use Shikiphp\Transformer\Notation\NotationDiff;

$code = <<<'JS'
console.log('this line is highlighted') // [!code highlight]
console.log('old line') // [!code --]
console.log('new line') // [!code ++]
JS;

echo Shikiphp::codeToHtml($code, [
    'lang'         => 'js',
    'theme'        => 'vitesse-dark',
    'transformers' => [
        new NotationHighlight(),
        new NotationDiff(),
    ],
]);

A folyamat

Minden transzformátor egy Shikiphp\Transformer\Transformer interfészt megvalósító objektum. A folyamat egyetlen blokk felépítése során, sorrendben futtatja a hookokat:

Minden hook opcionális. A visszaadott érték lecseréli a bemenetet; az null visszaadása változatlanul hagyja.

Az enforce() szabályozza a transzformátorok közötti sorrendet: először az 'pre' fut, utoljára az 'post', az null pedig (alapértelmezés szerint) közéjük kerül, a regisztráció sorrendjében.

Transzformátor írása

Terjessze ki az Shikiphp\Transformer\AbstractTransformer típust, így csak a szükséges hookokat kell felülírnia; a többi üres művelet marad. A transzformátor környezete biztosítja az addClassToHast() metódust, amellyel osztályokat adhat az elemekhez.

use Shikiphp\Hast\Element;
use Shikiphp\Shikiphp;
use Shikiphp\Transformer\AbstractTransformer;
use Shikiphp\Transformer\TransformerContext;

final class AddLanguageClass extends AbstractTransformer
{
    public function pre(Element $element, TransformerContext $context): ?Element
    {
        if ($context->lang !== null) {
            $context->addClassToHast($element, 'language-' . $context->lang);
        }

        return $element;
    }
}

echo Shikiphp::codeToHtml('const answer = 42', [
    'lang'         => 'js',
    'theme'        => 'nord',
    'transformers' => [new AddLanguageClass()],
]);
// <pre class="shiki nord language-js" …>

Beépített transzformátorok

Jelölés-transzformátorok

Ezek a forrás speciális // [!code …] megjegyzéseit olvassák be (a megjegyzések szintaxisát automatikusan felismerik), majd osztályokká alakítják őket, magát a megjegyzést pedig eltávolítják. A @shikijs/transformers jelöléskészlet közvetlen átültetései.

NotationHighlight

Shikiphp\Transformer\Notation\NotationHighlight — a // [!code highlight] (vagy a // [!code hl]) hozzáadja a highlighted osztályt a sorhoz.

console.log('kept plain')
console.log('this line is highlighted') // [!code highlight]

NotationDiff

Shikiphp\Transformer\Notation\NotationDiff — a // [!code ++] hozzáadottként jelöl egy sort (diff add), az // [!code --] pedig töröltként jelöli (diff remove).

console.log('old line') // [!code --]
console.log('new line') // [!code ++]

NotationFocus

Shikiphp\Transformer\Notation\NotationFocus — a // [!code focus] hozzáadja a focused osztályt.

console.log('focus on me') // [!code focus]

NotationErrorLevel

Shikiphp\Transformer\Notation\NotationErrorLevel — a // [!code error], a // [!code warning] és a // [!code info] hozzáadja a highlighted osztályt, valamint a error / warning / info értékeket.

throwSomething() // [!code error]
maybeRisky()     // [!code warning]

NotationWordHighlight

Shikiphp\Transformer\Notation\NotationWordHighlight — // [!code word:foo] (opcionálisan // [!code word:foo:2] a következő N sorra való korlátozáshoz) minden foo-előfordulást highlighted-word attribútumot hordozó span elembe csomagol.

// [!code word:config]
const config = loadConfig()

Metaadat-transzformátorok

Ezek a kódkerítésen keresztül megadott metaadat-sztringet olvassák be a meta beállítással (meta['__raw']), ahogyan az Shiki is beolvassa a bekerített kódblokk nyelve utáni szöveget.

MetaHighlight

Shikiphp\Transformer\MetaHighlight — kiemeli a metaadat-tartományban megadott sorokat, például a {1,3-5} sorait; ehhez hozzáadja a highlighted osztályt.

use Shikiphp\Shikiphp;
use Shikiphp\Transformer\MetaHighlight;

$code = "const a = 1\nconst b = 2\nconst c = 3\nconst d = 4\nconst e = 5";

echo Shikiphp::codeToHtml($code, [
    'lang'         => 'js',
    'theme'        => 'nord',
    'meta'         => ['__raw' => '{1,3-5}'],
    'transformers' => [new MetaHighlight()],
]);

MetaWordHighlight

Shikiphp\Transformer\MetaWordHighlight — a metaadat-sztringben megadott szavakat emeli ki /word/ szintaxissal, és hozzáadja a highlighted-word értéket.

Szóközök és struktúra

RenderWhitespace

Shikiphp\Transformer\RenderWhitespace — a szóköz- és tabulátorkaraktereket span elemekbe csomagolja (alapértelmezés szerint az space és tab osztállyal), hogy láthatóan jelenjenek meg. A konstruktor az (classSpace, classTab, position) értéket fogadja; az position értéke 'all' (alapértelmezett), 'boundary', 'trailing' vagy 'leading' lehet.

CompactLineOptions

Shikiphp\Transformer\CompactLineOptions — osztályokat rendel meghatározott sorokhoz egy {line, classes} bejegyzéseket tartalmazó listából.

use Shikiphp\Transformer\CompactLineOptions;

$transformer = new CompactLineOptions([
    ['line' => 1, 'classes' => 'highlighted'],
    ['line' => 3, 'classes' => ['highlighted', 'error']],
]);

A sorszámozás 1-től indul. Az objektumot ugyanúgy a transformers beállítással adja át, mint bármely más transzformátort.

RemoveNotationEscape

Shikiphp\Transformer\RemoveNotationEscape — visszaalakítja az [\!code …] formát, amellyel egy szó szerinti jelölésmegjegyzést lehet írni a jelölés-transzformátor aktiválása nélkül.

RemoveLineBreak

Shikiphp\Transformer\RemoveLineBreak — eltávolítja a sortörést tartalmazó szövegcsomópontokat a sorok közül (az Shiki transformerRemoveLineBreak értékét).

StyleToClass

Shikiphp\Transformer\StyleToClass — a beágyazott stílusokat generált osztályokká alakítja, és összegyűjti a stíluslapot, amely az getCSS() segítségével kérhető le. Az osztályneveket a stílus és az Shiki cyrb53 értéke alapján hash-eli, így a kimenet bájtról bájtra megegyezik az @shikijs/transformers 4.2.0 értékével, beleértve a hatókört is:

• Az <pre> stílus mindig osztállyá alakul.
• A tokenek span elemei csak akkor alakulnak át, ha előre összeállított stílussal rendelkeznek, ami themes térkép esetén áll fenn. Egyetlen theme esetén a tokenek span elemei megtartják beágyazott style="color:…" értékeiket, ahogyan az Shiki esetében is.

use Shikiphp\Shikiphp;
use Shikiphp\Transformer\StyleToClass;

$code = 'const answer = 42';
$styleToClass = new StyleToClass();

$html = Shikiphp::codeToHtml($code, [
    'lang'         => 'js',
    'themes'       => ['light' => 'github-light', 'dark' => 'github-dark'],
    'transformers' => [$styleToClass],
]);

$css = $styleToClass->getCSS(); // collected stylesheet for the classes above

A konstruktor (classPrefix, classSuffix, classReplacer) értéket fogad; az alapértelmezett előtag: __shiki_.