開発者ツール · 構文コンバーター
JSON 構成を TOML に移行: 何が変換され、何が人間の手を必要とするのか
· なぜそれが重要なのか
json トムル 開発者ワークフロー
TOML は Python および Rust プロジェクトの構成形式となり、多くの JSON 設定ファイルはそれに移行しています。この投稿では、どの部分が機械的に変換されるのか、またどの部分 (null、混合配列、深いネスト) が判断を必要とするのかについて説明します。
setup.cfg と settings.json の時代は終わります — プロジェクトは構成を pyproject.toml に統合し、移動する必要がある JSON ブロックが始まります
プロジェクトでは設定が 1 つの TOML ファイルに統合されることがありますが、リポジトリは「時代は終わりつつある」というアウトラインの主張をサポートできません。実際のタスクはより狭く、JSON 型のオブジェクトを TOML テーブルに移動し、損失を検査して、ターゲット アプリケーションが結果のキーを実際に認識していることを確認します。
ToolAcre には、TOML 出力のルート オブジェクトが必要です。 TOML ドキュメントはテーブルであるため、ルート配列、文字列、数値、ブール値、または null は拒否されます。この初期の形状チェックにより、発明されたラッパーがアプリケーションで承認された構成のように見えなくなるのを防ぎます。
構成の統合はプロジェクトの選択であり、古い形式の普遍的な目的ではありません。
コンバーターは具体的なメカニズムを証明します。 TOML にはテーブル、配列、およびスカラー値があります。そのライターは、ネストされたオブジェクトを有効な TOML 構造に変換します。また、null がなく、JSON 中かっことは異なる構文が使用されます。エコシステムの好みや設計の優位性に関する主張には、これらの実装ファイル以外のソースが必要です。
コメントは、メンテナが作成された TOML を好む理由の 1 つですが、JSON 入力には引き継ぐものが何も含まれていません。生成されたドキュメントは開始値のシリアル化です。人間による説明とプロジェクト固有の組織は後から追加する必要があります。
このコンバーターが一般的な形式の擁護ではなく TOML について証明していること
smol-toml でサポートされる文字列、有限数値、ブール値、ネストされたオブジェクトおよび配列は、機械的に変換されます。オブジェクトの配列はテーブルの配列になる可能性があります。ネストされたオブジェクトはテーブルヘッダーになる可能性があります。 Unicode とエスケープされた改行は、通常の値のテスト済みラウンドトリップに耐えます。
TOML 配列ルールは、ライターが表現できない形状や、サイレントに強制するのではなく失敗したエラー名を拒否できます。事前にすべての配列を同種と呼ぶと、依存関係のテストされた動作が単純化しすぎて、異種の配列も読み取られてしまいます。実際の変換をゲートとして使用します。
TOML ライターが受け入れる配列を含む、機械的に変換するもの
Null には TOML 表現がありません。 null を保持するオブジェクト プロパティは省略され、警告にリストされます。配列内の null は空の文字列になるため、後のインデックスはシフトされません。その代替品にも名前が付けられています。どちらの結果も元の値を保持しません。
いずれかの変更を受け入れる前に、null が何を意味するかを決定してください。これは、デフォルトを継承すること、フィールドを明示的にクリアすること、または値を指定しないことを意味する場合があります。キーを削除したり空のテキストに置き換えると、アプリケーションのセマンティクスが変更される可能性があるため、宛先の文書化された構成モデルに照らして解決してください。
スタイルに人間が必要な場合 — [テーブル] ヘッダー、点線キー、インライン テーブルのいずれかを選択し、ファイルが読みやすいように関連するキーをグループ化します。
ツリーには、保守者が `[tool.linter]`、点線キー、またはインライン テーブルのどちらを好むかは示されていません。シリアライザーは有効な構文を選択しますが、人間は所有権と関連オプションを明確にするグループ化を選択します。キーを並べ替えると出力が決定的になる可能性がありますが、一緒に属する概念が分離される可能性があります。
小さな差分を保存し、値が検証された後にコメントを追加します。後で TOML を JSON に戻しても、それらのコメントや選択した表のスペルを復元することはできません。スタイルは、単純な値モデルの外側で作成された情報です。
動作した例: リンターの JSON 構成を TOML に変換 — 2 つの 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 だけでは、次のメンテナにそれらを説明することはできません。