Vai al contenuto

API

Visualizza come Markdown Modifica su GitHub Documentazione di 22946a5

shikiphp espone due punti di accesso: la facciata statica Shikiphp per i casi comuni e l’istanza Highlighter per tutto il resto (output HAST, grammatiche e temi personalizzati, varianti dei temi e introspezione del bundle).

La facciata Shikiphp

Shikiphp\Shikiphp è una facciata statica essenziale sopra un highlighter bundled, creato e memorizzato nella cache quando serve.

Shikiphp::codeToHtml

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

Analizza $code e genera un blocco <pre class="shiki …"> HTML completo. L’array di opzioni include sempre un lang, oltre a una mappa theme o themes e a qualsiasi opzione di rendering.

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

Restituisce la griglia di token 2D essenziale (una lista interna per riga) di oggetti Shikiphp\Render\ThemedToken anziché 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

Un alias di codeToTokens che corrisponde al nome codeToTokensBase di Shiki.

Shikiphp::codeToTokensResult

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

Restituisce il risultato completo che rispecchia codeToTokens di primo livello di Shiki: la griglia di token, i colori risolti, il nome del tema, lo stile radice dei temi chiaro e scuro e lo stato finale della grammatica. Vedi TokensResult più avanti.

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

Analizza $code e restituisce lo stato della grammatica raggiunto al termine (getLastGrammarState di Shiki). Passatelo all’opzione grammarState per riprendere l’analisi di un frammento successivo dallo stesso stato, utile per l’evidenziazione incrementale. Genera un errore se lang è 'ansi' (ANSI non ha uno stato della grammatica).

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

Restituisce l’istanza bundled condivisa di Highlighter, creandola al primo utilizzo. Usatela per accedere ai metodi dell’istanza descritti di seguito.

Shikiphp::use e Shikiphp::reset

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

use sostituisce l’istanza Highlighter con una personalizzata (per esempio, una in cui avete caricato grammatiche o temi personalizzati), così che la facciata la usi. reset svuota la cache dell’istanza, in modo che la chiamata successiva ricrei l’highlighter bundled predefinito.

La Highlighter

Shikiphp\Highlighter offre tutte le funzionalità. Ottenete l’istanza bundled condivisa con Shikiphp::highlighter() oppure createne una esplicitamente:

PHP
use Shikiphp\Highlighter;

$highlighter = Highlighter::createBundled();

Implementa codeToHtml, codeToTokens, codeToTokensBase, codeToTokensResult e getLastGrammarState con le stesse firme della facciata, oltre a quanto segue.

Highlighter::codeToHast

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

Genera l'albero HAST esatto di pre.shiki > code > (span.line > span)*, come le build di Shiki, pronto per essere esplorato, modificato o serializzato. È ciò che codeToHtml serializza internamente.

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

Analizza una volta per tema e unisce il risultato in una variants per token, indicizzata per chiave del tema, rispecchiando codeToTokensWithThemes di Shiki. Richiede una mappa 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 e Highlighter::loadTheme

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

public function loadTheme(array $rawTheme): void

Registrate una grammatica TextMate o un tema VS Code personalizzato da JSON decodificato. Vedi Lingue e temi personalizzati.

Introspezione del bundle

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 riportano tutti gli ID attualmente utilizzabili (inclusi quelli bundled e quelli personalizzati registrati). bundledLanguages/bundledThemes riportano solo gli ID inclusi nel pacchetto. Vedi Lingue e Temi.

Oggetti valore

ThemedToken

Shikiphp\Render\ThemedToken è una sequenza di testo con uno stile:

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 è una maschera di bit di Shikiphp\Theme\FontStyle (NONE, ITALIC, BOLD, UNDERLINE, STRIKETHROUGH).

TokensResult

Shikiphp\TokensResult è il valore restituito da 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 contiene lo stack di regole del tokenizer (indicizzato per nome del tema), così da poter riprendere l’evidenziazione da un punto intermedio.

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