94 lines
2.3 KiB
Markdown
94 lines
2.3 KiB
Markdown
# 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以上を前提にしています。
|