Commands

tdsl は .tdsl ファイルの検証、JSON IRへのコンパイル、HTMLレンダリング、Wikidata起点の年表作成、手作業向けテンプレート生成を扱います。

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〜）

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〜）。

tdsl decompile sample.json --output sample.tdsl

merge

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

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

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 編集中にリアルタイム診断・補完・ホバー・定義ジャンプ・参照検索・リネーム・コードアクション・ドキュメントシンボルが利用できます。

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 の 3 精度を受理します（月・日精度は v1.10.0〜）。

キャッシュ管理

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

tdsl cache list            # キャッシュ済みエントリの一覧を表示する
tdsl cache clear           # すべてのキャッシュを削除する
tdsl cache clear --dry-run # 削除対象を確認する（実際には削除しない）

コマンド	用途
tdsl cache list	キャッシュ済みエントリとサイズを表示する
tdsl cache clear	すべてのキャッシュエントリを削除する

キャッシュの保存場所はOSのデータディレクトリ（dirs クレートの data_dir）以下です。--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〜）
--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	SVG の後ろに時系列順の内容一覧表を追加する（HTML 形式のみ、v1.16.0〜）
--json-schema	build	TimelineIr の JSON Schema を標準出力（または --output）へ書き出す（入力ファイル不要、v1.16.0〜）