Merge pull request #30979 from zeertzjq/vim-9.1.0810

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

5 files changed, 120 insertions, 2 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
diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua
index 00f7554832..710f82bf21 100644
--- a/runtime/lua/vim/_meta/options.lua
+++ b/runtime/lua/vim/_meta/options.lua
@@ -2294,6 +2294,62 @@ 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'.
+---
+--- 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()
+--- ```
+---
+---
+--- @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..b104356334 100644
--- a/runtime/lua/vim/_meta/vvars.lua
+++ b/runtime/lua/vim/_meta/vvars.lua
@@ -44,6 +44,11 @@ vim.v.cmdarg = ...
 --- @type integer
 vim.v.cmdbang = ...
 
+--- When evaluating 'findexpr': if 'findexpr' is used for cmdline
+--- completion the value is `v:true`, otherwise it is `v:false`.
+--- @type boolean
+vim.v.cmdcomplete = ...
+
 --- The current locale setting for collation order of the runtime
 --- environment.  This allows Vim scripts to be aware of the
 --- current locale encoding.  Technical: it's the value of
@@ -267,7 +272,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 = ...