Consistent filepath display and code cleanup. (#839)

BREAKING CHANGE: see :help telescope.changelog-839 for more information

Co-authored-by: Simon Hauser <Simon-Hauser@outlook.de>

2 files changed, 60 insertions, 36 deletions

diff --git a/doc/telescope.txt b/doc/telescope.txt
index b3f0956..6c932be 100644
--- a/doc/telescope.txt
+++ b/doc/telescope.txt
@@ -114,13 +114,15 @@ telescope.setup({opts})                                    *telescope.setup()*
           Into your config.
 
 
-        otherwise, just set the mapping to the function that you want it to be.
+        otherwise, just set the mapping to the function that you want it to
+        be.
 
             ...,
             ["<C-i>"] = require('telescope.actions').select_default,
             ...,
 
-        If the function you want is part of `telescope.actions`, then you can simply give a string.
+        If the function you want is part of `telescope.actions`, then you can
+        simply give a string.
           For example, the previous option is equivalent to:
 
             ...,
@@ -136,6 +138,21 @@ telescope.setup({opts})                                    *telescope.setup()*
             ...,
 
 
+                                          *telescope.defaults.path_display*
+    path_display: ~
+        Determines how file paths are displayed
+
+        path_display can be set to an array with a combination of:
+        - "hidden"    hide file names
+        - "tail"      only display the file name, and not the path
+        - "absolute"  display absolute paths
+        - "shorten"   only display the first character of each directory in
+                      the path
+
+        path_display can also be set to 'hidden' string to hide file names
+
+        Default: {}
+
                                          *telescope.defaults.prompt_prefix*
     prompt_prefix: ~
         Will be shown in front of the prompt.
@@ -728,14 +745,9 @@ builtin.tags({opts})                                          *builtin.tags()*
         {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)
-        {shorten_path}  (boolean)  if true, makes file paths shown in picker
-                                   use one letter for folders (default is true)
-        {hide_filename} (boolean)  if true, hides the name of the file in the
-                                   current picker (default is false)
+        {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)
 
 
 builtin.current_buffer_tags({opts})            *builtin.current_buffer_tags()*
@@ -1045,12 +1057,6 @@ builtin.tagstack({opts})                                  *builtin.tagstack()*
     Parameters: ~
         {opts} (table)  options to pass to the picker
 
-    Fields: ~
-        {shorten_path}  (boolean)  if true, makes file paths shown in picker
-                                   use one letter for folders (default is true)
-        {hide_filename} (boolean)  if true, hides the name of the file in the
-                                   current picker (default is true)
-
 
 builtin.jumplist({opts})                                  *builtin.jumplist()*
     Lists items from Vim's jumplist, jumps to location on `<cr>`
@@ -1068,10 +1074,6 @@ builtin.lsp_references({opts})                      *builtin.lsp_references()*
     Parameters: ~
         {opts} (table)  options to pass to the picker
 
-    Fields: ~
-        {shorten_path} (boolean)  if true, makes file paths shown in picker use
-                                  one letter for folders (default is false)
-
 
 builtin.lsp_definitions({opts})                    *builtin.lsp_definitions()*
     Goto the definition of the word under the cursor, if there's only one,
@@ -1134,13 +1136,7 @@ builtin.lsp_workspace_symbols({opts})        *builtin.lsp_workspace_symbols()*
         {opts} (table)  options to pass to the picker
 
     Fields: ~
-        {shorten_path}    (boolean)       if true, makes file paths shown in
-                                          picker use one letter for folders
-                                          (default is false)
         {ignore_filename} (string)        file(s) to ignore
-        {hide_filename}   (boolean)       if true, hides the name of the file
-                                          in the current picker (default is
-                                          false)
         {symbols}         (string|table)  filter results by symbol kind(s)
 
 
@@ -1154,10 +1150,6 @@ builtin.lsp_dynamic_workspace_symbols({opts})*builtin.lsp_dynamic_workspace_symb
     Parameters: ~
         {opts} (table)  options to pass to the picker
 
-    Fields: ~
-        {hide_filename} (boolean)  if true, hides the name of the file in the
-                                   current picker (default is false)
-
 
 builtin.lsp_document_diagnostics({opts})  *builtin.lsp_document_diagnostics()*
     Lists LSP diagnostics for the current buffer
@@ -1173,9 +1165,6 @@ builtin.lsp_document_diagnostics({opts})  *builtin.lsp_document_diagnostics()*
         {opts} (table)  options to pass to the picker
 
     Fields: ~
-        {hide_filename}  (boolean)        if true, hides the name of the file
-                                          in the current picker (default is
-                                          false)
         {severity}       (string|number)  filter diagnostics by severity name
                                           (string) or id (number)
         {severity_limit} (string|number)  keep diagnostics equal or more severe
@@ -1205,9 +1194,6 @@ builtin.lsp_workspace_diagnostics({opts})*builtin.lsp_workspace_diagnostics()*
         {opts} (table)  options to pass to the picker
 
     Fields: ~
-        {hide_filename}  (boolean)        if true, hides the name of the file
-                                          in the current picker (default is
-                                          false)
         {severity}       (string|number)  filter diagnostics by severity name
                                           (string) or id (number)
         {severity_limit} (string|number)  keep diagnostics equal or more severe
diff --git a/doc/telescope_changelog.txt b/doc/telescope_changelog.txt
index 5b255f7..b0c55fa 100644
--- a/doc/telescope_changelog.txt
+++ b/doc/telescope_changelog.txt
@@ -47,5 +47,43 @@ better.
 
     You should get error messages when you try and use any of the above keys now.
 
+                                                     *telescope.changelog-839*
+
+Date: July 7, 2021
+PR: https://github.com/nvim-telescope/telescope.nvim/pull/839
+
+Small breaking change regarding `shorten_path` and `hide_filename`.
+This allows to configure path displays on a global level and offers a way for
+extension developers to make use of the same configuration, offering a better
+overall experience.
+
+The new way to configure to configure path displays is with:
+    `path_display`: It is a table and accepts multiple values:
+        - "hidden"    hide file names
+        - "tail"      only display the file name, and not the path
+        - "absolute"  display absolute paths
+        - "shorten"   only display the first character of each directory in
+                      the path
+    see |telescope.defaults.path_display|
+
+Example would be for a global configuration:
+  require("telescope").setup{
+    defaults = {
+      path_display = {
+        "shorten_path",
+        "absolute",
+      },
+    }
+  }
+
+You can also still pass this to a single builtin call:
+    require("telescope.builtin").find_files {
+      path_display = { "shorten_path" }
+    }
+
+For extension developers there is a new util function that can be used to
+display a path:
+    local filename = utils.transform_path(opts, entry.filename)
+
 
  vim:tw=78:ts=8:ft=help:norl: