Merge pull request #1945 from nvim-telescope/dev

full changelog `:help telescope.changelog-1945`

1 files changed, 25 insertions, 3 deletions

diff --git a/lua/telescope/utils.lua b/lua/telescope/utils.lua
index 2a8de58..356d102 100644
--- a/lua/telescope/utils.lua
+++ b/lua/telescope/utils.lua
@@ -1,3 +1,10 @@
+---@tag telescope.utils
+---@config { ["module"] = "telescope.utils" }
+
+---@brief [[
+--- Utilities for writing telescope pickers
+---@brief ]]
+
 local Path = require "plenary.path"
 local Job = require "plenary.job"
 
@@ -13,6 +20,7 @@ utils.get_separator = function()
 end
 
 utils.if_nil = function(x, was_nil, was_not_nil)
+  log.error "telescope.utils.if_nil is deprecated and will be removed. Please use vim.F.if_nil"
   if x == nil then
     return was_nil
   else
@@ -21,6 +29,7 @@ utils.if_nil = function(x, was_nil, was_not_nil)
 end
 
 utils.get_default = function(x, default)
+  log.error "telescope.utils.get_default is deprecated and will be removed. Please use vim.F.if_nil"
   return utils.if_nil(x, default, x)
 end
 
@@ -191,7 +200,7 @@ utils.path_tail = (function()
 end)()
 
 utils.is_path_hidden = function(opts, path_display)
-  path_display = path_display or utils.get_default(opts.path_display, require("telescope.config").values.path_display)
+  path_display = path_display or vim.F.if_nil(opts.path_display, require("telescope.config").values.path_display)
 
   return path_display == nil
     or path_display == "hidden"
@@ -210,6 +219,16 @@ local calc_result_length = function(truncate_len)
   return type(truncate_len) == "number" and len - truncate_len or len
 end
 
+--- Transform path is a util function that formats a path based on path_display
+--- found in `opts` or the default value from config.
+--- It is meant to be used in make_entry to have a uniform interface for
+--- builtins as well as extensions utilizing the same user configuration
+--- Note: It is only supported inside `make_entry`/`make_display` the use of
+--- this function outside of telescope might yield to undefined behavior and will
+--- not be addressed by us
+---@param opts table: The opts the users passed into the picker. Might contains a path_display key
+---@param path string: The path that should be formated
+---@return string: The transformed path ready to be displayed
 utils.transform_path = function(opts, path)
   if path == nil then
     return
@@ -218,7 +237,7 @@ utils.transform_path = function(opts, path)
     return path
   end
 
-  local path_display = utils.get_default(opts.path_display, require("telescope.config").values.path_display)
+  local path_display = vim.F.if_nil(opts.path_display, require("telescope.config").values.path_display)
 
   local transformed_path = path
 
@@ -257,7 +276,10 @@ utils.transform_path = function(opts, path)
         if opts.__length == nil then
           opts.__length = calc_result_length(path_display.truncate)
         end
-        transformed_path = truncate(transformed_path, opts.__length, nil, -1)
+        if opts.__prefix == nil then
+          opts.__prefix = 0
+        end
+        transformed_path = truncate(transformed_path, opts.__length - opts.__prefix, nil, -1)
       end
     end