patch 9.1.1576: cannot easily trigger wildcard expansion

Problem:  cannot easily trigger wildcard expansion
Solution: Introduce wildtrigger() function
          (Girish Palya)

This PR introduces a new `wildtrigger()` function.

See `:h wildtrigger()`

`wildtrigger()` behaves like pressing the `wildchar,` but provides a
more refined and controlled completion experience:

- Suppresses beeps when no matches are found.
- Avoids displaying irrelevant completions (like full command lists)
  when the prefix is insufficient or doesn't match.
- Skips completion if the typeahead buffer has pending input or if a
  wildmenu is already active.
- Does not print "..." before completion.

This is an improvement on the `feedkeys()` based autocompletion script
given in #16759.

closes: #17806

Signed-off-by: Girish Palya <girishji@gmail.com>
Co-authored-by: zeertzjq <zeertzjq@outlook.com>
Signed-off-by: Christian Brabandt <cb@256bit.org>

runtime/doc/builtin.txt

@@ -1,4 +1,4 @@
-*builtin.txt*	For Vim version 9.1.  Last change: 2025 Jul 17
+*builtin.txt*	For Vim version 9.1.  Last change: 2025 Jul 21
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -757,6 +757,7 @@ virtcol2col({winid}, {lnum}, {col})
 				Number  byte index of a character on screen
 visualmode([{expr}])		String	last visual mode used
 wildmenumode()			Number	whether 'wildmenu' mode is active
+wildtrigger()			Number	start wildcard expansion
 win_execute({id}, {command} [, {silent}])
 				String	execute {command} in window {id}
 win_findbuf({bufnr})		List	find windows containing {bufnr}
@@ -12331,6 +12332,33 @@ wildmenumode()					*wildmenumode()*
 		Return type: |Number|
 
 
+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|.
+
+		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|.
+							*cmdline-autocompletion*
+		Example: To make the completion menu pop up automatically as
+		you type on the command line, use: >
+			autocmd CmdlineChanged [:/?] call wildtrigger()
+			set wildmode=noselect:lastused,full wildoptions=pum
+<
+		To retain normal history navigation (up/down keys): >
+			cnoremap <Up>   <C-U><Up>
+			cnoremap <Down> <C-U><Down>
+<
+		Return value is always 0.
+
+		Return type: |Number|
+
+
 win_execute({id}, {command} [, {silent}])		*win_execute()*
 		Like `execute()` but in the context of window {id}.
 		The window will temporarily be made the current window,

runtime/doc/cmdline.txt

@@ -1,4 +1,4 @@
-*cmdline.txt*   For Vim version 9.1.  Last change: 2025 Jun 28
+*cmdline.txt*   For Vim version 9.1.  Last change: 2025 Jul 21
 
 
 		  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -479,6 +479,8 @@ 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.
 

runtime/doc/options.txt

@@ -1,4 +1,4 @@
-*options.txt*	For Vim version 9.1.  Last change: 2025 Jul 20
+*options.txt*	For Vim version 9.1.  Last change: 2025 Jul 21
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -9797,7 +9797,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 <	'wildchar' also enables completion in search pattern contexts such as
 	|/|, |?|, |:s|, |:g|, |:v|, and |:vim|.  To insert a literal <Tab>
 	instead of triggering completion, type <C-V><Tab> or "\t".
-	See also |'wildoptions'|.
+	See also 'wildoptions' and |wildtrigger()|.
 	NOTE: This option is set to the Vi default value when 'compatible' is
 	set and to the Vim default value when 'compatible' is reset.
 

runtime/doc/tags

@@ -6620,6 +6620,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-changed	version5.txt	/*cmdline-changed*
 cmdline-completion	cmdline.txt	/*cmdline-completion*
 cmdline-editing	cmdline.txt	/*cmdline-editing*
@@ -11608,6 +11609,7 @@ whitespace	pattern.txt	/*whitespace*
 wildcard	editing.txt	/*wildcard*
 wildcards	editing.txt	/*wildcards*
 wildmenumode()	builtin.txt	/*wildmenumode()*
+wildtrigger()	builtin.txt	/*wildtrigger()*
 win-scrolled-resized	windows.txt	/*win-scrolled-resized*
 win16	os_win32.txt	/*win16*
 win32	os_win32.txt	/*win32*

runtime/doc/usr_41.txt

@@ -1,4 +1,4 @@
-*usr_41.txt*	For Vim version 9.1.  Last change: 2025 Jul 05
+*usr_41.txt*	For Vim version 9.1.  Last change: 2025 Jul 21
 
 		     VIM USER MANUAL - by Bram Moolenaar
 
@@ -1233,6 +1233,7 @@ Mappings and Menus:			    *mapping-functions*
 	mapset()		restore a mapping
 	menu_info()		get information about a menu item
 	wildmenumode()		check if the wildmode is active
+	wildtrigger()		start wildcard expansion
 
 Testing:				    *test-functions*
 	assert_equal()		assert that two expressions values are equal

runtime/doc/version9.txt

@@ -1,4 +1,4 @@
-*version9.txt*  For Vim version 9.1.  Last change: 2025 Jul 20
+*version9.txt*  For Vim version 9.1.  Last change: 2025 Jul 21
 
 
 		  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -41601,6 +41601,7 @@ Completion~
 	"nosort"	- do not sort completion results
 	"preinsert"	- highlight to be inserted values
 	"nearest"	- sort completion results by distance to cursor
+- new function |wildtrigger()| to trigger wildcard expansion
 
 Platform specific~
 -----------------
@@ -41765,6 +41766,7 @@ Functions: ~
 |str2blob()|		convert a List of strings into a blob
 |test_null_tuple()|	return a null tuple
 |tuple2list()|		turn a Tuple of items into a List
+|wildtrigger()|		trigger wildcard expansion
 
 
 Autocommands: ~