# 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行目をヘッダーとして扱います。

```go
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を復元します。

例:

```text
items[0].sku
```

は次の構造になります。

```json
{
  "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以上を前提にしています。