[(z_)vcpkg_prettify_command(_line)] Scripts Tree Audit (#16130)

* [vcpkg_prettify_command] Audit

* rename file

* rename out-var in docs

* fix file path

* add internal use message to docs

* escapin' in z_vcpkg_prettify_command_line

* regenerate docs

1 files changed, 48 insertions, 0 deletions

diff --git a/scripts/cmake/z_vcpkg_function_arguments.cmake b/scripts/cmake/z_vcpkg_function_arguments.cmake
new file mode 100644
index 000000000..a189c816d
--- /dev/null
+++ b/scripts/cmake/z_vcpkg_function_arguments.cmake
@@ -0,0 +1,48 @@
+#[===[.md:
+# z_vcpkg_function_arguments
+
+**Only for internal use in vcpkg helpers. Behavior and arguments will change without notice.**
+Get a list of the arguments which were passed in.
+Unlike `ARGV`, which is simply the arguments joined with `;`,
+so that `(A B)` is not distinguishable from `("A;B")`,
+this macro gives `"A;B"` for the first argument list,
+and `"A\;B"` for the second.
+
+```cmake
+z_vcpkg_function_arguments(<out-var> [<N>])
+```
+
+`z_vcpkg_function_arguments` gets the arguments between `ARGV<N>` and the last argument.
+`<N>` defaults to `0`, so that all arguments are taken.
+
+## Example:
+```cmake
+function(foo_replacement)
+    z_vcpkg_function_arguments(ARGS)
+    foo(${ARGS})
+    ...
+endfunction()
+```
+#]===]
+macro(z_vcpkg_function_arguments OUT_VAR)
+    if("${ARGC}" EQUAL 1)
+        set(z_vcpkg_function_arguments_FIRST_ARG 0)
+    elseif("${ARGC}" EQUAL 2)
+        set(z_vcpkg_function_arguments_FIRST_ARG "${ARGV1}")
+    else()
+        # vcpkg bug
+        message(FATAL_ERROR "z_vcpkg_function_arguments: invalid arguments (${ARGV})")
+    endif()
+
+    set("${OUT_VAR}")
+
+    # this allows us to get the value of the enclosing function's ARGC
+    set(z_vcpkg_function_arguments_ARGC_NAME "ARGC")
+    set(z_vcpkg_function_arguments_ARGC "${${z_vcpkg_function_arguments_ARGC_NAME}}")
+
+    math(EXPR z_vcpkg_function_arguments_LAST_ARG "${z_vcpkg_function_arguments_ARGC} - 1")
+    foreach(z_vcpkg_function_arguments_N RANGE "${z_vcpkg_function_arguments_FIRST_ARG}" "${z_vcpkg_function_arguments_LAST_ARG}")
+        string(REPLACE ";" "\\;" z_vcpkg_function_arguments_ESCAPED_ARG "${ARGV${z_vcpkg_function_arguments_N}}")
+        list(APPEND "${OUT_VAR}" "${z_vcpkg_function_arguments_ESCAPED_ARG}")
+    endforeach()
+endmacro()