1 /* CLI options framework, for GDB.
2
3 Copyright (C) 2017-2024 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 <optional>
24 #include "gdbsupport/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. */
option_defoption_def50 constexpr option_def (const char *name_,
51 var_types var_type_,
52 const literal_def *extra_literals_,
53 erased_get_var_address_ftype *erased_get_var_address_,
54 show_value_ftype *show_cmd_cb_,
55 const char *set_doc_,
56 const char *show_doc_,
57 const char *help_doc_)
58 : name (name_), type (var_type_), extra_literals (extra_literals_),
59 erased_get_var_address (erased_get_var_address_),
60 var_address {},
61 show_cmd_cb (show_cmd_cb_),
62 set_doc (set_doc_), show_doc (show_doc_), help_doc (help_doc_)
63 {}
64
65 public:
66 /* The option's name. */
67 const char *name;
68
69 /* The option's type. */
70 var_types type;
71
72 /* Extra literals, such as `unlimited', accepted in lieu of a number. */
73 const literal_def *extra_literals;
74
75 /* A function that gets the controlling variable's address, type
76 erased. */
77 erased_get_var_address_ftype *erased_get_var_address;
78
79 /* Get the controlling variable's address. Each type of variable
80 uses a different union member. We do this instead of having a
81 single hook that return a "void *", for better type safety. This
82 way, actual instances of concrete option_def types
83 (boolean_option_def, etc.) fail to compile if you pass in a
84 function with incorrect return type. CTX here is the aggregate
85 object that groups the option variables from which the callback
86 returns the address of some member. */
87 union
88 {
89 bool *(*boolean) (const option_def &, void *ctx);
90 unsigned int *(*uinteger) (const option_def &, void *ctx);
91 int *(*integer) (const option_def &, void *ctx);
92 const char **(*enumeration) (const option_def &, void *ctx);
93 std::string *(*string) (const option_def &, void *ctx);
94 }
95 var_address;
96
97 /* Pointer to null terminated list of enumerated values (like argv).
98 Only used by var_enum options. */
99 const char *const *enums = nullptr;
100
101 /* True if the option takes an argument. */
102 bool have_argument = true;
103
104 /* The "show" callback to use in the associated "show" command.
105 E.g., "show print elements". */
106 show_value_ftype *show_cmd_cb;
107
108 /* The set/show/help strings. These are shown in both the help of
109 commands that use the option group this option belongs to (e.g.,
110 "help print"), and in the associated commands (e.g., "set/show
111 print elements", "help set print elements"). */
112 const char *set_doc;
113 const char *show_doc;
114 const char *help_doc;
115
116 /* Convenience method that returns THIS as an option_def. Useful
117 when you're putting an option_def subclass in an option_def
118 array_view. */
defoption_def119 const option_def &def () const
120 {
121 return *this;
122 }
123 };
124
125 namespace detail
126 {
127
128 /* Get the address of the option's value, cast to the right type.
129 RetType is the restored type of the variable, and Context is the
130 restored type of the context pointer. */
131 template<typename RetType, typename Context>
132 static inline RetType *
get_var_address(const option_def & option,void * ctx)133 get_var_address (const option_def &option, void *ctx)
134 {
135 using unerased_ftype = RetType *(Context *);
136 unerased_ftype *fun = (unerased_ftype *) option.erased_get_var_address;
137 return fun ((Context *) ctx);
138 }
139
140 /* Convenience identity helper that just returns SELF. */
141
142 template<typename T>
143 static T *
return_self(T * self)144 return_self (T *self)
145 {
146 return self;
147 }
148
149 } /* namespace detail */
150
151 /* Follows the definitions of the option types that client code should
152 define. Note that objects of these types are placed in option_def
153 arrays, by design, so they must not have data fields of their
154 own. */
155
156 /* A var_boolean command line option. */
157
158 template<typename Context>
159 struct boolean_option_def : option_def
160 {
161 boolean_option_def (const char *long_option_,
162 bool *(*get_var_address_cb_) (Context *),
163 show_value_ftype *show_cmd_cb_,
164 const char *set_doc_,
165 const char *show_doc_ = nullptr,
166 const char *help_doc_ = nullptr)
167 : option_def (long_option_, var_boolean, nullptr,
168 (erased_get_var_address_ftype *) get_var_address_cb_,
169 show_cmd_cb_,
170 set_doc_, show_doc_, help_doc_)
171 {
172 var_address.boolean = detail::get_var_address<bool, Context>;
173 }
174 };
175
176 /* A flag command line option. This is a var_boolean option under the
177 hood, but unlike boolean options, flag options don't take an on/off
178 argument. */
179
180 template<typename Context = bool>
181 struct flag_option_def : boolean_option_def<Context>
182 {
183 flag_option_def (const char *long_option_,
184 bool *(*var_address_cb_) (Context *),
185 const char *set_doc_,
186 const char *help_doc_ = nullptr)
187 : boolean_option_def<Context> (long_option_,
188 var_address_cb_,
189 NULL,
190 set_doc_, NULL, help_doc_)
191 {
192 this->have_argument = false;
193 }
194
195 flag_option_def (const char *long_option_,
196 const char *set_doc_,
197 const char *help_doc_ = nullptr)
198 : boolean_option_def<Context> (long_option_,
199 gdb::option::detail::return_self,
200 NULL,
201 set_doc_, nullptr, help_doc_)
202 {
203 this->have_argument = false;
204 }
205 };
206
207 /* A var_uinteger command line option. */
208
209 template<typename Context>
210 struct uinteger_option_def : option_def
211 {
212 uinteger_option_def (const char *long_option_,
213 unsigned int *(*get_var_address_cb_) (Context *),
214 const literal_def *extra_literals_,
215 show_value_ftype *show_cmd_cb_,
216 const char *set_doc_,
217 const char *show_doc_ = nullptr,
218 const char *help_doc_ = nullptr)
219 : option_def (long_option_, var_uinteger, extra_literals_,
220 (erased_get_var_address_ftype *) get_var_address_cb_,
221 show_cmd_cb_,
222 set_doc_, show_doc_, help_doc_)
223 {
224 var_address.uinteger = detail::get_var_address<unsigned int, Context>;
225 }
226
227 uinteger_option_def (const char *long_option_,
228 unsigned 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)
uinteger_option_defuinteger_option_def233 : uinteger_option_def (long_option_, get_var_address_cb_, nullptr,
234 show_cmd_cb_, set_doc_, show_doc_, help_doc_)
235 { /* Nothing. */ }
236 };
237
238 /* A var_pinteger command line option. */
239
240 template<typename Context>
241 struct pinteger_option_def : option_def
242 {
243 pinteger_option_def (const char *long_option_,
244 int *(*get_var_address_cb_) (Context *),
245 const literal_def *extra_literals_,
246 show_value_ftype *show_cmd_cb_,
247 const char *set_doc_,
248 const char *show_doc_ = nullptr,
249 const char *help_doc_ = nullptr)
250 : option_def (long_option_, var_pinteger, extra_literals_,
251 (erased_get_var_address_ftype *) get_var_address_cb_,
252 show_cmd_cb_,
253 set_doc_, show_doc_, help_doc_)
254 {
255 var_address.integer = detail::get_var_address<int, Context>;
256 }
257
258 pinteger_option_def (const char *long_option_,
259 int *(*get_var_address_cb_) (Context *),
260 show_value_ftype *show_cmd_cb_,
261 const char *set_doc_,
262 const char *show_doc_ = nullptr,
263 const char *help_doc_ = nullptr)
pinteger_option_defpinteger_option_def264 : pinteger_option_def (long_option_, get_var_address_cb_, nullptr,
265 show_cmd_cb_, set_doc_, show_doc_, help_doc_)
266 { /* Nothing. */ }
267 };
268
269 /* An var_enum command line option. */
270
271 template<typename Context>
272 struct enum_option_def : option_def
273 {
274 enum_option_def (const char *long_option_,
275 const char *const *enumlist,
276 const char **(*get_var_address_cb_) (Context *),
277 show_value_ftype *show_cmd_cb_,
278 const char *set_doc_,
279 const char *show_doc_ = nullptr,
280 const char *help_doc_ = nullptr)
281 : option_def (long_option_, var_enum, nullptr,
282 (erased_get_var_address_ftype *) get_var_address_cb_,
283 show_cmd_cb_,
284 set_doc_, show_doc_, help_doc_)
285 {
286 var_address.enumeration = detail::get_var_address<const char *, Context>;
287 this->enums = enumlist;
288 }
289 };
290
291 /* A var_string command line option. */
292
293 template<typename Context>
294 struct string_option_def : option_def
295 {
296 string_option_def (const char *long_option_,
297 std::string *(*get_var_address_cb_) (Context *),
298 show_value_ftype *show_cmd_cb_,
299 const char *set_doc_,
300 const char *show_doc_ = nullptr,
301 const char *help_doc_ = nullptr)
302 : option_def (long_option_, var_string, nullptr,
303 (erased_get_var_address_ftype *) get_var_address_cb_,
304 show_cmd_cb_,
305 set_doc_, show_doc_, help_doc_)
306 {
307 var_address.string = detail::get_var_address<std::string, Context>;
308 }
309 };
310
311 /* A group of options that all share the same context pointer to pass
312 to the options' get-current-value callbacks. */
313 struct option_def_group
314 {
315 /* The list of options. */
316 gdb::array_view<const option_def> options;
317
318 /* The context pointer to pass to the options' get-current-value
319 callbacks. */
320 void *ctx;
321 };
322
323 /* Modes of operation for process_options. */
324 enum process_options_mode
325 {
326 /* In this mode, options are only processed if we find a "--"
327 delimiter. Throws an error if unknown options are found. */
328 PROCESS_OPTIONS_REQUIRE_DELIMITER,
329
330 /* In this mode, a "--" delimiter is not required. Throws an error
331 if unknown options are found, regardless of whether a delimiter
332 is present. */
333 PROCESS_OPTIONS_UNKNOWN_IS_ERROR,
334
335 /* In this mode, a "--" delimiter is not required. If an unknown
336 option is found, assume it is the command's argument/operand. */
337 PROCESS_OPTIONS_UNKNOWN_IS_OPERAND,
338 };
339
340 /* Process ARGS, using OPTIONS_GROUP as valid options. Returns true
341 if the string has been fully parsed and there are no operands to
342 handle by the caller. Return false if options were parsed, and
343 *ARGS now points at the first operand. */
344 extern bool process_options
345 (const char **args,
346 process_options_mode mode,
347 gdb::array_view<const option_def_group> options_group);
348
349 /* Complete ARGS on options listed by OPTIONS_GROUP. Returns true if
350 the string has been fully parsed and there are no operands to
351 handle by the caller. Return false if options were parsed, and
352 *ARGS now points at the first operand. */
353 extern bool complete_options
354 (completion_tracker &tracker,
355 const char **args,
356 process_options_mode mode,
357 gdb::array_view<const option_def_group> options_group);
358
359 /* Complete on all options listed by OPTIONS_GROUP. */
360 extern void
361 complete_on_all_options (completion_tracker &tracker,
362 gdb::array_view<const option_def_group> options_group);
363
364 /* Return a string with the result of replacing %OPTIONS% in HELP_TMLP
365 with an auto-generated "help" string fragment for all the options
366 in OPTIONS_GROUP. */
367 extern std::string build_help
368 (const char *help_tmpl,
369 gdb::array_view<const option_def_group> options_group);
370
371 /* Install set/show commands for options defined in OPTIONS. DATA is
372 a pointer to the structure that holds the data associated with the
373 OPTIONS array. */
374 extern void add_setshow_cmds_for_options (command_class cmd_class, void *data,
375 gdb::array_view<const option_def> options,
376 struct cmd_list_element **set_list,
377 struct cmd_list_element **show_list);
378
379 } /* namespace option */
380 } /* namespace gdb */
381
382 #endif /* CLI_OPTION_H */
383