開発者ツール · 構文コンバーター
TOML が存在する理由: Cargo.toml と pyproject.toml の背後にある設計目標
· 背景
トムル データ形式 開発者ワークフロー
TOML は、JSON の厳格さと YAML の曖昧さの両方に対する反応として、2013 で作成されました。この投稿では、その設計目標、その設計によって生み出された選択肢、そしてなぜ Rust と Python がそれをプロジェクト構成に標準化したのかについて説明します。
1 つのリポジトリ内の 3 つの構成形式 — エディター用の JSON、CI 用の YAML、ビルド用の TOML、および 3 番目が存在する理由の問題
リポジトリは、さまざまな構成サーフェスに JSON、YAML、および TOML を使用できます。 ToolAcre はすべてのプロジェクトの選択を説明することはできませんが、変換によって構造的な違いが明確になります。TOML はルート テーブルとして始まり、ネストにヘッダーと点線のパスを使用し、JSON では使用できない一時的な値を保持します。
見た目から議論するのではなく、例をロードしてください。ネストされたテーブルはオブジェクトになり、二重括弧テーブルは配列になり、値が JSON に入るとコメントが消えます。観察されたこれらの境界は、1 つの構文が本質的に優れているという一般的な主張よりも実用的です。
設計目標 — 最小限で明白なセマンティクス、読みやすさ、およびハッシュ テーブルに明確にマッピングされる形式
付属のパーサーは明らかなテーブル セマンティクスを公開します。ヘッダーはパスであり、割り当てはアクティブなテーブルに属し、スカラー トークンは TOML 型を定義しています。文字列は、その内容が日付のように見えるという理由だけで型指定されるわけではありません。実際の時間構文は、ToolAcre が意図的に正規化する日付オブジェクトを生成します。
このリポジトリは、フォーマットの作成者、日付、または表明された哲学を情報源としていないため、この記事では記憶に残る歴史を事実として提示することを避けています。 smol-toml とコンバーター独自の正規化層でテストされた動作を報告します。
出典のない出典の主張のない、出荷されたパーサーで観察可能な設計プロパティ
TOML には null がなく、そのドキュメント ルートを配列またはスカラーにすることはできません。このマッピングでは、YAML スタイルのアンカーやエイリアスは提供されません。コメントは作成された TOML に存在しますが、値パーサーによって保持されないため、JSON または YAML による変換後に存続できません。
引用符で囲まれていない裸の値は、YAML のスキーマ選択ではなく、TOML 文法に従います。パーサーは、型指定された値を受け入れるか、位置情報を含む無効な TOML を報告します。 ToolAcre は、不正な形式の割り当てに対して暗黙的な文字列モードを追加しません。
サポートされる値モデルで除外されるもの、または異なる方法で処理されるもの
モデルには、文字列、符号付き整数、浮動小数点数、ブール値、4 つの一時的な種類、配列、およびテーブルが含まれます。テーブルの配列は、繰り返されるオブジェクト レコードを表します。 2^53 を超える大きな符号付き整数は、変換時に 10 進数の文字列になるため、JavaScript は暗黙的に丸めません。
時間値は、オフセット日付/時間、ローカル日付/時間、ローカル日付、またはローカル時間のソース指向のテキストになります。警告では種類が散文で保持されますが、JSON は文字列のみを受け取ります。したがって、逆変換すると引用符が付けられ、ネイティブの TOML 型が失われます。
の採用 — Rust の初期の頃のカーゴ、PEP 518 による pyproject.toml の選択、および 2021 の 1.0.0 仕様
Cargo と pyproject の採用は歴史的であり、コンバーターのリポジトリに存在しないソースを必要とするエコシステムの主張です。ここでは意図的に省略しています。パスやファイル名は、年表、仕様リリース、または標準決定の証拠にはなりません。
運用上の問題は、ターゲット ツールが TOML を読み取るかどうか、またどのテーブルを予期するかということです。そのツールの現在のドキュメントを確認してください。構文コンバーターは、パッケージ マネージャーの構成コントラクトではなく、構文と値のマッピングを認識します。
エコシステム導入履歴はリポジトリ ソースなしで省略されます
深いネストは、テーブルのコンテキストが複数の行にわたって持続するため、スキャンが難しくなる可能性がありますが、テーブルの大きな配列では、繰り返されるヘッダー全体に 1 つの論理リストが分散されます。 JSON は完全な階層を明示しますが、中括弧と引用符が追加されます。どちらの表現も、基礎となる構成から複雑さを取り除くものではありません。
パーサーは、ネストを 100 に、ソースの長さを 200 万文字に制限します。これらは拒否境界であり、理想的な構成サイズや普遍的な TOML 制限についての記述ではありません。
これでカバーされないもの — TOML 各言語でのパーサーの選択、および一部の標準ライブラリ実装の読み取り専用の性質
標準ライブラリの書き込み機能と同様に、各言語でのパーサーの選択は範囲外です。 ToolAcre は smol-toml を動的に使用し、そのエラーをラップします。別の実装では、有効な出力を異なる形式でフォーマットしたり、同じデータを表現しながら別の API を公開したりできます。
相互運用性が重要な場合は、時間値、大きな整数、配列、および点線キーにクロスツール フィクスチャを使用します。ここで受け入れられたファイルは、すべての TOML コンシューマーによって自動的に受け入れられるわけではありません。
要点: TOML は構成形式であるという意見があります。また、構文コンバーター パネルでその形式の JSON または YAML ファイルをどのように表示できるかについても意見があります。
TOML は、テーブル ルート、明示的に型指定された値、ネイティブの一時的な種類、および null なしなど、観察可能な方法で意見化されています。変換により、起源神話を必要とせずに、これらの選択肢と、JSON 型のターゲットとの非互換性が明らかになります。
パネルを使用してツリーを検査し、警告を特定します。次に、宛先のスキーマに戻り、人間が管理するテーブル レイアウトを作成します。コンバーターは、形式の優先順位に関する判断ではなく、値に関する証拠を提供します。
TOML が単なる中間ビューである場合にも、同じ規定が適用されます。読みやすさを判断する前に、ソースを保存し、正規化された値を比較し、時間変換またはワイド整数変換をすべて記録します。コンパクトなテーブル レイアウトでは変更された型を隠すことができますが、テーブルの冗長な配列では意味的に正確なことが可能です。形式の選択は、生成された 1 つのサンプルの見た目の美しさではなく、構成契約とメンテナンスのワークフローに従う必要があります。