From 31675964e7ba37f1412aaa95af4199e9b62e8c08 Mon Sep 17 00:00:00 2001 From: Marc Chevrier Date: Tue, 4 Apr 2023 16:42:58 +0200 Subject: GenEx LIST: list operations Fixes: #24550, #24547 --- Help/command/list.rst | 30 +-- Help/manual/cmake-generator-expressions.7.rst | 264 +++++++++++++++++++++++++- Help/release/dev/GenEx-LIST.rst | 4 + 3 files changed, 281 insertions(+), 17 deletions(-) create mode 100644 Help/release/dev/GenEx-LIST.rst (limited to 'Help') diff --git a/Help/command/list.rst b/Help/command/list.rst index 191003a700..0c7a562872 100644 --- a/Help/command/list.rst +++ b/Help/command/list.rst @@ -188,7 +188,7 @@ For more information on regular expressions look under .. versionadded:: 3.12 - Transforms the list by applying an action to all or, by specifying a + Transforms the list by applying an ```` to all or, by specifying a ````, to the selected elements of the list, storing the result in-place or in the specified output variable. @@ -205,42 +205,42 @@ For more information on regular expressions look under :command:`APPEND `, :command:`PREPEND ` Append, prepend specified value to each element of the list. - .. code-block:: cmake - - list(TRANSFORM ...) + .. signature:: + list(TRANSFORM (APPEND|PREPEND) ...) + :target: TRANSFORM_APPEND - :command:`TOUPPER `, :command:`TOLOWER ` - Convert each element of the list to upper, lower characters. + :command:`TOLOWER `, :command:`TOUPPER ` + Convert each element of the list to lower, upper characters. - .. code-block:: cmake - - list(TRANSFORM ...) + .. signature:: + list(TRANSFORM (TOLOWER|TOUPPER) ...) + :target: TRANSFORM_TOLOWER :command:`STRIP ` Remove leading and trailing spaces from each element of the list. - .. code-block:: cmake - + .. signature:: list(TRANSFORM STRIP ...) + :target: TRANSFORM_STRIP :command:`GENEX_STRIP ` Strip any :manual:`generator expressions ` from each element of the list. - .. code-block:: cmake - + .. signature:: list(TRANSFORM GENEX_STRIP ...) + :target: TRANSFORM_GENEX_STRIP :command:`REPLACE `: Match the regular expression as many times as possible and substitute the replacement expression for the match for each element of the list (same semantic as :command:`string(REGEX REPLACE)`). - .. code-block:: cmake - + .. signature:: list(TRANSFORM REPLACE ...) + :target: TRANSFORM_REPLACE ```` determines which elements of the list will be transformed. Only one type of selector can be specified at a time. diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 9da37999b1..9d29dc38e3 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -104,6 +104,17 @@ improved further like so: VERBATIM ) +Finally, the above example can be expressed in a more simple and robust way +using an alternate generator expression: + +.. code-block:: cmake + + add_custom_target(run_some_tool + COMMAND some_tool "$,PREPEND,-I>" + COMMAND_EXPAND_LISTS + VERBATIM + ) + A common mistake is to try to split a generator expression across multiple lines with indenting: @@ -318,6 +329,15 @@ String Transformations List Expressions ---------------- +Most of the expressions in this section are closely associated with the +:command:`list` command, providing the same capabilities, but in +the form of a generator expression. + +.. _GenEx List Comparisons: + +List Comparisons +^^^^^^^^^^^^^^^^ + .. genex:: $ .. versionadded:: 3.12 @@ -325,9 +345,186 @@ List Expressions ``1`` if ``string`` is an item in the semicolon-separated ``list``, else ``0``. It uses case-sensitive comparisons. -.. genex:: $ +.. _GenEx List Queries: + +List Queries +^^^^^^^^^^^^ + +.. genex:: $ + + .. versionadded:: 3.27 + + Returns the list's length. + +.. genex:: $ + + .. versionadded:: 3.27 + + Returns the list of elements specified by indices from the list. + +.. genex:: $ + + .. versionadded:: 3.27 + + Returns a sublist of the given list. If is 0, an empty list will be + returned. If is -1 or the list is smaller than + then + the remaining elements of the list starting at will be returned. + +.. genex:: $ + + .. versionadded:: 3.27 + + Returns the index of the element specified in the list or -1 if it wasn't + found. + +.. _GenEx List Transformations: + +List Transformations +^^^^^^^^^^^^^^^^^^^^ + +.. genex:: $ + + .. versionadded:: 3.27 + + Returns a string which joins the list with the content of the ``glue`` string + inserted between each item. + +.. genex:: $ + + .. versionadded:: 3.27 + + Returns a list with the elements appended. + +.. genex:: $ + + .. versionadded:: 3.27 + + Returns a list with the elements inserted at the beginning of the list. + +.. genex:: $ + + .. versionadded:: 3.27 + + Returns a list with the elements inserted at the specified index. It is an + error to specify an out-of-range index. Valid indexes are 0 to N where N is + the length of the list, inclusive. An empty list has length 0. + +.. genex:: $ + + .. versionadded:: 3.27 + + Returns a list with the last element was removed. + +.. genex:: $ + + .. versionadded:: 3.27 + + Returns a list with the first element was removed. + +.. genex:: $ + + .. versionadded:: 3.27 + + Returns a list with all instances of the given values were removed. + +.. genex:: $ + + .. versionadded:: 3.27 - Joins the list with the content of ``string`` inserted between each item. + Returns a list with all values at given indices were removed. + +.. genex:: $ + + .. versionadded:: 3.27 + + Returns a list where duplicated items were removed. The relative order of + items is preserved, but if duplicates are encountered, only the first + instance is preserved. + +.. genex:: $ + + .. versionadded:: 3.27 + + Returns a list with the items that match the regular expression ``regex`` + were included or removed. + +.. genex:: $ + + .. versionadded:: 3.27 + + Returns the list transformed by applying an ``ACTION`` to all or, by + specifying a ``SELECTOR``, to the selected elements of the list. + + .. note:: + + The ``TRANSFORM`` sub-command does not change the number of elements in the + list. If a ``SELECTOR`` is specified, only some elements will be changed, + the other ones will remain the same as before the transformation. + + ``ACTION`` specifies the action to apply to the elements of the list. + The actions have exactly the same semantics as of the + :command:`list(TRANSFORM)` command. ``ACTION`` must be one of the following: + + :command:`APPEND `, :command:`PREPEND ` + Append, prepend specified value to each element of the list. + + .. code-block:: cmake + + $ + + :command:`TOLOWER `, :command:`TOUPPER ` + Convert each element of the list to lower, upper characters. + + .. code-block:: cmake + + $ + + :command:`STRIP ` + Remove leading and trailing spaces from each element of the list. + + .. code-block:: cmake + + $ + + :command:`REPLACE `: + Match the regular expression as many times as possible and substitute + the replacement expression for the match for each element of the list. + + .. code-block:: cmake + + $ + + ``SELECTOR`` determines which elements of the list will be transformed. + Only one type of selector can be specified at a time. When given, + ``SELECTOR`` must be one of the following: + + ``AT`` + Specify a list of indexes. + + .. code-block:: cmake + + $ + + ``FOR`` + Specify a range with, optionally, an increment used to iterate over the + range. + + .. code-block:: cmake + + $ + + ``REGEX`` + Specify a regular expression. + Only elements matching the regular expression will be transformed. + + .. code-block:: cmake + + $ + +.. genex:: $ + + Joins the list with the content of the ``glue`` string inserted between each + item. .. genex:: $ @@ -344,6 +541,69 @@ List Expressions Includes or removes items from ``list`` that match the regular expression ``regex``. +.. _GenEx List Ordering: + +List Ordering +^^^^^^^^^^^^^ + +.. genex:: $ + + .. versionadded:: 3.27 + + Returns the list with the elements in reverse order. + +.. genex:: $ + + .. versionadded:: 3.27 + + Returns the list sorted according the specified options. + + Use one of the ``COMPARE`` options to select the comparison method + for sorting: + + ``STRING`` + Sorts a list of strings alphabetically. + This is the default behavior if the ``COMPARE`` option is not given. + + ``FILE_BASENAME`` + Sorts a list of pathnames of files by their basenames. + + ``NATURAL`` + Sorts a list of strings using natural order + (see ``strverscmp(3)`` manual), i.e. such that contiguous digits + are compared as whole numbers. + For example: the following list `10.0 1.1 2.1 8.0 2.0 3.1` + will be sorted as `1.1 2.0 2.1 3.1 8.0 10.0` if the ``NATURAL`` + comparison is selected where it will be sorted as + `1.1 10.0 2.0 2.1 3.1 8.0` with the ``STRING`` comparison. + + Use one of the ``CASE`` options to select a case sensitive or case + insensitive sort mode: + + ``SENSITIVE`` + List items are sorted in a case-sensitive manner. + This is the default behavior if the ``CASE`` option is not given. + + ``INSENSITIVE`` + List items are sorted case insensitively. The order of + items which differ only by upper/lowercase is not specified. + + To control the sort order, one of the ``ORDER`` options can be given: + + ``ASCENDING`` + Sorts the list in ascending order. + This is the default behavior when the ``ORDER`` option is not given. + + ``DESCENDING`` + Sorts the list in descending order. + + This is an error to specify multiple times the same option. Various options + can be specified in any order: + + .. code-block:: cmake + + $ + Path Expressions ---------------- diff --git a/Help/release/dev/GenEx-LIST.rst b/Help/release/dev/GenEx-LIST.rst new file mode 100644 index 0000000000..f65a092db9 --- /dev/null +++ b/Help/release/dev/GenEx-LIST.rst @@ -0,0 +1,4 @@ +GenEx-LIST +---------- + +* The :genex:`LIST` generator expression was added to manage lists. -- cgit v1.2.1