From 5f2c47c44c984e58887ac8c62f6319f75128cb13 Mon Sep 17 00:00:00 2001 From: Brad King Date: Mon, 14 Sep 2015 10:35:50 -0400 Subject: [PATCH] Help: Organize string command docs into sections Add section headers and titles for each command signature. Group related commands into sections. --- Help/command/string.rst | 318 ++++++++++++++++++++++++++++------------ 1 file changed, 227 insertions(+), 91 deletions(-) diff --git a/Help/command/string.rst b/Help/command/string.rst index 20f8094d4..4d6c0d068 100644 --- a/Help/command/string.rst +++ b/Help/command/string.rst @@ -1,102 +1,81 @@ string ------ +.. only:: html + + .. contents:: + String operations. +Search and Replace +^^^^^^^^^^^^^^^^^^ + +FIND +"""" + +:: + + string(FIND [REVERSE]) + +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. + +REPLACE +""""""" + +:: + + string(REPLACE + + [...]) + +Replace all occurrences of ``match_string`` in the input +with ``replace_string`` and store the result in the output. + +Regular Expressions +^^^^^^^^^^^^^^^^^^^ + +REGEX MATCH +""""""""""" + :: string(REGEX MATCH [...]) + +Match the regular expression once and store the match in the output variable. + +REGEX MATCHALL +"""""""""""""" + +:: + string(REGEX MATCHALL [...]) + +Match the regular expression as many times as possible and store the matches +in the output variable as a list. + +REGEX REPLACE +""""""""""""" + +:: + string(REGEX REPLACE [...]) - string(REPLACE - - [...]) - string(APPEND [...]) - string(CONCAT [...]) - string( - ) - string(COMPARE EQUAL ) - string(COMPARE NOTEQUAL ) - string(COMPARE LESS ) - string(COMPARE GREATER ) - string(ASCII [ ...] ) - string(CONFIGURE - [@ONLY] [ESCAPE_QUOTES]) - string(TOUPPER ) - string(TOLOWER ) - string(LENGTH ) - string(SUBSTRING ) - string(STRIP ) - string(RANDOM [LENGTH ] [ALPHABET ] - [RANDOM_SEED ] ) - string(FIND [REVERSE]) - string(TIMESTAMP [] [UTC]) - string(MAKE_C_IDENTIFIER ) - string(GENEX_STRIP ) - string(UUID NAMESPACE NAME - TYPE [UPPER]) -``REGEX MATCH`` will match the regular expression once and store the match -in the output variable. +Match the regular expression as many times as possible and substitute the +replacement expression for the match in the output. -``REGEX MATCHALL`` will match the regular expression as many times as -possible and store the matches in the output variable as a list. +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 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 -with ``replace_string`` and store the result in the output. - -``APPEND`` will append all the input arguments to the string. - -``CONCAT`` will concatenate all the input arguments together and store -the result in the named output variable. - -``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. - -``ASCII`` will convert all numbers into corresponding ASCII characters. - -``CONFIGURE`` will transform a string like :command:`configure_file` -transforms a file. - -``TOUPPER``/``TOLOWER`` will convert string to upper/lower characters. - -``LENGTH`` will return a given string's length. - -``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. - -.. note:: - CMake 3.1 and below reported an error if length pointed past - the end of string. - -``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. - -``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. +Regex Specification +""""""""""""""""""" The following characters have special meaning in regular expressions: @@ -123,10 +102,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``. -``TIMESTAMP`` will write a string representation of the current date +Manipulation +^^^^^^^^^^^^ + +APPEND +"""""" + +:: + + string(APPEND [...]) + +Append all the input arguments to the string. + +CONCAT +"""""" + +:: + + string(CONCAT [...]) + +Concatenate all the input arguments together and store +the result in the named output variable. + +TOLOWER +""""""" + +:: + + string(TOLOWER ) + +Convert string to lower characters. + +TOUPPER +""""""" + +:: + + string(TOUPPER ) + +Convert string to upper characters. + +LENGTH +"""""" + +:: + + string(LENGTH ) + +Store in an output variable a given string's length. + +SUBSTRING +""""""""" + +:: + + string(SUBSTRING ) + +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 ) + +Store in an output variable a substring of a given string with leading and +trailing spaces removed. + +GENEX_STRIP +""""""""""" + +:: + + string(GENEX_STRIP ) + +Strip any :manual:`generator expressions ` +from the ``input string`` and store the result in the ``output variable``. + +Comparison +^^^^^^^^^^ + +:: + + string(COMPARE EQUAL ) + string(COMPARE NOTEQUAL ) + string(COMPARE LESS ) + string(COMPARE GREATER ) + +Compare the strings and store true or false in the output variable. + +Hashing +^^^^^^^ + +:: + + string( + ) + +Compute a cryptographic hash of the input string. + +Generation +^^^^^^^^^^ + +ASCII +""""" + +:: + + string(ASCII [ ...] ) + +Convert all numbers into corresponding ASCII characters. + +CONFIGURE +""""""""" + +:: + + string(CONFIGURE + [@ONLY] [ESCAPE_QUOTES]) + +Transform a string like :command:`configure_file` transforms a file. + +RANDOM +"""""" + +:: + + string(RANDOM [LENGTH ] [ALPHABET ] + [RANDOM_SEED ] ) + +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 [] [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 +291,22 @@ If no explicit ```` 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 ` from the -``input string`` and store the result in the ``output variable``. +:: -``UUID`` creates a univerally unique identifier (aka GUID) as per RFC4122 + string(MAKE_C_IDENTIFIER ) + +Write a string which can be used as an identifier in C. + +UUID +"""" + +:: + + string(UUID NAMESPACE NAME + TYPE [UPPER]) + +Create a univerally unique identifier (aka GUID) as per RFC4122 based on the hash of the combined values of ```` (which itself has to be a valid UUID) and ````. The hash algorithm can be either ``MD5`` (Version 3 UUID) or