feat(builtin.buffers): add filter_fn option

[trmckay]

Description

Adds an option filter_fn to telescope.builtins.buffers to filter out buffers from the picker. filter_fn is a function that takes a buffer number and returns true if the buffer should be kept.

Some example use-case:

• Search for buffers with the same filetype as current buffer.
• Search for terminal or other special buffers.
• Exclude special buffers from the search.
• Search for buffers with diagnostics.

Type of change

• New feature (non-breaking change which adds functionality)

How Has This Been Tested?

With a keymap to test different predicates. For example, do not show terminal buffers:

vim.api.nvim_set_keymap("<leader>fb", function()
    telescope.buffers({
        attach_mappings = function(_, map)
            map("i", "<C-q>", require("telescope.actions").delete_buffer)
            return true
        end,
        filter_fn = function(bufnr)
            return vim.api.nvim_buf_get_option(bufnr, "buftype") ~= "terminal"
        end,
    })
end)

Configuration:

• Neovim version (nvim --version): NVIM v0.8.1
• Operating system and version: macOS Ventura 13.0.1

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)

[fdschmidt93]

I'm not opposed to having this, but this can also be achieved by something like

require "telescope.builtin".buffers { file_ignore_patterns = { "term" } }

which levers the fact that buffer names of terminal buffers are prefixed with "term://" (though they could be changed).

[Conni2461]

i am gonna close this, because i dont wanna add more filter_fns. At this point its just duplicated code. we can have the same functionality if we do a generic implementation on finder level, that would bring filter_fn to all builtins.

I proposed a solution here: #2132 (review) i dont remember if i opened a issue for it so i'll check on that later, if i havent opened a issue, i am gonna do that, because a generic filter_fn interface should not be difficult to implement