feat: allow caching and resuming picker (#1051)

* expose `cache_picker` in telescope.setup to configure caching, see `:h telescope.defaults.cache_picker`
* add builtin.resume and builtin.pickers picker

lua/telescope/builtin/init.lua

@@ -68,7 +68,7 @@ local builtin = {}
 
 --- Search for a string and get results live as you type (respecting .gitignore)
 ---@param opts table: options to pass to the picker
----@field cwd string: directory path to search from (default is cwd, use utils.buffer_dir() to search relative to open buffer)
+---@field cwd string: root dir to search from (default is cwd, use utils.buffer_dir() to search relative to open buffer)
 ---@field grep_open_files boolean: if true, restrict search to open files only, mutually exclusive with `search_dirs`
 ---@field search_dirs table: directory/directories to search in, mutually exclusive with `grep_open_files`
 ---@field additional_args function: function(opts) which returns a table of additional arguments to be passed on
@@ -76,7 +76,7 @@ builtin.live_grep = require("telescope.builtin.files").live_grep
 
 --- Searches for the string under your cursor in your current working directory
 ---@param opts table: options to pass to the picker
----@field cwd string: directory path to search from (default is cwd, use utils.buffer_dir() to search relative to open buffer)
+---@field cwd string: root dir to search from (default is cwd, use utils.buffer_dir() to search relative to open buffer)
 ---@field search string: the query to search
 ---@field search_dirs table: directory/directories to search in
 ---@field use_regex boolean: if true, special characters won't be escaped, allows for using regex (default is false)
@@ -85,7 +85,7 @@ builtin.grep_string = require("telescope.builtin.files").grep_string
 
 --- Search for files (respecting .gitignore)
 ---@param opts table: options to pass to the picker
----@field cwd string: directory path to search from (default is cwd, use utils.buffer_dir() to search relative to open buffer)
+---@field cwd string: root dir to search from (default is cwd, use utils.buffer_dir() to search relative to open buffer)
 ---@field find_command table: command line arguments for `find_files` to use for the search, overrides default config
 ---@field follow boolean: if true, follows symlinks (i.e. uses `-L` flag for the `find` command)
 ---@field hidden boolean: determines whether to show hidden files or not (default is false)
@@ -105,7 +105,7 @@ builtin.fd = builtin.find_files
 ---       create the file `init.lua` inside of `lua/telescope` and will create the necessary folders (similar to how
 ---       `mkdir -p` would work) if they do not already exist
 ---@param opts table: options to pass to the picker
----@field cwd string: directory path to browse (default is cwd, use utils.buffer_dir() to browse relative to open buffer)
+---@field cwd string: root dir to browse from (default is cwd, use utils.buffer_dir() to search relative to open buffer)
 ---@field depth number: file tree depth to display (default is 1)
 ---@field dir_icon string: change the icon for a directory. default: 
 ---@field hidden boolean: determines whether to show hidden files or not (default is false)
@@ -243,6 +243,21 @@ builtin.command_history = require("telescope.builtin.internal").command_history
 ---@param opts table: options to pass to the picker
 builtin.search_history = require("telescope.builtin.internal").search_history
 
+--- Opens the previous picker in the identical state (incl. multi selections)
+--- - Notes:
+---   - Requires `cache_picker` in setup or when having invoked pickers, see |telescope.defaults.cache_picker|
+---@param opts table: options to pass to the picker
+---@field cache_index number: what picker to resume, where 1 denotes most recent (default 1)
+builtin.resume = require("telescope.builtin.internal").resume
+
+--- Opens a picker over previously cached pickers in there preserved states (incl. multi selections)
+--- - Default keymaps:
+---   - `<C-x>`: delete the selected cached picker
+--- - Notes:
+---   - Requires `cache_picker` in setup or when having invoked pickers, see |telescope.defaults.cache_picker|
+---@param opts table: options to pass to the picker
+builtin.pickers = require("telescope.builtin.internal").pickers
+
 --- Lists vim options, allows you to edit the current value on `<cr>`
 ---@param opts table: options to pass to the picker
 builtin.vim_options = require("telescope.builtin.internal").vim_options

lua/telescope/builtin/internal.lua

@@ -6,7 +6,9 @@ local make_entry = require "telescope.make_entry"
 local Path = require "plenary.path"
 local pickers = require "telescope.pickers"
 local previewers = require "telescope.previewers"
+local p_window = require "telescope.pickers.window"
 local sorters = require "telescope.sorters"
+local state = require "telescope.state"
 local utils = require "telescope.utils"
 
 local conf = require("telescope.config").values
@@ -71,6 +73,80 @@ internal.builtin = function(opts)
   }):find()
 end
 
+internal.resume = function(opts)
+  opts = opts or {}
+  opts.cache_index = vim.F.if_nil(opts.cache_index, 1)
+
+  local cached_pickers = state.get_global_key "cached_pickers"
+  if cached_pickers == nil or vim.tbl_isempty(cached_pickers) then
+    print "No picker(s) cached."
+    return
+  end
+  local picker = cached_pickers[opts.cache_index]
+  if picker == nil then
+    print("Index too large as there are only %s pickers cached", #cached_pickers)
+    return
+  end
+  -- reset layout strategy and get_window_options if default as only one is valid
+  -- and otherwise unclear which was actually set
+  if picker.layout_strategy == conf.layout_strategy then
+    picker.layout_strategy = nil
+  end
+  if picker.get_window_options == p_window.get_window_options then
+    picker.get_window_options = nil
+  end
+  picker.cache_picker.index = opts.cache_index
+
+  -- avoid partial `opts.cache_picker` at picker creation
+  if opts.cache_picker ~= false then
+    picker.cache_picker = vim.tbl_extend("keep", opts.cache_picker or {}, picker.cache_picker)
+  else
+    picker.cache_picker.disabled = true
+  end
+  opts.cache_picker = nil
+  pickers.new(opts, picker):find()
+end
+
+internal.pickers = function(opts)
+  local cached_pickers = state.get_global_key "cached_pickers"
+  if cached_pickers == nil or vim.tbl_isempty(cached_pickers) then
+    print "No picker(s) cached."
+    return
+  end
+
+  opts = opts or {}
+
+  -- clear cache picker for immediate pickers.new and pass option to resumed picker
+  if opts.cache_picker ~= nil then
+    opts._cache_picker = opts.cache_picker
+    opts.cache_picker = nil
+  end
+
+  pickers.new(opts, {
+    prompt_title = "Pickers",
+    finder = finders.new_table {
+      results = cached_pickers,
+      entry_maker = make_entry.gen_from_picker(opts),
+    },
+    previewer = previewers.pickers.new(opts),
+    sorter = conf.generic_sorter(opts),
+    cache_picker = false,
+    attach_mappings = function(_, map)
+      actions.select_default:replace(function(prompt_bufnr)
+        local current_picker = action_state.get_current_picker(prompt_bufnr)
+        local selection_index = current_picker:get_index(current_picker:get_selection_row())
+        actions._close(prompt_bufnr, cached_pickers[selection_index].initial_mode == "insert")
+        opts.cache_picker = opts._cache_picker
+        opts["cache_index"] = selection_index
+        internal.resume(opts)
+      end)
+      map("i", "<C-x>", actions.remove_selected_picker)
+      map("n", "<C-x>", actions.remove_selected_picker)
+      return true
+    end,
+  }):find()
+end
+
 internal.planets = function(opts)
   local show_pluto = opts.show_pluto or false