gdb/maint-test-options.c

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