156 lines
4.4 KiB
Markdown
156 lines
4.4 KiB
Markdown
# 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
|
|
```
|
|
|
|
privateリポジトリとして使う場合は、Git認証と `GOPRIVATE=git.rumginger.org/agent/dataxl`
|
|
の設定が必要になることがあります。
|
|
|
|
リポジトリを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を復元します。
|
|
|
|
列パスは `.` でmapのキー、`[n]` で0始まりの配列indexを表します。たとえば
|
|
`orders[0].items[1].sku` は、最初の注文に含まれる2番目の商品の `sku` です。
|
|
|
|
同じ行に `user` と `user.name` のような競合する列がある場合、先に読み込まれた
|
|
値を保持し、後続列で型を上書きしません。曖昧な復元を避けるため、親要素と子要素を
|
|
同時に列として置かないでください。
|
|
|
|
## セル値の型推定
|
|
|
|
CSV、TSV、XLSXから構造化形式へ戻す際は、セル文字列を次の順で推定します。
|
|
|
|
- 空文字は空文字列
|
|
- `true` / `false` はboolean
|
|
- 通常の整数は64-bit integer
|
|
- 小数点または指数表記を含む数値は64-bit floating point
|
|
- それ以外は文字列
|
|
|
|
郵便番号や商品コードを想定し、`00123` や `-01` のようなゼロ埋め値は文字列のまま
|
|
保持します。日付、時刻、`null` は自動推定しません。
|
|
|
|
## 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シートのみ読み書きします。
|
|
- セル値の型推定は、空文字、真偽値、整数、小数、文字列の範囲です。
|
|
- 空のmap/arrayは表側で `{}` / `[]` と表示されますが、逆変換時は文字列になります。
|
|
- mapキーに `.`、`[`、`]` を含む場合のescape記法は未対応です。
|
|
- 複雑なExcel書式や数式の保持は目的外です。
|
|
|
|
## 開発者向け情報
|
|
|
|
- 設計概要: [docs/architecture.md](docs/architecture.md)
|
|
- 開発手順: [docs/development.md](docs/development.md)
|