| 1 |
# @HEADER |
| 2 |
# ***************************************************************************** |
| 3 |
# TriBITS: Tribal Build, Integrate, and Test System |
| 4 |
# |
| 5 |
# Copyright 2013-2016 NTESS and the TriBITS contributors. |
| 6 |
# SPDX-License-Identifier: BSD-3-Clause |
| 7 |
# ***************************************************************************** |
| 8 |
# @HEADER |
| 9 |
|
| 10 |
include(TribitsDeprecatedHelpers) |
| 11 |
|
| 12 |
|
| 13 |
macro(parse_arguments_deprecated_warning) |
| 14 |
tribits_deprecated_command(parse_arguments |
| 15 |
MESSAGE "Use cmake_parse_arguments() instead.") |
| 16 |
endmacro() |
| 17 |
|
| 18 |
parse_arguments_deprecated_warning() |
| 19 |
|
| 20 |
# Set PARSE_ARGUMENTS_DUMP_OUTPUT_ENABLED to TRUE to see output from parsing. |
| 21 |
|
| 22 |
function(parse_arguments_dump_output OUTPUT_STR) |
| 23 |
if (PARSE_ARGUMENTS_DUMP_OUTPUT_ENABLED) |
| 24 |
message("${OUTPUT_STR}") |
| 25 |
endif() |
| 26 |
endfunction() |
| 27 |
|
| 28 |
|
| 29 |
# @MACRO: parse_arguments() |
| 30 |
# |
| 31 |
# Parse a set of macro/function input arguments into different lists. This |
| 32 |
# allows the easy implementation of keyword-based user-defined macros and |
| 33 |
# functions. |
| 34 |
# |
| 35 |
# Usage:: |
| 36 |
# |
| 37 |
# parse_arguments( |
| 38 |
# <prefix> <argNamesList> <optionNamesList> |
| 39 |
# <inputArgsList> |
| 40 |
# ) |
| 41 |
# |
| 42 |
# Arguments to this macro are: |
| 43 |
# |
| 44 |
# ``<prefix>`` |
| 45 |
# |
| 46 |
# Prefix ``<prefix>_`` added the list and option variables created listed |
| 47 |
# in ``<argNamesList>`` and ``<optionNamesList>``. |
| 48 |
# |
| 49 |
# ``<argNamesList>`` |
| 50 |
# |
| 51 |
# Quoted array of list arguments (e.g. ``"<argName0>;<argName1>;..."``). |
| 52 |
# For each variable name ``<argNamei>``, a local variable will be created |
| 53 |
# in the current scope with the name ``<prefix>_<argNamei>`` which gives |
| 54 |
# the list of variables parsed out of ``<inputArgsList>``. |
| 55 |
# |
| 56 |
# ``<optionNamesList>`` |
| 57 |
# |
| 58 |
# Quoted array of list options (e.g. ``"<optName0>;<optName1>;..."``) |
| 59 |
# typically pass in as ``${ARGN}`` in the outer function/macro. For each |
| 60 |
# variable name ``<optNamei>``, a local variable will be created in the |
| 61 |
# current scope with the name ``<prefix>_<optNamei>`` that is either set |
| 62 |
# to ``TRUE`` or ``FALSE`` depending if ``<optNamei>`` appears in |
| 63 |
# ``<inputArgsList>`` or not. |
| 64 |
# |
| 65 |
# ``<inputArgsList>`` |
| 66 |
# |
| 67 |
# List of arguments keyword-based arguments passed in through the outer |
| 68 |
# macro or function to be parsed out into the different argument and |
| 69 |
# option lists. |
| 70 |
# |
| 71 |
# What this macro does is very simple yet very useful. What it does is to |
| 72 |
# allow one to create one's own user-defined keyword-based macros and |
| 73 |
# functions like is used by some built-in CMake commands. |
| 74 |
# |
| 75 |
# For example, consider the following user-defined macro that uses both |
| 76 |
# positional and keyword-based arguments using ``parse_arguments()``:: |
| 77 |
# |
| 78 |
# macro(parse_special_vars BASE_NAME) |
| 79 |
# |
| 80 |
# parse_arguments( |
| 81 |
# #prefix |
| 82 |
# ${BASE_NAME} |
| 83 |
# #lists |
| 84 |
# "ARG0;ARG1;ARG2" |
| 85 |
# #options |
| 86 |
# "OPT0;OPT1" |
| 87 |
# ${ARGN} |
| 88 |
# ) |
| 89 |
# |
| 90 |
# endmacro() |
| 91 |
# |
| 92 |
# Calling this macro as:: |
| 93 |
# |
| 94 |
# parse_special_vars(MyVar ARG0 a b ARG2 c OPT1) |
| 95 |
# |
| 96 |
# sets the following variables in the current scope:: |
| 97 |
# |
| 98 |
# MyVar_ARG0="a;b" |
| 99 |
# MyVar_ARG1="" |
| 100 |
# MyVar_ARG2="c" |
| 101 |
# MyVar_OPT0="FALSE" |
| 102 |
# MyVar_OPT1="TRUE" |
| 103 |
# |
| 104 |
# This allows one to define user-defined macros and functions that have a |
| 105 |
# mixture of positional arguments and keyword-based arguments like one can do |
| 106 |
# in other languages. The keyword-based arguments can be passed in any order |
| 107 |
# and those that are missing are empty (or false for options) by default. |
| 108 |
# |
| 109 |
# Any initial arguments that are not recognized as ``<argNamesList>`` or |
| 110 |
# ``<optionNamesList>`` keyword arguments will be put into the local variable |
| 111 |
# ``<prefix>_DEFAULT_ARGS``. If no arguments in ``<inputArgsList>`` |
| 112 |
# (typically ``${ARGN}``) match any in ``<argNamesList>``, then all non-option |
| 113 |
# arguments are put into ``<prefix>_DEFAULT_ARGS``. For example, if one |
| 114 |
# passes in:: |
| 115 |
# |
| 116 |
# parse_special_vars(MyVar ARG5 a b c) |
| 117 |
# |
| 118 |
# you will get:: |
| 119 |
# |
| 120 |
# MyVar_DEFAULT_ARGS="ARG5;a;b;c" |
| 121 |
# MyVar_ARG0="" |
| 122 |
# MyVar_ARG1="" |
| 123 |
# MyVar_ARG2="" |
| 124 |
# MyVar_OPT0="FALSE" |
| 125 |
# MyVar_OPT1="FALSE" |
| 126 |
# |
| 127 |
# Multiple occurrences of keyword arguments in ``<inputArgsList>`` is allowed |
| 128 |
# but only the last one listed will be recorded. For example, if one calls:: |
| 129 |
# |
| 130 |
# parse_special_vars(MyVar ARG1 a b ARG1 c) |
| 131 |
# |
| 132 |
# then this will set:: |
| 133 |
# |
| 134 |
# MyVar_ARG0="" |
| 135 |
# MyVar_ARG1="c" |
| 136 |
# MyVar_ARG2="" |
| 137 |
# MyVar_OPT0="FALSE" |
| 138 |
# MyVar_OPT1="FALSE" |
| 139 |
# |
| 140 |
# This is actually consistent with the way that most argument list parsers |
| 141 |
# behave with respect to multiple instances of the same argument so hopefully |
| 142 |
# this will not be a surprise to anyone. |
| 143 |
# |
| 144 |
# If one puts an option keyword in the middle of a keyword argument list, the |
| 145 |
# option keyword will get pulled out of the list. For example, if one calls:: |
| 146 |
# |
| 147 |
# parse_special_vars(MyVar ARG0 a OPT0 c) |
| 148 |
# |
| 149 |
# then this will set:: |
| 150 |
# |
| 151 |
# MyVar_ARG0="a;c" |
| 152 |
# MyVar_ARG1="" |
| 153 |
# MyVar_ARG2="" |
| 154 |
# MyVar_OPT0="TRUE" |
| 155 |
# MyVar_OPT1="FALSE" |
| 156 |
# |
| 157 |
# This is confusing behavior so users would be smart not to mix option |
| 158 |
# arguments inside of list arguments. |
| 159 |
# |
| 160 |
# If ``PARSE_ARGUMENTS_DUMP_OUTPUT_ENABLED`` is set to ``TRUE``, then a bunch |
| 161 |
# of detailed debug info will be printed. This should only be used in the |
| 162 |
# most desperate of debug situations because it will print a *lot* of output! |
| 163 |
# |
| 164 |
# **PERFORMANCE:** This function will scale as:: |
| 165 |
# |
| 166 |
# o( (len(<argNamesList>) * len(<optionNamesList>)) * len(<inputArgsList>) ) |
| 167 |
# |
| 168 |
# Therefore, this could scale very badly for large sets of argument and option |
| 169 |
# names and input argument list names. |
| 170 |
# |
| 171 |
macro(parse_arguments prefix arg_names option_names) |
| 172 |
|
| 173 |
parse_arguments_deprecated_warning() |
| 174 |
|
| 175 |
parse_arguments_dump_output("PARSE_ARGUMENTS: prefix='${prefix}'") |
| 176 |
parse_arguments_dump_output("PARSE_ARGUMENTS: arg_names='${arg_names}'") |
| 177 |
parse_arguments_dump_output("PARSE_ARGUMENTS: option_names='${option_names}'") |
| 178 |
parse_arguments_dump_output("PARSE_ARGUMENTS: ARGN='${ARGN}'") |
| 179 |
|
| 180 |
foreach(arg_name ${arg_names}) |
| 181 |
set(${prefix}_${arg_name}) |
| 182 |
endforeach() |
| 183 |
|
| 184 |
foreach(option ${option_names}) |
| 185 |
set(${prefix}_${option} FALSE) |
| 186 |
endforeach() |
| 187 |
|
| 188 |
set(DEFAULT_ARGS) |
| 189 |
set(current_arg_name DEFAULT_ARGS) |
| 190 |
set(current_arg_list) |
| 191 |
|
| 192 |
foreach(arg ${ARGN}) |
| 193 |
set(larg_names ${arg_names}) |
| 194 |
list(FIND larg_names "${arg}" is_arg_name) |
| 195 |
if (is_arg_name GREATER -1) |
| 196 |
set(${prefix}_${current_arg_name} "${current_arg_list}") |
| 197 |
parse_arguments_dump_output("PARSE_ARGUMENTS: ${prefix}_${current_arg_name} = '${${prefix}_${current_arg_name}}'" ) |
| 198 |
set(current_arg_name "${arg}") |
| 199 |
set(current_arg_list) |
| 200 |
else() |
| 201 |
set(loption_names "${option_names}") |
| 202 |
list(FIND loption_names "${arg}" is_option) |
| 203 |
if (is_option GREATER -1) |
| 204 |
set(${prefix}_${arg} TRUE) |
| 205 |
parse_arguments_dump_output( "PARSE_ARGUMENTS: ${prefix}_${arg} = '${${prefix}_${arg}}'" ) |
| 206 |
else() |
| 207 |
list(APPEND current_arg_list "${arg}") |
| 208 |
endif() |
| 209 |
endif() |
| 210 |
endforeach() |
| 211 |
|
| 212 |
set(${prefix}_${current_arg_name} "${current_arg_list}") |
| 213 |
parse_arguments_dump_output( "PARSE_ARGUMENTS: ${prefix}_${current_arg_name} = '${${prefix}_${current_arg_name}}'" ) |
| 214 |
|
| 215 |
endmacro() |
| 216 |
|
| 217 |
# NOTE: If the above function turns out to be a performance bottle neck, there |
| 218 |
# are a few things that could be done to improve performance. One thing you |
| 219 |
# could do is replace the o(len(arg_names)) and o(len(option_names)) lookup |
| 220 |
# with o(1) lookups by creating CMake variables of the name |
| 221 |
# ${OUTER_FUNC_NAME}_arg_<argNamei> and then just look of that variable exists |
| 222 |
# or not. That should use a hash function. That might actually slow things |
| 223 |
# down for short lists however so we would have to measure, measure, |
| 224 |
# measure. I would have to pass in the function/macro name to disambiguate |
| 225 |
# the variable names. It would really be better if CMake would provide a |
| 226 |
# sorted list find operation. That would make this much faster for large |
| 227 |
# numbers of argument and option names. |