Ga naar de inhoud

API

Bekijken als Markdown Bewerken op GitHub Documentatie op 22946a5

shikiphp biedt twee toegangspunten: de statische facade Shikiphp voor de gebruikelijke gevallen en de instantie Highlighter voor al het andere (HAST-uitvoer, aangepaste grammatica's en thema's, thema-varianten en bundelinspectie).

De facade Shikiphp

Shikiphp\Shikiphp is een dunne statische facade rond een lazy aangemaakte, gecachete gebundelde highlighter.

Shikiphp::codeToHtml

PHP
public static function codeToHtml(string $code, array $options): string

Tokeniseert $code en geeft een volledig <pre class="shiki …">-HTML-blok weer. De opties-array bevat altijd een lang, plus een theme of themes-map en eventuele weergaveopties.

PHP
use Shikiphp\Shikiphp;

echo Shikiphp::codeToHtml($code, ['lang' => 'php', 'theme' => 'github-dark']);

Shikiphp::codeToTokens

PHP
/** @return list<list<ThemedToken>> */
public static function codeToTokens(string $code, array $options): array

Retourneert het onbewerkte 2D-tokengrid (één binnenlijst per regel) van Shikiphp\Render\ThemedToken-objecten in plaats van HTML.

PHP
use Shikiphp\Shikiphp;

$lines = Shikiphp::codeToTokens($code, ['lang' => 'js', 'theme' => 'nord']);

foreach ($lines as $line) {
    foreach ($line as $token) {
        // $token->content, $token->color, $token->fontStyle,
        // $token->bgColor, $token->htmlStyle, $token->offset
    }
}

Shikiphp::codeToTokensBase

PHP
/** @return list<list<ThemedToken>> */
public static function codeToTokensBase(string $code, array $options): array

Een alias van codeToTokens die overeenkomt met de naam codeToTokensBase van Shiki.

Shikiphp::codeToTokensResult

PHP
public static function codeToTokensResult(string $code, array $options): TokensResult

Retourneert het uitgebreide resultaat dat de bovenste codeToTokens van Shiki weerspiegelt: het tokengrid plus de opgeloste kleuren, themanaam, rootstijl voor dubbele thema's en de uiteindelijke grammaticastatus. Zie verderop TokensResult.

PHP
use Shikiphp\Shikiphp;

$result = Shikiphp::codeToTokensResult($code, [
    'lang'  => 'php',
    'theme' => 'github-dark',
]);

$result->tokens;       // list<list<ThemedToken>>
$result->fg;           // "#e1e4e8"
$result->bg;           // "#24292e"
$result->themeName;    // "github-dark"
$result->grammarState; // GrammarState

Shikiphp::getLastGrammarState

PHP
public static function getLastGrammarState(string $code, array $options): GrammarState

Tokeniseert $code en retourneert de grammaticastatus aan het einde (de getLastGrammarState van Shiki). Geef deze terug via de optie grammarState om een later fragment verder te tokeniseren vanaf dezelfde status — handig voor incrementele markering. Genereert een fout als lang gelijk is aan 'ansi' (ANSI heeft geen grammaticastatus).

PHP
use Shikiphp\Shikiphp;

$state = Shikiphp::getLastGrammarState("/* unterminated comment", [
    'lang'  => 'js',
    'theme' => 'nord',
]);

$html = Shikiphp::codeToHtml("still inside the comment */", [
    'lang'         => 'js',
    'theme'        => 'nord',
    'grammarState' => $state,
]);

Shikiphp::highlighter

PHP
public static function highlighter(): Highlighter

Retourneert de gedeelde gebundelde Highlighter en maakt deze aan bij het eerste gebruik. Gebruik dit om toegang te krijgen tot de instantiemethoden hieronder.

Shikiphp::use en Shikiphp::reset

PHP
public static function use(Highlighter $highlighter): void
public static function reset(): void

use vervangt de instantie door een aangepaste Highlighter (bijvoorbeeld een waarin u aangepaste grammatica's of thema's hebt geladen), zodat de facade deze gebruikt. reset wist de gecachete instantie, zodat de volgende aanroep de standaard gebundelde highlighter opnieuw opbouwt.

De Highlighter

Shikiphp\Highlighter biedt de volledige interface. Haal de gedeelde gebundelde instantie op met Shikiphp::highlighter() of maak er zelf een:

PHP
use Shikiphp\Highlighter;

$highlighter = Highlighter::createBundled();

Deze implementeert codeToHtml, codeToTokens, codeToTokensBase, codeToTokensResult en getLastGrammarState met dezelfde signaturen als de facade, plus het volgende.

Highlighter::codeToHast

PHP
public function codeToHast(string $code, array $options): \Shikiphp\Hast\Element

Bouwt de exacte HAST-structuur pre.shiki > code > (span.line > span)* die Shiki opbouwt, klaar om zelf te doorlopen, aan te passen of te serialiseren. Dit is wat codeToHtml intern serialiseert.

PHP
use Shikiphp\Shikiphp;

$hast = Shikiphp::highlighter()->codeToHast($code, [
    'lang'  => 'rust',
    'theme' => 'nord',
]);

Highlighter::codeToTokensWithThemes

PHP
/** @return list<list<ThemedTokenWithVariants>> */
public function codeToTokensWithThemes(string $code, array $options): array

Tokeniseert eenmaal per thema en voegt het resultaat samen tot een variants per token, gesleuteld op themasleutel, overeenkomstig de codeToTokensWithThemes van Shiki. Vereist een themes-map.

PHP
use Shikiphp\Shikiphp;

$lines = Shikiphp::highlighter()->codeToTokensWithThemes($code, [
    'lang'   => 'ts',
    'themes' => ['light' => 'github-light', 'dark' => 'github-dark'],
]);

$lines[0][0]->content;            // token text
$lines[0][0]->variants['light'];  // ThemedTokenStyle for the light theme
$lines[0][0]->variants['dark'];   // ThemedTokenStyle for the dark theme

Highlighter::loadGrammar en Highlighter::loadTheme

PHP
public function loadGrammar(
    array $rawTmLanguage,
    ?string $langId = null,
    array $aliases = [],
    array $embedded = [],
): void

public function loadTheme(array $rawTheme): void

Registreer een aangepaste TextMate-grammatica of een VS Code-thema uit gedecodeerde JSON. Zie Aangepaste talen en thema's.

Bundelinspectie

PHP
/** @return list<string> */ public function loadedLanguages(): array
/** @return list<string> */ public function loadedThemes(): array
/** @return list<string> */ public function bundledLanguages(): array
/** @return list<string> */ public function bundledThemes(): array

loadedLanguages/loadedThemes rapporteren elke ID die momenteel bruikbaar is (gebundeld plus alle aangepaste die u hebt geregistreerd). bundledLanguages/bundledThemes rapporteren alleen de ID's die in het pakket zijn opgenomen. Zie Talen en Thema's.

Waardeobjecten

ThemedToken

Shikiphp\Render\ThemedToken is één opgemaakte tekstpassage:

PHP
final class ThemedToken
{
    public readonly string $content;
    public readonly ?string $color;
    public readonly int $fontStyle;      // FontStyle bitmask
    public readonly ?string $bgColor;
    public readonly ?string $htmlStyle;  // pre-built inline style (dual themes / ANSI)
    public readonly int $offset;         // UTF-16 code-unit offset into the source
}

fontStyle is een bitmasker van Shikiphp\Theme\FontStyle (NONE, ITALIC, BOLD, UNDERLINE, STRIKETHROUGH).

TokensResult

Shikiphp\TokensResult is het resultaat van codeToTokensResult:

PHP
final class TokensResult
{
    public readonly array $tokens;             // list<list<ThemedToken>>
    public readonly ?string $fg;               // resolved foreground
    public readonly ?string $bg;               // resolved background
    public readonly ?string $themeName;        // single id, or "shiki-themes …"
    public readonly string|false|null $rootStyle; // dual-theme root style (or null)
    public readonly ?GrammarState $grammarState;
}

GrammarState

Shikiphp\GrammarState bevat de regelstack van de tokenizer (gesleuteld op themanaam), zodat de markering vanaf een tussenliggend punt kan worden hervat.

PHP
final class GrammarState
{
    public readonly string $lang;

    public function theme(): string;          // first theme name
    public function themes(): array;          // list<string>
    public function getScopes(?string $theme = null): array; // scopes in effect, innermost first
    public function withTheme(string $theme): self;
}