From ac38730da1d3696b608bc5bedf8b370f6435b884 Mon Sep 17 00:00:00 2001 From: Simon Hauser Date: Tue, 12 Jul 2022 11:52:57 +0200 Subject: [PATCH] docs: mappings documentation overhaul (#2065) Co-authored-by: TJ DeVries --- doc/telescope.txt | 239 +++++++++++++++++++++++-------------- lua/telescope/config.lua | 139 +++++++-------------- lua/telescope/mappings.lua | 142 ++++++++++++++++++---- scripts/gendocs.lua | 1 + scripts/minimal_init.vim | 1 + 5 files changed, 317 insertions(+), 205 deletions(-) diff --git a/doc/telescope.txt b/doc/telescope.txt index 2564854..437d537 100644 --- a/doc/telescope.txt +++ b/doc/telescope.txt @@ -119,20 +119,6 @@ telescope.setup({opts}) *telescope.setup()* - "descending" (default) - "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* selection_strategy: ~ Determines how the cursor acts after each sort iteration. @@ -370,6 +356,22 @@ telescope.setup({opts}) *telescope.setup()* 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* history: ~ This field handles the configuration for prompt history. @@ -559,79 +561,6 @@ telescope.setup({opts}) *telescope.setup()* 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 = { - [""] = require('telescope.actions').close, - }, - } - - - To disable a keymap, put [map] = false - So, to not map "", just put - - ..., - [""] = false, - ..., - - Into your config. - - - otherwise, just set the mapping to the function that you want it to - be. - - ..., - [""] = 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: - - ..., - [""] = "select_default", - ..., - - You can also add other mappings using tables with `type = "command"`. - For example: - - ..., - ["jj"] = { "", type = "command" }, - ["kk"] = { "echo \"Hello, World!\"", type = "command" },) - ..., - - You can also add additional options for mappings of any type - ("action" and "command"). For example: - - ..., - [""] = { - 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* file_sorter: ~ 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 + *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* file_ignore_patterns: ~ 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 = { + [""] = require('telescope.actions').close, + }, + } +< + +To disable a keymap, put `[map] = false` +For example: +> + { + ..., + [""] = 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) +> + { + ..., + [""] = 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: +> + { + ..., + [""] = "select_default", + ..., + } +< + +You can also add other mappings using tables with `type = "command"`. For +example: +> + { + ..., + ["jj"] = { "", type = "command" }, + ["kk"] = { "echo \"Hello, World!\"", type = "command" },) + ..., + } +< + +You can also add additional options for mappings of any type ("action" and +"command"). For example: +> + { + ..., + [""] = { + 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* diff --git a/lua/telescope/config.lua b/lua/telescope/config.lua index 8198ee2..db77491 100644 --- a/lua/telescope/config.lua +++ b/lua/telescope/config.lua @@ -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 = { - [""] = require('telescope.actions').close, - }, - } - - - To disable a keymap, put [map] = false - So, to not map "", just put - - ..., - [""] = false, - ..., - - Into your config. - - - otherwise, just set the mapping to the function that you want it to - be. - - ..., - [""] = 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: - - ..., - [""] = "select_default", - ..., - - You can also add other mappings using tables with `type = "command"`. - For example: - - ..., - ["jj"] = { "", type = "command" }, - ["kk"] = { "echo \"Hello, World!\"", type = "command" },) - ..., - - You can also add additional options for mappings of any type - ("action" and "command"). For example: - - ..., - [""] = { - 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, diff --git a/lua/telescope/mappings.lua b/lua/telescope/mappings.lua index b7baf41..04fbda2 100644 --- a/lua/telescope/mappings.lua +++ b/lua/telescope/mappings.lua @@ -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: +--- +--- { +--- mode = { ..keys } +--- } +--- +--- +--- where {mode} is the one character letter for a mode ('i' for insert, 'n' for normal). +--- +--- For example: +--- +--- mappings = { +--- i = { +--- [""] = require('telescope.actions').close, +--- }, +--- } +--- +--- +--- To disable a keymap, put `[map] = false`
+--- For example: +--- +--- { +--- ..., +--- [""] = 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) +--- +--- { +--- ..., +--- [""] = 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: +--- +--- { +--- ..., +--- [""] = "select_default", +--- ..., +--- } +--- +--- +--- You can also add other mappings using tables with `type = "command"`. +--- For example: +--- +--- { +--- ..., +--- ["jj"] = { "", type = "command" }, +--- ["kk"] = { "echo \"Hello, World!\"", type = "command" },) +--- ..., +--- } +--- +--- +--- You can also add additional options for mappings of any type ("action" and "command"). +--- For example: +--- +--- { +--- ..., +--- [""] = { +--- 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, +--- } +--- +---@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, , { - n = { - ["x"] = "just do this string", - - [""] = 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 diff --git a/scripts/gendocs.lua b/scripts/gendocs.lua index cc9f158..cfec160 100644 --- a/scripts/gendocs.lua +++ b/scripts/gendocs.lua @@ -15,6 +15,7 @@ docs.test = function() "./lua/telescope/command.lua", "./lua/telescope/builtin/init.lua", "./lua/telescope/themes.lua", + "./lua/telescope/mappings.lua", "./lua/telescope/pickers/layout_strategies.lua", "./lua/telescope/config/resolve.lua", "./lua/telescope/make_entry.lua", diff --git a/scripts/minimal_init.vim b/scripts/minimal_init.vim index 780c0e2..65ac43f 100644 --- a/scripts/minimal_init.vim +++ b/scripts/minimal_init.vim @@ -4,3 +4,4 @@ set rtp+=../tree-sitter-lua/ runtime! plugin/plenary.vim runtime! plugin/telescope.lua +runtime! plugin/ts_lua.vim