TOML を NDJSON に変換

TOML のドキュメントは常にテーブルであり、トップレベルが配列になることは仕様上ありません。改行区切りの JSON はトップレベルの配列を境界にして分割しますが、TOML の一つのファイルの中にはその境界がそもそも現れないため、ファイル全体が一行になります。

これは制約というより、この用途にちょうど合った形です。pyproject.toml を断片に分けたい人はいません。TOML を NDJSON に変換する人はたいてい、多数の設定ファイルを一つのコレクションにまとめようとしていて、一ファイル一レコードという単位がそのまま欲しい形になります。

手順は単純です。各ファイルを変換し、その一行を成長中の出力ファイルに追記していきます。それぞれの行は独立した完全な JSON の値で、外側を囲む配列もカンマもないため、連結すること自体がそのままマージになります。

こうして作った一覧は、質問に答えられるデータになります。どのクレートが特定のバージョンを固定しているか、どのパッケージがライセンスを宣言していないか。そうした問いに、フォルダーを歩いてパースするスクリプトを書く代わりに、一つのクエリーで答えられるようになります。

出どころの分からないレコードは、一覧としてほとんど使い物になりません。変換はファイルの中身だけを読み、パスやリポジトリ、コミットは関知しないため、書き出された行にはどこから来たかを示す情報がありません。

追加するタイミングは二つ考えられます。連結する段階で jq を通してパスのキーを差し込む方法は、TOML ファイル自体には手を加えずに済みます。もう一つは TOML ファイルの中にキーを足す方法で、将来のすべての変換に引き継がれますが、他人が所有するファイルに手を入れることになります。前者のほうが多くの場面で使いやすい方法です。

圧縮された JSON で、インデントも余分な空白もなく、キーは TOML に書かれていた順のまま、末尾には改行が付きます。テーブルは入れ子のオブジェクトに、テーブルの配列はオブジェクトの配列になり、著者一覧やビルドターゲットの集合も、クエリーエンジンが期待する形でそのまま届きます。

行の長さは設定ファイルの長さに比例します。pyproject.toml 程度なら数キロバイトですが、大きな設定ファイルではそれ以上になることもあります。

TOML には本格的な日時型がありますが JSON にはないため、日付やタイムスタンプはすべて文字列になります。オフセットはそのまま残り、ローカルの日付はそのまま書かれ、ローカルの時刻にはミリ秒の桁が加わります。

無限大や非数を表す inf、nan は有効な TOML の値ですが、JSON では null になります。設定された無限の上限値と、未設定の値が、データセットの中では見分けがつかなくなります。整数と浮動小数点の区別も失われ、1.0 は 1 として書き出されます。

TOML 1.0 は 64 ビットの符号付き整数を要求しますが、JSON の数値は倍精度浮動小数点数であり、およそ九千兆を超える値は正確に表現できません。パーサーは丸めた数値を書き込むのではなく、該当する行の番号を示してエラーで止まります。

これは一覧を作る用途では特に正しい挙動です。誤った数値が正しい数値と見分けがつかないまま何千件も並んでしまうのが一番困る事態だからです。エラーが出たら、その値を TOML の側で文字列として引用符付きにしておくと解決します。多くの場合、それは量ではなく識別子として扱うべき値です。

プロジェクトごとに設定の構成は違います。あるファイルには三つのリンターを含む tool テーブルがあり、別のファイルにはそれ自体がなく、さらに別のファイルは誰も使っていない独自のキーを持っています。それぞれの行は自分のファイルが持っていたキーだけを持つので、同じコレクションを列の形に平坦化したときに起きる、キーの和集合や空セルの問題が生じません。

それをどう扱うかは受け取り側次第です。スキーマを固定しないストアであれば、そのまま受け入れて一部のレコードにしかないキーを問い合わせることもできます。固定スキーマの読み込みツールであれば、外れ値を拒否するか、そのフィールドを落とすことになります。

TOML のコメントは、なぜその値がそうなっているかという理由そのものです。依存関係をなぜ固定しているか、どのチケットに関連する回避策か、その数値が何を意味するか。NDJSON は一行ごとの JSON なので、JSON にコメント構文がない以上、これらはすべて失われます。

一度読んで捨てるデータセットであれば問題ありません。TOML ファイルをこのデータから生成し直すつもりなら話は別で、理由の書かれていない設定を作ることになります。このストリームは設定についての問いに答えるために使い、設定ファイル自体はそのまま元の場所に置いておくのが適切です。

パースも書き出しも、このページの中で JavaScript によって行われます。トークンやレジストリの内部 URL を含む設定ファイルであっても、外に送信されることはありません。

無料枠は 100 MB までで、ファイル全体が一度メモリーに読み込まれます。定期的に一覧を作り直す必要があるなら、ディレクトリを歩いて本格的な TOML ライブラリーでパースし、パスを添えて行を出力するスクリプトのほうが向いています。このページは、その一覧を最初に作り、自動化する価値があるかを見極めるための場所です。