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 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
65public:
66 /* The option's name. */
67 const char *name;
68
69 /* The option's type. */
71
72 /* Extra literals, such as `unlimited', accepted in lieu of a number. */
74
75 /* A function that gets the controlling variable's address, type
76 erased. */
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 }
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". */
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. */
119 const option_def &def () const
120 {
121 return *this;
122 }
123};
124
125namespace 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. */
131template<typename RetType, typename Context>
132static inline RetType *
133get_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
142template<typename T>
143static T *
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
158template<typename Context>
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
180template<typename Context = bool>
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
209template<typename Context>
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)
233 : 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
240template<typename Context>
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)
264 : 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
271template<typename Context>
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
293template<typename Context>
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.enumeration = detail::get_var_address<const char *, 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. */
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. */
325{
326 /* In this mode, options are only processed if we find a "--"
327 delimiter. Throws an error if unknown options are found. */
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. */
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. */
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. */
344extern bool process_options
345 (const char **args,
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. */
353extern bool complete_options
354 (completion_tracker &tracker,
355 const char **args,
357 gdb::array_view<const option_def_group> options_group);
358
359/* Complete on all options listed by OPTIONS_GROUP. */
360extern void
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. */
367extern 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. */
374extern 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 */
void show_value_ftype(struct ui_file *file, int from_tty, struct cmd_list_element *cmd, const char *value)
Definition command.h:660
var_types
Definition command.h:75
@ var_pinteger
Definition command.h:97
@ var_string
Definition command.h:102
@ var_boolean
Definition command.h:78
@ var_uinteger
Definition command.h:89
@ var_enum
Definition command.h:114
command_class
Definition command.h:43
static T * return_self(T *self)
Definition cli-option.h:144
static RetType * get_var_address(const option_def &option, void *ctx)
Definition cli-option.h:133
bool process_options(const char **args, process_options_mode mode, gdb::array_view< const option_def_group > options_group)
Definition cli-option.c:627
@ PROCESS_OPTIONS_REQUIRE_DELIMITER
Definition cli-option.h:328
@ PROCESS_OPTIONS_UNKNOWN_IS_ERROR
Definition cli-option.h:333
@ PROCESS_OPTIONS_UNKNOWN_IS_OPERAND
Definition cli-option.h:337
std::string build_help(const char *help_tmpl, gdb::array_view< const option_def_group > options_group)
Definition cli-option.c:766
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:467
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:794
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:161
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:274
flag_option_def(const char *long_option_, const char *set_doc_, const char *help_doc_=nullptr)
Definition cli-option.h:195
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:183
gdb::array_view< const option_def > options
Definition cli-option.h:316
unsigned int *(* uinteger)(const option_def &, void *ctx)
Definition cli-option.h:90
show_value_ftype * show_cmd_cb
Definition cli-option.h:106
erased_get_var_address_ftype * erased_get_var_address
Definition cli-option.h:77
const char **(* enumeration)(const option_def &, void *ctx)
Definition cli-option.h:92
int *(* integer)(const option_def &, void *ctx)
Definition cli-option.h:91
const option_def & def() const
Definition cli-option.h:119
const char *const * enums
Definition cli-option.h:99
constexpr option_def(const char *name_, var_types var_type_, const literal_def *extra_literals_, 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
void * erased_get_var_address_ftype()
Definition cli-option.h:42
bool *(* boolean)(const option_def &, void *ctx)
Definition cli-option.h:89
const literal_def * extra_literals
Definition cli-option.h:73
union gdb::option::option_def::@28 var_address
pinteger_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:258
pinteger_option_def(const char *long_option_, int *(*get_var_address_cb_)(Context *), const literal_def *extra_literals_, show_value_ftype *show_cmd_cb_, const char *set_doc_, const char *show_doc_=nullptr, const char *help_doc_=nullptr)
Definition cli-option.h:243
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:296
uinteger_option_def(const char *long_option_, unsigned int *(*get_var_address_cb_)(Context *), const literal_def *extra_literals_, show_value_ftype *show_cmd_cb_, const char *set_doc_, const char *show_doc_=nullptr, const char *help_doc_=nullptr)
Definition cli-option.h:212
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:227
#define nullptr
Definition x86-cpuid.h:28