cmake_path: rename 'GET ... RELATIVE_PATH' to 'GET ... RELATIVE_PART'

For consistency, subcommand 'HAS_RELATIVE_PATH' is also renamed
to 'HAS_RELATIVE_PART'.

Fixes: #21385

Help/command/cmake_path.rst

@@ -36,7 +36,7 @@ Synopsis
     cmake_path(`GET`_ <path-var> :ref:`FILENAME <GET_FILENAME>` <out-var>)
     cmake_path(`GET`_ <path-var> :ref:`EXTENSION <GET_EXTENSION>` [LAST_ONLY] <out-var>)
     cmake_path(`GET`_ <path-var> :ref:`STEM <GET_STEM>` [LAST_ONLY] <out-var>)
-    cmake_path(`GET`_ <path-var> :ref:`RELATIVE_PATH <GET_RELATIVE_PATH>` <out-var>)
+    cmake_path(`GET`_ <path-var> :ref:`RELATIVE_PART <GET_RELATIVE_PART>` <out-var>)
     cmake_path(`GET`_ <path-var> :ref:`PARENT_PATH <GET_PARENT_PATH>` <out-var>)
 
   `Query`_
@@ -46,7 +46,7 @@ Synopsis
     cmake_path(`HAS_FILENAME`_ <path-var> <out-var>)
     cmake_path(`HAS_EXTENSION`_ <path-var> <out-var>)
     cmake_path(`HAS_STEM`_ <path-var> <out-var>)
-    cmake_path(`HAS_RELATIVE_PATH`_ <path-var> <out-var>)
+    cmake_path(`HAS_RELATIVE_PART`_ <path-var> <out-var>)
     cmake_path(`HAS_PARENT_PATH`_ <path-var> <out-var>)
     cmake_path(`IS_ABSOLUTE`_ <path-var> <out-var>)
     cmake_path(`IS_RELATIVE`_ <path-var> <out-var>)
@@ -161,7 +161,9 @@ constraints):
   The *stem* is the part of the ``filename`` before the extension.
 
 Some commands refer to a ``root-path``.  This is the concatenation of
-``root-name`` and ``root-directory``, either or both of which can be empty.
+``root-name`` and ``root-directory-separator``, either or both of which can
+be empty.  A ``relative-part`` refers to the full path with any ``root-path``
+removed.
 
 
 Creating A Path Variable
@@ -224,10 +226,12 @@ Decomposition
 .. _GET_FILENAME:
 .. _GET_EXTENSION:
 .. _GET_STEM:
+.. _GET_RELATIVE_PART:
+.. _GET_PARENT_PATH:
 
 The following forms of the ``GET`` subcommand each retrieve a different
-component or group of components from a path.
-`Path Structure And Terminology`_ defines the meaning of each path component.
+component or group of components from a path.  See
+`Path Structure And Terminology`_ for the meaning of each path component.
 
 ::
 
@@ -237,12 +241,19 @@ component or group of components from a path.
   cmake_path(GET <path-var> FILENAME <out-var>)
   cmake_path(GET <path-var> EXTENSION [LAST_ONLY] <out-var>)
   cmake_path(GET <path-var> STEM [LAST_ONLY] <out-var>)
+  cmake_path(GET <path-var> RELATIVE_PART <out-var>)
+  cmake_path(GET <path-var> PARENT_PATH <out-var>)
 
 If a requested component is not present in the path, an empty string will be
 stored in ``<out-var>``.  For example, only Windows systems have the concept
 of a ``root-name``, so when the host machine is non-Windows, the ``ROOT_NAME``
 subcommand will always return an empty string.
 
+For ``PARENT_PATH``, if the `HAS_RELATIVE_PART`_ subcommand returns false,
+the result is a copy of ``<path-var>``.  Note that this implies that a root
+directory is considered to have a parent, with that parent being itself.
+Where `HAS_RELATIVE_PART`_ returns true, the result will essentially be
+``<path-var>`` with one less element.
 
 Root examples
 """""""""""""
@@ -332,53 +343,31 @@ Extension and stem examples
   .some.more extension is ".more"
   .some.more stem is ".some"
 
-
-Relative paths
-""""""""""""""
-
-Two other forms of the ``GET`` subcommand interpret a path and return
-another path derived from it.
-
-.. _GET_RELATIVE_PATH:
-
-::
-
-  cmake_path(GET <path-var> RELATIVE_PATH <out-var>)
-
-Returns the path with any ``root-name`` and ``root-directory-separator``
-removed.  This leaves just the part of the path relative to the root
-directory (or put another way, every component of ``<path-var>`` after
-``root-path``).  If ``<path-var>`` is an empty path, it returns an empty
-path.
-
-For example:
+Relative part examples
+""""""""""""""""""""""
 
 .. code-block:: cmake
 
-  set(path "/a/b")
-  cmake_path(GET path RELATIVE_PATH result)
-  message("Relative path is \"${result}\"")
-
-  set(path "/")
-  cmake_path(GET path RELATIVE_PATH result)
-  message("Relative path is \"${result}\"")
-
-Output::
-
-  Relative path is "a/b"
-  Relative path is ""
+  set(path "c:/a/b")
+  cmake_path(GET path RELATIVE_PART result)
+  message("Relative part is \"${result}\"")
 
-.. _GET_PARENT_PATH:
+  set(path "c/d")
+  cmake_path(GET path RELATIVE_PART result)
+  message("Relative part is \"${result}\"")
 
-The other form returns the parent of the path::
+  set(path "/")
+  cmake_path(GET path RELATIVE_PART result)
+  message("Relative part is \"${result}\"")
 
-  cmake_path(GET <path-var> PARENT_PATH <out-var>)
+::
 
-If the `HAS_RELATIVE_PATH`_ sub-command returns false, the result is a
-copy of ``<path-var>``.  Otherwise, the result is ``<path-var>`` with
-one fewer element.
+  Relative part is "a/b"
+  Relative part is "c/d"
+  Relative part is ""
 
-For example:
+Path traversal examples
+"""""""""""""""""""""""
 
 .. code-block:: cmake
 
@@ -390,17 +379,18 @@ For example:
   cmake_path(GET path PARENT_PATH result)
   message("Parent path is \"${result}\"")
 
-Output::
+::
 
   Parent path is "c:/a"
-  Relative path is "c:/"
+  Parent path is "c:/"
+
 
 Query
 ^^^^^
 
-Most of the ``GET`` subcommands also have corresponding ``HAS_...``
-subcommands which can be used to discover whether a particular path
-component is present.  `Path Structure And Terminology`_ defines the
+Each of the ``GET`` subcommands has a corresponding ``HAS_...``
+subcommand which can be used to discover whether a particular path
+component is present.  See `Path Structure And Terminology`_ for the
 meaning of each path component.
 
 .. _HAS_ROOT_NAME:
@@ -409,6 +399,8 @@ meaning of each path component.
 .. _HAS_FILENAME:
 .. _HAS_EXTENSION:
 .. _HAS_STEM:
+.. _HAS_RELATIVE_PART:
+.. _HAS_PARENT_PATH:
 
 ::
 
@@ -418,32 +410,19 @@ meaning of each path component.
   cmake_path(HAS_FILENAME <path-var> <out-var>)
   cmake_path(HAS_EXTENSION <path-var> <out-var>)
   cmake_path(HAS_STEM <path-var> <out-var>)
+  cmake_path(HAS_RELATIVE_PART <path-var> <out-var>)
+  cmake_path(HAS_PARENT_PATH <path-var> <out-var>)
 
 Each of the above follows the predictable pattern of setting ``<out-var>``
 to true if the path has the associated component, or false otherwise.
-In the case of ``HAS_ROOT_PATH``, a true result will only be returned if
-at least one of ``root-name`` or ``root-directory`` is non-empty.
-
-.. _HAS_RELATIVE_PATH:
+Note the following special cases:
 
-::
-
-  cmake_path(HAS_RELATIVE_PATH <path-var> <out-var>)
-
-A relative path in this context means everything after the ``root-path``,
-if present.  This command sets ``<out-var>`` to true if there is at least
-one ``item-name`` or ``filename`` in the path.
-
-.. _HAS_PARENT_PATH:
-
-::
-
-  cmake_path(HAS_PARENT_PATH <path-var> <out-var>)
+* For ``HAS_ROOT_PATH``, a true result will only be returned if at least one
+  of ``root-name`` or ``root-directory`` is non-empty.
 
-This command sets ``<out-var>`` to true if ``<path-var>`` has parent path.
-Note that the root directory is also considered to have a parent, which
-will be itself.  The result is true except if the path consists of just a
-:ref:`filename <FILENAME_DEF>`.
+* For ``HAS_PARENT_PATH``, the root directory is also considered to have a
+  parent, which will be itself.  The result is true except if the path
+  consists of just a :ref:`filename <FILENAME_DEF>`.
 
 .. _IS_ABSOLUTE:
 

Source/cmCMakePathCommand.cxx

@@ -194,7 +194,7 @@ bool HandleGetCommand(std::vector<std::string> const& args,
                  }
                  return path.GetNarrowStem();
                } },
-             { "RELATIVE_PATH"_s,
+             { "RELATIVE_PART"_s,
                [](const cmCMakePath& path, bool) -> cmCMakePath {
                  return path.GetRelativePath();
                } },
@@ -817,7 +817,7 @@ bool HandleHasStemCommand(std::vector<std::string> const& args,
     [](const cmCMakePath& path) -> bool { return path.HasStem(); });
 }
 
-bool HandleHasRelativePathCommand(std::vector<std::string> const& args,
+bool HandleHasRelativePartCommand(std::vector<std::string> const& args,
                                   cmExecutionStatus& status)
 {
   return HandleHasItemCommand(
@@ -986,7 +986,7 @@ bool cmCMakePathCommand(std::vector<std::string> const& args,
     { "HAS_FILENAME"_s, HandleHasFilenameCommand },
     { "HAS_EXTENSION"_s, HandleHasExtensionCommand },
     { "HAS_STEM"_s, HandleHasStemCommand },
-    { "HAS_RELATIVE_PATH"_s, HandleHasRelativePathCommand },
+    { "HAS_RELATIVE_PART"_s, HandleHasRelativePartCommand },
     { "HAS_PARENT_PATH"_s, HandleHasParentPathCommand },
     { "IS_ABSOLUTE"_s, HandleIsAbsoluteCommand },
     { "IS_RELATIVE"_s, HandleIsRelativeCommand },

Tests/RunCMake/cmake_path/GET.cmake

@@ -61,9 +61,9 @@ if (NOT output STREQUAL "cc.ext1")
   list (APPEND errors "STEM LAST_ONLY returns bad data: ${output}")
 endif()
 
-cmake_path(GET path RELATIVE_PATH output)
+cmake_path(GET path RELATIVE_PART output)
 if (NOT output STREQUAL "aa/bb/cc.ext1.ext2")
-  list (APPEND errors "RELATIVE_PATH returns bad data: ${output}")
+  list (APPEND errors "RELATIVE_PART returns bad data: ${output}")
 endif()
 
 cmake_path(GET path PARENT_PATH output)
@@ -112,9 +112,9 @@ if (NOT output STREQUAL "")
   list (APPEND errors "STEM returns bad data: ${output}")
 endif()
 
-cmake_path(GET path RELATIVE_PATH output)
+cmake_path(GET path RELATIVE_PART output)
 if (NOT output STREQUAL path)
-  list (APPEND errors "RELATIVE_PATH returns bad data: ${output}")
+  list (APPEND errors "RELATIVE_PART returns bad data: ${output}")
 endif()
 
 cmake_path(GET path PARENT_PATH output)
@@ -173,9 +173,9 @@ if (NOT output STREQUAL "")
   list (APPEND errors "STEM returns bad data: ${output}")
 endif()
 
-cmake_path(GET path RELATIVE_PATH output)
+cmake_path(GET path RELATIVE_PART output)
 if (NOT output STREQUAL "")
-  list (APPEND errors "RELATIVE_PATH returns bad data: ${output}")
+  list (APPEND errors "RELATIVE_PART returns bad data: ${output}")
 endif()
 
 cmake_path(GET path PARENT_PATH output)

Tests/RunCMake/cmake_path/HAS_ITEM.cmake

@@ -96,14 +96,14 @@ if (output)
 endif()
 
 set (path "/a/b")
-cmake_path(HAS_RELATIVE_PATH path output)
+cmake_path(HAS_RELATIVE_PART path output)
 if (NOT output)
-  list (APPEND errors "RELATIVE_PATH: ${path} does not have relative path")
+  list (APPEND errors "RELATIVE_PART: ${path} does not have relative part")
 endif()
 set (path "/")
-cmake_path(HAS_RELATIVE_PATH path output)
+cmake_path(HAS_RELATIVE_PART path output)
 if (output)
-  list (APPEND errors "RELATIVE_PATH: ${path} has relative path")
+  list (APPEND errors "RELATIVE_PART: ${path} has relative part")
 endif()
 
 set (path "/a/b")
@@ -180,21 +180,21 @@ if (WIN32)
   endif()
 
   set (path "c:/a/b")
-  cmake_path(HAS_RELATIVE_PATH path output)
+  cmake_path(HAS_RELATIVE_PART path output)
   if (NOT output)
-    list (APPEND errors "RELATIVE_PATH: ${path} does not have relative path")
+    list (APPEND errors "RELATIVE_PART: ${path} does not have relative part")
   endif()
 
   set (path "c:a/b")
-  cmake_path(HAS_RELATIVE_PATH path output)
+  cmake_path(HAS_RELATIVE_PART path output)
   if (NOT output)
-    list (APPEND errors "RELATIVE_PATH: ${path} does not have relative path")
+    list (APPEND errors "RELATIVE_PART: ${path} does not have relative part")
   endif()
 
   set (path "//host/b")
-  cmake_path(HAS_RELATIVE_PATH path output)
+  cmake_path(HAS_RELATIVE_PART path output)
   if (NOT output)
-    list (APPEND errors "RELATIVE_PATH: ${path} does not have relative path")
+    list (APPEND errors "RELATIVE_PART: ${path} does not have relative part")
   endif()
 
   set (path "c:/a/b")

Tests/RunCMake/cmake_path/RunCMakeTest.cmake

@@ -7,7 +7,7 @@ set (RunCMake-stderr-file "wrong-path-stderr.txt")
 
 ### GET sub-command
 foreach (subcommand IN ITEMS ROOT_NAME ROOT_DIRECTORY ROOT_PATH FILENAME EXTENSION
-                             STEM RELATIVE_PATH PARENT_PATH)
+                             STEM RELATIVE_PART PARENT_PATH)
   run_cmake_command (GET-${subcommand}-wrong-path "${CMAKE_COMMAND}" "-DCMAKE_PATH_ARGUMENTS=GET wrong_path ${subcommand} output" -P "${RunCMake_SOURCE_DIR}/call-cmake_path.cmake")
 endforeach()
 
@@ -20,7 +20,7 @@ endforeach()
 foreach (command IN ITEMS NATIVE_PATH
                           HAS_ROOT_NAME HAS_ROOT_DIRECTORY HAS_ROOT_PATH
                           HAS_FILENAME HAS_EXTENSION HAS_STEM
-                          HAS_RELATIVE_PATH HAS_PARENT_PATH
+                          HAS_RELATIVE_PART HAS_PARENT_PATH
                           IS_ABSOLUTE IS_RELATIVE IS_PREFIX HASH)
   if (command STREQUAL "IS_PREFIX")
     set (extra_args path2)
@@ -36,7 +36,7 @@ set (RunCMake-stderr-file "missing-output-stderr.txt")
 
 ### GET sub-command
 foreach (subcommand IN ITEMS ROOT_NAME ROOT_DIRECTORY ROOT_PATH FILENAME EXTENSION
-                             STEM RELATIVE_PATH PARENT_PATH)
+                             STEM RELATIVE_PART PARENT_PATH)
   run_cmake_command (GET-${subcommand}-missing-output "${CMAKE_COMMAND}" "-DCMAKE_PATH_ARGUMENTS=GET path ${subcommand}" -P "${RunCMake_SOURCE_DIR}/call-cmake_path.cmake")
 endforeach()
 
@@ -53,7 +53,7 @@ endforeach()
 foreach (command IN ITEMS SET NATIVE_PATH
                           HAS_ROOT_NAME HAS_ROOT_DIRECTORY HAS_ROOT_PATH
                           HAS_FILENAME HAS_EXTENSION HAS_STEM
-                          HAS_RELATIVE_PATH HAS_PARENT_PATH
+                          HAS_RELATIVE_PART HAS_PARENT_PATH
                           IS_ABSOLUTE IS_RELATIVE IS_PREFIX HASH)
   if (command STREQUAL "IS_PREFIX")
     set (extra_args path2)
@@ -79,7 +79,7 @@ set (RunCMake-stderr-file "invalid-output-var-stderr.txt")
 
 ### GET sub-command
 foreach (subcommand IN ITEMS ROOT_NAME ROOT_DIRECTORY ROOT_PATH FILENAME EXTENSION
-                             STEM RELATIVE_PATH PARENT_PATH)
+                             STEM RELATIVE_PART PARENT_PATH)
   run_cmake_command (GET-${subcommand}-invalid-output "${CMAKE_COMMAND}" "-DCMAKE_PATH_ARGUMENTS=GET path ${subcommand}"  -DCHECK_INVALID_OUTPUT=ON -P "${RunCMake_SOURCE_DIR}/call-cmake_path.cmake")
 endforeach()
 
@@ -96,7 +96,7 @@ endforeach()
 foreach (command IN ITEMS NATIVE_PATH
                           HAS_ROOT_NAME HAS_ROOT_DIRECTORY HAS_ROOT_PATH
                           HAS_FILENAME HAS_EXTENSION HAS_STEM
-                          HAS_RELATIVE_PATH HAS_PARENT_PATH
+                          HAS_RELATIVE_PART HAS_PARENT_PATH
                           IS_ABSOLUTE IS_RELATIVE IS_PREFIX HASH)
   if (command STREQUAL "IS_PREFIX")
     set (extra_args path2)
@@ -118,7 +118,7 @@ set (RunCMake-stderr-file "unexpected-arg-stderr.txt")
 
 ### GET sub-command
 foreach (subcommand IN ITEMS ROOT_NAME ROOT_DIRECTORY ROOT_PATH FILENAME EXTENSION
-                             STEM RELATIVE_PATH PARENT_PATH)
+                             STEM RELATIVE_PART PARENT_PATH)
   if (subcommand STREQUAL "EXTENSION" OR subcommand STREQUAL "STEM")
     set (extra_args LAST_ONLY)
   else()
@@ -146,7 +146,7 @@ endforeach()
 foreach (command IN ITEMS SET NATIVE_PATH
                           HAS_ROOT_NAME HAS_ROOT_DIRECTORY HAS_ROOT_PATH
                           HAS_FILENAME HAS_EXTENSION HAS_STEM
-                          HAS_RELATIVE_PATH HAS_PARENT_PATH
+                          HAS_RELATIVE_PART HAS_PARENT_PATH
                           IS_ABSOLUTE IS_RELATIVE IS_PREFIX
                           HASH)
   if (command STREQUAL "IS_PREFIX")