개발자 도구 · 구문 변환기
JSON 구성을 TOML로 마이그레이션: 변환되는 항목과 사람이 필요한 항목
· 그것이 중요한 이유
JSON toml 개발자 워크플로
TOML는 Python 및 Rust 프로젝트의 구성 형식이 되었으며 많은 JSON 설정 파일이 이 형식으로 이동하고 있습니다. 이 게시물에서는 기계적으로 변환되는 부품과 판단이 필요한 부품(널, 혼합 배열, 깊은 중첩)을 설명합니다.
setup.cfg 및 settings.json 시대가 끝나고 있습니다. 이동해야 하는 pyproject.toml 및 JSON 블록에 구성을 통합하는 프로젝트입니다.
프로젝트는 때때로 설정을 하나의 TOML 파일로 통합하지만 저장소는 "시대가 끝나고 있다"는 개요의 주장을 지원할 수 없습니다. 실제 작업은 더 좁습니다. JSON 모양의 개체를 TOML 테이블로 이동하고 손실을 검사한 다음 대상 애플리케이션이 실제로 결과 키를 인식하는지 확인합니다.
ToolAcre에는 TOML 출력을 위한 루트 개체가 필요합니다. TOML 문서는 테이블이므로 루트 배열, 문자열, 숫자, 부울 또는 null은 거부됩니다. 이러한 초기 형태 검사는 발명된 래퍼가 응용 프로그램에서 승인된 구성처럼 보이는 것을 방지합니다.
구성 통합은 이전 형식의 보편적인 끝이 아니라 프로젝트 선택입니다.
변환기는 구체적인 메커니즘을 증명합니다. TOML에는 테이블, 배열 및 스칼라 값이 있습니다. 작성자는 중첩된 개체를 유효한 TOML 구조로 바꿉니다. 또한 null이 없으며 JSON 중괄호와 다른 구문을 사용합니다. 생태계 선호도나 디자인 우월성에 대한 주장에는 이러한 구현 파일 외부의 소스가 필요합니다.
주석은 관리자가 작성된 TOML을 선호하는 이유 중 하나이지만 JSON 입력에는 전달할 내용이 없습니다. 생성된 문서는 시작 값 직렬화입니다. 사람의 설명과 프로젝트별 구성은 나중에 추가해야 합니다.
이 변환기가 일반적인 형식 옹호가 아닌 TOML에 대해 증명하는 것
smol-toml이 지원하는 문자열, 유한 숫자, 부울, 중첩 객체 및 배열은 기계적으로 변환됩니다. 객체 배열은 테이블 배열이 될 수 있습니다. 중첩된 객체는 테이블 헤더가 될 수 있습니다. 유니코드 및 이스케이프된 줄 바꿈은 일반 값에 대한 테스트된 왕복에서 살아남습니다.
TOML 배열 규칙은 작성자가 표현할 수 없는 모양과 자동으로 강제하는 대신 실패한 오류 이름을 거부할 수 있습니다. 모든 배열을 동종으로 미리 호출하면 이종 배열을 읽는 종속성 테스트 동작이 지나치게 단순화됩니다. 실제 변환을 게이트로 사용하십시오.
TOML 작성자가 허용하는 배열을 포함하여 기계적으로 변환하는 것
Null에는 TOML 표현이 없습니다. null을 보유하는 개체 속성은 생략되고 경고에 나열됩니다. 배열 내부의 null은 빈 문자열이 되므로 이후 인덱스가 이동하지 않습니다. 그 대체품도 명명되었습니다. 두 결과 모두 원래 값을 유지하지 않습니다.
변경 사항을 수락하기 전에 null이 무엇을 의미하는지 결정하십시오. 이는 기본값을 상속하거나 필드를 명시적으로 지우거나 값이 제공되지 않음을 의미할 수 있습니다. 키를 삭제하거나 빈 텍스트로 대체하면 애플리케이션 의미 체계가 변경될 수 있으므로 대상의 문서화된 구성 모델에 대해 해결하세요.
스타일에 사람이 필요한 경우 — [테이블] 헤더, 점으로 구분된 키 및 인라인 테이블 중에서 선택하고 관련 키를 그룹화하여 파일이 잘 읽히도록 합니다.
트리는 관리자가 `[tool.linter]`, 점으로 구분된 키 또는 인라인 테이블을 선호하는지 여부를 말하지 않습니다. 직렬 변환기는 유효한 구문을 선택하는 반면 인간은 소유권 및 관련 옵션을 명확하게 하는 그룹화를 선택합니다. 키를 정렬하면 출력을 결정적으로 만들 수 있지만 함께 속하는 개념을 분리할 수 있습니다.
작은 차이를 유지하고 값이 확인된 후 설명을 추가합니다. 나중에 TOML을(를) 다시 JSON로 변환하면 해당 주석이나 선택한 테이블 철자를 복원할 수 없습니다. 스타일은 일반 가치 모델 외부에서 작성된 정보입니다.
작업 예: linter의 JSON 구성에서 TOML로 — 두 개의 null 값을 변환하고 해결하고 결과를 [tool.linter] 헤더 아래에 다시 그룹화
`{"tool":{"linter":{"lineLength":100,"preview":null,"exclude":["dist",null]}}}`을(를) 변환합니다. 루트 개체가 허용됩니다. `preview`이(가) 생략되었습니다. null 배열 멤버는 빈 문자열이 됩니다. 경고에는 두 경로의 이름이 모두 지정됩니다. 나머지 중첩 개체는 작성자가 선택한 TOML 테이블 아래에 직렬화됩니다.
저장하기 전에 미리보기가 false인지, 없어야 하는지 또는 다른 문서화된 값인지, 그리고 빈 제외 항목이 유효한지 여부를 결정하세요. 그런 다음 독자를 위해 테이블을 다시 그룹화하고 주석을 추가합니다. 이 예에서는 변환이 기계적인 반면 마이그레이션은 의미론적인 이유를 보여줍니다.
여기서 다루지 않는 내용 — 대상 도구가 실제로 TOML을 읽는지 여부와 문서에서만 알 수 있는 특정 키 이름을 알 수 있습니다.
유효한 TOML 파일은 도구가 TOML을 읽고, 섹션을 인식하거나, 이전 JSON 소비자와 같은 키를 해석한다는 것을 증명하지 않습니다. 현재 대상 문서를 확인하고 자체 유효성 검사 또는 테스트 실행 명령을 실행하세요. ToolAcre는 애플리케이션 스키마를 가져오지 않습니다.
날짜는 반대 방향으로도 주의가 필요합니다. TOML-기본 시간 값은 JSON로 읽을 때 문자열이 되므로 나중에 왕복할 때 이를 인용합니다. 양방향을 교차하는 마이그레이션 체인은 무손실이라고 할 수 없습니다.
요점: 먼저 변환한 다음 가독성을 위해 편집하십시오. 그리고 구문 변환기 패널이 브라우저에서 기계적인 부분을 수행하는 방법
기계적 비호환성을 노출시키기 위해 먼저 변환한 다음 의미와 가독성을 위해 편집하십시오. 원본을 유지하고 모든 경고를 검토하고 실제 대상으로 테스트하십시오. Null 처리 및 루트 모양은 엄격한 경계입니다. 테이블 구성은 인간의 디자인 결정입니다.
구문 변환기는 응용 프로그램 지식을 고안하지 않고도 반복적인 구문 작업을 제거합니다. 이러한 분할은 출력을 유용하게 만듭니다. 즉, 검토를 위해 기계로 제작된 구조와 형식이나 도구가 일치하지 않는 경우 의도적인 선택이 뒤따릅니다.
수락한 모든 경고에 대해 마이그레이션 메모를 보관하세요. null이 부재가 되는 경우 부재를 수정하는 대상 기본값을 명시합니다. null 배열 멤버가 빈 텍스트가 되는 경우 인덱스가 중요한 이유와 빈 텍스트가 유효한 이유를 설명하세요. 작성자가 혼합 배열을 거부하는 경우 해당 값을 개인적으로 강제하는 대신 다시 설계하세요. 이러한 결정은 지속 가능한 마이그레이션 기록입니다. 생성된 TOML만으로는 다음 관리자에게 이를 설명할 수 없습니다.