mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-02-17 12:40:40 -06:00
Code Issues Packages Projects Releases Wiki Activity

Help: Fix language and formatting inconsistencies for string() command

Browse Source
This commit is contained in:
Craig Scott
2019-07-16 22:03:15 +10:00
parent 79a21ba680
commit 26cd64d977
1 changed files with 85 additions and 81 deletions
Download Patch File Download Diff File Expand all files Collapse all files

166
Help/command/string.rst
View File

@@ -22,8 +22,8 @@ Synopsis
string(`PREPEND`_ <string-var> [<input>...]) string(`PREPEND`_ <string-var> [<input>...])
string(`CONCAT`_ <out-var> [<input>...]) string(`CONCAT`_ <out-var> [<input>...])
string(`JOIN`_ <glue> <out-var> [<input>...]) string(`JOIN`_ <glue> <out-var> [<input>...])
string(`TOLOWER`_ <string1> <out-var>) string(`TOLOWER`_ <string> <out-var>)
string(`TOUPPER`_ <string1> <out-var>) string(`TOUPPER`_ <string> <out-var>)
string(`LENGTH`_ <string> <out-var>) string(`LENGTH`_ <string> <out-var>)
string(`SUBSTRING`_ <string> <begin> <length> <out-var>) string(`SUBSTRING`_ <string> <begin> <length> <out-var>)
string(`STRIP`_ <string> <out-var>) string(`STRIP`_ <string> <out-var>)
@@ -38,7 +38,7 @@ Synopsis
`Generation`_ `Generation`_
string(`ASCII`_ <number>... <out-var>) string(`ASCII`_ <number>... <out-var>)
string(`CONFIGURE`_ <string1> <out-var> [...]) string(`CONFIGURE`_ <string> <out-var> [...])
string(`MAKE_C_IDENTIFIER`_ <string> <out-var>) string(`MAKE_C_IDENTIFIER`_ <string> <out-var>)
string(`RANDOM`_ [<option>...] <out-var>) string(`RANDOM`_ [<option>...] <out-var>)
string(`TIMESTAMP`_ <out-var> [<format string>] [UTC]) string(`TIMESTAMP`_ <out-var> [<format string>] [UTC])
@@ -51,23 +51,24 @@ Search and Replace
.. code-block:: cmake .. code-block:: cmake
string(FIND <string> <substring> <output variable> [REVERSE]) string(FIND <string> <substring> <output_variable> [REVERSE])
Return the position where the given substring was found in Return the position where the given ``<substring>`` was found in
the supplied string. If the ``REVERSE`` flag was used, the command will the supplied ``<string>``. If the ``REVERSE`` flag was used, the command will
search for the position of the last occurrence of the specified search for the position of the last occurrence of the specified
substring. If the substring is not found, a position of -1 is returned. ``<substring>``. If the ``<substring>`` is not found, a position of -1 is
returned.
.. _REPLACE: .. _REPLACE:
.. code-block:: cmake .. code-block:: cmake
string(REPLACE <match_string> string(REPLACE <match_string>
<replace_string> <output variable> <replace_string> <output_variable>
<input> [<input>...]) <input> [<input>...])
Replace all occurrences of ``match_string`` in the input Replace all occurrences of ``<match_string>`` in the ``<input>``
with ``replace_string`` and store the result in the output. with ``<replace_string>`` and store the result in the ``<output_variable>``.
Regular Expressions Regular Expressions
^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^
@@ -77,9 +78,10 @@ Regular Expressions
.. code-block:: cmake .. code-block:: cmake
string(REGEX MATCH <regular_expression> string(REGEX MATCH <regular_expression>
<output variable> <input> [<input>...]) <output_variable> <input> [<input>...])
Match the regular expression once and store the match in the output variable. Match the ``<regular_expression>`` once and store the match in the
``<output_variable>``.
All ``<input>`` arguments are concatenated before matching. All ``<input>`` arguments are concatenated before matching.
.. _`REGEX MATCHALL`: .. _`REGEX MATCHALL`:
@@ -87,10 +89,10 @@ All ``<input>`` arguments are concatenated before matching.
.. code-block:: cmake .. code-block:: cmake
string(REGEX MATCHALL <regular_expression> string(REGEX MATCHALL <regular_expression>
<output variable> <input> [<input>...]) <output_variable> <input> [<input>...])
Match the regular expression as many times as possible and store the matches Match the ``<regular_expression>`` as many times as possible and store the
in the output variable as a list. matches in the ``<output_variable>`` as a list.
All ``<input>`` arguments are concatenated before matching. All ``<input>`` arguments are concatenated before matching.
.. _`REGEX REPLACE`: .. _`REGEX REPLACE`:
@@ -98,16 +100,17 @@ All ``<input>`` arguments are concatenated before matching.
.. code-block:: cmake .. code-block:: cmake
string(REGEX REPLACE <regular_expression> string(REGEX REPLACE <regular_expression>
<replace_expression> <output variable> <replacement_expression> <output_variable>
<input> [<input>...]) <input> [<input>...])
Match the regular expression as many times as possible and substitute the Match the ``<regular_expression>`` as many times as possible and substitute
replacement expression for the match in the output. the ``<replacement_expression>`` for the match in the output.
All ``<input>`` arguments are concatenated before matching. All ``<input>`` arguments are concatenated before matching.
The replace expression may refer to paren-delimited subexpressions of the The ``<replacement_expression>`` may refer to parenthesis-delimited
match using ``\1``, ``\2``, ..., ``\9``. Note that two backslashes (``\\1``) subexpressions of the match using ``\1``, ``\2``, ..., ``\9``. Note that
are required in CMake code to get a backslash through argument parsing. two backslashes (``\\1``) are required in CMake code to get a backslash
through argument parsing.
.. _`Regex Specification`: .. _`Regex Specification`:
@@ -180,103 +183,104 @@ Manipulation
.. code-block:: cmake .. code-block:: cmake
string(APPEND <string variable> [<input>...]) string(APPEND <string_variable> [<input>...])
Append all the input arguments to the string. Append all the ``<input>`` arguments to the string.
.. _PREPEND: .. _PREPEND:
.. code-block:: cmake .. code-block:: cmake
string(PREPEND <string variable> [<input>...]) string(PREPEND <string_variable> [<input>...])
Prepend all the input arguments to the string. Prepend all the ``<input>`` arguments to the string.
.. _CONCAT: .. _CONCAT:
.. code-block:: cmake .. code-block:: cmake
string(CONCAT <output variable> [<input>...]) string(CONCAT <output_variable> [<input>...])
Concatenate all the input arguments together and store Concatenate all the ``<input>`` arguments together and store
the result in the named output variable. the result in the named ``<output_variable>``.
.. _JOIN: .. _JOIN:
.. code-block:: cmake .. code-block:: cmake
string(JOIN <glue> <output variable> [<input>...]) string(JOIN <glue> <output_variable> [<input>...])
Join all the input arguments together using the glue Join all the ``<input>`` arguments together using the ``<glue>``
string and store the result in the named output variable. string and store the result in the named ``<output_variable>``.
To join list's elements, use preferably the ``JOIN`` operator To join a list's elements, prefer to use the ``JOIN`` operator
from :command:`list` command. This allows for the elements to have from the :command:`list` command. This allows for the elements to have
special characters like ``;`` in them. special characters like ``;`` in them.
.. _TOLOWER: .. _TOLOWER:
.. code-block:: cmake .. code-block:: cmake
string(TOLOWER <string1> <output variable>) string(TOLOWER <string> <output_variable>)
Convert string to lower characters. Convert ``<string>`` to lower characters.
.. _TOUPPER: .. _TOUPPER:
.. code-block:: cmake .. code-block:: cmake
string(TOUPPER <string1> <output variable>) string(TOUPPER <string> <output_variable>)
Convert string to upper characters. Convert ``<string>`` to upper characters.
.. _LENGTH: .. _LENGTH:
.. code-block:: cmake .. code-block:: cmake
string(LENGTH <string> <output variable>) string(LENGTH <string> <output_variable>)
Store in an output variable a given string's length. Store in an ``<output_variable>`` a given string's length.
.. _SUBSTRING: .. _SUBSTRING:
.. code-block:: cmake .. code-block:: cmake
string(SUBSTRING <string> <begin> <length> <output variable>) string(SUBSTRING <string> <begin> <length> <output_variable>)
Store in an output variable a substring of a given string. If length is Store in an ``<output_variable>`` a substring of a given ``<string>``. If
``-1`` the remainder of the string starting at begin will be returned. ``<length>`` is ``-1`` the remainder of the string starting at ``<begin>``
If string is shorter than length then end of string is used instead. will be returned. If ``<string>`` is shorter than ``<length>`` then the
end of the string is used instead.
.. note:: .. note::
CMake 3.1 and below reported an error if length pointed past CMake 3.1 and below reported an error if ``<length>`` pointed past
the end of string. the end of ``<string>``.
.. _STRIP: .. _STRIP:
.. code-block:: cmake .. code-block:: cmake
string(STRIP <string> <output variable>) string(STRIP <string> <output_variable>)
Store in an output variable a substring of a given string with leading and Store in an ``<output_variable>`` a substring of a given ``<string>`` with
trailing spaces removed. leading and trailing spaces removed.
.. _GENEX_STRIP: .. _GENEX_STRIP:
.. code-block:: cmake .. code-block:: cmake
string(GENEX_STRIP <input string> <output variable>) string(GENEX_STRIP <string> <output_variable>)
Strip any :manual:`generator expressions <cmake-generator-expressions(7)>` Strip any :manual:`generator expressions <cmake-generator-expressions(7)>`
from the ``input string`` and store the result in the ``output variable``. from the input ``<string>`` and store the result in the ``<output_variable>``.
.. _REPEAT: .. _REPEAT:
.. code-block:: cmake .. code-block:: cmake
string(REPEAT <input string> <count> <output variable>) string(REPEAT <string> <count> <output_variable>)
Produce the output string as repetion of ``input string`` ``count`` times. Produce the output string as the input ``<string>`` repeated ``<count>`` times.
Comparison Comparison
^^^^^^^^^^ ^^^^^^^^^^
@@ -285,14 +289,14 @@ Comparison
.. code-block:: cmake .. code-block:: cmake
string(COMPARE LESS <string1> <string2> <output variable>) string(COMPARE LESS <string1> <string2> <output_variable>)
string(COMPARE GREATER <string1> <string2> <output variable>) string(COMPARE GREATER <string1> <string2> <output_variable>)
string(COMPARE EQUAL <string1> <string2> <output variable>) string(COMPARE EQUAL <string1> <string2> <output_variable>)
string(COMPARE NOTEQUAL <string1> <string2> <output variable>) string(COMPARE NOTEQUAL <string1> <string2> <output_variable>)
string(COMPARE LESS_EQUAL <string1> <string2> <output variable>) string(COMPARE LESS_EQUAL <string1> <string2> <output_variable>)
string(COMPARE GREATER_EQUAL <string1> <string2> <output variable>) string(COMPARE GREATER_EQUAL <string1> <string2> <output_variable>)
Compare the strings and store true or false in the output variable. Compare the strings and store true or false in the ``<output_variable>``.
.. _`Supported Hash Algorithms`: .. _`Supported Hash Algorithms`:
@@ -303,9 +307,9 @@ Hashing
.. code-block:: cmake .. code-block:: cmake
string(<HASH> <output variable> <input>) string(<HASH> <output_variable> <input>)
Compute a cryptographic hash of the input string. Compute a cryptographic hash of the ``<input>`` string.
The supported ``<HASH>`` algorithm names are: The supported ``<HASH>`` algorithm names are:
``MD5`` ``MD5``
@@ -336,7 +340,7 @@ Generation
.. code-block:: cmake .. code-block:: cmake
string(ASCII <number> [<number> ...] <output variable>) string(ASCII <number> [<number> ...] <output_variable>)
Convert all numbers into corresponding ASCII characters. Convert all numbers into corresponding ASCII characters.
@@ -344,31 +348,31 @@ Convert all numbers into corresponding ASCII characters.
.. code-block:: cmake .. code-block:: cmake
string(CONFIGURE <string1> <output variable> string(CONFIGURE <string> <output_variable>
[@ONLY] [ESCAPE_QUOTES]) [@ONLY] [ESCAPE_QUOTES])
Transform a string like :command:`configure_file` transforms a file. Transform a ``<string>`` like :command:`configure_file` transforms a file.
.. _MAKE_C_IDENTIFIER: .. _MAKE_C_IDENTIFIER:
.. code-block:: cmake .. code-block:: cmake
string(MAKE_C_IDENTIFIER <input string> <output variable>) string(MAKE_C_IDENTIFIER <string> <output_variable>)
Convert each non-alphanumeric character in the ``<input string>`` to an Convert each non-alphanumeric character in the input ``<string>`` to an
underscore and store the result in the ``<output variable>``. If the first underscore and store the result in the ``<output_variable>``. If the first
character of the string is a digit, an underscore will also be prepended to character of the ``<string>`` is a digit, an underscore will also be prepended
the result. to the result.
.. _RANDOM: .. _RANDOM:
.. code-block:: cmake .. code-block:: cmake
string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>] string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>]
[RANDOM_SEED <seed>] <output variable>) [RANDOM_SEED <seed>] <output_variable>)
Return a random string of given length consisting of Return a random string of given ``<length>`` consisting of
characters from the given alphabet. Default length is 5 characters characters from the given ``<alphabet>``. Default length is 5 characters
and default alphabet is all numbers and upper and lower case letters. 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 If an integer ``RANDOM_SEED`` is given, its value will be used to seed the
random number generator. random number generator.
@@ -377,18 +381,18 @@ random number generator.
.. code-block:: cmake .. code-block:: cmake
string(TIMESTAMP <output variable> [<format string>] [UTC]) string(TIMESTAMP <output_variable> [<format_string>] [UTC])
Write a string representation of the current date Write a string representation of the current date
and/or time to the output variable. and/or time to the ``<output_variable>``.
Should the command be unable to obtain a timestamp the output variable If the command is unable to obtain a timestamp, the ``<output_variable>``
will be set to the empty string "". will be set to the empty string ``""``.
The optional ``UTC`` flag requests the current date/time representation to The optional ``UTC`` flag requests the current date/time representation to
be in Coordinated Universal Time (UTC) rather than local time. be in Coordinated Universal Time (UTC) rather than local time.
The optional ``<format string>`` may contain the following format The optional ``<format_string>`` may contain the following format
specifiers: specifiers:
:: ::
@@ -415,7 +419,7 @@ specifiers:
Unknown format specifiers will be ignored and copied to the output Unknown format specifiers will be ignored and copied to the output
as-is. as-is.
If no explicit ``<format string>`` is given it will default to: If no explicit ``<format_string>`` is given, it will default to:
:: ::
@@ -432,7 +436,7 @@ If no explicit ``<format string>`` is given it will default to:
.. code-block:: cmake .. code-block:: cmake
string(UUID <output variable> NAMESPACE <namespace> NAME <name> string(UUID <output_variable> NAMESPACE <namespace> NAME <name>
TYPE <MD5|SHA1> [UPPER]) TYPE <MD5|SHA1> [UPPER])
Create a universally unique identifier (aka GUID) as per RFC4122 Create a universally unique identifier (aka GUID) as per RFC4122
@@ -441,6 +445,6 @@ based on the hash of the combined values of ``<namespace>``
The hash algorithm can be either ``MD5`` (Version 3 UUID) or The hash algorithm can be either ``MD5`` (Version 3 UUID) or
``SHA1`` (Version 5 UUID). ``SHA1`` (Version 5 UUID).
A UUID has the format ``xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`` A UUID has the format ``xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx``
where each `x` represents a lower case hexadecimal character. where each ``x`` represents a lower case hexadecimal character.
Where required an uppercase representation can be requested Where required, an uppercase representation can be requested
with the optional ``UPPER`` flag. with the optional ``UPPER`` flag.