INI を JSON に変換 — セクションをオブジェクトに

結果は 1 つの JSON オブジェクトです。各セクションヘッダーは、自身のオブジェクトを持つキーになり、そのヘッダーの下にあるキーと値のペアがそのオブジェクトのプロパティになります。どのセクションヘッダーよりも前に書かれたキー——多くのツールがグローバルブロックと呼ぶもの——は、専用の包み紙を持たず、セクションのオブジェクトと並んでトップレベルに置かれます。

これが構造上の変換のすべてです。INI ファイルの中に他に変換すべきものがないからです。この組み合わせを読む価値があるのは形ではなく値のほうで、値は形ほど文字どおりには渡りません。

INI ファイルに型はありません。等号のあとはすべて文字であり、読み込むすべてのプログラムがその意味を自分で決めます。このリーダーはこう決めます。文字列 true と false はそのまま JSON の真偽値になり、有限の数値として解析できるものは JSON の数値になり、それ以外は文字列のままです。

たいていの設定ではこれが正しい判断で、あなた自身が parseInt を通す手間を省きます。ポートは "8080" ではなく 8080 に、タイムアウトは 30 になり、-1 のような負のフラグも比較できる数値になります。代償は、リーダーが量と識別子を区別できないことで、そこで被害が起きます。

4 つのケースが静かに失敗し、どれも実際の設定ファイルに現れます。ゼロ埋めされた識別子 007 は数値の 7 になります。0755 と書かれた Unix のファイルモードは 755 になり、これは別のモードで、そのまま適用されます。0x1F と書かれた 16 進数のマスクは 31 になり、値としては正しくてもログに出力するたびに違って見えます。1.0 と固定されたバージョン番号は 1 になります。

4 つ目はより微妙です。およそ 900 兆を超える整数は精度を失います。JSON の数値は IEEE の倍精度浮動小数点だからです。64 ビットの識別子 9223372036854775807 は 9223372036854776000 として出てきます。何も警告はありません。あるキーがスノーフレーク ID やシリアル番号、口座参照番号を持つなら、元の INI ファイルの中でそれを引用符で囲んでください。引用符付きの値も解析されるので、より確実な対策は数字以外の文字を前後に付けることか、あとで JSON の中の値を直すことです。

どのキーを確認しなくていいか知っておく価値があります。単位が付いているものは安全で、128M と書かれたメモリー上限は文字列の 128M のままです。ドット区切りのアドレスも文字列のままなので、127.0.0.1 はそのまま渡ります。08:00 のような時刻や、パス、URL、数字の一部ではない文字を含むものも文字列のまま残ります。

等号を含む値も生き残ります。行は最初の等号でだけ分割されるので、接続文字列やクエリパラメータは無傷です。周囲の引用符は取り除かれますが、いちばん外側のペアだけです。引用符の内側にパディングがある値はそのパディングを保ち、引用符のない値は両端がトリムされます。その引用符の内側でだけ、バックスラッシュがエスケープを開始します。バックスラッシュと n は改行に、2 つのバックスラッシュは 1 つになります。これが複数行の値を INI へ、そして戻す往復を生き延びさせる仕組みで、引用符のない Windows のパス C:\new が書かれたとおりに読まれ、引用符の中にある同じパスはそうならない理由です。

Windows の INI ファイルや php.ini は true や false より On と Off をずっと多く使いますが、このリーダーはそれらを真偽値として扱いません。文字列の "On" と "Off" になり、これは擁護できます。所詮ただの単語だからです。しかし JSON の受け手が期待するものとはほぼ一致しません。

同じことが yes と no、フラグとして使われる 1 と 0 にも当てはまり、真偽値ではなく数値の 1 と 0 になります。JSON を読む側が何を真とみなすか自分で決める必要があり、いちばん安全な習慣は、変換がそれらを一貫させたと仮定せず、読み込み側のコードでそのキーを明示的に正規化することです。engine が On で debug が false という設定は、今や 2 種類の「はい」を持つことになります。

キーの順序はほぼどこでも保たれ、これは機械ではなく差分を読む人にとって重要です。セクションは登場した順に出てきて、セクション内のキーも書かれた順を保ちます。

例外は数値のキーです。JavaScript のオブジェクトは整数のように見えるキーを昇順でいちばん先に置くので、10、2、name の順で書かれたセクションは 2、10、name の順で出てきます。サーバーの一覧や順序付きルール、プレイリストの項目のように数字をキーに使う INI ファイルは並べ替えられて出てきます。順序が意味を持つファイルなら、そのセクションは JSON の配列になるべきで、それは手作業での修正になります。

INI には仕様がないので、実装は重複したセクションヘッダーの扱いで一致していません。マージするもの、両方保つもの、最後だけを取るものがあります。このリーダーはヘッダーに出会うたびに空のセクションを新しく始めるので、[logging] を 2 回含むファイルは 2 番目のブロックのキーだけを保ちます。最初のブロックは消え、JSON は有効なままで、何も報告されません。

この現象は設定ファイルを結合して組み立てるときに現れます。ベースファイルに環境ごとの上書きを追記する、というよくある配備の方法です。変換前に重複したヘッダーを元のファイルで grep してください。1 つのセクション内での重複キーも同じ挙動で、最後の代入が勝ちます。

これは付随的ではなく構造的な損失です。INI はコメントに対応していて多用しますが、RFC 8259 で規定される JSON にはコメントの記法がまったくありません。保存したいと思う変換ツールでも、_comment のようなキーを発明する以外に置き場所がなく、それを読む受け手はいないでしょう。

設定ファイルではこれがしばしば最大の損失です。プールサイズが既定値ではなく 12 である理由を記した注記、例として残されたコメントアウトのブロック、ある顧客向けに調整された値だと示す行——どれも渡りません。変換を置き換えとして扱わず、元の INI ファイルを JSON の隣でバージョン管理に残してください。

出力はスペース 2 つのインデントを持つ普通の JSON なので、jq、Node、Python、あらゆる JSON Schema バリデーターが問題なく読めます。セクションはオブジェクトのパスになります。jq なら .database.host です。そこにスキーマを重ねて、ポートが数値であること、ホストが文字列であることを主張できます。INI ファイルには何も検証できなかったのに対し、これが実際の利得です。

このサイズのファイルの変換は瞬時で、すべてブラウザーの中で完結します。無料枠の上限は 100 MB で、どんな設定ファイルもそこには届きません。実務上の制約はサイズではなく確認です。JSON がすべてから信頼されるファイルになる前に、一度、出力の中の数値を読んでおいてください。