표준 포매팅

Stack은 어휘와 문법이 유효한 모든 문서에 하나의 표준 바이트 표현을 정의합니다. 포매팅은 언어 버전, 의미, 모든 줄 주석을 바꾸지 않고 diff를 일관되게 만듭니다.

포맷 가능한 소스

포매터는 BOM 없는 UTF-8을 받습니다. 어휘나 문법 오류가 있으면 진단만 반환하고 부분적으로 다시 쓴 소스를 반환하지 않습니다. 문법이 유효하면 의미나 복잡도 진단이 있어도 포맷할 수 있으며, 포맷 성공이 다이어그램 유효성을 뜻하지는 않습니다.

표준 출력

표준 소스는 다음을 따릅니다.

• BOM 없는 UTF-8을 사용합니다.
• 모든 줄바꿈을 LF로 정규화합니다.
• 블록 레벨마다 ASCII 공백 두 칸을 사용하고 포매팅 탭을 쓰지 않습니다.
• 줄 끝에 포매팅 공백이 없습니다.
• 정확히 하나의 LF로 끝납니다.
• 여는 중괄호는 선언 또는 layout 줄에, 닫는 중괄호는 별도 줄에 둡니다.
• 버전과 다이어그램, 인접한 body member 사이에 빈 줄 하나를 둡니다.
• 속성과 레이아웃 문장 사이에는 빈 줄을 두지 않습니다.

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]
  }
}

순서와 목록

포매터는 다이어그램과 그룹 member, 노드와 엣지 속성, 레이아웃 문장, 목록 식별자의 작성 순서를 보존합니다. 그룹화하거나 정렬하지 않습니다. 목록은 한 줄에 두고 쉼표 뒤 공백 하나, 대괄호 안쪽 공백 없음, 마지막 쉼표 없음으로 출력합니다.

문자열

유효 문자열을 디코드해 Unicode normalization 없이 UTF-8로 직접 출력합니다. 따옴표와 역슬래시는 이스케이프하고 표준 출력은 \uXXXX를 사용하지 않습니다. 예를 들어 "API \u56F3 \uD83D\uDE80"는 "API 図 🚀"가 됩니다.

주석

모든 줄 주석과 순서를 보존합니다. 뒤따르는 주석은 앞 token 뒤에 공백 하나를 두고 유지합니다. 독립 줄 주석은 token gap을 보존하며 뒤따르는 member, 문장, 속성 바로 앞에 둡니다. 구문 내부 주석은 이어지는 줄을 강제할 수 있고 이는 일반적인 한 줄 규칙의 유일한 예외입니다.

표준 소스를 다시 포맷하면 바이트 단위로 같은 결과가 나와야 합니다. Normalized IR이 존재할 때 포맷 전후 소스는 의미가 같은 IR을 생성해야 합니다.