feat: highlight range in previewer

[luismeyer95]

Description

I'm currently working on a telescope picker that exposes some ast-grep functionalities. Seeing that the match highlighting in the existing previewers is limited to full single line only, I implemented finer-grained range highlighting capabilities in the vim_buffer_vimgrep previewer to improve match visualization. This could benefit any existing match-based picker.

In case this feature is accepted, I have some pending questions:

• In the current implementation, I’m overriding the existing TelescopePreviewLine highlights. Should the range highlight use a new hl group and be added on top of the existing TelescopePreviewLine highlight instead?
• Should the range highlight become a default for certain builtin pickers? Or should it be opt-in as a config option?

Closes #933 (if integrated into builtin pickers)

Type of change

• New feature (non-breaking change which adds functionality)
• This change requires a documentation update

How Has This Been Tested?

• By testing Telescope live_grep to make sure its existing previewer match highlighting behaviour didn't change (its entry maker only provides col, colend is also needed to opt in)
• By running luafile % with the following custom picker (requires installing ast-grep version ≥ 0.8.0).

It recursively searches cwd for pattern prompt and outputs results with previewer match highlighting. I did some manual tests with various combinations of patterns, buffer text (small/big match, non-ASCII chars) and provided range delimiters in entry maker output (lnum, lnend, col, colend). For non-ASCII chars, column byte offset is left computed by the user of the previewer, so any issue there should be due to misuse.

local pickers = require "telescope.pickers"
local finders = require "telescope.finders"
local sorters = require "telescope.sorters"
local conf = require("telescope.config").values
local Job = require "plenary.job"

local ast_grep = function(opts)
  opts = opts or {}

  pickers.new(opts, {
    prompt_title = "AST Grep",
    finder = finders.new_dynamic({
      fn = function(prompt)
        local result = Job:new({
          command = "sg",
          args = { "-p", prompt, "-l", "lua", "--json" },
          cwd = vim.fn.getcwd(),
          env = vim.fn.environ(),
        }):sync()

        result = table.concat(result, '')

        local matches = {}
        if result ~= "" then
          matches = vim.json.decode(result)
        end

        return matches
      end,
      entry_maker = function(chunk)
        local hl_range = {
          lnum = chunk.range.start.line + 1,
          lnend = chunk.range['end'].line + 1,
          col = chunk.range.start.column + 1,
          colend = chunk.range['end'].column + 1,
        }

        return vim.tbl_deep_extend("force", hl_range, {
          value = chunk.file .. ":" .. hl_range.lnum,
          display = chunk.file .. ":" .. hl_range.lnum,
          path = chunk.file,
          ordinal = chunk.file,
        })
      end,
    }),
    previewer = conf.grep_previewer(opts),
    sorter = sorters.empty(),
  }):find()
end

ast_grep()

Configuration:

macOS 11.2.3

NVIM v0.9.1
Build type: Release
LuaJIT 2.1.0-beta3

Checklist:

• My code follows the style guidelines of this project (stylua)
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation (lua annotations)

[Conni2461]

okay thats actually really cool, thanks for implementing that.
Could you resolve the styling issues, after that i plan to merge without any builtins using the feature (for now) but we could/should use it once #2536 is done.

CC @jamestrew

[luismeyer95]

Nice! Style issues fixed in latest push.

[jamestrew]

lgtm!

[Conni2461]

Thanks for the PR :)

[HerringtonDarkholme]

Thank @luismeyer95 again for this excellent contribution to both ast-grep and telescope! I'm honored!

[kuator]

Thank @luismeyer95 again for this excellent contribution to both ast-grep and telescope! I'm honored!

Ass we can