cmFunctionCommand: Introduce `CMAKE_CURRENT_FUNCTION*` variables

`CMAKE_CURRENT_FUNCTION`
  Can be used for diagnostic or debugging messages like the
  `__PRETTY_FUNCTION__` macro of GCC.

`CMAKE_CURRENT_FUNCTION_LIST_DIR`
  Eliminates the necessity of the additional "global"
  variables inside a module used to access additional "resource"
  files from functions defined in the module.

...

5 files changed, 127 insertions, 0 deletions

diff --git a/Tests/RunCMake/function/CMAKE_CURRENT_FUNCTION-stdout.txt b/Tests/RunCMake/function/CMAKE_CURRENT_FUNCTION-stdout.txt
new file mode 100644
index 0000000..5ebc89a
--- /dev/null
+++ b/Tests/RunCMake/function/CMAKE_CURRENT_FUNCTION-stdout.txt
@@ -0,0 +1,7 @@
+function\(print_self\)
+    file\(STRINGS "\${CMAKE_CURRENT_FUNCTION_LIST_FILE}" _lines\)
+    math\(EXPR _begin "\${CMAKE_CURRENT_FUNCTION_LIST_LINE} - 1"\)
+    list\(SUBLIST _lines \${_begin} 7 _lines\) # This function has 7 lines only
+    list\(JOIN _lines "\\n" _lines\)
+    message\(STATUS "Print the `\${CMAKE_CURRENT_FUNCTION}` function:\\n\${_lines}"\)
+endfunction\(\)
diff --git a/Tests/RunCMake/function/CMAKE_CURRENT_FUNCTION.cmake b/Tests/RunCMake/function/CMAKE_CURRENT_FUNCTION.cmake
new file mode 100644
index 0000000..38c032f
--- /dev/null
+++ b/Tests/RunCMake/function/CMAKE_CURRENT_FUNCTION.cmake
@@ -0,0 +1,94 @@
+set(_THIS_FILE "${CMAKE_CURRENT_LIST_FILE}")
+set(_THIS_DIR "${CMAKE_CURRENT_LIST_DIR}")
+
+if(CMAKE_CURRENT_FUNCTION)
+  message(SEND_ERROR "`CMAKE_CURRENT_FUNCTION` is not expected to be set here")
+endif()
+if(CMAKE_CURRENT_FUNCTION_LIST_FILE)
+  message(SEND_ERROR "`CMAKE_CURRENT_FUNCTION_LIST_FILE` is not expected to be set here")
+endif()
+if(CMAKE_CURRENT_FUNCTION_LIST_DIR)
+  message(SEND_ERROR "`CMAKE_CURRENT_FUNCTION_LIST_DIR` is not expected to be set here")
+endif()
+if(CMAKE_CURRENT_FUNCTION_LIST_LINE)
+  message(SEND_ERROR "`CMAKE_CURRENT_FUNCTION_LIST_LINE` is not expected to be set here")
+endif()
+
+function(bar)
+  if(NOT CMAKE_CURRENT_FUNCTION STREQUAL "bar")
+    message(SEND_ERROR "Bad value of `CMAKE_CURRENT_FUNCTION`")
+  endif()
+  if(NOT CMAKE_CURRENT_FUNCTION_LIST_FILE MATCHES "^.*/CMAKE_CURRENT_FUNCTION.cmake$")
+    message(SEND_ERROR "Bad value of `CMAKE_CURRENT_FUNCTION_LIST_FILE`")
+  endif()
+  if(NOT CMAKE_CURRENT_FUNCTION_LIST_FILE STREQUAL _THIS_FILE)
+    message(SEND_ERROR "Bad value of `CMAKE_CURRENT_FUNCTION_LIST_FILE`")
+  endif()
+  if(NOT CMAKE_CURRENT_FUNCTION_LIST_DIR MATCHES "^.*/Tests/RunCMake/function$")
+    message(SEND_ERROR "Bad value of `CMAKE_CURRENT_FUNCTION_LIST_DIR`")
+  endif()
+  if(NOT CMAKE_CURRENT_FUNCTION_LIST_DIR STREQUAL _THIS_DIR)
+    message(SEND_ERROR "Bad value of `CMAKE_CURRENT_FUNCTION_LIST_DIR`")
+  endif()
+  if(NOT CMAKE_CURRENT_FUNCTION_LIST_LINE EQUAL 17)
+    message(SEND_ERROR "Bad value of `CMAKE_CURRENT_FUNCTION_LIST_LINE`")
+  endif()
+endfunction()
+
+function(foo)
+  if(NOT CMAKE_CURRENT_FUNCTION STREQUAL "foo")
+    message(SEND_ERROR "Bad value of `CMAKE_CURRENT_FUNCTION`")
+  endif()
+  if(NOT CMAKE_CURRENT_FUNCTION_LIST_FILE MATCHES "^.*/function/CMAKE_CURRENT_FUNCTION.cmake$")
+    message(SEND_ERROR "Bad value of `CMAKE_CURRENT_FUNCTION_LIST_FILE`")
+  endif()
+  if(NOT CMAKE_CURRENT_FUNCTION_LIST_FILE STREQUAL _THIS_FILE)
+    message(SEND_ERROR "Bad value of `CMAKE_CURRENT_FUNCTION_LIST_FILE`")
+  endif()
+  if(NOT CMAKE_CURRENT_FUNCTION_LIST_DIR MATCHES "^.*/Tests/RunCMake/function$")
+    message(SEND_ERROR "Bad value of `CMAKE_CURRENT_FUNCTION_LIST_DIR`")
+  endif()
+  if(NOT CMAKE_CURRENT_FUNCTION_LIST_LINE EQUAL 38)
+    message(SEND_ERROR "Bad value of `CMAKE_CURRENT_FUNCTION_LIST_LINE`")
+  endif()
+  if(NOT CMAKE_CURRENT_FUNCTION_LIST_DIR STREQUAL _THIS_DIR)
+    message(SEND_ERROR "Bad value of `CMAKE_CURRENT_FUNCTION_LIST_DIR`")
+  endif()
+  bar()
+endfunction()
+
+foo()
+
+if(CMAKE_CURRENT_FUNCTION)
+  message(SEND_ERROR "`CMAKE_CURRENT_FUNCTION` is not expected to be set here")
+endif()
+if(CMAKE_CURRENT_FUNCTION_LIST_FILE)
+  message(SEND_ERROR "`CMAKE_CURRENT_FUNCTION_LIST_FILE` is not expected to be set here")
+endif()
+if(CMAKE_CURRENT_FUNCTION_LIST_DIR)
+  message(SEND_ERROR "`CMAKE_CURRENT_FUNCTION_LIST_DIR` is not expected to be set here")
+endif()
+if(CMAKE_CURRENT_FUNCTION_LIST_LINE)
+  message(SEND_ERROR "`CMAKE_CURRENT_FUNCTION_LIST_LINE` is not expected to be set here")
+endif()
+
+include("${CMAKE_CURRENT_LIST_DIR}/DummyMacro.cmake")
+
+function(calling_macro)
+  dummy()
+endfunction()
+
+calling_macro()
+
+cmake_policy(SET CMP0007 NEW)
+
+# ATTENTION `CMAKE_CURRENT_LIST_LINE` can't be used in `math()'
+function(print_self)
+    file(STRINGS "${CMAKE_CURRENT_FUNCTION_LIST_FILE}" _lines)
+    math(EXPR _begin "${CMAKE_CURRENT_FUNCTION_LIST_LINE} - 1")
+    list(SUBLIST _lines ${_begin} 7 _lines) # This function has 7 lines only
+    list(JOIN _lines "\n" _lines)
+    message(STATUS "Print the `${CMAKE_CURRENT_FUNCTION}` function:\n${_lines}")
+endfunction()
+
+print_self()
diff --git a/Tests/RunCMake/function/CMakeLists.txt b/Tests/RunCMake/function/CMakeLists.txt
new file mode 100644
index 0000000..2632ffa
--- /dev/null
+++ b/Tests/RunCMake/function/CMakeLists.txt
@@ -0,0 +1,3 @@
+cmake_minimum_required(VERSION 3.16)
+project(${RunCMake_TEST} NONE)
+include(${RunCMake_TEST}.cmake)
diff --git a/Tests/RunCMake/function/DummyMacro.cmake b/Tests/RunCMake/function/DummyMacro.cmake
new file mode 100644
index 0000000..1ab53e4
--- /dev/null
+++ b/Tests/RunCMake/function/DummyMacro.cmake
@@ -0,0 +1,20 @@
+macro(dummy)
+  if(NOT CMAKE_CURRENT_FUNCTION STREQUAL "calling_macro")
+    message(SEND_ERROR "Bad value of `CMAKE_CURRENT_FUNCTION`")
+  endif()
+  if(NOT CMAKE_CURRENT_FUNCTION_LIST_FILE MATCHES "^.*/function/CMAKE_CURRENT_FUNCTION.cmake$")
+    message(SEND_ERROR "Bad value of `CMAKE_CURRENT_FUNCTION_LIST_FILE`")
+  endif()
+  if(NOT CMAKE_CURRENT_FUNCTION_LIST_FILE STREQUAL _THIS_FILE)
+    message(SEND_ERROR "Bad value of `CMAKE_CURRENT_FUNCTION_LIST_FILE`")
+  endif()
+  if(NOT CMAKE_CURRENT_FUNCTION_LIST_DIR MATCHES "^.*/Tests/RunCMake/function$")
+    message(SEND_ERROR "Bad value of `CMAKE_CURRENT_FUNCTION_LIST_DIR`")
+  endif()
+  if(NOT CMAKE_CURRENT_FUNCTION_LIST_LINE EQUAL 77)
+    message(SEND_ERROR "Bad value of `CMAKE_CURRENT_FUNCTION_LIST_LINE`")
+  endif()
+  if(NOT CMAKE_CURRENT_FUNCTION_LIST_DIR STREQUAL _THIS_DIR)
+    message(SEND_ERROR "Bad value of `CMAKE_CURRENT_FUNCTION_LIST_DIR`")
+  endif()
+endmacro()
diff --git a/Tests/RunCMake/function/RunCMakeTest.cmake b/Tests/RunCMake/function/RunCMakeTest.cmake
new file mode 100644
index 0000000..88f48af
--- /dev/null
+++ b/Tests/RunCMake/function/RunCMakeTest.cmake
@@ -0,0 +1,3 @@
+include(RunCMake)
+
+run_cmake(CMAKE_CURRENT_FUNCTION)