구현하는 사람을 위해

English · 한국어

정본은 영문 매뉴얼이고, 이 문서는 그 번역입니다.

세 구현 가운데 하나를 고치거나 네 번째 구현을 쓰는 사람을 위한 쪽입니다.

적합성 사례

conformance/ 에는 모든 구현이 통과해야 하는 사례가 있습니다(명세 부록 B).

경로	규칙
`conformance/accept/NAME.lows`	받아들여야 합니다
`conformance/accept/NAME.dump`	그 정규 덤프, 바이트 단위로 같아야 합니다
`conformance/accept/NAME.json`	처음 열 사례에만 있는, 손으로 쓴 보기. Python 시험이 독립된 기준으로 대조합니다
`conformance/reject/NAME.lows`	첫 줄 `rem expect E-LOWS-…` 의 코드로 거부해야 합니다

사례는 바이트 단위로 정확합니다. 일부러 CRLF, 홀로 선 CR, BOM, NUL, 잘못된 UTF-8 을 담은 것이 있습니다. .gitattributes 가 Git 의 변환을 막으니, 줄 끝을 바꾸는 도구로 고치지 마십시오.

정규 덤프

부동소수를 글자로 옮기는 방법이 언어마다 달라서, 구현은 줄 단위 덤프로 서로 견줍니다.

lowstruct-dump 1
server.port int 8080
ratio float 3fe0000000000000
name  str x:6869
units u_str [65,66]
flag  empty

잎마다 한 줄, 소스 순서로 깊이 먼저: 점으로 이은 경로, 탭, 종류, 탭, 그리고 공백으로 가른 값입니다. 부동소수는 binary64 비트를 십육진으로, 바이트 문자열은 x: 와 십육진으로 적습니다. 전체 규칙은 명세 부록 C 에 있습니다.

모두 돌리기

tools/test-all.sh           # Python, Node.js, C 를 적합성 사례에 대고
tools/test-all.sh --fuzz    # 아래의 차분 퍼즈까지

차분 퍼즈

tools/difffuzz.py [반복 수] [시드] 는 적합성 사례를 변형하고 토큰을 무작위로 섞어 만든 입력을 세 구현에 모두 넣습니다. 셋은 같은 덤프, 또는 같은 오류 코드·줄·열을 내야 합니다. 어긋난 입력은 다시 돌려 볼 수 있게 build/fuzz/ 에 남습니다. cc 와 node 가 경로에 있어야 합니다.

릴리스 만들기

c/include/lowstruct.h, js/package.json, js/src/index.js, python/pyproject.toml, python/lowstruct/__init__.py, 명세의 판 번호를 고치고, CHANGELOG.md 항목을 그 판 아래로 옮깁니다.
이 머신에서(cd c && ../build/nob), 그리고 MinGW-w64 가 있는 곳에서 Windows 용으로(../build/nob windows) 빌드하고, Windows 에서 두 시험 프로그램을 적합성 파일과 함께 돌립니다.
tools/site/build-site.sh 가 docs/ 의 웹 매뉴얼과 build/site/ 의 매뉴얼 PDF 둘을 다시 만듭니다(Typst 와 스크립트에 적힌 글꼴 필요). PDF 는 릴리스에 붙입니다.
tools/package.sh 가 C 묶음, Node.js·Python 설치 zip 팩, SHA256SUMS 를 build/dist/ 에 씁니다. 패키지 레지스트리에는 아무것도 올리지 않습니다.

규칙을 더하거나 결함을 고칠 때

먼저 conformance/ 에 사례를 더합니다. 수용 사례면 .dump 와 함께, 거부 사례면 rem expect 줄과 함께.
세 구현이 tools/test-all.sh 를 통과하게 합니다. 세 구현은 일부러 같은 순서(파일 검사, 파일 전체의 토큰, 문장)로 짜여 있어서, 고치는 모양도 대개 셋이 비슷합니다.
tools/test-all.sh --fuzz 를 돌리고, C 는 -fsanitize=address,undefined 로 지어 봅니다.
명세를 영문으로 고치고, 그다음 한국어 번역을 고칩니다.

기대 덤프는 손으로 쓰거나, 한 구현으로 뽑은 뒤 한 줄씩 확인합니다. 시험받는 코드가 만든 덤프는 그것만으로는 아무것도 증명하지 않습니다.

네 번째 구현을 쓸 때

명세를 읽고, 파서를 conformance/ 에 대고 돌리십시오. 자주 틀리는 곳은 이렇습니다.

수 갈래의 순서(십육진 부동소수, 십진 부동소수, 십육진, 이진, 십진)와, 수 바로 뒤에 영문자·숫자·_ 가 오면 안 된다는 규칙
문자열은 먼저 바이트로 만들고, 그다음에 접두사가 바이트·UTF-16 유닛·코드포인트를 고릅니다
십육진 부동소수는 서브노멀까지 포함해 가장 가까운 짝수로 반올림해야 합니다
열은 바이트도 UTF-16 유닛도 아닌 코드포인트로 셉니다
파일 어디에 있든 어휘 오류가 그보다 앞의 구조 오류보다 먼저입니다
맨 앞의 BOM 은 오류입니다 — 어떤 디코더는 조용히 떼어 버립니다
__proto__ 같은 키도 평범한 이름입니다

← C 라이브러리 명세 →

구현하는 사람을 위해#

적합성 사례#

정규 덤프#

모두 돌리기#

차분 퍼즈#

릴리스 만들기#

규칙을 더하거나 결함을 고칠 때#

네 번째 구현을 쓸 때#