Debian Codegraph @

cmake/tribits/core/utils/ParseVariableArguments.cmake

raw
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.