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

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 編集中にリアルタイム診断・コンテキスト依存補完・ホバー・定義ジャンプ・参照検索・リネーム・コードアクション・ドキュメントシンボル・フォーマットが利用できます。VS Code 拡張は v1.19.0 以降で自動接続に対応しています。

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

export-csv

IR（.tdsl または .json）をCSVへ書き出します（v1.23.0〜）。import-csv が受理する8列（lane,type,start,end,time,label,tags,id）に source / origin を加えた10列を出力し、8列部分は import-csv と往復できます。source / origin は参照用に保持されますが import-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 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〜） | | --show-event-labels | render | イベント / event_range のラベルを常時表示する（v1.17.0〜） | | --lane-height <px> | render | lane の高さと縦密度を指定する（デフォルト 60、v1.21.0〜） | | --layout-style timeline,group-bands | render | レイアウト方式を指定する。group-bands は era/group の背景帯を描画する（デフォルト timeline、v1.23.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 | SVG の後ろに時系列順の内容一覧表を追加する（HTML 形式のみ、v1.16.0〜） | | --json-schema | build | TimelineIr の JSON Schema を標準出力（または --output）へ書き出す（入力ファイル不要、v1.16.0〜） |