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   /* For prefix commands, return a string containing prefix commands to
  75      get here: this one plus any others needed to get to it.  Ends in a
  76      space.  It is used before the word "command" in describing the
  77      commands reached through this prefix.
  78
  79      For non-prefix commands, return an empty string.  */
  80   std::string prefixname () const;
  81
  82   /* Return true if this command is an alias of another command.  */
  83   bool is_alias () const
  84   { return this->alias_target != nullptr; }
  85
  86   /* Return true if this command is a prefix command.  */
  87   bool is_prefix () const
  88   { return this->subcommands != nullptr; }
  89
  90   /* Points to next command in this list.  */
  91   struct cmd_list_element *next = nullptr;
  92
  93   /* Name of this command.  */
  94   const char *name;
  95
  96   /* Command class; class values are chosen by application program.  */
  97   enum command_class theclass;
  98
  99   /* When 1 indicated that this command is deprecated.  It may be
 100      removed from gdb's command set in the future.  */
 101
 102   unsigned int cmd_deprecated : 1;
 103
 104   /* The user needs to be warned that this is a deprecated command.
 105      The user should only be warned the first time a command is
 106      used.  */
 107
 108   unsigned int deprecated_warn_user : 1;
 109
 110   /* When functions are deprecated at compile time (this is the way
 111      it should, in general, be done) the memory containing the
 112      replacement string is statically allocated.  In some cases it
 113      makes sense to deprecate commands at runtime (the testsuite is
 114      one example).  In this case the memory for replacement is
 115      malloc'ed.  When a command is undeprecated or re-deprecated at
 116      runtime we don't want to risk calling free on statically
 117      allocated memory, so we check this flag.  */
 118
 119   unsigned int malloced_replacement : 1;
 120
 121   /* Set if the doc field should be xfree'd.  */
 122
 123   unsigned int doc_allocated : 1;
 124
 125   /* Set if the name field should be xfree'd.  */
 126
 127   unsigned int name_allocated : 1;
 128
 129   /* Flag that specifies if this command is already running its hook.  */
 130   /* Prevents the possibility of hook recursion.  */
 131   unsigned int hook_in : 1;
 132
 133   /* For prefix commands only:
 134      nonzero means do not get an error if subcommand is not
 135      recognized; call the prefix's own function in that case.  */
 136   unsigned int allow_unknown : 1;
 137
 138   /* Nonzero says this is an abbreviation, and should not
 139      be mentioned in lists of commands.
 140      This allows "br<tab>" to complete to "break", which it
 141      otherwise wouldn't.  */
 142   unsigned int abbrev_flag : 1;
 143
 144   /* Type of "set" or "show" command (or SET_NOT_SET if not "set"
 145      or "show").  */
 146   ENUM_BITFIELD (cmd_types) type : 2;
 147
 148   /* What kind of variable is *VAR?  */
 149   ENUM_BITFIELD (var_types) var_type : 4;
 150
 151   /* Function definition of this command.  NULL for command class
 152      names and for help topics that are not really commands.  NOTE:
 153      cagney/2002-02-02: This function signature is evolving.  For
 154      the moment suggest sticking with either set_cmd_cfunc() or
 155      set_cmd_sfunc().  */
 156   void (*func) (struct cmd_list_element *c, const char *args, int from_tty)
 157     = nullptr;
 158   /* The command's real callback.  At present func() bounces through
 159      to one of the below.  */
 160   union
 161     {
 162       /* If type is not_set_cmd, call it like this: */
 163       cmd_const_cfunc_ftype *const_cfunc;
 164       /* If type is set_cmd or show_cmd, first set the variables,
 165          and then call this: */
 166       cmd_const_sfunc_ftype *sfunc;
 167     }
 168   function;
 169
 170   /* Local state (context) for this command.  This can be anything.  */
 171   void *context = nullptr;
 172
 173   /* Documentation of this command (or help topic).
 174      First line is brief documentation; remaining lines form, with it,
 175      the full documentation.  First line should end with a period.
 176      Entire string should also end with a period, not a newline.  */
 177   const char *doc;
 178
 179   /* For set/show commands.  A method for printing the output to the
 180      specified stream.  */
 181   show_value_ftype *show_value_func = nullptr;
 182
 183   /* If this command is deprecated, this is the replacement name.  */
 184   const char *replacement = nullptr;
 185
 186   /* Hook for another command to be executed before this command.  */
 187   struct cmd_list_element *hook_pre = nullptr;
 188
 189   /* Hook for another command to be executed after this command.  */
 190   struct cmd_list_element *hook_post = nullptr;
 191
 192   /* Default arguments to automatically prepend to the user
 193      provided arguments when running this command or alias.  */
 194   std::string default_args;
 195
 196   /* Nonzero identifies a prefix command.  For them, the address
 197      of the variable containing the list of subcommands.  */
 198   struct cmd_list_element **subcommands = nullptr;
 199
 200   /* The prefix command of this command.  */
 201   struct cmd_list_element *prefix = nullptr;
 202
 203   /* Completion routine for this command.  */
 204   completer_ftype *completer = symbol_completer;
 205
 206   /* Handle the word break characters for this completer.  Usually
 207      this function need not be defined, but for some types of
 208      completers (e.g., Python completers declared as methods inside
 209      a class) the word break chars may need to be redefined
 210      depending on the completer type (e.g., for filename
 211      completers).  */
 212   completer_handle_brkchars_ftype *completer_handle_brkchars = nullptr;
 213
 214   /* Destruction routine for this command.  If non-NULL, this is
 215      called when this command instance is destroyed.  This may be
 216      used to finalize the CONTEXT field, if needed.  */
 217   void (*destroyer) (struct cmd_list_element *self, void *context) = nullptr;
 218
 219   /* Pointer to variable affected by "set" and "show".  Doesn't
 220      matter if type is not_set.  */
 221   void *var = nullptr;
 222
 223   /* Pointer to NULL terminated list of enumerated values (like
 224      argv).  */
 225   const char *const *enums = nullptr;
 226
 227   /* Pointer to command strings of user-defined commands */
 228   counted_command_line user_commands;
 229
 230   /* Pointer to command that is hooked by this one, (by hook_pre)
 231      so the hook can be removed when this one is deleted.  */
 232   struct cmd_list_element *hookee_pre = nullptr;
 233
 234   /* Pointer to command that is hooked by this one, (by hook_post)
 235      so the hook can be removed when this one is deleted.  */
 236   struct cmd_list_element *hookee_post = nullptr;
 237
 238   /* Pointer to command that is aliased by this one, so the
 239      aliased command can be located in case it has been hooked.  */
 240   struct cmd_list_element *alias_target = nullptr;
 241
 242   /* Start of a linked list of all aliases of this command.  */
 243   struct cmd_list_element *aliases = nullptr;
 244
 245   /* Link pointer for aliases on an alias list.  */
 246   struct cmd_list_element *alias_chain = nullptr;
 247
 248   /* If non-null, the pointer to a field in 'struct
 249      cli_suppress_notification', which will be set to true in cmd_func
 250      when this command is being executed.  It will be set back to false
 251      when the command has been executed.  */
 252   int *suppress_notification = nullptr;
 253 };
 254
 255 /* Functions that implement commands about CLI commands.  */
 256
 257 extern void help_cmd (const char *, struct ui_file *);
 258
 259 extern void apropos_cmd (struct ui_file *, struct cmd_list_element *,
 260                          bool verbose, compiled_regex &, const char *);
 261
 262 /* Used to mark commands that don't do anything.  If we just leave the
 263    function field NULL, the command is interpreted as a help topic, or
 264    as a class of commands.  */
 265
 266 extern void not_just_help_class_command (const char *arg, int from_tty);
 267
 268 /* Print only the first line of STR on STREAM.
 269    FOR_VALUE_PREFIX true indicates that the first line is output
 270    to be a prefix to show a value (see deprecated_show_value_hack):
 271    the first character is printed in uppercase, and the trailing
 272    dot character is not printed.  */
 273
 274 extern void print_doc_line (struct ui_file *stream, const char *str,
 275                             bool for_value_prefix);
 276
 277 /* The enums of boolean commands.  */
 278 extern const char * const boolean_enums[];
 279
 280 /* The enums of auto-boolean commands.  */
 281 extern const char * const auto_boolean_enums[];
 282
 283 /* Verify whether a given cmd_list_element is a user-defined command.
 284    Return 1 if it is user-defined.  Return 0 otherwise.  */
 285
 286 extern int cli_user_command_p (struct cmd_list_element *);
 287
 288 extern int find_command_name_length (const char *);
 289
 290 #endif /* CLI_CLI_DECODE_H */