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 
17 namespace lldb {
18 
20 public:
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.
259  bool HasCustomQuitExitCode();
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 
270 protected:
272 
274 
276 
277 private:
278  friend class SBDebugger;
279 
281 };
282 
284 public:
285  virtual ~SBCommandPluginInterface() = default;
286 
287  virtual bool DoExecute(lldb::SBDebugger /*debugger*/, char ** /*command*/,
288  lldb::SBCommandReturnObject & /*result*/) {
289  return false;
290  }
291 };
292 
293 class SBCommand {
294 public:
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 
311  uint32_t GetFlags();
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 
402 private:
403  friend class SBDebugger;
404  friend class SBCommandInterpreter;
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::SBStringList
Definition: SBStringList.h:16
lldb::SBCommandInterpreter::eBroadcastBitAsynchronousOutputData
@ eBroadcastBitAsynchronousOutputData
Definition: SBCommandInterpreter.h:25
lldb::SBCommandInterpreter::SourceInitFileInHomeDirectory
void SourceInitFileInHomeDirectory(lldb::SBCommandReturnObject &result)
Definition: SBCommandInterpreter.cpp:446
lldb::SBCommandPluginInterface
Definition: SBCommandInterpreter.h:283
lldb::SBCommandInterpreter::~SBCommandInterpreter
~SBCommandInterpreter()
lldb::SBCommandInterpreter::get
lldb_private::CommandInterpreter * get()
Definition: SBCommandInterpreter.cpp:418
lldb::SBCommandInterpreter::IsInteractive
bool IsInteractive()
Definition: SBCommandInterpreter.cpp:336
SBDefines.h
lldb::SBCommandReturnObject
Definition: SBCommandReturnObject.h:24
lldb::SBCommandInterpreter::GetQuitStatus
int GetQuitStatus()
Returns the exit code that the user has specified when running the 'quit' command.
Definition: SBCommandInterpreter.cpp:398
lldb::SBCommandInterpreter
Definition: SBCommandInterpreter.h:19
lldb::SBCommand::AddMultiwordCommand
lldb::SBCommand AddMultiwordCommand(const char *name, const char *help=nullptr)
Definition: SBCommandInterpreter.cpp:632
lldb::SBCommandInterpreter::AllowExitCodeOnQuit
void AllowExitCodeOnQuit(bool allow)
Sets whether the command interpreter should allow custom exit codes for the 'quit' command.
Definition: SBCommandInterpreter.cpp:382
lldb::SBCommandInterpreter::HasCommands
bool HasCommands()
Definition: SBCommandInterpreter.cpp:318
lldb::SBCommandInterpreter::GetPromptOnQuit
bool GetPromptOnQuit()
Definition: SBCommandInterpreter.cpp:369
lldb::SBCommand::SetFlags
void SetFlags(uint32_t flags)
Definition: SBCommandInterpreter.cpp:689
lldb::SBCommandInterpreter::GetProcess
lldb::SBProcess GetProcess()
Definition: SBCommandInterpreter.cpp:342
lldb::SBCommandInterpreter::GetBroadcasterClass
static const char * GetBroadcasterClass()
Definition: SBCommandInterpreter.cpp:493
lldb::SBCommand::GetFlags
uint32_t GetFlags()
Definition: SBCommandInterpreter.cpp:683
lldb::SBEvent
Definition: SBEvent.h:21
lldb::SBProcess
Definition: SBProcess.h:23
lldb::SBCommandInterpreter::GetDebugger
lldb::SBDebugger GetDebugger()
Definition: SBCommandInterpreter.cpp:359
lldb::SBCommandInterpreter::HandleCommand
lldb::ReturnStatus HandleCommand(const char *command_line, lldb::SBCommandReturnObject &result, bool add_to_history=false)
Definition: SBCommandInterpreter.cpp:150
lldb::SBExecutionContext
Definition: SBExecutionContext.h:20
lldb::SBCommandInterpreter::IsValid
bool IsValid() const
Definition: SBCommandInterpreter.cpp:103
lldb::SBCommand::m_opaque_sp
lldb::CommandObjectSP m_opaque_sp
Definition: SBCommandInterpreter.h:408
lldb::SBCommandInterpreter::GetIOHandlerControlSequence
const char * GetIOHandlerControlSequence(char ch)
Get the string that needs to be written to the debugger stdin file handle when a control character is...
Definition: SBCommandInterpreter.cpp:139
lldb::SBCommandInterpreter::AddMultiwordCommand
lldb::SBCommand AddMultiwordCommand(const char *name, const char *help)
Definition: SBCommandInterpreter.cpp:539
lldb::CommandArgumentType
CommandArgumentType
Definition: lldb-enumerations.h:515
lldb::SBDebugger
Definition: SBDebugger.h:34
lldb::ReturnStatus
ReturnStatus
Command Return Status Types.
Definition: lldb-enumerations.h:258
lldb::SBCommandInterpreter::SourceInitFileInCurrentWorkingDirectory
void SourceInitFileInCurrentWorkingDirectory(lldb::SBCommandReturnObject &result)
Definition: SBCommandInterpreter.cpp:469
lldb::SBCommand::GetHelpLong
const char * GetHelpLong()
Definition: SBCommandInterpreter.cpp:611
lldb::SBCommandInterpreter::eBroadcastBitThreadShouldExit
@ eBroadcastBitThreadShouldExit
Definition: SBCommandInterpreter.h:22
lldb::SBCommandInterpreter::AliasExists
bool AliasExists(const char *cmd)
Definition: SBCommandInterpreter.cpp:120
lldb::SBCommandInterpreter::HasAliases
bool HasAliases()
Definition: SBCommandInterpreter.cpp:324
lldb::SBCommandInterpreter::GetBroadcaster
lldb::SBBroadcaster GetBroadcaster()
Definition: SBCommandInterpreter.cpp:485
lldb::SBCommandInterpreter::eBroadcastBitAsynchronousErrorData
@ eBroadcastBitAsynchronousErrorData
Definition: SBCommandInterpreter.h:26
lldb::SBCommandInterpreter::ref
lldb_private::CommandInterpreter & ref()
Definition: SBCommandInterpreter.cpp:420
lldb::SBCommandInterpreter::HasCustomQuitExitCode
bool HasCustomQuitExitCode()
Returns true if the user has called the 'quit' command with a custom exit code.
Definition: SBCommandInterpreter.cpp:389
lldb::SBCommandInterpreter::GetArgumentTypeAsCString
static const char * GetArgumentTypeAsCString(const lldb::CommandArgumentType arg_type)
Definition: SBCommandInterpreter.cpp:499
lldb_private::CommandInterpreter
Definition: CommandInterpreter.h:214
SBDebugger.h
lldb::SBCommandInterpreter::SBCommandInterpreter
SBCommandInterpreter(const lldb::SBCommandInterpreter &rhs)
Definition: SBCommandInterpreter.cpp:88
lldb::SBCommand::SetHelpLong
void SetHelpLong(const char *)
Definition: SBCommandInterpreter.cpp:625
lldb::SBCommand
Definition: SBCommandInterpreter.h:293
lldb::SBCommandInterpreter::eBroadcastBitResetPrompt
@ eBroadcastBitResetPrompt
Definition: SBCommandInterpreter.h:23
lldb::SBCommandInterpreter::CommandExists
bool CommandExists(const char *cmd)
Definition: SBCommandInterpreter.cpp:113
lldb::SBCommandInterpreter::SourceInitFileInGlobalDirectory
void SourceInitFileInGlobalDirectory(lldb::SBCommandReturnObject &result)
Definition: SBCommandInterpreter.cpp:430
lldb::SBCommand::GetHelp
const char * GetHelp()
Definition: SBCommandInterpreter.cpp:604
lldb::SBCommandInterpreter::HandleCompletion
int HandleCompletion(const char *current_line, const char *cursor, const char *last_char, int match_start_point, int max_return_elements, lldb::SBStringList &matches)
Definition: SBCommandInterpreter.cpp:212
lldb::SBCommand::AddCommand
lldb::SBCommand AddCommand(const char *name, lldb::SBCommandPluginInterface *impl, const char *help=nullptr)
Add a new subcommand to the lldb::SBCommand.
Definition: SBCommandInterpreter.cpp:649
lldb::SBCommandInterpreter::AddCommand
lldb::SBCommand AddCommand(const char *name, lldb::SBCommandPluginInterface *impl, const char *help)
Add a new command to the lldb::CommandInterpreter.
Definition: SBCommandInterpreter.cpp:552
lldb::SBCommandInterpreter::HasAliasOptions
bool HasAliasOptions()
Definition: SBCommandInterpreter.cpp:330
uint32_t
lldb::SBCommandInterpreter::WasInterrupted
bool WasInterrupted() const
Definition: SBCommandInterpreter.cpp:133
lldb::SBCommandInterpreter::ResolveCommand
void ResolveCommand(const char *command_line, SBCommandReturnObject &result)
Resolve the command just as HandleCommand would, expanding abbreviations and aliases.
Definition: SBCommandInterpreter.cpp:405
lldb::SBCommandInterpreter::HandleCommandsFromFile
void HandleCommandsFromFile(lldb::SBFileSpec &file, lldb::SBExecutionContext &override_context, lldb::SBCommandInterpreterRunOptions &options, lldb::SBCommandReturnObject result)
Definition: SBCommandInterpreter.cpp:184
lldb::SBCommandInterpreter::eBroadcastBitQuitCommandReceived
@ eBroadcastBitQuitCommandReceived
Definition: SBCommandInterpreter.h:24
lldb::SBCommandInterpreter::operator=
const lldb::SBCommandInterpreter & operator=(const lldb::SBCommandInterpreter &rhs)
Definition: SBCommandInterpreter.cpp:96
lldb::SBCommand::SetHelp
void SetHelp(const char *)
Definition: SBCommandInterpreter.cpp:618
lldb::SBCommandInterpreter::GetArgumentDescriptionAsCString
static const char * GetArgumentDescriptionAsCString(const lldb::CommandArgumentType arg_type)
Definition: SBCommandInterpreter.cpp:506
lldb::SBFileSpec
Definition: SBFileSpec.h:16
lldb::SBCommand::SBCommand
SBCommand()
Definition: SBCommandInterpreter.cpp:584
lldb::CommandOverrideCallback
bool(* CommandOverrideCallback)(void *baton, const char **argv)
Definition: lldb-types.h:71
lldb::SBCommandInterpreter::reset
void reset(lldb_private::CommandInterpreter *)
Definition: SBCommandInterpreter.cpp:425
lldb::SBCommandPluginInterface::~SBCommandPluginInterface
virtual ~SBCommandPluginInterface()=default
lldb::SBBroadcaster
Definition: SBBroadcaster.h:16
lldb::SBCommandInterpreter::HandleCompletionWithDescriptions
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)
Definition: SBCommandInterpreter.cpp:224
lldb::SBCommandInterpreterRunOptions
Definition: SBCommandInterpreterRunOptions.h:23
lldb::SBCommandInterpreter::SetPromptOnQuit
void SetPromptOnQuit(bool b)
Definition: SBCommandInterpreter.cpp:375
lldb::SBCommandInterpreter::EventIsCommandInterpreterEvent
static bool EventIsCommandInterpreterEvent(const lldb::SBEvent &event)
Definition: SBCommandInterpreter.cpp:513
lldb::SBCommandInterpreter::SetCommandOverrideCallback
bool SetCommandOverrideCallback(const char *command_name, lldb::CommandOverrideCallback callback, void *baton)
Definition: SBCommandInterpreter.cpp:521
lldb::SBCommand::GetName
const char * GetName()
Definition: SBCommandInterpreter.cpp:598
lldb::SBCommandInterpreter::m_opaque_ptr
lldb_private::CommandInterpreter * m_opaque_ptr
Definition: SBCommandInterpreter.h:280
lldb
Definition: SBAddress.h:15
lldb::SBCommand::IsValid
bool IsValid()
Definition: SBCommandInterpreter.cpp:588
lldb::SBCommandPluginInterface::DoExecute
virtual bool DoExecute(lldb::SBDebugger, char **, lldb::SBCommandReturnObject &)
Definition: SBCommandInterpreter.h:287
lldb::SBCommandInterpreter::IsActive
bool IsActive()
Return true if the command interpreter is the active IO handler.
Definition: SBCommandInterpreter.cpp:127