cmake_language: Rename command from cmake_command

Also rename the `INVOKE` signature to `CALL`.

Fixes: #20732

1 files changed, 90 insertions, 0 deletions

diff --git a/Help/command/cmake_language.rst b/Help/command/cmake_language.rst
new file mode 100644
index 0000000..21f51a0
--- /dev/null
+++ b/Help/command/cmake_language.rst
@@ -0,0 +1,90 @@
+cmake_language
+--------------
+
+Call meta-operations on CMake commands.
+
+Synopsis
+^^^^^^^^
+
+.. parsed-literal::
+
+  cmake_language(`CALL`_ <command> [<args>...])
+  cmake_language(`EVAL`_ CODE <code>...)
+
+Introduction
+^^^^^^^^^^^^
+
+This command will call meta-operations on built-in CMake commands or
+those created via the :command:`macro` or :command:`function` commands.
+
+``cmake_language`` does not introduce a new variable or policy scope.
+
+Calling Commands
+^^^^^^^^^^^^^^^^
+
+.. _CALL:
+
+.. code-block:: cmake
+
+  cmake_language(CALL <command> [<args>...])
+
+Calls the named ``<command>`` with the given arguments (if any).
+For example, the code:
+
+.. code-block:: cmake
+
+  set(message_command "message")
+  cmake_language(CALL ${message_command} STATUS "Hello World!")
+
+is equivalent to
+
+.. code-block:: cmake
+
+  message(STATUS "Hello World!")
+
+Evaluating Code
+^^^^^^^^^^^^^^^
+
+.. _EVAL:
+
+.. code-block:: cmake
+
+  cmake_language(EVAL CODE <code>...)
+
+Evaluates the ``<code>...`` as CMake code.
+
+For example, the code:
+
+.. code-block:: cmake
+
+  set(A TRUE)
+  set(B TRUE)
+  set(C TRUE)
+  set(condition "(A AND B) OR C")
+
+  cmake_language(EVAL CODE "
+    if (${condition})
+      message(STATUS TRUE)
+    else()
+      message(STATUS FALSE)
+    endif()"
+  )
+
+is equivalent to
+
+.. code-block:: cmake
+
+  set(A TRUE)
+  set(B TRUE)
+  set(C TRUE)
+  set(condition "(A AND B) OR C")
+
+  file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/eval.cmake "
+    if (${condition})
+      message(STATUS TRUE)
+    else()
+      message(STATUS FALSE)
+    endif()"
+  )
+
+  include(${CMAKE_CURRENT_BINARY_DIR}/eval.cmake)