Formatētājs

Phasis nodrošina iebūvētu JavaScript formatētāju, kas veidots uz tā parsētāja bāzes. Tas pārveido pirmkodu atbilstoši prettier saderīga izkārtojuma semantikai, pilnībā izmantojot PHP: bez Node.js, bez interpretētām formatētāju pakotnēm un bez ārējiem procesiem.

formatSource

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

Vienas izsaukšanas ievades punkts vietnē Phasis\Formatter\Formatter. $sourceType izvēlas valodu: script vai module, ja formatējat JavaScript, json vai css. JavaScript parsē kodu norādītajā režīmā, pievieno atpakaļ komentārus un izdrukā to atbilstoši konfigurētajam rindas platumam.

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"

Nederīgs pirmkods izraisa tādu pašu Phasis\Exceptions\SyntaxError kļūdu kā parsētājā, norādot rindu, kolonnu un nobīdi.

FormatOptions

Izkārtojuma opcijas atbilst prettier 3.x opcijām, un pēc noklusējuma tiek izmantotas prettier noklusējuma vērtības:

CSS

formatSource($css, 'css') formatē stila lapas, izmantojot prettier stila lapu izkārtojumu: selektoru sarakstos katrs selektors ir savā rindā, katrs deklarējums ir savā rindā, kombinatoru un vērtību atstarpes tiek normalizētas, vienkāršu vērtību saraksti tiek aizpildīti līdz rindas platumam, ēnu un gradientu komatatdalīti saraksti tiek sadalīti pa rindām, funkciju argumenti tiek pārvietoti visi kopā, tiek saglabātas tukšās rindas un komentāri, bet nezināmu at-rules, piemēram, Tailwind @apply, priekšteksti paliek nemainīti. Garus saliktos selektorus sadala pie pēcteču kombinatoriem, savukārt pārāk garus pseidoklašu argumentus aplauž iekavās.

JSON

formatSource($json, 'json') izmanto to pašu JavaScript parsētāju un drukātājus, ievērojot prettier JSON kārtulas: atslēgas paliek pēdiņās, virknes vienmēr ir pēdiņās, neatkarīgi no singleQuote, komats beigās netiek pievienots un dokumentā esošie // komentāri tiek saglabāti.

Izkārtojuma semantika

Drukātājs īsteno prettier dokumenta modeli: grupas tiek saplacinātas, ja ietilpst rindas platumā, un citādi sadalītas rindās; izsaukuma argumenti cieši piekļaujas pēdējam funkcijas vai objekta argumentam; ķēdes posmi tiek sadalīti pirms katra punkta, ja tie pārsniedz rindas platumu; vairākrindu formātā rakstīti objekti paliek vairākās rindās; starp priekšrakstiem tiek saglabāta ne vairāk kā viena tukša rinda. Ja prettier formatēts kods tiek ievadīts ar tām pašām opcijām, formatētāja rezultāts reālam kodam ir identisks baitu pa baitam; tā atbilstības testu kopa to pārbauda ar pašā prettier ģenerētiem testa datiem.

Komentāri

Komentāri tiek apkopoti tokenizācijas laikā (Parser::setCollectComments(true), parsētājs tos atklāj rīkiem) un atkārtoti pievienoti kokam kā sākuma, beigu vai brīvi novietoti pielikumi. Rindas komentāri paliek savās rindās, tās pašas rindas beigu komentāri paliek pie sava priekšraksta, tiek saglabātas tukšās rindas ap komentāriem, un /** ... */ bloki tiek atkārtoti formatēti ar līdzinātu * malu.

Garantijas

Testu kopa nodrošina trīs invariantu izpildi katrai formatētajai izvadei:

• Izvadi var atkārtoti parsēt kā līdzvērtīgu programmu (neņemot vērā atrašanās vietas).
• Visi ievades komentāri ir saglabāti izvadē.
• Formatēšana ir idempotenta: atkārtoti formatējot formatētu izvadi, nekas nemainās.

Veiktspēja

Formatēšana notiek parsētāja ātrumā: īsti faili tiek formatēti dažu desmitu milisekunžu laikā, bet tipiska projekta pašrocīgi rakstītais JavaScript vienā procesā no sākuma līdz beigām tiek formatēts krietni mazāk nekā sekundē.