From b77413ff8f59f380612074f0c9bd49093d8db695 Mon Sep 17 00:00:00 2001 From: Mike Vink Date: Sun, 19 Jan 2025 13:52:52 +0100 Subject: Squashed 'mut/neovim/pack/plugins/start/blink.cmp/' content from commit 1cc3b1a git-subtree-dir: mut/neovim/pack/plugins/start/blink.cmp git-subtree-split: 1cc3b1a908fbcfd15451c4772759549724f38524 --- docs/configuration/keymap.md | 145 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 145 insertions(+) create mode 100644 docs/configuration/keymap.md (limited to 'docs/configuration/keymap.md') diff --git a/docs/configuration/keymap.md b/docs/configuration/keymap.md new file mode 100644 index 0000000..d82c5b8 --- /dev/null +++ b/docs/configuration/keymap.md @@ -0,0 +1,145 @@ +# Keymap + +Blink uses a special schema for defining keymaps since it needs to handle falling back to other mappings. However, there's nothing stopping you from using `require('blink.cmp')` and implementing these keymaps yourself. + +Your custom key mappings are merged with a `preset` and any conflicting keys will overwrite the preset mappings. The `fallback` command will run the next non blink keymap. + +## Example + +Each keymap may be a list of commands and/or functions, where commands map directly to `require('blink.cmp')[command]()`. If the command/function returns `false` or `nil`, the next command/function will be run. + +```lua +keymap = { + -- set to 'none' to disable the 'default' preset + preset = 'default', + + [''] = { 'select_prev', 'fallback' }, + [''] = { 'select_next', 'fallback' }, + + -- disable a keymap from the preset + [''] = {}, + + -- show with a list of providers + [''] = { function(cmp) cmp.show({ providers = { 'snippets' } }) end }, + + -- control whether the next command will be run when using a function + [''] = { + function(cmp) + if some_condition then return end -- runs the next command + return true -- doesn't run the next command + end, + 'select_next' + }, + + -- optionally, separate cmdline keymaps + -- cmdline = {} +} +``` + +## Commands + +- `show`: Shows the completion menu + - Optionally use `function(cmp) cmp.show({ providers = { 'snippets' } }) end` to show with a specific list of providers +- `hide`: Hides the completion menu +- `cancel`: Reverts `completion.list.selection.auto_insert` and hides the completion menu +- `accept`: Accepts the currently selected item + - Optionally pass an index to select a specific item in the list: `function(cmp) cmp.accept({ index = 1 }) end` + - Optionally pass a `callback` to run after the item is accepted: `function(cmp) cmp.accept({ callback = function() vim.api.nvim_feedkeys('\n', 'n', true) end }) end` +- `select_and_accept`: Accepts the currently selected item, or the first item if none are selected +- `select_prev`: Selects the previous item, cycling to the bottom of the list if at the top, if `completion.list.cycle.from_top == true` + - Optionally control the `auto_insert` property of `completion.list.selection`: `function(cmp) cmp.select_prev({ auto_insert = false }) end` +- `select_next`: Selects the next item, cycling to the top of the list if at the bottom, if `completion.list.cycle.from_bottom == true` + - Optionally control the `auto_insert` property of `completion.list.selection`: `function(cmp) cmp.select_next({ auto_insert = false }) end` +- `show_documentation`: Shows the documentation for the currently selected item +- `hide_documentation`: Hides the documentation +- `scroll_documentation_up`: Scrolls the documentation up by 4 lines + - Optionally use `function(cmp) cmp.scroll_documentation_up(4) end` to scroll by a specific number of lines +- `scroll_documentation_down`: Scrolls the documentation down by 4 lines + - Optionally use `function(cmp) cmp.scroll_documentation_down(4) end` to scroll by a specific number of lines +- `snippet_forward`: Jumps to the next snippet placeholder +- `snippet_backward`: Jumps to the previous snippet placeholder +- `fallback`: Runs the next non-blink keymap, or runs the built-in neovim binding + +## Cmdline + +You may set a separate keymap for cmdline by defining `keymap.cmdline`, with an identical structure to `keymap`. + +```lua +keymap = { + preset = 'default', + ... + cmdline = { + preset = 'enter', + ... + } +} +``` + +## Presets + +Set the preset to `none` to disable the presets + +### `default` + +```lua +[''] = { 'show', 'show_documentation', 'hide_documentation' }, +[''] = { 'hide' }, +[''] = { 'select_and_accept' }, + +[''] = { 'select_prev', 'fallback' }, +[''] = { 'select_next', 'fallback' }, + +[''] = { 'scroll_documentation_up', 'fallback' }, +[''] = { 'scroll_documentation_down', 'fallback' }, + +[''] = { 'snippet_forward', 'fallback' }, +[''] = { 'snippet_backward', 'fallback' }, +``` + +### `super-tab` + +You may want to set `completion.trigger.show_in_snippet = false` or use `completion.list.selection.preselect = function(ctx) return not require('blink.cmp').snippet_active({ direction = 1 }) end`. See more info in: https://cmp.saghen.dev/configuration/completion.html#list + +```lua +[''] = { 'show', 'show_documentation', 'hide_documentation' }, +[''] = { 'hide', 'fallback' }, + +[''] = { + function(cmp) + if cmp.snippet_active() then return cmp.accept() + else return cmp.select_and_accept() end + end, + 'snippet_forward', + 'fallback' +}, +[''] = { 'snippet_backward', 'fallback' }, + +[''] = { 'select_prev', 'fallback' }, +[''] = { 'select_next', 'fallback' }, +[''] = { 'select_prev', 'fallback' }, +[''] = { 'select_next', 'fallback' }, + +[''] = { 'scroll_documentation_up', 'fallback' }, +[''] = { 'scroll_documentation_down', 'fallback' }, +``` + +### `enter` + +You may want to set `completion.list.selection.preselect = false`. See more info in: https://cmp.saghen.dev/configuration/completion.html#list + +```lua +[''] = { 'show', 'show_documentation', 'hide_documentation' }, +[''] = { 'hide', 'fallback' }, +[''] = { 'accept', 'fallback' }, + +[''] = { 'snippet_forward', 'fallback' }, +[''] = { 'snippet_backward', 'fallback' }, + +[''] = { 'select_prev', 'fallback' }, +[''] = { 'select_next', 'fallback' }, +[''] = { 'select_prev', 'fallback' }, +[''] = { 'select_next', 'fallback' }, + +[''] = { 'scroll_documentation_up', 'fallback' }, +[''] = { 'scroll_documentation_down', 'fallback' }, +``` -- cgit v1.2.3