mirror of
https://github.com/SpaceVim/SpaceVim.git
synced 2025-01-23 17:30:04 +08:00
316 lines
15 KiB
Lua
316 lines
15 KiB
Lua
---@tag telescope.previewers
|
|
---@config { ["module"] = "telescope.previewers" }
|
|
|
|
---@brief [[
|
|
--- Provides a Previewer table that has to be implemented by each previewer.
|
|
--- To achieve this, this module also provides two wrappers that abstract most
|
|
--- of the work and make it really easy to create new previewers.
|
|
--- - `previewers.new_termopen_previewer`
|
|
--- - `previewers.new_buffer_previewer`
|
|
---
|
|
--- Furthermore, there are a collection of previewers already defined which
|
|
--- can be used for every picker, as long as the entries of the picker provide
|
|
--- the necessary fields. The more important ones are
|
|
--- - `previewers.cat`
|
|
--- - `previewers.vimgrep`
|
|
--- - `previewers.qflist`
|
|
--- - `previewers.vim_buffer_cat`
|
|
--- - `previewers.vim_buffer_vimgrep`
|
|
--- - `previewers.vim_buffer_qflist`
|
|
---
|
|
--- Previewers can be disabled for any builtin or custom picker by doing
|
|
--- :Telescope find_files previewer=false
|
|
---@brief ]]
|
|
|
|
local Previewer = require "telescope.previewers.previewer"
|
|
local term_previewer = require "telescope.previewers.term_previewer"
|
|
local buffer_previewer = require "telescope.previewers.buffer_previewer"
|
|
|
|
local previewers = {}
|
|
|
|
--- This is the base table all previewers have to implement. It's possible to
|
|
--- write a wrapper for this because most previewers need to have the same
|
|
--- keys set.
|
|
--- Examples of wrappers are:
|
|
--- - `new_buffer_previewer`
|
|
--- - `new_termopen_previewer`
|
|
---
|
|
--- To create a new table do following:
|
|
--- - `local new_previewer = Previewer:new(opts)`
|
|
---
|
|
--- What `:new` expects is listed below
|
|
---
|
|
--- The interface provides the following set of functions. All of them, besides
|
|
--- `new`, will be handled by telescope pickers.
|
|
--- - `:new(opts)`
|
|
--- - `:preview(entry, status)`
|
|
--- - `:teardown()`
|
|
--- - `:send_input(input)`
|
|
--- - `:scroll_fn(direction)`
|
|
---
|
|
--- `Previewer:new()` expects a table as input with following keys:
|
|
--- - `setup` function(self): Will be called the first time preview will be
|
|
--- called.
|
|
--- - `teardown` function(self): Will be called on clean up.
|
|
--- - `preview_fn` function(self, entry, status): Will be called each time
|
|
--- a new entry was selected.
|
|
--- - `title` function(self): Will return the static title of the previewer.
|
|
--- - `dynamic_title` function(self, entry): Will return the dynamic title of
|
|
--- the previewer. Will only be called
|
|
--- when config value dynamic_preview_title
|
|
--- is true.
|
|
--- - `send_input` function(self, input): This is meant for
|
|
--- `termopen_previewer` and it can be
|
|
--- used to send input to the terminal
|
|
--- application, like less.
|
|
--- - `scroll_fn` function(self, direction): Used to make scrolling work.
|
|
previewers.Previewer = Previewer
|
|
|
|
--- A shorthand for creating a new Previewer.
|
|
--- The provided table will be forwarded to `Previewer:new(...)`
|
|
previewers.new = function(...)
|
|
return Previewer:new(...)
|
|
end
|
|
|
|
--- Is a wrapper around Previewer and helps with creating a new
|
|
--- `termopen_previewer`.
|
|
---
|
|
--- It requires you to specify one table entry `get_command(entry, status)`.
|
|
--- This `get_command` function has to return the terminal command that will be
|
|
--- executed for each entry. Example:
|
|
--- <code>
|
|
--- get_command = function(entry, status)
|
|
--- return { 'bat', entry.path }
|
|
--- end
|
|
--- </code>
|
|
---
|
|
--- Additionally you can define:
|
|
--- - `title` a static title for example "File Preview"
|
|
--- - `dyn_title(self, entry)` a dynamic title function which gets called
|
|
--- when config value `dynamic_preview_title = true`
|
|
---
|
|
--- It's an easy way to get your first previewer going and it integrates well
|
|
--- with `bat` and `less`. Providing out of the box scrolling if the command
|
|
--- uses less.
|
|
---
|
|
--- Furthermore, it will forward all `config.set_env` environment variables to
|
|
--- that terminal process.
|
|
previewers.new_termopen_previewer = term_previewer.new_termopen_previewer
|
|
|
|
--- Provides a `termopen_previewer` which has the ability to display files.
|
|
--- It will always show the top of the file and has support for
|
|
--- `bat`(prioritized) and `cat`. Each entry has to provide either the field
|
|
--- `path` or `filename` in order to make this previewer work.
|
|
---
|
|
--- The preferred way of using this previewer is like this
|
|
--- `require('telescope.config').values.cat_previewer`
|
|
--- This will respect user configuration and will use `buffer_previewers` in
|
|
--- case it's configured that way.
|
|
previewers.cat = term_previewer.cat
|
|
|
|
--- Provides a `termopen_previewer` which has the ability to display files at
|
|
--- the provided line. It has support for `bat`(prioritized) and `cat`.
|
|
--- Each entry has to provide either the field `path` or `filename` and
|
|
--- a `lnum` field in order to make this previewer work.
|
|
---
|
|
--- The preferred way of using this previewer is like this
|
|
--- `require('telescope.config').values.grep_previewer`
|
|
--- This will respect user configuration and will use `buffer_previewers` in
|
|
--- case it's configured that way.
|
|
previewers.vimgrep = term_previewer.vimgrep
|
|
|
|
--- Provides a `termopen_previewer` which has the ability to display files at
|
|
--- the provided line or range. It has support for `bat`(prioritized) and
|
|
--- `cat`. Each entry has to provide either the field `path` or `filename`,
|
|
--- `lnum` and a `start` and `finish` range in order to make this previewer
|
|
--- work.
|
|
---
|
|
--- The preferred way of using this previewer is like this
|
|
--- `require('telescope.config').values.qflist_previewer`
|
|
--- This will respect user configuration and will use buffer previewers in
|
|
--- case it's configured that way.
|
|
previewers.qflist = term_previewer.qflist
|
|
|
|
--- An interface to instantiate a new `buffer_previewer`.
|
|
--- That means that the content actually lives inside a vim buffer which
|
|
--- enables us more control over the actual content. For example, we can
|
|
--- use `vim.fn.search` to jump to a specific line or reuse buffers/already
|
|
--- opened files more easily.
|
|
--- This interface is more complex than `termopen_previewer` but offers more
|
|
--- flexibility over your content.
|
|
--- It was designed to display files but was extended to also display the
|
|
--- output of terminal commands.
|
|
---
|
|
--- In the following options, state table and general tips are mentioned to
|
|
--- make your experience with this previewer more seamless.
|
|
---
|
|
---
|
|
--- options:
|
|
--- - `define_preview = function(self, entry, status)` (required)
|
|
--- Is called for each selected entry, after each selection_move
|
|
--- (up or down) and is meant to handle things like reading file,
|
|
--- jump to line or attach a highlighter.
|
|
--- - `setup = function(self)` (optional)
|
|
--- Is called once at the beginning, before the preview for the first
|
|
--- entry is displayed. You can return a table of vars that will be
|
|
--- available in `self.state` in each `define_preview` call.
|
|
--- - `teardown = function(self)` (optional)
|
|
--- Will be called at the end, when the picker is being closed and is
|
|
--- meant to clean up everything that was allocated by the previewer.
|
|
--- The `buffer_previewer` will automatically clean up all created buffers.
|
|
--- So you only need to handle things that were introduced by you.
|
|
--- - `keep_last_buf = true` (optional)
|
|
--- Will not delete the last selected buffer. This would allow you to
|
|
--- reuse that buffer in the select action. For example, that buffer can
|
|
--- be opened in a new split, rather than recreating that buffer in
|
|
--- an action. To access the last buffer number:
|
|
--- `require('telescope.state').get_global_key("last_preview_bufnr")`
|
|
--- - `get_buffer_by_name = function(self, entry)`
|
|
--- Allows you to set a unique name for each buffer. This is used for
|
|
--- caching purposes. `self.state.bufname` will be nil if the entry was
|
|
--- never loaded or the unique name when it was loaded once. For example,
|
|
--- useful if you have one file but multiple entries. This happens for grep
|
|
--- and lsp builtins. So to make the cache work only load content if
|
|
--- `self.state.bufname ~= entry.your_unique_key`
|
|
--- - `title` a static title for example "File Preview"
|
|
--- - `dyn_title(self, entry)` a dynamic title function which gets called
|
|
--- when config value `dynamic_preview_title = true`
|
|
---
|
|
--- `self.state` table:
|
|
--- - `self.state.bufnr`
|
|
--- Is the current buffer number, in which you have to write the loaded
|
|
--- content.
|
|
--- Don't create a buffer yourself, otherwise it's not managed by the
|
|
--- buffer_previewer interface and you will probably be better off
|
|
--- writing your own interface.
|
|
--- - self.state.winid
|
|
--- Current window id. Useful if you want to set the cursor to a provided
|
|
--- line number.
|
|
--- - self.state.bufname
|
|
--- Will return the current buffer name, if `get_buffer_by_name` is
|
|
--- defined. nil will be returned if the entry was never loaded or when
|
|
--- `get_buffer_by_name` is not set.
|
|
---
|
|
--- Tips:
|
|
--- - If you want to display content of a terminal job, use:
|
|
--- `require('telescope.previewers.utils').job_maker(cmd, bufnr, opts)`
|
|
--- - `cmd` table: for example { 'git', 'diff', entry.value }
|
|
--- - `bufnr` number: in which the content will be written
|
|
--- - `opts` table: with following keys
|
|
--- - `bufname` string: used for cache
|
|
--- - `value` string: used for cache
|
|
--- - `mode` string: either "insert" or "append". "insert" is default
|
|
--- - `env` table: define environment variables. Example:
|
|
--- - `{ ['PAGER'] = '', ['MANWIDTH'] = 50 }`
|
|
--- - `cwd` string: define current working directory for job
|
|
--- - `callback` function(bufnr, content): will be called when job
|
|
--- is done. Content will be nil if job is already loaded.
|
|
--- So you can do highlighting only the first time the previewer
|
|
--- is created for that entry.
|
|
--- Use the returned `bufnr` and not `self.state.bufnr` in callback,
|
|
--- because state can already be changed at this point in time.
|
|
--- - If you want to attach a highlighter use:
|
|
--- - `require('telescope.previewers.utils').highlighter(bufnr, ft)`
|
|
--- - This will prioritize tree sitter highlighting if available for
|
|
--- environment and language.
|
|
--- - `require('telescope.previewers.utils').regex_highlighter(bufnr, ft)`
|
|
--- - `require('telescope.previewers.utils').ts_highlighter(bufnr, ft)`
|
|
--- - If you want to use `vim.fn.search` or similar you need to run it in
|
|
--- that specific buffer context. Do
|
|
--- <code>
|
|
--- vim.api.nvim_buf_call(bufnr, function()
|
|
--- -- for example `search` and `matchadd`
|
|
--- end)
|
|
--- </code>
|
|
--- to achieve that.
|
|
--- - If you want to read a file into the buffer it's best to use
|
|
--- `buffer_previewer_maker`. But access this function with
|
|
--- `require('telescope.config').values.buffer_previewer_maker`
|
|
--- because it can be redefined by users.
|
|
previewers.new_buffer_previewer = buffer_previewer.new_buffer_previewer
|
|
|
|
--- A universal way of reading a file into a buffer previewer.
|
|
--- It handles async reading, cache, highlighting, displaying directories
|
|
--- and provides a callback which can be used, to jump to a line in the buffer.
|
|
---@param filepath string: String to the filepath, will be expanded
|
|
---@param bufnr number: Where the content will be written
|
|
---@param opts table: keys: `use_ft_detect`, `bufname` and `callback`
|
|
previewers.buffer_previewer_maker = buffer_previewer.file_maker
|
|
|
|
--- A previewer that is used to display a file. It uses the `buffer_previewer`
|
|
--- interface and won't jump to the line. To integrate this one into your
|
|
--- own picker make sure that the field `path` or `filename` is set for
|
|
--- each entry.
|
|
--- The preferred way of using this previewer is like this
|
|
--- `require('telescope.config').values.file_previewer`
|
|
--- This will respect user configuration and will use `termopen_previewer` in
|
|
--- case it's configured that way.
|
|
previewers.vim_buffer_cat = buffer_previewer.cat
|
|
|
|
--- A previewer that is used to display a file and jump to the provided line.
|
|
--- It uses the `buffer_previewer` interface. To integrate this one into your
|
|
--- own picker make sure that the field `path` or `filename` and `lnum` is set
|
|
--- in each entry. If the latter is not present, it will default to the first
|
|
--- line.
|
|
--- The preferred way of using this previewer is like this
|
|
--- `require('telescope.config').values.grep_previewer`
|
|
--- This will respect user configuration and will use `termopen_previewer` in
|
|
--- case it's configured that way.
|
|
previewers.vim_buffer_vimgrep = buffer_previewer.vimgrep
|
|
|
|
--- Is the same as `vim_buffer_vimgrep` and only exists for consistency with
|
|
--- `term_previewers`.
|
|
---
|
|
--- The preferred way of using this previewer is like this
|
|
--- `require('telescope.config').values.qflist_previewer`
|
|
--- This will respect user configuration and will use `termopen_previewer` in
|
|
--- case it's configured that way.
|
|
previewers.vim_buffer_qflist = buffer_previewer.qflist
|
|
|
|
--- A previewer that shows a log of a branch as graph
|
|
previewers.git_branch_log = buffer_previewer.git_branch_log
|
|
|
|
--- A previewer that shows a diff of a stash
|
|
previewers.git_stash_diff = buffer_previewer.git_stash_diff
|
|
|
|
--- A previewer that shows a diff of a commit to a parent commit.<br>
|
|
--- The run command is `git --no-pager diff SHA^! -- $CURRENT_FILE`
|
|
---
|
|
--- The current file part is optional. So is only uses it with bcommits.
|
|
previewers.git_commit_diff_to_parent = buffer_previewer.git_commit_diff_to_parent
|
|
|
|
--- A previewer that shows a diff of a commit to head.<br>
|
|
--- The run command is `git --no-pager diff --cached $SHA -- $CURRENT_FILE`
|
|
---
|
|
--- The current file part is optional. So is only uses it with bcommits.
|
|
previewers.git_commit_diff_to_head = buffer_previewer.git_commit_diff_to_head
|
|
|
|
--- A previewer that shows a diff of a commit as it was.<br>
|
|
--- The run command is `git --no-pager show $SHA:$CURRENT_FILE` or `git --no-pager show $SHA`
|
|
previewers.git_commit_diff_as_was = buffer_previewer.git_commit_diff_as_was
|
|
|
|
--- A previewer that shows the commit message of a diff.<br>
|
|
--- The run command is `git --no-pager log -n 1 $SHA`
|
|
previewers.git_commit_message = buffer_previewer.git_commit_message
|
|
|
|
--- A previewer that shows the current diff of a file. Used in git_status.<br>
|
|
--- The run command is `git --no-pager diff $FILE`
|
|
previewers.git_file_diff = buffer_previewer.git_file_diff
|
|
|
|
previewers.ctags = buffer_previewer.ctags
|
|
previewers.builtin = buffer_previewer.builtin
|
|
previewers.help = buffer_previewer.help
|
|
previewers.man = buffer_previewer.man
|
|
previewers.autocommands = buffer_previewer.autocommands
|
|
previewers.highlights = buffer_previewer.highlights
|
|
previewers.pickers = buffer_previewer.pickers
|
|
|
|
--- A deprecated way of displaying content more easily. Was written at a time,
|
|
--- where the buffer_previewer interface wasn't present. Nowadays it's easier
|
|
--- to just use this. We will keep it around for backwards compatibility
|
|
--- because some extensions use it.
|
|
--- It doesn't use cache or some other clever tricks.
|
|
previewers.display_content = buffer_previewer.display_content
|
|
|
|
return previewers
|