cmake -E env: Add --modify flag

When `cmake -E env` is given the `--modify` flag, try to parse the
following argument as an `ENVIRONMENT_MODIFICATION` operation and apply
it to the environment.

This generalizes `--unset=`:

1.  When implementing `ENVIRONMENT_MODIFICATION` features for other CMake
    commands, the `MYVAR=OP:VALUE` strings do not need to be translated
    to OP-specific flags.
2.  This provides a natural and consistent extension point to introduce
    new operations without introducing very many flags.
3.  Users need to learn only one syntax to access the same functionality.

There is one difference between the behavior here as compared to CTest's
interpretation of the `ENVIRONMENT_MODIFICATION` test property.
The `MYVAR=reset:` command when run in `cmake -E env` will reset `MYVAR`
to whatever its value was when `cmake -E env` launched, rather than try
to checkpoint after plain `MYVAR=VALUE` options.  This makes `MYVAR=VALUE`
and `--modify MYVAR=set:VALUE` semantically equivalent.

14 files changed, 83 insertions, 0 deletions

diff --git a/Tests/RunCMake/CommandLine/E_env-equal.cmake b/Tests/RunCMake/CommandLine/E_env-equal.cmake
new file mode 100644
index 0000000000..3f18bb65f7
--- /dev/null
+++ b/Tests/RunCMake/CommandLine/E_env-equal.cmake
@@ -0,0 +1,15 @@
+if (NOT DEFINED ENV{TEST_ENV_EXPECTED})
+    if (NOT DEFINED ENV{TEST_ENV})
+        message(STATUS "TEST_ENV is correctly not set in environment")
+    else ()
+        message(FATAL_ERROR "TEST_ENV is incorrectly set in environment")
+    endif ()
+else ()
+    if (NOT DEFINED ENV{TEST_ENV})
+        message(FATAL_ERROR "TEST_ENV is incorrectly not set in environment")
+    elseif ("$ENV{TEST_ENV}" STREQUAL "$ENV{TEST_ENV_EXPECTED}")
+        message(STATUS "TEST_ENV is correctly set in environment: $ENV{TEST_ENV}")
+    else ()
+        message(FATAL_ERROR "TEST_ENV is incorrectly set in environment!\n\tactual: $ENV{TEST_ENV}\n\texpected: $ENV{TEST_ENV_EXPECTED}")
+    endif ()
+endif ()
diff --git a/Tests/RunCMake/CommandLine/E_env_modify-bad-operation-result.txt b/Tests/RunCMake/CommandLine/E_env_modify-bad-operation-result.txt
new file mode 100644
index 0000000000..d00491fd7e
--- /dev/null
+++ b/Tests/RunCMake/CommandLine/E_env_modify-bad-operation-result.txt
@@ -0,0 +1 @@
+1
diff --git a/Tests/RunCMake/CommandLine/E_env_modify-bad-operation-stderr.txt b/Tests/RunCMake/CommandLine/E_env_modify-bad-operation-stderr.txt
new file mode 100644
index 0000000000..ccfdeab3df
--- /dev/null
+++ b/Tests/RunCMake/CommandLine/E_env_modify-bad-operation-stderr.txt
@@ -0,0 +1,3 @@
+^CMake Error: Error: Unrecognized environment manipulation argument: unknown
+
+cmake -E env: invalid parameter to --modify: TEST_ENV=unknown:$
diff --git a/Tests/RunCMake/CommandLine/E_env_modify-cmake_list-stdout.txt b/Tests/RunCMake/CommandLine/E_env_modify-cmake_list-stdout.txt
new file mode 100644
index 0000000000..ad42f56937
--- /dev/null
+++ b/Tests/RunCMake/CommandLine/E_env_modify-cmake_list-stdout.txt
@@ -0,0 +1 @@
+^-- TEST_ENV is correctly set in environment: exp;ect;ed$
diff --git a/Tests/RunCMake/CommandLine/E_env_modify-path_list-stdout.txt b/Tests/RunCMake/CommandLine/E_env_modify-path_list-stdout.txt
new file mode 100644
index 0000000000..49572a3d38
--- /dev/null
+++ b/Tests/RunCMake/CommandLine/E_env_modify-path_list-stdout.txt
@@ -0,0 +1 @@
+^-- TEST_ENV is correctly set in environment: exp[;:]ect[;:]ed$
diff --git a/Tests/RunCMake/CommandLine/E_env_modify-reset-stdout.txt b/Tests/RunCMake/CommandLine/E_env_modify-reset-stdout.txt
new file mode 100644
index 0000000000..a60f1bf302
--- /dev/null
+++ b/Tests/RunCMake/CommandLine/E_env_modify-reset-stdout.txt
@@ -0,0 +1 @@
+^-- TEST_ENV is correctly set in environment: expected$
diff --git a/Tests/RunCMake/CommandLine/E_env_modify-reset-to-unset-stdout.txt b/Tests/RunCMake/CommandLine/E_env_modify-reset-to-unset-stdout.txt
new file mode 100644
index 0000000000..a1d5c01083
--- /dev/null
+++ b/Tests/RunCMake/CommandLine/E_env_modify-reset-to-unset-stdout.txt
@@ -0,0 +1 @@
+^-- TEST_ENV is correctly not set in environment$
diff --git a/Tests/RunCMake/CommandLine/E_env_modify-set-stdout.txt b/Tests/RunCMake/CommandLine/E_env_modify-set-stdout.txt
new file mode 100644
index 0000000000..feff1176ea
--- /dev/null
+++ b/Tests/RunCMake/CommandLine/E_env_modify-set-stdout.txt
@@ -0,0 +1 @@
+^-- TEST_ENV is correctly set in environment: 1$
diff --git a/Tests/RunCMake/CommandLine/E_env_modify-string-stdout.txt b/Tests/RunCMake/CommandLine/E_env_modify-string-stdout.txt
new file mode 100644
index 0000000000..a60f1bf302
--- /dev/null
+++ b/Tests/RunCMake/CommandLine/E_env_modify-string-stdout.txt
@@ -0,0 +1 @@
+^-- TEST_ENV is correctly set in environment: expected$
diff --git a/Tests/RunCMake/CommandLine/E_env_modify-unset-stdout.txt b/Tests/RunCMake/CommandLine/E_env_modify-unset-stdout.txt
new file mode 100644
index 0000000000..a1d5c01083
--- /dev/null
+++ b/Tests/RunCMake/CommandLine/E_env_modify-unset-stdout.txt
@@ -0,0 +1 @@
+^-- TEST_ENV is correctly not set in environment$
diff --git a/Tests/RunCMake/CommandLine/E_env_modify-with-double-dash-result.txt b/Tests/RunCMake/CommandLine/E_env_modify-with-double-dash-result.txt
new file mode 100644
index 0000000000..573541ac97
--- /dev/null
+++ b/Tests/RunCMake/CommandLine/E_env_modify-with-double-dash-result.txt
@@ -0,0 +1 @@
+0
diff --git a/Tests/RunCMake/CommandLine/E_env_modify-without-double-dash-result.txt b/Tests/RunCMake/CommandLine/E_env_modify-without-double-dash-result.txt
new file mode 100644
index 0000000000..d00491fd7e
--- /dev/null
+++ b/Tests/RunCMake/CommandLine/E_env_modify-without-double-dash-result.txt
@@ -0,0 +1 @@
+1
diff --git a/Tests/RunCMake/CommandLine/E_env_modify-without-double-dash-stderr.txt b/Tests/RunCMake/CommandLine/E_env_modify-without-double-dash-stderr.txt
new file mode 100644
index 0000000000..8d98f9debd
--- /dev/null
+++ b/Tests/RunCMake/CommandLine/E_env_modify-without-double-dash-stderr.txt
@@ -0,0 +1 @@
+.*
diff --git a/Tests/RunCMake/CommandLine/RunCMakeTest.cmake b/Tests/RunCMake/CommandLine/RunCMakeTest.cmake
index 39d7858c23..7da0f8d82c 100644
--- a/Tests/RunCMake/CommandLine/RunCMakeTest.cmake
+++ b/Tests/RunCMake/CommandLine/RunCMakeTest.cmake
@@ -744,6 +744,10 @@ run_cmake_command(E_cat-without-double-dash ${CMAKE_COMMAND} -E cat "-file-start
 unset(RunCMake_TEST_COMMAND_WORKING_DIRECTORY)
 unset(out)
 
+# Unset environment variables that are used for testing cmake -E
+unset(ENV{TEST_ENV})
+unset(ENV{TEST_ENV_EXPECTED})
+
 run_cmake_command(E_env-no-command0 ${CMAKE_COMMAND} -E env)
 run_cmake_command(E_env-no-command1 ${CMAKE_COMMAND} -E env TEST_ENV=1)
 run_cmake_command(E_env-bad-arg1 ${CMAKE_COMMAND} -E env -bad-arg1)
@@ -758,6 +762,56 @@ file(COPY_FILE "${EXIT_CODE_EXE}" "${RunCMake_BINARY_DIR}/env=${exit_code}")
 run_cmake_command(E_env-with-double-dash ${CMAKE_COMMAND} -E env TEST_ENV=1 -- "${RunCMake_BINARY_DIR}/env=${exit_code}" zero_exit)
 run_cmake_command(E_env-without-double-dash ${CMAKE_COMMAND} -E env TEST_ENV=1 "${RunCMake_BINARY_DIR}/env=${exit_code}" zero_exit)
 
+## Tests of env --modify
+# Repeat the same tests as above
+run_cmake_command(E_env_modify-set   ${CMAKE_COMMAND} -E env --modify TEST_ENV=set:1 ${CMAKE_COMMAND} -P ${RunCMake_SOURCE_DIR}/E_env-set.cmake)
+run_cmake_command(E_env_modify-unset ${CMAKE_COMMAND} -E env --modify TEST_ENV=set:1 ${CMAKE_COMMAND} -E env --modify TEST_ENV=unset: ${CMAKE_COMMAND} -P ${RunCMake_SOURCE_DIR}/E_env-unset.cmake)
+run_cmake_command(E_env_modify-with-double-dash ${CMAKE_COMMAND} -E env --modify TEST_ENV=set:1 -- "${RunCMake_BINARY_DIR}/env=${exit_code}" zero_exit)
+run_cmake_command(E_env_modify-without-double-dash ${CMAKE_COMMAND} -E env --modify TEST_ENV=set:1 "${RunCMake_BINARY_DIR}/env=${exit_code}" zero_exit)
+
+# Test environment modification commands
+run_cmake_command(E_env_modify-reset
+                  ${CMAKE_COMMAND} -E env TEST_ENV=expected
+                  ${CMAKE_COMMAND} -E env TEST_ENV_EXPECTED=expected TEST_ENV=bad_value --modify TEST_ENV=reset:
+                  ${CMAKE_COMMAND} -P ${RunCMake_SOURCE_DIR}/E_env-equal.cmake)
+
+run_cmake_command(E_env_modify-reset-to-unset
+                  ${CMAKE_COMMAND} -E env --unset=TEST_ENV --unset=TEST_ENV_EXPECTED
+                  ${CMAKE_COMMAND} -E env TEST_ENV=bad_value --modify TEST_ENV=reset:
+                  ${CMAKE_COMMAND} -P ${RunCMake_SOURCE_DIR}/E_env-equal.cmake)
+
+run_cmake_command(E_env_modify-string
+                  ${CMAKE_COMMAND} -E env TEST_ENV_EXPECTED=expected
+                  --modify TEST_ENV=unset:
+                  --modify TEST_ENV=string_append:ect
+                  --modify TEST_ENV=string_prepend:exp
+                  --modify TEST_ENV=string_append:ed
+                  ${CMAKE_COMMAND} -P ${RunCMake_SOURCE_DIR}/E_env-equal.cmake)
+
+if (WIN32)
+  set(SEP "\\;")
+else ()
+  set(SEP ":")
+endif ()
+
+run_cmake_command(E_env_modify-path_list
+                  ${CMAKE_COMMAND} -E env "TEST_ENV_EXPECTED=exp${SEP}ect${SEP}ed"
+                  --modify TEST_ENV=unset:
+                  --modify TEST_ENV=path_list_append:ect
+                  --modify TEST_ENV=path_list_prepend:exp
+                  --modify TEST_ENV=path_list_append:ed
+                  ${CMAKE_COMMAND} -P ${RunCMake_SOURCE_DIR}/E_env-equal.cmake)
+
+run_cmake_command(E_env_modify-cmake_list
+                  ${CMAKE_COMMAND} -E env "TEST_ENV_EXPECTED=exp\\;ect\\;ed"
+                  --modify TEST_ENV=unset:
+                  --modify TEST_ENV=cmake_list_append:ect
+                  --modify TEST_ENV=cmake_list_prepend:exp
+                  --modify TEST_ENV=cmake_list_append:ed
+                  ${CMAKE_COMMAND} -P ${RunCMake_SOURCE_DIR}/E_env-equal.cmake)
+
+run_cmake_command(E_env_modify-bad-operation ${CMAKE_COMMAND} -E env --modify TEST_ENV=unknown:)
+
 run_cmake_command(E_md5sum-dir ${CMAKE_COMMAND} -E md5sum .)
 run_cmake_command(E_sha1sum-dir ${CMAKE_COMMAND} -E sha1sum .)
 run_cmake_command(E_sha224sum-dir ${CMAKE_COMMAND} -E sha224sum .)