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

1 files changed, 70 insertions, 9 deletions

diff --git a/doc/telescope.txt b/doc/telescope.txt
index 8fedd6c..fc36ca5 100644
--- a/doc/telescope.txt
+++ b/doc/telescope.txt
@@ -25,6 +25,28 @@ telescope.setup({opts})                                    *telescope.setup()*
 
         Default: true
 
+                                          *telescope.defaults.cache_picker*
+    cache_picker: ~
+        This field handles the configuration for picker caching.
+        By default it is a table, with default values (more below).
+        To disable caching, set it to false.
+
+        Caching preserves all previous multi selections and results and
+        therefore may result in slowdown or increased RAM occupation
+        if too many pickers (`cache_picker.num_pickers`) or entries
+        ('cache_picker.limit_entries`) are cached.
+
+        Fields:
+          - num_pickers:      The number of pickers to be cached.
+                              Set to -1 to preserve all pickers of your session.
+                              If passed to a picker, the cached pickers with
+                              indices larger than `cache_picker.num_pickers` will
+                              be cleared.
+                              Default: 1
+          - limit_entries:    The amount of entries that will be written in the
+                              Default: 1000
+
+
                                       *telescope.defaults.default_mappings*
     default_mappings: ~
         Not recommended to use except for advanced users.
@@ -367,8 +389,8 @@ builtin.live_grep({opts})                                *builtin.live_grep()*
         {opts} (table)  options to pass to the picker
 
     Fields: ~
-        {cwd}             (string)    directory path to search from (default
-                                      is cwd, use utils.buffer_dir() to search
+        {cwd}             (string)    root dir to search from (default is cwd,
+                                      use utils.buffer_dir() to search
                                       relative to open buffer)
         {grep_open_files} (boolean)   if true, restrict search to open files
                                       only, mutually exclusive with
@@ -388,8 +410,8 @@ builtin.grep_string({opts})                            *builtin.grep_string()*
         {opts} (table)  options to pass to the picker
 
     Fields: ~
-        {cwd}             (string)    directory path to search from (default
-                                      is cwd, use utils.buffer_dir() to search
+        {cwd}             (string)    root dir to search from (default is cwd,
+                                      use utils.buffer_dir() to search
                                       relative to open buffer)
         {search}          (string)    the query to search
         {search_dirs}     (table)     directory/directories to search in
@@ -408,9 +430,9 @@ builtin.find_files({opts})                              *builtin.find_files()*
         {opts} (table)  options to pass to the picker
 
     Fields: ~
-        {cwd}          (string)   directory path to search from (default is
-                                  cwd, use utils.buffer_dir() to search
-                                  relative to open buffer)
+        {cwd}          (string)   root dir to search from (default is cwd, use
+                                  utils.buffer_dir() to search relative to
+                                  open buffer)
         {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`
@@ -446,8 +468,8 @@ builtin.file_browser({opts})                          *builtin.file_browser()*
         {opts} (table)  options to pass to the picker
 
     Fields: ~
-        {cwd}      (string)   directory path to browse (default is cwd, use
-                              utils.buffer_dir() to browse relative to open
+        {cwd}      (string)   root dir to browse from (default is cwd, use
+                              utils.buffer_dir() to search relative to open
                               buffer)
         {depth}    (number)   file tree depth to display (default is 1)
         {dir_icon} (string)   change the icon for a directory. default: 
@@ -679,6 +701,35 @@ builtin.search_history({opts})                      *builtin.search_history()*
         {opts} (table)  options to pass to the picker
 
 
+builtin.resume({opts})                                      *builtin.resume()*
+    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|
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+    Fields: ~
+        {cache_index} (number)  what picker to resume, where 1 denotes most
+                                recent (default 1)
+
+
+builtin.pickers({opts})                                    *builtin.pickers()*
+    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|
+
+
+    Parameters: ~
+        {opts} (table)  options to pass to the picker
+
+
 builtin.vim_options({opts})                            *builtin.vim_options()*
     Lists vim options, allows you to edit the current value on `<cr>`
 
@@ -1582,6 +1633,16 @@ actions.cycle_previewers_prev({prompt_bufnr})*actions.cycle_previewers_prev()*
         {prompt_bufnr} (number)  The prompt bufnr
 
 
+actions.remove_selected_picker({prompt_bufnr})*actions.remove_selected_picker()*
+    Removes the selected picker in |builtin.pickers|.
+    This action is not mapped by default and only intended for
+    |builtin.pickers|.
+
+
+    Parameters: ~
+        {prompt_bufnr} (number)  The prompt bufnr
+
+
 
 ================================================================================
                                                        *telescope.actions.state*