# dataxl `dataxl` は、構造化データファイルとExcelの間で情報を行き来させるための Go製CLIです。 主な用途は、YAML/TOML/JSONなどの構造化ファイルをExcelに貼り付けやすい TSVへ変換したり、Excelからコピーした表を再び構造化データへ戻したりする ことです。 ## 対応形式 - JSON - YAML / YML - TOML - CSV - TSV - XLSX ## インストール Go 1.25以上が必要です。 ```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` です。 `.`、`[`、`]` を含むmapキーや空のmapキーはJSON文字列を使ったbracket記法で 表します。たとえば `{"build.target": {"x[y]": 1}}` は `["build.target"]["x[y]"]` という列名になります。 同じ行に `user` と `user.name` のような競合する列がある場合や、同名ヘッダーが 複数ある場合はエラーにします。どちらかの値だけを採用して正常終了することは ありません。 ## セル値の型推定 CSV、TSV、XLSXから構造化形式へ戻す際は、セル文字列を次の順で推定します。 - 空文字は空文字列 - `true` / `false` はboolean - 通常の整数は64-bit integer - 小数点または指数表記を含む数値は64-bit floating point - それ以外は文字列 郵便番号や商品コードを想定し、`00123` や `-01` のようなゼロ埋め値は文字列のまま 保持します。セルの前後空白も文字列の一部として保持し、` 42 ` のような値を数値に 変換しません。日付、時刻、`null` は自動推定しません。 ## データ欠落を防ぐ検証 - JSON入力はUTF-8として検証し、1つの値と後続空白だけを許可します。2つ目の値、 不正な後続データ、object内の重複キーは、値を置換・無視せずエラーにします。 - YAML streamに複数文書がある場合は、順序を保った配列としてすべて変換します。 - UTF-8 BOM付きCSV/TSVでは先頭のBOMをencoding markerとして除去します。 - CSV/TSVはUTF-8として検証し、ヘッダーより列数が多い行をエラーにします。 - 空ヘッダー列に値がある場合、重複ヘッダー、復元時に型が競合する列パスは エラーにします。 - scalar fieldを1つも持たないrecordは表で表現できないため、空行へ変換して record数を失う代わりにエラーにします。空のrecord listは空の表へ変換できます。 - `rows`、`records`、`items` を行配列として展開するのは、それがオブジェクト唯一の キーである場合だけです。同階層のmetadataを破棄しません。 ## 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`。 - `-version`: バージョンを表示して終了します。 ## 現在の制約 - 表形式では1行目をヘッダーとして扱います。 - XLSXは指定した1シートのみ読み書きします。 - セル値の型推定は、空文字、真偽値、整数、小数、文字列の範囲です。 - 空のmap/arrayは表側で `{}` / `[]` と表示されますが、逆変換時は文字列になります。 - structured形式の `null` と表形式の空文字は同じ空セルになります。 - top-level scalarやscalar配列は表側で `value` 列を使うため、逆変換時は `value` キーを持つレコードになります。 - 複雑なExcel書式や数式の保持は目的外です。 ## 開発者向け情報 - 設計概要: [docs/architecture.md](docs/architecture.md) - 開発手順: [docs/development.md](docs/development.md) ## License dataxlは[MIT License](LICENSE)で提供します。配布バイナリに含まれる依存ソフトウェアの 著作権表示とライセンスは[THIRD_PARTY_LICENSES.txt](THIRD_PARTY_LICENSES.txt)を参照してください。