Document conversion internals and limits

README.md

@@ -111,6 +111,26 @@ id	items[0].qty	items[0].sku	user.name
 逆方向の変換では、`user.name` や `items[0].sku` のような列名から入れ子の
 map/arrayを復元します。
 
+列パスは `.` でmapのキー、`[n]` で0始まりの配列indexを表します。たとえば
+`orders[0].items[1].sku` は、最初の注文に含まれる2番目の商品の `sku` です。
+
+同じ行に `user` と `user.name` のような競合する列がある場合、先に読み込まれた
+値を保持し、後続列で型を上書きしません。曖昧な復元を避けるため、親要素と子要素を
+同時に列として置かないでください。
+
+## セル値の型推定
+
+CSV、TSV、XLSXから構造化形式へ戻す際は、セル文字列を次の順で推定します。
+
+- 空文字は空文字列
+- `true` / `false` はboolean
+- 通常の整数は64-bit integer
+- 小数点または指数表記を含む数値は64-bit floating point
+- それ以外は文字列
+
+郵便番号や商品コードを想定し、`00123` や `-01` のようなゼロ埋め値は文字列のまま
+保持します。日付、時刻、`null` は自動推定しません。
+
 ## CLIオプション
 
 - `-i`: 入力ファイル。省略時はstdin。
@@ -125,6 +145,8 @@ map/arrayを復元します。
 - 表形式では1行目をヘッダーとして扱います。
 - XLSXは指定した1シートのみ読み書きします。
 - セル値の型推定は、空文字、真偽値、整数、小数、文字列の範囲です。
+- 空のmap/arrayは表側で `{}` / `[]` と表示されますが、逆変換時は文字列になります。
+- mapキーに `.`、`[`、`]` を含む場合のescape記法は未対応です。
 - 複雑なExcel書式や数式の保持は目的外です。
 
 ## 開発者向け情報