# dataxl

`dataxl` は、構造化データファイルとExcelの間で情報を行き来させるための
Go製CLIです。

主な用途は、YAML/TOML/JSONなどの構造化ファイルをExcelに貼り付けやすい
TSVへ変換したり、Excelからコピーした表を再び構造化データへ戻したりする
ことです。

## 対応形式

- JSON
- YAML / YML
- TOML
- CSV
- TSV
- XLSX

## インストール

Go 1.24以上が必要です。

```sh
go install git.rumginger.org/agent/dataxl/cmd/dataxl@latest
```

リポジトリをcloneして使う場合:

```sh
git clone https://git.rumginger.org/agent/dataxl.git
cd dataxl
go build ./cmd/dataxl
```

## 基本的な使い方

YAMLをExcel貼り付け向けのTSVへ変換:

```sh
dataxl -from yaml -to tsv -i examples/people.yaml -o people.tsv
```

ExcelからコピーしたTSVをJSONへ戻す:

```sh
dataxl -from tsv -to json < people.tsv > people.json
```

JSONからExcel workbookを作成:

```sh
dataxl -from json -to xlsx -i people.json -o people.xlsx
```

Excel workbookをYAMLへ変換:

```sh
dataxl -from xlsx -to yaml -i people.xlsx -sheet Sheet1
```

入力または出力ファイル名から形式を推定できる場合、`-from` または `-to` は
省略できます。stdin/stdoutを使う場合は明示してください。

```sh
dataxl -i examples/people.yaml -o people.tsv
dataxl -from tsv -to yaml < people.tsv
```

## Excelとの連携

Excelへ貼り付ける場合はTSVが便利です。

```sh
dataxl -from yaml -to tsv -i examples/people.yaml
```

出力をそのままコピーしてExcelのシートに貼り付けると、タブ区切りの列として
展開されます。

Excelから戻す場合は、シート上の範囲をコピーしてstdinへ渡します。

```sh
dataxl -from tsv -to yaml > restored.yaml
```

## 入れ子構造の表現

構造化データの入れ子は、Excelで編集しやすい列名へ展開されます。

入力例:

```yaml
- id: 1
  user:
    name: Alice
  items:
    - sku: A-001
      qty: 2
```

TSV出力例:

```tsv
id	items[0].qty	items[0].sku	user.name
1	2	A-001	Alice
```

逆方向の変換では、`user.name` や `items[0].sku` のような列名から入れ子の
map/arrayを復元します。

## CLIオプション

- `-i`: 入力ファイル。省略時はstdin。
- `-o`: 出力ファイル。省略時はstdout。
- `-from`: 入力形式。`json`, `yaml`, `toml`, `csv`, `tsv`, `xlsx`。
- `-to`: 出力形式。`json`, `yaml`, `toml`, `csv`, `tsv`, `xlsx`。
- `-sheet`: XLSXの読み書きに使うシート名。既定値は `Sheet1`。
- `-pretty`: JSONなどの構造化出力を整形するか。既定値は `true`。

## 現在の制約

- 表形式では1行目をヘッダーとして扱います。
- XLSXは指定した1シートのみ読み書きします。
- セル値の型推定は、空文字、真偽値、整数、小数、文字列の範囲です。
- 複雑なExcel書式や数式の保持は目的外です。

## 開発者向け情報

- 設計概要: [docs/architecture.md](docs/architecture.md)
- 開発手順: [docs/development.md](docs/development.md)