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

239
doc/telescope.txt
View File

@@ -119,20 +119,6 @@ telescope.setup({opts}) *telescope.setup()*
- "descending" (default) - "descending" (default)
- "ascending" - "ascending"
*telescope.defaults.tiebreak*
tiebreak: ~
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
*telescope.defaults.selection_strategy* *telescope.defaults.selection_strategy*
selection_strategy: ~ selection_strategy: ~
Determines how the cursor acts after each sort iteration. Determines how the cursor acts after each sort iteration.
@@ -370,6 +356,22 @@ telescope.setup({opts}) *telescope.setup()*
Default: "Prompt" Default: "Prompt"
*telescope.defaults.mappings*
mappings: ~
Your mappings to override telescope's default mappings.
See: ~
|telescope.mappings|
*telescope.defaults.default_mappings*
default_mappings: ~
Not recommended to use except for advanced users.
Will allow you to completely remove all of telescope's default maps
and use your own.
*telescope.defaults.history* *telescope.defaults.history*
history: ~ history: ~
This field handles the configuration for prompt history. This field handles the configuration for prompt history.
@@ -559,79 +561,6 @@ telescope.setup({opts}) *telescope.setup()*
Default: true Default: true
*telescope.defaults.mappings*
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 }
},
...,
*telescope.defaults.default_mappings*
default_mappings: ~
Not recommended to use except for advanced users.
Will allow you to completely remove all of telescope's default maps
and use your own.
*telescope.defaults.file_sorter* *telescope.defaults.file_sorter*
file_sorter: ~ file_sorter: ~
A function pointer that specifies the file_sorter. This sorter will A function pointer that specifies the file_sorter. This sorter will
@@ -658,6 +587,20 @@ telescope.setup({opts}) *telescope.setup()*
Default: require("telescope.sorters").prefilter Default: require("telescope.sorters").prefilter
*telescope.defaults.tiebreak*
tiebreak: ~
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
*telescope.defaults.file_ignore_patterns* *telescope.defaults.file_ignore_patterns*
file_ignore_patterns: ~ file_ignore_patterns: ~
A table of lua regex that define the files that should be ignored. A table of lua regex that define the files that should be ignored.
@@ -1716,6 +1659,128 @@ themes.get_ivy() *telescope.themes.get_ivy()*
================================================================================
MAPPINGS *telescope.mappings*
|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:
>
{
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`
For example:
>
{
...,
["<C-n>"] = false,
...,
}
<
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)
>
{
...,
["<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 }
},
...,
}
<
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
>
require("telescope").setup {
pickers = {
find_files = {
mappings = {
n = {
["kj"] = "close",
},
},
},
},
}
<
3. `attach_mappings` function for a particular picker.
>
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,
}
<
================================================================================ ================================================================================
LAYOUT *telescope.layout* LAYOUT *telescope.layout*

139
lua/telescope/config.lua
View File

@@ -152,25 +152,6 @@ append(
- "ascending"]] - "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( append(
"selection_strategy", "selection_strategy",
"reset", "reset",
@@ -442,6 +423,28 @@ append(
Default: "Prompt"]] 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( append(
"history", "history",
{ {
@@ -668,85 +671,6 @@ append(
Default: true]] 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( append(
"file_sorter", "file_sorter",
sorters.get_fzy_sorter, sorters.get_fzy_sorter,
@@ -783,6 +707,25 @@ append(
Default: require("telescope.sorters").prefilter]] 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( append(
"file_ignore_patterns", "file_ignore_patterns",
nil, 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 a = vim.api
local actions = require "telescope.actions" local actions = require "telescope.actions"
@@ -96,25 +217,6 @@ local assign_function = function(prompt_bufnr, func)
return func_id return func_id
end 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) local telescope_map = function(prompt_bufnr, mode, key_bind, key_func, opts)
if not key_func then if not key_func then
return return

1
scripts/gendocs.lua
View File

@@ -15,6 +15,7 @@ docs.test = function()
"./lua/telescope/command.lua", "./lua/telescope/command.lua",
"./lua/telescope/builtin/init.lua", "./lua/telescope/builtin/init.lua",
"./lua/telescope/themes.lua", "./lua/telescope/themes.lua",
"./lua/telescope/mappings.lua",
"./lua/telescope/pickers/layout_strategies.lua", "./lua/telescope/pickers/layout_strategies.lua",
"./lua/telescope/config/resolve.lua", "./lua/telescope/config/resolve.lua",
"./lua/telescope/make_entry.lua", "./lua/telescope/make_entry.lua",

1
scripts/minimal_init.vim
View File

@@ -4,3 +4,4 @@ set rtp+=../tree-sitter-lua/
runtime! plugin/plenary.vim runtime! plugin/plenary.vim
runtime! plugin/telescope.lua runtime! plugin/telescope.lua
runtime! plugin/ts_lua.vim