dataxl
dataxl は、構造化データファイルとExcelの間で情報を行き来させるための
Go製CLIです。
主な用途は、YAML/TOML/JSONなどの構造化ファイルをExcelに貼り付けやすい TSVへ変換したり、Excelからコピーした表を再び構造化データへ戻したりする ことです。
対応形式
- JSON
- YAML / YML
- TOML
- CSV
- TSV
- XLSX
- Markdown table (
markdown/md)
インストール
Go 1.25.13以上が必要です。
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
Markdownのテーブルを作成:
dataxl -from yaml -to markdown -i examples/people.yaml -o people.md
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
Markdownテーブル
GitHub Flavored Markdown互換のヘッダー・区切り行を持つテーブルを読み書きできます。
外側の | は省略可能で、区切り行の : による左寄せ・中央寄せ・右寄せ指定も
入力時に受け付けます（配置指定自体は保持しません）。
セル内の | とバックスラッシュはMarkdownのbackslash escapeを使用します。
改行や前後の空白・タブはHTML文字参照として表し、表形式間の変換で保持します。
入れ子構造の表現
構造化データの入れ子は、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 です。
.、[、] を含む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,markdown。-to: 出力形式。json,yaml,toml,csv,tsv,xlsx,markdown。-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/development.md