diff options
Diffstat (limited to 'Help/command/list.rst')
-rw-r--r-- | Help/command/list.rst | 275 |
1 files changed, 233 insertions, 42 deletions
diff --git a/Help/command/list.rst b/Help/command/list.rst index f6b75bc19..589e57253 100644 --- a/Help/command/list.rst +++ b/Help/command/list.rst @@ -3,66 +3,257 @@ list List operations. +Synopsis +^^^^^^^^ + +.. parsed-literal:: + + `Reading`_ + list(`LENGTH`_ <list> <out-var>) + list(`GET`_ <list> <element index> [<index> ...] <out-var>) + list(`JOIN`_ <list> <glue> <out-var>) + list(`SUBLIST`_ <list> <begin> <length> <out-var>) + + `Search`_ + list(`FIND`_ <list> <value> <out-var>) + + `Modification`_ + list(`APPEND`_ <list> [<element>...]) + list(`FILTER`_ <list> {INCLUDE | EXCLUDE} REGEX <regex>) + list(`INSERT`_ <list> <index> [<element>...]) + list(`REMOVE_ITEM`_ <list> <value>...) + list(`REMOVE_AT`_ <list> <index>...) + list(`REMOVE_DUPLICATES`_ <list>) + list(`TRANSFORM`_ <list> <ACTION> [...]) + + `Ordering`_ + list(`REVERSE`_ <list>) + list(`SORT`_ <list>) + +Introduction +^^^^^^^^^^^^ + +The list subcommands ``APPEND``, ``INSERT``, ``FILTER``, ``REMOVE_AT``, +``REMOVE_ITEM``, ``REMOVE_DUPLICATES``, ``REVERSE`` and ``SORT`` may create +new values for the list within the current CMake variable scope. Similar to +the :command:`set` command, the LIST command creates new variable values in +the current scope, even if the list itself is actually defined in a parent +scope. To propagate the results of these operations upwards, use +:command:`set` with ``PARENT_SCOPE``, :command:`set` with +``CACHE INTERNAL``, or some other means of value propagation. + +.. note:: + + A list in cmake is a ``;`` separated group of strings. To create a + list the set command can be used. For example, ``set(var a b c d e)`` + creates a list with ``a;b;c;d;e``, and ``set(var "a b c d e")`` creates a + string or a list with one item in it. (Note macro arguments are not + variables, and therefore cannot be used in LIST commands.) + +.. note:: + + When specifying index values, if ``<element index>`` is 0 or greater, it + is indexed from the beginning of the list, with 0 representing the + first list element. If ``<element index>`` is -1 or lesser, it is indexed + from the end of the list, with -1 representing the last list element. + Be careful when counting with negative indices: they do not start from + 0. -0 is equivalent to 0, the first list element. + +Reading +^^^^^^^ + +.. _LENGTH: + :: list(LENGTH <list> <output variable>) - list(GET <list> <element index> [<element index> ...] - <output variable>) + +Returns the list's length. + +.. _GET: + +:: + + list(GET <list> <element index> [<element index> ...] <output variable>) + +Returns the list of elements specified by indices from the list. + +.. _JOIN: + +:: + + list(JOIN <list> <glue> <output variable>) + +Returns a string joining all list's elements using the glue string. +To join multiple strings, which are not part of a list, use ``JOIN`` operator +from :command:`string` command. + +.. _SUBLIST: + +:: + + list(SUBLIST <list> <begin> <length> <output variable>) + +Returns a sublist of the given list. +If ``<length>`` is 0, an empty list will be returned. +If ``<length>`` is -1 or the list is smaller than ``<begin>+<length>`` then +the remaining elements of the list starting at ``<begin>`` will be returned. + +Search +^^^^^^ + +.. _FIND: + +:: + + list(FIND <list> <value> <output variable>) + +Returns the index of the element specified in the list or -1 +if it wasn't found. + +Modification +^^^^^^^^^^^^ + +.. _APPEND: + +:: + list(APPEND <list> [<element> ...]) + +Appends elements to the list. + +.. _FILTER: + +:: + list(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>) - list(FIND <list> <value> <output variable>) + +Includes or removes items from the list that match the mode's pattern. +In ``REGEX`` mode, items will be matched against the given regular expression. + +For more information on regular expressions see also the +:command:`string` command. + +.. _INSERT: + +:: + list(INSERT <list> <element_index> <element> [<element> ...]) + +Inserts elements to the list to the specified location. + +.. _REMOVE_ITEM: + +:: + list(REMOVE_ITEM <list> <value> [<value> ...]) + +Removes the given items from the list. + +.. _REMOVE_AT: + +:: + list(REMOVE_AT <list> <index> [<index> ...]) + +Removes items at given indices from the list. + +.. _REMOVE_DUPLICATES: + +:: + list(REMOVE_DUPLICATES <list>) - list(REVERSE <list>) - list(SORT <list>) -``LENGTH`` will return a given list's length. +Removes duplicated items in the list. -``GET`` will return list of elements specified by indices from the list. +.. _TRANSFORM: -``APPEND`` will append elements to the list. +:: -``FILTER`` will include or remove items from the list that match the -mode's pattern. -In ``REGEX`` mode, items will be matched against the given regular expression. -For more information on regular expressions see also the :command:`string` -command. + list(TRANSFORM <list> <ACTION> [<SELECTOR>] + [OUTPUT_VARIABLE <output variable>]) -``FIND`` will return the index of the element specified in the list or -1 -if it wasn't found. +Transforms the list by applying an action to all or, by specifying a +``<SELECTOR>``, to the selected elements of the list, storing result in-place +or in the specified output variable. -``INSERT`` will insert elements to the list to the specified location. +.. note:: -``REMOVE_AT`` and ``REMOVE_ITEM`` will remove items from the list. The -difference is that ``REMOVE_ITEM`` will remove the given items, while -``REMOVE_AT`` will remove the items at the given indices. + ``TRANSFORM`` sub-command does not change the number of elements of the + list. If a ``<SELECTOR>`` is specified, only some elements will be changed, + the other ones will remain same as before the transformation. -``REMOVE_DUPLICATES`` will remove duplicated items in the list. +``<ACTION>`` specify the action to apply to the elements of list. +The actions have exactly the same semantics as sub-commands of +:command:`string` command. -``REVERSE`` reverses the contents of the list in-place. +The ``<ACTION>`` may be one of: -``SORT`` sorts the list in-place alphabetically. +``APPEND``, ``PREPEND``: Append, prepend specified value to each element of +the list. :: + + list(TRANSFORM <list> <APPEND|PREPEND> <value> ...) + +``TOUPPER``, ``TOLOWER``: Convert each element of the list to upper, lower +characters. :: + + list(TRANSFORM <list> <TOLOWER|TOUPPER> ...) + +``STRIP``: Remove leading and trailing spaces from each element of the +list. :: + + list(TRANSFORM <list> STRIP ...) + +``GENEX_STRIP``: Strip any +:manual:`generator expressions <cmake-generator-expressions(7)>` from each +element of the list. :: + + list(TRANSFORM <list> GENEX_STRIP ...) + +``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 ``REGEX REPLACE`` from :command:`string` command). :: + + list(TRANSFORM <list> REPLACE <regular_expression> + <replace_expression> ...) + +``<SELECTOR>`` select which elements of the list will be transformed. Only one +type of selector can be specified at a time. + +The ``<SELECTOR>`` may be one of: + +``AT``: Specify a list of indexes. :: + + list(TRANSFORM <list> <ACTION> AT <index> [<index> ...] ...) + +``FOR``: Specify a range with, optionally, an increment used to iterate over +the range. :: + + list(TRANSFORM <list> <ACTION> FOR <start> <stop> [<step>] ...) + +``REGEX``: Specify a regular expression. Only elements matching the regular +expression will be transformed. :: + + list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...) + + +Ordering +^^^^^^^^ + +.. _REVERSE: + +:: + + list(REVERSE <list>) + +Reverses the contents of the list in-place. + +.. _SORT: + +:: + + list(SORT <list>) -The list subcommands ``APPEND``, ``INSERT``, ``FILTER``, ``REMOVE_AT``, -``REMOVE_ITEM``, ``REMOVE_DUPLICATES``, ``REVERSE`` and ``SORT`` may create new -values for the list within the current CMake variable scope. Similar to the -:command:`set` command, the LIST command creates new variable values in the -current scope, even if the list itself is actually defined in a parent -scope. To propagate the results of these operations upwards, use -:command:`set` with ``PARENT_SCOPE``, :command:`set` with -``CACHE INTERNAL``, or some other means of value propagation. -NOTES: A list in cmake is a ``;`` separated group of strings. To create a -list the set command can be used. For example, ``set(var a b c d e)`` -creates a list with ``a;b;c;d;e``, and ``set(var "a b c d e")`` creates a -string or a list with one item in it. (Note macro arguments are not -variables, and therefore cannot be used in LIST commands.) - -When specifying index values, if ``<element index>`` is 0 or greater, it -is indexed from the beginning of the list, with 0 representing the -first list element. If ``<element index>`` is -1 or lesser, it is indexed -from the end of the list, with -1 representing the last list element. -Be careful when counting with negative indices: they do not start from -0. -0 is equivalent to 0, the first list element. +Sorts the list in-place alphabetically. |