Hoppa till innehåll

API

Visa som Markdown Redigera på GitHub Dokumentation på 22946a5

shikiphp har två ingångspunkter: den statiska fasaden Shikiphp för de vanliga fallen och instansen Highlighter för allt annat (HAST-utdata, anpassade grammatiker och teman, temavarianter samt inspektion av paketet).

Fasaden Shikiphp

Shikiphp\Shikiphp är en tunn statisk fasad ovanpå en buntad highlighter som skapas vid behov och cachas.

Shikiphp::codeToHtml

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

Tokeniserar $code och återger ett komplett <pre class="shiki …">-block med HTML. Alternativmatrisen innehåller alltid en lang samt antingen en theme eller en themes-mappning och valfria alternativ för återgivning.

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

Returnerar det avskalade 2D-tokenrutnätet (en inre lista per rad) med objekt av typen Shikiphp\Render\ThemedToken i stället för 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

Ett alias för codeToTokens som motsvarar namnet codeToTokensBase i Shiki.

Shikiphp::codeToTokensResult

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

Returnerar det fullständiga resultatet som speglar toppnivå-codeToTokens i Shiki: tokenrutnätet samt de lösta färgerna, temanamnet, rotstilen för dubbeltemat och grammatiktillståndet i slutet. Se TokensResult nedan.

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

Tokeniserar $code och returnerar grammatiktillståndet som nås i slutet (getLastGrammarState i Shiki). Skicka tillbaka det via alternativet grammarState för att fortsätta tokenisera ett senare fragment från samma tillstånd — användbart vid inkrementell markering. Ger fel om lang är 'ansi' (ANSI har inget grammatiktillstånd).

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

Returnerar den gemensamma buntade instansen av Highlighter och skapar den vid första användningen. Använd den för att komma åt instansmetoderna nedan.

Shikiphp::use och Shikiphp::reset

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

use byter till en anpassad Highlighter (till exempel en som du har läst in anpassade grammatiker eller teman i), så att fasaden delegerar till den. reset rensar den cachade instansen så att nästa anrop bygger om standard-highlightern från paketet.

Highlighter

Shikiphp\Highlighter omfattar hela gränssnittet. Hämta den gemensamma buntade instansen med Shikiphp::highlighter() eller skapa en explicit:

PHP
use Shikiphp\Highlighter;

$highlighter = Highlighter::createBundled();

Den implementerar codeToHtml, codeToTokens, codeToTokensBase, codeToTokensResult och getLastGrammarState med samma signaturer som fasaden, samt följande.

Highlighter::codeToHast

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

Bygger det pre.shiki > code > (span.line > span)* HAST-träd Shiki bygger, redo för att du själv ska kunna gå igenom, ändra eller serialisera det. Det här är vad codeToHtml serialiserar internt.

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

Tokeniserar en gång per tema och slår ihop resultatet i per-token-variants, nycklade efter temanyckel, i likhet med Shikis codeToTokensWithThemes. Kräver en themes-karta.

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 och Highlighter::loadTheme

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

public function loadTheme(array $rawTheme): void

Registrera en anpassad TextMate-grammatik eller ett VS Code-tema från avkodad JSON. Se Anpassade språk och teman.

Granskning av paketets innehåll

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 rapporterar alla id:n som går att använda för närvarande (paketerade plus eventuella egna som du har registrerat). bundledLanguages/bundledThemes rapporterar endast id:n som ingår i paketet. Se Språk och Teman.

Värdeobjekt

ThemedToken

Shikiphp\Render\ThemedToken är en formaterad textsekvens:

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 är en bitmask från Shikiphp\Theme\FontStyle (NONE, ITALIC, BOLD, UNDERLINE, STRIKETHROUGH).

TokensResult

Shikiphp\TokensResult är returvärdet från 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 innehåller tokeniserarens regelstack (nycklad efter temanamn), så markeringen kan återupptas från en mellanliggande punkt.

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;
}