patch 9.1.0810: cannot easily adjust the |:find| command

Problem:  cannot easily adjust the |:find| command
Solution: Add support for the 'findexpr' option (Yegappan Lakshmanan)

closes: #15901
closes: #15905

Signed-off-by: Yegappan Lakshmanan <yegappan@yahoo.com>
Signed-off-by: Christian Brabandt <cb@256bit.org>

runtime/doc/eval.txt

@@ -1,4 +1,4 @@
-*eval.txt*	For Vim version 9.1.  Last change: 2024 Jul 28
+*eval.txt*	For Vim version 9.1.  Last change: 2024 Oct 22
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -2223,7 +2223,8 @@ v:fcs_choice	What should happen after a |FileChangedShell| event was
 
 					*v:fname* *fname-variable*
 v:fname		When evaluating 'includeexpr': the file name that was
-		detected.  Empty otherwise.
+		detected.  When evaluating 'findexpr': the argument passed to
+		the |:find| command.  Empty otherwise.
 
 					*v:fname_in* *fname_in-variable*
 v:fname_in	The name of the input file.  Valid while evaluating:

runtime/doc/options.txt

@@ -3552,6 +3552,51 @@ A jump table for the options with a short description can be found at |Q_op|.
 	  eob		EndOfBuffer		|hl-EndOfBuffer|
 	  lastline	NonText			|hl-NonText|
 
+						*'findexpr'* *'fexpr'*
+'findexpr' 'fexpr'	string	(default "")
+			global or local to buffer |global-local|
+			{not available when compiled without the |+eval|
+			feature}
+	Expression that is evaluated to obtain the filename(s) for the |:find|
+	command.  When this option is empty, the internal |file-searching|
+	mechanism is used.
+
+	While evaluating the expression, the |v:fname| variable is set to the
+	argument of the |:find| command.
+
+	The expression is evaluated only once per |:find| command invocation.
+	The expression can process all the directories specified in 'path'.
+
+	If a match is found, the expression should return a |List| containing
+	one or more file names.  If a match is not found, the expression
+	should return an empty List.
+
+	If any errors are encountered during the expression evaluation, an
+	empty List is used as the return value.
+
+	Using a function call without arguments is faster |expr-option-function|
+
+	It is not allowed to change text or jump to another window while
+	evaluating 'findexpr' |textlock|.
+
+	This option cannot be set from a |modeline| or in the |sandbox|, for
+	security reasons.
+
+	Examples:
+>
+	    " Use glob()
+	    func FindExprGlob()
+		return glob(v:fname, v:false, v:true)
+	    endfunc
+	    set findexpr=FindExprGlob()
+
+	    " Use the 'git ls-files' output
+	    func FindGitFiles()
+		let fnames = systemlist('git ls-files')
+		return fnames->filter('v:val =~? v:fname')
+	    endfunc
+	    set findexpr=FindGitFiles()
+<
 		*'fixendofline'* *'fixeol'* *'nofixendofline'* *'nofixeol'*
 'fixendofline' 'fixeol'	boolean	(default on)
 			local to buffer

runtime/doc/quickref.txt

@@ -1,4 +1,4 @@
-*quickref.txt*  For Vim version 9.1.  Last change: 2024 Mar 03
+*quickref.txt*  For Vim version 9.1.  Last change: 2024 Oct 22
 
 
 		  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -707,6 +707,7 @@ Short explanation of each option:		*option-list*
 'fileignorecase'  'fic'     ignore case when using file names
 'filetype'	  'ft'	    type of file, used for autocommands
 'fillchars'	  'fcs'     characters to use for displaying special items
+'findexpr'	  'fexpr'   expression to evaluate for |:find|
 'fixendofline'	  'fixeol'  make sure last line in file has <EOL>
 'fkmap'		  'fk'	    obsolete option for Farsi
 'foldclose'	  'fcl'     close a fold when the cursor leaves it

runtime/doc/tags

@@ -267,6 +267,7 @@ $quote	eval.txt	/*$quote*
 'fenc'	options.txt	/*'fenc'*
 'fencs'	options.txt	/*'fencs'*
 'fex'	options.txt	/*'fex'*
+'fexpr'	options.txt	/*'fexpr'*
 'ff'	options.txt	/*'ff'*
 'ffs'	options.txt	/*'ffs'*
 'fic'	options.txt	/*'fic'*
@@ -277,6 +278,7 @@ $quote	eval.txt	/*$quote*
 'fileignorecase'	options.txt	/*'fileignorecase'*
 'filetype'	options.txt	/*'filetype'*
 'fillchars'	options.txt	/*'fillchars'*
+'findexpr'	options.txt	/*'findexpr'*
 'fixendofline'	options.txt	/*'fixendofline'*
 'fixeol'	options.txt	/*'fixeol'*
 'fk'	options.txt	/*'fk'*

runtime/doc/version9.txt

@@ -1,4 +1,4 @@
-*version9.txt*  For Vim version 9.1.  Last change: 2024 Oct 14
+*version9.txt*  For Vim version 9.1.  Last change: 2024 Oct 22
 
 
 		  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -41649,6 +41649,8 @@ Options: ~
 
 'completeitemalign'	Order of |complete-items| in Insert mode completion
 			popup
+'findexpr'		Vim expression to obtain the results for a |:find|
+			command
 'winfixbuf'		Keep buffer focused in a window
 'tabclose'		Which tab page to focus after closing a tab page
 't_xo'			Terminal uses XON/XOFF handshaking (e.g. vt420)