# API

Το shikiphp παρέχει δύο σημεία εισόδου: τη στατική πρόσοψη `Shikiphp` για τις συνήθεις περιπτώσεις και το στιγμιότυπο `Highlighter` για όλα τα υπόλοιπα (έξοδο HAST, προσαρμοσμένες γραμματικές και θέματα, παραλλαγές θεμάτων και διερεύνηση πακέτου).

## Η πρόσοψη `Shikiphp`

Το `Shikiphp\Shikiphp` είναι μια λεπτή στατική πρόσοψη πάνω από ένα αποθηκευμένο επισημαντή που περιλαμβάνεται στο πακέτο και δημιουργείται αργά.

### `Shikiphp::codeToHtml`

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

Κατακερματίζει το `$code` και αποδίδει ένα πλήρες block `<pre class="shiki …">` HTML. Ο πίνακας επιλογών περιέχει πάντα ένα `lang`, καθώς και είτε έναν χάρτη `theme` είτε `themes`, και οποιεσδήποτε από τις επιλογές απόδοσης [options](https://shikiphp.inline0.dev/el/docs/options).

```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
```

Επιστρέφει το βασικό δισδιάστατο πλέγμα διακριτικών (μία εσωτερική λίστα ανά γραμμή) από αντικείμενα `Shikiphp\Render\ThemedToken`, αντί για 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
```

Ψευδώνυμο του `codeToTokens` που ταιριάζει με το όνομα `codeToTokensBase` του Shiki.

### `Shikiphp::codeToTokensResult`

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

Επιστρέφει το εμπλουτισμένο αποτέλεσμα που αντιστοιχεί στο κορυφαίο `codeToTokens` του Shiki: το πλέγμα διακριτικών μαζί με τα επιλυμένα χρώματα, το όνομα θέματος, το ριζικό στυλ διπλού θέματος και την τελική κατάσταση γραμματικής. Δείτε παρακάτω το [`TokensResult`](#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
```

Αναλύει το `$code` και επιστρέφει την κατάσταση γραμματικής στο τέλος (το `getLastGrammarState` του Shiki). Περάστε την ξανά μέσω της επιλογής [`grammarState`](https://shikiphp.inline0.dev/el/docs/options) για να συνεχίσετε την ανάλυση ενός μεταγενέστερου τμήματος από την ίδια κατάσταση — χρήσιμο για σταδιακή επισήμανση. Προκαλεί εξαίρεση αν το `lang` είναι `'ansi'` (το ANSI δεν έχει κατάσταση γραμματικής).

```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
```

Επιστρέφει το κοινόχρηστο επισημαντή `Highlighter` που περιλαμβάνεται στο πακέτο, δημιουργώντας τον στην πρώτη χρήση. Χρησιμοποιήστε το για πρόσβαση στις μεθόδους στιγμιότυπου που ακολουθούν.

### `Shikiphp::use` και `Shikiphp::reset`

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

Το `use` αντικαθιστά το `Highlighter` με ένα προσαρμοσμένο (για παράδειγμα, με ένα στο οποίο έχετε φορτώσει προσαρμοσμένες γραμματικές ή θέματα), ώστε η πρόσοψη να το χρησιμοποιεί. Το `reset` εκκαθαρίζει το αποθηκευμένο στιγμιότυπο, ώστε η επόμενη κλήση να δημιουργήσει ξανά τον προεπιλεγμένο επισημαντή του πακέτου.

## Το `Highlighter`

Το `Shikiphp\Highlighter` παρέχει το πλήρες σύνολο δυνατοτήτων. Αποκτήστε το κοινόχρηστο στιγμιότυπο που περιλαμβάνεται στο πακέτο με το `Shikiphp::highlighter()` ή δημιουργήστε ένα ρητά:

```php
use Shikiphp\Highlighter;

$highlighter = Highlighter::createBundled();
```

Υλοποιεί τα `codeToHtml`, `codeToTokens`, `codeToTokensBase`,
`codeToTokensResult` και `getLastGrammarState` με τις ίδιες υπογραφές με το
facade, καθώς και τα εξής.

### `Highlighter::codeToHast`

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

Δημιουργεί το δέντρο HAST `pre.shiki > code > (span.line > span)*` που δημιουργεί το Shiki, έτοιμο
για να το διατρέξετε, να το τροποποιήσετε ή να το σειριοποιήσετε. Αυτό είναι που το `codeToHtml` σειριοποιεί
εσωτερικά.

```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
```

Δημιουργεί τα token μία φορά ανά θέμα και συγχωνεύει το αποτέλεσμα σε `variants` ανά token, με κλειδί το όνομα του θέματος, όπως και το Shiki `codeToTokensWithThemes`. Απαιτεί map `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` και `Highlighter::loadTheme`

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

public function loadTheme(array $rawTheme): void
```

Καταχωρίστε μια προσαρμοσμένη γραμματική TextMate ή ένα θέμα VS Code από αποκωδικοποιημένο JSON. Δείτε
[Προσαρμοσμένες γλώσσες και θέματα](https://shikiphp.inline0.dev/el/docs/custom-languages-themes).

### Επισκόπηση του 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` εμφανίζουν κάθε διαθέσιμο id (ενσωματωμένα και όσα προσαρμοσμένα έχετε καταχωρίσει). Τα `bundledLanguages`/`bundledThemes` εμφανίζουν μόνο τα id που περιλαμβάνονται στο πακέτο. Δείτε τις [Γλώσσες](https://shikiphp.inline0.dev/el/docs/languages) και τα
[Θέματα](https://shikiphp.inline0.dev/el/docs/themes).

## Αντικείμενα τιμών

### `ThemedToken`

Το `Shikiphp\Render\ThemedToken` είναι ένα μορφοποιημένο τμήμα κειμένου:

```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` είναι μάσκα bit από το `Shikiphp\Theme\FontStyle` (`NONE`, `ITALIC`,
`BOLD`, `UNDERLINE`, `STRIKETHROUGH`).

### `TokensResult`

Το `Shikiphp\TokensResult` είναι η τιμή επιστροφής του `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` περιέχει τη στοίβα κανόνων του tokenizer (με κλειδί το όνομα του θέματος), ώστε
να μπορεί να συνεχιστεί η επισήμανση από ένα ενδιάμεσο σημείο.

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