get_filename_component: Add DIRECTORY option (#14091)

The name "PATH" is not precise so add equivalent option "DIRECTORY".
Document the latter as preferred and the former as a legacy alias.

Source/cmGetFilenameComponentCommand.cxx

@@ -58,7 +58,7 @@ bool cmGetFilenameComponentCommand
     }
   std::string storeArgs;
   std::string programArgs;
-  if (args[2] == "PATH")
+  if (args[2] == "DIRECTORY" || args[2] == "PATH")
     {
     result = cmSystemTools::GetFilenamePath(filename);
     }

Source/cmGetFilenameComponentCommand.h

@@ -64,12 +64,13 @@ public:
     return
       "  get_filename_component(<VAR> <FileName> <COMP> [CACHE])\n"
       "Set <VAR> to a component of <FileName>, where <COMP> is one of:\n"
-      " PATH      = Directory without file name\n"
+      " DIRECTORY = Directory without file name\n"
       " NAME      = File name without directory\n"
       " EXT       = File name longest extension (.b.c from d/a.b.c)\n"
       " NAME_WE   = File name without directory or longest extension\n"
       " ABSOLUTE  = Full path to file\n"
       " REALPATH  = Full path to existing file with symlinks resolved\n"
+      " PATH      = Legacy alias for DIRECTORY (use for CMake <= 2.8.11)\n"
       "Paths are returned with forward slashes and have no trailing slahes. "
       "The longest file extension is always considered. "
       "If the optional CACHE argument is specified, the result variable is "

Tests/RunCMake/get_filename_component/KnownComponents.cmake

@@ -5,28 +5,29 @@ macro(check desc actual expect)
 endmacro()
 
 set(filename "/path/to/filename.ext.in")
-set(expect_PATH "/path/to")
+set(expect_DIRECTORY "/path/to")
 set(expect_NAME "filename.ext.in")
 set(expect_EXT ".ext.in")
 set(expect_NAME_WE "filename")
-foreach(c PATH NAME EXT NAME_WE)
+set(expect_PATH "/path/to")
+foreach(c DIRECTORY NAME EXT NAME_WE PATH)
   get_filename_component(actual_${c} "${filename}" ${c})
   check("${c}" "${actual_${c}}" "${expect_${c}}")
 endforeach()
 
-get_filename_component(test_slashes "c:\\path\\to\\filename.ext.in" PATH)
-check("PATH from backslashes" "${test_slashes}" "c:/path/to")
+get_filename_component(test_slashes "c:\\path\\to\\filename.ext.in" DIRECTORY)
+check("DIRECTORY from backslashes" "${test_slashes}" "c:/path/to")
 
-get_filename_component(test_winroot "c:\\filename.ext.in" PATH)
-check("PATH in windows root" "${test_winroot}" "c:/")
+get_filename_component(test_winroot "c:\\filename.ext.in" DIRECTORY)
+check("DIRECTORY in windows root" "${test_winroot}" "c:/")
 
 get_filename_component(test_absolute "/path/to/a/../filename.ext.in" ABSOLUTE)
 check("ABSOLUTE" "${test_absolute}" "/path/to/filename.ext.in")
 
-get_filename_component(test_cache "/path/to/filename.ext.in" PATH CACHE)
+get_filename_component(test_cache "/path/to/filename.ext.in" DIRECTORY CACHE)
 check("CACHE 1" "${test_cache}" "/path/to")
-get_filename_component(test_cache "/path/to/other/filename.ext.in" PATH CACHE)
+get_filename_component(test_cache "/path/to/other/filename.ext.in" DIRECTORY CACHE)
 check("CACHE 2" "${test_cache}" "/path/to")
 unset(test_cache CACHE)
-get_filename_component(test_cache "/path/to/other/filename.ext.in" PATH CACHE)
+get_filename_component(test_cache "/path/to/other/filename.ext.in" DIRECTORY CACHE)
 check("CACHE 3" "${test_cache}" "/path/to/other")