Transformatoriai

Transformatoriai leidžia keisti paryškintą išvestį kiekviename etape — nuo neapdorotos šaltinio eilutės, per žetonų tinklelį iki galutinio HAST medžio ir HTML. shikiphp perkelia Shiki transformatorių modelį, kabliuką po kabliuko, todėl transformatoriai veikia taip pat kaip jų JavaScript atitikmenys.

Perduokite juos per parinktį transformers:

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

Proceso eiga

Kiekvienas transformatorius yra objektas, įgyvendinantis Shikiphp\Transformer\Transformer. Srautas vykdo kabliukus eilės tvarka kuriant vieną bloką:

Visi kabliukai pasirenkami. Grąžinus reikšmę, ji pakeičia įvestį; grąžinus null, įvestis lieka nepakeista.

enforce() valdo transformatorių eiliškumą: 'pre' vykdomas pirmas, 'post' paskutinis, o null (numatytoji reikšmė) vykdomas tarp jų registravimo tvarka.

Transformatoriaus kūrimas

Išplėskite Shikiphp\Transformer\AbstractTransformer ir perrašykite tik tuos kabliukus, kurių reikia; kiti nieko nedarys. Transformatoriaus kontekste pateikiama addClassToHast(), skirta elementų klasėms pridėti.

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" …>

Integruoti transformatoriai

Notacijos transformatoriai

Jie aptinka specialius // [!code …] komentarus šaltinyje (komentarų sintaksė kalboje nustatoma automatiškai) ir paverčia juos klasėmis, o patį komentarą pašalina. Tai tiesioginiai @shikijs/transformers notacijų rinkinio perkėlimai.

NotationHighlight

Shikiphp\Transformer\Notation\NotationHighlight — // [!code highlight] (arba // [!code hl]) eilutei prideda klasę highlighted.

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

NotationDiff

Shikiphp\Transformer\Notation\NotationDiff — // [!code ++] pažymi eilutę kaip pridėtą (diff add), o // [!code --] — kaip pašalintą (diff remove).

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

NotationFocus

Shikiphp\Transformer\Notation\NotationFocus — // [!code focus] prideda klasę focused.

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

NotationErrorLevel

Shikiphp\Transformer\Notation\NotationErrorLevel — // [!code error], // [!code warning] ir // [!code info] prideda klasę highlighted bei error / warning / info.

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

NotationWordHighlight

Shikiphp\Transformer\Notation\NotationWordHighlight — // [!code word:foo] (pasirinktinai // [!code word:foo:2], kad apimtų tik kitas N eilučių) kiekvieną foo atvejį apgaubia intervalu su highlighted-word.

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

Metaduomenų transformatoriai

Jie nuskaito kodo bloko metaduomenų eilutę, perduodamą per parinktį meta (meta['__raw']), kaip Shiki nuskaito tekstą po aptverto kodo bloko kalbos žymos.

MetaHighlight

Shikiphp\Transformer\MetaHighlight — paryškina metaduomenų intervale nurodytas eilutes, pavyzdžiui, {1,3-5}, ir prideda klasę highlighted.

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 — paryškina metaduomenų eilutėje nurodytus žodžius naudodamas sintaksę /word/ ir prideda highlighted-word.

Tarpai ir struktūra

RenderWhitespace

Shikiphp\Transformer\RenderWhitespace — tarpų ir tabuliacijos simbolius apgaubia intervalais (pagal numatytuosius nustatymus klasės space ir tab), kad jie būtų matomi. Konstruktoriui perduodamas (classSpace, classTab, position), kur position yra 'all' (numatytoji reikšmė), 'boundary', 'trailing' arba 'leading'.

CompactLineOptions

Shikiphp\Transformer\CompactLineOptions — priskiria klases konkrečioms eilutėms pagal {line, classes} įrašų sąrašą.

use Shikiphp\Transformer\CompactLineOptions;

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

Eilučių numeracija prasideda nuo 1. Perduokite objektą per parinktį transformers, kaip ir bet kurį kitą transformatorių.

RemoveNotationEscape

Shikiphp\Transformer\RemoveNotationEscape — panaikina [\!code …] formos eskeipinimą, naudojamą pažodiniam notacijos komentarui užrašyti, kad jis nesuaktyvintų notacijos transformatoriaus.

RemoveLineBreak

Shikiphp\Transformer\RemoveLineBreak — pašalina eilučių lūžių teksto mazgus tarp eilučių (Shiki elemento transformerRemoveLineBreak).

StyleToClass

Shikiphp\Transformer\StyleToClass — perkelia įterptuosius stilius į sugeneruotas klases ir surenka stiliaus lentelę, kurią galima gauti naudojant getCSS(). Klasių pavadinimai maišos funkcija apskaičiuojami iš stiliaus, naudojant Shiki cyrb53, todėl išvestis baitas į baitą sutampa su @shikijs/transformers 4.2.0, įskaitant jo taikymo sritį:

• <pre> stilius visada paverčiamas klase.
• Žetonų intervalai konvertuojami tik tada, kai turi iš anksto sukurtą stilių, kaip būna naudojant themes atvaizdį. Naudojant vieną theme, žetonų intervalai išlaiko įterptąjį style="color:…", kaip ir Shiki.

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

Konstruktoriui perduodamas (classPrefix, classSuffix, classReplacer); numatytasis prefiksas yra __shiki_.