Initial dataxl CLI

README.md

@@ -0,0 +1,130 @@
+# 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)