Vormindaja

Vaata Markdownina Muuda teenuses GitHub Dokumentatsioon: 5b53f69

Phasis sisaldab algupärast JavaScript vormindajat, mis põhineb oma parseril. See prindib lähtekoodi uuesti prettieriga ühilduva paigutusega, täielikult PHP: pole vaja Node.js, tõlgendatud vormindajapakette ega väliseid protsesse.

formatSource

PHP

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

Ühe väljakutsega sisenemispunkt Phasis\Formatter\Formatter-is. $sourceType valib keele: script või module vastavalt sellele, kas tegu on JavaScript, json või css-ga. JavaScript parsib määratud eesmärgi järgi, lisab kommentaarid tagasi ja prindib seadistatud reavahe laiuse järgi.

PHP

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"

Vigane lähtekood põhjustab sama Phasis\Exceptions\SyntaxError vea nagu parseris, koos rea, veeru ja nihkega.

FormatOptions

Paigutuse valikud järgivad prettier 3.x-i ja kasutavad vaikimisi prettieri vaikeväärtusi:

Valik	Vaikeväärtus	Tähendus
`printWidth`	`80`	Sihtrea laius, mille järgi paigutus kohandatakse.
`tabWidth`	`2`	Tühikuid taande taseme kohta (ja tabulaatori mõõdetud laius).
`useTabs`	`false`	Taanda tühikute asemel tabulaatoritega.
`semi`	`true`	Lausete semikoolonid.
`singleQuote`	`false`	Eelista `'` vormingule `"`, kui see nõuab vähem paomärke.
`trailingComma`	`'all'`	`'all'`, `'es5'` või `'none'`.
`bracketSpacing`	`true`	Objektisuludesse jäävad tühikud: `{ a }` versus `{a}`.
`arrowParens`	`'always'`	`'always'` või `'avoid'` ühe parameetriga noolefunktsioonide puhul.

CSS

formatSource($css, 'css') vormindab stiililehed prettieri stiililehepaigutuse järgi: valijaloendis üks valija rea kohta, üks deklaratsioon rea kohta, normaliseeritud kombinaatorite ja väärtuste vahed, lihtsate väärtuste loendite täitmine ridade kaupa, varjude ja gradientide komaloendid üks väärtus rea kohta, funktsiooniargumendid kõik või mitte midagi, tühjade ridade ja kommentaaride säilitamine ning tundmatute at-reeglite, näiteks Tailwind @apply-i päiste puutumata jätmine. Pikad liitvalijad murtakse järeltulevate kombinaatorite kohalt ja liiga pikad pseudoklassi argumendid murtakse sulgude sees.

JSON

formatSource($json, 'json') kasutab JavaScript parserit ja printereid koos prettieri JSON-reeglitega: võtmed jäävad jutumärkidesse, stringid jäävad singleQuote-ist olenemata topeltjutumärkidesse, lõpukomasid ei lisata ja dokumendi sees olevad // kommentaarid säilivad.

Paigutuse semantika

Printer rakendab prettieri dokumendimudelit: rühmad tasandatakse, kui need mahuvad prindilaiuse sisse, ja murtakse muul juhul; väljakutseargumendid paigutuvad lõpus oleva funktsiooni- või objektiargumendi lähedale; liikmeahelad murtakse enne iga punkti, kui need kasvavad reast pikemaks; mitmele reale kirjutatud objektid jäävad mitmerealiseks ja lausete vahele säilitatakse maksimaalselt üks tühi rida. Prettieriga vormindatud sisend annab samade valikute korral päris koodis bait-baidilt identse tulemuse; vastavustest kontrollib seda täpselt prettieri enda loodud näidisfailidega.

Kommentaarid

Kommentaarid kogutakse tokeniseerimise käigus (Parser::setCollectComments(true), parseris tööriistadele kättesaadavad) ja seotakse puuga uuesti juhtivate, järgnevate või eraldiseisvate manustena. Reakommentaarid jäävad oma ridadele, samal real olevad lõpukommentaarid jäävad lause juurde, kommentaaride ümber olevad tühjad read säilivad ning /** ... */ plokid taandatakse uuesti nii, et nende * veeris joondub.

Garantii

Iga vormindatud väljundi puhul kehtib kolm invarianti, mida testikomplekt kontrollib:

Väljund parsitakse samaväärseks programmiks (asukohad välja arvatud).
Kõik sisendi kommentaarid säilivad väljundis.
Vormindamine on idempotentne: vormindatud väljundi vormindamine ei muuda midagi.

Jõudlus

Vormindamine toimub parseri kiirusel: päris failide vormindamiseks kulub kümneid millisekundeid ja tüüpilise projekti käsitsi kirjutatud JavaScript vormindatakse otsast lõpuni ühe protsessiga tublisti alla sekundiga.