leigh/telescope.nvim
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: mappings documentation overhaul (#2065)

Browse Source 
Co-authored-by: TJ DeVries <devries.timothyj@gmail.com>
This commit is contained in:
Simon Hauser
2022-07-12 11:52:57 +02:00
committed by GitHub
parent 4ab56d215a
commit ac38730da1
5 changed files with 317 additions and 205 deletions
Download Patch File Download Diff File Expand all files Collapse all files

139
lua/telescope/config.lua
View File

@@ -152,25 +152,6 @@ append(
- "ascending"]]
)
append(
"tiebreak",
function(current_entry, existing_entry, _)
return #current_entry.ordinal < #existing_entry.ordinal
end,
[[
A function that determines how to break a tie when two entries have
the same score.
Having a function that always returns false would keep the entries in
the order they are found, so existing_entry before current_entry.
Vice versa always returning true would place the current_entry
before the existing_entry.
Signature: function(current_entry, existing_entry, prompt) -> boolean
Default: function that breaks the tie based on the length of the
entry's ordinal]]
)
append(
"selection_strategy",
"reset",
@@ -442,6 +423,28 @@ append(
Default: "Prompt"]]
)
append(
"mappings",
{},
[[
Your mappings to override telescope's default mappings.
See: ~
|telescope.mappings|
]]
)
append(
"default_mappings",
nil,
[[
Not recommended to use except for advanced users.
Will allow you to completely remove all of telescope's default maps
and use your own.
]]
)
append(
"history",
{
@@ -668,85 +671,6 @@ append(
Default: true]]
)
append(
"mappings",
{},
[[
Your mappings to override telescope's default mappings.
Format is:
{
mode = { ..keys }
}
where {mode} is the one character letter for a mode
('i' for insert, 'n' for normal).
For example:
mappings = {
i = {
["<esc>"] = require('telescope.actions').close,
},
}
To disable a keymap, put [map] = false
So, to not map "<C-n>", just put
...,
["<C-n>"] = false,
...,
Into your config.
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.
For example, the previous option is equivalent to:
...,
["<C-i>"] = "select_default",
...,
You can also add other mappings using tables with `type = "command"`.
For example:
...,
["jj"] = { "<esc>", type = "command" },
["kk"] = { "<cmd>echo \"Hello, World!\"<cr>", type = "command" },)
...,
You can also add additional options for mappings of any type
("action" and "command"). For example:
...,
["<C-j>"] = {
action = actions.move_selection_next,
opts = { nowait = true, silent = true }
},
...,
]]
)
append(
"default_mappings",
nil,
[[
Not recommended to use except for advanced users.
Will allow you to completely remove all of telescope's default maps
and use your own.
]]
)
append(
"file_sorter",
sorters.get_fzy_sorter,
@@ -783,6 +707,25 @@ append(
Default: require("telescope.sorters").prefilter]]
)
append(
"tiebreak",
function(current_entry, existing_entry, _)
return #current_entry.ordinal < #existing_entry.ordinal
end,
[[
A function that determines how to break a tie when two entries have
the same score.
Having a function that always returns false would keep the entries in
the order they are found, so existing_entry before current_entry.
Vice versa always returning true would place the current_entry
before the existing_entry.
Signature: function(current_entry, existing_entry, prompt) -> boolean
Default: function that breaks the tie based on the length of the
entry's ordinal]]
)
append(
"file_ignore_patterns",
nil,

142
lua/telescope/mappings.lua
View File

@@ -1,4 +1,125 @@
-- TODO: Customize keymap
---@tag telescope.mappings
---@brief [[
--- |telescope.mappings| is used to configure the keybindings within
--- a telescope picker. These keybinds are only local to the picker window
--- and will be cleared once you exit the picker.
---
--- We provide multiple different ways of configuring, as described below,
--- to provide an easy to use experience for changing the default behavior
--- of telescope or extending for your own purposes.
---
--- To see many of the builtin actions that you can use as values for this
--- table, see |telescope.actions|
---
--- Format is:
--- <code>
--- {
--- mode = { ..keys }
--- }
--- </code>
---
--- where {mode} is the one character letter for a mode ('i' for insert, 'n' for normal).
---
--- For example:
--- <code>
--- mappings = {
--- i = {
--- ["<esc>"] = require('telescope.actions').close,
--- },
--- }
--- </code>
---
--- To disable a keymap, put `[map] = false`<br>
--- For example:
--- <code>
--- {
--- ...,
--- ["<C-n>"] = false,
--- ...,
--- }
--- </code>
--- Into your config.
---
--- To override behavior of a key, simply set the value
--- to be a function (either by requiring an action or by writing
--- your own function)
--- <code>
--- {
--- ...,
--- ["<C-i>"] = require('telescope.actions').select_default,
--- ...,
--- }
--- </code>
---
--- 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:
--- <code>
--- {
--- ...,
--- ["<C-i>"] = "select_default",
--- ...,
--- }
--- </code>
---
--- You can also add other mappings using tables with `type = "command"`.
--- For example:
--- <code>
--- {
--- ...,
--- ["jj"] = { "<esc>", type = "command" },
--- ["kk"] = { "<cmd>echo \"Hello, World!\"<cr>", type = "command" },)
--- ...,
--- }
--- </code>
---
--- You can also add additional options for mappings of any type ("action" and "command").
--- For example:
--- <code>
--- {
--- ...,
--- ["<C-j>"] = {
--- action = actions.move_selection_next,
--- opts = { nowait = true, silent = true }
--- },
--- ...,
--- }
--- </code>
---
--- There are three main places you can configure |telescope.mappings|. These are
--- ordered from the lowest priority to the highest priority.
---
--- 1. |telescope.defaults.mappings|
--- 2. In the |telescope.setup()| table, inside a picker with a given name, use the `mappings` key
--- <code>
--- require("telescope").setup {
--- pickers = {
--- find_files = {
--- mappings = {
--- n = {
--- ["kj"] = "close",
--- },
--- },
--- },
--- },
--- }
--- </code>
--- 3. `attach_mappings` function for a particular picker.
--- <code>
--- require("telescope.builtin").find_files {
--- attach_mappings = function(_, map)
--- map("i", "asdf", function(_prompt_bufnr)
--- print "You typed asdf"
--- end)
--- -- needs to return true if you want to map default_mappings and
--- -- false if not
--- return true
--- end,
--- }
--- </code>
---@brief ]]
local a = vim.api
local actions = require "telescope.actions"
@@ -96,25 +217,6 @@ local assign_function = function(prompt_bufnr, func)
return func_id
end
--[[
Usage:
mappings.apply_keymap(42, <function>, {
n = {
["<leader>x"] = "just do this string",
["<CR>"] = function(picker, prompt_bufnr)
actions.close_prompt()
> local filename = ...
vim.cmd(string.format(":e %s", filename))
end,
},
i = {
}
})
--]]
local telescope_map = function(prompt_bufnr, mode, key_bind, key_func, opts)
if not key_func then
return