Trivia
******

.[perex]
Bílé znaky a komentáře nejsou uzly, ale trivia přivěšená k tokenům. Pravidlo, podle kterého se dělí, a jak je číst a psát, aniž by se rozbil zbytek souboru.


Komu patří mezera
=================

Mezi dvěma tokeny může být cokoli: mezery, konce řádků, prázdné řádky, komentáře. Aby se dalo o tom všem mluvit přesně, má každý token dvě pole trivia a jedno pravidlo říká, co kam patří:

**Koncová trivia** tokenu je všechno za ním až po první konec řádku včetně. **Úvodní trivia** dalšího tokenu je zbytek: prázdné řádky, odsazení, komentáře na vlastních řádcích, dokumentační komentáře.

```php
$sum = 0; // running total
		return $sum;
```

Středník za `0` má koncová trivia `[Whitespace " ", Comment "// running total", EndOfLine "\n"]`; `return` má úvodní trivia `[Whitespace "\t\t"]`. Komentář na řádku patří k řádku, na kterém je, a dokumentační komentář nad metodou patří k metodě, což je přesně to, co byste čekali, když se metoda přesouvá.

Každá trivia má druh (`TriviaKind::Whitespace`, `EndOfLine`, `Comment`, `DocComment`, `OpenTag`), text a řádek v původním souboru. Bílé znaky jsou rozdělené na běhy mezer a jednotlivé konce řádků, takže úvodní trivia tokenu, který začíná řádek, vypadá `[..., EndOfLine, Whitespace]` a prázdný řádek je `EndOfLine` následovaný `EndOfLine`.

Tři zvláštnosti, které stojí za zapamatování:

- **`<?php` není token**, ale trivia druhu `OpenTag` včetně povinné mezery nebo konce řádku za ním; je vždy úvodní trivia následujícího tokenu.
- **`?>` je token** (`TokenKind::CloseTag`), který si nese i konec řádku, jenž PHP za ním polyká; parser ho vidí jako středník.
- **Bílé znaky, které PHP počítá do tokenu, zůstávají v textu tokenu**: inline HTML, obsah heredocu včetně odsazení uzavíracího návěští, `( int )`. Trivia uvnitř interpolovaného řetězce (`"{$a /* c */}"`) nesou `inInterpolation` a metody na úpravu trivia je odmítnou, protože ta mezera je součást hodnoty řetězce.


Čtení
=====

Nejčastější otázky mají hotové odpovědi, aby nikdo nemusel procházet pole trivia ručně:

```php
$token->getTrailingSpace();       // vodorovná mezera za tokenem na témže řádku, null když řádek končí nebo je tam komentář
$token->startsLine();             // začíná řádek
$token->getLineIndentation();     // odsazení řádku, na kterém token stojí
$token->hasComment();             // komentář v jeho trivia
$token->getComments();            // ty komentáře jako pole Trivia
$token->hasCommentUpTo($other);   // komentář kdekoli mezi dvěma tokeny
$node->hasComment();              // komentář uvnitř uzlu, kromě jeho okrajů
$node->getComments();
$node->getDocComment();           // dokumentační komentář nad uzlem, jako Trivia
$token->getLineWidth($style);     // šířka řádku tak, jak ji vidíte, tabulátor podle stylu
```

Sama trivia komentáře odpoví na to, čím je, a vydá svůj text bez značek:

```php
$comment->isLineComment();    // // nebo #
$comment->isDocComment();     // /** */
$comment->isMultiLine();
$comment->getCommentText();   // 'running total'
```


Zápis
=====

Text a trivia tokenu jsou `private(set)`, takže se mění jen metodami; jsou to metody a ne vlastnosti proto, že `?->` nesmí stát vlevo od přiřazení, a `$node->getFirstToken()?->setText('x')` je zápis, který se používá pořád. Trivia jde přepsat celá (`setLeadingTrivia()`, `setTrailingTrivia()`), ale skoro nikdy to není potřeba: běžné úpravy mají vlastní metody, které dodrží pravidlo o tom, komu mezera patří.

```php
$token->setTrailingSpace(' ');        // mezera za tokenem; odmítne, když řádek končí nebo následuje komentář
$token->ensureLeadingNewline();       // token na vlastní řádek, konec řádku jde do koncových trivia předchozího tokenu
$token->setBlankLinesBefore(2);       // přesně dva prázdné řádky nad tokenem, nad komentářem, který k němu patří
$token->setIndentation("\t\t");       // odsazení řádku tokenu; token musí řádek začínat
$token->removeTrailingWhitespace();   // mezery na konci řádku, který token končí; komentář a konec řádku zůstanou
$token->removeTrivia($comment);       // jedna trivia, obvykle komentář, i s mezerou nebo řádkem, které by po ní zbyly
$token->replaceTrivia($old, $new);    // výměna na místě
$node->setEdgeTrivia(leading: []);    // trivia na vnějších okrajích uzlu, kde první nebo poslední token nemusí být
$node->replaceDocComment($trivia);    // dokumentační komentář uzlu
$node->removeDocComment();
```

Jedno pravidlo je za tím vším: **konec řádku, který uzavírá řádek tokenu, patří do jeho koncových trivia, nikdy do úvodních trivia dalšího tokenu.** Kdo ho dá jinam, rozbije `getTrailingSpace()` a všechno, co na něm stojí; kdo staví na `ensureLeadingNewline()` a `setBlankLinesBefore()`, má to za sebe vyřešené.

Vlastnost s hookem nesnese nepřímou změnu, takže `end($token->trailingTrivia)` potřebuje kopii pole, ne referenci na vlastnost.


Styl a odsazení
===============

`Style` je odsazovací jednotka, konec řádku a šířka tabulátoru souboru: výchozí tabulátor, `"\n"` a 4. `Style::detectEol($code)` pozná převládající konec řádku, `withIndent()` a `withEol()` odvodí styl, `indent($level)` vrátí odsazení dané úrovně.

`Indentation` je pomocník nad odsazením celého řádku včetně komentářů nad tokenem: `Indentation::set($token, $indentation, $commentIndentation)` odsadí řádek i komentáře nad ním, `normalize()` převede odsazení do znaků stylu, `opensLine($token)` řekne, zda je konec řádku nad tokenem trivia (a odsazení tedy smí měnit), nebo text (za inline HTML, heredocem, `?>`), kde je odsazení součástí obsahu. `findOwner()`, `findRole()` a `infer()` odpovídají na otázku, co řádek pokračuje a jaké odsazení by takový řádek konvenčně měl; na nich stojí rozvržení kódu podle stromu.