vim-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: vim/vim#15901
closes: vim/vim#15905

https://github.com/vim/vim/commit/aeb1c97db5b9de4f4903e7f288f2aa5ad6c49440

Co-authored-by: Yegappan Lakshmanan <yegappan@yahoo.com>

5 files changed, 100 insertions, 2 deletions

diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index 90f7f56ca2..17b2d22173 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -2598,6 +2598,50 @@ 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|
+	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:
+	>vim
+	    " 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
diff --git a/runtime/doc/quickref.txt b/runtime/doc/quickref.txt
index d77750b485..f64865a031 100644
--- a/runtime/doc/quickref.txt
+++ b/runtime/doc/quickref.txt
@@ -705,6 +705,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>
 'foldclose'	  'fcl'     close a fold when the cursor leaves it
 'foldcolumn'	  'fdc'     width of the column used to indicate folds
diff --git a/runtime/doc/vvars.txt b/runtime/doc/vvars.txt
index 15d836a83d..3f9ce8cc96 100644
--- a/runtime/doc/vvars.txt
+++ b/runtime/doc/vvars.txt
@@ -254,7 +254,8 @@ v:fcs_reason
 					*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_diff* *fname_diff-variable*
 v:fname_diff
diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua
index 00f7554832..8d5601ff6a 100644
--- a/runtime/lua/vim/_meta/options.lua
+++ b/runtime/lua/vim/_meta/options.lua
@@ -2294,6 +2294,57 @@ vim.wo.fcs = vim.wo.fillchars
 vim.go.fillchars = vim.o.fillchars
 vim.go.fcs = vim.go.fillchars
 
+--- 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:
+---
+--- ```vim
+---     " 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()
+--- ```
+---
+---
+--- @type string
+vim.o.findexpr = ""
+vim.o.fexpr = vim.o.findexpr
+vim.bo.findexpr = vim.o.findexpr
+vim.bo.fexpr = vim.bo.findexpr
+vim.go.findexpr = vim.o.findexpr
+vim.go.fexpr = vim.go.findexpr
+
 --- When writing a file and this option is on, <EOL> at the end of file
 --- will be restored if missing.  Turn this option off if you want to
 --- preserve the situation from the original file.
diff --git a/runtime/lua/vim/_meta/vvars.lua b/runtime/lua/vim/_meta/vvars.lua
index e00402ab3f..cba200101b 100644
--- a/runtime/lua/vim/_meta/vvars.lua
+++ b/runtime/lua/vim/_meta/vvars.lua
@@ -267,7 +267,8 @@ vim.v.fcs_choice = ...
 vim.v.fcs_reason = ...
 
 --- When evaluating 'includeexpr': the file name that was
---- detected.  Empty otherwise.
+--- detected.  When evaluating 'findexpr': the argument passed to
+--- the `:find` command.  Empty otherwise.
 --- @type string
 vim.v.fname = ...