leigh/telescope.nvim
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: document more actions and add introduction to actions (#1829)

Browse Source
This commit is contained in:
Simon Hauser
2022-04-17 14:47:13 +02:00
committed by GitHub
parent b7ae91c82b
commit a5be929142
2 changed files with 461 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files

206
lua/telescope/actions/init.lua
View File

@@ -5,6 +5,55 @@
---@brief [[
--- Actions functions that are useful for people creating their own mappings.
---
--- Actions can be either normal functions that expect the prompt_bufnr as
--- first argument (1) or they can be a custom telescope type called "action" (2).
---
--- (1) The `prompt_bufnr` of a normal function denotes the identifier of your
--- picker which can be used to access the picker state. In practice, users
--- most commonly access from both picker and global state via the following:
---
--- <code>
--- -- for utility functions
--- local action_state = require "telescope.actions.state"
---
--- local actions = {}
--- actions.do_stuff = function(prompt_bufnr)
--- local current_picker = action_state.get_current_picker(prompt_bufnr) -- picker state
--- local entry = action_state.get_selected_entry()
--- end
--- </code>
---
--- See |telescope.actions.state| for more information.
---
--- (2) To transform a module of functions into a module of "action"s, you need
--- to do the following:
---
--- <code>
--- local transform_mod = require("telescope.actions.mt").transform_mod
---
--- local mod = {}
--- mod.a1 = function(prompt_bufnr)
--- -- your code goes here
--- -- You can access the picker/global state as described above in (1).
--- end
---
--- mod.a2 = function(prompt_bufnr)
--- -- your code goes here
--- end
--- mod = transform_mod(mod)
---
--- -- Now the following is possible. This means that actions a2 will be executed
--- -- after action a1. You can chain as many actions as you want.
--- local action = mod.a1 + mod.a2
--- action(bufnr)
--- </code>
---
--- Another interesing thing to do is that these actions now have functions you
--- can call. These functions include `:replace(f)`, `:replace_if(f, c)`,
--- `replace_map(tbl)` and `enhance(tbl)`. More information on these functions
--- can be found in the `developers.md` and `lua/tests/automated/action_spec.lua`
--- file.
---@brief ]]
local a = vim.api
@@ -32,33 +81,33 @@ local actions = setmetatable({}, {
--- Move the selection to the next entry
---@param prompt_bufnr number: The prompt bufnr
function actions.move_selection_next(prompt_bufnr)
actions.move_selection_next = function(prompt_bufnr)
action_set.shift_selection(prompt_bufnr, 1)
end
--- Move the selection to the previous entry
---@param prompt_bufnr number: The prompt bufnr
function actions.move_selection_previous(prompt_bufnr)
actions.move_selection_previous = function(prompt_bufnr)
action_set.shift_selection(prompt_bufnr, -1)
end
--- Move the selection to the entry that has a worse score
---@param prompt_bufnr number: The prompt bufnr
function actions.move_selection_worse(prompt_bufnr)
actions.move_selection_worse = function(prompt_bufnr)
local picker = action_state.get_current_picker(prompt_bufnr)
action_set.shift_selection(prompt_bufnr, p_scroller.worse(picker.sorting_strategy))
end
--- Move the selection to the entry that has a better score
---@param prompt_bufnr number: The prompt bufnr
function actions.move_selection_better(prompt_bufnr)
actions.move_selection_better = function(prompt_bufnr)
local picker = action_state.get_current_picker(prompt_bufnr)
action_set.shift_selection(prompt_bufnr, p_scroller.better(picker.sorting_strategy))
end
--- Move to the top of the picker
---@param prompt_bufnr number: The prompt bufnr
function actions.move_to_top(prompt_bufnr)
actions.move_to_top = function(prompt_bufnr)
local current_picker = action_state.get_current_picker(prompt_bufnr)
current_picker:set_selection(
p_scroller.top(current_picker.sorting_strategy, current_picker.max_results, current_picker.manager:num_results())
@@ -67,7 +116,7 @@ end
--- Move to the middle of the picker
---@param prompt_bufnr number: The prompt bufnr
function actions.move_to_middle(prompt_bufnr)
actions.move_to_middle = function(prompt_bufnr)
local current_picker = action_state.get_current_picker(prompt_bufnr)
current_picker:set_selection(
p_scroller.middle(current_picker.sorting_strategy, current_picker.max_results, current_picker.manager:num_results())
@@ -76,7 +125,7 @@ end
--- Move to the bottom of the picker
---@param prompt_bufnr number: The prompt bufnr
function actions.move_to_bottom(prompt_bufnr)
actions.move_to_bottom = function(prompt_bufnr)
local current_picker = action_state.get_current_picker(prompt_bufnr)
current_picker:set_selection(
p_scroller.bottom(current_picker.sorting_strategy, current_picker.max_results, current_picker.manager:num_results())
@@ -85,21 +134,21 @@ end
--- Add current entry to multi select
---@param prompt_bufnr number: The prompt bufnr
function actions.add_selection(prompt_bufnr)
actions.add_selection = function(prompt_bufnr)
local current_picker = action_state.get_current_picker(prompt_bufnr)
current_picker:add_selection(current_picker:get_selection_row())
end
--- Remove current entry from multi select
---@param prompt_bufnr number: The prompt bufnr
function actions.remove_selection(prompt_bufnr)
actions.remove_selection = function(prompt_bufnr)
local current_picker = action_state.get_current_picker(prompt_bufnr)
current_picker:remove_selection(current_picker:get_selection_row())
end
--- Toggle current entry status for multi select
---@param prompt_bufnr number: The prompt bufnr
function actions.toggle_selection(prompt_bufnr)
actions.toggle_selection = function(prompt_bufnr)
local current_picker = action_state.get_current_picker(prompt_bufnr)
current_picker:toggle_selection(current_picker:get_selection_row())
end
@@ -107,7 +156,7 @@ end
--- Multi select all entries.
--- - Note: selected entries may include results not visible in the results popup.
---@param prompt_bufnr number: The prompt bufnr
function actions.select_all(prompt_bufnr)
actions.select_all = function(prompt_bufnr)
local current_picker = action_state.get_current_picker(prompt_bufnr)
action_utils.map_entries(prompt_bufnr, function(entry, _, row)
if not current_picker._multi:is_selected(entry) then
@@ -126,7 +175,7 @@ end
--- Drop all entries from the current multi selection.
---@param prompt_bufnr number: The prompt bufnr
function actions.drop_all(prompt_bufnr)
actions.drop_all = function(prompt_bufnr)
local current_picker = action_state.get_current_picker(prompt_bufnr)
action_utils.map_entries(prompt_bufnr, function(entry, _, row)
current_picker._multi:drop(entry)
@@ -144,7 +193,7 @@ end
--- Toggle multi selection for all entries.
--- - Note: toggled entries may include results not visible in the results popup.
---@param prompt_bufnr number: The prompt bufnr
function actions.toggle_all(prompt_bufnr)
actions.toggle_all = function(prompt_bufnr)
local current_picker = action_state.get_current_picker(prompt_bufnr)
action_utils.map_entries(prompt_bufnr, function(entry, _, row)
current_picker._multi:toggle(entry)
@@ -159,23 +208,34 @@ function actions.toggle_all(prompt_bufnr)
current_picker:get_status_updater(current_picker.prompt_win, current_picker.prompt_bufnr)()
end
function actions.preview_scrolling_up(prompt_bufnr)
--- Scroll the preview window up
---@param prompt_bufnr number: The prompt bufnr
actions.preview_scrolling_up = function(prompt_bufnr)
action_set.scroll_previewer(prompt_bufnr, -1)
end
function actions.preview_scrolling_down(prompt_bufnr)
--- Scroll the preview window down
---@param prompt_bufnr number: The prompt bufnr
actions.preview_scrolling_down = function(prompt_bufnr)
action_set.scroll_previewer(prompt_bufnr, 1)
end
function actions.results_scrolling_up(prompt_bufnr)
--- Scroll the results window up
---@param prompt_bufnr number: The prompt bufnr
actions.results_scrolling_up = function(prompt_bufnr)
action_set.scroll_results(prompt_bufnr, -1)
end
function actions.results_scrolling_down(prompt_bufnr)
--- Scroll the results window down
---@param prompt_bufnr number: The prompt bufnr
actions.results_scrolling_down = function(prompt_bufnr)
action_set.scroll_results(prompt_bufnr, 1)
end
function actions.center(_)
--- Center the cursor in the window, can be used after selecting a file to edit
--- You can just map `actions.select_default + actions.center`
---@param prompt_bufnr number: The prompt bufnr
actions.center = function(prompt_bufnr)
vim.cmd ":normal! zz"
end
@@ -250,28 +310,49 @@ actions.select_tab = {
-- TODO: consider adding float!
-- https://github.com/nvim-telescope/telescope.nvim/issues/365
function actions.file_edit(prompt_bufnr)
--- Perform file edit on selection, usually something like<br>
--- `:edit <selection>`
---@param prompt_bufnr number: The prompt bufnr
actions.file_edit = function(prompt_bufnr)
return action_set.edit(prompt_bufnr, "edit")
end
function actions.file_split(prompt_bufnr)
--- Perform file split on selection, usually something like<br>
--- `:new <selection>`
---@param prompt_bufnr number: The prompt bufnr
actions.file_split = function(prompt_bufnr)
return action_set.edit(prompt_bufnr, "new")
end
function actions.file_vsplit(prompt_bufnr)
--- Perform file vsplit on selection, usually something like<br>
--- `:vnew <selection>`
---@param prompt_bufnr number: The prompt bufnr
actions.file_vsplit = function(prompt_bufnr)
return action_set.edit(prompt_bufnr, "vnew")
end
function actions.file_tab(prompt_bufnr)
--- Perform file tab on selection, usually something like<br>
--- `:tabedit <selection>`
---@param prompt_bufnr number: The prompt bufnr
actions.file_tab = function(prompt_bufnr)
return action_set.edit(prompt_bufnr, "tabedit")
end
function actions.close_pum(_)
actions.close_pum = function(_)
if 0 ~= vim.fn.pumvisible() then
vim.api.nvim_feedkeys(vim.api.nvim_replace_termcodes("<c-y>", true, true, true), "n", true)
end
end
--- Close the Telescope window, usually used within an action
---@param prompt_bufnr number: The prompt bufnr
actions.close = function(prompt_bufnr)
actions._close(prompt_bufnr, false)
end
--- Close the Telescope window and specify if you want to keep insert mode or not
---@param prompt_bufnr number: The prompt bufnr
---@param keepinsert boolean: Remain in INSERT mode if true
actions._close = function(prompt_bufnr, keepinsert)
action_state.get_current_history():reset()
local picker = action_state.get_current_picker(prompt_bufnr)
@@ -288,20 +369,25 @@ actions._close = function(prompt_bufnr, keepinsert)
pcall(a.nvim_set_current_win, original_win_id)
end
function actions.close(prompt_bufnr)
actions._close(prompt_bufnr, false)
end
actions.edit_command_line = function(prompt_bufnr)
local set_edit_line = function(prompt_bufnr, fname, prefix, postfix)
postfix = vim.F.if_nil(postfix, "")
local selection = action_state.get_selected_entry()
if selection == nil then
utils.__warn_no_selection "actions.edit_command_line"
utils.__warn_no_selection(fname)
return
end
actions.close(prompt_bufnr)
a.nvim_feedkeys(a.nvim_replace_termcodes(":" .. selection.value, true, false, true), "t", true)
a.nvim_feedkeys(a.nvim_replace_termcodes(prefix .. selection.value .. postfix, true, false, true), "t", true)
end
--- Set a value in the command line and dont run it, making it editable.
---@param prompt_bufnr number: The prompt bufnr
actions.edit_command_line = function(prompt_bufnr)
set_edit_line(prompt_bufnr, "actions.edit_command_line", ":")
end
--- Set a value in the command line and run it
---@param prompt_bufnr number: The prompt bufnr
actions.set_command_line = function(prompt_bufnr)
local selection = action_state.get_selected_entry()
if selection == nil then
@@ -313,26 +399,20 @@ actions.set_command_line = function(prompt_bufnr)
vim.cmd(selection.value)
end
--- Set a value in the search line and dont search for it, making it editable.
---@param prompt_bufnr number: The prompt bufnr
actions.edit_search_line = function(prompt_bufnr)
local selection = action_state.get_selected_entry()
if selection == nil then
utils.__warn_no_selection "actions.edit_search_line"
return
end
actions.close(prompt_bufnr)
a.nvim_feedkeys(a.nvim_replace_termcodes("/" .. selection.value, true, false, true), "t", true)
set_edit_line(prompt_bufnr, "actions.edit_search_line", "/")
end
--- Set a value in the search line and search for it
---@param prompt_bufnr number: The prompt bufnr
actions.set_search_line = function(prompt_bufnr)
local selection = action_state.get_selected_entry()
if selection == nil then
utils.__warn_no_selection "actions.set_search_line"
return
end
actions.close(prompt_bufnr)
a.nvim_feedkeys(a.nvim_replace_termcodes("/" .. selection.value .. "<CR>", true, false, true), "t", true)
set_edit_line(prompt_bufnr, "actions.set_search_line", "/", "<CR>")
end
--- Edit a register
---@param prompt_bufnr number: The prompt bufnr
actions.edit_register = function(prompt_bufnr)
local selection = action_state.get_selected_entry()
local picker = action_state.get_current_picker(prompt_bufnr)
@@ -355,6 +435,8 @@ actions.edit_register = function(prompt_bufnr)
-- print(vim.inspect(picker.finder.results))
end
--- Paste the selected register into the buffer
---@param prompt_bufnr number: The prompt bufnr
actions.paste_register = function(prompt_bufnr)
local selection = action_state.get_selected_entry()
if selection == nil then
@@ -370,12 +452,16 @@ actions.paste_register = function(prompt_bufnr)
end
end
--- Insert a symbol into the current buffer (while switching to normal mode)
---@param prompt_bufnr number: The prompt bufnr
actions.insert_symbol = function(prompt_bufnr)
local symbol = action_state.get_selected_entry().value[1]
actions.close(prompt_bufnr)
vim.api.nvim_put({ symbol }, "", true, true)
end
--- Insert a symbol into the current buffer and keeping the insert mode.
---@param prompt_bufnr number: The prompt bufnr
actions.insert_symbol_i = function(prompt_bufnr)
local symbol = action_state.get_selected_entry().value[1]
actions._close(prompt_bufnr, true)
@@ -658,6 +744,8 @@ actions.git_reset_hard = function(prompt_bufnr)
git_reset_branch(prompt_bufnr, "--hard")
end
--- Checkout a specific file for a given sha
---@param prompt_bufnr number: The prompt bufnr
actions.git_checkout_current_buffer = function(prompt_bufnr)
local cwd = action_state.get_current_picker(prompt_bufnr).cwd
local selection = action_state.get_selected_entry()
@@ -742,41 +830,49 @@ local send_all_to_qf = function(prompt_bufnr, mode, target)
end
--- Sends the selected entries to the quickfix list, replacing the previous entries.
---@param prompt_bufnr number: The prompt bufnr
actions.send_selected_to_qflist = function(prompt_bufnr)
send_selected_to_qf(prompt_bufnr, " ")
end
--- Adds the selected entries to the quickfix list, keeping the previous entries.
---@param prompt_bufnr number: The prompt bufnr
actions.add_selected_to_qflist = function(prompt_bufnr)
send_selected_to_qf(prompt_bufnr, "a")
end
--- Sends all entries to the quickfix list, replacing the previous entries.
---@param prompt_bufnr number: The prompt bufnr
actions.send_to_qflist = function(prompt_bufnr)
send_all_to_qf(prompt_bufnr, " ")
end
--- Adds all entries to the quickfix list, keeping the previous entries.
---@param prompt_bufnr number: The prompt bufnr
actions.add_to_qflist = function(prompt_bufnr)
send_all_to_qf(prompt_bufnr, "a")
end
--- Sends the selected entries to the location list, replacing the previous entries.
---@param prompt_bufnr number: The prompt bufnr
actions.send_selected_to_loclist = function(prompt_bufnr)
send_selected_to_qf(prompt_bufnr, " ", "loclist")
end
--- Adds the selected entries to the location list, keeping the previous entries.
---@param prompt_bufnr number: The prompt bufnr
actions.add_selected_to_loclist = function(prompt_bufnr)
send_selected_to_qf(prompt_bufnr, "a", "loclist")
end
--- Sends all entries to the location list, replacing the previous entries.
---@param prompt_bufnr number: The prompt bufnr
actions.send_to_loclist = function(prompt_bufnr)
send_all_to_qf(prompt_bufnr, " ", "loclist")
end
--- Adds all entries to the location list, keeping the previous entries.
---@param prompt_bufnr number: The prompt bufnr
actions.add_to_loclist = function(prompt_bufnr)
send_all_to_qf(prompt_bufnr, "a", "loclist")
end
@@ -792,28 +888,34 @@ end
--- Sends the selected entries to the quickfix list, replacing the previous entries.
--- If no entry was selected, sends all entries.
---@param prompt_bufnr number: The prompt bufnr
actions.smart_send_to_qflist = function(prompt_bufnr)
smart_send(prompt_bufnr, " ")
end
--- Adds the selected entries to the quickfix list, keeping the previous entries.
--- If no entry was selected, adds all entries.
---@param prompt_bufnr number: The prompt bufnr
actions.smart_add_to_qflist = function(prompt_bufnr)
smart_send(prompt_bufnr, "a")
end
--- Sends the selected entries to the location list, replacing the previous entries.
--- If no entry was selected, sends all entries.
---@param prompt_bufnr number: The prompt bufnr
actions.smart_send_to_loclist = function(prompt_bufnr)
smart_send(prompt_bufnr, " ", "loclist")
end
--- Adds the selected entries to the location list, keeping the previous entries.
--- If no entry was selected, adds all entries.
---@param prompt_bufnr number: The prompt bufnr
actions.smart_add_to_loclist = function(prompt_bufnr)
smart_send(prompt_bufnr, "a", "loclist")
end
--- Open completion menu containing the tags which can be used to filter the results in a faster way
---@param prompt_bufnr number: The prompt bufnr
actions.complete_tag = function(prompt_bufnr)
local current_picker = action_state.get_current_picker(prompt_bufnr)
local tags = current_picker.sorter.tags
@@ -863,6 +965,8 @@ actions.complete_tag = function(prompt_bufnr)
vim.fn.complete(col - #line, filtered_tags)
end
--- Cycle to the next search prompt in the history
---@param prompt_bufnr number: The prompt bufnr
actions.cycle_history_next = function(prompt_bufnr)
local history = action_state.get_current_history()
local current_picker = action_state.get_current_picker(prompt_bufnr)
@@ -879,6 +983,8 @@ actions.cycle_history_next = function(prompt_bufnr)
end
end
--- Cycle to the previous search prompt in the history
---@param prompt_bufnr number: The prompt bufnr
actions.cycle_history_prev = function(prompt_bufnr)
local history = action_state.get_current_history()
local current_picker = action_state.get_current_picker(prompt_bufnr)
@@ -894,13 +1000,17 @@ actions.cycle_history_prev = function(prompt_bufnr)
end
end
--- Open the quickfix list
actions.open_qflist = function(_)
--- Open the quickfix list. It makes sense to use this in combination with one of the send_to_qflist actions
--- `actions.smart_send_to_qflist + actions.open_qflist`
---@param prompt_bufnr number: The prompt bufnr
actions.open_qflist = function(prompt_bufnr)
vim.cmd [[copen]]
end
--- Open the location list
actions.open_loclist = function(_)
--- Open the location list. It makes sense to use this in combination with one of the send_to_loclist actions
--- `actions.smart_send_to_qflist + actions.open_qflist`
---@param prompt_bufnr number: The prompt bufnr
actions.open_loclist = function(prompt_bufnr)
vim.cmd [[lopen]]
end