Transformers

Transformers låter dig omforma den markerade utdatan i varje steg — från råkällsträngen via tokengallret till det slutliga HAST-trädet och HTML. shikiphp överför Shikis transformer-modell hook för hook, så transformers fungerar på samma sätt som motsvarande komponenter i JavaScript.

Skicka dem via alternativet 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(),
    ],
]);

Flödet

Varje transformer är ett objekt som implementerar Shikiphp\Transformer\Transformer. Flödet kör hookarna i ordning medan ett block byggs:

Alla hookar är valfria. Ett returvärde ersätter indata; om du returnerar null lämnas den oförändrad.

enforce() styr ordningen mellan transformers: 'pre' körs först, 'post' sist och null (standardvärdet) däremellan i registreringsordning.

Skriva en transformer

Utöka Shikiphp\Transformer\AbstractTransformer så att du bara behöver åsidosätta de hookar du använder; resten gör ingenting. Transformer-kontexten ger åtkomst till addClassToHast() för att lägga till klasser på element.

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

Inbyggda transformers

Noteringstransformers

De här läser särskilda // [!code …]-kommentarer i källan (kommentarsyntaxen för språket identifieras automatiskt) och omvandlar dem till klasser, samtidigt som själva kommentaren tas bort. De är direkta portar av @shikijs/transformerss notationsuppsättning.

NotationHighlight

Shikiphp\Transformer\Notation\NotationHighlight — // [!code highlight] (eller // [!code hl]) lägger till klassen highlighted på sin rad.

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

NotationDiff

Shikiphp\Transformer\Notation\NotationDiff — // [!code ++] markerar en rad som tillagd (diff add) och // [!code --] som borttagen (diff remove).

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

NotationFocus

Shikiphp\Transformer\Notation\NotationFocus — // [!code focus] lägger till klassen focused.

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

NotationErrorLevel

Shikiphp\Transformer\Notation\NotationErrorLevel — // [!code error], // [!code warning] och // [!code info] lägger till klassen highlighted samt error / warning / info.

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

NotationWordHighlight

Shikiphp\Transformer\Notation\NotationWordHighlight — // [!code word:foo] (vid behov // [!code word:foo:2] för att begränsa till de följande N raderna) omsluter varje förekomst av foo i ett span med highlighted-word.

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

Metatransformatorer

Dessa läser kodstängslets metasträng som anges via meta-alternativet (meta['__raw']), på samma sätt som Shiki läser texten efter språket i ett kodblock med kodstängsel.

MetaHighlight

Shikiphp\Transformer\MetaHighlight — markerar rader som anges i ett metaintervall som {1,3-5} och lägger till klassen 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 — markerar ord som anges i metasträngen med syntaxen /word/ och lägger till highlighted-word.

Blanksteg och struktur

RenderWhitespace

Shikiphp\Transformer\RenderWhitespace — omsluter blanksteg och tabbtecken i span-element (klasserna space och tab som standard) så att de kan visas synligt. Konstruktorn tar (classSpace, classTab, position) där position är 'all' (standard), 'boundary', 'trailing' eller 'leading'.

CompactLineOptions

Shikiphp\Transformer\CompactLineOptions — tillämpar klasser på specifika rader från en lista med {line, classes} poster.

use Shikiphp\Transformer\CompactLineOptions;

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

Radnumreringen börjar på 1. Skicka objektet i alternativet transformers som vilken annan transformator som helst.

RemoveNotationEscape

Shikiphp\Transformer\RemoveNotationEscape — avkodar formen [\!code …] som används för att skriva en bokstavlig noteringskommentar utan att aktivera en noteringstransformator.

RemoveLineBreak

Shikiphp\Transformer\RemoveLineBreak — tar bort radbrytningstextnoderna mellan rader (Shikis transformerRemoveLineBreak).

StyleToClass

Shikiphp\Transformer\StyleToClass — flyttar inline-format till genererade klasser och samlar en formatmall som du hämtar med getCSS(). Klassnamnen hashas från formatet med Shikis cyrb53, så utdata är byteidentiska med @shikijs/transformers 4.2.0, inklusive dess omfattning:

• Stilen <pre> blir alltid en klass.
• Tokenintervall konverteras bara när de har en förbyggd stil, vilket är fallet med en themes-karta. Med en enda theme behåller tokenintervallen sin inline-style="color:…", precis som i 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

Konstruktorn tar (classPrefix, classSuffix, classReplacer); standardprefixet är __shiki_.