Merge pull request #30979 from zeertzjq/vim-9.1.0810

vim-patch:9.1.{0810,0811,0821}: 'findexpr'

3 files changed, 57 insertions, 1 deletions

diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index 90f7f56ca2..7f95a19918 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -2598,6 +2598,55 @@ 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'* *E1514*
+'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'.
+
+	The expression may be evaluated for command-line completion as well,
+	in which case the |v:cmdcomplete| variable will be set to |v:true|,
+	otherwise it will be set to |v:false|.
+
+	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()
+		let pat = v:cmdcomplete ? $'{v:fname}*' : v:fname
+		return glob(pat, 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..1c1d88c29c 100644
--- a/runtime/doc/vvars.txt
+++ b/runtime/doc/vvars.txt
@@ -48,6 +48,11 @@ v:cmdbang
 		can only be used in autocommands.  For user commands |<bang>|
 		can be used.
 
+				*v:cmdcomplete* *cmdcomplete-variable*
+v:cmdcomplete
+		When evaluating 'findexpr': if 'findexpr' is used for cmdline
+		completion the value is |v:true|, otherwise it is |v:false|.
+
 					*v:collate* *collate-variable*
 v:collate
 		The current locale setting for collation order of the runtime
@@ -254,7 +259,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