# Opcje

Wszystkie punkty wejścia (`codeToHtml`, `codeToTokens`, `codeToTokensResult`,
`codeToHast`) przyjmują tę samą tablicę opcji jako drugi argument. Wymagane są tylko `lang`
i motyw.

## `lang`

**Wymagane.** Identyfikator języka lub alias używany do tokenizacji — `php`, `ts`, `js`,
`rust`, `python`, `html` itd. Specjalna wartość `'ansi'` wyróżnia
sekwencje ucieczki terminala zamiast używać gramatyki (zobacz [ANSI](https://shikiphp.inline0.dev/pl/docs/ansi)).

```php
['lang' => 'php']
```

## `theme`

Pojedynczy identyfikator motywu. Wymagany, chyba że podano `themes`.

```php
['lang' => 'php', 'theme' => 'github-dark']
```

## `themes`

Mapa kluczy na identyfikatory motywów dla wyjścia z jednym (lub wieloma) motywami za pomocą zmiennych CSS.
Wymagane, chyba że podano `theme`.

```php
['lang' => 'ts', 'themes' => ['light' => 'github-light', 'dark' => 'github-dark']]
```

## `defaultColor`

Który klucz w `themes` staje się domyślnym kolorem wbudowanym w kod (pozostałe stają się zmiennymi
`--shiki-<key>` CSS). Domyślnie `'light'`. Ustaw na `false`, aby generować
wyłącznie zmienne, bez domyślnego koloru wbudowanego — przydatne, gdy wszystkie kolory kontrolujesz z poziomu
CSS.

```php
['themes' => ['light' => '…', 'dark' => '…'], 'defaultColor' => 'dark']
```

## `transformers`

Lista obiektów `Shikiphp\Transformer\Transformer` stosowanych w potoku.
Zobacz [Transformery](https://shikiphp.inline0.dev/pl/docs/transformers).

```php
use Shikiphp\Transformer\Notation\NotationHighlight;

['transformers' => [new NotationHighlight()]]
```

## `decorations`

Stosuj klasy lub atrybuty do dowolnych zakresów źródła, określonych położeniem wiersza lub znaku.
Każda dekoracja ma postać `{start, end, properties}`, gdzie pozycje są `{line, character}` (liczone od zera).

```php
['decorations' => [
    [
        'start'      => ['line' => 0, 'character' => 0],
        'end'        => ['line' => 0, 'character' => 5],
        'properties' => ['class' => 'highlight'],
    ],
]]
```

## `colorReplacements`

Zmienia mapowanie kolorów w wyjściu. Wpisy tekstowe globalnie zastępują kolor; wpisy zagnieżdżone, których kluczem jest nazwa motywu, dotyczą tylko tego motywu.

```php
['colorReplacements' => [
    '#ffffff'      => '#f8f8f2',          // global
    'github-dark'  => ['#24292e' => '#000'], // only in github-dark
]]
```

## `structure`

`'classic'` (domyślnie) generuje pełną strukturę `pre > code > span.line > span`.
`'inline'` generuje tylko zakresy tokenów wraz z podziałem na wiersze, bez otaczających elementów
`pre`/`code` — przydatne dla fragmentów w tekście.

```php
['structure' => 'inline']
```

## `tabindex`

Atrybut `tabindex` elementu `<pre>`. Domyślnie `0`. Przekaż `false`,
aby go pominąć.

```php
['tabindex' => false]
```

## `cssVariablePrefix`

Prefiks używany dla zmiennych CSS przy dwóch motywach. Domyślnie `'--shiki-'`.

```php
['cssVariablePrefix' => '--my-']
```

## `mergeWhitespaces`

Określa sposób obsługi tokenów białych znaków. `true` (domyślnie) łączy tokeny zawierające wyłącznie białe znaki z następującym po nich tokenem; `'never'` rozdziela początkowe i końcowe białe znaki każdego tokenu na osobne tokeny; `false` pozostawia tokeny bez zmian.

```php
['mergeWhitespaces' => 'never']
```

## `tokenizeMaxLineLength`

Pomija tokenizację (i emituje pojedynczy zwykły token) dla każdego wiersza o długości równej lub większej od tej wartości,
wyrażonej w 16-bitowych jednostkach kodu Unicode. Domyślnie brak limitu. Zabezpieczenie przed patologicznymi
wejściami jednowierszowymi.

```php
['tokenizeMaxLineLength' => 1000]
```

## `meta`

Dowolne metadane przekazywane transformerom przez kontekst transformera —
na przykład metadane ciągu po znaczniku kodu, używane przez
[`MetaHighlight`](https://shikiphp.inline0.dev/pl/docs/transformers#metahighlight) i
[`MetaWordHighlight`](https://shikiphp.inline0.dev/pl/docs/transformers#metawordhighlight).

```php
['meta' => ['__raw' => '{1,3-5}']]
```

## `grammarState`

A `Shikiphp\GrammarState` (z `getLastGrammarState`) służy do wznowienia tokenizacji
od wskazanego miejsca. Przenoszone wartości `lang` i theme(s) muszą być zgodne. Zobacz
[`getLastGrammarState`](https://shikiphp.inline0.dev/pl/docs/api#shikiphpgetlastgrammarstate).