runtime(doc): Improve doc for cmdline-autocompletion
- Address https://github.com/vim/vim/pull/18219#issuecomment-3264634710 - Make the cmdline-autocompletion help more user friendly closes: #18245 Signed-off-by: Girish Palya <girishji@gmail.com> Signed-off-by: Christian Brabandt <cb@256bit.org>
This commit is contained in:
Girish Palya
committed by
Christian Brabandt
Christian Brabandt
parent
3980c86525
commit
d7d6a6f05a
@ -1,4 +1,4 @@
|
||||
*builtin.txt* For Vim version 9.1. Last change: 2025 Sep 06
|
||||
*builtin.txt* For Vim version 9.1. Last change: 2025 Sep 08
|
||||
|
||||
|
||||
VIM REFERENCE MANUAL by Bram Moolenaar
|
||||
@ -12407,7 +12407,6 @@ wildmenumode() *wildmenumode()*
|
||||
wildtrigger() *wildtrigger()*
|
||||
Start wildcard expansion in the command-line, using the
|
||||
behavior defined by the 'wildmode' and 'wildoptions' settings.
|
||||
See |cmdline-completion|.
|
||||
|
||||
This function also enables completion in search patterns such
|
||||
as |/|, |?|, |:s|, |:g|, |:v| and |:vimgrep|.
|
||||
@ -12415,23 +12414,15 @@ wildtrigger() *wildtrigger()*
|
||||
Unlike pressing 'wildchar' manually, this function does not
|
||||
produce a beep when no matches are found and generally
|
||||
operates more quietly. This makes it suitable for triggering
|
||||
completion automatically, such as from an |:autocmd|.
|
||||
completion automatically.
|
||||
|
||||
Note: After navigating command-line history, the first call to
|
||||
wildtrigger() is a no-op; a second call is needed to start
|
||||
expansion. This is to support history navigation in
|
||||
command-line autocompletion.
|
||||
|
||||
See |cmdline-autocompletion|.
|
||||
|
||||
*cmdline-autocompletion*
|
||||
Example: To make the completion menu pop up automatically
|
||||
while typing on the command line: >
|
||||
autocmd CmdlineChanged [:/\?] call wildtrigger()
|
||||
set wildmode=noselect:lastused,full wildoptions=pum
|
||||
<
|
||||
To retain normal history navigation with the up/down keys: >
|
||||
cnoremap <expr> <Up> wildmenumode() ? "\<C-E>\<Up>" : "\<Up>"
|
||||
cnoremap <expr> <Down> wildmenumode() ? "\<C-E>\<Down>" : "\<Down>"
|
||||
<
|
||||
To apply an option only during a search, for example to set
|
||||
'pumheight': >
|
||||
autocmd CmdlineEnter [/\?] set pumheight=8
|
||||
autocmd CmdlineLeave [/\?] set pumheight&
|
||||
<
|
||||
Return value is always 0.
|
||||
|
||||
Return type: |Number|
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
*cmdline.txt* For Vim version 9.1. Last change: 2025 Aug 08
|
||||
*cmdline.txt* For Vim version 9.1. Last change: 2025 Sep 08
|
||||
|
||||
|
||||
VIM REFERENCE MANUAL by Bram Moolenaar
|
||||
@ -20,6 +20,7 @@ Basic command line editing is explained in chapter 20 of the user manual
|
||||
5. Ex command-line flags |ex-flags|
|
||||
6. Ex special characters |cmdline-special|
|
||||
7. Command-line window |cmdline-window|
|
||||
8. Command-line autocompletion |cmdline-autocompletion|
|
||||
|
||||
==============================================================================
|
||||
1. Command-line editing *cmdline-editing*
|
||||
@ -406,6 +407,9 @@ word before the cursor. This is available for:
|
||||
The number of help item matches is limited (currently to 300) to avoid a long
|
||||
delay when there are very many matches.
|
||||
|
||||
For automatic completion as you type (without pressing a key like <Tab>),
|
||||
see |cmdline-autocompletion|.
|
||||
|
||||
These are the commands that can be used:
|
||||
|
||||
*c_CTRL-D*
|
||||
@ -479,8 +483,6 @@ When repeating 'wildchar' or CTRL-N you cycle through the matches, eventually
|
||||
ending up back to what was typed. If the first match is not what you wanted,
|
||||
you can use <S-Tab> or CTRL-P to go straight back to what you typed.
|
||||
|
||||
See also |wildtrigger()|.
|
||||
|
||||
The 'wildmenu' option can be set to show the matches just above the command
|
||||
line.
|
||||
|
||||
@ -1340,4 +1342,83 @@ The character used for the pattern indicates the type of command-line:
|
||||
@ string for |input()|
|
||||
- text for |:insert| or |:append|
|
||||
|
||||
==============================================================================
|
||||
8. Command-line autocompletion *cmdline-autocompletion*
|
||||
|
||||
Autocompletion makes the command-line more efficient and easier to navigate by
|
||||
automatically showing a popup menu of suggestions as you type, whether
|
||||
searching (/ or ?) or entering commands (:).
|
||||
|
||||
A basic setup is: >
|
||||
autocmd CmdlineChanged [:/\?] call wildtrigger()
|
||||
set wildmode=noselect:lastused,full
|
||||
set wildoptions=pum
|
||||
|
||||
With this configuration, suggestions appear immediately, and you can
|
||||
move through them with <Tab> or the arrow keys.
|
||||
|
||||
To retain normal command-line history navigation with <Up>/<Down>: >
|
||||
cnoremap <expr> <Up> wildmenumode() ? "\<C-E>\<Up>" : "\<Up>"
|
||||
cnoremap <expr> <Down> wildmenumode() ? "\<C-E>\<Down>" : "\<Down>"
|
||||
|
||||
Options can also be applied only for specific command-lines. For
|
||||
example, to use a shorter popup menu height only during search: >
|
||||
autocmd CmdlineEnter [/\?] set pumheight=8
|
||||
autocmd CmdlineLeave [/\?] set pumheight&
|
||||
|
||||
EXTRAS *fuzzy-file-picker* *live-grep*
|
||||
|
||||
Command-line autocompletion can also be extended for advanced uses.
|
||||
For example, you can turn the native |:find| command into a fuzzy, interactive
|
||||
file picker: >
|
||||
|
||||
set findfunc=Find
|
||||
func Find(arg, _)
|
||||
if get(s:, 'filescache', []) == []
|
||||
let s:filescache = systemlist(
|
||||
\ 'find . -path "*/.git" -prune -o -type f -print')
|
||||
endif
|
||||
return a:arg == '' ? s:filescache : matchfuzzy(s:filescache, a:arg)
|
||||
endfunc
|
||||
autocmd CmdlineEnter : let s:filescache = []
|
||||
|
||||
The `:Grep` command searches for lines matching a pattern and updates the
|
||||
results dynamically as you type (triggered after two characters; note: needs
|
||||
the `CmdlineLeavePre` autocmd from the next section): >
|
||||
|
||||
command! -nargs=+ -complete=customlist,<SID>Grep
|
||||
\ Grep call <SID>VisitFile()
|
||||
|
||||
func s:Grep(arglead, cmdline, cursorpos)
|
||||
let cmd = $'grep -REIHns "{a:arglead}" --exclude-dir=.git
|
||||
\ --exclude=".*"'
|
||||
return len(a:arglead) > 1 ? systemlist(cmd) : []
|
||||
endfunc
|
||||
|
||||
func s:VisitFile()
|
||||
let item = getqflist(#{lines: [s:selected]}).items[0]
|
||||
let pos = '[0,\ item.lnum,\ item.col,\ 0]'
|
||||
exe $':b +call\ setpos(".",\ {pos}) {item.bufnr}'
|
||||
call setbufvar(item.bufnr, '&buflisted', 1)
|
||||
endfunc
|
||||
|
||||
Automatically select the first item in the completion list when leaving the
|
||||
command-line, and for `:Grep`, add the typed pattern to the command-line
|
||||
history: >
|
||||
|
||||
autocmd CmdlineLeavePre :
|
||||
\ if get(cmdcomplete_info(), 'matches', []) != [] |
|
||||
\ let s:info = cmdcomplete_info() |
|
||||
\ if getcmdline() =~ '^\s*fin\%[d]\s' && s:info.selected == -1 |
|
||||
\ call setcmdline($'find {s:info.matches[0]}') |
|
||||
\ endif |
|
||||
\ if getcmdline() =~ '^\s*Grep\s' |
|
||||
\ let s:selected = s:info.selected != -1
|
||||
\ ? s:info.matches[s:info.selected] : s:info.matches[0] |
|
||||
\ call setcmdline(s:info.cmdline_orig) |
|
||||
\ endif |
|
||||
\ endif
|
||||
|
||||
For autocompletion in insert mode, see |ins-autocompletion|.
|
||||
|
||||
vim:tw=78:ts=8:noet:ft=help:norl:
|
||||
|
||||
@ -6673,7 +6673,7 @@ cmdarg-variable eval.txt /*cmdarg-variable*
|
||||
cmdbang-variable eval.txt /*cmdbang-variable*
|
||||
cmdcomplete_info() builtin.txt /*cmdcomplete_info()*
|
||||
cmdline-arguments vi_diff.txt /*cmdline-arguments*
|
||||
cmdline-autocompletion builtin.txt /*cmdline-autocompletion*
|
||||
cmdline-autocompletion cmdline.txt /*cmdline-autocompletion*
|
||||
cmdline-changed version5.txt /*cmdline-changed*
|
||||
cmdline-completion cmdline.txt /*cmdline-completion*
|
||||
cmdline-editing cmdline.txt /*cmdline-editing*
|
||||
@ -7680,6 +7680,7 @@ function-range-example userfunc.txt /*function-range-example*
|
||||
function-search-undo userfunc.txt /*function-search-undo*
|
||||
function_key intro.txt /*function_key*
|
||||
functions eval.txt /*functions*
|
||||
fuzzy-file-picker cmdline.txt /*fuzzy-file-picker*
|
||||
fuzzy-matching pattern.txt /*fuzzy-matching*
|
||||
fvwm.vim syntax.txt /*fvwm.vim*
|
||||
fvwm2rc syntax.txt /*fvwm2rc*
|
||||
@ -8829,6 +8830,7 @@ listener_remove() builtin.txt /*listener_remove()*
|
||||
lite.vim syntax.txt /*lite.vim*
|
||||
literal-Dict eval.txt /*literal-Dict*
|
||||
literal-string eval.txt /*literal-string*
|
||||
live-grep cmdline.txt /*live-grep*
|
||||
lnum-variable eval.txt /*lnum-variable*
|
||||
load-plugins starting.txt /*load-plugins*
|
||||
load-vim-script repeat.txt /*load-vim-script*
|
||||
|
||||
Reference in New Issue
Block a user