YAML を TOML に変換

単純な値と配列がまず上に書かれ、そのあと入れ子になったマッピングがそれぞれ角括弧の見出しとして現れます。3 段階のネストは、3 段の入れ子ブロックではなく、ドットでつながれた 1 個の見出しになります。tool、ruff、その下の設定という並びは、[tool.ruff] という 1 個の見出しの下に設定が入る形にまとまります。

この見出しの平坦化が、2 つの形式のいちばん目立つ違いです。YAML は空白で深さを表現し、際限なく入れ子にできますが読みにくくなります。TOML は深さを見出し名の中に表現し、各ブロックが完全な経路を書いているため 4 段でも読めます。これはこの形式が意図して選んだ取引で、プロジェクト設定にはたいてい合っています。

key: とだけ書いて何も続けない行は有効な YAML で、null として解析されます。TOML には null がありません——仕様がそもそも定義していません——ので、書き出し処理はそのキーを省略します。エラーもプレースホルダーもコメントもなく、YAML にあったキーが TOML にはない、という結果になります。

これは見た目以上に重要です。空のキーは意図的な YAML の慣用表現だからです。設定が「存在はするが未設定」であることを示したり、運用担当者があとで埋める場所を確保したり、選択肢が存在することを文書化したりします。それがすべて消えます。変換の前にコロンで終わる行をソースから探し、それぞれに明示的な値を与えるか、空文字にするか、TOML 側にコメントを残すかを決めてください。

同じ null が配列の中にあると挙動が変わり、書き出し処理はそこで拒否します。配列に null や undefined は入れられない、というメッセージとともに変換が失敗し、何も生成されません。

これは 2 つのうちで安全な側の挙動で、この違いは偶然ではなく意図的です。テーブルからキーを 1 個落としても残りのテーブルは意味を保ちますが、配列から要素を 1 個落とすと、それ以降のすべての要素の位置がずれ、順序を持つリストが別のリストに変わってしまいます。拒否することだけが安全な答えで、余分なダッシュだけで中身のない YAML の行は、静かに何かおかしいものに変換されるのではなく、そのことを教えてくれます。

TOML はテーブルごとにまとめます。あるテーブルに属するものはすべて、その見出しのあとから次の見出しの前までに書かれる必要があるため、書き出し処理はまず単純な値と配列をすべて出力し、そのあと入れ子のブロックを 1 個ずつ出力します。.gitlab-ci.yml をこの方法で変換すると、YAML の中での並び順に関わらず stages の配列が先頭に、ジョブの定義がそのあとにテーブルとして続きます。

計画しておくべきなのは差分です。YAML ファイルがレビュー対象で、同じリポジトリで TOML に置き換えるなら、最初のコミットは翻訳ではなく書き直しのように見えます。実際そのとおりだからです。この変換だけを含む単独のコミットとして反映すれば、次に読む人は構文だけが変わったことをそこから読み取れます。

パイプ記号のあとにインデントされたシェルスクリプトが続く、いわゆるブロックスカラーは、あらゆる CI ファイルがビルドコマンドを保持している形ですが、これは解析されると改行を含む 1 個の文字列になり、書き出し処理はそれをバックスラッシュ n のエスケープを含む通常の引用符付き TOML 文字列として書きます。10 行のスクリプトが 1 行のとても長い行になります。

TOML には三重引用符を使う複数行文字列の構文があり、これならスクリプトを読める形で保持できますが、書き出し処理はそこまで踏み込みません。これは手作業で直す部類の変換です。エスケープされた改行を含む値を見つけ、それぞれを三重引用符のブロックに書き直してください。人が再び手を入れる値については行う価値があり、プログラムしか読まない値については行わなくても構いません。

この系列の形式の中で、TOML だけが日付を第一級の型として持ちます。オフセット付き日時、ローカル日時、ローカル日付、ローカル時刻はすべて仕様の一部で、TOML のパーサーは文字列ではなく日付そのものとして返します。これが JSON より TOML を選ぶ主な理由の一つです。

この変換ではそれが得られません。YAML 1.2 は引用符のない 2024-01-02 を文字列として扱うため、TOML には引用符付きの "2024-01-02" として現れます。あとから引用符を外す作業は数秒で終わり、外さずに使うこともできます。その場合は TOML が日付として持てる情報をテキストとして保持しているだけです。同じことは小数点付きの整数にも起きます。YAML の 1.0 という値は、書き出し処理に届く前に解析器が整数と判断しているため、TOML の整数 1 になります。

人々が心配するはずの構造が、いちばんうまく変換されます。項目がマッピングである YAML のリスト——著者のリスト、バイナリのリスト、ジョブのリスト——は、二重角括弧の見出しを項目ごとに繰り返す TOML のテーブル配列になります。これはまさに pyproject.toml や Cargo.toml が authors や targets に求めている形です。

YAML ファイルの最上位がリストである場合だけは例外です。TOML の文書は常にテーブルなので、リストだけの文書は items という単一のキーの下にリストが入ったテーブルとして包まれます。YAML がルートで配列になっているなら、変換の前にキー名を自分で決めてソースに加えておくほうが、その名前に意味を持たせられます。

TOML の裸のキーは文字、数字、アンダースコア、ハイフンだけを許します。それ以外はすべて引用符が必要で、書き出し処理が代わりに引用符を付けます。ドットを含むキーは引用符付きの "date.timezone" として出力され、スペースを含むキーも同様です。引用符付きのキーは完全に有効な TOML です。

それは同時に合図でもあります。ドットを含む引用符付きキーは、たいてい YAML がキー名の中で構造を表現していたことを示しており、TOML ではそれを本物のテーブルとして書き直したほうが良い場合が多いということです。分割するかどうかは変換ではなく設定の中身に関する判断ですが、出力の中の引用符は、どこから探し始めればよいかの信頼できる手がかりになります。

どちらの形式もコメントに対応していますが、あなたのコメントは 1 個も渡りません。解析処理は読み込み時にそれを捨て、書き出し処理には書くものが何も残っていません。プロジェクト設定にとってこれは実質的な損失で、依存関係を固定している理由や、コメントアウトされた代替案、どの環境向けのブロックかを示す行が失われます。

移行が本当に終わるのは、それらを戻したときです。変換したあと、古い YAML と新しい TOML を並べて開き、コメントを元の場所に付け直してください。ふつうのファイルなら 10 分ほどの作業で、それをやるかやらないかが、誰かが保守できる設定と、動くけれど誰も触りたがらない設定との差になります。