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

1 files changed, 158 insertions, 48 deletions

diff --git a/lua/telescope/actions/init.lua b/lua/telescope/actions/init.lua
index c69b368..2e16f1d 100644
--- a/lua/telescope/actions/init.lua
+++ b/lua/telescope/actions/init.lua
@@ -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