diff options
Diffstat (limited to 'runtime/doc/map.txt')
| -rw-r--r-- | runtime/doc/map.txt | 131 |
1 files changed, 127 insertions, 4 deletions
diff --git a/runtime/doc/map.txt b/runtime/doc/map.txt index 98da68b76a..59a5a63e16 100644 --- a/runtime/doc/map.txt +++ b/runtime/doc/map.txt @@ -48,6 +48,7 @@ modes. allows for nested and recursive use of mappings. Note: Trailing spaces are included in the {rhs}, because space is a valid Normal mode command. + See |map-trailing-white|. *:nore* *:norem* :no[remap] {lhs} {rhs} |mapmode-nvo| *:no* *:noremap* *:nor* @@ -85,10 +86,8 @@ modes. for other modes where it applies. It also works when {lhs} matches the {rhs} of a mapping. This is for when an abbreviation applied. - Note: Trailing spaces are included in the {lhs}. This - unmap does NOT work: > - :map @@ foo - :unmap @@ | print + Note: Trailing spaces are included in the {lhs}. + See |map-trailing-white|. :mapc[lear] |mapmode-nvo| *:mapc* *:mapclear* :nmapc[lear] |mapmode-n| *:nmapc* *:nmapclear* @@ -152,6 +151,24 @@ that mapping won't get expanded yet, Vim is waiting for another character. If you type a space, then "foo" will get inserted, plus the space. If you type "a", then "bar" will get inserted. +Trailing white space ~ + *map-trailing-white* +This unmap command does NOT work: > + :map @@ foo + :unmap @@ | print + +Because it tries to unmap "@@ ", including the white space before the command +separator "|". Other examples with trailing white space: > + unmap @@ + unmap @@ " comment + +An error will be issued, which is very hard to identify, because the ending +whitespace character in `unmap @@ ` is not visible. + +A generic solution is to put the command separator "|" right after the mapped +keys. After that white space and a comment may follow: > + unmap @@| " comment + 1.2 SPECIAL ARGUMENTS *:map-arguments* @@ -1430,6 +1447,112 @@ Possible values are (second column is the short name used in listing): -addr=other ? other kind of range +Incremental preview ~ + *:command-preview* {nvim-api} +Commands can show an 'inccommand' (as-you-type) preview by defining a preview +handler (only from Lua, see |nvim_create_user_command()|). + +The preview callback must be a Lua function with this signature: > + + function cmdpreview(opts, ns, buf) +< +where "opts" has the same form as that given to |nvim_create_user_command()| +callbacks, "ns" is the preview namespace id for highlights, and "buf" is the +buffer that your preview routine will directly modify to show the previewed +results (for "inccommand=split", or nil for "inccommand=nosplit"). + +Your command preview routine must implement this protocol: + +1. Modify the current buffer as required for the preview (see + |nvim_buf_set_text()| and |nvim_buf_set_lines()|). +2. If preview buffer is provided, add necessary text to the preview buffer. +3. Add required highlights to the current buffer. If preview buffer is + provided, add required highlights to the preview buffer as well. All + highlights must be added to the preview namespace which is provided as an + argument to the preview callback (see |nvim_buf_add_highlight()| and + |nvim_buf_set_extmark()| for help on how to add highlights to a namespace). +4. Return an integer (0, 1, 2) which controls how Nvim behaves as follows: + 0: No preview is shown. + 1: Preview is shown without preview window (even with "inccommand=split"). + 2: Preview is shown and preview window is opened (if "inccommand=split"). + For "inccommand=nosplit" this is the same as 1. + +After preview ends, Nvim discards all changes to the buffer and all highlights +in the preview namespace. + +Here's an example of a command to trim trailing whitespace from lines that +supports incremental command preview: +> + -- Trims trailing whitespace in the current buffer. + -- Also performs 'inccommand' preview if invoked as a preview callback + -- (preview_ns is non-nil). + local function trim_space(opts, preview_ns, preview_buf) + local line1 = opts.line1 + local line2 = opts.line2 + local buf = vim.api.nvim_get_current_buf() + local lines = vim.api.nvim_buf_get_lines(buf, line1 - 1, line2, 0) + local new_lines = {} + local preview_buf_line = 0 + + for i, line in ipairs(lines) do + local startidx, endidx = string.find(line, '%s+$') + + if startidx ~= nil then + -- Highlight the match if in command preview mode + if preview_ns ~= nil then + vim.api.nvim_buf_add_highlight( + buf, preview_ns, 'Substitute', line1 + i - 2, startidx - 1, + endidx + ) + + -- Add lines and highlight to the preview buffer + -- if inccommand=split + if preview_buf ~= nil then + local prefix = string.format('|%d| ', line1 + i - 1) + + vim.api.nvim_buf_set_lines( + preview_buf, preview_buf_line, preview_buf_line, 0, + { prefix .. line } + ) + vim.api.nvim_buf_add_highlight( + preview_buf, preview_ns, 'Substitute', preview_buf_line, + #prefix + startidx - 1, #prefix + endidx + ) + + preview_buf_line = preview_buf_line + 1 + end + end + end + + if not preview_ns then + new_lines[#new_lines+1] = string.gsub(line, '%s+$', '') + end + end + + -- Don't make any changes to the buffer if previewing + if not preview_ns then + vim.api.nvim_buf_set_lines(buf, line1 - 1, line2, 0, new_lines) + end + + -- When called as a preview callback, return the value of the + -- preview type + if preview_ns ~= nil then + return 2 + end + end + + -- Create the user command + vim.api.nvim_create_user_command( + 'TrimTrailingWhitespace', + trim_space, + { nargs = '?', range = '%', addr = 'lines', preview = trim_space } + ) +< +Note that in the above example, the same function is used as both the command +callback and the preview callback, but you could instead use separate +functions. + + Special cases ~ *:command-bang* *:command-bar* *:command-register* *:command-buffer* |