feat: expose completion APIs for external integrations

README.md

@@ -132,6 +132,18 @@ require("skkelua").config({
   この項目だけのメニューが開くので、変換キーを使わずに新しい単語を登録できます
 - skkelua の有効・無効に連動して補完も付いたり外れたりします
 
+### 外部の補完 UI との連携
+
+`skkelua.completion.get()` / `accept()` で候補生成と確定処理を共有できます。
+`skkelua.lsp.start(bufnr)` は、既定の文書解決を使い、バッファ間で LSP クライアントを共有します。
+組み込み UI は有効化しません。要求 URI と入力先の対応や、その要求が現在の入力を対象とするかの判定は接続側が担当します。
+`skkelua.lsp.new_server()` で接続を自前で管理することもでき、
+`skkelua.completion.set_adapter()` で外部 UI の選択状態・確定キー・再補完を接続します。
+`completion.enabled` に関係なく、従来の cmp / pum.vim の自動検出と確定キー連携も使えます。
+`false` では組み込み補完を無効にし、外部側で接続を設定できます。
+明示的なアダプターは自動検出より優先されます。各 UI の候補ソースや確定後の学習は外部側で接続します。
+詳細は `:help skkelua-completion-extension` を参照してください。
+
 ## skkeleton との関係
 
 skkelua は [vim-skk/skkeleton](https://github.com/vim-skk/skkeleton) の
@@ -153,7 +165,7 @@ denops 版との主な違い:
 | 変換ごとの undo 区切り (`setUndoPoint`) | デフォルト有効 | デフォルト無効 |
 | SKK サーバー | 非同期 TCP | 同期 TCP (タイムアウト 1 秒) |
 | Google 日本語入力 | fetch | curl |
-| ddc.vim ソース | 同梱 | 非同梱 (補完用 Lua API を提供) |
+| ddc.vim ソース | 同梱 | 非同梱 (UI 非依存の候補・確定 API と LSP transport を提供) |
 
 ## Development
 

doc/skkelua.txt

@@ -143,6 +143,8 @@ require("skkelua").get_default_mapped_keys()
 
 補完プラグイン連携用 API ~
                                                   *skkelua-completion-api*
+外部補完の接続は |skkelua-completion-extension| を参照してください。
+
 require("skkelua").get_pre_edit()
 	現在のプリエディット文字列を返します。
 require("skkelua").get_pre_edit_length()
@@ -185,7 +187,9 @@ config() に渡せる主なオプション (括弧内はデフォルト値):
 acceptIllegalResult (false)
 	かなに変換できなかった入力をそのまま残すかどうか。
 completion ({ enabled = false })
-	変換候補の builtin LSP 補完。|skkelua-completion| 参照。
+	変換候補の builtin LSP 補完を設定します。
+	cmp / pum.vim の確定キー連携は、この設定に関係なく利用できます。
+	|skkelua-completion| 参照。
 completionRankFile ("")
 	補完候補ランクの保存先ファイル。設定すると補完候補の並び順
 	(確定が新しい候補ほど上、|skkelua-completion| 参照) が
@@ -346,6 +350,110 @@ Note: |vim.lsp.completion.enable()| は最初にバッファの補完状態を
 他の設定・プラグインが opts 無しで enable(true) を呼ぶと、skkelua の
 autotrigger が失われて候補が自動表示されなくなります。
 
+外部補完との接続                               *skkelua-completion-extension*
+
+外部プラグインは候補生成・確定処理を再実装せず、以下の API を利用できます。
+UI の表示、絞り込み、キー設定、LSP client の起動・停止は外部側が所有します。
+completion.enabled に関係なく、表示中の cmp / pum.vim
+を自動検出して確定キーを連携します (pum.vim、cmp、native の順)。既存の
+補完 UI との確定連携であり、各 UI の候補ソースを自動設定するものではありません。
+
+自前で接続を管理する場合は completion.enabled = false にしてください。
+組み込み補完を無効にし、以下の API は利用できます。
+cmp / pum.vim の自動検出は引き続き有効です。
+
+require("skkelua.completion").get({context})
+	現在の SKK 状態から LSP CompletionList を返します。context は
+	{ line = 行の全文, row = 0 始まりの行番号, col = 0 始まりのバイト位置 }
+	です。文字位置は UTF-8 で、Insert バッファにもコマンドラインにも
+	使えます。渡したカーソルの直前が現在の pre-edit と一致しない場合や
+	SKK 無効時は空の items を返します。要求対象が現在の SKK 入力先かは
+	呼び出し側で判定してください (SKK 状態は文書ごとではありません)。
+	送りなし・送りあり・変換中・abbrev の候補、注釈、学習順、辞書登録項目
+	を共通で生成します。'completeopt' や UI、カーソルには触れません。
+	textEdit は pre-edit 全体を置換する PlainText です。insertText にも同じ
+	文字列を設定するため、表示用 label を挿入文字列に使う必要はありません。
+	候補の表示順には
+	sortText を使い、data を確定時まで保持してください。
+
+require("skkelua.completion").accept({item})
+	実際に確定した元の LSP CompletionItem を一度だけ渡してください。
+	通常候補を学習し、abbrev の入力そのままの候補は学習から除外します。
+	辞書登録項目は次のイベントループで SKK の登録プロンプトを開きます。
+	SKK の項目なら true、それ以外なら false を返します。
+	textEdit の適用は UI 側の責務です。選択・キャンセル時は呼ばず、
+	確定イベントで呼びます。登録項目は pre-edit と入力モードを保持して
+	確定してください。古い候補への遅延した確定通知は渡さないでください。
+
+require("skkelua.lsp").get_context({params}, {bufnr}?)
+	要求 URI に一致するロード済み名前付きバッファから、params.position の行と
+	UTF-8 バイト位置を読み、context とバッファ番号を返します。
+	名前付きバッファが見つからなければ、URI が一致する現在バッファを使います。
+	無名バッファ同士は URI で区別できないため、現在バッファだけを対象にします。
+	文書を新規作成・ロードせず、対象や行が存在しなければ nil を返します。
+	bufnr を指定すると URI の解決を省略し、そのバッファを読みます。
+	無名バッファ・仮想文書・URI の別名に使えますが、URI の検証は呼び出し側の責務です。
+	現在の SKK 入力先かどうかの判定やモード制限は呼び出し側で行ってください。
+
+require("skkelua.lsp").start({bufnr}?)
+	指定バッファ (省略時は現在のバッファ) を外部補完クライアント
+	"skkelua" に接続し、client ID を返します。バッファ間でクライアントを
+	再利用し、接続済みなら再 attach しません。文書解決には上記の get_context を使います。
+	UI を有効化せず、SKK 無効化後も接続を維持します。
+	独自の文書解決が必要な場合は new_server(get_context) と vim.lsp.start() を使います。
+
+require("skkelua.lsp").new_server({get_context}?)
+	|vim.lsp.start()| の cmd に渡す in-process LSP transport を返します。
+	UI は有効化せず、LSP の位置エンコーディングは UTF-8 です。
+	既定では上記の get_context で要求 URI と位置からバッファを読みます。
+	独自の文書解決には get_context(params) から get() と同じ context を
+	返してください。対象外の要求には nil を返すと、空の items を返します。
+	要求 URI と入力先の対応、現在の SKK 入力先かどうかの判定は接続側の責務です。
+	入力モードや補完プラグイン固有のバッファ構成は判定しません。
+	文書同期通知を蓄積するサーバーではありません。文書の内容は要求処理時に
+	バッファまたは get_context から読みます。
+>lua
+	require("skkelua").config({ completion = { enabled = false } })
+	local client_id = vim.lsp.start({
+		name = "skkelua-external",
+		cmd = require("skkelua.lsp").new_server(),
+	}, { bufnr = vim.api.nvim_get_current_buf() })
+<
+	外部側で必要なバッファに attach し、SKK 無効時も接続を維持できます。
+	候補生成側が SKK 無効時に空の items を返します。UI の有効・無効には
+	|skkelua-autocmds| を利用できます。確定時の
+	accept() 呼び出しは LSP を利用する場合も外部側で接続してください。
+
+require("skkelua.completion").set_adapter({adapter}?)
+	補完 UI への接続を一つ登録します。明示的な登録は自動検出より優先されます。
+	nil で登録を解除し、cmp / pum.vim の自動検出に戻します。
+	候補取得だけなら不要ですが、SKK の確定キー・選択挿入・辞書登録後の
+	再補完と協調する場合に必要です。adapter は以下の関数を持ちます。
+
+	state(): { visible: boolean, selected?: { word: string, item: table } }
+		現在の UI 状態を返します。未選択なら selected を省略します。
+		item は元の LSP CompletionItem (他ソースの項目でも可)、word は
+		選択によって挿入済みの文字列です。未挿入なら空文字にします。
+		この情報は確定キー、選択挿入中の削除・接尾辞・purge、補完中の
+		移動キーの判定に使います。UI 非表示時は visible = false を返します。
+	confirm(): string
+		選択を確定するキー列を返します。その場でバッファを変更しないで
+		ください。戻り値は展開済みのキーコード (例: "\25") です。
+		コマンドなら nvim_replace_termcodes() で <Cmd>...<CR> を変換します。
+	trigger(): nil (省略可)
+		辞書登録のキャンセルなどで pre-edit が復元された際に補完を要求します。
+
+	アダプターの登録は SKK の有効・無効や completion.enabled と独立です。
+	同じ補完 UI を使い続ける場合は一度登録すれば十分です。nil を渡すのは
+	明示的な連携を解除するときです。キャンセル処理や
+	キーの保存・復元は外部側で管理します。
+
+設定の選び方:
+	completion.enabled は組み込み補完の有効・無効だけを制御します。
+	cmp / pum.vim の自動検出と確定連携は設定に関係なく利用できます。
+	自動検出を置き換える場合は set_adapter() で明示的に登録します。低水準 API
+	(get_completion_result / complete_callback など) も引き続き使えます。
+
 ==============================================================================
 INDICATOR                                                  *skkelua-indicator*
 
@@ -473,7 +581,7 @@ skkeleton (denops 版) との違い:
 - 辞書ロードは同期です。SKK-JISYO.L 規模で数百 ms かかるため、
   気になる場合は起動後に initialize() を呼んで事前ロードしてください。
 - YAML 辞書、Deno KV データベース (updateDatabase) は非対応です。
-- ddc.vim 用ソースは同梱しません。|skkelua-completion-api| を使って
+- 外部補完用ソースは同梱しません。|skkelua-completion-api| を使って
   補完ソースを実装できます。
 - skkserv への問い合わせは同期実行で、応答が無い場合 1 秒でタイムアウト
   します。