#概要

telescope.nvimの拡張(ソース)の作り方のいい文献があまり見つからなかったのでメモ。

#基本構造

telescope.nvimの拡張はlua/telescope/_extensions/[source]以下のディレクトリに置き、

require("telescope").load_extension "source"

をすることで読み込まれる。

このsourceディレクトリ以下を作成するのが基本的な流れ。 この中でtelescope.register_extensionをすることで拡張を登録できる。 これ以下のコードでは、この拡張の名前をsourceとする。

local telescope = require "telescope"
 
return telescope.register_extension({
  setup = setup,
  exports = {
    command = picker
  },
})

telescope.register_extensionにはsetupとexportsというキーを持ったテーブルを登録することができる。

#setup

まず、setupには関数を指定するが、ここではユーザーがTelescopeのsetup関数で設定した値を受け取ることができる。つまり、

require("telescope").setup({
  extensions = {
    source = {} -- ←ココ
})

上のコード内で示した部分のテーブルを受け取ることができる。これは主にキーマッピングを設定する際などに使用される。

#exports

次にexportsだが、ここに拡張の実体を指定することになる。exportsは{[command]: Picker}の形式のテーブルを受け取る。ここでコマンド名がソース名と一致していれば、:Telescope sourceを実行することでピッカーを実行できる。一方、一致していない場合はTelescope source commandに割り当てられる。

#picker

pickerというのがTelescope拡張の実体であり、ここに指定した関数が実行される。pickerの例を下に示す。

local pickers = require("telescope.pickers")
local sorters = require("telescope.sorters")
 
local picker = function(opts)
	pickers
		.new(opts, {
			prompt_title = "Search",
			sorter = sorters.get_generic_fuzzy_sorter(),
			previewer = previewer,
			finder = finders.new_table({
				results = flat_data,
				entry_maker = function(entry)
					return {
						value = entry,
						display = entry,
						ordinal = entry,
					}
				end,
			}),
			attach_mappings = function(prompt_bufnr, map)
				return true
			end,
		})
		:find()
 
end

見ての通りだが、telescope.pickers.newに色々なオプションを指定することで動作をカスタマイズできる。

• sorter: ソートする関数を指定する。sorters.get_generic_fuzzy_sorter()で問題ないことが多いと思う。
• previewer: (選択中の)entryを受け取り、プレビューの内容を決める。
• finder: ここが一番重要なところ。ここではfinders.new_tableを使って、配列からfinderを作成している。entry_makerで返すテーブルは、valueがpickerに渡される値、displayが一覧画面で表示される文字列、ordinalが検索に使用される文字列。 他にも外部コマンドを実行して結果を得るなどできる。