From 7e1a4567fbe01133349b61452f89c4c33f237150 Mon Sep 17 00:00:00 2001 From: Craig Scott Date: Sat, 5 Nov 2022 21:05:59 +1100 Subject: Help: Make VALIDATOR wording clearer and more precise --- Help/command/FIND_XXX.txt | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt index 59a4e71..bd55e24 100644 --- a/Help/command/FIND_XXX.txt +++ b/Help/command/FIND_XXX.txt @@ -70,23 +70,28 @@ Options include: ``VALIDATOR`` .. versionadded:: 3.25 - Specify a :command:`function` (a :command:`macro` is not an acceptable - choice) which will be called for each found item. The search ends when - the validation function returns a successful status. - - The validation function expects two arguments: output variable name and item - value. By default, the output variable name already holds a ``TRUE`` value. + Specify a :command:`function` to be called for each candidate item found + (a :command:`macro` cannot be provided, that will result in an error). + Two arguments will be passed to the validator function: the name of a + result variable, and the absolute path to the candidate item. The item + will be accepted and the search will end unless the function sets the + value in the result variable to false in the calling scope. The result + variable will hold a true value when the validator function is entered. .. parsed-literal:: - function (MY_CHECK output_status item) - if (NOT item MATCHES ...) - set(${output_status} FALSE PARENT_SCOPE) + function(my_check validator_result_var item) + if(NOT item MATCHES ...) + set(${validator_result_var} FALSE PARENT_SCOPE) endif() endfunction() |FIND_XXX| (result NAMES ... VALIDATOR my_check) + Note that if a cached result is used, the search is skipped and any + ``VALIDATOR`` is ignored. The cached result is not required to pass the + validation function. + ``DOC`` Specify the documentation string for the ```` cache entry. -- cgit v0.12