GDB (xrefs)
Loading...
Searching...
No Matches
cli-decode.h
Go to the documentation of this file.
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. */
41
42/* This structure records one command'd definition. */
43
44
46{
47 cmd_list_element (const char *name_, enum command_class theclass_,
48 const char *doc_)
49 : name (name_),
50 theclass (theclass_),
54 doc_allocated (0),
56 hook_in (0),
57 allow_unknown (0),
58 abbrev_flag (0),
60 doc (doc_)
61 {
62 memset (&function, 0, sizeof (function));
63 }
64
66 {
67 if (doc && doc_allocated)
68 xfree ((char *) doc);
70 xfree ((char *) name);
71 }
72
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. */
101 { return this->func == nullptr; }
102
103 void set_context (void *context)
104 {
105 gdb_assert (m_context == nullptr);
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. */
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(). */
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. */
186 }
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. */
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. */
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). */
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 */
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. */
256
257 /* Node to link aliases on an alias list. */
259 = intrusive_list_node<cmd_list_element>;
261
262 /* Linked list of all aliases of this command. */
264 = intrusive_member_node<cmd_list_element,
267 = intrusive_list<cmd_list_element, aliases_list_member_node_type>;
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;
276private:
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
283extern void help_cmd (const char *, struct ui_file *);
284
285extern void apropos_cmd (struct ui_file *, struct cmd_list_element *,
286 bool verbose, compiled_regex &);
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
292extern 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
300extern void print_doc_line (struct ui_file *stream, const char *str,
301 bool for_value_prefix);
302
303/* The enums of boolean commands. */
304extern const char * const boolean_enums[];
305
306/* The enums of auto-boolean commands. */
307extern 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
312extern int cli_user_command_p (struct cmd_list_element *);
313
314extern int find_command_name_length (const char *);
315
316#endif /* CLI_CLI_DECODE_H */
void xfree(void *)
int find_command_name_length(const char *)
cmd_types
Definition cli-decode.h:36
@ not_set_cmd
Definition cli-decode.h:37
@ set_cmd
Definition cli-decode.h:38
@ show_cmd
Definition cli-decode.h:39
void apropos_cmd(struct ui_file *, struct cmd_list_element *, bool verbose, compiled_regex &)
void not_just_help_class_command(const char *arg, int from_tty)
Definition cli-decode.c:483
const char *const boolean_enums[]
Definition cli-decode.c:800
void help_cmd(const char *, struct ui_file *)
int cli_user_command_p(struct cmd_list_element *)
const char *const auto_boolean_enums[]
Definition cli-decode.c:744
void print_doc_line(struct ui_file *stream, const char *str, bool for_value_prefix)
std::shared_ptr< command_line > counted_command_line
Definition cli-script.h:67
void completer_ftype(struct cmd_list_element *, completion_tracker &tracker, const char *text, const char *word)
Definition command.h:511
void cmd_simple_func_ftype(const char *args, int from_tty)
Definition command.h:388
void show_value_ftype(struct ui_file *file, int from_tty, struct cmd_list_element *cmd, const char *value)
Definition command.h:660
void completer_handle_brkchars_ftype(struct cmd_list_element *, completion_tracker &tracker, const char *text, const char *word)
Definition command.h:516
void cmd_func_ftype(const char *args, int from_tty, cmd_list_element *c)
Definition command.h:499
command_class
Definition command.h:43
void symbol_completer(struct cmd_list_element *ignore, completion_tracker &tracker, const char *text, const char *word)
Definition completer.c:1110
unsigned int doc_allocated
Definition cli-decode.h:145
cmd_list_element(const char *name_, enum command_class theclass_, const char *doc_)
Definition cli-decode.h:47
struct cmd_list_element * hook_post
Definition cli-decode.h:206
unsigned int abbrev_flag
Definition cli-decode.h:164
union cmd_list_element::@27 function
aliases_list_type aliases
Definition cli-decode.h:265
struct cmd_list_element * hookee_post
Definition cli-decode.h:251
const char * doc
Definition cli-decode.h:193
std::vector< std::string > command_components() const
Definition cli-decode.c:151
intrusive_member_node< cmd_list_element, &cmd_list_element::aliases_list_node > aliases_list_member_node_type
Definition cli-decode.h:262
bool * suppress_notification
Definition cli-decode.h:271
cmd_simple_func_ftype * simple_func
Definition cli-decode.h:185
cmd_func_ftype * func
Definition cli-decode.h:175
gdb::optional< setting > var
Definition cli-decode.h:236
struct cmd_list_element * hookee_pre
Definition cli-decode.h:247
struct cmd_list_element * hook_pre
Definition cli-decode.h:203
std::string prefixname() const
Definition cli-decode.c:132
DISABLE_COPY_AND_ASSIGN(cmd_list_element)
std::string default_args
Definition cli-decode.h:210
aliases_list_node_type aliases_list_node
Definition cli-decode.h:259
struct cmd_list_element ** subcommands
Definition cli-decode.h:214
completer_handle_brkchars_ftype * completer_handle_brkchars
Definition cli-decode.h:228
unsigned int cmd_deprecated
Definition cli-decode.h:124
completer_ftype * completer
Definition cli-decode.h:220
counted_command_line user_commands
Definition cli-decode.h:243
struct cmd_list_element * prefix
Definition cli-decode.h:217
unsigned int deprecated_warn_user
Definition cli-decode.h:130
bool is_alias() const
Definition cli-decode.h:90
unsigned int hook_in
Definition cli-decode.h:153
bool is_command_class_help() const
Definition cli-decode.h:100
intrusive_list< cmd_list_element, aliases_list_member_node_type > aliases_list_type
Definition cli-decode.h:264
void * context() const
Definition cli-decode.h:109
__extension__ enum cmd_types type
Definition cli-decode.h:168
void(* destroyer)(struct cmd_list_element *self, void *context)
Definition cli-decode.h:233
unsigned int name_allocated
Definition cli-decode.h:149
struct cmd_list_element * alias_target
Definition cli-decode.h:255
intrusive_list_node< cmd_list_element > aliases_list_node_type
Definition cli-decode.h:258
unsigned int malloced_replacement
Definition cli-decode.h:141
const char * name
Definition cli-decode.h:116
const char *const * enums
Definition cli-decode.h:240
bool is_prefix() const
Definition cli-decode.h:94
show_value_ftype * show_value_func
Definition cli-decode.h:197
const char * replacement
Definition cli-decode.h:200
unsigned int allow_unknown
Definition cli-decode.h:158
enum command_class theclass
Definition cli-decode.h:119
void set_context(void *context)
Definition cli-decode.h:103