# Opzioni

Tutti i punti di ingresso (`codeToHtml`, `codeToTokens`, `codeToTokensResult`,
`codeToHast`) accettano lo stesso array di opzioni come secondo argomento. Sono obbligatori solo `lang`
e un tema.

## `lang`

**Obbligatorio.** L'id o l'alias della lingua da usare per suddividere il codice in token: `php`, `ts`, `js`,
`rust`, `python`, `html` e così via. Il valore speciale `'ansi'` evidenzia
le sequenze di escape del terminale invece di usare una grammatica (consultate [ANSI](https://shikiphp.inline0.dev/it/docs/ansi)).

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

## `theme`

Un singolo id tema. Obbligatorio se non viene fornito `themes`.

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

## `themes`

Una mappa di chiavi e id dei temi per generare output con temi doppi (o multipli) tramite variabili CSS.
Obbligatoria se non viene fornito `theme`.

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

## `defaultColor`

Quale chiave di `themes` diventa il colore predefinito in linea (le altre diventano
variabili `--shiki-<key>` CSS). Il valore predefinito è `'light'`. Impostatela su `false` per generare
solo variabili, senza un colore predefinito in linea: utile se controllate tutti i colori da
CSS.

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

## `transformers`

Un elenco di oggetti `Shikiphp\Transformer\Transformer` applicati attraverso la
pipeline. Consultate [Transformer](https://shikiphp.inline0.dev/it/docs/transformers).

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

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

## `decorations`

Applicate classi o attributi a intervalli arbitrari del codice sorgente, in base alla posizione di riga/carattere.
Ogni decorazione è `{start, end, properties}`; le posizioni sono `{line, character}` (a base zero).

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

## `colorReplacements`

Rimappate i colori nell'output. Le voci stringa sostituiscono globalmente un colore; le voci annidate,
indicate con il nome del tema, si applicano solo a quel tema.

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

## `structure`

`'classic'` (predefinito) genera la struttura `pre > code > span.line > span` completa.
`'inline'` genera solo gli intervalli dei token con interruzioni di riga, senza elementi `pre`/`code`
di contenimento: utile per frammenti in linea.

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

## `tabindex`

L'attributo `tabindex` sull'elemento `<pre>`. Il valore predefinito è `0`. Passate `false`
per ometterlo.

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

## `cssVariablePrefix`

Il prefisso usato per le variabili CSS dei temi doppi. Il valore predefinito è `'--shiki-'`.

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

## `mergeWhitespaces`

Controlla la gestione dei token di spaziatura. `true` (predefinito) accorpa i token composti solo da spazi con il token successivo; `'never'` suddivide gli spazi iniziali e finali di ogni token in token autonomi; `false` lascia invariati i token.

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

## `tokenizeMaxLineLength`

Salta la tokenizzazione e genera un unico token di testo semplice per ogni riga di lunghezza pari o superiore a questo valore, espresso in unità di codice UTF-16. Nessun limite per impostazione predefinita. Protegge da input patologici su una sola riga.

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

## `meta`

Metadati arbitrari passati ai transformer tramite il contesto del transformer:
per esempio, la stringa meta del code fence utilizzata da
[`MetaHighlight`](https://shikiphp.inline0.dev/it/docs/transformers#metahighlight) e
[`MetaWordHighlight`](https://shikiphp.inline0.dev/it/docs/transformers#metawordhighlight).

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

## `grammarState`

Un `Shikiphp\GrammarState` (da `getLastGrammarState`) per riprendere la tokenizzazione
un punto preciso. I valori mantenuti in `lang` e theme(s) devono corrispondere. Consultate
[`getLastGrammarState`](https://shikiphp.inline0.dev/it/docs/api#shikiphpgetlastgrammarstate).