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"
17
18namespace lldb_private {
19class CommandPluginInterfaceImplementation;
20}
21
22namespace lldb {
23
25public:
26 enum {
29 eBroadcastBitQuitCommandReceived = (1 << 2), // User entered quit
32 };
33
36
38
41
42 static const char *
44
45 static const char *
47
48 static bool EventIsCommandInterpreterEvent(const lldb::SBEvent &event);
49
50 explicit operator bool() const;
51
52 bool IsValid() const;
53
54 /// Return whether a built-in command with the passed in
55 /// name or command path exists.
56 ///
57 /// \param[in] cmd
58 /// The command or command path to search for.
59 ///
60 /// \return
61 /// \b true if the command exists, \b false otherwise.
62 bool CommandExists(const char *cmd);
63
64 /// Return whether a user defined command with the passed in
65 /// name or command path exists.
66 ///
67 /// \param[in] cmd
68 /// The command or command path to search for.
69 ///
70 /// \return
71 /// \b true if the command exists, \b false otherwise.
72 bool UserCommandExists(const char *cmd);
73
74 /// Return whether the passed in name or command path
75 /// exists and is an alias to some other command.
76 ///
77 /// \param[in] cmd
78 /// The command or command path to search for.
79 ///
80 /// \return
81 /// \b true if the command exists, \b false otherwise.
82 bool AliasExists(const char *cmd);
83
85
86 static const char *GetBroadcasterClass();
87
88 bool HasCommands();
89
90 bool HasAliases();
91
92 bool HasAliasOptions();
93
94 bool IsInteractive();
95
97
99
100#ifndef SWIG
101 lldb::SBCommand AddMultiwordCommand(const char *name, const char *help);
102
103 /// Add a new command to the lldb::CommandInterpreter.
104 ///
105 /// The new command won't support autorepeat. If you need this functionality,
106 /// use the override of this function that accepts the \a auto_repeat_command
107 /// parameter.
108 ///
109 /// \param[in] name
110 /// The name of the command.
111 ///
112 /// \param[in] impl
113 /// The handler of this command.
114 ///
115 /// \param[in] help
116 /// The general description to show as part of the help message of this
117 /// command.
118 ///
119 /// \return
120 /// A lldb::SBCommand representing the newly created command.
121 lldb::SBCommand AddCommand(const char *name,
123 const char *help);
124
125 /// Add a new command to the lldb::CommandInterpreter.
126 ///
127 /// The new command won't support autorepeat. If you need this functionality,
128 /// use the override of this function that accepts the \a auto_repeat_command
129 /// parameter.
130 ///
131 /// \param[in] name
132 /// The name of the command.
133 ///
134 /// \param[in] impl
135 /// The handler of this command.
136 ///
137 /// \param[in] help
138 /// The general description to show as part of the help message of this
139 /// command.
140 ///
141 /// \param[in] syntax
142 /// The syntax to show as part of the help message of this command. This
143 /// could include a description of the different arguments and flags this
144 /// command accepts.
145 ///
146 /// \return
147 /// A lldb::SBCommand representing the newly created command.
148 lldb::SBCommand AddCommand(const char *name,
150 const char *help, const char *syntax);
151
152 /// Add a new command to the lldb::CommandInterpreter.
153 ///
154 /// \param[in] name
155 /// The name of the command.
156 ///
157 /// \param[in] impl
158 /// The handler of this command.
159 ///
160 /// \param[in] help
161 /// The general description to show as part of the help message of this
162 /// command.
163 ///
164 /// \param[in] syntax
165 /// The syntax to show as part of the help message of this command. This
166 /// could include a description of the different arguments and flags this
167 /// command accepts.
168 ///
169 /// \param[in] auto_repeat_command
170 /// Autorepeating is triggered when the user presses Enter successively
171 /// after executing a command. If \b nullptr is provided, the previous
172 /// exact command will be repeated. If \b "" is provided, autorepeating
173 /// is disabled. Otherwise, the provided string is used as a repeat
174 /// command.
175 ///
176 /// \return
177 /// A lldb::SBCommand representing the newly created command.
178 lldb::SBCommand AddCommand(const char *name,
180 const char *help, const char *syntax,
181 const char *auto_repeat_command);
183#endif
184
185
188 bool is_repl);
189
190 void
192
193 lldb::ReturnStatus HandleCommand(const char *command_line,
195 bool add_to_history = false);
196
197 lldb::ReturnStatus HandleCommand(const char *command_line,
198 SBExecutionContext &exe_ctx,
199 SBCommandReturnObject &result,
200 bool add_to_history = false);
201
203 lldb::SBExecutionContext &override_context,
206
207 // The pointer based interface is not useful in SWIG, since the cursor &
208 // last_char arguments are string pointers INTO current_line and you can't do
209 // that in a scripting language interface in general...
210
211 // In either case, the way this works is that the you give it a line and
212 // cursor position in the line. The function will return the number of
213 // completions. The matches list will contain number_of_completions + 1
214 // elements. The first element is the common substring after the cursor
215 // position for all the matches. The rest of the elements are the matches.
216 // The first element is useful if you are emulating the common shell behavior
217 // where the tab completes to the string that is common among all the
218 // matches, then you should first check if the first element is non-empty,
219 // and if so just insert it and move the cursor to the end of the insertion.
220 // The next tab will return an empty common substring, and a list of choices
221 // (if any), at which point you should display the choices and let the user
222 // type further to disambiguate.
223
224#ifndef SWIG
225 int HandleCompletion(const char *current_line, const char *cursor,
226 const char *last_char, int match_start_point,
227 int max_return_elements, lldb::SBStringList &matches);
228#endif
229
230 int HandleCompletion(const char *current_line, uint32_t cursor_pos,
231 int match_start_point, int max_return_elements,
232 lldb::SBStringList &matches);
233
234 // Same as HandleCompletion, but also fills out `descriptions` with
235 // descriptions for each match.
236#ifndef SWIG
238 const char *current_line, const char *cursor, const char *last_char,
239 int match_start_point, int max_return_elements,
240 lldb::SBStringList &matches, lldb::SBStringList &descriptions);
241#endif
242
243 int HandleCompletionWithDescriptions(const char *current_line,
244 uint32_t cursor_pos,
245 int match_start_point,
246 int max_return_elements,
247 lldb::SBStringList &matches,
248 lldb::SBStringList &descriptions);
249
250 /// Returns whether an interrupt flag was raised either by the SBDebugger -
251 /// when the function is not running on the RunCommandInterpreter thread, or
252 /// by SBCommandInterpreter::InterruptCommand if it is. If your code is doing
253 /// interruptible work, check this API periodically, and interrupt if it
254 /// returns true.
255 bool WasInterrupted() const;
256
257 /// Interrupts the command currently executing in the RunCommandInterpreter
258 /// thread.
259 ///
260 /// \return
261 /// \b true if there was a command in progress to recieve the interrupt.
262 /// \b false if there's no command currently in flight.
263 bool InterruptCommand();
264
265 // Catch commands before they execute by registering a callback that will get
266 // called when the command gets executed. This allows GUI or command line
267 // interfaces to intercept a command and stop it from happening
268 bool SetCommandOverrideCallback(const char *command_name,
270 void *baton);
271
272 /// Return true if the command interpreter is the active IO handler.
273 ///
274 /// This indicates that any input coming into the debugger handles will
275 /// go to the command interpreter and will result in LLDB command line
276 /// commands being executed.
277 bool IsActive();
278
279 /// Get the string that needs to be written to the debugger stdin file
280 /// handle when a control character is typed.
281 ///
282 /// Some GUI programs will intercept "control + char" sequences and want
283 /// to have them do what normally would happen when using a real
284 /// terminal, so this function allows GUI programs to emulate this
285 /// functionality.
286 ///
287 /// \param[in] ch
288 /// The character that was typed along with the control key
289 ///
290 /// \return
291 /// The string that should be written into the file handle that is
292 /// feeding the input stream for the debugger, or nullptr if there is
293 /// no string for this control key.
294 const char *GetIOHandlerControlSequence(char ch);
295
296 bool GetPromptOnQuit();
297
298 void SetPromptOnQuit(bool b);
299
300 /// Sets whether the command interpreter should allow custom exit codes
301 /// for the 'quit' command.
302 void AllowExitCodeOnQuit(bool allow);
303
304 /// Returns true if the user has called the 'quit' command with a custom exit
305 /// code.
307
308 /// Returns the exit code that the user has specified when running the
309 /// 'quit' command. Returns 0 if the user hasn't called 'quit' at all or
310 /// without a custom exit code.
311 int GetQuitStatus();
312
313 /// Resolve the command just as HandleCommand would, expanding abbreviations
314 /// and aliases. If successful, result->GetOutput has the full expansion.
315 void ResolveCommand(const char *command_line, SBCommandReturnObject &result);
316
318
319 /// Returns a list of handled commands, output and error. Each element in
320 /// the list is a dictionary with the following keys/values:
321 /// - "command" (string): The command that was given by the user.
322 /// - "commandName" (string): The name of the executed command.
323 /// - "commandArguments" (string): The arguments of the executed command.
324 /// - "output" (string): The output of the command. Empty ("") if no output.
325 /// - "error" (string): The error of the command. Empty ("") if no error.
326 /// - "durationInSeconds" (float): The time it took to execute the command.
327 /// - "timestampInEpochSeconds" (int): The timestamp when the command is
328 /// executed.
329 ///
330 /// Turn on settings `interpreter.save-transcript` for LLDB to populate
331 /// this list. Otherwise this list is empty.
333
334protected:
336
337 /// Access using SBDebugger::GetCommandInterpreter();
340
342
344
345private:
346 friend class SBDebugger;
347
349};
350
351#ifndef SWIG
353public:
354 virtual ~SBCommandPluginInterface() = default;
355
356 virtual bool DoExecute(lldb::SBDebugger /*debugger*/, char ** /*command*/,
357 lldb::SBCommandReturnObject & /*result*/) {
358 return false;
359 }
360};
361
363public:
364 SBCommand();
365
366 explicit operator bool() const;
367
368 bool IsValid();
369
370 const char *GetName();
371
372 const char *GetHelp();
373
374 const char *GetHelpLong();
375
376 void SetHelp(const char *);
377
378 void SetHelpLong(const char *);
379
380 uint32_t GetFlags();
381
382 void SetFlags(uint32_t flags);
383
384 lldb::SBCommand AddMultiwordCommand(const char *name,
385 const char *help = nullptr);
386
387 /// Add a new subcommand to the lldb::SBCommand.
388 ///
389 /// The new command won't support autorepeat. If you need this functionality,
390 /// use the override of this function that accepts the \a auto_repeat
391 /// parameter.
392 ///
393 /// \param[in] name
394 /// The name of the command.
395 ///
396 /// \param[in] impl
397 /// The handler of this command.
398 ///
399 /// \param[in] help
400 /// The general description to show as part of the help message of this
401 /// command.
402 ///
403 /// \return
404 /// A lldb::SBCommand representing the newly created command.
405 lldb::SBCommand AddCommand(const char *name,
407 const char *help = nullptr);
408
409 /// Add a new subcommand to the lldb::SBCommand.
410 ///
411 /// The new command won't support autorepeat. If you need this functionality,
412 /// use the override of this function that accepts the \a auto_repeat_command
413 /// parameter.
414 ///
415 /// \param[in] name
416 /// The name of the command.
417 ///
418 /// \param[in] impl
419 /// The handler of this command.
420 ///
421 /// \param[in] help
422 /// The general description to show as part of the help message of this
423 /// command.
424 ///
425 /// \param[in] syntax
426 /// The syntax to show as part of the help message of this command. This
427 /// could include a description of the different arguments and flags this
428 /// command accepts.
429 ///
430 /// \return
431 /// A lldb::SBCommand representing the newly created command.
432 lldb::SBCommand AddCommand(const char *name,
434 const char *help, const char *syntax);
435
436 /// Add a new subcommand to the lldb::SBCommand.
437 ///
438 /// The new command won't support autorepeat. If you need this functionality,
439 /// use the override of this function that accepts the \a auto_repeat_command
440 /// parameter.
441 ///
442 /// \param[in] name
443 /// The name of the command.
444 ///
445 /// \param[in] impl
446 /// The handler of this command.
447 ///
448 /// \param[in] help
449 /// The general description to show as part of the help message of this
450 /// command.
451 ///
452 /// \param[in] syntax
453 /// The syntax to show as part of the help message of this command. This
454 /// could include a description of the different arguments and flags this
455 /// command accepts.
456 ///
457 /// \param[in] auto_repeat_command
458 /// Autorepeating is triggered when the user presses Enter successively
459 /// after executing a command. If \b nullptr is provided, the previous
460 /// exact command will be repeated. If \b "" is provided, autorepeating
461 /// is disabled. Otherwise, the provided string is used as a repeat
462 /// command.
463 ///
464 /// \return
465 /// A lldb::SBCommand representing the newly created command.
466 lldb::SBCommand AddCommand(const char *name,
468 const char *help, const char *syntax,
469 const char *auto_repeat_command);
470
471private:
472 friend class SBDebugger;
474
476
478};
479#endif
480
481} // namespace lldb
482
483#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...
SBStructuredData GetTranscript()
Returns a list of handled commands, output and error.
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)
Return whether the passed in name or command path exists and is an alias to some other command.
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)
bool WasInterrupted() const
Returns whether an interrupt flag was raised either by the SBDebugger - when the function is not runn...
void SourceInitFileInCurrentWorkingDirectory(lldb::SBCommandReturnObject &result)
bool UserCommandExists(const char *cmd)
Return whether a user defined command with the passed in name or command path exists.
bool InterruptCommand()
Interrupts the command currently executing in the RunCommandInterpreter thread.
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)
Return whether a built-in command with the passed in name or command path exists.
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 *)
A class that represents a running process on the host machine.
Definition: SBAddress.h:15
std::shared_ptr< lldb_private::CommandObject > CommandObjectSP
Definition: lldb-forward.h:329
ReturnStatus
Command Return Status Types.
bool(* CommandOverrideCallback)(void *baton, const char **argv)
Definition: lldb-types.h:74