FreeChainXenon/binutils-gdb
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
binutils-gdb/gdb/maint-test-options.c
Pedro Alves 9d0faba9f5 Introduce generic command options framework 
This commit adds a generic command options framework, that makes it
easy enough to add '-'-style options to commands in a uniform way,
instead of each command implementing option parsing in its own way.

Options are defined in arrays of option_def objects (for option
definition), and the same options definitions are used for supporting
TAB completion, and also for generating the relevant help fragment of
the "help" command.  See the gdb::options::build_help function, which
returns a string with the result of replacing %OPTIONS% in a template
string with an auto-generated "help" string fragment for all the
passed-in options.

Since most options in GDB are in the form of "-OPT", with a single
dash, this is the format that the framework supports.

I like to think of gdb's "-OPT" as the equivalent to getopt's long
options format ("--OPT"), and gdb's "/" as the equivalent to getopt's
short options format.  getopt's short options format allows mixing
several one-character options, like "ls -als", kind of similar to
gdb's "x /FMT" and "disassemble /MOD", etc.  While with gdb's "-"
options, the option is expected to have a full name, and to be
abbreviatable.  E.g., "watch -location", "break -function main", etc.

This patch only deals with "-" options.  The above comment serves more
to disclose why I don't think we should support mixing several
unrelated options in a single "-" option invocation, like "thread
apply -qcs" instead of "thread apply -q -c -s".

The following patches will add uses of the infrastructure to several
key commands.  Most notably, "print", "compile print", "backtrace",
"frame apply" and "thread apply".  I tried to add options to several
commands in order to make sure the framework didn't leave that many
open holes open.

Options use the same type as set commands -- enum var_types.  So
boolean options are var_boolean, enum options are var_enum, etc.  The
idea is to share code between settings commands and command options.
The "print" options will be based on the "set print" commands, and
their names will be the same.  Actually, their definitions will be the
same too.  There is a function to create "set/show" commands from an
array for option definitions:

 /* Install set/show commands for options defined in OPTIONS.  DATA is
    a pointer to the structure that holds the data associated with the
    OPTIONS array.  */
 extern 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);

That will be used by several following patches.

Other features:

 - You can use the "--" delimiter to explicitly indicate end of
   options.  Several existing commands use this token sequence for
   this effect already, so this just standardizes it.

 - You can shorten option names, as long as unambiguous.  Currently,
   some commands allow this (e.g., break -function), while others do
   not (thread apply all -ascending).  As GDB allows abbreviating
   command names and other things, it feels more GDB-ish to allow
   abbreviating option names too, to me.

 - For boolean options, 0/1 stands for off/on, just like with boolean
   "set" commands.

 - For boolean options, "true" is implied, just like with boolean "set
   commands.

These are the option types supported, with a few examples:

 - boolean options (var_boolean).  The option's argument is optional.

   (gdb) print -pretty on -- *obj
   (gdb) print -pretty off -- *obj
   (gdb) print -p -- *obj
   (gdb) print -p 0 -- *obj

 - flag options (like var_boolean, but no option argument (on/off))

   (gdb) thread apply all -s COMMAND

 - enum options  (var_enum)

   (gdb) bt -entry-values compact
   (gdb) bt -e c

 - uinteger options (var_uinteger)

   (gdb) print -elements 100 -- *obj
   (gdb) print -e 100 -- *obj
   (gdb) print -elements unlimited -- *obj
   (gdb) print -e u -- *obj

 - zuinteger-unlimited options (var_zuinteger_unlimited)

   (gdb) print -max-depth 100 -- obj
   (gdb) print -max-depth -1 -- obj
   (gdb) print -max-depth unlimited -- obj

Other var_types could be supported, of course.  These were just the
types that I needed for the commands that I ported over, in the
following patches.

It was interesting (and unfortunate) to find that we need at least 3
different modes to cover the existing commands:

- Commands that require ending options with "--" if you specify any
  option: "print" and "compile print".

- Commands that do not want to require "--", and want to error out if
  you specify an unknown option (i.e., an unknown argument that starts
  with '-'): "compile code" / "compile file".

- Commands that do not want to require "--", and want to process
  unknown options themselves: "bt", because of "bt -COUNT",
  "thread/frame apply", because "-" is a valid command.

The different behavior is encoded in the process_options_mode enum,
passed to process_options/complete_options.

For testing, this patch adds one representative maintenance command
for each of the process_options_mode values, that are used by the
testsuite to exercise the options framework:

 (gdb) maint test-options require-delimiter
 (gdb) maint test-options unknown-is-error
 (gdb) maint test-options unknown-is-operand

and adds another command to help with TAB-completion testing:

 (gdb) maint show test-options-completion-result

See their description at the top of the maint-test-options.c file.

Docs/NEWS are in a patch later in the series.

gdb/ChangeLog:
2019-06-13  Pedro Alves  <palves@redhat.com>

	* Makefile.in (SUBDIR_CLI_SRCS): Add cli/cli-option.c.
	(COMMON_SFILES): Add maint-test-settings.c.
	* cli/cli-decode.c (boolean_enums): New global, factored out from
	...
	(add_setshow_boolean_cmd): ... here.
	* cli/cli-decode.h (boolean_enums): Declare.
	* cli/cli-option.c: New file.
	* cli/cli-option.h: New file.
	* cli/cli-setshow.c (parse_cli_boolean_value(const char **)): New,
	factored out from ...
	(parse_cli_boolean_value(const char *)): ... this.
	(is_unlimited_literal): Change parameter type to pointer to
	pointer.  Adjust and advance ARG pointer.
	(parse_cli_var_uinteger, parse_cli_var_zuinteger_unlimited)
	(parse_cli_var_enum): New, factored out from ...
	(do_set_command): ... this.  Adjust.
	* cli/cli-setshow.h (parse_cli_boolean_value)
	(parse_cli_var_uinteger, parse_cli_var_zuinteger_unlimited)
	(parse_cli_var_enum): Declare.
	* cli/cli-utils.c: Include "cli/cli-option.h".
	(get_ulongest): New.
	* cli/cli-utils.h (get_ulongest): Declare.
	(check_for_argument): New overloads.
	* maint-test-options.c: New file.

gdb/testsuite/ChangeLog:
2019-06-13  Pedro Alves  <palves@redhat.com>

	* gdb.base/options.c: New file.
	* gdb.base/options.exp: New file.
2019-06-13 00:18:12 +01:00

461 lines
15 KiB
C
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

/* Maintenance commands for testing the options framework.
Copyright (C) 2019 Free Software Foundation, Inc.
This file is part of GDB.
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>. */
#include "defs.h"
#include "gdbcmd.h"
#include "cli/cli-option.h"
/* This file defines three "maintenance test-options" subcommands to
exercise TAB-completion and option processing:
(gdb) maint test-options require-delimiter
(gdb) maint test-options unknown-is-error
(gdb) maint test-options unknown-is-operand
And a fourth one to help with TAB-completion testing.
(gdb) maint show test-options-completion-result
Each of the test-options subcommands exercise
gdb::option::process_options with a different enum
process_options_mode value. Examples for commands they model:
- "print" and "compile print", are like "require-delimiter",
because they accept random expressions as argument.
- "backtrace" and "frame/thread apply" are like
"unknown-is-operand", because "-" is a valid command.
- "compile file" and "compile code" are like "unknown-is-error".
These commands allow exercising all aspects of option processing
without having to pick some existing command. That should be more
stable going forward than relying on an existing user command,
since if we picked say "print", that command or its options could
change in future, and then we'd be left with having to pick some
other command or option to exercise some non-command-specific
option processing detail. Also, actual user commands have side
effects that we're not interested in when we're focusing on unit
testing the options machinery. BTW, a maintenance command is used
as a sort of unit test driver instead of actual "maint selftest"
unit tests, since we need to go all the way via gdb including
readline, for proper testing of TAB completion.
These maintenance commands support options of all the different
available kinds of commands (boolean, enum, flag, uinteger):
(gdb) maint test-options require-delimiter -[TAB]
-bool -enum -flag -uinteger -xx1 -xx2
(gdb) maint test-options require-delimiter -bool o[TAB]
off on
(gdb) maint test-options require-delimiter -enum [TAB]
xxx yyy zzz
(gdb) maint test-options require-delimiter -uinteger [TAB]
NUMBER unlimited
'-xx1' and '-xx2' are flag options too. They exist in order to
test ambiguous option names, like '-xx'.
Invoking the commands makes them print out the options parsed:
(gdb) maint test-options unknown-is-error -flag -enum yyy cmdarg
-flag 1 -xx1 0 -xx2 0 -bool 0 -enum yyy -uint 0 -zuint-unl 0 -- cmdarg
(gdb) maint test-options require-delimiter -flag -enum yyy cmdarg
-flag 0 -xx1 0 -xx2 0 -bool 0 -enum xxx -uint 0 -zuint-unl 0 -- -flag -enum yyy cmdarg
(gdb) maint test-options require-delimiter -flag -enum yyy cmdarg --
Unrecognized option at: cmdarg --
(gdb) maint test-options require-delimiter -flag -enum yyy -- cmdarg
-flag 1 -xx1 0 -xx2 0 -bool 0 -enum yyy -uint 0 -zuint-unl 0 -- cmdarg
The "maint show test-options-completion-result" command exists in
order to do something similar for completion:
(gdb) maint test-options unknown-is-error -flag -b 0 -enum yyy OPERAND[TAB]
(gdb) maint show test-options-completion-result
0 OPERAND
(gdb) maint test-options unknown-is-error -flag -b 0 -enum yyy[TAB]
(gdb) maint show test-options-completion-result
1
(gdb) maint test-options require-dash -unknown[TAB]
(gdb) maint show test-options-completion-result
1
Here, "1" means the completion function processed the whole input
line, and that the command shouldn't do anything with the arguments,
since there are no operands. While "0" indicates that there are
operands after options. The text after "0" is the operands.
This level of detail is particularly important because getting the
completion function's entry point to return back to the caller the
right pointer into the operand is quite tricky in several
scenarios. */
/* Enum values for the "maintenance test-options" commands. */
const char test_options_enum_values_xxx[] = "xxx";
const char test_options_enum_values_yyy[] = "yyy";
const char test_options_enum_values_zzz[] = "zzz";
static const char *const test_options_enum_values_choices[] =
{
test_options_enum_values_xxx,
test_options_enum_values_yyy,
test_options_enum_values_zzz,
NULL
};
/* Option data for the "maintenance test-options" commands. */
struct test_options_opts
{
int flag_opt = 0;
int xx1_opt = 0;
int xx2_opt = 0;
int boolean_opt = 0;
const char *enum_opt = test_options_enum_values_xxx;
unsigned int uint_opt = 0;
int zuint_unl_opt = 0;
};
/* Option definitions for the "maintenance test-options" commands. */
static const gdb::option::option_def test_options_option_defs[] = {
/* A flag option. */
gdb::option::flag_option_def<test_options_opts> {
"flag",
[] (test_options_opts *opts) { return &opts->flag_opt; },
N_("A flag option."),
},
/* A couple flags with similar names, for "ambiguous option names"
testing. */
gdb::option::flag_option_def<test_options_opts> {
"xx1",
[] (test_options_opts *opts) { return &opts->xx1_opt; },
N_("A flag option."),
},
gdb::option::flag_option_def<test_options_opts> {
"xx2",
[] (test_options_opts *opts) { return &opts->xx2_opt; },
N_("A flag option."),
},
/* A boolean option. */
gdb::option::boolean_option_def<test_options_opts> {
"bool",
[] (test_options_opts *opts) { return &opts->boolean_opt; },
nullptr, /* show_cmd_cb */
N_("A boolean option."),
},
/* An enum option. */
gdb::option::enum_option_def<test_options_opts> {
"enum",
test_options_enum_values_choices,
[] (test_options_opts *opts) { return &opts->enum_opt; },
nullptr, /* show_cmd_cb */
N_("An enum option."),
},
/* A uinteger option. */
gdb::option::uinteger_option_def<test_options_opts> {
"uinteger",
[] (test_options_opts *opts) { return &opts->uint_opt; },
nullptr, /* show_cmd_cb */
N_("A uinteger option."),
nullptr, /* show_doc */
N_("A help doc that spawns\nmultiple lines."),
},
/* A zuinteger_unlimited option. */
gdb::option::zuinteger_unlimited_option_def<test_options_opts> {
"zuinteger-unlimited",
[] (test_options_opts *opts) { return &opts->zuint_unl_opt; },
nullptr, /* show_cmd_cb */
N_("A zuinteger-unlimited option."),
nullptr, /* show_doc */
nullptr, /* help_doc */
},
};
/* Create an option_def_group for the test_options_opts options, with
OPTS as context. */
static inline gdb::option::option_def_group
make_test_options_options_def_group (test_options_opts *opts)
{
return {{test_options_option_defs}, opts};
}
/* Implementation of the "maintenance test-options
require-delimiter/unknown-is-error/unknown-is-operand" commands.
Each of the commands maps to a different enum process_options_mode
enumerator. The test strategy is simply processing the options in
a number of scenarios, and printing back the parsed result. */
static void
maintenance_test_options_command_mode (const char *args,
gdb::option::process_options_mode mode)
{
test_options_opts opts;
gdb::option::process_options (&args, mode,
make_test_options_options_def_group (&opts));
if (args == nullptr)
args = "";
else
args = skip_spaces (args);
printf_unfiltered (_("-flag %d -xx1 %d -xx2 %d -bool %d "
"-enum %s -uint %s -zuint-unl %s -- %s\n"),
opts.flag_opt,
opts.xx1_opt,
opts.xx2_opt,
opts.boolean_opt,
opts.enum_opt,
(opts.uint_opt == UINT_MAX
? "unlimited"
: pulongest (opts.uint_opt)),
(opts.zuint_unl_opt == -1
? "unlimited"
: plongest (opts.zuint_unl_opt)),
args);
}
/* Variables used by the "maintenance show
test-options-completion-result" command. These variables are
stored by the completer of the "maint test-options"
subcommands. */
/* The result of gdb::option::complete_options. */
static int maintenance_test_options_command_completion_result;
/* The text at the word point after gdb::option::complete_options
returns. */
static std::string maintenance_test_options_command_completion_text;
/* The "maintenance show test-options-completion-result" command. */
static void
maintenance_show_test_options_completion_result
(struct ui_file *file, int from_tty,
struct cmd_list_element *c, const char *value)
{
if (maintenance_test_options_command_completion_result)
fprintf_filtered (file, "1\n");
else
fprintf_filtered
(file, _("0 %s\n"),
maintenance_test_options_command_completion_text.c_str ());
}
/* Implementation of completer for the "maintenance test-options
require-delimiter/unknown-is-error/unknown-is-operand" commands.
Each of the commands maps to a different enum process_options_mode
enumerator. */
static void
maintenance_test_options_completer_mode (completion_tracker &tracker,
const char *text,
gdb::option::process_options_mode mode)
{
try
{
maintenance_test_options_command_completion_result
= gdb::option::complete_options
(tracker, &text, mode,
make_test_options_options_def_group (nullptr));
maintenance_test_options_command_completion_text = text;
}
catch (const gdb_exception_error &ex)
{
maintenance_test_options_command_completion_result = 1;
throw;
}
}
/* Implementation of the "maintenance test-options require-delimiter"
command. */
static void
maintenance_test_options_require_delimiter_command (const char *args,
int from_tty)
{
maintenance_test_options_command_mode
(args, gdb::option::PROCESS_OPTIONS_REQUIRE_DELIMITER);
}
/* Implementation of the "maintenance test-options
unknown-is-error" command. */
static void
maintenance_test_options_unknown_is_error_command (const char *args,
int from_tty)
{
maintenance_test_options_command_mode
(args, gdb::option::PROCESS_OPTIONS_UNKNOWN_IS_ERROR);
}
/* Implementation of the "maintenance test-options
unknown-is-operand" command. */
static void
maintenance_test_options_unknown_is_operand_command (const char *args,
int from_tty)
{
maintenance_test_options_command_mode
(args, gdb::option::PROCESS_OPTIONS_UNKNOWN_IS_OPERAND);
}
/* Completer for the "maintenance test-options require-delimiter"
command. */
static void
maintenance_test_options_require_delimiter_command_completer
(cmd_list_element *ignore, completion_tracker &tracker,
const char *text, const char *word)
{
maintenance_test_options_completer_mode
(tracker, text, gdb::option::PROCESS_OPTIONS_REQUIRE_DELIMITER);
}
/* Completer for the "maintenance test-options unknown-is-error"
command. */
static void
maintenance_test_options_unknown_is_error_command_completer
(cmd_list_element *ignore, completion_tracker &tracker,
const char *text, const char *word)
{
maintenance_test_options_completer_mode
(tracker, text, gdb::option::PROCESS_OPTIONS_UNKNOWN_IS_ERROR);
}
/* Completer for the "maintenance test-options unknown-is-operand"
command. */
static void
maintenance_test_options_unknown_is_operand_command_completer
(cmd_list_element *ignore, completion_tracker &tracker,
const char *text, const char *word)
{
maintenance_test_options_completer_mode
(tracker, text, gdb::option::PROCESS_OPTIONS_UNKNOWN_IS_OPERAND);
}
/* Command list for maint test-options. */
struct cmd_list_element *maintenance_test_options_list;
/* The "maintenance test-options" prefix command. */
static void
maintenance_test_options_command (const char *arg, int from_tty)
{
printf_unfiltered
(_("\"maintenance test-options\" must be followed "
"by the name of a subcommand.\n"));
help_list (maintenance_test_options_list, "maintenance test-options ",
all_commands, gdb_stdout);
}
void
_initialize_maint_test_options ()
{
cmd_list_element *cmd;
add_prefix_cmd ("test-options", no_class, maintenance_test_options_command,
_("\
Generic command for testing the options infrastructure."),
&maintenance_test_options_list,
"maintenance test-options ", 0,
&maintenancelist);
const auto def_group = make_test_options_options_def_group (nullptr);
static const std::string help_require_delim_str
= gdb::option::build_help (_("\
Command used for testing options processing.\n\
Usage: maint test-options require-delimiter [[OPTION]... --] [OPERAND]...\n\
\n\
Options:\n\
\n\
%OPTIONS%\n\
If you specify any command option, you must use a double dash (\"--\")\n\
to mark the end of option processing."),
def_group);
static const std::string help_unknown_is_error_str
= gdb::option::build_help (_("\
Command used for testing options processing.\n\
Usage: maint test-options unknown-is-error [OPTION]... [OPERAND]...\n\
\n\
Options:\n\
\n\
%OPTIONS%"),
def_group);
static const std::string help_unknown_is_operand_str
= gdb::option::build_help (_("\
Command used for testing options processing.\n\
Usage: maint test-options unknown-is-operand [OPTION]... [OPERAND]...\n\
\n\
Options:\n\
\n\
%OPTIONS%"),
def_group);
cmd = add_cmd ("require-delimiter", class_maintenance,
maintenance_test_options_require_delimiter_command,
help_require_delim_str.c_str (),
&maintenance_test_options_list);
set_cmd_completer_handle_brkchars
(cmd, maintenance_test_options_require_delimiter_command_completer);
cmd = add_cmd ("unknown-is-error", class_maintenance,
maintenance_test_options_unknown_is_error_command,
help_unknown_is_error_str.c_str (),
&maintenance_test_options_list);
set_cmd_completer_handle_brkchars
(cmd, maintenance_test_options_unknown_is_error_command_completer);
cmd = add_cmd ("unknown-is-operand", class_maintenance,
maintenance_test_options_unknown_is_operand_command,
help_unknown_is_operand_str.c_str (),
&maintenance_test_options_list);
set_cmd_completer_handle_brkchars
(cmd, maintenance_test_options_unknown_is_operand_command_completer);
add_setshow_zinteger_cmd ("test-options-completion-result", class_maintenance,
&maintenance_test_options_command_completion_result,
_("\
Set maintenance test-options completion result."), _("\
Show maintenance test-options completion result."), _("\
Show the results of completing\n\
\"maint test-options require-delimiter\",\n\
\"maint test-options unknown-is-error\", or\n\
\"maint test-options unknown-is-operand\"."),
NULL,
maintenance_show_test_options_completion_result,
&maintenance_set_cmdlist,
&maintenance_show_cmdlist);
}
Reference in a new issue View git blame Copy permalink