Commands

tdsl は .tdsl ファイルの検証、JSON IRへのコンパイル、HTMLレンダリング、Wikidata起点の年表作成、手作業向けテンプレート生成を扱います。各サブコマンドの詳細な引数・オプションは CLIリファレンスを参照してください。

tdsl --help
tdsl help <command>

基本フロー

tdsl check sample.tdsl
tdsl lint sample.tdsl
tdsl build sample.tdsl --pretty --output sample.json
tdsl render sample.tdsl --output sample.html

コマンド	用途
`tdsl check <FILE>`	構文・意味チェックを実行する
`tdsl lint <FILE>`	品質チェックを実行する
`tdsl build <FILE>`	`.tdsl` をIR JSONにコンパイルする
`tdsl render <FILE>`	スタンドアロンHTMLに描画する
`tdsl ast <FILE>`	デバッグ用にASTを出力する
`tdsl decompile <FILE>`	JSON IRを `.tdsl` に逆コンパイルする（v1.1.0〜）
`tdsl merge <FILES...>`	複数の `.tdsl` ファイルを結合する（v1.2.0〜）
`tdsl completions <SHELL>`	シェル補完スクリプトを生成する（v1.9.0〜）
`tdsl lsp`	言語サーバ（LSP）を起動する（v1.11.0〜）
`tdsl fmt <FILE>`	`.tdsl` を正準スタイルに整形する（v1.14.0〜）
`tdsl export-csv <FILE>`	IRをCSVに書き出す（v1.23.0〜）

build と render は Wikidata import を含むファイルでネットワークアクセスを行うことがあります。ローカル定義だけを処理したい場合は --offline を指定します。

tdsl build sample.tdsl --offline --pretty
tdsl render sample.tdsl --offline --output sample.html

decompile

JSON IRから .tdsl ソースを逆生成します。build の逆方向の変換で、既存IRからDSLソースを復元したい場合に使います（v1.1.0〜）。start / end / time の秒精度・UTCオフセット（Z / ±HH:MM）も欠落なくラウンドトリップします（v1.27.0〜。それ以前は無声で破棄されていました）。

tdsl decompile sample.json --output sample.tdsl

merge

複数の .tdsl ファイルを統合してIR JSONを出力します。レーンやイベントをファイル分割して管理し、最終的に1つのIRにまとめる場合に使います（v1.2.0〜）。

tdsl merge part1.tdsl part2.tdsl --output combined.json --pretty

render

.tdsl をスタンドアロンHTML / SVG / PNG / PDF として描画します。--format で出力形式を切り替えます。--format png は v1.10.0〜、--format pdf は v1.11.0〜対応です。

tdsl render sample.tdsl --format svg --output sample.svg
tdsl render sample.tdsl --format png --output sample.png
tdsl render sample.tdsl --format pdf --output sample.pdf

PNG 出力は内部 SVG を resvg でラスタライズします。CJK レーンラベルは system fonts（Noto Sans JP / Hiragino Sans / Yu Gothic 等）が読み込まれている環境で描画できます。--dpi（デフォルト 96）でラスタライズ解像度を、--png-scale でピクセルサイズの倍率を指定できます。--dpi と --png-scale は同時に指定できません（v1.11.0〜）。

PDF 出力はベクタ形式で出力します。印刷・高解像度表示に適しています（v1.11.0〜）。

--orientation vertical を指定すると、時間軸を縦方向（上→下）に描画する垂直レイアウトになります（デフォルトは horizontal、v1.13.0〜）。HTML / SVG / PNG / PDF の全形式に対応します。

tdsl render sample.tdsl --orientation vertical --output sample.svg

--grid を指定すると、目盛りに合わせたグリッド線を背景に描画します。decade / year / month で間隔を選び、none（デフォルト）で非表示にします（v1.14.0〜）。水平・垂直どちらのレイアウトにも対応します。グリッド線は薄く描画され、装飾要素として支援技術からは読み上げられません。デフォルトが none のため、既存の出力は変化しません。

tdsl render sample.tdsl --grid decade --output sample.svg

completions

シェル補完スクリプトを生成して読み込みます。bash / zsh / fish / pwsh / elvish に対応しています（v1.9.0〜）。

# bash
tdsl completions bash >> ~/.bashrc

# zsh
tdsl completions zsh > ~/.zfunc/_tdsl

# fish
tdsl completions fish > ~/.config/fish/completions/tdsl.fish

lsp

Timeline DSL の言語サーバ（LSP）を stdio 経由で起動します（v1.11.0〜）。エディタの LSP クライアントから接続すると、.tdsl 編集中にリアルタイム診断・コンテキスト依存補完・ホバー・定義ジャンプ・参照検索・リネーム・コードアクション・ドキュメントシンボル・フォーマットが利用できます。VS Code 拡張は v1.19.0 以降で自動接続に対応しています。v1.27.0 以降、時刻リテラルへのホバーでは精度（date-time (second) 等）と offset の有無も表示されます。

tdsl lsp

コードアクション（quick fix）は tdsl lint --fix と同一の出力で自動修正します。fixable な lint（start_gt_end / invalid_tags / missing_id）のみ対象です。コメントは可能な限り保持されますが、ブロック内コメントは正準位置へ移動する場合があります。

tdsl lsp は引数を取らず、標準入出力で LSP の JSON-RPC を話します。エディタ側の設定（Neovim / Helix / VS Code）や各機能の使い方、fixable / non-fixable lint の詳細はインストールを参照してください。

fmt

.tdsl を正準スタイル（2 スペースインデント・ブロック間 1 行空け）に整形します（v1.14.0〜）。デフォルトは整形結果を標準出力へ書き出します。--write でファイルを直接上書きし、--check で差分があれば非ゼロ終了します（CI 向け）。

tdsl fmt sample.tdsl           # 整形結果を標準出力へ
tdsl fmt sample.tdsl --write   # ファイルを上書きする
tdsl fmt sample.tdsl --check   # 差分があれば失敗する（CI 向け）

tdsl lint --fix・LSP のドキュメント整形・WebUI の Format ボタンと同一の整形エンジンを使います。コメント（//・/* */）は保持されますが、ブロック内コメントは正準位置へ移動する場合があります。

Wikidata起点

Wikidataから候補QIDを探し、年表化しやすい情報を確認してから .tdsl 雛形を生成します。

tdsl search "漢王朝" --lang ja -n 5
tdsl inspect Q7209 --lang ja,en
tdsl scaffold wikidata \
  --qids Q7183,Q7209 \
  --timeline "中国王朝(生成)" \
  --lang ja,en \
  --target auto \
  --lane-mode per-entity \
  --output china.tdsl
tdsl render china.tdsl --output china.html

コマンド	用途
`tdsl search <QUERY>`	Wikidataの候補QIDを検索する
`tdsl inspect <QID>`	QIDの年表化方針を確認する
`tdsl fetch <QID>`	Wikidataエンティティのデータを表示する
`tdsl resolve <URL>`	Wikipedia記事URLからWikidata QIDを解決する
`tdsl scaffold wikidata`	複数QIDから `.tdsl` 雛形を生成する

search、inspect、resolve は --json に対応しています。CIや別ツールから扱う場合に使います。

手作業起点

空の年表を作ってから、CSVで項目を追加できます。

tdsl init \
  --output manual.tdsl \
  --timeline "架空世界年表" \
  --range-start 1000 \
  --range-end 1300 \
  --lanes "王国:kingdom,事件:incidents"

tdsl import-csv items.csv --append manual.tdsl
tdsl lint manual.tdsl --fix
tdsl render manual.tdsl --output manual.html

import-csv は lane,type,start,end,time,label,tags,id のヘッダー行を持つUTF-8 CSVを入力にします。start / end / time 列は YYYY / YYYY-MM / YYYY-MM-DD の日付精度に加え、YYYY-MM-DDTHH:MM / YYYY-MM-DDTHH:MM:SS の時刻精度と Z / ±HH:MM のUTCオフセットを受理します（月・日精度は v1.10.0〜、時刻・秒・オフセットはDSL本体の時刻リテラルパーサに準拠）。source / origin 列は任意かつ独立に判定されるため、どちらか一方のみを含む9列CSVもそのまま受理し、両方を含む export-csv 出力の10列CSVも往復できます（v1.26.0〜）。

export-csv

IR（.tdsl または .json）をCSVへ書き出します（v1.23.0〜）。import-csv が受理する8列（lane,type,start,end,time,label,tags,id）に source / origin を加えた10列を出力し、source / origin を含めて全10列が import-csv とラウンドトリップします（v1.26.0〜）。start / end / time の秒精度・UTCオフセット（Z / ±HH:MM）も欠落せずラウンドトリップします（v1.27.0〜。それ以前は無声で破棄されていました）。origin=wikidata の行は source が wd:Q<id> 形式であることが必須で、不整合はCSV行番号付きエラーになります。

tdsl export-csv manual.tdsl --output manual.csv
tdsl export-csv manual.tdsl --offline --output manual.csv

キャッシュ管理

tdsl build / tdsl render はWikidataの取得結果をローカルにキャッシュします。tdsl cache サブコマンドでキャッシュを操作できます（v1.1.0〜）。

tdsl cache status               # キャッシュの統計情報（件数・合計サイズ・最古/最新エントリ）を表示する
tdsl cache clear                # すべてのキャッシュを削除する
tdsl cache clear --older-than 7 # 7日より古いエントリのみ削除する

コマンド	用途
`tdsl cache status`	キャッシュの統計情報を表示する
`tdsl cache clear [OPTIONS]`	キャッシュエントリを削除する
`--older-than <DAYS>`（`clear`）	指定日数より古いエントリのみ削除する（デフォルトは全件削除）

キャッシュの保存場所はOSのキャッシュディレクトリ（dirs クレートの cache_dir、例: ~/.cache/tdsl/）以下です。--no-cache を渡すとキャッシュを使わずにWikidataを再取得します。

よく使うオプション

オプション	対象	用途
`--pretty`	`build`	JSONを読みやすく整形する
`--output`, `-o`	`build`, `render`, `init`, `import-csv`	出力先を指定する
`--offline`	`build`, `render`	Wikidata取得をスキップする
`--no-cache`	`build`, `render`	Wikidataキャッシュを使わず再取得する
`--cache-ttl <秒>`	`build`, `render`	WikidataキャッシュのTTLを指定する
`--wikidata-timeout <秒>`	`build`, `render`, `search`, `inspect`	WikidataへのHTTPタイムアウト秒数を指定する（v1.4.0〜）
`--format html,svg,png,pdf`	`render`	出力形式を指定する（デフォルト `html`、`--format pdf` は v1.11.0〜）
`--dpi <数値>`	`render`	PNG ラスタライズ解像度を指定する（デフォルト 96、`--png-scale` と排他、v1.11.0〜）
`--png-scale <倍率>`	`render`	PNG 出力の倍率を指定する（`--dpi` と排他、v1.11.0〜）
`--orientation horizontal,vertical`	`render`	タイムラインの向きを指定する（デフォルト `horizontal`、v1.13.0〜）
`--grid decade,year,month,none`	`render`	背景にグリッド線を描画する（デフォルト `none`、v1.14.0〜）
`--show-event-labels`	`render`	イベント / event_range のラベルを常時表示する（v1.17.0〜）
`--lane-height <px>`	`render`	lane の高さと縦密度を指定する（デフォルト 60、v1.21.0〜）
`--layout-style timeline,group-bands,gantt,zigzag`	`render`	レイアウト方式を指定する。`group-bands` は era/group の背景帯、`gantt` は月グリッド強調と期間ラベル常時表示、`zigzag` はレーン内アイテムの上下交互配置を行う(`zigzag` は lane数が2以下の場合のみ有効。それ以外は `timeline` にフォールバックする)(デフォルト `timeline`、`group-bands` は v1.23.0〜、`gantt` / `zigzag` は v1.24.0〜)
`--show-legend`	`render`	lane ・タグの色を示す静的な凡例パネルを追加する（v1.23.0〜）
`--format text,json`	`lint`	lint結果の出力形式を指定する
`--fix`	`lint`	安全な修正をファイルへ適用する
`--write`	`fmt`	整形結果をファイルへ上書きする（v1.14.0〜）
`--check`	`fmt`	差分があれば非ゼロ終了する（CI 向け、v1.14.0〜）
`--watch`	`render`	入力ファイルを監視して変更時に自動で再レンダリングする（html / svg のみ、v1.16.0〜）
`--show-table`	`render`	時系列順の内容一覧表を追加する。`--format html` ではHTML `<table>`、`svg` / `png` / `pdf` ではタイムライン本体の下にSVG描画で同等の表を追加する（v1.16.0〜）
`--pdf-pagination`	`render`	`--show-table` のアイテムテーブルをPDFの複数ページに分割する（`--show-table` 必須、`--format pdf` のみ。`--chart-pagination` 併用時はテーブルページがチャートページ群の後に続く、v1.27.0〜）
`--chart-pagination <N>`	`render`	チャート本体を lane グループ単位で N レーンずつ複数ページに分割する（`--output` 必須。`svg` は `<stem>.pageN.svg` の複数ファイル、`pdf` は単一PDF内の複数ページ、v1.28.0〜）
`--json-schema`	`build`	TimelineIr の JSON Schema を標準出力（または `--output`）へ書き出す（入力ファイル不要、v1.16.0〜）

視覚効果・動き

読みやすさ