GDB (xrefs)
Loading...
Searching...
No Matches
cli-option.h
Go to the documentation of this file.
1/* CLI options framework, for GDB.
2
3 Copyright (C) 2017-2023 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 "gdbsupport/gdb_optional.h"
24#include "gdbsupport/array-view.h"
25#include "completer.h"
26#include <string>
27#include "command.h"
28
29namespace gdb {
30namespace 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. */
38{
39 /* The ctor is protected because you're supposed to construct using
40 one of bool_option_def, etc. below. */
41protected:
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
64public:
65 /* The option's name. */
66 const char *name;
67
68 /* The option's type. */
70
71 /* A function that gets the controlling variable's address, type
72 erased. */
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 bool *(*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 std::string *(*string) (const option_def &, void *ctx);
90 }
92
93 /* Pointer to null terminated list of enumerated values (like argv).
94 Only used by var_enum options. */
95 const char *const *enums = nullptr;
96
97 /* True if the option takes an argument. */
98 bool have_argument = true;
99
100 /* The "show" callback to use in the associated "show" command.
101 E.g., "show print elements". */
103
104 /* The set/show/help strings. These are shown in both the help of
105 commands that use the option group this option belongs to (e.g.,
106 "help print"), and in the associated commands (e.g., "set/show
107 print elements", "help set print elements"). */
108 const char *set_doc;
109 const char *show_doc;
110 const char *help_doc;
111
112 /* Convenience method that returns THIS as an option_def. Useful
113 when you're putting an option_def subclass in an option_def
114 array_view. */
115 const option_def &def () const
116 {
117 return *this;
118 }
119};
120
121namespace detail
122{
123
124/* Get the address of the option's value, cast to the right type.
125 RetType is the restored type of the variable, and Context is the
126 restored type of the context pointer. */
127template<typename RetType, typename Context>
128static inline RetType *
129get_var_address (const option_def &option, void *ctx)
130{
131 using unerased_ftype = RetType *(Context *);
132 unerased_ftype *fun = (unerased_ftype *) option.erased_get_var_address;
133 return fun ((Context *) ctx);
134}
135
136/* Convenience identity helper that just returns SELF. */
137
138template<typename T>
139static T *
141{
142 return self;
143}
144
145} /* namespace detail */
146
147/* Follows the definitions of the option types that client code should
148 define. Note that objects of these types are placed in option_def
149 arrays, by design, so they must not have data fields of their
150 own. */
151
152/* A var_boolean command line option. */
153
154template<typename Context>
156{
157 boolean_option_def (const char *long_option_,
158 bool *(*get_var_address_cb_) (Context *),
159 show_value_ftype *show_cmd_cb_,
160 const char *set_doc_,
161 const char *show_doc_ = nullptr,
162 const char *help_doc_ = nullptr)
163 : option_def (long_option_, var_boolean,
164 (erased_get_var_address_ftype *) get_var_address_cb_,
165 show_cmd_cb_,
166 set_doc_, show_doc_, help_doc_)
167 {
168 var_address.boolean = detail::get_var_address<bool, Context>;
169 }
170};
171
172/* A flag command line option. This is a var_boolean option under the
173 hood, but unlike boolean options, flag options don't take an on/off
174 argument. */
175
176template<typename Context = bool>
178{
179 flag_option_def (const char *long_option_,
180 bool *(*var_address_cb_) (Context *),
181 const char *set_doc_,
182 const char *help_doc_ = nullptr)
183 : boolean_option_def<Context> (long_option_,
184 var_address_cb_,
185 NULL,
186 set_doc_, NULL, help_doc_)
187 {
188 this->have_argument = false;
189 }
190
191 flag_option_def (const char *long_option_,
192 const char *set_doc_,
193 const char *help_doc_ = nullptr)
194 : boolean_option_def<Context> (long_option_,
195 gdb::option::detail::return_self,
196 NULL,
197 set_doc_, nullptr, help_doc_)
198 {
199 this->have_argument = false;
200 }
201};
202
203/* A var_uinteger command line option. */
204
205template<typename Context>
207{
208 uinteger_option_def (const char *long_option_,
209 unsigned int *(*get_var_address_cb_) (Context *),
210 show_value_ftype *show_cmd_cb_,
211 const char *set_doc_,
212 const char *show_doc_ = nullptr,
213 const char *help_doc_ = nullptr)
214 : option_def (long_option_, var_uinteger,
215 (erased_get_var_address_ftype *) get_var_address_cb_,
216 show_cmd_cb_,
217 set_doc_, show_doc_, help_doc_)
218 {
219 var_address.uinteger = detail::get_var_address<unsigned int, Context>;
220 }
221};
222
223/* A var_zuinteger_unlimited command line option. */
224
225template<typename Context>
227{
228 zuinteger_unlimited_option_def (const char *long_option_,
229 int *(*get_var_address_cb_) (Context *),
230 show_value_ftype *show_cmd_cb_,
231 const char *set_doc_,
232 const char *show_doc_ = nullptr,
233 const char *help_doc_ = nullptr)
234 : option_def (long_option_, var_zuinteger_unlimited,
235 (erased_get_var_address_ftype *) get_var_address_cb_,
236 show_cmd_cb_,
237 set_doc_, show_doc_, help_doc_)
238 {
239 var_address.integer = detail::get_var_address<int, Context>;
240 }
241};
242
243/* An var_enum command line option. */
244
245template<typename Context>
247{
248 enum_option_def (const char *long_option_,
249 const char *const *enumlist,
250 const char **(*get_var_address_cb_) (Context *),
251 show_value_ftype *show_cmd_cb_,
252 const char *set_doc_,
253 const char *show_doc_ = nullptr,
254 const char *help_doc_ = nullptr)
255 : option_def (long_option_, var_enum,
256 (erased_get_var_address_ftype *) get_var_address_cb_,
257 show_cmd_cb_,
258 set_doc_, show_doc_, help_doc_)
259 {
260 var_address.enumeration = detail::get_var_address<const char *, Context>;
261 this->enums = enumlist;
262 }
263};
264
265/* A var_string command line option. */
266
267template<typename Context>
269{
270 string_option_def (const char *long_option_,
271 std::string *(*get_var_address_cb_) (Context *),
272 show_value_ftype *show_cmd_cb_,
273 const char *set_doc_,
274 const char *show_doc_ = nullptr,
275 const char *help_doc_ = nullptr)
276 : option_def (long_option_, var_string,
277 (erased_get_var_address_ftype *) get_var_address_cb_,
278 show_cmd_cb_,
279 set_doc_, show_doc_, help_doc_)
280 {
281 var_address.enumeration = detail::get_var_address<const char *, Context>;
282 }
283};
284
285/* A group of options that all share the same context pointer to pass
286 to the options' get-current-value callbacks. */
288{
289 /* The list of options. */
290 gdb::array_view<const option_def> options;
291
292 /* The context pointer to pass to the options' get-current-value
293 callbacks. */
294 void *ctx;
295};
296
297/* Modes of operation for process_options. */
299{
300 /* In this mode, options are only processed if we find a "--"
301 delimiter. Throws an error if unknown options are found. */
303
304 /* In this mode, a "--" delimiter is not required. Throws an error
305 if unknown options are found, regardless of whether a delimiter
306 is present. */
308
309 /* In this mode, a "--" delimiter is not required. If an unknown
310 option is found, assume it is the command's argument/operand. */
312};
313
314/* Process ARGS, using OPTIONS_GROUP as valid options. Returns true
315 if the string has been fully parsed and there are no operands to
316 handle by the caller. Return false if options were parsed, and
317 *ARGS now points at the first operand. */
318extern bool process_options
319 (const char **args,
321 gdb::array_view<const option_def_group> options_group);
322
323/* Complete ARGS on options listed by OPTIONS_GROUP. Returns true if
324 the string has been fully parsed and there are no operands to
325 handle by the caller. Return false if options were parsed, and
326 *ARGS now points at the first operand. */
327extern bool complete_options
328 (completion_tracker &tracker,
329 const char **args,
331 gdb::array_view<const option_def_group> options_group);
332
333/* Complete on all options listed by OPTIONS_GROUP. */
334extern void
336 gdb::array_view<const option_def_group> options_group);
337
338/* Return a string with the result of replacing %OPTIONS% in HELP_TMLP
339 with an auto-generated "help" string fragment for all the options
340 in OPTIONS_GROUP. */
341extern std::string build_help
342 (const char *help_tmpl,
343 gdb::array_view<const option_def_group> options_group);
344
345/* Install set/show commands for options defined in OPTIONS. DATA is
346 a pointer to the structure that holds the data associated with the
347 OPTIONS array. */
348extern void add_setshow_cmds_for_options (command_class cmd_class, void *data,
349 gdb::array_view<const option_def> options,
350 struct cmd_list_element **set_list,
351 struct cmd_list_element **show_list);
352
353} /* namespace option */
354} /* namespace gdb */
355
356#endif /* CLI_OPTION_H */
void() show_value_ftype(struct ui_file *file, int from_tty, struct cmd_list_element *cmd, const char *value)
Definition command.h:646
var_types
Definition command.h:75
@ var_string
Definition command.h:100
@ var_boolean
Definition command.h:78
@ var_zuinteger_unlimited
Definition command.h:118
@ var_uinteger
Definition command.h:89
@ var_enum
Definition command.h:122
command_class
Definition command.h:43
static T * return_self(T *self)
Definition cli-option.h:140
static RetType * get_var_address(const option_def &option, void *ctx)
Definition cli-option.h:129
bool process_options(const char **args, process_options_mode mode, gdb::array_view< const option_def_group > options_group)
Definition cli-option.c:616
@ PROCESS_OPTIONS_REQUIRE_DELIMITER
Definition cli-option.h:302
@ PROCESS_OPTIONS_UNKNOWN_IS_ERROR
Definition cli-option.h:307
@ PROCESS_OPTIONS_UNKNOWN_IS_OPERAND
Definition cli-option.h:311
std::string build_help(const char *help_tmpl, gdb::array_view< const option_def_group > options_group)
Definition cli-option.c:743
void complete_on_all_options(completion_tracker &tracker, gdb::array_view< const option_def_group > options_group)
Definition cli-option.c:170
bool complete_options(completion_tracker &tracker, const char **args, process_options_mode mode, gdb::array_view< const option_def_group > options_group)
Definition cli-option.c:457
void add_setshow_cmds_for_options(command_class cmd_class, void *data, gdb::array_view< const option_def > options, struct cmd_list_element **set_list, struct cmd_list_element **show_list)
Definition cli-option.c:771
Definition 1.cc:26
boolean_option_def(const char *long_option_, bool *(*get_var_address_cb_)(Context *), show_value_ftype *show_cmd_cb_, const char *set_doc_, const char *show_doc_=nullptr, const char *help_doc_=nullptr)
Definition cli-option.h:157
enum_option_def(const char *long_option_, const char *const *enumlist, const char **(*get_var_address_cb_)(Context *), show_value_ftype *show_cmd_cb_, const char *set_doc_, const char *show_doc_=nullptr, const char *help_doc_=nullptr)
Definition cli-option.h:248
flag_option_def(const char *long_option_, const char *set_doc_, const char *help_doc_=nullptr)
Definition cli-option.h:191
flag_option_def(const char *long_option_, bool *(*var_address_cb_)(Context *), const char *set_doc_, const char *help_doc_=nullptr)
Definition cli-option.h:179
gdb::array_view< const option_def > options
Definition cli-option.h:290
void *() erased_get_var_address_ftype()
Definition cli-option.h:42
union gdb::option::option_def::@26 var_address
show_value_ftype * show_cmd_cb
Definition cli-option.h:102
erased_get_var_address_ftype * erased_get_var_address
Definition cli-option.h:73
const option_def & def() const
Definition cli-option.h:115
const char *const * enums
Definition cli-option.h:95
constexpr option_def(const char *name_, var_types var_type_, erased_get_var_address_ftype *erased_get_var_address_, show_value_ftype *show_cmd_cb_, const char *set_doc_, const char *show_doc_, const char *help_doc_)
Definition cli-option.h:50
string_option_def(const char *long_option_, std::string *(*get_var_address_cb_)(Context *), show_value_ftype *show_cmd_cb_, const char *set_doc_, const char *show_doc_=nullptr, const char *help_doc_=nullptr)
Definition cli-option.h:270
uinteger_option_def(const char *long_option_, unsigned int *(*get_var_address_cb_)(Context *), show_value_ftype *show_cmd_cb_, const char *set_doc_, const char *show_doc_=nullptr, const char *help_doc_=nullptr)
Definition cli-option.h:208
zuinteger_unlimited_option_def(const char *long_option_, int *(*get_var_address_cb_)(Context *), show_value_ftype *show_cmd_cb_, const char *set_doc_, const char *show_doc_=nullptr, const char *help_doc_=nullptr)
Definition cli-option.h:228