From 36996056272a7174868367acf1043cead333d115 Mon Sep 17 00:00:00 2001 From: Simon Hauser Date: Fri, 9 Jul 2021 20:45:29 +0200 Subject: feat: cycle prompt history (#521) history is enabled on default but cycle_history_next and cycle_history_prev is not mapped yet Example: require('telescope').setup { defaults = { mappings = { i = { [""] = require('telescope.actions').cycle_history_next, [""] = require('telescope.actions').cycle_history_prev, } } } } For more information :help telescope.defaults.history big thanks to clason and all other testers :) --- doc/telescope.txt | 1657 ++++++++++++++++++++----------------- lua/telescope/actions/history.lua | 186 +++++ lua/telescope/actions/init.lua | 84 +- lua/telescope/actions/mt.lua | 22 +- lua/telescope/actions/set.lua | 14 + lua/telescope/actions/state.lua | 16 + lua/telescope/config.lua | 54 +- lua/telescope/pickers.lua | 7 +- scripts/gendocs.lua | 9 +- 9 files changed, 1261 insertions(+), 788 deletions(-) create mode 100644 lua/telescope/actions/history.lua diff --git a/doc/telescope.txt b/doc/telescope.txt index 6c932be..a264ec5 100644 --- a/doc/telescope.txt +++ b/doc/telescope.txt @@ -41,13 +41,43 @@ telescope.setup({opts}) *telescope.setup()* Default: false - *telescope.defaults.entry_prefix* entry_prefix: ~ Prefix in front of each result entry. Current selection not included. Default: ' ' + *telescope.defaults.history* + history: ~ + 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 either false or nil. + + Currently mappings still need to be added, Example: + mappings = { + i = { + [""] = require('telescope.actions').cycle_history_next, + [""] = 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 + + *telescope.defaults.layout_config* layout_config: ~ Determines the default configuration values for layout strategies. @@ -221,991 +251,1245 @@ telescope.extensions() *telescope.extensions()* ================================================================================ - *telescope.themes* - -Themes are ways to combine several elements of styling together. - -They are helpful for managing the several differnt UI aspects for telescope and -provide a simple interface for users to get a particular "style" of picker. - -themes.get_dropdown() *themes.get_dropdown()* - Dropdown style theme. + *telescope.builtin* - Usage: +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 the +amazing pickers already shipped with Telescope! - `local builtin = require('telescope.builtin')` - `local themes = require('telescope.themes')` - `builtin.find_files(themes.get_dropdown())` +Any of these functions can just be called directly by doing: +:lua require('telescope.builtin').$NAME_OF_PICKER() +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: -themes.get_ivy() *themes.get_ivy()* - Ivy style theme. +: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 +}) - Usage: +You can also pass default configurations to builtin pickers. These options will +also be added if the picker is executed with `Telescope find_files`. - `local builtin = require('telescope.builtin')` - `local themes = require('telescope.themes')` - `builtin.find_files(themes.get_ivy())` +require("telescope").setup { + pickers = { + buffers = { + show_all_buffers = true, + sort_lastused = true, + theme = "dropdown", + previewer = false, + mappings = { + i = { + [""] = require("telescope.actions").delete_buffer, + -- or right hand side can also be the name of the action as string + [""] = "delete_buffer", + }, + n = { + [""] = require("telescope.actions").delete_buffer, + } + } + } + } +} +This will use the default configuration options. Other configuration options +are still in flux at the moment +builtin.live_grep({opts}) *builtin.live_grep()* + Search for a string in your current working directory and get results live + as you type (respecting .gitignore) -================================================================================ - *telescope.actions.set* + Parameters: ~ + {opts} (table) options to pass to the picker -Telescope action sets are used to provide an interface for managing actions -that all primarily do the same thing, but with slight tweaks. + Fields: ~ + {grep_open_files} (boolean) if true, restrict search to open files + only, mutually exclusive with + `search_dirs` + {search_dirs} (table) directory/directories to search in, + mutually exclusive with `grep_open_files` -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. -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. +builtin.grep_string({opts}) *builtin.grep_string()* + Searches for the string under your cursor in your current working directory Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr - {change} (number) The amount to shift the selection by + {opts} (table) options to pass to the picker + Fields: ~ + {search} (string) the query to search + {search_dirs} (table) directory/directories to search in + {use_regex} (boolean) if true, special characters won't be escaped, + allows for using regex (default is false) -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. +builtin.find_files({opts}) *builtin.find_files()* + Lists files in your current working directory, respects .gitignore Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr - {type} (string) The type of selection to make + {opts} (table) options to pass to the picker + Fields: ~ + {find_command} (table) command line arguments for `find_files` to + use for the search, overrides default config + {follow} (boolean) if true, follows symlinks (i.e. uses `-L` + flag for the `find` command) + {hidden} (boolean) determines whether to show hidden files or + not (default is false) + {search_dirs} (table) directory/directories to search in -action_set.edit({prompt_bufnr}, {command}) *action_set.edit()* - Edit a file based on the current selection. +builtin.fd() *builtin.fd()* + This is an alias for the `find_files` picker - 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 +builtin.file_browser({opts}) *builtin.file_browser()* + Lists files and folders in your current working directory, open files, + navigate your filesystem, and create new files and folders + - Default keymaps: + - ``: opens the currently selected file, or navigates to the + currently selected directory + - ``: creates new file in current directory, creates new directory + if the name contains a trailing '/' + - Note: you can create files nested into several directories with + ``, i.e. `lua/telescope/init.lua` would 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 Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr - {direction} (number) The direction of the scrolling + {opts} (table) options to pass to the picker + Fields: ~ + {cwd} (string) directory path to browse (default is cwd) + {depth} (number) file tree depth to display (default is 1) -================================================================================ - *telescope.actions* +builtin.treesitter() *builtin.treesitter()* + Lists function names, variables, and other symbols from treesitter queries + - Default keymaps: + - ``: show autocompletion menu to prefilter your query by kind of ts + node you want to see (i.e. `:var:`) -Actions functions that are useful for people creating their own mappings. -actions.move_selection_next({prompt_bufnr}) *actions.move_selection_next()* - Move the selection to the next entry + Fields: ~ + {show_line} (boolean) if true, shows the row:column that the result is + found at (default is true) + + +builtin.current_buffer_fuzzy_find({opts})*builtin.current_buffer_fuzzy_find()* + Live fuzzy search inside of the currently open buffer Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr + {opts} (table) options to pass to the picker -actions.move_selection_previous({prompt_bufnr})*actions.move_selection_previous()* - Move the selection to the previous entry +builtin.tags({opts}) *builtin.tags()* + 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) Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr + {opts} (table) options to pass to the picker + Fields: ~ + {ctags_file} (string) specify a particular ctags file to use + {show_line} (boolean) if true, shows the content of the line the tag + is found on in the picker (default is true) -actions.move_selection_worse({prompt_bufnr}) *actions.move_selection_worse()* - Move the selection to the entry that has a worse score + +builtin.current_buffer_tags({opts}) *builtin.current_buffer_tags()* + Lists all of the tags for the currently open buffer, with a preview Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr + {opts} (table) options to pass to the picker -actions.move_selection_better({prompt_bufnr})*actions.move_selection_better()* - Move the selection to the entry that has a better score +builtin.git_files({opts}) *builtin.git_files()* + Fuzzy search for files tracked by Git. This command lists the output of the + `git ls-files` command, respects .gitignore, and optionally ignores + untracked files + - Default keymaps: + - ``: opens the currently selected file Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr + {opts} (table) options to pass to the picker + + Fields: ~ + {show_untracked} (boolean) if true, adds `--others` flag to + command and shows untracked files + (default is true) + {recurse_submodules} (boolean) if true, adds the + `--recurse-submodules` flag to command + (default is false) -actions.move_to_top({prompt_bufnr}) *actions.move_to_top()* - Move to the top of the picker +builtin.git_commits({opts}) *builtin.git_commits()* + Lists commits for current directory with diff preview + - Default keymaps: + - ``: checks out the currently selected commit Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr + {opts} (table) options to pass to the picker + Fields: ~ + {cwd} (string) specify the path of the repo -actions.move_to_middle({prompt_bufnr}) *actions.move_to_middle()* - Move to the middle of the picker + +builtin.git_bcommits({opts}) *builtin.git_bcommits()* + Lists commits for current buffer with diff preview + - Default keymaps or your overriden `select_` keys: + - ``: checks out the currently selected commit + - ``: opens a diff in a vertical split + - ``: opens a diff in a horizontal split + - ``: opens a diff in a new tab Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr + {opts} (table) options to pass to the picker + Fields: ~ + {cwd} (string) specify the path of the repo + {current_file} (string) specify the current file that should be used + for bcommits (default: current buffer) -actions.move_to_bottom({prompt_bufnr}) *actions.move_to_bottom()* - Move to the bottom of the picker + +builtin.git_branches({opts}) *builtin.git_branches()* + List branches for current directory, with output from `git log --oneline` + shown in the preview window + - Default keymaps: + - ``: checks out the currently selected branch + - ``: tracks currently selected branch + - ``: rebases currently selected branch + - ``: creates a new branch, with confirmation prompt before creation + - ``: deletes the currently selected branch, with confirmation + prompt before deletion Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr + {opts} (table) options to pass to the picker -actions.add_selection({prompt_bufnr}) *actions.add_selection()* - Add current entry to multi select +builtin.git_status({opts}) *builtin.git_status()* + Lists git status for current directory + - Default keymaps: + - ``: stages or unstages the currently selected file + - ``: opens the currently selected file Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr + {opts} (table) options to pass to the picker -actions.remove_selection({prompt_bufnr}) *actions.remove_selection()* - Remove current entry from multi select +builtin.git_stash({opts}) *builtin.git_stash()* + Lists stash items in current repository + - Default keymaps: + - ``: runs `git apply` for currently selected stash Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr + {opts} (table) options to pass to the picker -actions.toggle_selection({prompt_bufnr}) *actions.toggle_selection()* - Toggle current entry status for multi select +builtin.builtin({opts}) *builtin.builtin()* + Lists all of the community maintained pickers built into Telescope Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr + {opts} (table) options to pass to the picker -actions.select_all({prompt_bufnr}) *actions.select_all()* - Multi select all entries. - - Note: selected entries may include results not visible in the results - popup. +builtin.planets({opts}) *builtin.planets()* + Use the telescope... Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr + {opts} (table) options to pass to the picker -actions.drop_all({prompt_bufnr}) *actions.drop_all()* - Drop all entries from the current multi selection. +builtin.symbols({opts}) *builtin.symbols()* + Lists symbols inside of data/telescope-sources/*.json found in your runtime + path. Check README for more info Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr + {opts} (table) options to pass to the picker -actions.toggle_all({prompt_bufnr}) *actions.toggle_all()* - Toggle multi selection for all entries. - - Note: toggled entries may include results not visible in the results - popup. +builtin.commands({opts}) *builtin.commands()* + Lists available plugin/user commands and runs them on `` Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr + {opts} (table) options to pass to the picker -actions.git_create_branch({prompt_bufnr}) *actions.git_create_branch()* - Create and checkout a new git branch if it doesn't already exist +builtin.quickfix({opts}) *builtin.quickfix()* + Lists items in the quickfix list, jumps to location on `` Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr + {opts} (table) options to pass to the picker -actions.git_apply_stash({prompt_bufnr}) *actions.git_apply_stash()* - Applies an existing git stash +builtin.loclist({opts}) *builtin.loclist()* + Lists items from the current window's location list, jumps to location on + `` Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr + {opts} (table) options to pass to the picker -actions.git_checkout({prompt_bufnr}) *actions.git_checkout()* - Checkout an existing git branch +builtin.oldfiles({opts}) *builtin.oldfiles()* + Lists previously open files, opens on `` Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr + {opts} (table) options to pass to the picker -actions.git_switch_branch({prompt_bufnr}) *actions.git_switch_branch()* - Switch to git branch. - If the branch already exists in local, switch to that. If the branch is - only in remote, create new branch tracking remote and switch to new one. +builtin.command_history({opts}) *builtin.command_history()* + Lists commands that were executed recently, and reruns them on `` + - Default keymaps: + - ``: open the command line with the text of the currently selected + result populated in it Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr + {opts} (table) options to pass to the picker -actions.git_track_branch({prompt_bufnr}) *actions.git_track_branch()* - Tell git to track the currently selected remote branch in Telescope +builtin.search_history({opts}) *builtin.search_history()* + Lists searches that were executed recently, and reruns them on `` + - Default keymaps: + - ``: open a search window with the text of the currently selected + search result populated in it Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr + {opts} (table) options to pass to the picker -actions.git_delete_branch({prompt_bufnr}) *actions.git_delete_branch()* - Delete the currently selected branch +builtin.vim_options({opts}) *builtin.vim_options()* + Lists vim options, allows you to edit the current value on `` Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr + {opts} (table) options to pass to the picker -actions.git_rebase_branch({prompt_bufnr}) *actions.git_rebase_branch()* - Rebase to selected git branch +builtin.help_tags({opts}) *builtin.help_tags()* + Lists available help tags and opens a new window with the relevant help + info on `` Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr + {opts} (table) options to pass to the picker -actions.git_staging_toggle({prompt_bufnr}) *actions.git_staging_toggle()* - Stage/unstage selected file +builtin.man_pages({opts}) *builtin.man_pages()* + Lists manpage entries, opens them in a help window on `` Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr + {opts} (table) options to pass to the picker -actions.send_selected_to_qflist() *actions.send_selected_to_qflist()* - Sends the selected entries to the quickfix list, replacing the previous - entries. +builtin.reloader({opts}) *builtin.reloader()* + Lists lua modules and reloads them on `` + Parameters: ~ + {opts} (table) options to pass to the picker -actions.add_selected_to_qflist() *actions.add_selected_to_qflist()* - Adds the selected entries to the quickfix list, keeping the previous - entries. +builtin.buffers({opts}) *builtin.buffers()* + Lists open buffers in current neovim instance, opens selected buffer on + `` -actions.send_to_qflist() *actions.send_to_qflist()* - Sends all entries to the quickfix list, replacing the previous entries. + Parameters: ~ + {opts} (table) options to pass to the picker + Fields: ~ + {show_all_buffers} (boolean) if true, show all buffers, including + unloaded buffers (default true) + {ignore_current_buffer} (boolean) if true, don't show the current + buffer in the list (default false) + {only_cwd} (boolean) if true, only show buffers in the + current working directory (default + false) + {sort_lastused} (boolean) if true, sort the shown buffers so + that the last used one is selected + (default false) + {bufnr_width} (number) Defines the width of the buffer + numbers in front of the filenames -actions.add_to_qflist() *actions.add_to_qflist()* - Adds all entries to the quickfix list, keeping the previous entries. +builtin.colorscheme({opts}) *builtin.colorscheme()* + Lists available colorschemes and applies them on `` + Parameters: ~ + {opts} (table) options to pass to the picker -actions.send_selected_to_loclist() *actions.send_selected_to_loclist()* - Sends the selected entries to the location list, replacing the previous - entries. +builtin.marks({opts}) *builtin.marks()* + Lists vim marks and their value, jumps to the mark on `` -actions.add_selected_to_loclist() *actions.add_selected_to_loclist()* - Adds the selected entries to the location list, keeping the previous - entries. + Parameters: ~ + {opts} (table) options to pass to the picker +builtin.registers({opts}) *builtin.registers()* + Lists vim registers, pastes the contents of the register on `` + - Default keymaps: + - ``: edit the contents of the currently selected register -actions.send_to_loclist() *actions.send_to_loclist()* - Sends all entries to the location list, replacing the previous entries. + Parameters: ~ + {opts} (table) options to pass to the picker -actions.add_to_loclist() *actions.add_to_loclist()* - Adds all entries to the location list, keeping the previous entries. +builtin.keymaps({opts}) *builtin.keymaps()* + Lists normal mode keymappings, runs the selected keymap on `` + Parameters: ~ + {opts} (table) options to pass to the picker -actions.smart_send_to_qflist() *actions.smart_send_to_qflist()* - Sends the selected entries to the quickfix list, replacing the previous - entries. If no entry was selected, sends all entries. +builtin.filetypes({opts}) *builtin.filetypes()* + Lists all available filetypes, sets currently open buffer's filetype to + selected filetype in Telescope on `` -actions.smart_add_to_qflist() *actions.smart_add_to_qflist()* - Adds the selected entries to the quickfix list, keeping the previous - entries. If no entry was selected, adds all entries. + Parameters: ~ + {opts} (table) options to pass to the picker +builtin.highlights({opts}) *builtin.highlights()* + Lists all available highlights -actions.smart_send_to_loclist() *actions.smart_send_to_loclist()* - Sends the selected entries to the location list, replacing the previous - entries. If no entry was selected, sends all entries. + Parameters: ~ + {opts} (table) options to pass to the picker -actions.smart_add_to_loclist() *actions.smart_add_to_loclist()* - Adds the selected entries to the location list, keeping the previous - entries. If no entry was selected, adds all entries. +builtin.autocommands({opts}) *builtin.autocommands()* + Lists vim autocommands and goes to their declaration on `` + Parameters: ~ + {opts} (table) options to pass to the picker -actions.open_qflist() *actions.open_qflist()* - Open the quickfix list + +builtin.spell_suggest({opts}) *builtin.spell_suggest()* + Lists spelling suggestions for the current word under the cursor, replaces + word with selected suggestion on `` + Parameters: ~ + {opts} (table) options to pass to the picker -actions.open_loclist() *actions.open_loclist()* - Open the location list +builtin.tagstack({opts}) *builtin.tagstack()* + Lists the tag stack for the current window, jumps to tag on `` -actions.delete_buffer({prompt_bufnr}) *actions.delete_buffer()* - Delete the selected buffer or all the buffers selected using multi - selection. + Parameters: ~ + {opts} (table) options to pass to the picker + + +builtin.jumplist({opts}) *builtin.jumplist()* + Lists items from Vim's jumplist, jumps to location on `` Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr + {opts} (table) options to pass to the picker -actions.cycle_previewers_next({prompt_bufnr})*actions.cycle_previewers_next()* - Cycle to the next previewer if there is one available. - This action is not mapped on default. +builtin.lsp_references({opts}) *builtin.lsp_references()* + Lists LSP references for word under the cursor, jumps to reference on + `` Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr + {opts} (table) options to pass to the picker -actions.cycle_previewers_prev({prompt_bufnr})*actions.cycle_previewers_prev()* - Cycle to the previous previewer if there is one available. - This action is not mapped on default. +builtin.lsp_definitions({opts}) *builtin.lsp_definitions()* + Goto the definition of the word under the cursor, if there's only one, + otherwise show all options in Telescope Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr + {opts} (table) options to pass to the picker +builtin.lsp_implementations({opts}) *builtin.lsp_implementations()* + Goto the implementation of the word under the cursor if there's only one, + otherwise show all options in Telescope -================================================================================ - *telescope.builtin* -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 the -amazing pickers already shipped with Telescope! + Parameters: ~ + {opts} (table) options to pass to the picker -Any of these functions can just be called directly by doing: -:lua require('telescope.builtin').$NAME_OF_PICKER() +builtin.lsp_code_actions({opts}) *builtin.lsp_code_actions()* + Lists any LSP actions for the word under the cursor which can be triggered + with `` -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: -: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 -}) + Parameters: ~ + {opts} (table) options to pass to the picker -You can also pass default configurations to builtin pickers. These options will -also be added if the picker is executed with `Telescope find_files`. -require("telescope").setup { - pickers = { - buffers = { - show_all_buffers = true, - sort_lastused = true, - theme = "dropdown", - previewer = false, - mappings = { - i = { - [""] = require("telescope.actions").delete_buffer, - -- or right hand side can also be the name of the action as string - [""] = "delete_buffer", - }, - n = { - [""] = require("telescope.actions").delete_buffer, - } - } - } - } -} +builtin.lsp_range_code_actions({opts}) *builtin.lsp_range_code_actions()* + Lists any LSP actions for a given range, that can be triggered with `` -This will use the default configuration options. Other configuration options -are still in flux at the moment -builtin.live_grep({opts}) *builtin.live_grep()* - Search for a string in your current working directory and get results live - as you type (respecting .gitignore) + Parameters: ~ + {opts} (table) options to pass to the picker + + +builtin.lsp_document_symbols({opts}) *builtin.lsp_document_symbols()* + Lists LSP document symbols in the current buffer + - Default keymaps: + - ``: show autocompletion menu to prefilter your query by type of + symbol you want to see (i.e. `:variable:`) Parameters: ~ {opts} (table) options to pass to the picker Fields: ~ - {grep_open_files} (boolean) if true, restrict search to open files - only, mutually exclusive with - `search_dirs` - {search_dirs} (table) directory/directories to search in, - mutually exclusive with `grep_open_files` + {ignore_filename} (type) string with file to ignore + {symbols} (string|table) filter results by symbol kind(s) -builtin.grep_string({opts}) *builtin.grep_string()* - Searches for the string under your cursor in your current working directory +builtin.lsp_workspace_symbols({opts}) *builtin.lsp_workspace_symbols()* + Lists LSP document symbols in the current workspace + - Default keymaps: + - ``: show autocompletion menu to prefilter your query by type of + symbol you want to see (i.e. `:variable:`) Parameters: ~ {opts} (table) options to pass to the picker Fields: ~ - {search} (string) the query to search - {search_dirs} (table) directory/directories to search in - {use_regex} (boolean) if true, special characters won't be escaped, - allows for using regex (default is false) + {ignore_filename} (string) file(s) to ignore + {symbols} (string|table) filter results by symbol kind(s) -builtin.find_files({opts}) *builtin.find_files()* - Lists files in your current working directory, respects .gitignore +builtin.lsp_dynamic_workspace_symbols({opts})*builtin.lsp_dynamic_workspace_symbols()* + Dynamically lists LSP for all workspace symbols + - Default keymaps: + - ``: show autocompletion menu to prefilter your query by type of + symbol you want to see (i.e. `:variable:`) + + + Parameters: ~ + {opts} (table) options to pass to the picker + + +builtin.lsp_document_diagnostics({opts}) *builtin.lsp_document_diagnostics()* + Lists LSP diagnostics for the current buffer + - Fields: + - `All severity flags can be passed as `string` or `number` as per + `:vim.lsp.protocol.DiagnosticSeverity:` + - Default keymaps: + - ``: show autocompletion menu to prefilter your query with the + diagnostic you want to see (i.e. `:warning:`) + + + Parameters: ~ + {opts} (table) options to pass to the picker + + Fields: ~ + {severity} (string|number) filter diagnostics by severity name + (string) or id (number) + {severity_limit} (string|number) keep diagnostics equal or more severe + wrt severity name (string) or id + (number) + {severity_bound} (string|number) keep diagnostics equal or less severe + wrt severity name (string) or id + (number) + {no_sign} (bool) hide LspDiagnosticSigns from Results + (default is false) + {line_width} (number) set length of diagnostic entry text + in Results + + +builtin.lsp_workspace_diagnostics({opts})*builtin.lsp_workspace_diagnostics()* + Lists LSP diagnostics for the current workspace if supported, otherwise + searches in all open buffers + - Fields: + - `All severity flags can be passed as `string` or `number` as per + `:vim.lsp.protocol.DiagnosticSeverity:` + - Default keymaps: + - ``: show autocompletion menu to prefilter your query with the + diagnostic you want to see (i.e. `:warning:`) Parameters: ~ {opts} (table) options to pass to the picker - Fields: ~ - {find_command} (table) command line arguments for `find_files` to - use for the search, overrides default config - {follow} (boolean) if true, follows symlinks (i.e. uses `-L` - flag for the `find` command) - {hidden} (boolean) determines whether to show hidden files or - not (default is false) - {search_dirs} (table) directory/directories to search in + Fields: ~ + {severity} (string|number) filter diagnostics by severity name + (string) or id (number) + {severity_limit} (string|number) keep diagnostics equal or more severe + wrt severity name (string) or id + (number) + {severity_bound} (string|number) keep diagnostics equal or less severe + wrt severity name (string) or id + (number) + {no_sign} (bool) hide LspDiagnosticSigns from Results + (default is false) + {line_width} (number) set length of diagnostic entry text + in Results + + + +================================================================================ + *telescope.themes* + +Themes are ways to combine several elements of styling together. + +They are helpful for managing the several differnt UI aspects for telescope and +provide a simple interface for users to get a particular "style" of picker. + +themes.get_dropdown() *themes.get_dropdown()* + Dropdown style theme. + + Usage: + + `local builtin = require('telescope.builtin')` + `local themes = require('telescope.themes')` + `builtin.find_files(themes.get_dropdown())` + + + +themes.get_ivy() *themes.get_ivy()* + Ivy style theme. + + Usage: + + `local builtin = require('telescope.builtin')` + `local themes = require('telescope.themes')` + `builtin.find_files(themes.get_ivy())` + + + + +================================================================================ + *telescope.layout* + +Layout strategies are different functions to position telescope. + +All layout strategies are functions with the following signature: + + function(picker, columns, lines, layout_config) + -- Do some calculations here... + return { + preview = preview_configuration + results = results_configuration, + prompt = prompt_configuration, + } + end + + Parameters: ~ + - picker : A Picker object. (docs coming soon) + - columns : (number) Columns in the vim window + - lines : (number) Lines in the vim window + - layout_config : (table) The configuration values specific to the picker. + + +This means you can create your own layout strategy if you want! Just be aware +for now that we may change some APIs or interfaces, so they may break if you +create your own. + +A good method for creating your own would be to copy one of the strategies that +most resembles what you want from +"./lua/telescope/pickers/layout_strategies.lua" in the telescope repo. + + +layout_strategies.horizontal() *layout_strategies.horizontal()* + Horizontal layout has two columns, one for the preview and one for the + prompt and results. + + ┌──────────────────────────────────────────────────┐ + │ │ + │ ┌───────────────────┐┌───────────────────┐ │ + │ │ ││ │ │ + │ │ ││ │ │ + │ │ ││ │ │ + │ │ Results ││ │ │ + │ │ ││ Preview │ │ + │ │ ││ │ │ + │ │ ││ │ │ + │ └───────────────────┘│ │ │ + │ ┌───────────────────┐│ │ │ + │ │ Prompt ││ │ │ + │ └───────────────────┘└───────────────────┘ │ + │ │ + └──────────────────────────────────────────────────┘ + + `picker.layout_config` shared options: + - height: + - How tall to make Telescope's entire layout + - See |resolver.resolve_height()| + - mirror: Flip the location of the results/prompt and preview windows + - scroll_speed: The number of lines to scroll through the previewer + - width: + - How wide to make Telescope's entire layout + - See |resolver.resolve_width()| + + `picker.layout_config` unique options: + - preview_cutoff: When columns are less than this value, the preview will be disabled + - preview_width: + - Change the width of Telescope's preview window + - See |resolver.resolve_width()| + - prompt_position: + - Where to place prompt window. + - Available Values: 'bottom', 'top' + + +layout_strategies.center() *layout_strategies.center()* + Centered layout with a combined block of the prompt and results aligned to + the middle of the screen. The preview window is then placed in the + remaining space above. Particularly useful for creating dropdown menus (see + |telescope.themes| and |themes.get_dropdown()|`). + + ┌──────────────────────────────────────────────────┐ + │ ┌────────────────────────────────────────┐ │ + │ | Preview | │ + │ | Preview | │ + │ └────────────────────────────────────────┘ │ + │ ┌────────────────────────────────────────┐ │ + │ | Prompt | │ + │ ├────────────────────────────────────────┤ │ + │ | Result | │ + │ | Result | │ + │ └────────────────────────────────────────┘ │ + │ │ + │ │ + │ │ + │ │ + └──────────────────────────────────────────────────┘ + + `picker.layout_config` shared options: + - height: + - How tall to make Telescope's entire layout + - See |resolver.resolve_height()| + - mirror: Flip the location of the results/prompt and preview windows + - scroll_speed: The number of lines to scroll through the previewer + - width: + - How wide to make Telescope's entire layout + - See |resolver.resolve_width()| + + `picker.layout_config` unique options: + - preview_cutoff: When lines are less than this value, the preview will be disabled + + +layout_strategies.vertical() *layout_strategies.vertical()* + Vertical layout stacks the items on top of each other. Particularly useful + with thinner windows. + + ┌──────────────────────────────────────────────────┐ + │ │ + │ ┌────────────────────────────────────────┐ │ + │ | Preview | │ + │ | Preview | │ + │ | Preview | │ + │ └────────────────────────────────────────┘ │ + │ ┌────────────────────────────────────────┐ │ + │ | Result | │ + │ | Result | │ + │ └────────────────────────────────────────┘ │ + │ ┌────────────────────────────────────────┐ │ + │ | Prompt | │ + │ └────────────────────────────────────────┘ │ + │ │ + └──────────────────────────────────────────────────┘ + + `picker.layout_config` shared options: + - height: + - How tall to make Telescope's entire layout + - See |resolver.resolve_height()| + - mirror: Flip the location of the results/prompt and preview windows + - scroll_speed: The number of lines to scroll through the previewer + - width: + - How wide to make Telescope's entire layout + - See |resolver.resolve_width()| + + `picker.layout_config` unique options: + - preview_cutoff: When lines are less than this value, the preview will be disabled + - preview_height: + - Change the height of Telescope's preview window + - See |resolver.resolve_height()| + - prompt_position: + - (unimplemented, but we plan on supporting) + +layout_strategies.flex() *layout_strategies.flex()* + Flex layout swaps between `horizontal` and `vertical` strategies based on + the window width + - Supports |layout_strategies.vertical| or |layout_strategies.horizontal| + features -builtin.fd() *builtin.fd()* - This is an alias for the `find_files` picker + `picker.layout_config` shared options: + - height: + - How tall to make Telescope's entire layout + - See |resolver.resolve_height()| + - mirror: Flip the location of the results/prompt and preview windows + - scroll_speed: The number of lines to scroll through the previewer + - width: + - How wide to make Telescope's entire layout + - See |resolver.resolve_width()| + `picker.layout_config` unique options: + - flip_columns: The number of columns required to move to horizontal mode + - flip_lines: The number of lines required to move to horizontal mode + - horizontal: Options to pass when switching to horizontal layout + - vertical: Options to pass when switching to vertical layout -builtin.file_browser({opts}) *builtin.file_browser()* - Lists files and folders in your current working directory, open files, - navigate your filesystem, and create new files and folders - - Default keymaps: - - ``: opens the currently selected file, or navigates to the - currently selected directory - - ``: creates new file in current directory, creates new directory - if the name contains a trailing '/' - - Note: you can create files nested into several directories with - ``, i.e. `lua/telescope/init.lua` would 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 +layout_strategies.bottom_pane() *layout_strategies.bottom_pane()* + Bottom pane can be used to create layouts similar to "ivy". - Parameters: ~ - {opts} (table) options to pass to the picker + For an easy ivy configuration, see |themes.get_ivy()| - Fields: ~ - {cwd} (string) directory path to browse (default is cwd) - {depth} (number) file tree depth to display (default is 1) -builtin.treesitter() *builtin.treesitter()* - Lists function names, variables, and other symbols from treesitter queries - - Default keymaps: - - ``: show autocompletion menu to prefilter your query by kind of ts - node you want to see (i.e. `:var:`) +================================================================================ + *telescope.resolve* + +Provides "resolver functions" to allow more customisable inputs for options. - Fields: ~ - {show_line} (boolean) if true, shows the row:column that the result is - found at (default is true) +resolver.resolve_height() *resolver.resolve_height()* + Converts input to a function that returns the height. The input must take + one of four forms: + 1. 0 <= number < 1 + This means total height as a percentage. + 2. 1 <= number + This means total height as a fixed number. + 3. function + Must have signature: function(self, max_columns, max_lines): number + 4. table of the form: {padding = `foo`} + where `foo` has one of the previous three forms. + The height is then set to be the remaining space after padding. For + example, if the window has height 50, and the input is {padding = 5}, + the height returned will be `40 = 50 - 2*5` + The returned function will have signature: function(self, max_columns, + max_lines): number -builtin.current_buffer_fuzzy_find({opts})*builtin.current_buffer_fuzzy_find()* - Live fuzzy search inside of the currently open buffer - Parameters: ~ - {opts} (table) options to pass to the picker +resolver.resolve_width() *resolver.resolve_width()* + Converts input to a function that returns the width. The input must take + one of four forms: + 1. 0 <= number < 1 + This means total width as a percentage. + 2. 1 <= number + This means total width as a fixed number. + 3. function + Must have signature: function(self, max_columns, max_lines): number + 4. table of the form: {padding = `foo`} + where `foo` has one of the previous three forms. + The width is then set to be the remaining space after padding. For + example, if the window has width 100, and the input is {padding = 5}, + the width returned will be `90 = 100 - 2*5` + The returned function will have signature: function(self, max_columns, + max_lines): number -builtin.tags({opts}) *builtin.tags()* - 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) - Parameters: ~ - {opts} (table) options to pass to the picker - Fields: ~ - {ctags_file} (string) specify a particular ctags file to use - {show_line} (boolean) if true, shows the content of the line the tag - is found on in the picker (default is true) +================================================================================ + *telescope.actions* +Actions functions that are useful for people creating their own mappings. -builtin.current_buffer_tags({opts}) *builtin.current_buffer_tags()* - Lists all of the tags for the currently open buffer, with a preview +actions.move_selection_next({prompt_bufnr}) *actions.move_selection_next()* + Move the selection to the next entry Parameters: ~ - {opts} (table) options to pass to the picker + {prompt_bufnr} (number) The prompt bufnr -builtin.git_files({opts}) *builtin.git_files()* - Fuzzy search for files tracked by Git. This command lists the output of the - `git ls-files` command, respects .gitignore, and optionally ignores - untracked files - - Default keymaps: - - ``: opens the currently selected file +actions.move_selection_previous({prompt_bufnr})*actions.move_selection_previous()* + Move the selection to the previous entry Parameters: ~ - {opts} (table) options to pass to the picker - - Fields: ~ - {show_untracked} (boolean) if true, adds `--others` flag to - command and shows untracked files - (default is true) - {recurse_submodules} (boolean) if true, adds the - `--recurse-submodules` flag to command - (default is false) + {prompt_bufnr} (number) The prompt bufnr -builtin.git_commits({opts}) *builtin.git_commits()* - Lists commits for current directory with diff preview - - Default keymaps: - - ``: checks out the currently selected commit +actions.move_selection_worse({prompt_bufnr}) *actions.move_selection_worse()* + Move the selection to the entry that has a worse score Parameters: ~ - {opts} (table) options to pass to the picker - - Fields: ~ - {cwd} (string) specify the path of the repo + {prompt_bufnr} (number) The prompt bufnr -builtin.git_bcommits({opts}) *builtin.git_bcommits()* - Lists commits for current buffer with diff preview - - Default keymaps or your overriden `select_` keys: - - ``: checks out the currently selected commit - - ``: opens a diff in a vertical split - - ``: opens a diff in a horizontal split - - ``: opens a diff in a new tab +actions.move_selection_better({prompt_bufnr})*actions.move_selection_better()* + Move the selection to the entry that has a better score Parameters: ~ - {opts} (table) options to pass to the picker - - Fields: ~ - {cwd} (string) specify the path of the repo - {current_file} (string) specify the current file that should be used - for bcommits (default: current buffer) + {prompt_bufnr} (number) The prompt bufnr -builtin.git_branches({opts}) *builtin.git_branches()* - List branches for current directory, with output from `git log --oneline` - shown in the preview window - - Default keymaps: - - ``: checks out the currently selected branch - - ``: tracks currently selected branch - - ``: rebases currently selected branch - - ``: creates a new branch, with confirmation prompt before creation - - ``: deletes the currently selected branch, with confirmation - prompt before deletion +actions.move_to_top({prompt_bufnr}) *actions.move_to_top()* + Move to the top of the picker Parameters: ~ - {opts} (table) options to pass to the picker + {prompt_bufnr} (number) The prompt bufnr -builtin.git_status({opts}) *builtin.git_status()* - Lists git status for current directory - - Default keymaps: - - ``: stages or unstages the currently selected file - - ``: opens the currently selected file +actions.move_to_middle({prompt_bufnr}) *actions.move_to_middle()* + Move to the middle of the picker Parameters: ~ - {opts} (table) options to pass to the picker + {prompt_bufnr} (number) The prompt bufnr -builtin.git_stash({opts}) *builtin.git_stash()* - Lists stash items in current repository - - Default keymaps: - - ``: runs `git apply` for currently selected stash +actions.move_to_bottom({prompt_bufnr}) *actions.move_to_bottom()* + Move to the bottom of the picker Parameters: ~ - {opts} (table) options to pass to the picker + {prompt_bufnr} (number) The prompt bufnr -builtin.builtin({opts}) *builtin.builtin()* - Lists all of the community maintained pickers built into Telescope +actions.add_selection({prompt_bufnr}) *actions.add_selection()* + Add current entry to multi select Parameters: ~ - {opts} (table) options to pass to the picker + {prompt_bufnr} (number) The prompt bufnr -builtin.planets({opts}) *builtin.planets()* - Use the telescope... +actions.remove_selection({prompt_bufnr}) *actions.remove_selection()* + Remove current entry from multi select Parameters: ~ - {opts} (table) options to pass to the picker + {prompt_bufnr} (number) The prompt bufnr -builtin.symbols({opts}) *builtin.symbols()* - Lists symbols inside of data/telescope-sources/*.json found in your runtime - path. Check README for more info +actions.toggle_selection({prompt_bufnr}) *actions.toggle_selection()* + Toggle current entry status for multi select Parameters: ~ - {opts} (table) options to pass to the picker + {prompt_bufnr} (number) The prompt bufnr -builtin.commands({opts}) *builtin.commands()* - Lists available plugin/user commands and runs them on `` +actions.select_all({prompt_bufnr}) *actions.select_all()* + Multi select all entries. + - Note: selected entries may include results not visible in the results + popup. Parameters: ~ - {opts} (table) options to pass to the picker + {prompt_bufnr} (number) The prompt bufnr -builtin.quickfix({opts}) *builtin.quickfix()* - Lists items in the quickfix list, jumps to location on `` +actions.drop_all({prompt_bufnr}) *actions.drop_all()* + Drop all entries from the current multi selection. Parameters: ~ - {opts} (table) options to pass to the picker + {prompt_bufnr} (number) The prompt bufnr -builtin.loclist({opts}) *builtin.loclist()* - Lists items from the current window's location list, jumps to location on - `` +actions.toggle_all({prompt_bufnr}) *actions.toggle_all()* + Toggle multi selection for all entries. + - Note: toggled entries may include results not visible in the results + popup. Parameters: ~ - {opts} (table) options to pass to the picker + {prompt_bufnr} (number) The prompt bufnr -builtin.oldfiles({opts}) *builtin.oldfiles()* - Lists previously open files, opens on `` +actions.git_create_branch({prompt_bufnr}) *actions.git_create_branch()* + Create and checkout a new git branch if it doesn't already exist Parameters: ~ - {opts} (table) options to pass to the picker + {prompt_bufnr} (number) The prompt bufnr -builtin.command_history({opts}) *builtin.command_history()* - Lists commands that were executed recently, and reruns them on `` - - Default keymaps: - - ``: open the command line with the text of the currently selected - result populated in it +actions.git_apply_stash({prompt_bufnr}) *actions.git_apply_stash()* + Applies an existing git stash Parameters: ~ - {opts} (table) options to pass to the picker - + {prompt_bufnr} (number) The prompt bufnr -builtin.search_history({opts}) *builtin.search_history()* - Lists searches that were executed recently, and reruns them on `` - - Default keymaps: - - ``: open a search window with the text of the currently selected - search result populated in it + +actions.git_checkout({prompt_bufnr}) *actions.git_checkout()* + Checkout an existing git branch Parameters: ~ - {opts} (table) options to pass to the picker + {prompt_bufnr} (number) The prompt bufnr -builtin.vim_options({opts}) *builtin.vim_options()* - Lists vim options, allows you to edit the current value on `` +actions.git_switch_branch({prompt_bufnr}) *actions.git_switch_branch()* + Switch to git branch. + If the branch already exists in local, switch to that. If the branch is + only in remote, create new branch tracking remote and switch to new one. Parameters: ~ - {opts} (table) options to pass to the picker + {prompt_bufnr} (number) The prompt bufnr -builtin.help_tags({opts}) *builtin.help_tags()* - Lists available help tags and opens a new window with the relevant help - info on `` +actions.git_track_branch({prompt_bufnr}) *actions.git_track_branch()* + Tell git to track the currently selected remote branch in Telescope Parameters: ~ - {opts} (table) options to pass to the picker + {prompt_bufnr} (number) The prompt bufnr -builtin.man_pages({opts}) *builtin.man_pages()* - Lists manpage entries, opens them in a help window on `` +actions.git_delete_branch({prompt_bufnr}) *actions.git_delete_branch()* + Delete the currently selected branch Parameters: ~ - {opts} (table) options to pass to the picker + {prompt_bufnr} (number) The prompt bufnr -builtin.reloader({opts}) *builtin.reloader()* - Lists lua modules and reloads them on `` +actions.git_rebase_branch({prompt_bufnr}) *actions.git_rebase_branch()* + Rebase to selected git branch Parameters: ~ - {opts} (table) options to pass to the picker + {prompt_bufnr} (number) The prompt bufnr -builtin.buffers({opts}) *builtin.buffers()* - Lists open buffers in current neovim instance, opens selected buffer on - `` +actions.git_staging_toggle({prompt_bufnr}) *actions.git_staging_toggle()* + Stage/unstage selected file Parameters: ~ - {opts} (table) options to pass to the picker + {prompt_bufnr} (number) The prompt bufnr - Fields: ~ - {show_all_buffers} (boolean) if true, show all buffers, including - unloaded buffers (default true) - {ignore_current_buffer} (boolean) if true, don't show the current - buffer in the list (default false) - {only_cwd} (boolean) if true, only show buffers in the - current working directory (default - false) - {sort_lastused} (boolean) if true, sort the shown buffers so - that the last used one is selected - (default false) - {bufnr_width} (number) Defines the width of the buffer - numbers in front of the filenames +actions.send_selected_to_qflist() *actions.send_selected_to_qflist()* + Sends the selected entries to the quickfix list, replacing the previous + entries. -builtin.colorscheme({opts}) *builtin.colorscheme()* - Lists available colorschemes and applies them on `` - Parameters: ~ - {opts} (table) options to pass to the picker +actions.add_selected_to_qflist() *actions.add_selected_to_qflist()* + Adds the selected entries to the quickfix list, keeping the previous + entries. -builtin.marks({opts}) *builtin.marks()* - Lists vim marks and their value, jumps to the mark on `` +actions.send_to_qflist() *actions.send_to_qflist()* + Sends all entries to the quickfix list, replacing the previous entries. - Parameters: ~ - {opts} (table) options to pass to the picker -builtin.registers({opts}) *builtin.registers()* - Lists vim registers, pastes the contents of the register on `` - - Default keymaps: - - ``: edit the contents of the currently selected register +actions.add_to_qflist() *actions.add_to_qflist()* + Adds all entries to the quickfix list, keeping the previous entries. - Parameters: ~ - {opts} (table) options to pass to the picker +actions.send_selected_to_loclist() *actions.send_selected_to_loclist()* + Sends the selected entries to the location list, replacing the previous + entries. -builtin.keymaps({opts}) *builtin.keymaps()* - Lists normal mode keymappings, runs the selected keymap on `` - Parameters: ~ - {opts} (table) options to pass to the picker +actions.add_selected_to_loclist() *actions.add_selected_to_loclist()* + Adds the selected entries to the location list, keeping the previous + entries. -builtin.filetypes({opts}) *builtin.filetypes()* - Lists all available filetypes, sets currently open buffer's filetype to - selected filetype in Telescope on `` +actions.send_to_loclist() *actions.send_to_loclist()* + Sends all entries to the location list, replacing the previous entries. - Parameters: ~ - {opts} (table) options to pass to the picker -builtin.highlights({opts}) *builtin.highlights()* - Lists all available highlights +actions.add_to_loclist() *actions.add_to_loclist()* + Adds all entries to the location list, keeping the previous entries. - Parameters: ~ - {opts} (table) options to pass to the picker +actions.smart_send_to_qflist() *actions.smart_send_to_qflist()* + Sends the selected entries to the quickfix list, replacing the previous + entries. If no entry was selected, sends all entries. -builtin.autocommands({opts}) *builtin.autocommands()* - Lists vim autocommands and goes to their declaration on `` - Parameters: ~ - {opts} (table) options to pass to the picker +actions.smart_add_to_qflist() *actions.smart_add_to_qflist()* + Adds the selected entries to the quickfix list, keeping the previous + entries. If no entry was selected, adds all entries. -builtin.spell_suggest({opts}) *builtin.spell_suggest()* - Lists spelling suggestions for the current word under the cursor, replaces - word with selected suggestion on `` +actions.smart_send_to_loclist() *actions.smart_send_to_loclist()* + Sends the selected entries to the location list, replacing the previous + entries. If no entry was selected, sends all entries. - Parameters: ~ - {opts} (table) options to pass to the picker -builtin.tagstack({opts}) *builtin.tagstack()* - Lists the tag stack for the current window, jumps to tag on `` +actions.smart_add_to_loclist() *actions.smart_add_to_loclist()* + Adds the selected entries to the location list, keeping the previous + entries. If no entry was selected, adds all entries. - Parameters: ~ - {opts} (table) options to pass to the picker +actions.open_qflist() *actions.open_qflist()* + Open the quickfix list -builtin.jumplist({opts}) *builtin.jumplist()* - Lists items from Vim's jumplist, jumps to location on `` - Parameters: ~ - {opts} (table) options to pass to the picker +actions.open_loclist() *actions.open_loclist()* + Open the location list -builtin.lsp_references({opts}) *builtin.lsp_references()* - Lists LSP references for word under the cursor, jumps to reference on - `` + +actions.delete_buffer({prompt_bufnr}) *actions.delete_buffer()* + Delete the selected buffer or all the buffers selected using multi + selection. Parameters: ~ - {opts} (table) options to pass to the picker + {prompt_bufnr} (number) The prompt bufnr -builtin.lsp_definitions({opts}) *builtin.lsp_definitions()* - Goto the definition of the word under the cursor, if there's only one, - otherwise show all options in Telescope +actions.cycle_previewers_next({prompt_bufnr})*actions.cycle_previewers_next()* + Cycle to the next previewer if there is one available. + This action is not mapped on default. Parameters: ~ - {opts} (table) options to pass to the picker + {prompt_bufnr} (number) The prompt bufnr -builtin.lsp_implementations({opts}) *builtin.lsp_implementations()* - Goto the implementation of the word under the cursor if there's only one, - otherwise show all options in Telescope +actions.cycle_previewers_prev({prompt_bufnr})*actions.cycle_previewers_prev()* + Cycle to the previous previewer if there is one available. + This action is not mapped on default. Parameters: ~ - {opts} (table) options to pass to the picker + {prompt_bufnr} (number) The prompt bufnr -builtin.lsp_code_actions({opts}) *builtin.lsp_code_actions()* - Lists any LSP actions for the word under the cursor which can be triggered - with `` +================================================================================ + *telescope.actions.state* - Parameters: ~ - {opts} (table) options to pass to the picker +Functions to be used to determine the current state of telescope. +Generally used from within other |telescope.actions| -builtin.lsp_range_code_actions({opts}) *builtin.lsp_range_code_actions()* - Lists any LSP actions for a given range, that can be triggered with `` +action_state.get_selected_entry() *action_state.get_selected_entry()* + Get the current entry - Parameters: ~ - {opts} (table) options to pass to the picker +action_state.get_current_line() *action_state.get_current_line()* + Gets the current line -builtin.lsp_document_symbols({opts}) *builtin.lsp_document_symbols()* - Lists LSP document symbols in the current buffer - - Default keymaps: - - ``: show autocompletion menu to prefilter your query by type of - symbol you want to see (i.e. `:variable:`) - Parameters: ~ - {opts} (table) options to pass to the picker +action_state.get_current_picker({prompt_bufnr})*action_state.get_current_picker()* + Gets the current picker - Fields: ~ - {ignore_filename} (type) string with file to ignore - {symbols} (string|table) filter results by symbol kind(s) + Parameters: ~ + {prompt_bufnr} (number) The prompt bufnr -builtin.lsp_workspace_symbols({opts}) *builtin.lsp_workspace_symbols()* - Lists LSP document symbols in the current workspace - - Default keymaps: - - ``: show autocompletion menu to prefilter your query by type of - symbol you want to see (i.e. `:variable:`) - Parameters: ~ - {opts} (table) options to pass to the picker +================================================================================ + *telescope.actions.set* - Fields: ~ - {ignore_filename} (string) file(s) to ignore - {symbols} (string|table) filter results by symbol kind(s) +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. -builtin.lsp_dynamic_workspace_symbols({opts})*builtin.lsp_dynamic_workspace_symbols()* - Dynamically lists LSP for all workspace symbols - - Default keymaps: - - ``: show autocompletion menu to prefilter your query by type of - symbol you want to see (i.e. `:variable:`) +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. Parameters: ~ - {opts} (table) options to pass to the picker + {prompt_bufnr} (number) The prompt bufnr + {change} (number) The amount to shift the selection by -builtin.lsp_document_diagnostics({opts}) *builtin.lsp_document_diagnostics()* - Lists LSP diagnostics for the current buffer - - Fields: - - `All severity flags can be passed as `string` or `number` as per - `:vim.lsp.protocol.DiagnosticSeverity:` - - Default keymaps: - - ``: show autocompletion menu to prefilter your query with the - diagnostic you want to see (i.e. `:warning:`) +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: ~ - {opts} (table) options to pass to the picker - Fields: ~ - {severity} (string|number) filter diagnostics by severity name - (string) or id (number) - {severity_limit} (string|number) keep diagnostics equal or more severe - wrt severity name (string) or id - (number) - {severity_bound} (string|number) keep diagnostics equal or less severe - wrt severity name (string) or id - (number) - {no_sign} (bool) hide LspDiagnosticSigns from Results - (default is false) - {line_width} (number) set length of diagnostic entry text - in Results + Parameters: ~ + {prompt_bufnr} (number) The prompt bufnr + {type} (string) The type of selection to make -builtin.lsp_workspace_diagnostics({opts})*builtin.lsp_workspace_diagnostics()* - Lists LSP diagnostics for the current workspace if supported, otherwise - searches in all open buffers - - Fields: - - `All severity flags can be passed as `string` or `number` as per - `:vim.lsp.protocol.DiagnosticSeverity:` - - Default keymaps: - - ``: show autocompletion menu to prefilter your query with the - diagnostic you want to see (i.e. `:warning:`) +action_set.edit({prompt_bufnr}, {command}) *action_set.edit()* + Edit a file based on the current selection. Parameters: ~ - {opts} (table) options to pass to the picker + {prompt_bufnr} (number) The prompt bufnr + {command} (string) The command to use to open the file. - Fields: ~ - {severity} (string|number) filter diagnostics by severity name - (string) or id (number) - {severity_limit} (string|number) keep diagnostics equal or more severe - wrt severity name (string) or id - (number) - {severity_bound} (string|number) keep diagnostics equal or less severe - wrt severity name (string) or id - (number) - {no_sign} (bool) hide LspDiagnosticSigns from Results - (default is false) - {line_width} (number) set length of diagnostic entry text - in Results + +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 @@ -1273,78 +1557,6 @@ utils.map_selections({prompt_bufnr}, {f}) *utils.map_selections()* -================================================================================ - *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.resolve* - -Provides "resolver functions" to allow more customisable inputs for options. - -resolver.resolve_height() *resolver.resolve_height()* - Converts input to a function that returns the height. The input must take - one of four forms: - 1. 0 <= number < 1 - This means total height as a percentage. - 2. 1 <= number - This means total height as a fixed number. - 3. function - Must have signature: function(self, max_columns, max_lines): number - 4. table of the form: {padding = `foo`} - where `foo` has one of the previous three forms. - The height is then set to be the remaining space after padding. For - example, if the window has height 50, and the input is {padding = 5}, - the height returned will be `40 = 50 - 2*5` - - The returned function will have signature: function(self, max_columns, - max_lines): number - - - -resolver.resolve_width() *resolver.resolve_width()* - Converts input to a function that returns the width. The input must take - one of four forms: - 1. 0 <= number < 1 - This means total width as a percentage. - 2. 1 <= number - This means total width as a fixed number. - 3. function - Must have signature: function(self, max_columns, max_lines): number - 4. table of the form: {padding = `foo`} - where `foo` has one of the previous three forms. - The width is then set to be the remaining space after padding. For - example, if the window has width 100, and the input is {padding = 5}, - the width returned will be `90 = 100 - 2*5` - - The returned function will have signature: function(self, max_columns, - max_lines): number - - - - ================================================================================ *telescope.previewers* @@ -1671,183 +1883,108 @@ previewers.display_content() *previewers.display_content()* ================================================================================ - *telescope.layout* + *telescope.actions.history* -Layout strategies are different functions to position telescope. +A base implementation of a prompt history that provides a simple history and +can be replaced with a custom implementation. -All layout strategies are functions with the following signature: +For example: We provide a extension for a smart history that uses sql.nvim to +map histories to metadata, like the calling picker or cwd. - function(picker, columns, lines, layout_config) - -- Do some calculations here... - return { - preview = preview_configuration - results = results_configuration, - prompt = prompt_configuration, - } - end +So you have a history for: +- find_files project_1 +- grep_string project_1 +- live_grep project_1 +- find_files project_2 +- grep_string project_2 +- live_grep project_2 +- etc - Parameters: ~ - - picker : A Picker object. (docs coming soon) - - columns : (number) Columns in the vim window - - lines : (number) Lines in the vim window - - layout_config : (table) The configuration values specific to the picker. +See github.com/nvim-telescope/telescope-smart-history.nvim +histories.History() *histories.History()* + Manages prompt history -This means you can create your own layout strategy if you want! Just be aware -for now that we may change some APIs or interfaces, so they may break if you -create your own. -A good method for creating your own would be to copy one of the strategies that -most resembles what you want from -"./lua/telescope/pickers/layout_strategies.lua" in the telescope repo. + Fields: ~ + {enabled} (boolean) Will indicate if History is enabled or disabled + {path} (string) Will point to the location of the history file + {limit} (string) Will have the limit of the history. Can be nil, if + limit is disabled. + {content} (table) History table. Needs to be filled by your own + History implementation + {index} (number) Used to keep track of the next or previous index. + Default is #content + 1 -layout_strategies.horizontal() *layout_strategies.horizontal()* - Horizontal layout has two columns, one for the preview and one for the - prompt and results. +histories.History:new({opts}) *histories.History:new()* + Create a new History - ┌──────────────────────────────────────────────────┐ - │ │ - │ ┌───────────────────┐┌───────────────────┐ │ - │ │ ││ │ │ - │ │ ││ │ │ - │ │ ││ │ │ - │ │ Results ││ │ │ - │ │ ││ Preview │ │ - │ │ ││ │ │ - │ │ ││ │ │ - │ └───────────────────┘│ │ │ - │ ┌───────────────────┐│ │ │ - │ │ Prompt ││ │ │ - │ └───────────────────┘└───────────────────┘ │ - │ │ - └──────────────────────────────────────────────────┘ - `picker.layout_config` shared options: - - height: - - How tall to make Telescope's entire layout - - See |resolver.resolve_height()| - - mirror: Flip the location of the results/prompt and preview windows - - scroll_speed: The number of lines to scroll through the previewer - - width: - - How wide to make Telescope's entire layout - - See |resolver.resolve_width()| + Parameters: ~ + {opts} (table) Defines the behavior of History - `picker.layout_config` unique options: - - preview_cutoff: When columns are less than this value, the preview will be disabled - - preview_width: - - Change the width of Telescope's preview window - - See |resolver.resolve_width()| - - prompt_position: - - Where to place prompt window. - - Available Values: 'bottom', 'top' + Fields: ~ + {init} (function) Will be called after handling configuration + (required) + {append} (function) How to append a new prompt item (required) + {reset} (function) What happens on reset. Will be called when + telescope closes (required) + {pre_get} (function) Will be called before a next or previous item + will be returned (optional) -layout_strategies.center() *layout_strategies.center()* - Centered layout with a combined block of the prompt and results aligned to - the middle of the screen. The preview window is then placed in the - remaining space above. Particularly useful for creating dropdown menus (see - |telescope.themes| and |themes.get_dropdown()|`). +histories.new() *histories.new()* + Shorthand to create a new history - ┌──────────────────────────────────────────────────┐ - │ ┌────────────────────────────────────────┐ │ - │ | Preview | │ - │ | Preview | │ - │ └────────────────────────────────────────┘ │ - │ ┌────────────────────────────────────────┐ │ - │ | Prompt | │ - │ ├────────────────────────────────────────┤ │ - │ | Result | │ - │ | Result | │ - │ └────────────────────────────────────────┘ │ - │ │ - │ │ - │ │ - │ │ - └──────────────────────────────────────────────────┘ - `picker.layout_config` shared options: - - height: - - How tall to make Telescope's entire layout - - See |resolver.resolve_height()| - - mirror: Flip the location of the results/prompt and preview windows - - scroll_speed: The number of lines to scroll through the previewer - - width: - - How wide to make Telescope's entire layout - - See |resolver.resolve_width()| - `picker.layout_config` unique options: - - preview_cutoff: When lines are less than this value, the preview will be disabled +histories.History:reset() *histories.History:reset()* + Will reset the history index to the default initial state. Will happen + after the picker closed -layout_strategies.vertical() *layout_strategies.vertical()* - Vertical layout stacks the items on top of each other. Particularly useful - with thinner windows. - ┌──────────────────────────────────────────────────┐ - │ │ - │ ┌────────────────────────────────────────┐ │ - │ | Preview | │ - │ | Preview | │ - │ | Preview | │ - │ └────────────────────────────────────────┘ │ - │ ┌────────────────────────────────────────┐ │ - │ | Result | │ - │ | Result | │ - │ └────────────────────────────────────────┘ │ - │ ┌────────────────────────────────────────┐ │ - │ | Prompt | │ - │ └────────────────────────────────────────┘ │ - │ │ - └──────────────────────────────────────────────────┘ +histories.History:append({line}, {picker}, {no_reset})*histories.History:append()* + Append a new line to the history - `picker.layout_config` shared options: - - height: - - How tall to make Telescope's entire layout - - See |resolver.resolve_height()| - - mirror: Flip the location of the results/prompt and preview windows - - scroll_speed: The number of lines to scroll through the previewer - - width: - - How wide to make Telescope's entire layout - - See |resolver.resolve_width()| - `picker.layout_config` unique options: - - preview_cutoff: When lines are less than this value, the preview will be disabled - - preview_height: - - Change the height of Telescope's preview window - - See |resolver.resolve_height()| - - prompt_position: - - (unimplemented, but we plan on supporting) + Parameters: ~ + {line} (string) current line that will be appended + {picker} (table) the current picker object + {no_reset} (boolean) On default it will reset the state at the end. If + you don't want to do this set to true -layout_strategies.flex() *layout_strategies.flex()* - Flex layout swaps between `horizontal` and `vertical` strategies based on - the window width - - Supports |layout_strategies.vertical| or |layout_strategies.horizontal| - features +histories.History:get_next({line}, {picker}) *histories.History:get_next()* + Will return the next history item. Can be nil if there are no next items - `picker.layout_config` shared options: - - height: - - How tall to make Telescope's entire layout - - See |resolver.resolve_height()| - - mirror: Flip the location of the results/prompt and preview windows - - scroll_speed: The number of lines to scroll through the previewer - - width: - - How wide to make Telescope's entire layout - - See |resolver.resolve_width()| + Parameters: ~ + {line} (string) the current line + {picker} (table) the current picker object - `picker.layout_config` unique options: - - flip_columns: The number of columns required to move to horizontal mode - - flip_lines: The number of lines required to move to horizontal mode - - horizontal: Options to pass when switching to horizontal layout - - vertical: Options to pass when switching to vertical layout + Return: ~ + string: the next history item -layout_strategies.bottom_pane() *layout_strategies.bottom_pane()* - Bottom pane can be used to create layouts similar to "ivy". +histories.History:get_prev({line}, {picker}) *histories.History:get_prev()* + Will return the previous history item. Can be nil if there are no previous + items - For an easy ivy configuration, see |themes.get_ivy()| + + Parameters: ~ + {line} (string) the current line + {picker} (table) the current picker object + + Return: ~ + string: the previous history item + + +histories.get_simple_history() *histories.get_simple_history()* + A simple implementation of history. + + It will keep one unified history across all pickers. diff --git a/lua/telescope/actions/history.lua b/lua/telescope/actions/history.lua new file mode 100644 index 0000000..8ec58e2 --- /dev/null +++ b/lua/telescope/actions/history.lua @@ -0,0 +1,186 @@ +local conf = require('telescope.config').values +local Path = require('plenary.path') + +local uv = vim.loop + +---@brief [[ +--- A base implementation of a prompt history that provides a simple history +--- and can be replaced with a custom implementation. +--- +--- For example: We provide a extension for a smart history that uses sql.nvim +--- to map histories to metadata, like the calling picker or cwd. +--- +--- So you have a history for: +--- - find_files project_1 +--- - grep_string project_1 +--- - live_grep project_1 +--- - find_files project_2 +--- - grep_string project_2 +--- - live_grep project_2 +--- - etc +--- +--- See github.com/nvim-telescope/telescope-smart-history.nvim +---@brief ]] +---@tag telescope.actions.history + +-- TODO(conni2461): currently not present in plenary path only sync. +-- But sync is just unnecessary here +local write_async = function(path, txt, flag) + uv.fs_open(path, flag, 438, function(open_err, fd) + assert(not open_err, open_err) + uv.fs_write(fd, txt, -1, function(write_err) + assert(not write_err, write_err) + uv.fs_close(fd, function(close_err) + assert(not close_err, close_err) + end) + end) + end) +end + +local append_async = function(path, txt) write_async(path, txt, "a") end + +local histories = {} + +--- Manages prompt history +---@class History @Manages prompt history +---@field enabled boolean: Will indicate if History is enabled or disabled +---@field path string: Will point to the location of the history file +---@field limit string: Will have the limit of the history. Can be nil, if limit is disabled. +---@field content table: History table. Needs to be filled by your own History implementation +---@field index number: Used to keep track of the next or previous index. Default is #content + 1 +histories.History = {} +histories.History.__index = histories.History + +--- Create a new History +---@param opts table: Defines the behavior of History +---@field init function: Will be called after handling configuration (required) +---@field append function: How to append a new prompt item (required) +---@field reset function: What happens on reset. Will be called when telescope closes (required) +---@field pre_get function: Will be called before a next or previous item will be returned (optional) +function histories.History:new(opts) + local obj = {} + if not conf.history or type(conf.history) ~= "table" then + obj.enabled = false + return setmetatable(obj, self) + end + obj.enabled = true + if conf.history.limit then + obj.limit = conf.history.limit + end + obj.path = vim.fn.expand(conf.history.path) + obj.content = {} + obj.index = 1 + + opts.init(obj) + obj._reset = opts.reset + obj._append = opts.append + obj._pre_get = opts.pre_get + + return setmetatable(obj, self) +end + +--- Shorthand to create a new history +function histories.new(...) + return histories.History:new(...) +end + +--- Will reset the history index to the default initial state. Will happen after the picker closed +function histories.History:reset() + if not self.enabled then return end + self._reset(self) +end + +--- Append a new line to the history +---@param line string: current line that will be appended +---@param picker table: the current picker object +---@param no_reset boolean: On default it will reset the state at the end. If you don't want to do this set to true +function histories.History:append(line, picker, no_reset) + if not self.enabled then return end + self._append(self, line, picker, no_reset) +end + +--- Will return the next history item. Can be nil if there are no next items +---@param line string: the current line +---@param picker table: the current picker object +---@return string: the next history item +function histories.History:get_next(line, picker) + if not self.enabled then + print("You are cycling to next the history item but history is disabled.", + "Read ':help telescope.defaults.history'") + return false + end + if self._pre_get then self._pre_get(self, line, picker) end + + local next_idx = self.index + 1 + if next_idx <= #self.content then + self.index = next_idx + return self.content[next_idx] + end + self.index = #self.content + 1 + return nil +end + +--- Will return the previous history item. Can be nil if there are no previous items +---@param line string: the current line +---@param picker table: the current picker object +---@return string: the previous history item +function histories.History:get_prev(line, picker) + if not self.enabled then + print("You are cycling to previous the history item but history is disabled.", + "Read ':help telescope.defaults.history'") + return false + end + if self._pre_get then self._pre_get(self, line, picker) end + + local next_idx = self.index - 1 + if self.index == #self.content + 1 then + if line ~= '' then self:append(line, picker, true) end + end + if next_idx >= 1 then + self.index = next_idx + return self.content[next_idx] + end + return nil +end + +--- A simple implementation of history. +--- +--- It will keep one unified history across all pickers. +histories.get_simple_history = function() + return histories.new({ + init = function(obj) + local p = Path:new(obj.path) + if not p:exists() then p:touch({ parents = true }) end + + obj.content = Path:new(obj.path):readlines() + obj.index = #obj.content + table.remove(obj.content, obj.index) + end, + reset = function(self) + self.index = #self.content + 1 + end, + append = function(self, line, _, no_reset) + if line ~= '' then + if self.content[#self.content] ~= line then + table.insert(self.content, line) + + local len = #self.content + if self.limit and len > self.limit then + local diff = len - self.limit + for i = diff, 1, -1 do + table.remove(self.content, i) + end + write_async(self.path, table.concat(self.content, '\n') .. '\n', 'w') + else + append_async(self.path, line .. '\n') + end + end + end + if not no_reset then + self:reset() + end + end, + }) +end + +return histories diff --git a/lua/telescope/actions/init.lua b/lua/telescope/actions/init.lua index bf45bb3..8ca96c7 100644 --- a/lua/telescope/actions/init.lua +++ b/lua/telescope/actions/init.lua @@ -196,21 +196,53 @@ function actions.center(_) vim.cmd(':normal! zz') end -function actions.select_default(prompt_bufnr) - return action_set.select(prompt_bufnr, "default") -end +actions.select_default = { + pre = function(prompt_bufnr) + action_state.get_current_history():append( + action_state.get_current_line(), + action_state.get_current_picker(prompt_bufnr) + ) + end, + action = function(prompt_bufnr) + return action_set.select(prompt_bufnr, "default") + end +} -function actions.select_horizontal(prompt_bufnr) - return action_set.select(prompt_bufnr, "horizontal") -end +actions.select_horizontal = { + pre = function(prompt_bufnr) + action_state.get_current_history():append( + action_state.get_current_line(), + action_state.get_current_picker(prompt_bufnr) + ) + end, + action = function(prompt_bufnr) + return action_set.select(prompt_bufnr, "horizontal") + end +} -function actions.select_vertical(prompt_bufnr) - return action_set.select(prompt_bufnr, "vertical") -end +actions.select_vertical = { + pre = function(prompt_bufnr) + action_state.get_current_history():append( + action_state.get_current_line(), + action_state.get_current_picker(prompt_bufnr) + ) + end, + action = function(prompt_bufnr) + return action_set.select(prompt_bufnr, "vertical") + end +} -function actions.select_tab(prompt_bufnr) - return action_set.select(prompt_bufnr, "tab") -end +actions.select_tab = { + pre = function(prompt_bufnr) + action_state.get_current_history():append( + action_state.get_current_line(), + action_state.get_current_picker(prompt_bufnr) + ) + end, + action = function(prompt_bufnr) + return action_set.select(prompt_bufnr, "tab") + end +} -- TODO: consider adding float! -- https://github.com/nvim-telescope/telescope.nvim/issues/365 @@ -238,6 +270,7 @@ function actions.close_pum(_) end actions._close = function(prompt_bufnr, keepinsert) + action_state.get_current_history():reset() local picker = action_state.get_current_picker(prompt_bufnr) local prompt_win = state.get_status(prompt_bufnr).prompt_win local original_win_id = picker.original_win_id @@ -695,6 +728,33 @@ actions.complete_tag = function(prompt_bufnr) end +actions.cycle_history_next = function(prompt_bufnr) + local history = action_state.get_current_history() + local current_picker = actions.get_current_picker(prompt_bufnr) + local line = action_state.get_current_line() + + local entry = history:get_next(line, current_picker) + if entry == false then return end + + current_picker:reset_prompt() + if entry ~= nil then + current_picker:set_prompt(entry) + end +end + +actions.cycle_history_prev = function(prompt_bufnr) + local history = action_state.get_current_history() + local current_picker = actions.get_current_picker(prompt_bufnr) + local line = action_state.get_current_line() + + local entry = history:get_prev(line, current_picker) + if entry == false then return end + if entry ~= nil then + current_picker:reset_prompt() + current_picker:set_prompt(entry) + end +end + --- Open the quickfix list actions.open_qflist = function(_) vim.cmd [[copen]] diff --git a/lua/telescope/actions/mt.lua b/lua/telescope/actions/mt.lua index 5efeddf..7f233cf 100644 --- a/lua/telescope/actions/mt.lua +++ b/lua/telescope/actions/mt.lua @@ -19,6 +19,9 @@ action_mt.create = function(mod) __call = function(t, ...) local values = {} for _, action_name in ipairs(t) do + if t._static_pre[action_name] then + t._static_pre[action_name](...) + end if t._pre[action_name] then t._pre[action_name](...) end @@ -34,6 +37,9 @@ action_mt.create = function(mod) table.insert(values, res) end + if t._static_post[action_name] then + t._static_post[action_name](...) + end if t._post[action_name] then t._post[action_name](...) end @@ -55,8 +61,10 @@ action_mt.create = function(mod) return setmetatable(new_actions, getmetatable(lhs)) end, + _static_pre = {}, _pre = {}, _replacements = {}, + _static_post = {}, _post = {}, } @@ -119,8 +127,14 @@ action_mt.create = function(mod) return mt end -action_mt.transform = function(k, mt) - return setmetatable({k}, mt) +action_mt.transform = function(k, mt, mod, v) + local res = setmetatable({k}, mt) + if type(v) == "table" then + res._static_pre[k] = v.pre + res._static_post[k] = v.post + mod[k] = v.action + end + return res end action_mt.transform_mod = function(mod) @@ -130,8 +144,8 @@ action_mt.transform_mod = function(mod) -- This allows for custom errors, lookups, etc. local redirect = setmetatable({}, getmetatable(mod) or {}) - for k, _ in pairs(mod) do - redirect[k] = action_mt.transform(k, mt) + for k, v in pairs(mod) do + redirect[k] = action_mt.transform(k, mt, mod, v) end redirect._clear = mt.clear diff --git a/lua/telescope/actions/set.lua b/lua/telescope/actions/set.lua index 5b39c54..e790e34 100644 --- a/lua/telescope/actions/set.lua +++ b/lua/telescope/actions/set.lua @@ -48,6 +48,20 @@ action_set.select = function(prompt_bufnr, type) return action_set.edit(prompt_bufnr, action_state.select_key_to_edit_key(type)) end +-- goal: currently we have a workaround in actions/init.lua where we do this for all files +-- action_set.select = { +-- -- Will not be called if `select_default` is replaced rather than `action_set.select` because we never get here +-- pre = function(prompt_bufnr) +-- action_state.get_current_history():append( +-- action_state.get_current_line(), +-- action_state.get_current_picker(prompt_bufnr) +-- ) +-- end, +-- action = function(prompt_bufnr, type) +-- return action_set.edit(prompt_bufnr, action_state.select_key_to_edit_key(type)) +-- end +-- } + local edit_buffer do local map = { diff --git a/lua/telescope/actions/state.lua b/lua/telescope/actions/state.lua index 7ef9f6c..8470f2d 100644 --- a/lua/telescope/actions/state.lua +++ b/lua/telescope/actions/state.lua @@ -7,6 +7,7 @@ ---@brief ]] local global_state = require('telescope.state') +local conf = require('telescope.config').values local action_state = {} @@ -36,4 +37,19 @@ function action_state.select_key_to_edit_key(type) return select_to_edit_map[type] end +function action_state.get_current_history() + local history = global_state.get_global_key("history") + if not history then + if not conf.history or type(conf.history) ~= "table" then + history = require('telescope.actions.history').get_simple_history() + global_state.set_global_key("history", history) + else + history = conf.history.handler() + global_state.set_global_key("history", history) + end + end + + return history +end + return action_state diff --git a/lua/telescope/config.lua b/lua/telescope/config.lua index dd3d453..00d4101 100644 --- a/lua/telescope/config.lua +++ b/lua/telescope/config.lua @@ -2,6 +2,7 @@ local strings = require "plenary.strings" local deprecated = require "telescope.deprecated" local sorters = require "telescope.sorters" local if_nil = vim.F.if_nil +local os_sep = require("plenary.path").path.sep -- Keep the values around between reloads _TelescopeConfigurationValues = _TelescopeConfigurationValues or {} @@ -206,15 +207,48 @@ local telescope_defaults = { end, }, - dynamic_preview_title = { - 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 - ]], + 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 either false or nil. + + Currently mappings still need to be added, Example: + mappings = { + i = { + [""] = require('telescope.actions').cycle_history_next, + [""] = 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 + ]], + }, -- Builtin configuration @@ -346,6 +380,16 @@ function config.set_defaults(user_defaults, tele_defaults) vim.tbl_deep_extend("keep", if_nil(config.values[name], {}), if_nil(default_val, {})) ) end + if name == "history" then + if not user_defaults[name] or not config.values[name] then + return false + end + + return smarter_depth_2_extend( + if_nil(user_defaults[name], {}), + vim.tbl_deep_extend("keep", if_nil(config.values[name], {}), if_nil(default_val, {})) + ) + end return first_non_null(user_defaults[name], config.values[name], default_val) end diff --git a/lua/telescope/pickers.lua b/lua/telescope/pickers.lua index a60d2df..449d869 100644 --- a/lua/telescope/pickers.lua +++ b/lua/telescope/pickers.lua @@ -473,7 +473,7 @@ function Picker:find() pcall(a.nvim_buf_set_option, prompt_bufnr, 'filetype', 'TelescopePrompt') if self.default_text then - vim.api.nvim_buf_set_lines(prompt_bufnr, 0, 1, false, {self.default_text}) + self:set_prompt(self.default_text) end if self.initial_mode == "insert" then @@ -544,6 +544,11 @@ function Picker:delete_selection(delete_cb) end) end +function Picker:set_prompt(str) + -- TODO(conni2461): As soon as prompt_buffers are fix use this: + -- vim.api.nvim_buf_set_lines(self.prompt_bufnr, 0, 1, false, { str }) + vim.api.nvim_feedkeys(str, 'n', false) +end function Picker.close_windows(status) local prompt_win = status.prompt_win diff --git a/scripts/gendocs.lua b/scripts/gendocs.lua index 1533bd5..5f04727 100644 --- a/scripts/gendocs.lua +++ b/scripts/gendocs.lua @@ -11,20 +11,17 @@ docs.test = function() local input_files = { "./lua/telescope/init.lua", "./lua/telescope/builtin/init.lua", + "./lua/telescope/themes.lua", "./lua/telescope/pickers/layout_strategies.lua", + "./lua/telescope/config/resolve.lua", "./lua/telescope/actions/init.lua", "./lua/telescope/actions/state.lua", "./lua/telescope/actions/set.lua", "./lua/telescope/actions/utils.lua", "./lua/telescope/previewers/init.lua", - "./lua/telescope/config/resolve.lua", - "./lua/telescope/themes.lua", + "./lua/telescope/actions/history.lua", } - table.sort(input_files, function(a, b) - return #a < #b - end) - local output_file = "./doc/telescope.txt" local output_file_handle = io.open(output_file, "w") -- cgit v1.2.3