feat: expand path_display function return type (#3074)

* feat: support path_style in path_display option

* docs: document second value

* tests: add test

* tests: handle function in assert_path

* docs: more explanation

Co-authored-by: James Trew <66286082+jamestrew@users.noreply.github.com>

---------

Co-authored-by: James Trew <66286082+jamestrew@users.noreply.github.com>

lua/telescope/config.lua

@@ -359,7 +359,14 @@ append(
   path_display can also be set to 'hidden' string to hide file names
 
   path_display can also be set to a function for custom formatting of
-  the path display. Example:
+  the path display with the following signature
+
+  Signature: fun(opts: table, path: string): string, table?
+
+  The optional table is an list of positions and highlight groups to
+  set the highlighting of the return path string.
+
+  Example:
 
       -- Format path as "file.txt (path\to\file\)"
       path_display = function(opts, path)
@@ -367,6 +374,24 @@ append(
         return string.format("%s (%s)", tail, path)
       end,
 
+      -- Format path and add custom highlighting
+      path_display = function(opts, path)
+        local tail = require("telescope.utils").path_tail(path)
+        path = string.format("%s (%s)", tail, path)
+
+        local highlights = {
+          {
+            {
+              0, -- highlight start position
+              #path, -- highlight end position
+            },
+            "Comment", -- highlight group name
+          },
+        }
+
+        return path, highlights
+      end
+
   Default: {}]]
 )
 

lua/telescope/utils.lua

@@ -280,14 +280,15 @@ utils.transform_path = function(opts, path)
     return path, {}
   end
 
-  ---@type fun(opts:table, path: string): string
+  ---@type fun(opts:table, path: string): string, table?
   local path_display = vim.F.if_nil(opts.path_display, require("telescope.config").values.path_display)
 
   local transformed_path = path
   local path_style = {}
 
   if type(path_display) == "function" then
-    return path_display(opts, transformed_path), path_style
+    local custom_transformed_path, custom_path_style = path_display(opts, transformed_path)
+    return custom_transformed_path, custom_path_style or path_style
   elseif utils.is_path_hidden(nil, path_display) then
     return "", path_style
   elseif type(path_display) == "table" then

lua/tests/automated/utils_spec.lua

@@ -205,6 +205,9 @@ describe("transform_path", function()
     elseif type(path_display) == "table" then
       opts.path_display = path_display
       eq(expect, utils.transform_path(opts, path))
+    elseif type(path_display) == "function" then
+      opts.path_display = path_display
+      eq(expect, utils.transform_path(opts, path))
     elseif path_display == nil then
       eq(expect, utils.transform_path(opts, path))
     end
@@ -297,4 +300,10 @@ describe("transform_path", function()
       new_relpath "init.lua lua/telescope"
     )
   end)
+
+  it("handles function passed to path_display", function()
+    assert_path(function(_, path)
+      return string.gsub(path, "^doc", "d")
+    end, new_relpath "doc/mydoc.md", new_relpath "d/mydoc.md")
+  end)
 end)