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

docs: rewrite readme and add missing config values + builtin opts

Browse Source
This commit is contained in:
Simon Hauser
2021-09-13 22:03:41 +02:00
parent aaffa84ebb
commit 5131df7df1
17 changed files with 1822 additions and 1165 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
lua/telescope/actions/generate.lua
View File

@@ -3,8 +3,8 @@
---@brief [[
--- Module for convenience to override defaults of corresponding |telescope.actions| at |telescope.setup()|.
---
--- <pre>
--- General usage:
--- <code>
--- require("telescope").setup {
--- defaults = {
--- mappings = {
@@ -19,7 +19,7 @@
--- },
--- },
--- }
--- </pre>
--- </code>
---@brief ]]
local actions = require "telescope.actions"

54
lua/telescope/actions/utils.lua
View File

@@ -16,20 +16,21 @@ local utils = {}
--- - Indices are 1-indexed, whereas rows are 0-indexed.
--- - Warning: `map_entries` has no return value.
--- - The below example showcases how to collect results
--- <pre>
---
--- Usage:
--- local action_state = require "telescope.actions.state"
--- local action_utils = require "telescope.actions.utils"
--- function entry_value_by_row()
--- local prompt_bufnr = vim.api.nvim_get_current_buf()
--- local current_picker = action_state.get_current_picker(prompt_bufnr)
--- local results = {}
--- action_utils.map_entries(prompt_bufnr, function(entry, index, row)
--- results[row] = entry.value
--- end)
--- return results
--- end
--- </pre>
--- <code>
--- local action_state = require "telescope.actions.state"
--- local action_utils = require "telescope.actions.utils"
--- function entry_value_by_row()
--- local prompt_bufnr = vim.api.nvim_get_current_buf()
--- local current_picker = action_state.get_current_picker(prompt_bufnr)
--- local results = {}
--- action_utils.map_entries(prompt_bufnr, function(entry, index, row)
--- results[row] = entry.value
--- end)
--- return results
--- end
--- </code>
---@param prompt_bufnr number: The prompt bufnr
---@param f function: Function to map onto entries of picker that takes (entry, index, row) as viable arguments
function utils.map_entries(prompt_bufnr, f)
@@ -52,20 +53,21 @@ end
--- - Selected entries are returned in order of their selection.
--- - Warning: `map_selections` has no return value.
--- - The below example showcases how to collect results
--- <pre>
---
--- Usage:
--- local action_state = require "telescope.actions.state"
--- local action_utils = require "telescope.actions.utils"
--- function selection_by_index()
--- local prompt_bufnr = vim.api.nvim_get_current_buf()
--- local current_picker = action_state.get_current_picker(prompt_bufnr)
--- local results = {}
--- action_utils.map_selections(prompt_bufnr, function(entry, index)
--- results[index] = entry.value
--- end)
--- return results
--- end
--- </pre>
--- <code>
--- local action_state = require "telescope.actions.state"
--- local action_utils = require "telescope.actions.utils"
--- function selection_by_index()
--- local prompt_bufnr = vim.api.nvim_get_current_buf()
--- local current_picker = action_state.get_current_picker(prompt_bufnr)
--- local results = {}
--- action_utils.map_selections(prompt_bufnr, function(entry, index)
--- results[index] = entry.value
--- end)
--- return results
--- end
--- </code>
---@param prompt_bufnr number: The prompt bufnr
---@param f function: Function to map onto selection of picker that takes (selection) as a viable argument
function utils.map_selections(prompt_bufnr, f)

190
lua/telescope/builtin/init.lua
View File

@@ -1,5 +1,7 @@
---@tag telescope.builtin
---@config { ['field_heading'] = "Options" }
---@brief [[
--- Telescope Builtins is a collection of community maintained pickers to support common workflows. It can be used as
--- reference when writing PRs, Telescope extensions, your own custom pickers, or just as a discovery tool for all of
@@ -12,44 +14,16 @@
--- To use any of Telescope's default options or any picker-specific options, call your desired picker by passing a lua
--- table to the picker with all of the options you want to use. Here's an example with the live_grep picker:
---
--- <pre>
--- :lua require('telescope.builtin').live_grep({
--- prompt_title = 'find string in open buffers...',
--- grep_open_files = true
--- })
--- -- or with dropdown theme
--- :lua require('telescope.builtin').find_files(require('telescope.themes').get_dropdown{
--- previewer = false
--- })
--- </pre>
---
--- You can also pass default configurations to builtin pickers. These options will also be added if
--- the picker is executed with `Telescope find_files`.
---
--- <pre>
--- require("telescope").setup {
--- pickers = {
--- buffers = {
--- show_all_buffers = true,
--- sort_lastused = true,
--- theme = "dropdown",
--- previewer = false,
--- mappings = {
--- i = {
--- ["<c-d>"] = require("telescope.actions").delete_buffer,
--- -- or right hand side can also be the name of the action as string
--- ["<c-d>"] = "delete_buffer",
--- },
--- n = {
--- ["<c-d>"] = require("telescope.actions").delete_buffer,
--- }
--- }
--- }
--- }
--- }
--- </pre>
---
--- This will use the default configuration options. Other configuration options are still in flux at the moment
--- <code>
--- :lua require('telescope.builtin').live_grep({
--- prompt_title = 'find string in open buffers...',
--- grep_open_files = true
--- })
--- -- or with dropdown theme
--- :lua require('telescope.builtin').find_files(require('telescope.themes').get_dropdown{
--- previewer = false
--- })
--- </code>
---@brief ]]
if 1 ~= vim.fn.has "nvim-0.5" then
@@ -79,28 +53,33 @@ end
--- Search for a string and get results live as you type (respecting .gitignore)
---@param opts table: options to pass to the picker
---@field cwd string: root dir to search from (default is cwd, use utils.buffer_dir() to search relative to open buffer)
---@field cwd string: root dir to search from (default: cwd, use utils.buffer_dir() to search relative to open buffer)
---@field grep_open_files boolean: if true, restrict search to open files only, mutually exclusive with `search_dirs`
---@field search_dirs table: directory/directories to search in, mutually exclusive with `grep_open_files`
---@field additional_args function: function(opts) which returns a table of additional arguments to be passed on
---@field max_results number: define a upper result value
---@field disable_coordinates boolean: don't show the line & row numbers (default: false)
builtin.live_grep = require_on_exported_call("telescope.builtin.files").live_grep
--- Searches for the string under your cursor in your current working directory
---@param opts table: options to pass to the picker
---@field cwd string: root dir to search from (default is cwd, use utils.buffer_dir() to search relative to open buffer)
---@field cwd string: root dir to search from (default: cwd, use utils.buffer_dir() to search relative to open buffer)
---@field search string: the query to search
---@field search_dirs table: directory/directories to search in
---@field use_regex boolean: if true, special characters won't be escaped, allows for using regex (default is false)
---@field use_regex boolean: if true, special characters won't be escaped, allows for using regex (default: false)
---@field word_match string: can be set to `-w` to enable exact word matches
---@field additional_args function: function(opts) which returns a table of additional arguments to be passed on
---@field disable_coordinates boolean: don't show the line and row numbers (default: false)
---@field sort_only_text boolean: only sort the text, not the file, line or row (default: false)
builtin.grep_string = require_on_exported_call("telescope.builtin.files").grep_string
--- Search for files (respecting .gitignore)
---@param opts table: options to pass to the picker
---@field cwd string: root dir to search from (default is cwd, use utils.buffer_dir() to search relative to open buffer)
---@field find_command table: command line arguments for `find_files` to use for the search, overrides default config
---@field cwd string: root dir to search from (default: cwd, use utils.buffer_dir() to search relative to open buffer)
---@field find_command table: command line arguments for `find_files` to use for the search, overrides default: config
---@field follow boolean: if true, follows symlinks (i.e. uses `-L` flag for the `find` command)
---@field hidden boolean: determines whether to show hidden files or not (default is false)
---@field no_ignore boolean: show files ignored by .gitignore, .ignore, etc. (default is false)
---@field hidden boolean: determines whether to show hidden files or not (default: false)
---@field no_ignore boolean: show files ignored by .gitignore, .ignore, etc. (default: false)
---@field search_dirs table: directory/directories to search in
builtin.find_files = require_on_exported_call("telescope.builtin.files").find_files
@@ -116,31 +95,40 @@ builtin.fd = builtin.find_files
--- create the file `init.lua` inside of `lua/telescope` and will create the necessary folders (similar to how
--- `mkdir -p` would work) if they do not already exist
---@param opts table: options to pass to the picker
---@field cwd string: root dir to browse from (default is cwd, use utils.buffer_dir() to search relative to open buffer)
---@field depth number: file tree depth to display (default is 1)
---@field dir_icon string: change the icon for a directory. default: 
---@field hidden boolean: determines whether to show hidden files or not (default is false)
---@field cwd string: root dir to browse from (default: cwd, use utils.buffer_dir() to search relative to open buffer)
---@field depth number: file tree depth to display (default: 1)
---@field dir_icon string: change the icon for a directory. (default: )
---@field hidden boolean: determines whether to show hidden files or not (default: false)
builtin.file_browser = require_on_exported_call("telescope.builtin.files").file_browser
--- Lists function names, variables, and other symbols from treesitter queries
--- - Default keymaps:
--- - `<C-l>`: show autocompletion menu to prefilter your query by kind of ts node you want to see (i.e. `:var:`)
---@field show_line boolean: if true, shows the row:column that the result is found at (default is true)
---@field show_line boolean: if true, shows the row:column that the result is found at (default: true)
---@field bufnr number: specify the buffer number where treesitter should run. (default: current buffer)
---@field symbol_highlights table: string -> string. Matches symbol with hl_group
builtin.treesitter = require_on_exported_call("telescope.builtin.files").treesitter
--- Live fuzzy search inside of the currently open buffer
---@param opts table: options to pass to the picker
---@field skip_empty_lines boolean: if true we dont display empty lines (default: false)
builtin.current_buffer_fuzzy_find = require_on_exported_call("telescope.builtin.files").current_buffer_fuzzy_find
--- Lists tags in current directory with tag location file preview (users are required to run ctags -R to generate tags
--- or update when introducing new changes)
---@param opts table: options to pass to the picker
---@field cwd string: root dir to search from (default: cwd, use utils.buffer_dir() to search relative to open buffer)
---@field ctags_file string: specify a particular ctags file to use
---@field show_line boolean: if true, shows the content of the line the tag is found on in the picker (default is true)
---@field show_line boolean: if true, shows the content of the line the tag is found on in the picker (default: true)
---@field only_sort_tags boolean: if true we will only sort tags (default: false)
builtin.tags = require_on_exported_call("telescope.builtin.files").tags
--- Lists all of the tags for the currently open buffer, with a preview
---@param opts table: options to pass to the picker
---@field cwd string: root dir to search from (default: cwd, use utils.buffer_dir() to search relative to open buffer)
---@field ctags_file string: specify a particular ctags file to use
---@field show_line boolean: if true, shows the content of the line the tag is found on in the picker (default: true)
---@field only_sort_tags boolean: if true we will only sort tags (default: false)
builtin.current_buffer_tags = require_on_exported_call("telescope.builtin.files").current_buffer_tags
--
@@ -154,8 +142,10 @@ builtin.current_buffer_tags = require_on_exported_call("telescope.builtin.files"
--- - Default keymaps:
--- - `<cr>`: opens the currently selected file
---@param opts table: options to pass to the picker
---@field show_untracked boolean: if true, adds `--others` flag to command and shows untracked files (default is true)
---@field recurse_submodules boolean: if true, adds the `--recurse-submodules` flag to command (default is false)
---@field cwd string: specify the path of the repo
---@field use_git_root boolean: if we should use git root as cwd or the cwd (important for submodule) (default: true)
---@field show_untracked boolean: if true, adds `--others` flag to command and shows untracked files (default: true)
---@field recurse_submodules boolean: if true, adds the `--recurse-submodules` flag to command (default: false)
builtin.git_files = require_on_exported_call("telescope.builtin.git").files
--- Lists commits for current directory with diff preview
@@ -166,6 +156,7 @@ builtin.git_files = require_on_exported_call("telescope.builtin.git").files
--- - `<C-r>h`: resets current branch to selected commit using hard mode
---@param opts table: options to pass to the picker
---@field cwd string: specify the path of the repo
---@field use_git_root boolean: if we should use git root as cwd or the cwd (important for submodule) (default: true)
builtin.git_commits = require_on_exported_call("telescope.builtin.git").commits
--- Lists commits for current buffer with diff preview
@@ -176,6 +167,7 @@ builtin.git_commits = require_on_exported_call("telescope.builtin.git").commits
--- - `<c-t>`: opens a diff in a new tab
---@param opts table: options to pass to the picker
---@field cwd string: specify the path of the repo
---@field use_git_root boolean: if we should use git root as cwd or the cwd (important for submodule) (default: true)
---@field current_file string: specify the current file that should be used for bcommits (default: current buffer)
builtin.git_bcommits = require_on_exported_call("telescope.builtin.git").bcommits
@@ -188,6 +180,8 @@ builtin.git_bcommits = require_on_exported_call("telescope.builtin.git").bcommit
--- - `<C-d>`: deletes the currently selected branch, with confirmation prompt before deletion
--- - `<C-y>`: merges the currently selected branch, with confirmation prompt before deletion
---@param opts table: options to pass to the picker
---@field cwd string: specify the path of the repo
---@field use_git_root boolean: if we should use git root as cwd or the cwd (important for submodule) (default: true)
builtin.git_branches = require_on_exported_call("telescope.builtin.git").branches
--- Lists git status for current directory
@@ -195,12 +189,17 @@ builtin.git_branches = require_on_exported_call("telescope.builtin.git").branche
--- - `<Tab>`: stages or unstages the currently selected file
--- - `<cr>`: opens the currently selected file
---@param opts table: options to pass to the picker
---@field cwd string: specify the path of the repo
---@field use_git_root boolean: if we should use git root as cwd or the cwd (important for submodule) (default: true)
---@field git_icons table: string -> string. Matches name with icon (see source code, make_entry.lua git_icon_defaults)
builtin.git_status = require_on_exported_call("telescope.builtin.git").status
--- Lists stash items in current repository
--- - Default keymaps:
--- - `<cr>`: runs `git apply` for currently selected stash
---@param opts table: options to pass to the picker
---@field cwd string: specify the path of the repo
---@field use_git_root boolean: if we should use git root as cwd or the cwd (important for submodule) (default: true)
builtin.git_stash = require_on_exported_call("telescope.builtin.git").stash
--
@@ -211,10 +210,28 @@ builtin.git_stash = require_on_exported_call("telescope.builtin.git").stash
--- Lists all of the community maintained pickers built into Telescope
---@param opts table: options to pass to the picker
---@field ignore_filename boolean: dont show filenames (default: true)
---@field include_extensions boolean: if true will show the pickers of the installed extensions (default: false)
builtin.builtin = require_on_exported_call("telescope.builtin.internal").builtin
--- Opens the previous picker in the identical state (incl. multi selections)
--- - Notes:
--- - Requires `cache_picker` in setup or when having invoked pickers, see |telescope.defaults.cache_picker|
---@param opts table: options to pass to the picker
---@field cache_index number: what picker to resume, where 1 denotes most recent (default: 1)
builtin.resume = require_on_exported_call("telescope.builtin.internal").resume
--- Opens a picker over previously cached pickers in there preserved states (incl. multi selections)
--- - Default keymaps:
--- - `<C-x>`: delete the selected cached picker
--- - Notes:
--- - Requires `cache_picker` in setup or when having invoked pickers, see |telescope.defaults.cache_picker|
---@param opts table: options to pass to the picker
builtin.pickers = require_on_exported_call("telescope.builtin.internal").pickers
--- Use the telescope...
---@param opts table: options to pass to the picker
---@field show_pluto boolean: we love pluto (default: false, because its a hidden feature)
builtin.planets = require_on_exported_call("telescope.builtin.internal").planets
--- Lists symbols inside of `data/telescope-sources/*.json` found in your runtime path
@@ -233,14 +250,17 @@ builtin.commands = require_on_exported_call("telescope.builtin.internal").comman
--- Lists items in the quickfix list, jumps to location on `<cr>`
---@param opts table: options to pass to the picker
---@field ignore_filename boolean: dont show filenames (default: true)
builtin.quickfix = require_on_exported_call("telescope.builtin.internal").quickfix
--- Lists items from the current window's location list, jumps to location on `<cr>`
---@param opts table: options to pass to the picker
---@field ignore_filename boolean: dont show filenames (default: true)
builtin.loclist = require_on_exported_call("telescope.builtin.internal").loclist
--- Lists previously open files, opens on `<cr>`
---@param opts table: options to pass to the picker
---@field only_cwd boolean: show only files in the cwd (default: false)
builtin.oldfiles = require_on_exported_call("telescope.builtin.internal").oldfiles
--- Lists commands that were executed recently, and reruns them on `<cr>`
@@ -255,46 +275,35 @@ builtin.command_history = require_on_exported_call("telescope.builtin.internal")
---@param opts table: options to pass to the picker
builtin.search_history = require_on_exported_call("telescope.builtin.internal").search_history
--- Opens the previous picker in the identical state (incl. multi selections)
--- - Notes:
--- - Requires `cache_picker` in setup or when having invoked pickers, see |telescope.defaults.cache_picker|
---@param opts table: options to pass to the picker
---@field cache_index number: what picker to resume, where 1 denotes most recent (default 1)
builtin.resume = require_on_exported_call("telescope.builtin.internal").resume
--- Opens a picker over previously cached pickers in there preserved states (incl. multi selections)
--- - Default keymaps:
--- - `<C-x>`: delete the selected cached picker
--- - Notes:
--- - Requires `cache_picker` in setup or when having invoked pickers, see |telescope.defaults.cache_picker|
---@param opts table: options to pass to the picker
builtin.pickers = require_on_exported_call("telescope.builtin.internal").pickers
--- Lists vim options, allows you to edit the current value on `<cr>`
---@param opts table: options to pass to the picker
builtin.vim_options = require_on_exported_call("telescope.builtin.internal").vim_options
--- Lists available help tags and opens a new window with the relevant help info on `<cr>`
---@param opts table: options to pass to the picker
---@field lang string: specify language (default: vim.o.helplang)
---@field fallback boolean: fallback to en if language isn't installed (default: true)
builtin.help_tags = require_on_exported_call("telescope.builtin.internal").help_tags
--- Lists manpage entries, opens them in a help window on `<cr>`
---@param opts table: options to pass to the picker
---@field sections table: a list of sections to search, use `{ "ALL" }` to search in all sections
---@field sections table: a list of sections to search, use `{ "ALL" }` to search in all sections (default: { "1" })
---@field man_cmd function: that returns the man command. (Default: `apropos ""` on linux, `apropos " "` on macos)
builtin.man_pages = require_on_exported_call("telescope.builtin.internal").man_pages
--- Lists lua modules and reloads them on `<cr>`
---@param opts table: options to pass to the picker
---@field column_len number: define the max column len for the module name (default: dynamic, longest module name)
builtin.reloader = require_on_exported_call("telescope.builtin.internal").reloader
--- Lists open buffers in current neovim instance, opens selected buffer on `<cr>`
---@param opts table: options to pass to the picker
---@field show_all_buffers boolean: if true, show all buffers, including unloaded buffers (default true)
---@field ignore_current_buffer boolean: if true, don't show the current buffer in the list (default false)
---@field only_cwd boolean: if true, only show buffers in the current working directory (default false)
---@field sort_lastused boolean: Sorts current and last buffer to the top and selects the lastused (default false)
---@field sort_mru boolean: Sorts all buffers after most recent used. Not just the current and last one (default false)
---@field bufnr_width number: Defines the width of the buffer numbers in front of the filenames
---@field show_all_buffers boolean: if true, show all buffers, including unloaded buffers (default: true)
---@field ignore_current_buffer boolean: if true, don't show the current buffer in the list (default: false)
---@field only_cwd boolean: if true, only show buffers in the current working directory (default: false)
---@field sort_lastused boolean: Sorts current and last buffer to the top and selects the lastused (default: false)
---@field sort_mru boolean: Sorts all buffers after most recent used. Not just the current and last one (default: false)
---@field bufnr_width number: Defines the width of the buffer numbers in front of the filenames (default: dynamic)
builtin.buffers = require_on_exported_call("telescope.builtin.internal").buffers
--- Lists available colorschemes and applies them on `<cr>`
@@ -334,10 +343,12 @@ builtin.spell_suggest = require_on_exported_call("telescope.builtin.internal").s
--- Lists the tag stack for the current window, jumps to tag on `<cr>`
---@param opts table: options to pass to the picker
---@field ignore_filename boolean: dont show filenames (default: true)
builtin.tagstack = require_on_exported_call("telescope.builtin.internal").tagstack
--- Lists items from Vim's jumplist, jumps to location on `<cr>`
---@param opts table: options to pass to the picker
---@field ignore_filename boolean: dont show filenames (default: true)
builtin.jumplist = require_on_exported_call("telescope.builtin.internal").jumplist
--
@@ -348,52 +359,73 @@ builtin.jumplist = require_on_exported_call("telescope.builtin.internal").jumpli
--- Lists LSP references for word under the cursor, jumps to reference on `<cr>`
---@param opts table: options to pass to the picker
---@field timeout number: timeout for the sync call (default: 10000)
builtin.lsp_references = require_on_exported_call("telescope.builtin.lsp").references
--- Goto the definition of the word under the cursor, if there's only one, otherwise show all options in Telescope
---@param opts table: options to pass to the picker
---@field timeout number: timeout for the sync call (default: 10000)
---@field jump_type string: how to goto definition if there is only one, values: "tab", "split", "vsplit", "never"
---@field ignore_filename boolean: dont show filenames (default: true)
builtin.lsp_definitions = require_on_exported_call("telescope.builtin.lsp").definitions
--- Goto the definition of the type of the word under the cursor, if there's only one,
--- otherwise show all options in Telescope
---@param opts table: options to pass to the picker
---@field timeout number: timeout for the sync call (default: 10000)
---@field jump_type string: how to goto definition if there is only one, values: "tab", "split", "vsplit", "never"
---@field ignore_filename boolean: dont show filenames (default: true)
builtin.lsp_type_definitions = require("telescope.builtin.lsp").type_definitions
--- Goto the implementation of the word under the cursor if there's only one, otherwise show all options in Telescope
---@param opts table: options to pass to the picker
---@field timeout number: timeout for the sync call (default: 10000)
---@field jump_type string: how to goto implementation if there is only one, values: "tab", "split", "vsplit", "never"
---@field ignore_filename boolean: dont show filenames (default: true)
builtin.lsp_implementations = require_on_exported_call("telescope.builtin.lsp").implementations
--- Lists any LSP actions for the word under the cursor which can be triggered with `<cr>`
---@param opts table: options to pass to the picker
---@field timeout number: timeout for the sync call (default: 10000)
builtin.lsp_code_actions = require_on_exported_call("telescope.builtin.lsp").code_actions
--- Lists any LSP actions for a given range, that can be triggered with `<cr>`
---@param opts table: options to pass to the picker
---@field timeout number: timeout for the sync call (default: 10000)
---@field start_line number: where the code action starts (default: handled by :'<,'>Telescope lsp_range_code_actions)
---@field start_line number: where the code action ends (default: handled by :'<,'>Telescope lsp_range_code_actions)
builtin.lsp_range_code_actions = require_on_exported_call("telescope.builtin.lsp").range_code_actions
--- Lists LSP document symbols in the current buffer
--- - Default keymaps:
--- - `<C-l>`: show autocompletion menu to prefilter your query by type of symbol you want to see (i.e. `:variable:`)
---@param opts table: options to pass to the picker
---@field ignore_filename type: string with file to ignore
---@field timeout number: timeout for the sync call (default: 10000)
---@field ignore_filename boolean: dont show filenames (default: true)
---@field show_line boolean: if true, shows the content of the line the tag is found on (default: false)
---@field symbols string|table: filter results by symbol kind(s)
---@field symbol_highlights table: string -> string. Matches symbol with hl_group
builtin.lsp_document_symbols = require_on_exported_call("telescope.builtin.lsp").document_symbols
--- Lists LSP document symbols in the current workspace
--- - Default keymaps:
--- - `<C-l>`: show autocompletion menu to prefilter your query by type of symbol you want to see (i.e. `:variable:`)
---@param opts table: options to pass to the picker
---@field ignore_filename string: file(s) to ignore
---@field query string: for what to query the workspace (default: "")
---@field timeout number: timeout for the sync call (default: 10000)
---@field ignore_filename boolean: dont show filenames (default: false)
---@field show_line boolean: if true, shows the content of the line the tag is found on (default: false)
---@field symbols string|table: filter results by symbol kind(s)
---@field symbol_highlights table: string -> string. Matches symbol with hl_group
builtin.lsp_workspace_symbols = require_on_exported_call("telescope.builtin.lsp").workspace_symbols
--- Dynamically lists LSP for all workspace symbols
--- - Default keymaps:
--- - `<C-l>`: show autocompletion menu to prefilter your query by type of symbol you want to see (i.e. `:variable:`)
---@param opts table: options to pass to the picker
---@field ignore_filename boolean: dont show filenames (default: false)
---@field show_line boolean: if true, shows the content of the line the symbol is found on (default: false)
---@field symbol_highlights table: string -> string. Matches symbol with hl_group
builtin.lsp_dynamic_workspace_symbols = require_on_exported_call("telescope.builtin.lsp").dynamic_workspace_symbols
--- Lists LSP diagnostics for the current buffer
@@ -405,7 +437,7 @@ builtin.lsp_dynamic_workspace_symbols = require_on_exported_call("telescope.buil
---@field severity string|number: filter diagnostics by severity name (string) or id (number)
---@field severity_limit string|number: keep diagnostics equal or more severe wrt severity name (string) or id (number)
---@field severity_bound string|number: keep diagnostics equal or less severe wrt severity name (string) or id (number)
---@field no_sign bool: hide LspDiagnosticSigns from Results (default is false)
---@field no_sign boolean: hide LspDiagnosticSigns from Results (default: false)
---@field line_width number: set length of diagnostic entry text in Results
builtin.lsp_document_diagnostics = require_on_exported_call("telescope.builtin.lsp").diagnostics
@@ -418,7 +450,7 @@ builtin.lsp_document_diagnostics = require_on_exported_call("telescope.builtin.l
---@field severity string|number: filter diagnostics by severity name (string) or id (number)
---@field severity_limit string|number: keep diagnostics equal or more severe wrt severity name (string) or id (number)
---@field severity_bound string|number: keep diagnostics equal or less severe wrt severity name (string) or id (number)
---@field no_sign bool: hide LspDiagnosticSigns from Results (default is false)
---@field no_sign boolean: hide LspDiagnosticSigns from Results (default: false)
---@field line_width number: set length of diagnostic entry text in Results
builtin.lsp_workspace_diagnostics = require_on_exported_call("telescope.builtin.lsp").workspace_diagnostics

7
lua/telescope/builtin/internal.lua
View File

@@ -635,7 +635,7 @@ internal.reloader = function(opts)
local package_list = vim.tbl_keys(package.loaded)
-- filter out packages we don't want and track the longest package name
opts.column_len = 0
local column_len = 0
for index, module_name in pairs(package_list) do
if
type(require(module_name)) ~= "table"
@@ -643,10 +643,11 @@ internal.reloader = function(opts)
or package.searchpath(module_name, package.path) == nil
then
table.remove(package_list, index)
elseif #module_name > opts.column_len then
opts.column_len = #module_name
elseif #module_name > column_len then
column_len = #module_name
end
end
opts.column_len = vim.F.if_nil(opts.column_len, column_len)
pickers.new(opts, {
prompt_title = "Packages",

3
lua/telescope/command.lua
View File

@@ -166,7 +166,8 @@ local function run_command(args)
end
if string.len(theme) > 0 then
opts = themes[theme](opts)
local func = themes[theme] or themes["get_" .. theme]
opts = func(opts)
end
if string.len(extension_type) > 0 and extension_type ~= '"' then

647
lua/telescope/config.lua
View File

@@ -120,191 +120,247 @@ local layout_config_description = string.format(
-- - first entry is the value
-- - second entry is the description of the option
local telescope_defaults = {
local telescope_defaults = {}
config.descriptions_order = {}
local append = function(name, val, doc)
telescope_defaults[name] = { val, doc }
table.insert(config.descriptions_order, name)
end
sorting_strategy = {
"descending",
[[
Determines the direction "better" results are sorted towards.
append(
"sorting_strategy",
"descending",
[[
Determines the direction "better" results are sorted towards.
Available options are:
- "descending" (default)
- "ascending"]],
},
Available options are:
- "descending" (default)
- "ascending"]]
)
selection_strategy = {
"reset",
[[
Determines how the cursor acts after each sort iteration.
append(
"selection_strategy",
"reset",
[[
Determines how the cursor acts after each sort iteration.
Available options are:
- "reset" (default)
- "follow"
- "row"
- "closest"]],
},
Available options are:
- "reset" (default)
- "follow"
- "row"
- "closest"]]
)
scroll_strategy = {
"cycle",
[[
Determines what happens you try to scroll past view of the picker.
append(
"scroll_strategy",
"cycle",
[[
Determines what happens if you try to scroll past the view of the
picker.
Available options are:
- "cycle" (default)
- "limit"]],
},
Available options are:
- "cycle" (default)
- "limit"]]
)
layout_strategy = {
"horizontal",
[[
Determines the default layout of Telescope pickers.
See |telescope.layout| for details of the available strategies.
append(
"layout_strategy",
"horizontal",
[[
Determines the default layout of Telescope pickers.
See |telescope.layout| for details of the available strategies.
Default: 'horizontal']],
},
Default: 'horizontal']]
)
layout_config = { layout_config_defaults, layout_config_description },
append("layout_config", layout_config_defaults, layout_config_description)
winblend = { 0 },
append(
"winblend",
0,
[[
Configure winblend for telescope floating windows. See |winblend| for
more information.
prompt_prefix = { "> ", [[
Will be shown in front of the prompt.
Default: 0]]
)
Default: '> ']] },
append(
"prompt_prefix",
"> ",
[[
The character(s) that will be shown in front of Telescope's prompt.
selection_caret = { "> ", [[
Will be shown in front of the selection.
Default: '> ']]
)
Default: '> ']] },
append(
"selection_caret",
"> ",
[[
The character(s) that will be shown in front of the current selection.
entry_prefix = {
" ",
[[
Prefix in front of each result entry. Current selection not included.
Default: ' ']],
},
Default: '> ']]
)
initial_mode = { "insert" },
append(
"entry_prefix",
" ",
[[
Prefix in front of each result entry. Current selection not included.
border = { true, [[
Boolean defining if borders are added to Telescope windows.
Default: ' ']]
)
Default: true]] },
append(
"initial_mode",
"insert",
[[
Determines in which mode telescope starts. Valid Keys:
`insert` and `normal`.
path_display = {
{},
[[
Determines how file paths are displayed
Default: "insert"]]
)
path_display can be set to an array with a combination of:
- "hidden" hide file names
- "tail" only display the file name, and not the path
- "absolute" display absolute paths
- "smart" remove as much from the path as possible to only show
the difference between the displayed paths
- "shorten" only display the first character of each directory in
the path
append(
"border",
true,
[[
Boolean defining if borders are added to Telescope windows.
You can also specify the number of characters of each directory name
to keep by setting `path_display.shorten = num`.
e.g. for a path like
`alpha/beta/gamma/delta.txt`
setting `path_display.shorten = 1` will give a path like:
`a/b/g/delta.txt`
Similarly, `path_display.shorten = 2` will give a path like:
`al/be/ga/delta.txt`
Default: true]]
)
path_display can also be set to 'hidden' string to hide file names
append(
"path_display",
{},
[[
Determines how file paths are displayed
path_display can also be set to a function for custom formatting of
the path display. Example:
path_display can be set to an array with a combination of:
- "hidden" hide file names
- "tail" only display the file name, and not the path
- "absolute" display absolute paths
- "smart" remove as much from the path as possible to only show
the difference between the displayed paths
- "shorten" only display the first character of each directory in
the path
-- Format path as "file.txt (path\to\file\)"
path_display = function(opts, path)
local tail = require("telescope.utils").path_tail(path)
return string.format("%s (%s)", tail, path)
end,
You can also specify the number of characters of each directory name
to keep by setting `path_display.shorten = num`.
e.g. for a path like
`alpha/beta/gamma/delta.txt`
setting `path_display.shorten = 1` will give a path like:
`a/b/g/delta.txt`
Similarly, `path_display.shorten = 2` will give a path like:
`al/be/ga/delta.txt`
Default: {}]],
},
path_display can also be set to 'hidden' string to hide file names
borderchars = { { "─", "│", "─", "│", "╭", "╮", "╯", "╰" } },
path_display can also be set to a function for custom formatting of
the path display. Example:
get_status_text = {
function(self, opts)
local xx = (self.stats.processed or 0) - (self.stats.filtered or 0)
local yy = self.stats.processed or 0
if xx == 0 and yy == 0 then
return ""
end
-- Format path as "file.txt (path\to\file\)"
path_display = function(opts, path)
local tail = require("telescope.utils").path_tail(path)
return string.format("%s (%s)", tail, path)
end,
-- local status_icon
-- if opts.completed then
-- status_icon = "✔️"
-- else
-- status_icon = "*"
-- end
Default: {}]]
)
return string.format("%s / %s ", xx, yy)
append(
"borderchars",
{ "─", "│", "─", "│", "╭", "╮", "╯", "╰" },
[[
Set the borderchars of telescope floating windows. It has to be a
table of 8 string values.
Default: { "─", "│", "─", "│", "╭", "╮", "╯", "╰" }]]
)
append(
"get_status_text",
function(self)
local xx = (self.stats.processed or 0) - (self.stats.filtered or 0)
local yy = self.stats.processed or 0
if xx == 0 and yy == 0 then
return ""
end
-- local status_icon
-- if opts.completed then
-- status_icon = "✔️"
-- else
-- status_icon = "*"
-- end
return string.format("%s / %s", xx, yy)
end,
[[
A function that determines what the virtual text looks like.
Signature: function(picker) -> str
Default: function that shows current count / all]]
)
append(
"dynamic_preview_title",
false,
[[
Will change the title of the preview window dynamically, where it
is supported. For example, the preview window's title could show up as
the full filename.
Default: false]]
)
append(
"history",
{
path = vim.fn.stdpath "data" .. os_sep .. "telescope_history",
limit = 100,
handler = function(...)
return require("telescope.actions.history").get_simple_history(...)
end,
},
[[
This field handles the configuration for prompt history.
By default it is a table, with default values (more below).
To disable history, set it to false.
dynamic_preview_title = {
false,
[[
Will change the title of the preview window dynamically, where it
is supported. Means the preview window will for example show the
full filename.
Default: false]],
},
history = {
{
path = vim.fn.stdpath "data" .. os_sep .. "telescope_history",
limit = 100,
handler = function(...)
return require("telescope.actions.history").get_simple_history(...)
end,
},
[[
This field handles the configuration for prompt history.
By default it is a table, with default values (more below).
To disable history, set it to false.
Currently mappings still need to be added, Example:
mappings = {
i = {
["<C-Down>"] = require('telescope.actions').cycle_history_next,
["<C-Up>"] = require('telescope.actions').cycle_history_prev,
},
Currently mappings still need to be added, Example:
mappings = {
i = {
["<C-Down>"] = require('telescope.actions').cycle_history_next,
["<C-Up>"] = require('telescope.actions').cycle_history_prev,
},
Fields:
- path: The path to the telescope history as string.
default: stdpath("data")/telescope_history
- limit: The amount of entries that will be written in the
history.
Warning: If limit is set to nil it will grown unbound.
default: 100
- handler: A lua function that implements the history.
This is meant as a developer setting for extensions to
override the history handling, e.g.,
https://github.com/nvim-telescope/telescope-smart-history.nvim,
which allows context sensitive (cwd + picker) history.
Default:
require('telescope.actions.history').get_simple_history
]],
},
cache_picker = {
{
num_pickers = 1,
limit_entries = 1000,
},
[[
Fields:
- path: The path to the telescope history as string.
default: stdpath("data")/telescope_history
- limit: The amount of entries that will be written in the
history.
Warning: If limit is set to nil it will grown unbound.
default: 100
- handler: A lua function that implements the history.
This is meant as a developer setting for extensions to
override the history handling, e.g.,
https://github.com/nvim-telescope/telescope-smart-history.nvim,
which allows context sensitive (cwd + picker) history.
Default:
require('telescope.actions.history').get_simple_history]]
)
append(
"cache_picker",
{
num_pickers = 1,
limit_entries = 1000,
},
[[
This field handles the configuration for picker caching.
By default it is a table, with default values (more below).
To disable caching, set it to false.
@@ -323,117 +379,239 @@ local telescope_defaults = {
Default: 1
- limit_entries: The amount of entries that will be written in the
Default: 1000
]],
},
]]
)
-- Builtin configuration
append(
"vimgrep_arguments",
{ "rg", "--color=never", "--no-heading", "--with-filename", "--line-number", "--column", "--smart-case" },
[[
Defines the command that will be used for `live_grep` and `grep_string`
pickers.
Hint: Make sure that color is currently set to `never` because we do
not yet interpret color codes
Hint 2: Make sure that these options are in your changes arguments:
"--no-heading", "--with-filename", "--line-number", "--column"
because we need them so the ripgrep output is in the correct format.
-- List that will be executed.
-- Last argument will be the search term (passed in during execution)
vimgrep_arguments = {
{ "rg", "--color=never", "--no-heading", "--with-filename", "--line-number", "--column", "--smart-case" },
},
Default: {
"rg",
"--color=never",
"--no-heading",
"--with-filename",
"--line-number",
"--column",
"--smart-case"
}]]
)
use_less = { true },
append(
"use_less",
true,
[[
Boolean if less should be enabled in term_previewer (deprecated and
currently no longer used in the builtin pickers).
color_devicons = { true },
Default: true]]
)
set_env = { nil },
append(
"set_env",
nil,
[[
Set an environment for term_previewer. A table of key values:
Example: { COLORTERM = "truecolor", ... }
Hint: Empty table is not allowed.
Default: nil]]
)
append(
"color_devicons",
true,
[[
Boolean if devicons should be enabled or not.
Hint: Coloring only works if |termguicolors| is enabled.
Default: true]]
)
append(
"mappings",
{},
[[
Your mappings to override telescope's default mappings.
Format is:
{
mode = { ..keys }
}
where {mode} is the one character letter for a mode
('i' for insert, 'n' for normal).
For example:
mappings = {
{},
[[
Your mappings to override telescope's default mappings.
i = {
["<esc>"] = require('telescope.actions').close,
},
}
Format is:
{
mode = { ..keys }
}
where {mode} is the one character letter for a mode
('i' for insert, 'n' for normal).
To disable a keymap, put [map] = false
So, to not map "<C-n>", just put
...,
["<C-n>"] = false,
...,
Into your config.
otherwise, just set the mapping to the function that you want it to
be.
...,
["<C-i>"] = require('telescope.actions').select_default,
...,
If the function you want is part of `telescope.actions`, then you can
simply give a string.
For example, the previous option is equivalent to:
...,
["<C-i>"] = "select_default",
...,
You can also add other mappings using tables with `type = "command"`.
For example:
mappings = {
i = {
["<esc>"] = require('telescope.actions').close,
},
}
...,
["jj"] = { "<esc>", type = "command" },
["kk"] = { "<cmd>echo \"Hello, World!\"<cr>", type = "command" },)
...,
]]
)
append(
"default_mappings",
nil,
[[
Not recommended to use except for advanced users.
To disable a keymap, put [map] = false
So, to not map "<C-n>", just put
Will allow you to completely remove all of telescope's default maps
and use your own.
]]
)
...,
["<C-n>"] = false,
...,
append(
"file_sorter",
sorters.get_fzy_sorter,
[[
A function pointer that specifies the file_sorter. This sorter will
be used for find_files, git_files and similar.
Hint: If you load a native sorter, you dont need to change this value,
the native sorter will override it anyway.
Into your config.
Default: require("telescope.sorters").get_fzy_sorter]]
)
append(
"generic_sorter",
sorters.get_fzy_sorter,
[[
A function pointer to the generic sorter. The sorter that should be
used for everything that is not a file.
Hint: If you load a native sorter, you dont need to change this value,
the native sorter will override it anyway.
otherwise, just set the mapping to the function that you want it to
be.
Default: require("telescope.sorters").get_fzy_sorter]]
)
...,
["<C-i>"] = require('telescope.actions').select_default,
...,
--TODO(conni2461): Why is this even configurable???
append(
"prefilter_sorter",
sorters.prefilter,
[[
This points to a wrapper sorter around the generic_sorter that is able
to do prefiltering.
Its usually used for lsp_*_symbols and lsp_*_diagnostics
If the function you want is part of `telescope.actions`, then you can
simply give a string.
For example, the previous option is equivalent to:
Default: require("telescope.sorters").prefilter]]
)
...,
["<C-i>"] = "select_default",
...,
append(
"file_ignore_patterns",
nil,
[[
A table of lua regex that define the files that should be ignored.
Example: { "^scratch/" } -- ignore all files in scratch directory
Example: { "%.npz" } -- ignore all npz files
See: https://www.lua.org/manual/5.1/manual.html#5.4.1 for more
information about lua regex
You can also add other mappings using tables with `type = "command"`.
For example:
Default: nil]]
)
...,
["jj"] = { "<esc>", type = "command" },
["kk"] = { "<cmd>echo \"Hello, World!\"<cr>", type = "command" },)
...,
]],
},
append(
"file_previewer",
function(...)
return require("telescope.previewers").vim_buffer_cat.new(...)
end,
[[
Function pointer to the default file_previewer. It is mostly used
for find_files, git_files and similar.
You can change this function pointer to either use your own
previewer or use the command-line program bat as the previewer:
require("telescope.previewers").cat.new
default_mappings = {
nil,
[[
Not recommended to use except for advanced users.
Default: require("telescope.previewers").vim_buffer_cat.new]]
)
Will allow you to completely remove all of telescope's default maps
and use your own.
]],
},
append(
"grep_previewer",
function(...)
return require("telescope.previewers").vim_buffer_vimgrep.new(...)
end,
[[
Function pointer to the default vim_grep previewer. It is mostly
used for live_grep, grep_string and similar.
You can change this function pointer to either use your own
previewer or use the command-line program bat as the previewer:
require("telescope.previewers").vimgrep.new
generic_sorter = { sorters.get_generic_fuzzy_sorter },
prefilter_sorter = { sorters.prefilter },
file_sorter = { sorters.get_fuzzy_file },
Default: require("telescope.previewers").vim_buffer_vimgrep.new]]
)
file_ignore_patterns = { nil },
append(
"qflist_previewer",
function(...)
return require("telescope.previewers").vim_buffer_qflist.new(...)
end,
[[
Function pointer to the default qflist previewer. It is mostly
used for qflist, loclist and lsp.
You can change this function pointer to either use your own
previewer or use the command-line program bat as the previewer:
require("telescope.previewers").qflist.new
file_previewer = {
function(...)
return require("telescope.previewers").vim_buffer_cat.new(...)
end,
},
grep_previewer = {
function(...)
return require("telescope.previewers").vim_buffer_vimgrep.new(...)
end,
},
qflist_previewer = {
function(...)
return require("telescope.previewers").vim_buffer_qflist.new(...)
end,
},
buffer_previewer_maker = {
function(...)
return require("telescope.previewers").buffer_previewer_maker(...)
end,
},
}
Default: require("telescope.previewers").vim_buffer_vimgrep.new]]
)
append(
"buffer_previewer_maker",
function(...)
return require("telescope.previewers").buffer_previewer_maker(...)
end,
[[
Developer option that defines the underlining functionality
of the buffer previewer.
For interesting configuration examples take a look at
https://github.com/nvim-telescope/telescope.nvim/wiki/Configuration-Recipes
Default: require("telescope.previewers").buffer_previewer_maker]]
)
-- @param user_defaults table: a table where keys are the names of options,
-- and values are the ones the user wants
@@ -470,8 +648,7 @@ function config.set_defaults(user_defaults, tele_defaults)
end
local function set(name, default_val, description)
-- TODO(doc): Once we have descriptions for all of these, then we can add this back in.
-- assert(description, "Config values must always have a description")
assert(description, "Config values must always have a description")
config.values[name] = get(name, default_val)
if description then

57
lua/telescope/init.lua
View File

@@ -2,6 +2,7 @@ local _extensions = require "telescope._extensions"
local telescope = {}
-- TODO(conni2461): also table of contents for tree-sitter-lua
-- TODO: Add pre to the works
-- ---@pre [[
-- ---@pre ]]
@@ -10,22 +11,68 @@ local telescope = {}
--- Telescope.nvim is a plugin for fuzzy finding and neovim. It helps you search,
--- filter, find and pick things in Lua.
---
--- Getting started with telescope:
--- 1. Run `:checkhealth telescope` to make sure everything is installed.
--- 2. Evalulate it working with
--- `:Telescope find_files` or
--- `:lua require("telescope.builtin").find_files()`
--- 3. Put a `require("telescope").setup() call somewhere in your neovim config.
--- 4. Read |telescope.setup| to check what config keys are available and what you can put inside the setup call
--- 5. Read |telescope.builtin| to check which builtin pickers are offered and what options these implement
--- 6. Profit
---
--- <pre>
--- To find out more:
--- https://github.com/nvim-telescope/telescope.nvim
---
--- :h telescope.setup
--- :h telescope.command
--- :h telescope.builtin
--- :h telescope.themes
--- :h telescope.layout
--- :h telescope.resolve
--- :h telescope.actions
--- :h telescope.actions.state
--- :h telescope.actions.set
--- :h telescope.actions.utils
--- :h telescope.actions.generate
--- :h telescope.previewers
--- :h telescope.actions.history
--- </pre>
---@brief ]]
---@tag telescope.nvim
--- Setup function to be run by user. Configures the defaults, extensions
--- and other aspects of telescope.
---@param opts table: Configuration opts. Keys: defaults, extensions
--- Setup function to be run by user. Configures the defaults, pickers and
--- extensions of telescope.
---
--- Usage:
--- <code>
--- require('telescope').setup{
--- defaults = {
--- -- Default configuration for telescope goes here:
--- -- config_key = value,
--- -- ..
--- },
--- pickers = {
--- -- Default configuration for builtin pickers goes here:
--- -- picker_name = {
--- -- picker_config_key = value,
--- -- ...
--- -- }
--- -- Now the picker_config_key will be applied every time you call this
--- -- builtin picker
--- },
--- extensions = {
--- -- Your extension configuration goes here:
--- -- extension_name = {
--- -- extension_config_key = value,
--- -- }
--- -- please take a look at the readme of the extension you want to configure
--- }
--- }
--- </code>
---@param opts table: Configuration opts. Keys: defaults, pickers, extensions
---@eval { ["description"] = require('telescope').__format_setup_keys() }
function telescope.setup(opts)
opts = opts or {}
@@ -56,11 +103,9 @@ end
telescope.extensions = require("telescope._extensions").manager
telescope.__format_setup_keys = function()
local names = require("telescope.config").descriptions_order
local descriptions = require("telescope.config").descriptions
local names = vim.tbl_keys(descriptions)
table.sort(names)
local result = { "<pre>", "", "Valid keys for {opts.defaults}" }
for _, name in ipairs(names) do
local desc = descriptions[name]

8
lua/telescope/make_entry.lua
View File

@@ -61,7 +61,7 @@ do
function make_entry.gen_from_file(opts)
opts = opts or {}
local cwd = vim.fn.expand(opts.cwd or vim.fn.getcwd())
local cwd = vim.fn.expand(opts.cwd or vim.loop.cwd())
local disable_devicons = opts.disable_devicons
@@ -181,7 +181,7 @@ do
local display_string = "%s:%s%s"
mt_vimgrep_entry = {
cwd = vim.fn.expand(opts.cwd or vim.fn.getcwd()),
cwd = vim.fn.expand(opts.cwd or vim.loop.cwd()),
display = function(entry)
local display_filename = utils.transform_path(opts, entry.filename)
@@ -428,7 +428,7 @@ function make_entry.gen_from_buffer(opts)
},
}
local cwd = vim.fn.expand(opts.cwd or vim.fn.getcwd())
local cwd = vim.fn.expand(opts.cwd or vim.loop.cwd())
local make_display = function(entry)
local display_bufname = utils.transform_path(opts, entry.filename)
@@ -842,7 +842,7 @@ end
function make_entry.gen_from_ctags(opts)
opts = opts or {}
local cwd = vim.fn.expand(opts.cwd or vim.fn.getcwd())
local cwd = vim.fn.expand(opts.cwd or vim.loop.cwd())
local current_file = Path:new(vim.fn.expand "%"):normalize(cwd)
local display_items = {

4
lua/telescope/pickers.lua
View File

@@ -538,14 +538,14 @@ end
--- such as deleting buffers or files.
---
--- Example usage:
--- <pre>
--- <code>
--- actions.delete_something = function(prompt_bufnr)
--- local current_picker = action_state.get_current_picker(prompt_bufnr)
--- current_picker:delete_selection(function(selection)
--- -- delete the selection outside of telescope
--- end)
--- end
--- </pre>
--- </code>
---
--- Example usage in telescope:
--- - `actions.delete_buffer()`

4
lua/telescope/pickers/layout_strategies.lua
View File

@@ -6,7 +6,7 @@
---
--- All layout strategies are functions with the following signature:
---
--- <pre>
--- <code>
--- function(picker, columns, lines, layout_config)
--- -- Do some calculations here...
--- return {
@@ -15,7 +15,9 @@
--- prompt = prompt_configuration,
--- }
--- end
--- </code>
---
--- <pre>
--- Parameters: ~
--- - picker : A Picker object. (docs coming soon)
--- - columns : (number) Columns in the vim window

8
lua/telescope/previewers/init.lua
View File

@@ -77,11 +77,11 @@ end
--- 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:
--- <pre>
--- <code>
--- get_command = function(entry, status)
--- return { 'bat', entry.path }
--- end
--- </pre>
--- </code>
---
--- Additionally you can define:
--- - `title` a static title for example "File Preview"
@@ -219,12 +219,12 @@ previewers.qflist = term_previewer.qflist
--- - `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
--- <pre>
--- <code>
--- vim.api.nvim_buf_call(bufnr, function()
--- -- for example `search` and `matchadd`
--- end)
--- to achieve that.
--- </pre>
--- </code>
--- - 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`

14
lua/telescope/themes.lua
View File

@@ -15,14 +15,13 @@
local themes = {}
--- Dropdown style theme.
--- <pre>
---
--- Usage:
---
--- <code>
--- `local builtin = require('telescope.builtin')`
--- `local themes = require('telescope.themes')`
--- `builtin.find_files(themes.get_dropdown())`
--- </pre>
--- </code>
function themes.get_dropdown(opts)
opts = opts or {}
@@ -59,14 +58,14 @@ function themes.get_dropdown(opts)
end
--- Cursor style theme.
--- <pre>
---
--- Usage:
--- <code>
---
--- `local builtin = require('telescope.builtin')`
--- `local themes = require('telescope.themes')`
--- `builtin.lsp_code_actions(themes.get_cursor())`
--- </pre>
--- </code>
function themes.get_cursor(opts)
opts = opts or {}
@@ -97,14 +96,13 @@ function themes.get_cursor(opts)
end
--- Ivy style theme.
--- <pre>
---
--- Usage:
---
--- <code>
--- `local builtin = require('telescope.builtin')`
--- `local themes = require('telescope.themes')`
--- `builtin.find_files(themes.get_ivy())`
--- </pre>
--- </code>
function themes.get_ivy(opts)
opts = opts or {}