Pārveidotāji

Pārveidotāji ļauj pārveidot izcelto izvadi katrā posmā — no neapstrādātas avota virknes līdz tokenu režģim, galīgajam HAST kokam un HTML. shikiphp pārņem Shiki pārveidotāju modeli, saglabājot katru āķi, tāpēc pārveidotāji darbojas tāpat kā to JavaScript līdzinieki.

Padodiet tos, izmantojot opciju 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(),
    ],
]);

Darbplūsma

Katrs pārveidotājs ir objekts, kas implementē Shikiphp\Transformer\Transformer. Veidojot vienu bloku, konveijers secīgi izsauc šos āķus:

Visi āķi nav obligāti. Atgriežot vērtību, ievade tiek aizstāta; atgriežot null, tā paliek nemainīga.

enforce() nosaka secību starp pārveidotājiem: 'pre' darbojas pirmais, 'post' darbojas pēdējais, bet null (pēc noklusējuma) darbojas pa vidu reģistrēšanas secībā.

Pārveidotāja izveide

Paplašiniet Shikiphp\Transformer\AbstractTransformer, lai pārrakstītu tikai nepieciešamos āķus; pārējie nedara neko. Transformatora konteksts nodrošina addClassToHast() elementu klašu pievienošanai.

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

Iebūvētie pārveidotāji

Apzīmējumu pārveidotāji

Tie nolasa avotā īpašus // [!code …] komentārus (komentāru sintakse tiek automātiski noteikta pēc valodas) un pārvērš tos klasēs, pašu komentāru noņemot. Tie ir tiešs @shikijs/transformers apzīmējumu kopas ports.

NotationHighlight

Shikiphp\Transformer\Notation\NotationHighlight — // [!code highlight] (vai // [!code hl]) pievieno rindai klasi highlighted.

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

NotationDiff

Shikiphp\Transformer\Notation\NotationDiff — // [!code ++] atzīmē rindu kā pievienotu (diff add), bet // [!code --] — kā noņemtu (diff remove).

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

NotationFocus

Shikiphp\Transformer\Notation\NotationFocus — // [!code focus] pievieno klasi focused.

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

NotationErrorLevel

Shikiphp\Transformer\Notation\NotationErrorLevel — // [!code error], // [!code warning] un // [!code info] pievieno klasi highlighted, kā arī error / warning / info.

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

NotationWordHighlight

Shikiphp\Transformer\Notation\NotationWordHighlight — // [!code word:foo] (neobligāti norādiet // [!code word:foo:2], lai ierobežotu līdz nākamajām N rindām); katru foo sastopamības vietu aptver span elements ar klasi highlighted-word.

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

Meta pārveidotāji

Tie nolasa koda bloka meta virkni, kas padota ar opciju meta (meta['__raw']), līdzīgi kā Shiki nolasa tekstu aiz iežogota koda bloka valodas nosaukuma.

MetaHighlight

Shikiphp\Transformer\MetaHighlight — izceļ meta diapazonā norādītās rindas, piemēram, {1,3-5}, pievienojot klasi 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 — izceļ meta virknē norādītos vārdus, izmantojot sintaksi /word/, un pievieno highlighted-word.

Atstarpes un struktūra

RenderWhitespace

Shikiphp\Transformer\RenderWhitespace — aptver atstarpes un tabulācijas rakstzīmes ar span elementiem (pēc noklusējuma klases space un tab), lai tās varētu redzami atveidot. Konstruktors pieņem (classSpace, classTab, position), kur position ir 'all' (pēc noklusējuma), 'boundary', 'trailing' vai 'leading'.

CompactLineOptions

Shikiphp\Transformer\CompactLineOptions — piešķir klases noteiktām rindām, balstoties uz {line, classes} ierakstu sarakstu.

use Shikiphp\Transformer\CompactLineOptions;

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

Rindu numerācija sākas ar 1. Padodiet objektu opcijā transformers tāpat kā jebkuru citu pārveidotāju.

RemoveNotationEscape

Shikiphp\Transformer\RemoveNotationEscape — atkodē [\!code …] formu, ko izmanto, lai uzrakstītu burtisku apzīmējuma komentāru un neiedarbinātu apzīmējumu pārveidotāju.

RemoveLineBreak

Shikiphp\Transformer\RemoveLineBreak — noņem rindu pārtraukumu teksta mezglus starp rindām (Shiki transformerRemoveLineBreak).

StyleToClass

Shikiphp\Transformer\StyleToClass — pārceļ iekļautos stilus uz ģenerētām klasēm un apkopo stilu lapu, ko varat iegūt ar getCSS(). Klašu nosaukumos stila jaucējvērtība tiek aprēķināta ar Shiki cyrb53, tāpēc izvade ir byte-for-byte identiska @shikijs/transformers 4.2.0 izvadei, ieskaitot tās tvērumu:

• <pre> stils vienmēr kļūst par klasi.
• Tokenu span elementi tiek pārveidoti tikai tad, ja tiem ir iepriekš izveidots stils, kā tas ir themes atbilstības kartes gadījumā. Ja ir viens theme, tokenu span elementi saglabā savu iekļauto style="color:…", tāpat kā Shiki gadījumā.

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

Konstruktors pieņem (classPrefix, classSuffix, classReplacer); noklusējuma prefikss ir __shiki_.