From a1dc38a5670939a8ce8dfd99282f86d47412a98a Mon Sep 17 00:00:00 2001
From: scivision <scivision@users.noreply.github.com>
Date: Mon, 23 Jan 2023 10:47:54 -0500
Subject: Help: Document behavior of if(EXISTS,IS_DIRECTORY) for empty paths

Document and add explicit tests for empty string input:
`if(EXISTS "")` and `if(IS_DIRECTORY "")` are always false.
This avoids need for users to do extra checks due to
CMake non-short-circuit logic as below:

    if("${p}")
      if(EXISTS "${p}")
---
 Help/command/if.rst                     | 8 ++++++--
 Tests/RunCMake/if/IsDirectoryLong.cmake | 3 +++
 Tests/RunCMake/if/RunCMakeTest.cmake    | 1 +
 Tests/RunCMake/if/exists.cmake          | 3 +++
 4 files changed, 13 insertions(+), 2 deletions(-)
 create mode 100644 Tests/RunCMake/if/exists.cmake

diff --git a/Help/command/if.rst b/Help/command/if.rst
index a57630b..684c113 100644
--- a/Help/command/if.rst
+++ b/Help/command/if.rst
@@ -165,6 +165,8 @@ File Operations
  Resolves symbolic links, i.e. if the named file or directory is a
  symbolic link, returns true if the target of the symbolic link exists.
 
+ False if the given path is an empty string.
+
 ``if(file1 IS_NEWER_THAN file2)``
  True if ``file1`` is newer than ``file2`` or if one of the two files doesn't
  exist.  Behavior is well-defined only for full paths.  If the file
@@ -173,10 +175,12 @@ File Operations
  of a tie.  This includes the case of passing the same file name for
  both file1 and file2.
 
-``if(IS_DIRECTORY path-to-directory)``
- True if the given name is a directory.  Behavior is well-defined only
+``if(IS_DIRECTORY path)``
+ True if ``path`` is a directory.  Behavior is well-defined only
  for full paths.
 
+ False if the given path is an empty string.
+
 ``if(IS_SYMLINK file-name)``
  True if the given name is a symbolic link.  Behavior is well-defined
  only for full paths.
diff --git a/Tests/RunCMake/if/IsDirectoryLong.cmake b/Tests/RunCMake/if/IsDirectoryLong.cmake
index e6939ac..41f1818 100644
--- a/Tests/RunCMake/if/IsDirectoryLong.cmake
+++ b/Tests/RunCMake/if/IsDirectoryLong.cmake
@@ -8,3 +8,6 @@ if(IS_DIRECTORY "${d}/")
 else()
   message(STATUS "Directory path with length ${dl} correctly does not exist.")
 endif()
+if(IS_DIRECTORY "")
+  message(FATAL_ERROR "IS_DIRECTORY \"\" should not exist")
+endif()
diff --git a/Tests/RunCMake/if/RunCMakeTest.cmake b/Tests/RunCMake/if/RunCMakeTest.cmake
index de9cb57..efee116 100644
--- a/Tests/RunCMake/if/RunCMakeTest.cmake
+++ b/Tests/RunCMake/if/RunCMakeTest.cmake
@@ -1,6 +1,7 @@
 include(RunCMake)
 
 run_cmake(InvalidArgument1)
+run_cmake(exists)
 run_cmake(IsDirectory)
 run_cmake(IsDirectoryLong)
 run_cmake(duplicate-deep-else)
diff --git a/Tests/RunCMake/if/exists.cmake b/Tests/RunCMake/if/exists.cmake
new file mode 100644
index 0000000..2e5c0ee
--- /dev/null
+++ b/Tests/RunCMake/if/exists.cmake
@@ -0,0 +1,3 @@
+if(EXISTS "")
+  message(FATAL_ERROR "EXISTS \"\" should not exist")
+endif()
-- 
cgit v0.12