Merge topic 'doc-regex-backslash'

fab2c2339b Help: Fix documentation of escape sequences in a regex

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !2460

1 files changed, 13 insertions, 6 deletions

diff --git a/Help/command/string.rst b/Help/command/string.rst
index 29a153a..cc18069 100644
--- a/Help/command/string.rst
+++ b/Help/command/string.rst
@@ -121,6 +121,11 @@ The following characters have special meaning in regular expressions:
   Matches at end of input
 ``.``
   Matches any single character
+``\<char>``
+  Matches the single character specified by ``<char>``.  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
 ``[^ ]``
@@ -151,12 +156,9 @@ 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``.
 
-Backslash (``\``) characters in regular expressions are interpreted
-literally and do not escape anything or represent placeholders.
-However, 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:
+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.
@@ -164,6 +166,11 @@ in a regex.  For example:
   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\)]]``.
 
 Manipulation
 ^^^^^^^^^^^^