コンテンツにスキップ
Timeline DSL

インストール

Timeline DSL はCLIツールとして利用します。初期サイトでは Homebrew 経由の導入を前提に案内します。

Terminal window
brew tap keroway/tap
brew install tdsl

インストール後、CLIが実行できることを確認します。

Terminal window
tdsl --help

必要な環境

Section titled “必要な環境”
  • macOS または Linux（Homebrew 経由）
  • Windows（バイナリ手動インストール）
  • Git

Homebrew 以外の導入方法（Linux ワンラインインストール、Windows バイナリ、cargo）は Homebrewとその他の導入方法 を参照してください。

VS Code 拡張

Section titled “VS Code 拡張”

v1.0.0 以降、構文ハイライトを提供する VS Code 拡張機能があります。v1.2.0 から Marketplace で公開されており、v1.4.0 以降はスニペットも利用できます。

インストール

Section titled “インストール”

VS Code の拡張機能パネル（Ctrl+Shift+X / Cmd+Shift+X）で Timeline DSL を検索してインストールします。または以下のコマンドを実行します。

Terminal window
code --install-extension keroway.timeline-dsl

利用可能なスニペット

Section titled “利用可能なスニペット”
プレフィックス展開内容
timelinetimeline ブロックのテンプレート（title、unit、range、calendar 込み）
lanelane 定義のテンプレート（kind、order 込み）
spanspan イベントのテンプレート（開始・終了日時付き）

スニペットはファイル拡張子が .tdsl のファイルで有効です。

VS Code 拡張は構文ハイライトとスニペットを提供します。診断・補完・ホバー・定義ジャンプといった対話的な機能は、次の言語サーバ（LSP）が担当します。

言語サーバ (LSP)

Section titled “言語サーバ (LSP)”

v1.11.0 以降、tdsl lsp で Timeline DSL の言語サーバ（LSP）を起動できます。LSP は標準入出力（stdio）で通信するため、LSP クライアントを持つエディタ（VS Code・Neovim・Helix・Emacs など）から接続して、.tdsl 編集中に対話的な支援を受けられます。VS Code 拡張（構文ハイライト + スニペット）とは独立した仕組みです。

機能内容バージョン
診断（Diagnostics）構文・意味エラーを編集中にリアルタイム表示するv1.11.0〜
補完（Completion）DSL キーワードを補完するv1.12.0〜
ホバー（Hover）lane ID / QID のホバー情報を表示するv1.12.0〜
定義ジャンプ（Goto Definition）lane 参照から lane 宣言へジャンプするv1.12.0〜
参照検索（References）lane ID の宣言・全参照位置を返すv1.13.0〜
リネーム（Rename）lane ID を宣言・全参照まとめて一括置換するv1.13.0〜
コードアクション（Code Action）lint の自動修正を quick fix として提供するv1.13.0〜
ドキュメントシンボル（Document Symbol）timeline > lane > 項目の階層シンボルを返すv1.13.0〜
ドキュメント整形（Formatting）全文を正準スタイルに整形するv1.14.0〜

起動コマンドは引数を取りません。

Terminal window
tdsl lsp

各エディタからは、コマンド tdsl lsp を .tdsl（言語 ID: tdsl）に紐づく言語サーバとして登録します。Neovim（0.10 以降のコア LSP、プラグイン不要）の例:

vim.filetype.add({ extension = { tdsl = "tdsl" } })


vim.api.nvim_create_autocmd("FileType", {
  pattern = "tdsl",
  callback = function()
    vim.lsp.start({
      name = "tdsl-lsp",
      cmd = { "tdsl", "lsp" },
      root_dir = vim.fs.root(0, { ".git" }),
    })
  end,
})

Helix の場合は languages.toml に登録します。

~/.config/helix/languages.toml
[language-server.tdsl-lsp]
command = "tdsl"
args = ["lsp"]


[[language]]
name = "tdsl"
scope = "source.tdsl"
file-types = ["tdsl"]
language-servers = ["tdsl-lsp"]

VS Code には .tdsl 専用の LSP クライアントは無いため、汎用 LSP クライアント拡張から「言語 ID tdsl / コマンド tdsl lsp / stdio」として登録します。構文ハイライトとスニペットを提供する VS Code 拡張とは独立して動くため、両方を同時に有効化できます。

各機能の使い方

Section titled “各機能の使い方”
  • 診断 / 補完 / ホバー / 定義ジャンプ: 編集中に構文・意味エラーがリアルタイム表示され、DSL キーワードの補完、lane ID / QID のホバー、lane 参照から宣言へのジャンプが使えます。
  • 参照検索（References）: lane の宣言または参照箇所にカーソルを置くと、その lane ID の全参照（lane 宣言・span / event / event_range の lane 指定・map の lane プロパティ）が一覧されます。
  • リネーム（Rename）: lane ID 上でリネームすると宣言と全参照が一括置換されます。lane ID 以外（キーワードや文字列リテラル）の上ではリネームできません。
  • ドキュメントシンボル（Document Symbol）: timeline > lane > 項目（span / event / event_range）の階層でアウトラインを返します。
  • ドキュメント整形（Formatting）: エディタの整形コマンドで全文を正準スタイルに整形します（v1.14.0〜）。CLI の tdsl fmt と同一の整形エンジンを使います。整形を適用するとコメント（//・/* */）は失われます。

すべての機能はソーステキストの静的解析で動き、ネットワーク I/O は不要（offline）です。

コードアクションと fixable / non-fixable lint

Section titled “コードアクションと fixable / non-fixable lint”

コードアクションは tdsl lint --fix 相当の自動修正を quick fix として提示します。lint には自動修正できるものとできないものがあります。

種別対象 lintコードアクション
fixablestart_gt_end / invalid_tags / missing_idquick fix「自動修正可能な lint をすべて修正」を提示
non-fixableunknown_lane / duplicate_id / empty_labelquick fix は出ない（手で修正する）

fixable な issue が 1 件も無い場合、quick fix は表示されません。適用すると tdsl lint --fix と同一の emitter でドキュメント全文が整形・置換されるため、ソース中のコメントは失われます（全文再 emit 方式のため）。出力は tdsl lint --fix と一致します。

tdsl lsp の概要は Commands も参照してください。