Preskoči na vsebino

API

Prikaži kot Markdown Uredi na GitHub Dokumentacija za 22946a5

shikiphp ponuja dve vstopni točki: statično fasado Shikiphp za običajne primere in primerek Highlighter za vse ostalo (izhod HAST, gramatike in teme po meri, različice tem ter pregled svežnjev).

Fasada Shikiphp

Shikiphp\Shikiphp je tanka statična fasada nad predpomnjenim razčlenjevalnikom označevanja v svežnju, ki se ustvari z zakasnitvijo.

Shikiphp::codeToHtml

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

Tokenizira $code in izriše celoten blok <pre class="shiki …"> HTML. Polje možnosti vedno vsebuje lang ter bodisi theme bodisi preslikavo themes in katere koli možnosti za izris.

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

Vrne golo 2D-mrežo žetonov (po en notranji seznam za vsako vrstico) z objekti Shikiphp\Render\ThemedToken namesto 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

Vzdevek za codeToTokens, ki ustreza imenu codeToTokensBase v Shiki.

Shikiphp::codeToTokensResult

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

Vrne podroben rezultat, ki odraža vrhnji codeToTokens v Shiki: mrežo žetonov, razrešene barve, ime teme, korenski slog dveh tem in končno stanje gramatike. Glejte spodaj: 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

Tokenizira $code in vrne stanje gramatike ob koncu (Shiki, njegov getLastGrammarState). Podajte ga nazaj prek možnosti grammarState, da nadaljujete tokenizacijo poznejšega odlomka iz istega stanja — uporabno za postopno poudarjanje. Sproži napako, če je lang enak 'ansi' (ANSI nima stanja gramatike).

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

Vrne skupni vključeni Highlighter in ga ustvari ob prvi uporabi. To uporabite za klicanje spodnjih metod instance.

Shikiphp::use in Shikiphp::reset

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

use zamenja primerek Highlighter po meri (na primer takšnega, v katerega ste naložili gramatike ali teme po meri), da mu fasada preda izvajanje. reset izbriše predpomnjeni primerek, zato naslednji klic znova sestavi privzeti razčlenjevalnik označevanja v svežnju.

Highlighter

Shikiphp\Highlighter ponuja celoten vmesnik. Skupni primerek iz svežnja pridobite z Shikiphp::highlighter() ali pa ga izrecno ustvarite:

PHP
use Shikiphp\Highlighter;

$highlighter = Highlighter::createBundled();

Izvaja codeToHtml, codeToTokens, codeToTokensBase, codeToTokensResult in getLastGrammarState z enakimi podpisi kot fasada, poleg tega pa še naslednje.

Highlighter::codeToHast

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

Zgradi drevo HAST pre.shiki > code > (span.line > span)*, ki ga zgradi Shiki, pripravljeno za sprehod, spreminjanje ali serializacijo. To je tisto, kar codeToHtml serializira interno.

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

Tokenizira enkrat za vsako temo in združi rezultat v variants za posamezne žetone, indeksirane po ključu teme, po vzoru ShikicodeToTokensWithThemes. Zahteva zemljevid themes.

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

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

public function loadTheme(array $rawTheme): void

Registrirajte slovnico po meri TextMate ali temo VS Code iz dekodiranega JSON. Oglejte si Jeziki in teme po meri.

Pregled vsebine paketa

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 izpišeta vsak trenutno uporaben ID (vgrajen in vse po meri, ki ste jih registrirali). bundledLanguages/bundledThemes izpišeta samo ID-je, vključene v paket. Oglejte si Jezike in Teme.

Vrednostni objekti

ThemedToken

Shikiphp\Render\ThemedToken je en oblikovan odsek besedila:

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 je bitna maska iz Shikiphp\Theme\FontStyle (NONE, ITALIC, BOLD, UNDERLINE, STRIKETHROUGH).

TokensResult

Shikiphp\TokensResult je vrnjena vrednost funkcije 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 hrani sklad pravil tokenizatorja (indeksiran po imenu teme), da se lahko označevanje nadaljuje od vmesne točke.

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