Canonical formatting

Stackはlexically / syntactically validな各documentに、1つのcanonical byte representationを定義します。Formattingはlanguage version、semantic meaning、line commentを変えず、diffを一定にします。

Formatできるsource

FormatterはBOMなしUTF-8を受け取ります。Lexical/syntax error時はdiagnosticだけを返し、partial formatted sourceを返しません。Syntaxがvalidならsemantic/complexity diagnosticがあってもformatできます。Format成功はdiagramのvalidityを意味しません。

Canonical output

Canonical sourceは次の規則に従います。

• BOMなしUTF-8を使う。
• 全line endingをLFへ正規化する。
• Block levelごとにASCII space 2つを使い、formatting tabを使わない。
• Line末尾のformatting whitespaceを置かない。
• 最後はちょうど1 LFにする。
• Opening braceはdeclarationまたはlayout行、closing braceは単独行に置く。
• Versionとdiagram、bodyの隣接member間に1 empty lineを置く。
• Propertyとlayout statement間にはempty lineを置かない。

stack 1.0

diagram "Title" {
  theme dark

  node client "Client"

  node api "API" {
    kind service
    detail "Public API"
  }

  edge client -> api "HTTPS" {
    kind request
  }

  layout {
    direction right
    order [client, api]
  }
}

Orderとlist

Formatterはdiagram/group member、node/edge property、layout statement、list identifierのauthored orderを保持します。Group化やsortはしません。Listは1行でcomma後に1 space、bracket内側にspaceなし、trailing commaなしです。

String

Valid stringをdecodeし、Unicode normalizationせずUTF-8で直接出力します。Quoteとbackslashはescapeし、canonical outputは\uXXXXを使いません。たとえば"API \u56F3 \uD83D\uDE80"は"API 図 🚀"になります。

Comment

すべてのline commentと順序を保持します。Trailing commentは直前tokenの後へ1 spaceで続きます。Own-line commentはtoken gapを保ち、後続member、statement、propertyの直前に置きます。Construct内commentはcontinuation lineを強制でき、通常のone-line ruleに対する唯一の例外です。

Canonical sourceを再formatした結果はbyte-identicalでなければなりません。Normalized IRがある場合、format前後でsemantically equalなIRを生成します。