Formatavimo įrankis

Phasis turi vietinį JavaScript formatavimo įrankį, sukurtą naudojant nuosavą analizatorių. Jis perrašo šaltinio kodą pagal prettier suderinamas išdėstymo taisykles, visiškai PHP: nereikia Node.js, interpretuojamų formatavimo paketų ar išorinių procesų.

formatSource

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

Vieno iškvietimo įvesties taškas Phasis\Formatter\Formatter. $sourceType parenka kalbą: script arba module, skirtą JavaScript, json arba css. JavaScript analizuoja pagal nurodytą tikslą, vėl prideda komentarus ir spausdina pagal sukonfigūruotą eilutės plotį.

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"

Netinkamas šaltinio kodas sukelia tą pačią Phasis\Exceptions\SyntaxError kaip ir analizatorius; nurodoma eilutė, stulpelis ir poslinkis.

FormatOptions

Išdėstymo parinktys atitinka prettier 3.x, o pagal numatytuosius nustatymus naudojamos prettier numatytosios reikšmės:

CSS

formatSource($css, 'css') formatuoja stilių lenteles pagal prettier stilių lentelių išdėstymą: kiekvienas selektorius sąraše rašomas atskiroje eilutėje, kiekviena deklaracija taip pat atskiroje eilutėje, normalizuojami jungtukų ir reikšmių tarpai, paprasti reikšmių sąrašai glaudžiai sudėliojami, šešėlių ir gradientų sąrašų elementai atskiriami kableliais ir rašomi po vieną eilutėje, funkcijų argumentai laužomi visi kartu arba nė vienas, išsaugomos tuščios eilutės ir komentarai, o nežinomų at-rules, pavyzdžiui, Tailwind @apply, pradžios tekstas paliekamas nepakeistas. Ilgi sudėtiniai selektoriai laužomi ties žemyn nukreiptais jungtukais, o per ilgi pseudoklasės argumentai perkeliami į kelias eilutes skliaustų viduje.

JSON

formatSource($json, 'json') pakartotinai naudoja JavaScript analizatorių ir spausdintuvus su prettier JSON taisyklėmis: raktai lieka kabutėse, eilutės visada lieka dvigubose kabutėse, nepaisant singleQuote, kableliai gale niekada nenaudojami, o dokumento viduje esantys // komentarai išsaugomi.

Išdėstymo taisyklės

Spausdintuvas įgyvendina prettier dokumento modelį: grupės sutraukiamos į vieną eilutę, kai telpa į spausdinimo plotį, o kitu atveju laužomos; iškvietimo argumentai glaudžiai priglunda prie pabaigoje esančio funkcijos arba objekto argumento; narių grandinės laužomos prieš kiekvieną tašką, kai netelpa eilutėje; keliose eilutėse parašyti objektai lieka kelių eilučių; tarp teiginių išsaugoma ne daugiau kaip viena tuščia eilutė. Kai parinktys sutampa, prettier suformatuotas įvesties kodas realiuose projektuose išvedamas identiškas baitas į baitą; atitikties testų rinkinys tai tikrina naudodamas pačios prettier sugeneruotus pavyzdžius.

Komentarai

Komentarai surenkami skaidymo į žetonus metu (Parser::setCollectComments(true), pateikiami analizatoriuje įrankiams) ir vėl pridedami prie medžio kaip priekyje, gale arba atskirai esantys komentarai. Eilučių komentarai lieka savo eilutėse, tos pačios eilutės galiniai komentarai lieka prie savo teiginio, išsaugomos tuščios eilutės aplink komentarus, o /** ... */ blokai įtraukiami iš naujo, sulygiuojant jų * paraštes.

Garantijos

Testų rinkinys užtikrina tris kiekvieno suformatuoto rezultato invariantus:

• Išvestis išanalizuojama į lygiavertę programą (išskyrus vietas).
• Kiekvienas įvesties komentaras išsaugomas išvestyje.
• Formatavimas yra idempotentinis: pakartotinis suformatuotos išvesties formatavimas nieko nekeičia.

Našumas

Formatavimas vyksta analizatoriaus greičiu: realūs failai suformatuojami per keliasdešimt milisekundžių, o tipinis ranka rašytas JavaScript projektas viename procese suformatuojamas nuo pradžios iki galo gerokai greičiau nei per sekundę.