1 /* Maintenance commands for testing the options framework.
3 Copyright (C) 2019 Free Software Foundation, Inc.
5 This file is part of GDB.
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.
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.
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/>. */
22 #include "cli/cli-option.h"
24 /* This file defines three "maintenance test-options" subcommands to
25 exercise TAB-completion and option processing:
27 (gdb) maint test-options require-delimiter
28 (gdb) maint test-options unknown-is-error
29 (gdb) maint test-options unknown-is-operand
31 And a fourth one to help with TAB-completion testing.
33 (gdb) maint show test-options-completion-result
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:
39 - "print" and "compile print", are like "require-delimiter",
40 because they accept random expressions as argument.
42 - "backtrace" and "frame/thread apply" are like
43 "unknown-is-operand", because "-" is a valid command.
45 - "compile file" and "compile code" are like "unknown-is-error".
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.
60 These maintenance commands support options of all the different
61 available kinds of commands (boolean, enum, flag, uinteger):
63 (gdb) maint test-options require-delimiter -[TAB]
64 -bool -enum -flag -uinteger -xx1 -xx2
66 (gdb) maint test-options require-delimiter -bool o[TAB]
68 (gdb) maint test-options require-delimiter -enum [TAB]
70 (gdb) maint test-options require-delimiter -uinteger [TAB]
73 '-xx1' and '-xx2' are flag options too. They exist in order to
74 test ambiguous option names, like '-xx'.
76 Invoking the commands makes them print out the options parsed:
78 (gdb) maint test-options unknown-is-error -flag -enum yyy cmdarg
79 -flag 1 -xx1 0 -xx2 0 -bool 0 -enum yyy -uint 0 -zuint-unl 0 -- cmdarg
81 (gdb) maint test-options require-delimiter -flag -enum yyy cmdarg
82 -flag 0 -xx1 0 -xx2 0 -bool 0 -enum xxx -uint 0 -zuint-unl 0 -- -flag -enum yyy cmdarg
83 (gdb) maint test-options require-delimiter -flag -enum yyy cmdarg --
84 Unrecognized option at: cmdarg --
85 (gdb) maint test-options require-delimiter -flag -enum yyy -- cmdarg
86 -flag 1 -xx1 0 -xx2 0 -bool 0 -enum yyy -uint 0 -zuint-unl 0 -- cmdarg
88 The "maint show test-options-completion-result" command exists in
89 order to do something similar for completion:
91 (gdb) maint test-options unknown-is-error -flag -b 0 -enum yyy OPERAND[TAB]
92 (gdb) maint show test-options-completion-result
95 (gdb) maint test-options unknown-is-error -flag -b 0 -enum yyy[TAB]
96 (gdb) maint show test-options-completion-result
99 (gdb) maint test-options require-dash -unknown[TAB]
100 (gdb) maint show test-options-completion-result
103 Here, "1" means the completion function processed the whole input
104 line, and that the command shouldn't do anything with the arguments,
105 since there are no operands. While "0" indicates that there are
106 operands after options. The text after "0" is the operands.
108 This level of detail is particularly important because getting the
109 completion function's entry point to return back to the caller the
110 right pointer into the operand is quite tricky in several
113 /* Enum values for the "maintenance test-options" commands. */
114 const char test_options_enum_values_xxx
[] = "xxx";
115 const char test_options_enum_values_yyy
[] = "yyy";
116 const char test_options_enum_values_zzz
[] = "zzz";
117 static const char *const test_options_enum_values_choices
[] =
119 test_options_enum_values_xxx
,
120 test_options_enum_values_yyy
,
121 test_options_enum_values_zzz
,
125 /* Option data for the "maintenance test-options" commands. */
127 struct test_options_opts
133 const char *enum_opt
= test_options_enum_values_xxx
;
134 unsigned int uint_opt
= 0;
135 int zuint_unl_opt
= 0;
137 /* Dump the options to FILE. ARGS is the remainder unprocessed
139 void dump (ui_file
*file
, const char *args
) const
141 fprintf_unfiltered (file
,
142 _("-flag %d -xx1 %d -xx2 %d -bool %d "
143 "-enum %s -uint %s -zuint-unl %s -- %s\n"),
149 (uint_opt
== UINT_MAX
151 : pulongest (uint_opt
)),
154 : plongest (zuint_unl_opt
)),
159 /* Option definitions for the "maintenance test-options" commands. */
161 static const gdb::option::option_def test_options_option_defs
[] = {
164 gdb::option::flag_option_def
<test_options_opts
> {
166 [] (test_options_opts
*opts
) { return &opts
->flag_opt
; },
167 N_("A flag option."),
170 /* A couple flags with similar names, for "ambiguous option names"
172 gdb::option::flag_option_def
<test_options_opts
> {
174 [] (test_options_opts
*opts
) { return &opts
->xx1_opt
; },
175 N_("A flag option."),
177 gdb::option::flag_option_def
<test_options_opts
> {
179 [] (test_options_opts
*opts
) { return &opts
->xx2_opt
; },
180 N_("A flag option."),
183 /* A boolean option. */
184 gdb::option::boolean_option_def
<test_options_opts
> {
186 [] (test_options_opts
*opts
) { return &opts
->boolean_opt
; },
187 nullptr, /* show_cmd_cb */
188 N_("A boolean option."),
191 /* An enum option. */
192 gdb::option::enum_option_def
<test_options_opts
> {
194 test_options_enum_values_choices
,
195 [] (test_options_opts
*opts
) { return &opts
->enum_opt
; },
196 nullptr, /* show_cmd_cb */
197 N_("An enum option."),
200 /* A uinteger option. */
201 gdb::option::uinteger_option_def
<test_options_opts
> {
203 [] (test_options_opts
*opts
) { return &opts
->uint_opt
; },
204 nullptr, /* show_cmd_cb */
205 N_("A uinteger option."),
206 nullptr, /* show_doc */
207 N_("A help doc that spawns\nmultiple lines."),
210 /* A zuinteger_unlimited option. */
211 gdb::option::zuinteger_unlimited_option_def
<test_options_opts
> {
212 "zuinteger-unlimited",
213 [] (test_options_opts
*opts
) { return &opts
->zuint_unl_opt
; },
214 nullptr, /* show_cmd_cb */
215 N_("A zuinteger-unlimited option."),
216 nullptr, /* show_doc */
217 nullptr, /* help_doc */
221 /* Create an option_def_group for the test_options_opts options, with
224 static inline gdb::option::option_def_group
225 make_test_options_options_def_group (test_options_opts
*opts
)
227 return {{test_options_option_defs
}, opts
};
230 /* Implementation of the "maintenance test-options
231 require-delimiter/unknown-is-error/unknown-is-operand" commands.
232 Each of the commands maps to a different enum process_options_mode
233 enumerator. The test strategy is simply processing the options in
234 a number of scenarios, and printing back the parsed result. */
237 maintenance_test_options_command_mode (const char *args
,
238 gdb::option::process_options_mode mode
)
240 test_options_opts opts
;
242 gdb::option::process_options (&args
, mode
,
243 make_test_options_options_def_group (&opts
));
248 args
= skip_spaces (args
);
250 opts
.dump (gdb_stdout
, args
);
253 /* Variable used by the "maintenance show
254 test-options-completion-result" command. This variable is stored
255 by the completer of the "maint test-options" subcommands.
257 If the completer returned false, this includes the text at the word
258 point after gdb::option::complete_options returns. If true, then
259 this includes a dump of the processed options. */
260 static std::string maintenance_test_options_command_completion_text
;
262 /* The "maintenance show test-options-completion-result" command. */
265 maintenance_show_test_options_completion_result (const char *args
,
268 puts_filtered (maintenance_test_options_command_completion_text
.c_str ());
271 /* Save the completion result in the global variables read by the
272 "maintenance test-options require-delimiter" command. */
275 save_completion_result (const test_options_opts
&opts
, bool res
,
283 opts
.dump (&stream
, text
);
284 maintenance_test_options_command_completion_text
285 = std::move (stream
.string ());
289 maintenance_test_options_command_completion_text
290 = string_printf ("0 %s\n", text
);
294 /* Implementation of completer for the "maintenance test-options
295 require-delimiter/unknown-is-error/unknown-is-operand" commands.
296 Each of the commands maps to a different enum process_options_mode
300 maintenance_test_options_completer_mode (completion_tracker
&tracker
,
302 gdb::option::process_options_mode mode
)
304 test_options_opts opts
;
308 bool res
= (gdb::option::complete_options
309 (tracker
, &text
, mode
,
310 make_test_options_options_def_group (&opts
)));
312 save_completion_result (opts
, res
, text
);
314 catch (const gdb_exception_error
&ex
)
316 save_completion_result (opts
, true, text
);
321 /* Implementation of the "maintenance test-options require-delimiter"
325 maintenance_test_options_require_delimiter_command (const char *args
,
328 maintenance_test_options_command_mode
329 (args
, gdb::option::PROCESS_OPTIONS_REQUIRE_DELIMITER
);
332 /* Implementation of the "maintenance test-options
333 unknown-is-error" command. */
336 maintenance_test_options_unknown_is_error_command (const char *args
,
339 maintenance_test_options_command_mode
340 (args
, gdb::option::PROCESS_OPTIONS_UNKNOWN_IS_ERROR
);
343 /* Implementation of the "maintenance test-options
344 unknown-is-operand" command. */
347 maintenance_test_options_unknown_is_operand_command (const char *args
,
350 maintenance_test_options_command_mode
351 (args
, gdb::option::PROCESS_OPTIONS_UNKNOWN_IS_OPERAND
);
354 /* Completer for the "maintenance test-options require-delimiter"
358 maintenance_test_options_require_delimiter_command_completer
359 (cmd_list_element
*ignore
, completion_tracker
&tracker
,
360 const char *text
, const char *word
)
362 maintenance_test_options_completer_mode
363 (tracker
, text
, gdb::option::PROCESS_OPTIONS_REQUIRE_DELIMITER
);
366 /* Completer for the "maintenance test-options unknown-is-error"
370 maintenance_test_options_unknown_is_error_command_completer
371 (cmd_list_element
*ignore
, completion_tracker
&tracker
,
372 const char *text
, const char *word
)
374 maintenance_test_options_completer_mode
375 (tracker
, text
, gdb::option::PROCESS_OPTIONS_UNKNOWN_IS_ERROR
);
378 /* Completer for the "maintenance test-options unknown-is-operand"
382 maintenance_test_options_unknown_is_operand_command_completer
383 (cmd_list_element
*ignore
, completion_tracker
&tracker
,
384 const char *text
, const char *word
)
386 maintenance_test_options_completer_mode
387 (tracker
, text
, gdb::option::PROCESS_OPTIONS_UNKNOWN_IS_OPERAND
);
390 /* Command list for maint test-options. */
391 struct cmd_list_element
*maintenance_test_options_list
;
393 /* The "maintenance test-options" prefix command. */
396 maintenance_test_options_command (const char *arg
, int from_tty
)
399 (_("\"maintenance test-options\" must be followed "
400 "by the name of a subcommand.\n"));
401 help_list (maintenance_test_options_list
, "maintenance test-options ",
402 all_commands
, gdb_stdout
);
407 _initialize_maint_test_options ()
409 cmd_list_element
*cmd
;
411 add_prefix_cmd ("test-options", no_class
, maintenance_test_options_command
,
413 Generic command for testing the options infrastructure."),
414 &maintenance_test_options_list
,
415 "maintenance test-options ", 0,
418 const auto def_group
= make_test_options_options_def_group (nullptr);
420 static const std::string help_require_delim_str
421 = gdb::option::build_help (_("\
422 Command used for testing options processing.\n\
423 Usage: maint test-options require-delimiter [[OPTION]... --] [OPERAND]...\n\
428 If you specify any command option, you must use a double dash (\"--\")\n\
429 to mark the end of option processing."),
432 static const std::string help_unknown_is_error_str
433 = gdb::option::build_help (_("\
434 Command used for testing options processing.\n\
435 Usage: maint test-options unknown-is-error [OPTION]... [OPERAND]...\n\
442 static const std::string help_unknown_is_operand_str
443 = gdb::option::build_help (_("\
444 Command used for testing options processing.\n\
445 Usage: maint test-options unknown-is-operand [OPTION]... [OPERAND]...\n\
452 cmd
= add_cmd ("require-delimiter", class_maintenance
,
453 maintenance_test_options_require_delimiter_command
,
454 help_require_delim_str
.c_str (),
455 &maintenance_test_options_list
);
456 set_cmd_completer_handle_brkchars
457 (cmd
, maintenance_test_options_require_delimiter_command_completer
);
459 cmd
= add_cmd ("unknown-is-error", class_maintenance
,
460 maintenance_test_options_unknown_is_error_command
,
461 help_unknown_is_error_str
.c_str (),
462 &maintenance_test_options_list
);
463 set_cmd_completer_handle_brkchars
464 (cmd
, maintenance_test_options_unknown_is_error_command_completer
);
466 cmd
= add_cmd ("unknown-is-operand", class_maintenance
,
467 maintenance_test_options_unknown_is_operand_command
,
468 help_unknown_is_operand_str
.c_str (),
469 &maintenance_test_options_list
);
470 set_cmd_completer_handle_brkchars
471 (cmd
, maintenance_test_options_unknown_is_operand_command_completer
);
473 add_cmd ("test-options-completion-result", class_maintenance
,
474 maintenance_show_test_options_completion_result
,
476 Show maintenance test-options completion result.\n\
477 Shows the results of completing\n\
478 \"maint test-options require-delimiter\",\n\
479 \"maint test-options unknown-is-error\", or\n\
480 \"maint test-options unknown-is-operand\"."),
481 &maintenance_show_cmdlist
);