Formátovač

Phasis obsahuje natívny formátovač JavaScript založený na vlastnom analyzátore. Zdrojový kód vypíše nanovo s pravidlami rozloženia kompatibilnými s prettier, celý v PHP: bez Node.js, interpretovaných balíkov formátovača či externých procesov.

formatSource

public static function formatSource(
    string $source,
    string $sourceType = 'script',
    ?FormatOptions $options = null,
): string

Jednovolací vstupný bod v Phasis\Formatter\Formatter. Jazyk vyberá $sourceType: script alebo module pre JavaScript, json alebo css. JavaScript analyzuje kód podľa zadaného cieľa, znovu priradí komentáre a vypíše ho podľa nastavenej šírky riadka.

use Phasis\Formatter\Formatter;
use Phasis\Formatter\FormatOptions;

$formatted = Formatter::formatSource(
    "const a={x:1,y:2};",
    'script',
    new FormatOptions(useTabs: true, singleQuote: true),
);
// "const a = { x: 1, y: 2 };\n"

Neplatný zdrojový kód vyvolá rovnakú chybu Phasis\Exceptions\SyntaxError ako analyzátor, vrátane riadka, stĺpca a posunu.

FormatOptions

Možnosti rozloženia kopírujú 3.x prettier a predvolene používajú nastavenia prettier:

CSS

formatSource($css, 'css') formátuje štýly pomocou rozloženia štýlových súborov z prettier: v zoznamoch selektorov je jeden selektor na riadok, jedno deklarovanie na riadok, normalizované medzery pri kombinátoroch a hodnotách, jednoduché zoznamy hodnôt vyplnené na riadok, zoznamy tieňov a gradientov oddelené čiarkami po jednom na riadok, argumenty funkcií buď všetky na jednom riadku, alebo každý na samostatnom riadku, zachované prázdne riadky a komentáre a nezmenené úvody neznámych pravidiel at-rule, ako je Tailwind od @apply. Dlhé zložené selektory sa zalomia pri kombinátoroch potomkov a príliš dlhé argumenty pseudo-tried sa zalomia v zátvorkách.

JSON

formatSource($json, 'json') opätovne používa analyzátor a tlačiarne JavaScript s pravidlami JSON z prettier: kľúče zostávajú v úvodzovkách, reťazce zostávajú v dvojitých úvodzovkách bez ohľadu na singleQuote, koncové čiarky sa nikdy nepoužijú a komentáre // v dokumente sa zachovajú.

Pravidlá rozloženia

Tlačiareň implementuje model dokumentu z prettier: skupiny sa zreťazia, ak sa zmestia do šírky riadka, inak sa zalomia; argumenty volania priliehajú k záverečnému argumentu funkcie alebo objektu; reťazce prístupov k členom sa pri prekročení šírky zalomia pred každou bodkou; objekty zapísané na viacerých riadkoch zostanú viacriadkové a medzi príkazmi sa zachová najviac jeden prázdny riadok. Pri vstupe formátovanom pomocou prettier s rovnakými možnosťami je výstup bajtovo identický pre skutočný kód; testovacia súprava zhody to overuje na vzorových súboroch vytvorených priamo nástrojom prettier.

Komentáre

Komentáre sa zhromažďujú počas tokenizácie (Parser::setCollectComments(true), sprístupnené v analyzátore pre nástroje) a znovu sa pripájajú k stromu ako úvodné, záverečné alebo voľne pripojené komentáre. Riadkové komentáre zostávajú na vlastných riadkoch, záverečné komentáre na tom istom riadku zostávajú pri svojom príkaze, prázdne riadky okolo komentárov sa zachovajú a bloky /** ... */ sa znova odsadia tak, aby bol ich okraj * zarovnaný.

Záruky

Pre každý formátovaný výstup platia tri invarianty, ktoré vynucuje testovacia súprava:

• Výstup sa dá znova analyzovať na ekvivalentný program (bez ohľadu na umiestnenia).
• Všetky komentáre zo vstupu sa zachovajú vo výstupe.
• Formátovanie je idempotentné: opätovné formátovanie výstupu nič nezmení.

Výkon

Formátovanie je rýchle ako analýza: súbory z reálnej praxe sa naformátujú za desiatky milisekúnd a ručne napísaný JavaScript typického projektu sa v jednom procese naformátuje od začiatku do konca za výrazne menej než sekundu.