GDB (xrefs)
Loading...
Searching...
No Matches
maint-test-options.c
Go to the documentation of this file.
1/* Maintenance commands for testing the options framework.
2
3 Copyright (C) 2019-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#include "defs.h"
21#include "gdbcmd.h"
22#include "cli/cli-option.h"
23
24/* This file defines three "maintenance test-options" subcommands to
25 exercise TAB-completion and option processing:
26
27 (gdb) maint test-options require-delimiter
28 (gdb) maint test-options unknown-is-error
29 (gdb) maint test-options unknown-is-operand
30
31 And a fourth one to help with TAB-completion testing.
32
33 (gdb) maint show test-options-completion-result
34
35 Each of the test-options subcommands exercise
36 gdb::option::process_options with a different enum
37 process_options_mode value. Examples for commands they model:
38
39 - "print" and "compile print", are like "require-delimiter",
40 because they accept random expressions as argument.
41
42 - "backtrace" and "frame/thread apply" are like
43 "unknown-is-operand", because "-" is a valid command.
44
45 - "compile file" and "compile code" are like "unknown-is-error".
46
47 These commands allow exercising all aspects of option processing
48 without having to pick some existing command. That should be more
49 stable going forward than relying on an existing user command,
50 since if we picked say "print", that command or its options could
51 change in future, and then we'd be left with having to pick some
52 other command or option to exercise some non-command-specific
53 option processing detail. Also, actual user commands have side
54 effects that we're not interested in when we're focusing on unit
55 testing the options machinery. BTW, a maintenance command is used
56 as a sort of unit test driver instead of actual "maint selftest"
57 unit tests, since we need to go all the way via gdb including
58 readline, for proper testing of TAB completion.
59
60 These maintenance commands support options of all the different
61 available kinds of commands (boolean, enum, flag, string, uinteger):
62
63 (gdb) maint test-options require-delimiter -[TAB]
64 -bool -pinteger-unlimited -xx1
65 -enum -string -xx2
66 -flag -uinteger-unlimited
67
68 (gdb) maint test-options require-delimiter -bool o[TAB]
69 off on
70 (gdb) maint test-options require-delimiter -enum [TAB]
71 xxx yyy zzz
72 (gdb) maint test-options require-delimiter -uinteger-unlimited [TAB]
73 NUMBER unlimited
74
75 '-xx1' and '-xx2' are flag options too. They exist in order to
76 test ambiguous option names, like '-xx'.
77
78 Invoking the commands makes them print out the options parsed:
79
80 (gdb) maint test-options unknown-is-error -flag -enum yyy cmdarg
81 -flag 1 -xx1 0 -xx2 0 -bool 0 -enum yyy -uint-unl 0 -pint-unl 0 -string '' -- cmdarg
82
83 (gdb) maint test-options require-delimiter -flag -enum yyy cmdarg
84 -flag 0 -xx1 0 -xx2 0 -bool 0 -enum xxx -uint-unl 0 -pint-unl 0 -string '' -- -flag -enum yyy cmdarg
85 (gdb) maint test-options require-delimiter -flag -enum yyy cmdarg --
86 Unrecognized option at: cmdarg --
87 (gdb) maint test-options require-delimiter -flag -enum yyy -- cmdarg
88 -flag 1 -xx1 0 -xx2 0 -bool 0 -enum yyy -uint-unl 0 -pint-unl 0 -string '' -- cmdarg
89
90 The "maint show test-options-completion-result" command exists in
91 order to do something similar for completion:
92
93 (gdb) maint test-options unknown-is-error -flag -b 0 -enum yyy OPERAND[TAB]
94 (gdb) maint show test-options-completion-result
95 0 OPERAND
96
97 (gdb) maint test-options unknown-is-error -flag -b 0 -enum yyy[TAB]
98 (gdb) maint show test-options-completion-result
99 1
100
101 (gdb) maint test-options require-dash -unknown[TAB]
102 (gdb) maint show test-options-completion-result
103 1
104
105 Here, "1" means the completion function processed the whole input
106 line, and that the command shouldn't do anything with the arguments,
107 since there are no operands. While "0" indicates that there are
108 operands after options. The text after "0" is the operands.
109
110 This level of detail is particularly important because getting the
111 completion function's entry point to return back to the caller the
112 right pointer into the operand is quite tricky in several
113 scenarios. */
114
115/* Enum values for the "maintenance test-options" commands. */
116const char test_options_enum_values_xxx[] = "xxx";
117const char test_options_enum_values_yyy[] = "yyy";
118const char test_options_enum_values_zzz[] = "zzz";
126
127/* Option data for the "maintenance test-options" commands. */
128
130{
131 bool flag_opt = false;
132 bool xx1_opt = false;
133 bool xx2_opt = false;
134 bool boolean_opt = false;
136 unsigned int uint_unl_opt = 0;
138 std::string string_opt;
139
140 test_options_opts () = default;
141
143
144 /* Dump the options to FILE. ARGS is the remainder unprocessed
145 arguments. */
146 void dump (ui_file *file, const char *args) const
147 {
148 gdb_printf (file,
149 _("-flag %d -xx1 %d -xx2 %d -bool %d "
150 "-enum %s -uint-unl %s -pint-unl %s -string '%s' -- %s\n"),
151 flag_opt,
152 xx1_opt,
153 xx2_opt,
155 enum_opt,
156 (uint_unl_opt == UINT_MAX
157 ? "unlimited"
158 : pulongest (uint_unl_opt)),
159 (pint_unl_opt == -1
160 ? "unlimited"
161 : plongest (pint_unl_opt)),
162 string_opt.c_str (),
163 args);
164 }
165};
166
167/* Option definitions for the "maintenance test-options" commands. */
168
170
171 /* A flag option. */
173 "flag",
174 [] (test_options_opts *opts) { return &opts->flag_opt; },
175 N_("A flag option."),
176 },
177
178 /* A couple flags with similar names, for "ambiguous option names"
179 testing. */
181 "xx1",
182 [] (test_options_opts *opts) { return &opts->xx1_opt; },
183 N_("A flag option."),
184 },
186 "xx2",
187 [] (test_options_opts *opts) { return &opts->xx2_opt; },
188 N_("A flag option."),
189 },
190
191 /* A boolean option. */
193 "bool",
194 [] (test_options_opts *opts) { return &opts->boolean_opt; },
195 nullptr, /* show_cmd_cb */
196 N_("A boolean option."),
197 },
198
199 /* An enum option. */
201 "enum",
203 [] (test_options_opts *opts) { return &opts->enum_opt; },
204 nullptr, /* show_cmd_cb */
205 N_("An enum option."),
206 },
207
208 /* A uinteger + "unlimited" option. */
210 "uinteger-unlimited",
211 [] (test_options_opts *opts) { return &opts->uint_unl_opt; },
213 nullptr, /* show_cmd_cb */
214 N_("A uinteger option."),
215 nullptr, /* show_doc */
216 N_("A help doc that spawns\nmultiple lines."),
217 },
218
219 /* A pinteger + "unlimited" option. */
221 "pinteger-unlimited",
222 [] (test_options_opts *opts) { return &opts->pint_unl_opt; },
224 nullptr, /* show_cmd_cb */
225 N_("A pinteger-unlimited option."),
226 nullptr, /* show_doc */
227 nullptr, /* help_doc */
228 },
229
230 /* A string option. */
232 "string",
233 [] (test_options_opts *opts) { return &opts->string_opt; },
234 nullptr, /* show_cmd_cb */
235 N_("A string option."),
236 },
237};
238
239/* Create an option_def_group for the test_options_opts options, with
240 OPTS as context. */
241
247
248/* Implementation of the "maintenance test-options
249 require-delimiter/unknown-is-error/unknown-is-operand" commands.
250 Each of the commands maps to a different enum process_options_mode
251 enumerator. The test strategy is simply processing the options in
252 a number of scenarios, and printing back the parsed result. */
253
254static void
257{
259
260 gdb::option::process_options (&args, mode,
262
263 if (args == nullptr)
264 args = "";
265 else
266 args = skip_spaces (args);
267
268 opts.dump (gdb_stdout, args);
269}
270
271/* Variable used by the "maintenance show
272 test-options-completion-result" command. This variable is stored
273 by the completer of the "maint test-options" subcommands.
274
275 If the completer returned false, this includes the text at the word
276 point after gdb::option::complete_options returns. If true, then
277 this includes a dump of the processed options. */
279
280/* The "maintenance show test-options-completion-result" command. */
281
282static void
288
289/* Save the completion result in the global variables read by the
290 "maintenance test-options require-delimiter" command. */
291
292static void
294 const char *text)
295{
296 if (res)
297 {
298 string_file stream;
299
300 stream.puts ("1 ");
301 opts.dump (&stream, text);
303 }
304 else
305 {
307 = string_printf ("0 %s\n", text);
308 }
309}
310
311/* Implementation of completer for the "maintenance test-options
312 require-delimiter/unknown-is-error/unknown-is-operand" commands.
313 Each of the commands maps to a different enum process_options_mode
314 enumerator. */
315
316static void
318 const char *text,
320{
322
323 try
324 {
326 (tracker, &text, mode,
328
329 save_completion_result (opts, res, text);
330 }
331 catch (const gdb_exception_error &ex)
332 {
333 save_completion_result (opts, true, text);
334 throw;
335 }
336}
337
338/* Implementation of the "maintenance test-options require-delimiter"
339 command. */
340
341static void
348
349/* Implementation of the "maintenance test-options
350 unknown-is-error" command. */
351
352static void
359
360/* Implementation of the "maintenance test-options
361 unknown-is-operand" command. */
362
363static void
370
371/* Completer for the "maintenance test-options require-delimiter"
372 command. */
373
374static void
382
383/* Completer for the "maintenance test-options unknown-is-error"
384 command. */
385
386static void
394
395/* Completer for the "maintenance test-options unknown-is-operand"
396 command. */
397
398static void
406
407/* Command list for maint test-options. */
409
410
412void
414{
415 cmd_list_element *cmd;
416
417 add_basic_prefix_cmd ("test-options", no_class,
418 _("\
419Generic command for testing the options infrastructure."),
421 0, &maintenancelist);
422
423 const auto def_group = make_test_options_options_def_group (nullptr);
424
425 static const std::string help_require_delim_str
427Command used for testing options processing.\n\
428Usage: maint test-options require-delimiter [[OPTION]... --] [OPERAND]...\n\
429\n\
430Options:\n\
431%OPTIONS%\n\
432\n\
433If you specify any command option, you must use a double dash (\"--\")\n\
434to mark the end of option processing."),
435 def_group);
436
437 static const std::string help_unknown_is_error_str
439Command used for testing options processing.\n\
440Usage: maint test-options unknown-is-error [OPTION]... [OPERAND]...\n\
441\n\
442Options:\n\
443%OPTIONS%"),
444 def_group);
445
446 static const std::string help_unknown_is_operand_str
448Command used for testing options processing.\n\
449Usage: maint test-options unknown-is-operand [OPTION]... [OPERAND]...\n\
450\n\
451Options:\n\
452%OPTIONS%"),
453 def_group);
454
455 cmd = add_cmd ("require-delimiter", class_maintenance,
457 help_require_delim_str.c_str (),
461
462 cmd = add_cmd ("unknown-is-error", class_maintenance,
464 help_unknown_is_error_str.c_str (),
468
469 cmd = add_cmd ("unknown-is-operand", class_maintenance,
471 help_unknown_is_operand_str.c_str (),
475
476 add_cmd ("test-options-completion-result", class_maintenance,
478 _("\
479Show maintenance test-options completion result.\n\
480Shows the results of completing\n\
481\"maint test-options require-delimiter\",\n\
482\"maint test-options unknown-is-error\", or\n\
483\"maint test-options unknown-is-operand\"."),
485}
std::string release()
Definition ui-file.h:204
virtual void puts(const char *str)
Definition ui-file.h:76
struct cmd_list_element * maintenancelist
Definition cli-cmds.c:143
struct cmd_list_element * maintenance_show_cmdlist
Definition maint.c:752
const literal_def pinteger_unlimited_literals[]
struct cmd_list_element * add_cmd(const char *name, enum command_class theclass, const char *doc, struct cmd_list_element **list)
Definition cli-decode.c:233
void set_cmd_completer_handle_brkchars(struct cmd_list_element *cmd, completer_handle_brkchars_ftype *func)
Definition cli-decode.c:125
const literal_def uinteger_unlimited_literals[]
struct cmd_list_element * add_basic_prefix_cmd(const char *name, enum command_class theclass, const char *doc, struct cmd_list_element **subcommands, int allow_unknown, struct cmd_list_element **list)
Definition cli-decode.c:391
@ class_maintenance
Definition command.h:65
@ no_class
Definition command.h:53
static void maintenance_test_options_unknown_is_operand_command_completer(cmd_list_element *ignore, completion_tracker &tracker, const char *text, const char *word)
static void maintenance_test_options_unknown_is_error_command(const char *args, int from_tty)
static void maintenance_test_options_completer_mode(completion_tracker &tracker, const char *text, gdb::option::process_options_mode mode)
const char test_options_enum_values_xxx[]
static const gdb::option::option_def test_options_option_defs[]
static void maintenance_test_options_unknown_is_error_command_completer(cmd_list_element *ignore, completion_tracker &tracker, const char *text, const char *word)
static gdb::option::option_def_group make_test_options_options_def_group(test_options_opts *opts)
static void save_completion_result(const test_options_opts &opts, bool res, const char *text)
void _initialize_maint_test_options()
static void maintenance_test_options_require_delimiter_command_completer(cmd_list_element *ignore, completion_tracker &tracker, const char *text, const char *word)
static void maintenance_test_options_unknown_is_operand_command(const char *args, int from_tty)
static void maintenance_test_options_require_delimiter_command(const char *args, int from_tty)
static const char *const test_options_enum_values_choices[]
const char test_options_enum_values_yyy[]
static void maintenance_test_options_command_mode(const char *args, gdb::option::process_options_mode mode)
static std::string maintenance_test_options_command_completion_text
const char test_options_enum_values_zzz[]
static cmd_list_element * maintenance_test_options_list
static void maintenance_show_test_options_completion_result(const char *args, int from_tty)
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
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
DISABLE_COPY_AND_ASSIGN(test_options_opts)
test_options_opts()=default
void dump(ui_file *file, const char *args) const
void gdb_printf(struct ui_file *stream, const char *format,...)
Definition utils.c:1886
void gdb_puts(const char *linebuffer, struct ui_file *stream)
Definition utils.c:1809
#define gdb_stdout
Definition utils.h:182