From e55f473ea9101fe137a046d7a9a561c82a9fbf1d Mon Sep 17 00:00:00 2001 From: Adriaan de Groot Date: Tue, 21 Dec 2021 15:34:48 +0100 Subject: Help: clarify that list(APPEND) on a non-existent list creates it This is hinted-at in the introduction, which mentions creating a new variable value in the current scope, but let's make it explicit. Fixes: #22910 --- Help/command/list.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Help/command/list.rst b/Help/command/list.rst index 9b49cb4..46285cc 100644 --- a/Help/command/list.rst +++ b/Help/command/list.rst @@ -128,7 +128,9 @@ Modification list(APPEND [ ...]) -Appends elements to the list. +Appends elements to the list. If no variable named ```` exists in the +current scope its value is treated as empty and the elements are appended to +that empty list. .. _FILTER: -- cgit v0.12 From b6fdcb3df0bd8c9643caf694aecfbc13727f99ad Mon Sep 17 00:00:00 2001 From: Adriaan de Groot Date: Tue, 21 Dec 2021 15:35:29 +0100 Subject: Help: clarify description of list(INSERT) Since the argument is called 'index', use that in the description. --- Help/command/list.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Help/command/list.rst b/Help/command/list.rst index 46285cc..bd8277d 100644 --- a/Help/command/list.rst +++ b/Help/command/list.rst @@ -152,7 +152,7 @@ For more information on regular expressions look under list(INSERT [ ...]) -Inserts elements to the list to the specified location. +Inserts elements to the list to the specified index. .. _POP_BACK: -- cgit v0.12 From b3a249c2cb90dc462316e69ccb4a9c7b5ba14618 Mon Sep 17 00:00:00 2001 From: Adriaan de Groot Date: Tue, 21 Dec 2021 15:37:38 +0100 Subject: Help: clarify range for list(INSERT), mention nonexistent / empty case --- Help/command/list.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/Help/command/list.rst b/Help/command/list.rst index bd8277d..621eeb4 100644 --- a/Help/command/list.rst +++ b/Help/command/list.rst @@ -152,7 +152,12 @@ For more information on regular expressions look under list(INSERT [ ...]) -Inserts elements to the list to the specified index. +Inserts elements to the list to 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. If no variable named ```` exists in the +current scope its value is treated as empty and the elements are +inserted in that empty list. .. _POP_BACK: -- cgit v0.12 From b151db01f9ea4ce8a0fb0b8528f2278a4bfb5fc3 Mon Sep 17 00:00:00 2001 From: Adriaan de Groot Date: Tue, 21 Dec 2021 15:38:50 +0100 Subject: Help: mention non-existent case for list(PREPEND) --- Help/command/list.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Help/command/list.rst b/Help/command/list.rst index 621eeb4..33c4f80 100644 --- a/Help/command/list.rst +++ b/Help/command/list.rst @@ -193,7 +193,9 @@ to the given variables and then remove the first `N` values from .. versionadded:: 3.15 -Insert elements to the 0th position in the list. +Insert elements to the 0th position in the list. If no variable named +```` exists in the current scope its value is treated as empty and +the elements are prepended to that empty list. .. _REMOVE_ITEM: -- cgit v0.12 From b573a732dc654f82bd70aeb53666fcf61f26ca16 Mon Sep 17 00:00:00 2001 From: Adriaan de Groot Date: Tue, 21 Dec 2021 15:55:34 +0100 Subject: Tests: add tests to check claims in the documentation - list commands APPEND, PREPEND, INSERT treat non-existent lists as empty and use that value, creating a new list variable in the process. --- Tests/RunCMake/list/LIST-nonexistent.cmake | 45 ++++++++++++++++++++++++++++++ Tests/RunCMake/list/RunCMakeTest.cmake | 3 ++ 2 files changed, 48 insertions(+) create mode 100644 Tests/RunCMake/list/LIST-nonexistent.cmake diff --git a/Tests/RunCMake/list/LIST-nonexistent.cmake b/Tests/RunCMake/list/LIST-nonexistent.cmake new file mode 100644 index 0000000..ee88548 --- /dev/null +++ b/Tests/RunCMake/list/LIST-nonexistent.cmake @@ -0,0 +1,45 @@ +# Various list operations should treat non-existent variables as empty +# - APPEND +# - PREPEND +# - INSERT (only valid index is 0) +set(nex_l0 "") +list(APPEND nex_l0 a) +list(APPEND nex_l0 b) +if(NOT nex_l0 STREQUAL "a;b") + message(FATAL_ERROR "a;b expected, got ${nex_l0}") +endif() + +unset(nex_l1) +list(APPEND nex_l1 c) +list(APPEND nex_l1 d) +if(NOT nex_l1 STREQUAL "c;d") + message(FATAL_ERROR "c;d expected, got ${nex_l1}") +endif() + +set(nex_l2 "") +list(PREPEND nex_l2 E) +list(PREPEND nex_l2 f) +if(NOT nex_l2 STREQUAL "f;E") + message(FATAL_ERROR "f;E expected, got ${nex_l2}") +endif() + +unset(nex_l3) +list(PREPEND nex_l3 hi) +list(PREPEND nex_l3 G) +if(NOT nex_l3 STREQUAL "G;hi") + message(FATAL_ERROR "G;hi expected, got ${nex_l3}") +endif() + +set(nex_l4 "") +list(INSERT nex_l4 0 j) +list(INSERT nex_l4 0 kl) +if(NOT nex_l4 STREQUAL "kl;j") + message(FATAL_ERROR "kl;j expected, got ${nex_l4}") +endif() + +unset(nex_l5) +list(INSERT nex_l5 0 M) +list(INSERT nex_l5 0 noP) +if(NOT nex_l5 STREQUAL "noP;M") + message(FATAL_ERROR "noP;M expected, got ${nex_l5}") +endif() diff --git a/Tests/RunCMake/list/RunCMakeTest.cmake b/Tests/RunCMake/list/RunCMakeTest.cmake index eb43ee0..adfe255 100644 --- a/Tests/RunCMake/list/RunCMakeTest.cmake +++ b/Tests/RunCMake/list/RunCMakeTest.cmake @@ -116,3 +116,6 @@ run_cmake(POP_FRONT-NoArgs) # Successful tests run_cmake(POP_BACK) run_cmake(POP_FRONT) + +# Nonexistent variables treated as empty +run_cmake(LIST-nonexistent) -- cgit v0.12