Transformatorji

Transformatorji omogočajo preoblikovanje označenega izhoda na vsaki stopnji — od izvornega niza prek mreže žetonov do končnega drevesa HAST in HTML. shikiphp prenaša model transformatorjev Shiki po vseh priklopih, zato se transformatorji obnašajo enako kot njihovi ustrezniki v JavaScript.

Podajte jih prek možnosti 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(),
    ],
]);

Cevovod

Vsak transformator je objekt, ki implementira Shikiphp\Transformer\Transformer. Cevovod izvede priklope po vrsti med pripravo enega bloka:

Vsi priklopi so neobvezni. Če vrnete vrednost, ta nadomesti vhod; če vrnete null, ostane nespremenjen.

enforce() nadzira vrstni red transformatorjev: 'pre' se izvede prvi, 'post' zadnji, null (privzeto) pa vmes, po vrstnem redu registracije.

Pisanje transformatorja

Razširite Shikiphp\Transformer\AbstractTransformer, da preglasite samo potrebne priklope; ostali ne naredijo ničesar. Kontekst transformatorja omogoča dostop do addClassToHast() za dodajanje razredov elementom.

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

Vgrajeni transformatorji

Transformatorji zapisa

Ti berejo posebne komentarje // [!code …] v izvorni kodi (skladnja komentarjev jezika se zazna samodejno) in jih pretvorijo v razrede, sam komentar pa odstranijo. Gre za neposreden prenos nabora zapisov @shikijs/transformers.

NotationHighlight

Shikiphp\Transformer\Notation\NotationHighlight — // [!code highlight] (ali // [!code hl]) doda razred highlighted svoji vrstici.

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

NotationDiff

Shikiphp\Transformer\Notation\NotationDiff — // [!code ++] označi vrstico kot dodano (diff add), // [!code --] pa kot odstranjeno (diff remove).

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

NotationFocus

Shikiphp\Transformer\Notation\NotationFocus — // [!code focus] doda razred focused.

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

NotationErrorLevel

Shikiphp\Transformer\Notation\NotationErrorLevel — // [!code error], // [!code warning] in // [!code info] dodajo razred highlighted ter error / warning / info.

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

NotationWordHighlight

Shikiphp\Transformer\Notation\NotationWordHighlight — // [!code word:foo] (po želji // [!code word:foo:2] za omejitev na naslednjih N vrstic) ovije vsako pojavitve niza foo v element span z atributom highlighted-word.

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

Pretvorniki metapodatkov

Ti berejo metapodatkovni niz ograje kode, podan prek meta (meta['__raw']), podobno kot Shiki bere besedilo za jezikom v ograjenem bloku kode.

MetaHighlight

Shikiphp\Transformer\MetaHighlight — poudari vrstice, navedene v obsegu metapodatkov, na primer {1,3-5}, in doda razred 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 — poudari besede, navedene v metapodatkovnem nizu s sintakso /word/, in doda highlighted-word.

Presledki in struktura

RenderWhitespace

Shikiphp\Transformer\RenderWhitespace — ovije presledke in tabulatorje v elemente span (privzeta razreda sta space in tab), da jih je mogoče vidno prikazati. Konstruktor sprejme (classSpace, classTab, position), kjer je position 'all' (privzeto), 'boundary', 'trailing' ali 'leading'.

CompactLineOptions

Shikiphp\Transformer\CompactLineOptions — uporabi razrede za določene vrstice s seznama vnosov {line, classes}.

use Shikiphp\Transformer\CompactLineOptions;

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

Številčenje vrstic se začne z 1. Objekt podajte v možnosti transformers, tako kot kateri koli drug pretvornik.

RemoveNotationEscape

Shikiphp\Transformer\RemoveNotationEscape — odstrani ubežne znake iz oblike [\!code …], ki se uporablja za zapis komentarja z dobesednim zapisom notacije, ne da bi sprožila pretvornik notacije.

RemoveLineBreak

Shikiphp\Transformer\RemoveLineBreak — odstrani besedilna vozlišča prelomov vrstic med vrsticami (transformerRemoveLineBreak za Shiki).

StyleToClass

Shikiphp\Transformer\StyleToClass — premakne vgrajene sloge v ustvarjene razrede in zbere slogovno predlogo, ki jo pridobite z getCSS(). Imena razredov zgoščujejo slog z uporabo cyrb53 za Shiki, zato je izhod bajt za bajtom enak kot pri @shikijs/transformers 4.2.0, vključno z njegovim obsegom:

• Slog <pre> vedno postane razred.
• Razponi žetonov se pretvorijo le, če vsebujejo vnaprej pripravljen slog, kar velja pri preslikavi themes. Pri enem samem theme razponi žetonov ohranijo vgrajeni style="color:…", tako kot v 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

Konstruktor sprejme (classPrefix, classSuffix, classReplacer); privzeta predpona je __shiki_.