Commit | Line | Data |
---|---|---|
9d0faba9 PA |
1 | /* CLI options framework, for GDB. |
2 | ||
3 | Copyright (C) 2017-2019 Free Software Foundation, Inc. | |
4 | ||
5 | This file is part of GDB. | |
6 | ||
7 | This program is free software; you can redistribute it and/or modify | |
8 | it under the terms of the GNU General Public License as published by | |
9 | the Free Software Foundation; either version 3 of the License, or | |
10 | (at your option) any later version. | |
11 | ||
12 | This program is distributed in the hope that it will be useful, | |
13 | but WITHOUT ANY WARRANTY; without even the implied warranty of | |
14 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
15 | GNU General Public License for more details. | |
16 | ||
17 | You should have received a copy of the GNU General Public License | |
18 | along with this program. If not, see <http://www.gnu.org/licenses/>. */ | |
19 | ||
20 | #ifndef CLI_OPTION_H | |
21 | #define CLI_OPTION_H 1 | |
22 | ||
23 | #include "common/gdb_optional.h" | |
24 | #include "common/array-view.h" | |
25 | #include "completer.h" | |
26 | #include <string> | |
27 | #include "command.h" | |
28 | ||
29 | namespace gdb { | |
30 | namespace option { | |
31 | ||
32 | /* A type-erased option definition. The actual type of the option is | |
33 | stored in the TYPE field. Client code cannot define objects of | |
34 | this type directly (the ctor is protected). Instead, one of the | |
35 | wrapper types below that extends this (boolean_option_def, | |
36 | flag_option_def, uinteger_option_def, etc.) should be defined. */ | |
37 | struct option_def | |
38 | { | |
39 | /* The ctor is protected because you're supposed to construct using | |
40 | one of bool_option_def, etc. below. */ | |
41 | protected: | |
42 | typedef void *(erased_get_var_address_ftype) (); | |
43 | ||
44 | /* Construct an option. NAME_ is the option's name. VAR_TYPE_ | |
45 | defines the option's type. ERASED_GET_VAR_ADDRESS_ is a pointer | |
46 | to a function that returns the option's control variable. | |
47 | SHOW_CMD_CB_ is a pointer to callback for the "show" command that | |
48 | is installed for this option. SET_DOC_, SHOW_DOC_, HELP_DOC_ are | |
49 | used to create the option's "set/show" commands. */ | |
50 | constexpr option_def (const char *name_, | |
51 | var_types var_type_, | |
52 | erased_get_var_address_ftype *erased_get_var_address_, | |
53 | show_value_ftype *show_cmd_cb_, | |
54 | const char *set_doc_, | |
55 | const char *show_doc_, | |
56 | const char *help_doc_) | |
57 | : name (name_), type (var_type_), | |
58 | erased_get_var_address (erased_get_var_address_), | |
59 | var_address {}, | |
60 | show_cmd_cb (show_cmd_cb_), | |
61 | set_doc (set_doc_), show_doc (show_doc_), help_doc (help_doc_) | |
62 | {} | |
63 | ||
64 | public: | |
65 | /* The option's name. */ | |
66 | const char *name; | |
67 | ||
68 | /* The option's type. */ | |
69 | var_types type; | |
70 | ||
71 | /* A function that gets the controlling variable's address, type | |
72 | erased. */ | |
73 | erased_get_var_address_ftype *erased_get_var_address; | |
74 | ||
75 | /* Get the controlling variable's address. Each type of variable | |
76 | uses a different union member. We do this instead of having a | |
77 | single hook that return a "void *", for better type safety. This | |
78 | way, actual instances of concrete option_def types | |
79 | (boolean_option_def, etc.) fail to compile if you pass in a | |
80 | function with incorrect return type. CTX here is the aggregate | |
81 | object that groups the option variables from which the callback | |
82 | returns the address of some member. */ | |
83 | union | |
84 | { | |
85 | int *(*boolean) (const option_def &, void *ctx); | |
86 | unsigned int *(*uinteger) (const option_def &, void *ctx); | |
87 | int *(*integer) (const option_def &, void *ctx); | |
88 | const char **(*enumeration) (const option_def &, void *ctx); | |
89 | } | |
90 | var_address; | |
91 | ||
92 | /* Pointer to null terminated list of enumerated values (like argv). | |
93 | Only used by var_enum options. */ | |
94 | const char *const *enums = nullptr; | |
95 | ||
96 | /* True if the option takes an argument. */ | |
97 | bool have_argument = true; | |
98 | ||
99 | /* The "show" callback to use in the associated "show" command. | |
100 | E.g., "show print elements". */ | |
101 | show_value_ftype *show_cmd_cb; | |
102 | ||
103 | /* The set/show/help strings. These are shown in both the help of | |
104 | commands that use the option group this option belongs to (e.g., | |
105 | "help print"), and in the associated commands (e.g., "set/show | |
106 | print elements", "help set print elements"). */ | |
107 | const char *set_doc; | |
108 | const char *show_doc; | |
109 | const char *help_doc; | |
110 | ||
111 | /* Convenience method that returns THIS as an option_def. Useful | |
112 | when you're putting an option_def subclass in an option_def | |
113 | array_view. */ | |
114 | const option_def &def () const | |
115 | { | |
116 | return *this; | |
117 | } | |
118 | }; | |
119 | ||
120 | namespace detail | |
121 | { | |
122 | ||
123 | /* Get the address of the option's value, cast to the right type. | |
124 | RetType is the restored type of the variable, and Context is the | |
125 | restored type of the context pointer. */ | |
126 | template<typename RetType, typename Context> | |
127 | static inline RetType * | |
128 | get_var_address (const option_def &option, void *ctx) | |
129 | { | |
130 | using unerased_ftype = RetType *(Context *); | |
131 | unerased_ftype *fun = (unerased_ftype *) option.erased_get_var_address; | |
132 | return fun ((Context *) ctx); | |
133 | } | |
134 | ||
135 | /* Convenience identity helper that just returns SELF. */ | |
136 | ||
137 | template<typename T> | |
138 | static T * | |
139 | return_self (T *self) | |
140 | { | |
141 | return self; | |
142 | } | |
143 | ||
144 | } /* namespace detail */ | |
145 | ||
146 | /* Follows the definitions of the option types that client code should | |
147 | define. Note that objects of these types are placed in option_def | |
148 | arrays, by design, so they must not have data fields of their | |
149 | own. */ | |
150 | ||
151 | /* A var_boolean command line option. */ | |
152 | ||
153 | template<typename Context> | |
154 | struct boolean_option_def : option_def | |
155 | { | |
156 | boolean_option_def (const char *long_option_, | |
157 | int *(*get_var_address_cb_) (Context *), | |
158 | show_value_ftype *show_cmd_cb_, | |
159 | const char *set_doc_, | |
160 | const char *show_doc_ = nullptr, | |
161 | const char *help_doc_ = nullptr) | |
162 | : option_def (long_option_, var_boolean, | |
163 | (erased_get_var_address_ftype *) get_var_address_cb_, | |
164 | show_cmd_cb_, | |
165 | set_doc_, show_doc_, help_doc_) | |
166 | { | |
167 | var_address.boolean = detail::get_var_address<int, Context>; | |
168 | } | |
169 | }; | |
170 | ||
171 | /* A flag command line option. This is a var_boolean option under the | |
172 | hood, but unlike boolean options, flag options don't take an on/off | |
173 | argument. */ | |
174 | ||
175 | template<typename Context = int> | |
176 | struct flag_option_def : boolean_option_def<Context> | |
177 | { | |
178 | flag_option_def (const char *long_option_, | |
179 | int *(*var_address_cb_) (Context *), | |
180 | const char *set_doc_, | |
181 | const char *help_doc_ = nullptr) | |
182 | : boolean_option_def<Context> (long_option_, | |
183 | var_address_cb_, | |
184 | NULL, | |
185 | set_doc_, NULL, help_doc_) | |
186 | { | |
187 | this->have_argument = false; | |
188 | } | |
189 | ||
190 | flag_option_def (const char *long_option_, | |
191 | const char *set_doc_, | |
192 | const char *help_doc_ = nullptr) | |
193 | : boolean_option_def<Context> (long_option_, | |
194 | gdb::option::detail::return_self, | |
195 | NULL, | |
196 | set_doc_, nullptr, help_doc_) | |
197 | { | |
198 | this->have_argument = false; | |
199 | } | |
200 | }; | |
201 | ||
202 | /* A var_uinteger command line option. */ | |
203 | ||
204 | template<typename Context> | |
205 | struct uinteger_option_def : option_def | |
206 | { | |
207 | uinteger_option_def (const char *long_option_, | |
208 | unsigned int *(*get_var_address_cb_) (Context *), | |
209 | show_value_ftype *show_cmd_cb_, | |
210 | const char *set_doc_, | |
211 | const char *show_doc_ = nullptr, | |
212 | const char *help_doc_ = nullptr) | |
213 | : option_def (long_option_, var_uinteger, | |
214 | (erased_get_var_address_ftype *) get_var_address_cb_, | |
215 | show_cmd_cb_, | |
216 | set_doc_, show_doc_, help_doc_) | |
217 | { | |
218 | var_address.uinteger = detail::get_var_address<unsigned int, Context>; | |
219 | } | |
220 | }; | |
221 | ||
222 | /* A var_zuinteger_unlimited command line option. */ | |
223 | ||
224 | template<typename Context> | |
225 | struct zuinteger_unlimited_option_def : option_def | |
226 | { | |
227 | zuinteger_unlimited_option_def (const char *long_option_, | |
228 | int *(*get_var_address_cb_) (Context *), | |
229 | show_value_ftype *show_cmd_cb_, | |
230 | const char *set_doc_, | |
231 | const char *show_doc_ = nullptr, | |
232 | const char *help_doc_ = nullptr) | |
233 | : option_def (long_option_, var_zuinteger_unlimited, | |
234 | (erased_get_var_address_ftype *) get_var_address_cb_, | |
235 | show_cmd_cb_, | |
236 | set_doc_, show_doc_, help_doc_) | |
237 | { | |
238 | var_address.integer = detail::get_var_address<int, Context>; | |
239 | } | |
240 | }; | |
241 | ||
242 | /* An var_enum command line option. */ | |
243 | ||
244 | template<typename Context> | |
245 | struct enum_option_def : option_def | |
246 | { | |
247 | enum_option_def (const char *long_option_, | |
248 | const char *const *enumlist, | |
249 | const char **(*get_var_address_cb_) (Context *), | |
250 | show_value_ftype *show_cmd_cb_, | |
251 | const char *set_doc_, | |
252 | const char *show_doc_ = nullptr, | |
253 | const char *help_doc_ = nullptr) | |
254 | : option_def (long_option_, var_enum, | |
255 | (erased_get_var_address_ftype *) get_var_address_cb_, | |
256 | show_cmd_cb_, | |
257 | set_doc_, show_doc_, help_doc_) | |
258 | { | |
259 | var_address.enumeration = detail::get_var_address<const char *, Context>; | |
260 | this->enums = enumlist; | |
261 | } | |
262 | }; | |
263 | ||
264 | /* A group of options that all share the same context pointer to pass | |
265 | to the options' get-current-value callbacks. */ | |
266 | struct option_def_group | |
267 | { | |
268 | /* The list of options. */ | |
269 | gdb::array_view<const option_def> options; | |
270 | ||
271 | /* The context pointer to pass to the options' get-current-value | |
272 | callbacks. */ | |
273 | void *ctx; | |
274 | }; | |
275 | ||
276 | /* Modes of operation for process_options. */ | |
277 | enum process_options_mode | |
278 | { | |
279 | /* In this mode, options are only processed if we find a "--" | |
280 | delimiter. Throws an error if unknown options are found. */ | |
281 | PROCESS_OPTIONS_REQUIRE_DELIMITER, | |
282 | ||
283 | /* In this mode, a "--" delimiter is not required. Throws an error | |
284 | if unknown options are found, regardless of whether a delimiter | |
285 | is present. */ | |
286 | PROCESS_OPTIONS_UNKNOWN_IS_ERROR, | |
287 | ||
288 | /* In this mode, a "--" delimiter is not required. If an unknown | |
289 | option is found, assume it is the command's argument/operand. */ | |
290 | PROCESS_OPTIONS_UNKNOWN_IS_OPERAND, | |
291 | }; | |
292 | ||
293 | /* Process ARGS, using OPTIONS_GROUP as valid options. Returns true | |
294 | if the string has been fully parsed and there are no operands to | |
295 | handle by the caller. Return false if options were parsed, and | |
296 | *ARGS now points at the first operand. */ | |
297 | extern bool process_options | |
298 | (const char **args, | |
299 | process_options_mode mode, | |
300 | gdb::array_view<const option_def_group> options_group); | |
301 | ||
302 | /* Complete ARGS on options listed by OPTIONS_GROUP. Returns true if | |
303 | the string has been fully parsed and there are no operands to | |
304 | handle by the caller. Return false if options were parsed, and | |
305 | *ARGS now points at the first operand. */ | |
306 | extern bool complete_options | |
307 | (completion_tracker &tracker, | |
308 | const char **args, | |
309 | process_options_mode mode, | |
310 | gdb::array_view<const option_def_group> options_group); | |
311 | ||
312 | /* Complete on all options listed by OPTIONS_GROUP. */ | |
313 | extern void | |
314 | complete_on_all_options (completion_tracker &tracker, | |
315 | gdb::array_view<const option_def_group> options_group); | |
316 | ||
317 | /* Return a string with the result of replacing %OPTIONS% in HELP_TMLP | |
318 | with an auto-generated "help" string fragment for all the options | |
319 | in OPTIONS_GROUP. */ | |
320 | extern std::string build_help | |
321 | (const char *help_tmpl, | |
322 | gdb::array_view<const option_def_group> options_group); | |
323 | ||
324 | /* Install set/show commands for options defined in OPTIONS. DATA is | |
325 | a pointer to the structure that holds the data associated with the | |
326 | OPTIONS array. */ | |
327 | extern void add_setshow_cmds_for_options (command_class cmd_class, void *data, | |
328 | gdb::array_view<const option_def> options, | |
329 | struct cmd_list_element **set_list, | |
330 | struct cmd_list_element **show_list); | |
331 | ||
332 | } /* namespace option */ | |
333 | } /* namespace gdb */ | |
334 | ||
335 | #endif /* CLI_OPTION_H */ |