Merge pull request #2308 from h-east/update-cmdline

Update cmdline.{txt,jax}

Author: h-east

doc/cmdline.jax

@@ -1,4 +1,4 @@
-*cmdline.txt*   For Vim バージョン 9.1.  Last change: 2025 Aug 08
+*cmdline.txt*   For Vim バージョン 9.1.  Last change: 2025 Sep 10
 
 
 		  VIMリファレンスマニュアル    by Bram Moolenaar
@@ -19,6 +19,7 @@
 5. Exコマンドラインのフラグ	|ex-flags|
 6. Exコマンド用の特別な文字	|cmdline-special|
 7. コマンドラインウィンドウ	|cmdline-window|
+8. コマンドラインの自動補完	|cmdline-autocompletion|
 
 ==============================================================================
 1. コマンドラインの編集					*cmdline-editing*
@@ -385,6 +386,9 @@ CTRL-]		文字を挿入することなく短縮入力を展開する。
 マッチするヘルプ項目の個数には上限がある(現在のところは 300)。非常に多くのマッ
 チがあったとき、遅くなるのを避けるためである。
 
+(<Tab> 等のキーを押さずに) 入力時に自動補完を行う場合、
+|cmdline-autocompletion| を参照。
+
 補完に使えるコマンドは以下の通り。
 
 							*c_CTRL-D*
@@ -448,8 +452,6 @@ CTRL-T		'incsearch' が設定され "/" や "?" にパターンを入力して
 ある。以前のバージョンでは <Esc> が使われていた)。パターンがファイル名に対して
 適用されるときは標準の |wildcards| が使用できる。
 
-|wildtrigger()| も参照。
-
 'wildchar' または CTRL-N を繰り返すとマッチしたものの始めから終わりまでを循環
 して、最終的には入力されたものに戻る。最初のマッチが望むものでないなら、入力し
 たものにまっすぐに戻るために <S-Tab> または CTRL-P を使うことができる。
@@ -1284,4 +1286,82 @@ Note: これは |file-pattern| なので、"?" をエスケープする必要が
 	@	関数 |input()| に対して入力する文字列
 	-	コマンド |:insert| や |:append| に対して入力する文字列
 
+==============================================================================
+8. コマンドラインの自動補完			 *cmdline-autocompletion*
+
+自動補完は、入力中に検索 (/ または ?) やコマンド入力 (:) の際に自動的に候補の
+ポップアップメニューを表示することで、コマンドラインの操作をより効率的かつ簡単
+にする。
+
+基本的な設定: >
+	autocmd CmdlineChanged [:\/\?] call wildtrigger()
+	set wildmode=noselect:lastused,full
+	set wildoptions=pum
+
+この設定では、すぐに候補が表示され、<Tab> キーまたは矢印キーを使用して候補間を
+移動できる。
+
+<Up>/<Down> による通常のコマンドライン履歴ナビゲーションを維持するには: >
+	cnoremap <expr> <Up>   wildmenumode() ? "\<C-E>\<Up>"   : "\<Up>"
+	cnoremap <expr> <Down> wildmenumode() ? "\<C-E>\<Down>" : "\<Down>"
+
+オプションは特定のコマンドラインにのみ適用することもできる。例えば、検索時のみ
+ポップアップメニューの高さを低くするには: >
+	autocmd CmdlineEnter [\/\?] set pumheight=8
+	autocmd CmdlineLeave [\/\?] set pumheight&
+
+☆おまけ				*fuzzy-file-picker* *live-grep*
+
+コマンドラインの自動補完は、高度な用途向けに拡張することもでる。
+例えば、ネイティブの |:find| コマンドを、あいまい検索が可能な対話型ファイルピッ
+カーに変えることができる: >
+
+	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 = []
+
+`:Grep` コマンドは、パターンにマッチする行を検索し、入力すると結果を動的に更新
+する (2 文字後にトリガーされる。note: 次のセクションの `CmdlineLeavePre` 自動
+コマンドが必要である): >
+
+	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
+
+コマンドラインを終了するときに補完リストの最初の項目を自動的に選択し、`:Grep`
+の場合は入力したパターンをコマンドライン履歴に追加する: >
+
+	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
+
+挿入モードでの自動補完については、|ins-autocompletion| を参照。
+
  vim:tw=78:ts=8:noet:ft=help:norl:

en/cmdline.txt

@@ -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 10
 
 
 		  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: