From e55f473ea9101fe137a046d7a9a561c82a9fbf1d Mon Sep 17 00:00:00 2001
From: Adriaan de Groot <groot@kde.org>
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 <list> [<element> ...])
-Appends elements to the list.
+Appends elements to the list. If no variable named ``<list>`` 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 <groot@kde.org>
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 <list> <element_index> <element> [<element> ...])
-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 <groot@kde.org>
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 <list> <element_index> <element> [<element> ...])
-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 ``<list>`` 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 <groot@kde.org>
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
+``<list>`` 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 <groot@kde.org>
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