dataxl/docs/architecture.md

Architecture

dataxl は、ファイル形式ごとの差を小さくするために、内部表現を2つに分けています。

• structured value: JSON/YAML/TOMLから読める map[string]any, []any, scalar
• table: Excel/CSV/TSVに近い Header []string と Rows [][]string

変換は原則として次のどれかです。

• structured -> structured
• structured -> table
• table -> structured
• table -> table

Format Adapters

各形式の処理は cmd/dataxl/main.go の以下の関数に集約しています。

• parseStructured
• encodeStructured
• parseTable
• encodeTable

現在はCLIが小さいため単一ファイルに置いています。形式やオプションが増えたら、 internal/format や internal/table へ分割する余地があります。

Table Model

表形式は必ず1行目をヘッダーとして扱います。

type table struct {
    Header []string
    Rows   [][]string
}

CSV/TSV/XLSXの読み込みでは、短い行を空文字で埋めて列数を揃えます。 XLSXの書き出しではヘッダーを太字にし、1行目を固定します。

Flattening

structured -> table では、入れ子のmap/arrayを列パスへ展開します。

• map: user.name
• array: items[0].sku
• top-level scalar: value

列順は安定性を優先してソートしています。Excel上で列の位置が変わっても、 ヘッダー名を見て復元するため、列順には依存しません。

Unflattening

table -> structured では、ヘッダーのパス表現からmap/arrayを復元します。

例:

items[0].sku

は次の構造になります。

{
  "items": [
    {
      "sku": "..."
    }
  ]
}

セル値は parseCell で軽く型推定します。

• 空文字: ""
• true / false: boolean
• 整数: int64
• 小数または指数表記: float64
• その他: string

TOML Output

TOMLはトップレベル配列を直接表せないため、表からTOMLへ出力する場合など、 トップレベルがmapでない値は rows キーに包んで出力します。

Dependencies

• github.com/xuri/excelize/v2: XLSX読み書き
• gopkg.in/yaml.v3: YAML読み書き
• github.com/BurntSushi/toml: TOML読み書き

Go 1.24以上を前提にしています。