Merge topic 'doc-string-REGEX-concat'

3809150a Help: Document string(REGEX) input concatentation (#15742)
5f2c47c4 Help: Organize string command docs into sections

1 files changed, 221 insertions, 82 deletions

diff --git a/Help/command/string.rst b/Help/command/string.rst
index 20f8094..0361c74 100644
--- a/Help/command/string.rst
+++ b/Help/command/string.rst
@@ -1,102 +1,84 @@
 string
 ------
 
+.. only:: html
+
+   .. contents::
+
 String operations.
 
+Search and Replace
+^^^^^^^^^^^^^^^^^^
+
+FIND
+""""
+
 ::
 
-  string(REGEX MATCH <regular_expression>
-         <output variable> <input> [<input>...])
-  string(REGEX MATCHALL <regular_expression>
-         <output variable> <input> [<input>...])
-  string(REGEX REPLACE <regular_expression>
-         <replace_expression> <output variable>
-         <input> [<input>...])
-  string(REPLACE <match_string>
-         <replace_string> <output variable>
-         <input> [<input>...])
-  string(APPEND <string variable> [<input>...])
-  string(CONCAT <output variable> [<input>...])
-  string(<MD5|SHA1|SHA224|SHA256|SHA384|SHA512>
-         <output variable> <input>)
-  string(COMPARE EQUAL <string1> <string2> <output variable>)
-  string(COMPARE NOTEQUAL <string1> <string2> <output variable>)
-  string(COMPARE LESS <string1> <string2> <output variable>)
-  string(COMPARE GREATER <string1> <string2> <output variable>)
-  string(ASCII <number> [<number> ...] <output variable>)
-  string(CONFIGURE <string1> <output variable>
-         [@ONLY] [ESCAPE_QUOTES])
-  string(TOUPPER <string1> <output variable>)
-  string(TOLOWER <string1> <output variable>)
-  string(LENGTH <string> <output variable>)
-  string(SUBSTRING <string> <begin> <length> <output variable>)
-  string(STRIP <string> <output variable>)
-  string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>]
-         [RANDOM_SEED <seed>] <output variable>)
   string(FIND <string> <substring> <output variable> [REVERSE])
-  string(TIMESTAMP <output variable> [<format string>] [UTC])
-  string(MAKE_C_IDENTIFIER <input string> <output variable>)
-  string(GENEX_STRIP <input string> <output variable>)
-  string(UUID <output variable> NAMESPACE <namespace> NAME <name>
-         TYPE <MD5|SHA1> [UPPER])
 
-``REGEX MATCH`` will match the regular expression once and store the match
-in the output variable.
+Return the position where the given substring was found in
+the supplied string.  If the ``REVERSE`` flag was used, the command will
+search for the position of the last occurrence of the specified
+substring.  If the substring is not found, a position of -1 is returned.
 
-``REGEX MATCHALL`` will match the regular expression as many times as
-possible and store the matches in the output variable as a list.
+REPLACE
+"""""""
 
-``REGEX REPLACE`` will match the regular expression as many times as
-possible and substitute the replacement expression for the match in
-the output.  The replace expression may refer to paren-delimited
-subexpressions of the match using \1, \2, ..., \9.  Note that two
-backslashes (\\1) are required in CMake code to get a backslash
-through argument parsing.
+::
 
-``REPLACE`` will replace all occurrences of ``match_string`` in the input
+  string(REPLACE <match_string>
+         <replace_string> <output variable>
+         <input> [<input>...])
+
+Replace all occurrences of ``match_string`` in the input
 with ``replace_string`` and store the result in the output.
 
-``APPEND`` will append all the input arguments to the string.
+Regular Expressions
+^^^^^^^^^^^^^^^^^^^
 
-``CONCAT`` will concatenate all the input arguments together and store
-the result in the named output variable.
+REGEX MATCH
+"""""""""""
 
-``MD5``, ``SHA1``, ``SHA224``, ``SHA256``, ``SHA384``, and ``SHA512`` will
-compute a cryptographic hash of the input string.
+::
 
-``COMPARE EQUAL``/``COMPARE NOTEQUAL``/``COMPARE LESS/GREATER`` will
-compare the strings and store true or false in the output variable.
+  string(REGEX MATCH <regular_expression>
+         <output variable> <input> [<input>...])
 
-``ASCII`` will convert all numbers into corresponding ASCII characters.
+Match the regular expression once and store the match in the output variable.
+All ``<input>`` arguments are concatenated before matching.
 
-``CONFIGURE`` will transform a string like :command:`configure_file`
-transforms a file.
+REGEX MATCHALL
+""""""""""""""
 
-``TOUPPER``/``TOLOWER`` will convert string to upper/lower characters.
+::
 
-``LENGTH`` will return a given string's length.
+  string(REGEX MATCHALL <regular_expression>
+         <output variable> <input> [<input>...])
 
-``SUBSTRING`` will return a substring of a given string. If length is -1
-the remainder of the string starting at begin will be returned.
-If string is shorter than length then end of string is used instead.
+Match the regular expression as many times as possible and store the matches
+in the output variable as a list.
+All ``<input>`` arguments are concatenated before matching.
 
-.. note::
-  CMake 3.1 and below reported an error if length pointed past
-  the end of string.
+REGEX REPLACE
+"""""""""""""
 
-``STRIP`` will return a substring of a given string with leading and
-trailing spaces removed.
+::
 
-``RANDOM`` will return a random string of given length consisting of
-characters from the given alphabet.  Default length is 5 characters
-and default alphabet is all numbers and upper and lower case letters.
-If an integer ``RANDOM_SEED`` is given, its value will be used to seed the
-random number generator.
+  string(REGEX REPLACE <regular_expression>
+         <replace_expression> <output variable>
+         <input> [<input>...])
 
-``FIND`` will return the position where the given substring was found in
-the supplied string.  If the ``REVERSE`` flag was used, the command will
-search for the position of the last occurrence of the specified
-substring.  If the substring is not found, a position of -1 is returned.
+Match the regular expression as many times as possible and substitute the
+replacement expression for the match in the output.
+All ``<input>`` arguments are concatenated before matching.
+
+The replace expression may refer to paren-delimited subexpressions of the
+match using ``\1``, ``\2``, ..., ``\9``.  Note that two backslashes (``\\1``)
+are required in CMake code to get a backslash through argument parsing.
+
+Regex Specification
+"""""""""""""""""""
 
 The following characters have special meaning in regular expressions:
 
@@ -123,10 +105,159 @@ The following characters have special meaning in regular expressions:
 
 ``*``, ``+`` 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".
+expression ``^ab+d$`` matches ``abbd`` but not ``ababd``, and the regular
+expression ``^(ab|cd)$`` matches ``ab`` but not ``abd``.
+
+Manipulation
+^^^^^^^^^^^^
+
+APPEND
+""""""
+
+::
+
+  string(APPEND <string variable> [<input>...])
+
+Append all the input arguments to the string.
+
+CONCAT
+""""""
+
+::
+
+  string(CONCAT <output variable> [<input>...])
+
+Concatenate all the input arguments together and store
+the result in the named output variable.
+
+TOLOWER
+"""""""
+
+::
+
+  string(TOLOWER <string1> <output variable>)
+
+Convert string to lower characters.
+
+TOUPPER
+"""""""
 
-``TIMESTAMP`` will write a string representation of the current date
+::
+
+  string(TOUPPER <string1> <output variable>)
+
+Convert string to upper characters.
+
+LENGTH
+""""""
+
+::
+
+  string(LENGTH <string> <output variable>)
+
+Store in an output variable a given string's length.
+
+SUBSTRING
+"""""""""
+
+::
+
+  string(SUBSTRING <string> <begin> <length> <output variable>)
+
+Store in an output variable a substring of a given string.  If length is
+``-1`` the remainder of the string starting at begin will be returned.
+If string is shorter than length then end of string is used instead.
+
+.. note::
+  CMake 3.1 and below reported an error if length pointed past
+  the end of string.
+
+STRIP
+"""""
+
+::
+
+  string(STRIP <string> <output variable>)
+
+Store in an output variable a substring of a given string with leading and
+trailing spaces removed.
+
+GENEX_STRIP
+"""""""""""
+
+::
+
+  string(GENEX_STRIP <input string> <output variable>)
+
+Strip any :manual:`generator expressions <cmake-generator-expressions(7)>`
+from the ``input string`` and store the result in the ``output variable``.
+
+Comparison
+^^^^^^^^^^
+
+::
+
+  string(COMPARE EQUAL <string1> <string2> <output variable>)
+  string(COMPARE NOTEQUAL <string1> <string2> <output variable>)
+  string(COMPARE LESS <string1> <string2> <output variable>)
+  string(COMPARE GREATER <string1> <string2> <output variable>)
+
+Compare the strings and store true or false in the output variable.
+
+Hashing
+^^^^^^^
+
+::
+
+  string(<MD5|SHA1|SHA224|SHA256|SHA384|SHA512>
+         <output variable> <input>)
+
+Compute a cryptographic hash of the input string.
+
+Generation
+^^^^^^^^^^
+
+ASCII
+"""""
+
+::
+
+  string(ASCII <number> [<number> ...] <output variable>)
+
+Convert all numbers into corresponding ASCII characters.
+
+CONFIGURE
+"""""""""
+
+::
+
+  string(CONFIGURE <string1> <output variable>
+         [@ONLY] [ESCAPE_QUOTES])
+
+Transform a string like :command:`configure_file` transforms a file.
+
+RANDOM
+""""""
+
+::
+
+  string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>]
+         [RANDOM_SEED <seed>] <output variable>)
+
+Return a random string of given length consisting of
+characters from the given alphabet.  Default length is 5 characters
+and default alphabet is all numbers and upper and lower case letters.
+If an integer ``RANDOM_SEED`` is given, its value will be used to seed the
+random number generator.
+
+TIMESTAMP
+"""""""""
+
+::
+
+  string(TIMESTAMP <output variable> [<format string>] [UTC])
+
+Write a string representation of the current date
 and/or time to the output variable.
 
 Should the command be unable to obtain a timestamp the output variable
@@ -163,14 +294,22 @@ If no explicit ``<format string>`` is given it will default to:
    %Y-%m-%dT%H:%M:%S    for local time.
    %Y-%m-%dT%H:%M:%SZ   for UTC.
 
-``MAKE_C_IDENTIFIER`` will write a string which can be used as an
-identifier in C.
 
-``GENEX_STRIP`` will strip any
-:manual:`generator expressions <cmake-generator-expressions(7)>` from the
-``input string`` and store the result in the ``output variable``.
+::
+
+  string(MAKE_C_IDENTIFIER <input string> <output variable>)
+
+Write a string which can be used as an identifier in C.
+
+UUID
+""""
+
+::
+
+  string(UUID <output variable> NAMESPACE <namespace> NAME <name>
+         TYPE <MD5|SHA1> [UPPER])
 
-``UUID`` creates a univerally unique identifier (aka GUID) as per RFC4122
+Create a univerally unique identifier (aka GUID) as per RFC4122
 based on the hash of the combined values of ``<namespace>``
 (which itself has to be a valid UUID) and ``<name>``.
 The hash algorithm can be either ``MD5`` (Version 3 UUID) or