From 5f2c47c44c984e58887ac8c62f6319f75128cb13 Mon Sep 17 00:00:00 2001 From: Brad King Date: Mon, 14 Sep 2015 10:35:50 -0400 Subject: 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 | 300 +++++++++++++++++++++++++++++++++++------------- 1 file changed, 218 insertions(+), 82 deletions(-) diff --git a/Help/command/string.rst b/Help/command/string.rst index 20f8094..4d6c0d0 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(REGEX MATCH - [...]) - string(REGEX MATCHALL - [...]) - 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. +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 + + [...]) + +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 + [...]) -``ASCII`` will convert all numbers into corresponding ASCII characters. +Match the regular expression once and store the match in the output variable. -``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 + [...]) -``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. -.. 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 + + [...]) -``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. + +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 +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``. + +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 +""""""" -``TIMESTAMP`` will write a string representation of the current date +:: + + 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``. +:: + + string(MAKE_C_IDENTIFIER ) + +Write a string which can be used as an identifier in C. + +UUID +"""" + +:: + + string(UUID NAMESPACE NAME + TYPE [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 ```` (which itself has to be a valid UUID) and ````. The hash algorithm can be either ``MD5`` (Version 3 UUID) or -- cgit v0.12 From 3809150a3895c5e15793a6801ca1bd0eb1ee61b1 Mon Sep 17 00:00:00 2001 From: Brad King Date: Mon, 14 Sep 2015 10:37:59 -0400 Subject: Help: Document string(REGEX) input concatentation (#15742) These commands concatenate all their input before matching. Document this behavior. --- Help/command/string.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Help/command/string.rst b/Help/command/string.rst index 4d6c0d0..0361c74 100644 --- a/Help/command/string.rst +++ b/Help/command/string.rst @@ -46,6 +46,7 @@ REGEX MATCH [...]) Match the regular expression once and store the match in the output variable. +All ```` arguments are concatenated before matching. REGEX MATCHALL """""""""""""" @@ -57,6 +58,7 @@ REGEX MATCHALL Match the regular expression as many times as possible and store the matches in the output variable as a list. +All ```` arguments are concatenated before matching. REGEX REPLACE """"""""""""" @@ -69,6 +71,7 @@ REGEX REPLACE Match the regular expression as many times as possible and substitute the replacement expression for the match in the output. +All ```` 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``) -- cgit v0.12