pm__core.disallow_special_names.cmake

include_guard(GLOBAL)

include(pm__core.msg)


function(pm_disallow_special_names)
    foreach(V IN LISTS ARGV)
        if(V MATCHES "^ARG[VNC]$" OR
           V MATCHES "^ARGV[0-9]+$")
            pm_exit(
                "A variable, \"${V}\", passed into this function is a "
                "special-case variable name that is generated for all CMake "
                "function and macro invocations. We are, by definition, unable "
                "to read or modify the contents of such variables outside of "
                "the scope for which they were geneated---e.g. in any called "
                "function. (You might be able to ex; `set(argn ${ARGN})` and "
                "pass `argn` to be read/modified by a called function, though.)"
            )
        elseif(V MATCHES "^UNPARSED_ARGUMENTS$" OR
               V MATCHES "^UNSET_PARAMETERS$")
            pm_warn_devs(
                "A variable, \"${V}\", passed into this function is a "
                "special-case variable name that is generated by "
                "`pm_parse_arguments`. Called functions are technically "
                "capable of reading and modifying the contents of this "
                "variable, but it is *highly* likely that passing it will "
                "result in local shadowing that will lead to not-so-subtle "
                "bugs (it's all but guaranteed if `pm_parse_arguments` is "
                "called in the same scope)."
            )
        elseif(V STREQUAL "OUTn")
            pm_warn_devs(
                "You seem to be passing the variable \"OUTn\" *into* a called "
                "function. It's our convention to use that variable to store "
                "the name of functions' output parameters. If you're passing "
                "\"OUTn\" into a function that has an argument named \"OUTn\", "
                "you're going to see some _really_ weird variable shaodowing "
                "issues. (You might be ble to ex; `set(outn ${OUTn})` and pass "
                "`outn` into the called function, though.)"
            )
        endif()
    endforeach()
endfunction()


function(pm_loosely_disallow_special_names)
    foreach(V IN LISTS ARGV)
        if(V MATCHES "^ARG[VNC]$" OR
           V MATCHES "^ARGV[0-9]+$")
            pm_exit(
                "A variable, \"${V}\", passed into this function is a "
                "special-case variable name that is generated for all CMake "
                "function and macro invocations. We are, by definition, unable "
                "to read or modify the contents of such variables outside of "
                "the scope for which they were geneated---e.g. in any called "
                "function. (You might be able to ex; `set(argn ${ARGN})` and "
                "pass `argn` to be read/modified by a called function, though.)"
            )
        elseif(V STREQUAL "OUTn")
            message(STATUS "V :: ${V}")
            pm_warn_devs(
                "You seem to be passing the variable \"OUTn\" *into* a called "
                "function. It's our convention to use that variable to store "
                "the name of functions' output parameters. If you're passing "
                "\"OUTn\" into a function that has an argument named \"OUTn\", "
                "you're going to see some _really_ weird variable shaodowing "
                "issues. (You might be ble to ex; `set(outn ${OUTn})` and pass "
                "`outn` into the called function, though.)"
            )
        endif()
    endforeach()
endfunction()