dataxl

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

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

対応形式

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

インストール

Go 1.24以上が必要です。

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

privateリポジトリとして使う場合は、Git認証と GOPRIVATE=git.rumginger.org/agent/dataxl の設定が必要になることがあります。

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

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

基本的な使い方

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

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

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

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

JSONからExcel workbookを作成:

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

Excel workbookをYAMLへ変換:

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

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

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

Excelとの連携

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

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

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

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

dataxl -from tsv -to yaml > restored.yaml

入れ子構造の表現

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

入力例:

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

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/development.md