From 7350b58c162eb6d53f5b71a40251137d52edb9bf Mon Sep 17 00:00:00 2001 From: Tyler Yankee Date: Fri, 4 Sep 2026 13:59:13 -0400 Subject: [PATCH] Help: Move regex specification to cmake-language(7) Many other places in CMake beyond the `string` command rely on our regex syntax, so it should be documented in a more general location. Fixes: #22270 --- Help/command/cmake_language.rst | 8 +- Help/command/file.rst | 2 +- Help/command/if.rst | 4 +- Help/command/install.rst | 2 +- Help/command/list.rst | 4 +- Help/command/string.rst | 67 +--------------- Help/manual/cmake-generator-expressions.7.rst | 4 +- Help/manual/cmake-language.7.rst | 76 +++++++++++++++++++ Help/manual/ctest.1.rst | 4 +- Help/manual/presets/include-properties.rst | 4 +- Help/manual/presets/schema.yaml | 4 +- 11 files changed, 96 insertions(+), 83 deletions(-) diff --git a/Help/command/cmake_language.rst b/Help/command/cmake_language.rst index 1090354d05..ebfbb35c07 100644 --- a/Help/command/cmake_language.rst +++ b/Help/command/cmake_language.rst @@ -590,8 +590,8 @@ Printing Targets ``REGEX `` Only list targets whose name matches the given - :ref:`regular expression `. If no target matches, - a warning is issued. + :ref:`regular expression `. + If no target matches, a warning is issued. ``IGNORE_CASE`` Match the ``REGEX`` case-insensitively. Only valid with ``REGEX``. @@ -646,10 +646,10 @@ Printing Variables ``NAME_REGEX `` Print only variables whose name matches the given - :ref:`regular expression `. + :ref:`regular expression `. ``VALUE_REGEX `` Print only variables whose value matches the given - :ref:`regular expression `. + :ref:`regular expression `. ``IGNORE_CASE`` Lower-case both the pattern and the candidate string before matching, so ``NAME_REGEX`` and ``VALUE_REGEX`` match case-insensitively. diff --git a/Help/command/file.rst b/Help/command/file.rst index 5ddf4dacbb..d47d5173e7 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -114,7 +114,7 @@ Reading ``REGEX `` Consider only strings that match the given regular expression, - as described under :ref:`string(REGEX) `. + as described in the :ref:`CMake Language Regex Specification`. .. versionchanged:: 3.29 Capture groups from the last match in the file are stored in diff --git a/Help/command/if.rst b/Help/command/if.rst index 23f50925e7..8c7609a226 100644 --- a/Help/command/if.rst +++ b/Help/command/if.rst @@ -276,8 +276,8 @@ Comparisons :target: MATCHES True if the given string or variable's value matches the given regular - expression. See :ref:`Regex Specification` for regex format. ``()`` groups - are captured in :variable:`CMAKE_MATCH_` variables. + expression. See the :ref:`CMake Language Regex Specification` for regex + format. ``()`` groups are captured in :variable:`CMAKE_MATCH_` variables. .. signature:: if( LESS ) :target: LESS diff --git a/Help/command/install.rst b/Help/command/install.rst index ef922b577b..cc2b9ecc20 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -805,7 +805,7 @@ Signatures ``REGEX `` Match any portion of the full path of a file with a - :ref:`regular expression `. + :ref:`regular expression `. One may use ``/`` and ``$`` to limit matching to the end of a path. Each ```` may be followed by ```` arguments. diff --git a/Help/command/list.rst b/Help/command/list.rst index a72667dfa6..f64bd64795 100644 --- a/Help/command/list.rst +++ b/Help/command/list.rst @@ -135,8 +135,8 @@ Modification list(FILTER REGEX ) - For more information on regular expressions look under - :ref:`string(REGEX) `. + For more information on regular expressions, see the + :ref:`CMake Language Regex Specification`. ``PREDICATE`` Specify a user-defined :command:`function` as a predicate. diff --git a/Help/command/string.rst b/Help/command/string.rst index 35754f8ab3..8974cc8bf0 100644 --- a/Help/command/string.rst +++ b/Help/command/string.rst @@ -144,71 +144,8 @@ Search and Replace With Regular Expressions Regex Specification """"""""""""""""""" -The following characters have special meaning in regular expressions: - -``^`` - Matches at beginning of input -``$`` - Matches at end of input -``.`` - Matches any single character -``\`` - Matches the single character specified by ````. Use this to - match special regex characters, e.g. ``\.`` for a literal ``.`` - or ``\\`` for a literal backslash ``\``. Escaping a non-special - character is unnecessary but allowed, e.g. ``\a`` matches ``a``. -``[ ]`` - Matches any character(s) inside the brackets. - To match a literal ``]``, make it the first character, e.g., ``[]ab]``. -``[^ ]`` - Matches any character(s) not inside the brackets. - To not match a literal ``]``, make it the first character, e.g., ``[^]ab]``. -``-`` - Inside brackets, specifies an inclusive range between characters on - either side, e.g., ``[a-f]`` is ``[abcdef]``. - To match a literal ``-`` using brackets, make it the first or the last - character, e.g., ``[+*/-]`` matches basic mathematical operators. -``*`` - Matches preceding pattern zero or more times -``+`` - Matches preceding pattern one or more times -``?`` - Matches preceding pattern zero or once only -``|`` - Matches a pattern on either side of the ``|`` -``()`` - Saves a matched subexpression, which can be referenced - in the ``REGEX REPLACE`` operation. - - .. versionadded:: 3.9 - All regular expression-related commands, including e.g. - :command:`if(MATCHES)`, save subgroup matches in the variables - :variable:`CMAKE_MATCH_` for ```` 0..9. - -.. noqa: spellcheck off - -``*``, ``+`` and ``?`` have higher precedence than concatenation. ``|`` -has lower precedence than concatenation. This means that the regular -expression ``^ab+d$`` matches ``abbd`` but not ``ababd``, and the regular -expression ``^(ab|cd)$`` matches ``ab`` but not ``abd``. - -.. noqa: spellcheck on - -CMake language :ref:`Escape Sequences` such as ``\t``, ``\r``, ``\n``, -and ``\\`` may be used to construct literal tabs, carriage returns, -newlines, and backslashes (respectively) to pass in a regex. For example: - -* The quoted argument ``"[ \t\r\n]"`` specifies a regex that matches - any single whitespace character. -* The quoted argument ``"[/\\]"`` specifies a regex that matches - a single forward slash ``/`` or backslash ``\``. -* The quoted argument ``"[A-Za-z0-9_]"`` specifies a regex that matches - any single "word" character in the C locale. -* The quoted argument ``"\\(\\a\\+b\\)"`` specifies a regex that matches - the exact string ``(a+b)``. Each ``\\`` is parsed in a quoted argument - as just ``\``, so the regex itself is actually ``\(\a\+\b\)``. This - can alternatively be specified in a :ref:`bracket argument` without - having to escape the backslashes, e.g. ``[[\(\a\+\b\)]]``. +For more details on CMake's regular expression syntax, please refer to +:ref:`CMake Language Regex Specification`. Manipulation ^^^^^^^^^^^^ diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index bd517c6e70..72db5372b4 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -444,8 +444,8 @@ String Queries ``ALL`` Match as many times as possible and return the matches as a list. - See the :ref:`Regular expressions specification ` for - the syntax of the ``regular_expression`` parameter. + See the :ref:`CMake Language Regex Specification` for the syntax of the + ``regular_expression`` parameter. .. _`String Generating Generator Expressions`: diff --git a/Help/manual/cmake-language.7.rst b/Help/manual/cmake-language.7.rst index 777ef0b7ba..0a588c9a69 100644 --- a/Help/manual/cmake-language.7.rst +++ b/Help/manual/cmake-language.7.rst @@ -689,3 +689,79 @@ To avoid problems, consider the following advice: Note that this approach does not apply to :command:`macro` implementations because they reference arguments using placeholders, not real variables. + +.. _`CMake Language Regex Specification`: + +Regex Specification +=================== + +Several CMake commands accept regular expressions, including +:command:`string(REGEX ...) `, :command:`if(MATCHES)`, +:command:`list(FILTER)`, and others, as well as command-line options such as +:option:`ctest -L` and related modes. + +The following characters have special meaning in regular expressions: + +``^`` + Matches at beginning of input +``$`` + Matches at end of input +``.`` + Matches any single character +``\`` + Matches the single character specified by ````. Use this to + match special regex characters, e.g. ``\.`` for a literal ``.`` + or ``\\`` for a literal backslash ``\``. Escaping a non-special + character is unnecessary but allowed, e.g. ``\a`` matches ``a``. +``[ ]`` + Matches any character(s) inside the brackets. + To match a literal ``]``, make it the first character, e.g., ``[]ab]``. +``[^ ]`` + Matches any character(s) not inside the brackets. + To not match a literal ``]``, make it the first character, e.g., ``[^]ab]``. +``-`` + Inside brackets, specifies an inclusive range between characters on + either side, e.g., ``[a-f]`` is ``[abcdef]``. + To match a literal ``-`` using brackets, make it the first or the last + character, e.g., ``[+*/-]`` matches basic mathematical operators. +``*`` + Matches preceding pattern zero or more times +``+`` + Matches preceding pattern one or more times +``?`` + Matches preceding pattern zero or once only +``|`` + Matches a pattern on either side of the ``|`` +``()`` + Saves a matched subexpression, which can be referenced + in the ``REGEX REPLACE`` operation. + + .. versionadded:: 3.9 + All regular expression-related commands, including e.g. + :command:`if(MATCHES)`, save subgroup matches in the variables + :variable:`CMAKE_MATCH_` for ```` 0..9. + +.. noqa: spellcheck off + +``*``, ``+`` and ``?`` have higher precedence than concatenation. ``|`` +has lower precedence than concatenation. This means that the regular +expression ``^ab+d$`` matches ``abbd`` but not ``ababd``, and the regular +expression ``^(ab|cd)$`` matches ``ab`` but not ``abd``. + +.. noqa: spellcheck on + +CMake language :ref:`Escape Sequences` such as ``\t``, ``\r``, ``\n``, +and ``\\`` may be used to construct literal tabs, carriage returns, +newlines, and backslashes (respectively) to pass in a regex. For example: + +* The quoted argument ``"[ \t\r\n]"`` specifies a regex that matches + any single whitespace character. +* The quoted argument ``"[/\\]"`` specifies a regex that matches + a single forward slash ``/`` or backslash ``\``. +* The quoted argument ``"[A-Za-z0-9_]"`` specifies a regex that matches + any single "word" character in the C locale. +* The quoted argument ``"\\(\\a\\+b\\)"`` specifies a regex that matches + the exact string ``(a+b)``. Each ``\\`` is parsed in a quoted argument + as just ``\``, so the regex itself is actually ``\(\a\+\b\)``. This + can alternatively be specified in a :ref:`bracket argument` without + having to escape the backslashes, e.g. ``[[\(\a\+\b\)]]``. diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index ec7775f889..5208ca12df 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -274,8 +274,8 @@ The options for running tests are: .. option:: -L , --label-regex - Run tests with labels matching regular expression as described under - :ref:`string(REGEX) `. + Run tests with labels matching regular expression as described in the + :ref:`CMake Language Regex Specification`. This option tells CTest to run only the tests whose labels match the given regular expression. When more than one ``-L`` option is given, diff --git a/Help/manual/presets/include-properties.rst b/Help/manual/presets/include-properties.rst index b55c0e1046..56c362ee62 100644 --- a/Help/manual/presets/include-properties.rst +++ b/Help/manual/presets/include-properties.rst @@ -8,8 +8,8 @@ Equivalent to passing :ctest-option:`--tests-regex` on the command line. This field supports `macro expansion`_. - CMake regex syntax is described under - :ref:`string(REGEX) `. + See the :ref:`CMake Language Regex Specification` for the + regex syntax. .. _`CMakePresets.testPresets.filter.include.label`: diff --git a/Help/manual/presets/schema.yaml b/Help/manual/presets/schema.yaml index 4376e54f24..1730e7ce66 100644 --- a/Help/manual/presets/schema.yaml +++ b/Help/manual/presets/schema.yaml @@ -1434,8 +1434,8 @@ properties: Equivalent to passing :ctest-option:`--tests-regex` on the command line. This field supports `macro expansion`_. - CMake regex syntax is described under - :ref:`string(REGEX) `. + See the :ref:`CMake Language Regex Specification` for the + regex syntax. label: type: string description: