TOML 테이블이 JSON 객체가 되는 방법: [table], [[array]] 및 점으로 구분된 키

중첩은 어디에서 왔습니까? — 깊게 중첩된 JSON로 변환된 평면적인 TOML 파일과 이를 발생시킨 헤더

TOML 파일은 대괄호에 중첩이 있기 때문에 거의 평평하게 나타날 수 있습니다. `[a.b.c]`은 중간 테이블을 열므로 그 아래의 `d = 1`는 `{"a":{"b":{"c":{"d":1}}}}`이 됩니다. JSON 중괄호는 TOML가 활성 테이블 경로를 통해 표현하는 계층 구조를 표시합니다.

ToolAcre는 구문 분석을 smol-toml에 위임한 다음 JSON이 전달할 수 없는 값을 정규화합니다. 이는 라인 기반 재작성이 아닙니다. 테이블, 점으로 구분된 키 및 테이블 배열은 JSON 직렬화 이전에 일반 개체 및 배열이 되므로 해당 철자와 주석을 출력에서 ​​사용할 수 없습니다.

[table] 헤더 — 헤더가 중첩 객체를 여는 방법과 [a.b.c]가 암시적으로 중간 객체를 생성하는 방법

단일 대괄호 헤더는 테이블을 엽니다. `[owner]`는 다음 할당을 `owner`에 지시합니다. `[owner.contact]`는 중첩된 연락처 개체를 생성하거나 입력합니다. 중간 개체에는 별도의 헤더가 필요하지 않습니다. 해당 존재는 헤더의 경로 세그먼트에서 이어집니다.

헤더 앞의 할당은 루트에 유지됩니다. 이후 테이블은 소급하여 테이블을 이동하지 않습니다. 변환된 JSON을(를) 검토할 때 줄 사이의 물리적 거리가 아닌 전체 속성 경로를 따르세요. TOML의 현재 테이블은 다른 헤더가 변경될 때까지 활성 상태로 유지됩니다.

[[테이블 배열]] — 반복되는 이중 대괄호 헤더가 객체를 배열에 추가하는 이유와 유지되는 순서

이중 대괄호 헤더는 테이블을 배열에 추가합니다. 두 개의 `[[server]]` 섹션은 소스 순서대로 `server: [{...},{...}]`이 됩니다. 각 헤더 아래의 필드는 다른 헤더가 시작될 때까지 해당 배열 멤버에 속하므로 JSON에서 반복되는 구성이 명시적으로 지정됩니다.

배열 내부의 순서는 데이터이며 보존됩니다. 옵션을 선택하면 개체 키 표시가 나중에 정렬될 수 있지만 배열 구성원은 다시 정렬되지 않습니다. 두 가지를 혼동하면 단순히 문서 형식을 지정하는 것이 아니라 서버 우선 순위나 플러그인 순서가 변경됩니다.

점으로 구분된 키 및 인라인 테이블 — 동일한 중첩을 표현하는 두 가지 방법으로 a.b = 1 및 { x = 1 }

점으로 구분된 할당은 또 다른 경로 표기법을 제공합니다. `a.b.c = true`는 해당 테이블 헤더와 동일한 중첩 개체 모양을 생성합니다. `point = { x = 1, y = 2 }`과 같은 인라인 테이블은 즉시 중첩 개체가 됩니다. 이러한 양식은 검토자에게는 매우 다르게 보이지만 비슷한 나무를 설명할 수 있습니다.

JSON는 결과 키와 값만 기록하며 TOML 표기법으로 작성된 값은 기록하지 않습니다. 따라서 다시 변환하면 헤더, 점으로 구분된 키 및 인라인 테이블 중에서 원래 선택을 복원할 수 없습니다. TOML 작성자는 트리에서 자체적으로 유효한 직렬화를 선택합니다.

전달되는 유형과 그렇지 않은 유형 — 정수, 부동 소수점, 부울 및 문자열이 직접 매핑됩니다. 날짜-시간은 문자열이 되고 JSON null에는 TOML 소스가 없습니다.

문자열, 안전한 정수, 부동 소수점, 부울, 배열 및 테이블은 직접 매핑됩니다. TOML의 네 가지 시간 유형은 오프셋 날짜-시간, 현지 날짜-시간, 현지 날짜 및 현지 시간이 RFC 3339과 유사한 소스 문자열이 되지 않으며 경고에는 각 경로와 종류의 이름이 지정됩니다. 작성자는 나중에 날짜/시간 토큰을 다시 생성하는 대신 해당 문자열을 인용합니다.

TOML의 부호 있는 64비트 정수는 JavaScript의 안전한 정수 범위를 초과할 수 있습니다. smol-toml은 필요할 때 BigInt와 같은 값을 반환합니다. ToolAcre는 이를 십진수 문자열로 변환하고 숫자를 반올림하는 대신 경고합니다. 이는 JSON 유형을 변경하는 대신 철자를 유지합니다.

작업된 예: pyproject.toml — [project], [project.ional-dependents] 및 [[tool.plugins]] 목록이 추적된 각 레벨과 함께 JSON로 변환되었습니다.

`name = "demo"`, `[project]`, `dependencies = ["a", "b"]`, `[project.optional]`, `test = ["vitest"]`를 시도한 다음 고유한 이름을 가진 두 개의 `[[tool.plugins]]` 테이블을 시도하십시오. JSON는 루트에 이름을 배치하고 프로젝트와 선택 사항을 중첩하며 도구 아래에 플러그인 배열을 생성합니다.

`released = 1979-05-27` 및 `huge = 9223372036854775807`을 추가합니다. 첫 번째는 `1979-05-27` 문자열이 됩니다. 두 번째는 10진수 문자열이 됩니다. 두 경고 모두 변경된 경로를 식별하여 자동 날짜 또는 숫자 강제 변환을 허용하는 대신 JSON 유형이 아닌 유형을 검토 가능하게 만듭니다.

여기서 다루지 않는 내용 — 규칙이 완전히 결정하지 않는 스타일 선택과 관련된 합리적인 헤더 그룹화를 사용하여 JSON을 관용적 TOML로 다시 변환합니다.

JSON-to-TOML은 루트 개체에 대해 지원되지만 관용적인 작성자 선택이나 설명을 다시 생성하지는 않습니다. Null 값 키는 생략됩니다. 배열 내부의 null은 위치를 유지하기 위해 빈 문자열이 됩니다. TOML 문서는 테이블이어야 하므로 루트 배열, 스칼라 또는 null은 거부됩니다.

이 동작은 역변환이 범위를 벗어나는 개요의 의미를 수정합니다. 변환기는 TOML을 작성하지만 스타일 충실도는 보장되지 않습니다. 차이점은 중요합니다. 지원되는 직렬화는 소스 파일을 바이트 단위로 복원하거나 관리자가 선호하는 레이아웃을 선택하는 것과는 다릅니다.

JSON을(를) 다시 TOML에 쓰는 것은 지원되지만 댓글, 날짜/시간 유형 및 작성자 스타일은 반환되지 않습니다.

TOML 헤더를 경로로 읽고 이중 괄호를 추가 작업으로 읽습니다. JSON 뷰는 결과 트리를 추적하는 데 유용하며, 경고는 유형 경계를 넘는 날짜/시간 및 넓은 정수를 노출합니다. 경고가 나타나면 무손실 작업을 호출하지 마세요.

구성 마이그레이션의 경우 변환된 출력 옆에 원본을 보관하세요. 먼저 값을 확인한 다음 독자 및 대상 도구에 대한 TOML 조직을 편집하십시오. 구문 변환기는 기계적 구문 분석 및 쓰기 단계를 수행합니다. 프로젝트별 그룹화, 허용되는 키 또는 응용 프로그램이 해당 파일을 지원하는지 여부를 결정할 수 없습니다.

최종 비교에서는 함께 모호해지기 쉬운 세 가지 질문을 분리해야 합니다. 첫째, 파싱된 값이 살아남았는가? 둘째, TOML 전용 유형이 JSON 문자열이 되었거나 null이 사라졌나요? 셋째, 새로 직렬화된 TOML는 관리자가 이해할 수 있는 방식으로 구성되어 있습니까? 처음 두 개는 값 및 경고와 비교하여 확인할 수 있습니다. 세 번째는 사람의 검토가 필요합니다. 이러한 검사를 별도로 유지하면 유형이나 권한 구조가 변경될 때 기술적으로 유효한 직렬화를 충실한 마이그레이션이라고 부르는 것을 방지할 수 있습니다.