From c6980a9acf8af836196508000c34dcb06b11137b Mon Sep 17 00:00:00 2001 From: TJ DeVries Date: Thu, 22 Apr 2021 14:08:22 -0700 Subject: [PATCH] docs: add other actions modules (#792) * docs: add other actions modules * [docgen] Update doc/telescope.txt skip-checks: true * fixup * [docgen] Update doc/telescope.txt skip-checks: true Co-authored-by: Github Actions --- doc/telescope.txt | 96 +++++++++++++++++++++++++++++---- lua/telescope/actions/set.lua | 35 ++++++------ lua/telescope/actions/state.lua | 9 ++++ scripts/gendocs.lua | 2 + 4 files changed, 118 insertions(+), 24 deletions(-) diff --git a/doc/telescope.txt b/doc/telescope.txt index a5885ad..1bf9c3f 100644 --- a/doc/telescope.txt +++ b/doc/telescope.txt @@ -92,22 +92,54 @@ telescope.extensions() *telescope.extensions()* ================================================================================ - *telescope.builtin* + *telescope.actions.set* -A collection of builtin pickers for telescope. +Telescope action sets are used to provide an interface for managing actions +that all primarily do the same thing, but with slight tweaks. -Meant for both example and for easy startup. +For example, when editing files you may want it in the current split, a +vertical split, etc. Instead of making users have to overwrite EACH of those +every time they want to change this behavior, they can instead replace the +`set` itself and then it will work great and they're done. -Any of these functions can just be called directly by doing: +action_set.shift_selection({prompt_bufnr}, {change})*action_set.shift_selection()* + Move the current selection of a picker {change} rows. Handles not + overflowing / underflowing the list. -:lua require('telescope.builtin').$NAME() -This will use the default configuration options. Other configuration options -are still in flux at the moment + Parameters: ~ + {prompt_bufnr} (number) The prompt bufnr + {change} (number) The amount to shift the selection by -builtin.live_grep() *builtin.live_grep()* - Live grep means grep as you type. +action_set.select({prompt_bufnr}, {type}) *action_set.select()* + Select the current entry. This is the action set to overwrite common + actions by the user. + + By default maps to editing a file. + + + Parameters: ~ + {prompt_bufnr} (number) The prompt bufnr + {type} (string) The type of selection to make + + +action_set.edit({prompt_bufnr}, {command}) *action_set.edit()* + Edit a file based on the current selection. + + + Parameters: ~ + {prompt_bufnr} (number) The prompt bufnr + {command} (string) The command to use to open the file. + + +action_set.scroll_previewer({prompt_bufnr}, {direction})*action_set.scroll_previewer()* + Scrolls the previewer up or down + + + Parameters: ~ + {prompt_bufnr} (number) The prompt bufnr + {direction} (number) The direction of the scrolling @@ -234,6 +266,52 @@ actions.open_qflist() *actions.open_qflist()* +================================================================================ + *telescope.builtin* + +A collection of builtin pickers for telescope. + +Meant for both example and for easy startup. + +Any of these functions can just be called directly by doing: + +:lua require('telescope.builtin').$NAME() + +This will use the default configuration options. Other configuration options +are still in flux at the moment + +builtin.live_grep() *builtin.live_grep()* + Live grep means grep as you type. + + + + +================================================================================ + *telescope.actions.state* + +Functions to be used to determine the current state of telescope. + +Generally used from within other |telescope.actions| + +action_state.get_selected_entry() *action_state.get_selected_entry()* + Get the current entry + + + +action_state.get_current_line() *action_state.get_current_line()* + Gets the current line + + + +action_state.get_current_picker({prompt_bufnr})*action_state.get_current_picker()* + Gets the current picker + + + Parameters: ~ + {prompt_bufnr} (number) The prompt bufnr + + + ================================================================================ *telescope.previewers* diff --git a/lua/telescope/actions/set.lua b/lua/telescope/actions/set.lua index 54abbfc..49dd74a 100644 --- a/lua/telescope/actions/set.lua +++ b/lua/telescope/actions/set.lua @@ -1,3 +1,15 @@ +---@tag telescope.actions.set + +---@brief [[ +--- Telescope action sets are used to provide an interface for managing +--- actions that all primarily do the same thing, but with slight tweaks. +--- +--- For example, when editing files you may want it in the current split, +--- a vertical split, etc. Instead of making users have to overwrite EACH +--- of those every time they want to change this behavior, they can instead +--- replace the `set` itself and then it will work great and they're done. +---@brief ]] + local a = vim.api local log = require('telescope.log') @@ -8,14 +20,7 @@ local action_state = require('telescope.actions.state') local transform_mod = require('telescope.actions.mt').transform_mod ---- Telescope action sets are used to provide an interface for managing ---- actions that all primarily do the same thing, but with slight tweaks. ---- ---- For example, when editing files you may want it in the current split, ---- a vertical split, etc. Instead of making users have to overwrite EACH ---- of those every time they want to change this behavior, they can instead ---- replace the `set` itself and then it will work great and they're done. -local set = setmetatable({}, { +local action_set = setmetatable({}, { __index = function(_, k) error("'telescope.actions.set' does not have a value: " .. tostring(k)) end @@ -25,7 +30,7 @@ local set = setmetatable({}, { --- Handles not overflowing / underflowing the list. ---@param prompt_bufnr number: The prompt bufnr ---@param change number: The amount to shift the selection by -set.shift_selection = function(prompt_bufnr, change) +action_set.shift_selection = function(prompt_bufnr, change) local count = vim.v.count count = count == 0 and 1 or count count = a.nvim_get_mode().mode == "n" and count or 1 @@ -39,8 +44,8 @@ end ---@param prompt_bufnr number: The prompt bufnr ---@param type string: The type of selection to make -- Valid types include: "default", "horizontal", "vertical", "tabedit" -set.select = function(prompt_bufnr, type) - return set.edit(prompt_bufnr, action_state.select_key_to_edit_key(type)) +action_set.select = function(prompt_bufnr, type) + return action_set.edit(prompt_bufnr, action_state.select_key_to_edit_key(type)) end local edit_buffer @@ -65,7 +70,7 @@ end ---@param prompt_bufnr number: The prompt bufnr ---@param command string: The command to use to open the file. -- Valid commands include: "edit", "new", "vedit", "tabedit" -set.edit = function(prompt_bufnr, command) +action_set.edit = function(prompt_bufnr, command) local entry = action_state.get_selected_entry() if not entry then @@ -129,7 +134,7 @@ end ---@param prompt_bufnr number: The prompt bufnr ---@param direction number: The direction of the scrolling -- Valid directions include: "1", "-1" -set.scroll_previewer = function (prompt_bufnr, direction) +action_set.scroll_previewer = function (prompt_bufnr, direction) local status = state.get_status(prompt_bufnr) local default_speed = vim.api.nvim_win_get_height(status.preview_win) / 2 local speed = status.picker.layout_config.scroll_speed or default_speed @@ -140,5 +145,5 @@ end -- ================================================== -- Transforms modules and sets the corect metatables. -- ================================================== -set = transform_mod(set) -return set +action_set = transform_mod(action_set) +return action_set diff --git a/lua/telescope/actions/state.lua b/lua/telescope/actions/state.lua index 0752171..7ef9f6c 100644 --- a/lua/telescope/actions/state.lua +++ b/lua/telescope/actions/state.lua @@ -1,3 +1,11 @@ +---@tag telescope.actions.state + +---@brief [[ +--- Functions to be used to determine the current state of telescope. +--- +--- Generally used from within other |telescope.actions| +---@brief ]] + local global_state = require('telescope.state') local action_state = {} @@ -13,6 +21,7 @@ function action_state.get_current_line() end --- Gets the current picker +---@param prompt_bufnr number: The prompt bufnr function action_state.get_current_picker(prompt_bufnr) return global_state.get_status(prompt_bufnr).picker end diff --git a/scripts/gendocs.lua b/scripts/gendocs.lua index 7ac3b3e..ead868a 100644 --- a/scripts/gendocs.lua +++ b/scripts/gendocs.lua @@ -12,6 +12,8 @@ docs.test = function() "./lua/telescope/builtin/init.lua", "./lua/telescope/pickers/layout_strategies.lua", "./lua/telescope/actions/init.lua", + "./lua/telescope/actions/state.lua", + "./lua/telescope/actions/set.lua", "./lua/telescope/previewers/init.lua", }