gdb/cli/cli-decode.h

   1 /* Header file for GDB command decoding library.
   2
   3    Copyright (C) 2000-2021 Free Software Foundation, Inc.
   4
   5    This program is free software; you can redistribute it and/or modify
   6    it under the terms of the GNU General Public License as published by
   7    the Free Software Foundation; either version 3 of the License, or
   8    (at your option) any later version.
   9
  10    This program is distributed in the hope that it will be useful,
  11    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13    GNU General Public License for more details.
  14
  15    You should have received a copy of the GNU General Public License
  16    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  17
  18 #ifndef CLI_CLI_DECODE_H
  19 #define CLI_CLI_DECODE_H
  20
  21 /* This file defines the private interfaces for any code implementing
  22    command internals.  */
  23
  24 /* Include the public interfaces.  */
  25 #include "command.h"
  26 #include "gdb_regex.h"
  27 #include "cli-script.h"
  28 #include "completer.h"
  29
  30 /* Not a set/show command.  Note that some commands which begin with
  31    "set" or "show" might be in this category, if their syntax does
  32    not fall into one of the following categories.  */
  33 enum cmd_types
  34 {
  35   not_set_cmd,
  36   set_cmd,
  37   show_cmd
  38 };
  39
  40 /* This structure records one command'd definition.  */
  41
  42
  43 struct cmd_list_element
  44   {
  45     cmd_list_element (const char *name_, enum command_class theclass_,
  46                       const char *doc_)
  47       : name (name_),
  48         theclass (theclass_),
  49         cmd_deprecated (0),
  50         deprecated_warn_user (0),
  51         malloced_replacement (0),
  52         doc_allocated (0),
  53         name_allocated (0),
  54         hook_in (0),
  55         allow_unknown (0),
  56         abbrev_flag (0),
  57         type (not_set_cmd),
  58         var_type (var_boolean),
  59         doc (doc_)
  60     {
  61       memset (&function, 0, sizeof (function));
  62     }
  63
  64     ~cmd_list_element ()
  65     {
  66       if (doc && doc_allocated)
  67         xfree ((char *) doc);
  68       if (name_allocated)
  69         xfree ((char *) name);
  70     }
  71
  72     DISABLE_COPY_AND_ASSIGN (cmd_list_element);
  73
  74
  75     /* Points to next command in this list.  */
  76     struct cmd_list_element *next = nullptr;
  77
  78     /* Name of this command.  */
  79     const char *name;
  80
  81     /* Command class; class values are chosen by application program.  */
  82     enum command_class theclass;
  83
  84     /* When 1 indicated that this command is deprecated.  It may be
  85        removed from gdb's command set in the future.  */
  86
  87     unsigned int cmd_deprecated : 1;
  88
  89     /* The user needs to be warned that this is a deprecated command.
  90        The user should only be warned the first time a command is
  91        used.  */
  92
  93     unsigned int deprecated_warn_user : 1;
  94
  95     /* When functions are deprecated at compile time (this is the way
  96        it should, in general, be done) the memory containing the
  97        replacement string is statically allocated.  In some cases it
  98        makes sense to deprecate commands at runtime (the testsuite is
  99        one example).  In this case the memory for replacement is
 100        malloc'ed.  When a command is undeprecated or re-deprecated at
 101        runtime we don't want to risk calling free on statically
 102        allocated memory, so we check this flag.  */
 103
 104     unsigned int malloced_replacement : 1;
 105
 106     /* Set if the doc field should be xfree'd.  */
 107
 108     unsigned int doc_allocated : 1;
 109
 110     /* Set if the name field should be xfree'd.  */
 111
 112     unsigned int name_allocated : 1;
 113
 114     /* Flag that specifies if this command is already running its hook.  */
 115     /* Prevents the possibility of hook recursion.  */
 116     unsigned int hook_in : 1;
 117
 118     /* For prefix commands only:
 119        nonzero means do not get an error if subcommand is not
 120        recognized; call the prefix's own function in that case.  */
 121     unsigned int allow_unknown : 1;
 122
 123     /* Nonzero says this is an abbreviation, and should not
 124        be mentioned in lists of commands.
 125        This allows "br<tab>" to complete to "break", which it
 126        otherwise wouldn't.  */
 127     unsigned int abbrev_flag : 1;
 128
 129     /* Type of "set" or "show" command (or SET_NOT_SET if not "set"
 130        or "show").  */
 131     ENUM_BITFIELD (cmd_types) type : 2;
 132
 133     /* What kind of variable is *VAR?  */
 134     ENUM_BITFIELD (var_types) var_type : 4;
 135
 136     /* Function definition of this command.  NULL for command class
 137        names and for help topics that are not really commands.  NOTE:
 138        cagney/2002-02-02: This function signature is evolving.  For
 139        the moment suggest sticking with either set_cmd_cfunc() or
 140        set_cmd_sfunc().  */
 141     void (*func) (struct cmd_list_element *c, const char *args, int from_tty)
 142       = nullptr;
 143     /* The command's real callback.  At present func() bounces through
 144        to one of the below.  */
 145     union
 146       {
 147         /* If type is not_set_cmd, call it like this: */
 148         cmd_const_cfunc_ftype *const_cfunc;
 149         /* If type is set_cmd or show_cmd, first set the variables,
 150            and then call this: */
 151         cmd_const_sfunc_ftype *sfunc;
 152       }
 153     function;
 154
 155     /* Local state (context) for this command.  This can be anything.  */
 156     void *context = nullptr;
 157
 158     /* Documentation of this command (or help topic).
 159        First line is brief documentation; remaining lines form, with it,
 160        the full documentation.  First line should end with a period.
 161        Entire string should also end with a period, not a newline.  */
 162     const char *doc;
 163
 164     /* For set/show commands.  A method for printing the output to the
 165        specified stream.  */
 166     show_value_ftype *show_value_func = nullptr;
 167
 168     /* If this command is deprecated, this is the replacement name.  */
 169     const char *replacement = nullptr;
 170
 171     /* If this command represents a show command, then this function
 172        is called before the variable's value is examined.  */
 173     void (*pre_show_hook) (struct cmd_list_element *c) = nullptr;
 174
 175     /* Hook for another command to be executed before this command.  */
 176     struct cmd_list_element *hook_pre = nullptr;
 177
 178     /* Hook for another command to be executed after this command.  */
 179     struct cmd_list_element *hook_post = nullptr;
 180
 181     /* Default arguments to automatically prepend to the user
 182        provided arguments when running this command or alias.  */
 183     std::string default_args;
 184
 185     /* Nonzero identifies a prefix command.  For them, the address
 186        of the variable containing the list of subcommands.  */
 187     struct cmd_list_element **prefixlist = nullptr;
 188
 189     /* For prefix commands only:
 190        String containing prefix commands to get here: this one
 191        plus any others needed to get to it.  Should end in a space.
 192        It is used before the word "command" in describing the
 193        commands reached through this prefix.  */
 194     const char *prefixname = nullptr;
 195
 196     /* The prefix command of this command.  */
 197     struct cmd_list_element *prefix = nullptr;
 198
 199     /* Completion routine for this command.  */
 200     completer_ftype *completer = symbol_completer;
 201
 202     /* Handle the word break characters for this completer.  Usually
 203        this function need not be defined, but for some types of
 204        completers (e.g., Python completers declared as methods inside
 205        a class) the word break chars may need to be redefined
 206        depending on the completer type (e.g., for filename
 207        completers).  */
 208     completer_handle_brkchars_ftype *completer_handle_brkchars = nullptr;
 209
 210     /* Destruction routine for this command.  If non-NULL, this is
 211        called when this command instance is destroyed.  This may be
 212        used to finalize the CONTEXT field, if needed.  */
 213     void (*destroyer) (struct cmd_list_element *self, void *context) = nullptr;
 214
 215     /* Pointer to variable affected by "set" and "show".  Doesn't
 216        matter if type is not_set.  */
 217     void *var = nullptr;
 218
 219     /* Pointer to NULL terminated list of enumerated values (like
 220        argv).  */
 221     const char *const *enums = nullptr;
 222
 223     /* Pointer to command strings of user-defined commands */
 224     counted_command_line user_commands;
 225
 226     /* Pointer to command that is hooked by this one, (by hook_pre)
 227        so the hook can be removed when this one is deleted.  */
 228     struct cmd_list_element *hookee_pre = nullptr;
 229
 230     /* Pointer to command that is hooked by this one, (by hook_post)
 231        so the hook can be removed when this one is deleted.  */
 232     struct cmd_list_element *hookee_post = nullptr;
 233
 234     /* Pointer to command that is aliased by this one, so the
 235        aliased command can be located in case it has been hooked.  */
 236     struct cmd_list_element *cmd_pointer = nullptr;
 237
 238     /* Start of a linked list of all aliases of this command.  */
 239     struct cmd_list_element *aliases = nullptr;
 240
 241     /* Link pointer for aliases on an alias list.  */
 242     struct cmd_list_element *alias_chain = nullptr;
 243
 244     /* If non-null, the pointer to a field in 'struct
 245        cli_suppress_notification', which will be set to true in cmd_func
 246        when this command is being executed.  It will be set back to false
 247        when the command has been executed.  */
 248     int *suppress_notification = nullptr;
 249   };
 250
 251 /* Functions that implement commands about CLI commands.  */
 252
 253 extern void help_cmd (const char *, struct ui_file *);
 254
 255 extern void apropos_cmd (struct ui_file *, struct cmd_list_element *,
 256                          bool verbose, compiled_regex &, const char *);
 257
 258 /* Used to mark commands that don't do anything.  If we just leave the
 259    function field NULL, the command is interpreted as a help topic, or
 260    as a class of commands.  */
 261
 262 extern void not_just_help_class_command (const char *arg, int from_tty);
 263
 264 /* Print only the first line of STR on STREAM.
 265    FOR_VALUE_PREFIX true indicates that the first line is output
 266    to be a prefix to show a value (see deprecated_show_value_hack):
 267    the first character is printed in uppercase, and the trailing
 268    dot character is not printed.  */
 269
 270 extern void print_doc_line (struct ui_file *stream, const char *str,
 271                             bool for_value_prefix);
 272
 273 /* The enums of boolean commands.  */
 274 extern const char * const boolean_enums[];
 275
 276 /* The enums of auto-boolean commands.  */
 277 extern const char * const auto_boolean_enums[];
 278
 279 /* Verify whether a given cmd_list_element is a user-defined command.
 280    Return 1 if it is user-defined.  Return 0 otherwise.  */
 281
 282 extern int cli_user_command_p (struct cmd_list_element *);
 283
 284 extern int find_command_name_length (const char *);
 285
 286 #endif /* CLI_CLI_DECODE_H */