", 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
diff --git a/lua/telescope/init.lua b/lua/telescope/init.lua
index 7a740a3..d52d60d 100644
--- a/lua/telescope/init.lua
+++ b/lua/telescope/init.lua
@@ -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
+---
---
--- 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
---
---@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:
+---
+--- 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
+--- }
+--- }
+---
+---@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 = { "", "", "Valid keys for {opts.defaults}" }
for _, name in ipairs(names) do
local desc = descriptions[name]
diff --git a/lua/telescope/make_entry.lua b/lua/telescope/make_entry.lua
index beb7e18..bf0287c 100644
--- a/lua/telescope/make_entry.lua
+++ b/lua/telescope/make_entry.lua
@@ -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 = {
diff --git a/lua/telescope/pickers.lua b/lua/telescope/pickers.lua
index 1c0ce67..624ab00 100644
--- a/lua/telescope/pickers.lua
+++ b/lua/telescope/pickers.lua
@@ -538,14 +538,14 @@ end
--- such as deleting buffers or files.
---
--- Example usage:
----
+---
--- 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
----
+---
---
--- Example usage in telescope:
--- - `actions.delete_buffer()`
diff --git a/lua/telescope/pickers/layout_strategies.lua b/lua/telescope/pickers/layout_strategies.lua
index b97888a..c703d4f 100644
--- a/lua/telescope/pickers/layout_strategies.lua
+++ b/lua/telescope/pickers/layout_strategies.lua
@@ -6,7 +6,7 @@
---
--- All layout strategies are functions with the following signature:
---
----
+---
--- function(picker, columns, lines, layout_config)
--- -- Do some calculations here...
--- return {
@@ -15,7 +15,9 @@
--- prompt = prompt_configuration,
--- }
--- end
+---
---
+---
--- Parameters: ~
--- - picker : A Picker object. (docs coming soon)
--- - columns : (number) Columns in the vim window
diff --git a/lua/telescope/previewers/init.lua b/lua/telescope/previewers/init.lua
index b749056..0051fff 100644
--- a/lua/telescope/previewers/init.lua
+++ b/lua/telescope/previewers/init.lua
@@ -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:
----
+---
--- get_command = function(entry, status)
--- return { 'bat', entry.path }
--- end
----
+---
---
--- 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
----
+---
--- vim.api.nvim_buf_call(bufnr, function()
--- -- for example `search` and `matchadd`
--- end)
--- to achieve that.
----
+---
--- - If you want to read a file into the buffer it's best to use
--- `buffer_previewer_maker`. But access this function with
--- `require('telescope.config').values.buffer_previewer_maker`
diff --git a/lua/telescope/themes.lua b/lua/telescope/themes.lua
index 1cd2efe..301fa37 100644
--- a/lua/telescope/themes.lua
+++ b/lua/telescope/themes.lua
@@ -15,14 +15,13 @@
local themes = {}
--- Dropdown style theme.
----
---
--- Usage:
----
+---
--- `local builtin = require('telescope.builtin')`
--- `local themes = require('telescope.themes')`
--- `builtin.find_files(themes.get_dropdown())`
----
+---
function themes.get_dropdown(opts)
opts = opts or {}
@@ -59,14 +58,14 @@ function themes.get_dropdown(opts)
end
--- Cursor style theme.
----
---
--- Usage:
+---
---
--- `local builtin = require('telescope.builtin')`
--- `local themes = require('telescope.themes')`
--- `builtin.lsp_code_actions(themes.get_cursor())`
----
+---
function themes.get_cursor(opts)
opts = opts or {}
@@ -97,14 +96,13 @@ function themes.get_cursor(opts)
end
--- Ivy style theme.
----
---
--- Usage:
----
+---
--- `local builtin = require('telescope.builtin')`
--- `local themes = require('telescope.themes')`
--- `builtin.find_files(themes.get_ivy())`
----
+---
function themes.get_ivy(opts)
opts = opts or {}