LLDB mainline
SBCommandInterpreter.h
Go to the documentation of this file.
1//===-- SBCommandInterpreter.h ----------------------------------*- C++ -*-===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8
9#ifndef LLDB_API_SBCOMMANDINTERPRETER_H
10#define LLDB_API_SBCOMMANDINTERPRETER_H
11
12#include <memory>
13
14#include "lldb/API/SBDebugger.h"
15#include "lldb/API/SBDefines.h"
16
17namespace lldb {
18
20public:
21 enum {
24 eBroadcastBitQuitCommandReceived = (1 << 2), // User entered quit
27 };
28
30
32
35
36 static const char *
38
39 static const char *
41
42 static bool EventIsCommandInterpreterEvent(const lldb::SBEvent &event);
43
44 explicit operator bool() const;
45
46 bool IsValid() const;
47
48 bool CommandExists(const char *cmd);
49
50 bool AliasExists(const char *cmd);
51
53
54 static const char *GetBroadcasterClass();
55
56 bool HasCommands();
57
58 bool HasAliases();
59
60 bool HasAliasOptions();
61
62 bool IsInteractive();
63
65
67
68 lldb::SBCommand AddMultiwordCommand(const char *name, const char *help);
69
70 /// Add a new command to the lldb::CommandInterpreter.
71 ///
72 /// The new command won't support autorepeat. If you need this functionality,
73 /// use the override of this function that accepts the \a auto_repeat_command
74 /// parameter.
75 ///
76 /// \param[in] name
77 /// The name of the command.
78 ///
79 /// \param[in] impl
80 /// The handler of this command.
81 ///
82 /// \param[in] help
83 /// The general description to show as part of the help message of this
84 /// command.
85 ///
86 /// \return
87 /// A lldb::SBCommand representing the newly created command.
88 lldb::SBCommand AddCommand(const char *name,
90 const char *help);
91
92 /// Add a new command to the lldb::CommandInterpreter.
93 ///
94 /// The new command won't support autorepeat. If you need this functionality,
95 /// use the override of this function that accepts the \a auto_repeat_command
96 /// parameter.
97 ///
98 /// \param[in] name
99 /// The name of the command.
100 ///
101 /// \param[in] impl
102 /// The handler of this command.
103 ///
104 /// \param[in] help
105 /// The general description to show as part of the help message of this
106 /// command.
107 ///
108 /// \param[in] syntax
109 /// The syntax to show as part of the help message of this command. This
110 /// could include a description of the different arguments and flags this
111 /// command accepts.
112 ///
113 /// \return
114 /// A lldb::SBCommand representing the newly created command.
115 lldb::SBCommand AddCommand(const char *name,
117 const char *help, const char *syntax);
118
119 /// Add a new command to the lldb::CommandInterpreter.
120 ///
121 /// \param[in] name
122 /// The name of the command.
123 ///
124 /// \param[in] impl
125 /// The handler of this command.
126 ///
127 /// \param[in] help
128 /// The general description to show as part of the help message of this
129 /// command.
130 ///
131 /// \param[in] syntax
132 /// The syntax to show as part of the help message of this command. This
133 /// could include a description of the different arguments and flags this
134 /// command accepts.
135 ///
136 /// \param[in] auto_repeat_command
137 /// Autorepeating is triggered when the user presses Enter successively
138 /// after executing a command. If \b nullptr is provided, the previous
139 /// exact command will be repeated. If \b "" is provided, autorepeating
140 /// is disabled. Otherwise, the provided string is used as a repeat
141 /// command.
142 ///
143 /// \return
144 /// A lldb::SBCommand representing the newly created command.
145 lldb::SBCommand AddCommand(const char *name,
147 const char *help, const char *syntax,
148 const char *auto_repeat_command);
149
151
154 bool is_repl);
155
156 void
158
159 lldb::ReturnStatus HandleCommand(const char *command_line,
161 bool add_to_history = false);
162
163 lldb::ReturnStatus HandleCommand(const char *command_line,
164 SBExecutionContext &exe_ctx,
165 SBCommandReturnObject &result,
166 bool add_to_history = false);
167
169 lldb::SBExecutionContext &override_context,
172
173 // The pointer based interface is not useful in SWIG, since the cursor &
174 // last_char arguments are string pointers INTO current_line and you can't do
175 // that in a scripting language interface in general...
176
177 // In either case, the way this works is that the you give it a line and
178 // cursor position in the line. The function will return the number of
179 // completions. The matches list will contain number_of_completions + 1
180 // elements. The first element is the common substring after the cursor
181 // position for all the matches. The rest of the elements are the matches.
182 // The first element is useful if you are emulating the common shell behavior
183 // where the tab completes to the string that is common among all the
184 // matches, then you should first check if the first element is non-empty,
185 // and if so just insert it and move the cursor to the end of the insertion.
186 // The next tab will return an empty common substring, and a list of choices
187 // (if any), at which point you should display the choices and let the user
188 // type further to disambiguate.
189
190 int HandleCompletion(const char *current_line, const char *cursor,
191 const char *last_char, int match_start_point,
192 int max_return_elements, lldb::SBStringList &matches);
193
194 int HandleCompletion(const char *current_line, uint32_t cursor_pos,
195 int match_start_point, int max_return_elements,
196 lldb::SBStringList &matches);
197
198 // Same as HandleCompletion, but also fills out `descriptions` with
199 // descriptions for each match.
201 const char *current_line, const char *cursor, const char *last_char,
202 int match_start_point, int max_return_elements,
203 lldb::SBStringList &matches, lldb::SBStringList &descriptions);
204
205 int HandleCompletionWithDescriptions(const char *current_line,
206 uint32_t cursor_pos,
207 int match_start_point,
208 int max_return_elements,
209 lldb::SBStringList &matches,
210 lldb::SBStringList &descriptions);
211
212 bool WasInterrupted() const;
213
214 // Catch commands before they execute by registering a callback that will get
215 // called when the command gets executed. This allows GUI or command line
216 // interfaces to intercept a command and stop it from happening
217 bool SetCommandOverrideCallback(const char *command_name,
219 void *baton);
220
222 lldb_private::CommandInterpreter *interpreter_ptr =
223 nullptr); // Access using SBDebugger::GetCommandInterpreter();
224
225 /// Return true if the command interpreter is the active IO handler.
226 ///
227 /// This indicates that any input coming into the debugger handles will
228 /// go to the command interpreter and will result in LLDB command line
229 /// commands being executed.
230 bool IsActive();
231
232 /// Get the string that needs to be written to the debugger stdin file
233 /// handle when a control character is typed.
234 ///
235 /// Some GUI programs will intercept "control + char" sequences and want
236 /// to have them do what normally would happen when using a real
237 /// terminal, so this function allows GUI programs to emulate this
238 /// functionality.
239 ///
240 /// \param[in] ch
241 /// The character that was typed along with the control key
242 ///
243 /// \return
244 /// The string that should be written into the file handle that is
245 /// feeding the input stream for the debugger, or nullptr if there is
246 /// no string for this control key.
247 const char *GetIOHandlerControlSequence(char ch);
248
249 bool GetPromptOnQuit();
250
251 void SetPromptOnQuit(bool b);
252
253 /// Sets whether the command interpreter should allow custom exit codes
254 /// for the 'quit' command.
255 void AllowExitCodeOnQuit(bool allow);
256
257 /// Returns true if the user has called the 'quit' command with a custom exit
258 /// code.
260
261 /// Returns the exit code that the user has specified when running the
262 /// 'quit' command. Returns 0 if the user hasn't called 'quit' at all or
263 /// without a custom exit code.
264 int GetQuitStatus();
265
266 /// Resolve the command just as HandleCommand would, expanding abbreviations
267 /// and aliases. If successful, result->GetOutput has the full expansion.
268 void ResolveCommand(const char *command_line, SBCommandReturnObject &result);
269
270protected:
272
274
276
277private:
278 friend class SBDebugger;
279
281};
282
284public:
285 virtual ~SBCommandPluginInterface() = default;
286
287 virtual bool DoExecute(lldb::SBDebugger /*debugger*/, char ** /*command*/,
288 lldb::SBCommandReturnObject & /*result*/) {
289 return false;
290 }
291};
292
294public:
295 SBCommand();
296
297 explicit operator bool() const;
298
299 bool IsValid();
300
301 const char *GetName();
302
303 const char *GetHelp();
304
305 const char *GetHelpLong();
306
307 void SetHelp(const char *);
308
309 void SetHelpLong(const char *);
310
312
313 void SetFlags(uint32_t flags);
314
315 lldb::SBCommand AddMultiwordCommand(const char *name,
316 const char *help = nullptr);
317
318 /// Add a new subcommand to the lldb::SBCommand.
319 ///
320 /// The new command won't support autorepeat. If you need this functionality,
321 /// use the override of this function that accepts the \a auto_repeat
322 /// parameter.
323 ///
324 /// \param[in] name
325 /// The name of the command.
326 ///
327 /// \param[in] impl
328 /// The handler of this command.
329 ///
330 /// \param[in] help
331 /// The general description to show as part of the help message of this
332 /// command.
333 ///
334 /// \return
335 /// A lldb::SBCommand representing the newly created command.
336 lldb::SBCommand AddCommand(const char *name,
338 const char *help = nullptr);
339
340 /// Add a new subcommand to the lldb::SBCommand.
341 ///
342 /// The new command won't support autorepeat. If you need this functionality,
343 /// use the override of this function that accepts the \a auto_repeat_command
344 /// parameter.
345 ///
346 /// \param[in] name
347 /// The name of the command.
348 ///
349 /// \param[in] impl
350 /// The handler of this command.
351 ///
352 /// \param[in] help
353 /// The general description to show as part of the help message of this
354 /// command.
355 ///
356 /// \param[in] syntax
357 /// The syntax to show as part of the help message of this command. This
358 /// could include a description of the different arguments and flags this
359 /// command accepts.
360 ///
361 /// \return
362 /// A lldb::SBCommand representing the newly created command.
363 lldb::SBCommand AddCommand(const char *name,
365 const char *help, const char *syntax);
366
367 /// Add a new subcommand to the lldb::SBCommand.
368 ///
369 /// The new command won't support autorepeat. If you need this functionality,
370 /// use the override of this function that accepts the \a auto_repeat_command
371 /// parameter.
372 ///
373 /// \param[in] name
374 /// The name of the command.
375 ///
376 /// \param[in] impl
377 /// The handler of this command.
378 ///
379 /// \param[in] help
380 /// The general description to show as part of the help message of this
381 /// command.
382 ///
383 /// \param[in] syntax
384 /// The syntax to show as part of the help message of this command. This
385 /// could include a description of the different arguments and flags this
386 /// command accepts.
387 ///
388 /// \param[in] auto_repeat_command
389 /// Autorepeating is triggered when the user presses Enter successively
390 /// after executing a command. If \b nullptr is provided, the previous
391 /// exact command will be repeated. If \b "" is provided, autorepeating
392 /// is disabled. Otherwise, the provided string is used as a repeat
393 /// command.
394 ///
395 /// \return
396 /// A lldb::SBCommand representing the newly created command.
397 lldb::SBCommand AddCommand(const char *name,
399 const char *help, const char *syntax,
400 const char *auto_repeat_command);
401
402private:
403 friend class SBDebugger;
405
406 SBCommand(lldb::CommandObjectSP cmd_sp);
407
408 lldb::CommandObjectSP m_opaque_sp;
409};
410
411} // namespace lldb
412
413#endif // LLDB_API_SBCOMMANDINTERPRETER_H
lldb::SBCommand AddMultiwordCommand(const char *name, const char *help)
const lldb::SBCommandInterpreter & operator=(const lldb::SBCommandInterpreter &rhs)
lldb_private::CommandInterpreter & ref()
void ResolveCommand(const char *command_line, SBCommandReturnObject &result)
Resolve the command just as HandleCommand would, expanding abbreviations and aliases.
static const char * GetBroadcasterClass()
const char * GetIOHandlerControlSequence(char ch)
Get the string that needs to be written to the debugger stdin file handle when a control character is...
lldb::SBCommand AddCommand(const char *name, lldb::SBCommandPluginInterface *impl, const char *help)
Add a new command to the lldb::CommandInterpreter.
void AllowExitCodeOnQuit(bool allow)
Sets whether the command interpreter should allow custom exit codes for the 'quit' command.
bool AliasExists(const char *cmd)
bool IsActive()
Return true if the command interpreter is the active IO handler.
static const char * GetArgumentDescriptionAsCString(const lldb::CommandArgumentType arg_type)
int HandleCompletion(const char *current_line, const char *cursor, const char *last_char, int match_start_point, int max_return_elements, lldb::SBStringList &matches)
void reset(lldb_private::CommandInterpreter *)
static const char * GetArgumentTypeAsCString(const lldb::CommandArgumentType arg_type)
bool SetCommandOverrideCallback(const char *command_name, lldb::CommandOverrideCallback callback, void *baton)
void SourceInitFileInCurrentWorkingDirectory(lldb::SBCommandReturnObject &result)
void SourceInitFileInHomeDirectory(lldb::SBCommandReturnObject &result)
lldb_private::CommandInterpreter * m_opaque_ptr
void HandleCommandsFromFile(lldb::SBFileSpec &file, lldb::SBExecutionContext &override_context, lldb::SBCommandInterpreterRunOptions &options, lldb::SBCommandReturnObject result)
lldb_private::CommandInterpreter * get()
bool HasCustomQuitExitCode()
Returns true if the user has called the 'quit' command with a custom exit code.
int HandleCompletionWithDescriptions(const char *current_line, const char *cursor, const char *last_char, int match_start_point, int max_return_elements, lldb::SBStringList &matches, lldb::SBStringList &descriptions)
void SourceInitFileInGlobalDirectory(lldb::SBCommandReturnObject &result)
bool CommandExists(const char *cmd)
lldb::ReturnStatus HandleCommand(const char *command_line, lldb::SBCommandReturnObject &result, bool add_to_history=false)
lldb::SBBroadcaster GetBroadcaster()
int GetQuitStatus()
Returns the exit code that the user has specified when running the 'quit' command.
static bool EventIsCommandInterpreterEvent(const lldb::SBEvent &event)
virtual ~SBCommandPluginInterface()=default
virtual bool DoExecute(lldb::SBDebugger, char **, lldb::SBCommandReturnObject &)
const char * GetHelpLong()
lldb::CommandObjectSP m_opaque_sp
lldb::SBCommand AddMultiwordCommand(const char *name, const char *help=nullptr)
void SetHelpLong(const char *)
void SetFlags(uint32_t flags)
lldb::SBCommand AddCommand(const char *name, lldb::SBCommandPluginInterface *impl, const char *help=nullptr)
Add a new subcommand to the lldb::SBCommand.
void SetHelp(const char *)
Definition: SBAddress.h:15
ReturnStatus
Command Return Status Types.
bool(* CommandOverrideCallback)(void *baton, const char **argv)
Definition: lldb-types.h:71