list: Add FILTER subcommand (#3986)

Create a `list(FILTER)` command to filter lists by regular expression.

2 files changed, 15 insertions, 3 deletions

diff --git a/Help/command/list.rst b/Help/command/list.rst
index a7a05c7..f6b75bc 100644
--- a/Help/command/list.rst
+++ b/Help/command/list.rst
@@ -9,6 +9,7 @@ List operations.
   list(GET <list> <element index> [<element index> ...]
        <output variable>)
   list(APPEND <list> [<element> ...])
+  list(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>)
   list(FIND <list> <value> <output variable>)
   list(INSERT <list> <element_index> <element> [<element> ...])
   list(REMOVE_ITEM <list> <value> [<value> ...])
@@ -23,6 +24,12 @@ List operations.
 
 ``APPEND`` will append elements to the list.
 
+``FILTER`` will include or remove items from the list that match the
+mode's pattern.
+In ``REGEX`` mode, items will be matched against the given regular expression.
+For more information on regular expressions see also the :command:`string`
+command.
+
 ``FIND`` will return the index of the element specified in the list or -1
 if it wasn't found.
 
@@ -38,9 +45,9 @@ difference is that ``REMOVE_ITEM`` will remove the given items, while
 
 ``SORT`` sorts the list in-place alphabetically.
 
-The list subcommands ``APPEND``, ``INSERT``, ``REMOVE_AT``, ``REMOVE_ITEM``,
-``REMOVE_DUPLICATES``, ``REVERSE`` and ``SORT`` may create new values for
-the list within the current CMake variable scope.  Similar to the
+The list subcommands ``APPEND``, ``INSERT``, ``FILTER``, ``REMOVE_AT``,
+``REMOVE_ITEM``, ``REMOVE_DUPLICATES``, ``REVERSE`` and ``SORT`` may create new
+values for the list within the current CMake variable scope.  Similar to the
 :command:`set` command, the LIST command creates new variable values in the
 current scope, even if the list itself is actually defined in a parent
 scope.  To propagate the results of these operations upwards, use
diff --git a/Help/release/dev/list-FILTER-command.rst b/Help/release/dev/list-FILTER-command.rst
new file mode 100644
index 0000000..3fee4f0
--- /dev/null
+++ b/Help/release/dev/list-FILTER-command.rst
@@ -0,0 +1,5 @@
+list-FILTER-command
+-------------------
+
+* The :command:`list` command gained a ``FILTER`` sub-command to filter
+  list elements by regular expression.