Trivia

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.

$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ě:

$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->hasCommentUpTo($other);   // komentář kdekoli mezi dvěma tokeny
$node->hasComment();              // komentář uvnitř uzlu, kromě jeho okrajů
$node->getDocComment();           // dokumentační komentář nad uzlem, jako Trivia
$token->getLineWidth($style);     // šířka řádku tak, jak ji vidíte, tabulátor podle stylu

Zápis

Trivia tokenu se přepisují jako celek přes setLeadingTrivia() a setTrailingTrivia(), ale skoro nikdy to není potřeba, protože běžné úpravy mají vlastní metody, které dodrží pravidlo o tom, komu mezera patří:

$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->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é.

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.