From 533ebb072bb90bdba296aac79114a1ed0840759f Mon Sep 17 00:00:00 2001 From: Matthew Woehlke Date: Fri, 24 Feb 2023 16:25:16 -0500 Subject: Help: Use signature directive for string command --- Help/command/string.rst | 586 +++++++++++++++++++++--------------------------- 1 file changed, 256 insertions(+), 330 deletions(-) diff --git a/Help/command/string.rst b/Help/command/string.rst index c24b9bc..b47fa09 100644 --- a/Help/command/string.rst +++ b/Help/command/string.rst @@ -45,16 +45,16 @@ Synopsis `JSON`_ string(JSON [ERROR_VARIABLE ] - {:ref:`GET ` | :ref:`TYPE ` | :ref:`LENGTH ` | :ref:`REMOVE `} + {`GET `_ | `TYPE `_ | `LENGTH `_ | `REMOVE `_} [ ...]) string(JSON [ERROR_VARIABLE ] - :ref:`MEMBER ` + `MEMBER `_ [ ...] ) string(JSON [ERROR_VARIABLE ] - :ref:`SET ` + `SET `_ [ ...] ) string(JSON [ERROR_VARIABLE ] - :ref:`EQUAL ` ) + `EQUAL `_ ) Search and Replace ^^^^^^^^^^^^^^^^^^ @@ -62,75 +62,60 @@ Search and Replace Search and Replace With Plain Strings """"""""""""""""""""""""""""""""""""" -.. _FIND: - -.. code-block:: cmake - +.. signature:: string(FIND [REVERSE]) -Return the position where the given ```` was found in -the supplied ````. If the ``REVERSE`` flag was used, the command will -search for the position of the last occurrence of the specified -````. If the ```` is not found, a position of -1 is -returned. - -The ``string(FIND)`` subcommand treats all strings as ASCII-only characters. -The index stored in ```` will also be counted in bytes, -so strings containing multi-byte characters may lead to unexpected results. + Return the position where the given ```` was found in + the supplied ````. If the ``REVERSE`` flag was used, the command + will search for the position of the last occurrence of the specified + ````. If the ```` is not found, a position of -1 is + returned. -.. _REPLACE: - -.. code-block:: cmake + The ``string(FIND)`` subcommand treats all strings as ASCII-only characters. + The index stored in ```` will also be counted in bytes, + so strings containing multi-byte characters may lead to unexpected results. +.. signature:: string(REPLACE [...]) -Replace all occurrences of ```` in the ```` -with ```` and store the result in the ````. + Replace all occurrences of ```` in the ```` + with ```` and store the result in the ````. Search and Replace With Regular Expressions """"""""""""""""""""""""""""""""""""""""""" -.. _`REGEX MATCH`: - -.. code-block:: cmake - +.. signature:: string(REGEX MATCH [...]) -Match the ```` once and store the match in the -````. -All ```` arguments are concatenated before matching. -Regular expressions are specified in the subsection just below. - -.. _`REGEX MATCHALL`: - -.. code-block:: cmake + Match the ```` once and store the match in the + ````. + All ```` arguments are concatenated before matching. + Regular expressions are specified in the subsection just below. +.. signature:: string(REGEX MATCHALL [...]) -Match the ```` as many times as possible and store the -matches in the ```` as a list. -All ```` arguments are concatenated before matching. - -.. _`REGEX REPLACE`: - -.. code-block:: cmake + Match the ```` as many times as possible and store the + matches in the ```` as a list. + All ```` arguments are concatenated before matching. +.. signature:: string(REGEX REPLACE [...]) -Match the ```` as many times as possible and substitute -the ```` for the match in the output. -All ```` arguments are concatenated before matching. + Match the ```` as many times as possible and substitute + the ```` for the match in the output. + All ```` arguments are concatenated before matching. -The ```` may refer to parenthesis-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. + The ```` may refer to parenthesis-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`: @@ -201,130 +186,100 @@ newlines, and backslashes (respectively) to pass in a regex. For example: Manipulation ^^^^^^^^^^^^ -.. _APPEND: - -.. code-block:: cmake - +.. signature:: string(APPEND [...]) -.. versionadded:: 3.4 - -Append all the ```` arguments to the string. + .. versionadded:: 3.4 -.. _PREPEND: - -.. code-block:: cmake + Append all the ```` arguments to the string. +.. signature:: string(PREPEND [...]) -.. versionadded:: 3.10 - -Prepend all the ```` arguments to the string. - -.. _CONCAT: + .. versionadded:: 3.10 -.. code-block:: cmake + Prepend all the ```` arguments to the string. +.. signature:: string(CONCAT [...]) -Concatenate all the ```` arguments together and store -the result in the named ````. - -.. _JOIN: - -.. code-block:: cmake + Concatenate all the ```` arguments together and store + the result in the named ````. +.. signature:: string(JOIN [...]) -.. versionadded:: 3.12 - -Join all the ```` arguments together using the ```` -string and store the result in the named ````. - -To join a list's elements, prefer to use the ``JOIN`` operator -from the :command:`list` command. This allows for the elements to have -special characters like ``;`` in them. + .. versionadded:: 3.12 -.. _TOLOWER: + Join all the ```` arguments together using the ```` + string and store the result in the named ````. -.. code-block:: cmake + To join a list's elements, prefer to use the ``JOIN`` operator + from the :command:`list` command. This allows for the elements to have + special characters like ``;`` in them. +.. signature:: string(TOLOWER ) -Convert ```` to lower characters. - -.. _TOUPPER: - -.. code-block:: cmake + Convert ```` to lower characters. +.. signature:: string(TOUPPER ) -Convert ```` to upper characters. - -.. _LENGTH: - -.. code-block:: cmake + Convert ```` to upper characters. +.. signature:: string(LENGTH ) -Store in an ```` a given string's length in bytes. -Note that this means if ```` contains multi-byte characters, the -result stored in ```` will *not* be the number of characters. - -.. _SUBSTRING: - -.. code-block:: cmake + Store in an ```` a given string's length in bytes. + Note that this means if ```` contains multi-byte characters, + the result stored in ```` will *not* be + the number of characters. +.. signature:: string(SUBSTRING ) -Store in an ```` a substring of a given ````. If -```` is ``-1`` the remainder of the string starting at ```` -will be returned. - -.. versionchanged:: 3.2 - If ```` is shorter than ```` then the end of the string - is used instead. Previous versions of CMake reported an error in this case. - -Both ```` and ```` are counted in bytes, so care must -be exercised if ```` could contain multi-byte characters. + Store in an ```` a substring of a given ````. If + ```` is ``-1`` the remainder of the string starting at ```` + will be returned. -.. _STRIP: + .. versionchanged:: 3.2 + If ```` is shorter than ```` + then the end of the string is used instead. + Previous versions of CMake reported an error in this case. -.. code-block:: cmake + Both ```` and ```` are counted in bytes, so care must + be exercised if ```` could contain multi-byte characters. +.. signature:: string(STRIP ) -Store in an ```` a substring of a given ```` with -leading and trailing spaces removed. - -.. _GENEX_STRIP: - -.. code-block:: cmake + Store in an ```` a substring of a given ```` + with leading and trailing spaces removed. +.. signature:: string(GENEX_STRIP ) -.. versionadded:: 3.1 - -Strip any :manual:`generator expressions ` -from the input ```` and store the result in the ````. - -.. _REPEAT: + .. versionadded:: 3.1 -.. code-block:: cmake + Strip any :manual:`generator expressions ` + from the input ```` and store the result + in the ````. +.. signature:: string(REPEAT ) -.. versionadded:: 3.15 + .. versionadded:: 3.15 -Produce the output string as the input ```` repeated ```` times. + Produce the output string as the input ```` + repeated ```` times. Comparison ^^^^^^^^^^ .. _COMPARE: -.. code-block:: cmake - +.. signature:: string(COMPARE LESS ) string(COMPARE GREATER ) string(COMPARE EQUAL ) @@ -332,240 +287,217 @@ Comparison string(COMPARE LESS_EQUAL ) string(COMPARE GREATER_EQUAL ) -Compare the strings and store true or false in the ````. + Compare the strings and store true or false in the ````. -.. versionadded:: 3.7 - Added the ``LESS_EQUAL`` and ``GREATER_EQUAL`` options. + .. versionadded:: 3.7 + Added the ``LESS_EQUAL`` and ``GREATER_EQUAL`` options. .. _`Supported Hash Algorithms`: Hashing ^^^^^^^ -.. _`HASH`: - -.. code-block:: cmake - +.. signature:: string( ) + :target: HASH + + Compute a cryptographic hash of the ```` string. + The supported ```` algorithm names are: + + ``MD5`` + Message-Digest Algorithm 5, RFC 1321. + ``SHA1`` + US Secure Hash Algorithm 1, RFC 3174. + ``SHA224`` + US Secure Hash Algorithms, RFC 4634. + ``SHA256`` + US Secure Hash Algorithms, RFC 4634. + ``SHA384`` + US Secure Hash Algorithms, RFC 4634. + ``SHA512`` + US Secure Hash Algorithms, RFC 4634. + ``SHA3_224`` + Keccak SHA-3. + ``SHA3_256`` + Keccak SHA-3. + ``SHA3_384`` + Keccak SHA-3. + ``SHA3_512`` + Keccak SHA-3. -Compute a cryptographic hash of the ```` string. -The supported ```` algorithm names are: - -``MD5`` - Message-Digest Algorithm 5, RFC 1321. -``SHA1`` - US Secure Hash Algorithm 1, RFC 3174. -``SHA224`` - US Secure Hash Algorithms, RFC 4634. -``SHA256`` - US Secure Hash Algorithms, RFC 4634. -``SHA384`` - US Secure Hash Algorithms, RFC 4634. -``SHA512`` - US Secure Hash Algorithms, RFC 4634. -``SHA3_224`` - Keccak SHA-3. -``SHA3_256`` - Keccak SHA-3. -``SHA3_384`` - Keccak SHA-3. -``SHA3_512`` - Keccak SHA-3. - -.. versionadded:: 3.8 - Added the ``SHA3_*`` hash algorithms. + .. versionadded:: 3.8 + Added the ``SHA3_*`` hash algorithms. Generation ^^^^^^^^^^ -.. _ASCII: - -.. code-block:: cmake - +.. signature:: string(ASCII [ ...] ) -Convert all numbers into corresponding ASCII characters. - -.. _HEX: - -.. code-block:: cmake + Convert all numbers into corresponding ASCII characters. +.. signature:: string(HEX ) -.. versionadded:: 3.18 - -Convert each byte in the input ```` to its hexadecimal representation -and store the concatenated hex digits in the ````. Letters in -the output (``a`` through ``f``) are in lowercase. + .. versionadded:: 3.18 -.. _CONFIGURE: - -.. code-block:: cmake + Convert each byte in the input ```` to its hexadecimal representation + and store the concatenated hex digits in the ````. + Letters in the output (``a`` through ``f``) are in lowercase. +.. signature:: string(CONFIGURE [@ONLY] [ESCAPE_QUOTES]) -Transform a ```` like :command:`configure_file` transforms a file. - -.. _MAKE_C_IDENTIFIER: - -.. code-block:: cmake + Transform a ```` like :command:`configure_file` transforms a file. +.. signature:: string(MAKE_C_IDENTIFIER ) -Convert each non-alphanumeric character in the input ```` to an -underscore and store the result in the ````. If the first -character of the ```` is a digit, an underscore will also be prepended -to the result. - -.. _RANDOM: - -.. code-block:: cmake + Convert each non-alphanumeric character in the input ```` to an + underscore and store the result in the ````. If the first + character of the ```` is a digit, an underscore will also be + prepended to the result. +.. signature:: string(RANDOM [LENGTH ] [ALPHABET ] [RANDOM_SEED ] ) -Return a random string of given ```` consisting of -characters from the given ````. 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: - -.. code-block:: cmake + Return a random string of given ```` consisting of + characters from the given ````. 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. +.. signature:: string(TIMESTAMP [] [UTC]) -Write a string representation of the current date -and/or time to the ````. - -If the command is unable to obtain a timestamp, the ```` -will be set to the empty string ``""``. + Write a string representation of the current date + and/or time to the ````. -The optional ``UTC`` flag requests the current date/time representation to -be in Coordinated Universal Time (UTC) rather than local time. + If the command is unable to obtain a timestamp, the ```` + will be set to the empty string ``""``. -The optional ```` may contain the following format -specifiers: - -``%%`` - .. versionadded:: 3.8 + The optional ``UTC`` flag requests the current date/time representation to + be in Coordinated Universal Time (UTC) rather than local time. - A literal percent sign (%). + The optional ```` may contain the following format + specifiers: -``%d`` - The day of the current month (01-31). + ``%%`` + .. versionadded:: 3.8 -``%H`` - The hour on a 24-hour clock (00-23). + A literal percent sign (%). -``%I`` - The hour on a 12-hour clock (01-12). + ``%d`` + The day of the current month (01-31). -``%j`` - The day of the current year (001-366). + ``%H`` + The hour on a 24-hour clock (00-23). -``%m`` - The month of the current year (01-12). + ``%I`` + The hour on a 12-hour clock (01-12). -``%b`` - .. versionadded:: 3.7 + ``%j`` + The day of the current year (001-366). - Abbreviated month name (e.g. Oct). + ``%m`` + The month of the current year (01-12). -``%B`` - .. versionadded:: 3.10 + ``%b`` + .. versionadded:: 3.7 - Full month name (e.g. October). + Abbreviated month name (e.g. Oct). -``%M`` - The minute of the current hour (00-59). + ``%B`` + .. versionadded:: 3.10 -``%s`` - .. versionadded:: 3.6 + Full month name (e.g. October). - Seconds since midnight (UTC) 1-Jan-1970 (UNIX time). + ``%M`` + The minute of the current hour (00-59). -``%S`` - The second of the current minute. 60 represents a leap second. (00-60) + ``%s`` + .. versionadded:: 3.6 -``%f`` - .. versionadded:: 3.23 + Seconds since midnight (UTC) 1-Jan-1970 (UNIX time). - The microsecond of the current second (000000-999999). + ``%S`` + The second of the current minute. 60 represents a leap second. (00-60) -``%U`` - The week number of the current year (00-53). + ``%f`` + .. versionadded:: 3.23 -``%V`` - .. versionadded:: 3.22 + The microsecond of the current second (000000-999999). - The ISO 8601 week number of the current year (01-53). + ``%U`` + The week number of the current year (00-53). -``%w`` - The day of the current week. 0 is Sunday. (0-6) + ``%V`` + .. versionadded:: 3.22 -``%a`` - .. versionadded:: 3.7 + The ISO 8601 week number of the current year (01-53). - Abbreviated weekday name (e.g. Fri). + ``%w`` + The day of the current week. 0 is Sunday. (0-6) -``%A`` - .. versionadded:: 3.10 + ``%a`` + .. versionadded:: 3.7 - Full weekday name (e.g. Friday). + Abbreviated weekday name (e.g. Fri). -``%y`` - The last two digits of the current year (00-99). + ``%A`` + .. versionadded:: 3.10 -``%Y`` - The current year. + Full weekday name (e.g. Friday). -``%z`` - .. versionadded:: 3.26 + ``%y`` + The last two digits of the current year (00-99). - The offset of the time zone from UTC, in hours and minutes, - with format ``+hhmm`` or ``-hhmm``. + ``%Y`` + The current year. -``%Z`` - .. versionadded:: 3.26 + ``%z`` + .. versionadded:: 3.26 - The time zone name. + The offset of the time zone from UTC, in hours and minutes, + with format ``+hhmm`` or ``-hhmm``. -Unknown format specifiers will be ignored and copied to the output -as-is. + ``%Z`` + .. versionadded:: 3.26 -If no explicit ```` is given, it will default to: + The time zone name. -:: + Unknown format specifiers will be ignored and copied to the output + as-is. - %Y-%m-%dT%H:%M:%S for local time. - %Y-%m-%dT%H:%M:%SZ for UTC. + If no explicit ```` is given, it will default to: -.. versionadded:: 3.8 - If the ``SOURCE_DATE_EPOCH`` environment variable is set, - its value will be used instead of the current time. - See https://reproducible-builds.org/specs/source-date-epoch/ for details. + :: -.. _UUID: + %Y-%m-%dT%H:%M:%S for local time. + %Y-%m-%dT%H:%M:%SZ for UTC. -.. code-block:: cmake + .. versionadded:: 3.8 + If the ``SOURCE_DATE_EPOCH`` environment variable is set, + its value will be used instead of the current time. + See https://reproducible-builds.org/specs/source-date-epoch/ for details. +.. signature:: string(UUID NAMESPACE NAME TYPE [UPPER]) -.. versionadded:: 3.1 + .. versionadded:: 3.1 -Create a universally 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 -``SHA1`` (Version 5 UUID). -A UUID has the format ``xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`` -where each ``x`` represents a lower case hexadecimal character. -Where required, an uppercase representation can be requested -with the optional ``UPPER`` flag. + Create a universally 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 + ``SHA1`` (Version 5 UUID). + A UUID has the format ``xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`` + where each ``x`` represents a lower case hexadecimal character. + Where required, an uppercase representation can be requested + with the optional ``UPPER`` flag. .. _JSON: @@ -586,78 +518,72 @@ Functionality for querying a JSON string. option is not present, a fatal error message is generated. If no error occurs, the ```` will be set to ``NOTFOUND``. -.. _JSON_GET: -.. code-block:: cmake - +.. signature:: string(JSON [ERROR_VARIABLE ] GET [ ...]) + :target: JSON GET -Get an element from ```` at the location given -by the list of ```` arguments. -Array and object elements will be returned as a JSON string. -Boolean elements will be returned as ``ON`` or ``OFF``. -Null elements will be returned as an empty string. -Number and string types will be returned as strings. - -.. _JSON_TYPE: -.. code-block:: cmake + Get an element from ```` at the location given + by the list of ```` arguments. + Array and object elements will be returned as a JSON string. + Boolean elements will be returned as ``ON`` or ``OFF``. + Null elements will be returned as an empty string. + Number and string types will be returned as strings. +.. signature:: string(JSON [ERROR_VARIABLE ] TYPE [ ...]) + :target: JSON TYPE -Get the type of an element in ```` at the location -given by the list of ```` arguments. The ```` -will be set to one of ``NULL``, ``NUMBER``, ``STRING``, ``BOOLEAN``, -``ARRAY``, or ``OBJECT``. - -.. _JSON_MEMBER: -.. code-block:: cmake + Get the type of an element in ```` at the location + given by the list of ```` arguments. The ```` + will be set to one of ``NULL``, ``NUMBER``, ``STRING``, ``BOOLEAN``, + ``ARRAY``, or ``OBJECT``. +.. signature:: string(JSON [ERROR_VARIABLE ] MEMBER [ ...] ) + :target: JSON MEMBER -Get the name of the ````-th member in ```` at the location -given by the list of ```` arguments. -Requires an element of object type. - -.. _JSON_LENGTH: -.. code-block:: cmake + Get the name of the ````-th member in ```` + at the location given by the list of ```` arguments. + Requires an element of object type. +.. signature:: string(JSON [ERROR_VARIABLE ] LENGTH [ ...]) + :target: JSON LENGTH -Get the length of an element in ```` at the location -given by the list of ```` arguments. -Requires an element of array or object type. - -.. _JSON_REMOVE: -.. code-block:: cmake + Get the length of an element in ```` at the location + given by the list of ```` arguments. + Requires an element of array or object type. +.. signature:: string(JSON [ERROR_VARIABLE ] REMOVE [ ...]) + :target: JSON REMOVE -Remove an element from ```` at the location -given by the list of ```` arguments. The JSON string -without the removed element will be stored in ````. - -.. _JSON_SET: -.. code-block:: cmake + Remove an element from ```` at the location + given by the list of ```` arguments. The JSON string + without the removed element will be stored in ````. +.. signature:: string(JSON [ERROR_VARIABLE ] SET [ ...] ) + :target: JSON SET -Set an element in ```` at the location -given by the list of ```` arguments to ````. -The contents of ```` should be valid JSON. - -.. _JSON_EQUAL: -.. code-block:: cmake + Set an element in ```` at the location + given by the list of ```` arguments to ````. + The contents of ```` should be valid JSON. +.. signature:: string(JSON [ERROR_VARIABLE ] EQUAL ) + :target: JSON EQUAL -Compare the two JSON objects given by ```` and ```` -for equality. The contents of ```` and ```` -should be valid JSON. The ```` will be set to a true value if the -JSON objects are considered equal, or a false value otherwise. + Compare the two JSON objects given by ```` + and ```` for equality. The contents of ```` + and ```` should be valid JSON. The ```` + will be set to a true value if the JSON objects are considered equal, + or a false value otherwise. -- cgit v0.12