1 /* Header file for GDB command decoding library. 2 3 Copyright (C) 2000-2023 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 "gdbsupport/gdb_regex.h" 27 #include "cli-script.h" 28 #include "completer.h" 29 #include "gdbsupport/intrusive_list.h" 30 #include "gdbsupport/buildargv.h" 31 32 /* Not a set/show command. Note that some commands which begin with 33 "set" or "show" might be in this category, if their syntax does 34 not fall into one of the following categories. */ 35 enum cmd_types 36 { 37 not_set_cmd, 38 set_cmd, 39 show_cmd 40 }; 41 42 /* This structure records one command'd definition. */ 43 44 45 struct cmd_list_element 46 { 47 cmd_list_element (const char *name_, enum command_class theclass_, 48 const char *doc_) 49 : name (name_), 50 theclass (theclass_), 51 cmd_deprecated (0), 52 deprecated_warn_user (0), 53 malloced_replacement (0), 54 doc_allocated (0), 55 name_allocated (0), 56 hook_in (0), 57 allow_unknown (0), 58 abbrev_flag (0), 59 type (not_set_cmd), 60 doc (doc_) 61 { 62 memset (&function, 0, sizeof (function)); 63 } 64 65 ~cmd_list_element () 66 { 67 if (doc && doc_allocated) 68 xfree ((char *) doc); 69 if (name_allocated) 70 xfree ((char *) name); 71 } 72 73 DISABLE_COPY_AND_ASSIGN (cmd_list_element); 74 75 /* For prefix commands, return a string containing prefix commands to 76 get here: this one plus any others needed to get to it. Ends in a 77 space. It is used before the word "command" in describing the 78 commands reached through this prefix. 79 80 For non-prefix commands, return an empty string. */ 81 std::string prefixname () const; 82 83 /* Return a vector of strings describing the components of the full name 84 of this command. For example, if this command is 'set AA BB CC', 85 then the vector will contain 4 elements 'set', 'AA', 'BB', and 'CC' 86 in that order. */ 87 std::vector<std::string> command_components () const; 88 89 /* Return true if this command is an alias of another command. */ 90 bool is_alias () const 91 { return this->alias_target != nullptr; } 92 93 /* Return true if this command is a prefix command. */ 94 bool is_prefix () const 95 { return this->subcommands != nullptr; } 96 97 /* Return true if this command is a "command class help" command. For 98 instance, a "stack" dummy command is registered so that one can do 99 "help stack" and show help for all commands of the "stack" class. */ 100 bool is_command_class_help () const 101 { return this->func == nullptr; } 102 103 void set_context (void *context) 104 { 105 gdb_assert (m_context == nullptr); 106 m_context = context; 107 } 108 109 void *context () const 110 { return m_context; } 111 112 /* Points to next command in this list. */ 113 struct cmd_list_element *next = nullptr; 114 115 /* Name of this command. */ 116 const char *name; 117 118 /* Command class; class values are chosen by application program. */ 119 enum command_class theclass; 120 121 /* When 1 indicated that this command is deprecated. It may be 122 removed from gdb's command set in the future. */ 123 124 unsigned int cmd_deprecated : 1; 125 126 /* The user needs to be warned that this is a deprecated command. 127 The user should only be warned the first time a command is 128 used. */ 129 130 unsigned int deprecated_warn_user : 1; 131 132 /* When functions are deprecated at compile time (this is the way 133 it should, in general, be done) the memory containing the 134 replacement string is statically allocated. In some cases it 135 makes sense to deprecate commands at runtime (the testsuite is 136 one example). In this case the memory for replacement is 137 malloc'ed. When a command is undeprecated or re-deprecated at 138 runtime we don't want to risk calling free on statically 139 allocated memory, so we check this flag. */ 140 141 unsigned int malloced_replacement : 1; 142 143 /* Set if the doc field should be xfree'd. */ 144 145 unsigned int doc_allocated : 1; 146 147 /* Set if the name field should be xfree'd. */ 148 149 unsigned int name_allocated : 1; 150 151 /* Flag that specifies if this command is already running its hook. */ 152 /* Prevents the possibility of hook recursion. */ 153 unsigned int hook_in : 1; 154 155 /* For prefix commands only: 156 nonzero means do not get an error if subcommand is not 157 recognized; call the prefix's own function in that case. */ 158 unsigned int allow_unknown : 1; 159 160 /* Nonzero says this is an abbreviation, and should not 161 be mentioned in lists of commands. 162 This allows "br<tab>" to complete to "break", which it 163 otherwise wouldn't. */ 164 unsigned int abbrev_flag : 1; 165 166 /* Type of "set" or "show" command (or SET_NOT_SET if not "set" 167 or "show"). */ 168 ENUM_BITFIELD (cmd_types) type : 2; 169 170 /* Function definition of this command. NULL for command class 171 names and for help topics that are not really commands. NOTE: 172 cagney/2002-02-02: This function signature is evolving. For 173 the moment suggest sticking with either set_cmd_cfunc() or 174 set_cmd_sfunc(). */ 175 cmd_func_ftype *func; 176 177 /* The command's real callback. At present func() bounces through 178 to one of the below. */ 179 union 180 { 181 /* Most commands don't need the cmd_list_element parameter passed to FUNC. 182 They therefore register a command of this type, which doesn't have the 183 cmd_list_element parameter. do_simple_func is installed as FUNC, and 184 acts as a shim between the two. */ 185 cmd_simple_func_ftype *simple_func; 186 } 187 function; 188 189 /* Documentation of this command (or help topic). 190 First line is brief documentation; remaining lines form, with it, 191 the full documentation. First line should end with a period. 192 Entire string should also end with a period, not a newline. */ 193 const char *doc; 194 195 /* For set/show commands. A method for printing the output to the 196 specified stream. */ 197 show_value_ftype *show_value_func = nullptr; 198 199 /* If this command is deprecated, this is the replacement name. */ 200 const char *replacement = nullptr; 201 202 /* Hook for another command to be executed before this command. */ 203 struct cmd_list_element *hook_pre = nullptr; 204 205 /* Hook for another command to be executed after this command. */ 206 struct cmd_list_element *hook_post = nullptr; 207 208 /* Default arguments to automatically prepend to the user 209 provided arguments when running this command or alias. */ 210 std::string default_args; 211 212 /* Nonzero identifies a prefix command. For them, the address 213 of the variable containing the list of subcommands. */ 214 struct cmd_list_element **subcommands = nullptr; 215 216 /* The prefix command of this command. */ 217 struct cmd_list_element *prefix = nullptr; 218 219 /* Completion routine for this command. */ 220 completer_ftype *completer = symbol_completer; 221 222 /* Handle the word break characters for this completer. Usually 223 this function need not be defined, but for some types of 224 completers (e.g., Python completers declared as methods inside 225 a class) the word break chars may need to be redefined 226 depending on the completer type (e.g., for filename 227 completers). */ 228 completer_handle_brkchars_ftype *completer_handle_brkchars = nullptr; 229 230 /* Destruction routine for this command. If non-NULL, this is 231 called when this command instance is destroyed. This may be 232 used to finalize the CONTEXT field, if needed. */ 233 void (*destroyer) (struct cmd_list_element *self, void *context) = nullptr; 234 235 /* Setting affected by "set" and "show". Not used if type is not_set_cmd. */ 236 gdb::optional<setting> var; 237 238 /* Pointer to NULL terminated list of enumerated values (like 239 argv). */ 240 const char *const *enums = nullptr; 241 242 /* Pointer to command strings of user-defined commands */ 243 counted_command_line user_commands; 244 245 /* Pointer to command that is hooked by this one, (by hook_pre) 246 so the hook can be removed when this one is deleted. */ 247 struct cmd_list_element *hookee_pre = nullptr; 248 249 /* Pointer to command that is hooked by this one, (by hook_post) 250 so the hook can be removed when this one is deleted. */ 251 struct cmd_list_element *hookee_post = nullptr; 252 253 /* Pointer to command that is aliased by this one, so the 254 aliased command can be located in case it has been hooked. */ 255 struct cmd_list_element *alias_target = nullptr; 256 257 /* Node to link aliases on an alias list. */ 258 using aliases_list_node_type 259 = intrusive_list_node<cmd_list_element>; 260 aliases_list_node_type aliases_list_node; 261 262 /* Linked list of all aliases of this command. */ 263 using aliases_list_member_node_type 264 = intrusive_member_node<cmd_list_element, 265 &cmd_list_element::aliases_list_node>; 266 using aliases_list_type 267 = intrusive_list<cmd_list_element, aliases_list_member_node_type>; 268 aliases_list_type aliases; 269 270 /* If non-null, the pointer to a field in 'struct 271 cli_suppress_notification', which will be set to true in cmd_func 272 when this command is being executed. It will be set back to false 273 when the command has been executed. */ 274 bool *suppress_notification = nullptr; 275 276 private: 277 /* Local state (context) for this command. This can be anything. */ 278 void *m_context = nullptr; 279 }; 280 281 /* Functions that implement commands about CLI commands. */ 282 283 extern void help_cmd (const char *, struct ui_file *); 284 285 extern void apropos_cmd (struct ui_file *, struct cmd_list_element *, 286 bool verbose, compiled_regex &, const char *); 287 288 /* Used to mark commands that don't do anything. If we just leave the 289 function field NULL, the command is interpreted as a help topic, or 290 as a class of commands. */ 291 292 extern void not_just_help_class_command (const char *arg, int from_tty); 293 294 /* Print only the first line of STR on STREAM. 295 FOR_VALUE_PREFIX true indicates that the first line is output 296 to be a prefix to show a value (see deprecated_show_value_hack): 297 the first character is printed in uppercase, and the trailing 298 dot character is not printed. */ 299 300 extern void print_doc_line (struct ui_file *stream, const char *str, 301 bool for_value_prefix); 302 303 /* The enums of boolean commands. */ 304 extern const char * const boolean_enums[]; 305 306 /* The enums of auto-boolean commands. */ 307 extern const char * const auto_boolean_enums[]; 308 309 /* Verify whether a given cmd_list_element is a user-defined command. 310 Return 1 if it is user-defined. Return 0 otherwise. */ 311 312 extern int cli_user_command_p (struct cmd_list_element *); 313 314 extern int find_command_name_length (const char *); 315 316 #endif /* CLI_CLI_DECODE_H */ 317