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 
63 
65 
66  lldb::SBCommand AddMultiwordCommand(const char *name, const char *help);
67 
68  /// Add a new command to the lldb::CommandInterpreter.
69  ///
70  /// The new command won't support autorepeat. If you need this functionality,
71  /// use the override of this function that accepts the \a auto_repeat_command
72  /// parameter.
73  ///
74  /// \param[in] name
75  /// The name of the command.
76  ///
77  /// \param[in] impl
78  /// The handler of this command.
79  ///
80  /// \param[in] help
81  /// The general description to show as part of the help message of this
82  /// command.
83  ///
84  /// \return
85  /// A lldb::SBCommand representing the newly created command.
86  lldb::SBCommand AddCommand(const char *name,
88  const char *help);
89 
90  /// Add a new command to the lldb::CommandInterpreter.
91  ///
92  /// The new command won't support autorepeat. If you need this functionality,
93  /// use the override of this function that accepts the \a auto_repeat_command
94  /// parameter.
95  ///
96  /// \param[in] name
97  /// The name of the command.
98  ///
99  /// \param[in] impl
100  /// The handler of this command.
101  ///
102  /// \param[in] help
103  /// The general description to show as part of the help message of this
104  /// command.
105  ///
106  /// \param[in] syntax
107  /// The syntax to show as part of the help message of this command. This
108  /// could include a description of the different arguments and flags this
109  /// command accepts.
110  ///
111  /// \return
112  /// A lldb::SBCommand representing the newly created command.
113  lldb::SBCommand AddCommand(const char *name,
115  const char *help, const char *syntax);
116 
117  /// Add a new command to the lldb::CommandInterpreter.
118  ///
119  /// \param[in] name
120  /// The name of the command.
121  ///
122  /// \param[in] impl
123  /// The handler of this command.
124  ///
125  /// \param[in] help
126  /// The general description to show as part of the help message of this
127  /// command.
128  ///
129  /// \param[in] syntax
130  /// The syntax to show as part of the help message of this command. This
131  /// could include a description of the different arguments and flags this
132  /// command accepts.
133  ///
134  /// \param[in] auto_repeat_command
135  /// Autorepeating is triggered when the user presses Enter successively
136  /// after executing a command. If \b nullptr is provided, the previous
137  /// exact command will be repeated. If \b "" is provided, autorepeating
138  /// is disabled. Otherwise, the provided string is used as a repeat
139  /// command.
140  ///
141  /// \return
142  /// A lldb::SBCommand representing the newly created command.
143  lldb::SBCommand AddCommand(const char *name,
145  const char *help, const char *syntax,
146  const char *auto_repeat_command);
147 
150  bool is_repl);
151 
152  void
154 
155  lldb::ReturnStatus HandleCommand(const char *command_line,
157  bool add_to_history = false);
158 
159  lldb::ReturnStatus HandleCommand(const char *command_line,
160  SBExecutionContext &exe_ctx,
161  SBCommandReturnObject &result,
162  bool add_to_history = false);
163 
165  lldb::SBExecutionContext &override_context,
168 
169  // The pointer based interface is not useful in SWIG, since the cursor &
170  // last_char arguments are string pointers INTO current_line and you can't do
171  // that in a scripting language interface in general...
172 
173  // In either case, the way this works is that the you give it a line and
174  // cursor position in the line. The function will return the number of
175  // completions. The matches list will contain number_of_completions + 1
176  // elements. The first element is the common substring after the cursor
177  // position for all the matches. The rest of the elements are the matches.
178  // The first element is useful if you are emulating the common shell behavior
179  // where the tab completes to the string that is common among all the
180  // matches, then you should first check if the first element is non-empty,
181  // and if so just insert it and move the cursor to the end of the insertion.
182  // The next tab will return an empty common substring, and a list of choices
183  // (if any), at which point you should display the choices and let the user
184  // type further to disambiguate.
185 
186  int HandleCompletion(const char *current_line, const char *cursor,
187  const char *last_char, int match_start_point,
188  int max_return_elements, lldb::SBStringList &matches);
189 
190  int HandleCompletion(const char *current_line, uint32_t cursor_pos,
191  int match_start_point, int max_return_elements,
192  lldb::SBStringList &matches);
193 
194  // Same as HandleCompletion, but also fills out `descriptions` with
195  // descriptions for each match.
197  const char *current_line, const char *cursor, const char *last_char,
198  int match_start_point, int max_return_elements,
199  lldb::SBStringList &matches, lldb::SBStringList &descriptions);
200 
201  int HandleCompletionWithDescriptions(const char *current_line,
202  uint32_t cursor_pos,
203  int match_start_point,
204  int max_return_elements,
205  lldb::SBStringList &matches,
206  lldb::SBStringList &descriptions);
207 
208  bool WasInterrupted() const;
209 
210  // Catch commands before they execute by registering a callback that will get
211  // called when the command gets executed. This allows GUI or command line
212  // interfaces to intercept a command and stop it from happening
213  bool SetCommandOverrideCallback(const char *command_name,
215  void *baton);
216 
218  lldb_private::CommandInterpreter *interpreter_ptr =
219  nullptr); // Access using SBDebugger::GetCommandInterpreter();
220 
221  /// Return true if the command interpreter is the active IO handler.
222  ///
223  /// This indicates that any input coming into the debugger handles will
224  /// go to the command interpreter and will result in LLDB command line
225  /// commands being executed.
226  bool IsActive();
227 
228  /// Get the string that needs to be written to the debugger stdin file
229  /// handle when a control character is typed.
230  ///
231  /// Some GUI programs will intercept "control + char" sequences and want
232  /// to have them do what normally would happen when using a real
233  /// terminal, so this function allows GUI programs to emulate this
234  /// functionality.
235  ///
236  /// \param[in] ch
237  /// The character that was typed along with the control key
238  ///
239  /// \return
240  /// The string that should be written into the file handle that is
241  /// feeding the input stream for the debugger, or nullptr if there is
242  /// no string for this control key.
243  const char *GetIOHandlerControlSequence(char ch);
244 
245  bool GetPromptOnQuit();
246 
247  void SetPromptOnQuit(bool b);
248 
249  /// Sets whether the command interpreter should allow custom exit codes
250  /// for the 'quit' command.
251  void AllowExitCodeOnQuit(bool allow);
252 
253  /// Returns true if the user has called the 'quit' command with a custom exit
254  /// code.
255  bool HasCustomQuitExitCode();
256 
257  /// Returns the exit code that the user has specified when running the
258  /// 'quit' command. Returns 0 if the user hasn't called 'quit' at all or
259  /// without a custom exit code.
260  int GetQuitStatus();
261 
262  /// Resolve the command just as HandleCommand would, expanding abbreviations
263  /// and aliases. If successful, result->GetOutput has the full expansion.
264  void ResolveCommand(const char *command_line, SBCommandReturnObject &result);
265 
266 protected:
268 
270 
272 
273 private:
274  friend class SBDebugger;
275 
277 };
278 
280 public:
281  virtual ~SBCommandPluginInterface() = default;
282 
283  virtual bool DoExecute(lldb::SBDebugger /*debugger*/, char ** /*command*/,
284  lldb::SBCommandReturnObject & /*result*/) {
285  return false;
286  }
287 };
288 
289 class SBCommand {
290 public:
291  SBCommand();
292 
293  explicit operator bool() const;
294 
295  bool IsValid();
296 
297  const char *GetName();
298 
299  const char *GetHelp();
300 
301  const char *GetHelpLong();
302 
303  void SetHelp(const char *);
304 
305  void SetHelpLong(const char *);
306 
307  uint32_t GetFlags();
308 
309  void SetFlags(uint32_t flags);
310 
311  lldb::SBCommand AddMultiwordCommand(const char *name,
312  const char *help = nullptr);
313 
314  /// Add a new subcommand to the lldb::SBCommand.
315  ///
316  /// The new command won't support autorepeat. If you need this functionality,
317  /// use the override of this function that accepts the \a auto_repeat
318  /// parameter.
319  ///
320  /// \param[in] name
321  /// The name of the command.
322  ///
323  /// \param[in] impl
324  /// The handler of this command.
325  ///
326  /// \param[in] help
327  /// The general description to show as part of the help message of this
328  /// command.
329  ///
330  /// \return
331  /// A lldb::SBCommand representing the newly created command.
332  lldb::SBCommand AddCommand(const char *name,
334  const char *help = nullptr);
335 
336  /// Add a new subcommand to the lldb::SBCommand.
337  ///
338  /// The new command won't support autorepeat. If you need this functionality,
339  /// use the override of this function that accepts the \a auto_repeat_command
340  /// parameter.
341  ///
342  /// \param[in] name
343  /// The name of the command.
344  ///
345  /// \param[in] impl
346  /// The handler of this command.
347  ///
348  /// \param[in] help
349  /// The general description to show as part of the help message of this
350  /// command.
351  ///
352  /// \param[in] syntax
353  /// The syntax to show as part of the help message of this command. This
354  /// could include a description of the different arguments and flags this
355  /// command accepts.
356  ///
357  /// \return
358  /// A lldb::SBCommand representing the newly created command.
359  lldb::SBCommand AddCommand(const char *name,
361  const char *help, const char *syntax);
362 
363  /// Add a new subcommand to the lldb::SBCommand.
364  ///
365  /// The new command won't support autorepeat. If you need this functionality,
366  /// use the override of this function that accepts the \a auto_repeat_command
367  /// parameter.
368  ///
369  /// \param[in] name
370  /// The name of the command.
371  ///
372  /// \param[in] impl
373  /// The handler of this command.
374  ///
375  /// \param[in] help
376  /// The general description to show as part of the help message of this
377  /// command.
378  ///
379  /// \param[in] syntax
380  /// The syntax to show as part of the help message of this command. This
381  /// could include a description of the different arguments and flags this
382  /// command accepts.
383  ///
384  /// \param[in] auto_repeat_command
385  /// Autorepeating is triggered when the user presses Enter successively
386  /// after executing a command. If \b nullptr is provided, the previous
387  /// exact command will be repeated. If \b "" is provided, autorepeating
388  /// is disabled. Otherwise, the provided string is used as a repeat
389  /// command.
390  ///
391  /// \return
392  /// A lldb::SBCommand representing the newly created command.
393  lldb::SBCommand AddCommand(const char *name,
395  const char *help, const char *syntax,
396  const char *auto_repeat_command);
397 
398 private:
399  friend class SBDebugger;
400  friend class SBCommandInterpreter;
401 
402  SBCommand(lldb::CommandObjectSP cmd_sp);
403 
404  lldb::CommandObjectSP m_opaque_sp;
405 };
406 
407 } // namespace lldb
408 
409 #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:454
lldb::SBCommandPluginInterface
Definition: SBCommandInterpreter.h:279
lldb::SBCommandInterpreter::~SBCommandInterpreter
~SBCommandInterpreter()
lldb::SBCommandInterpreter::get
lldb_private::CommandInterpreter * get()
Definition: SBCommandInterpreter.cpp:442
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:420
lldb::SBCommandInterpreter
Definition: SBCommandInterpreter.h:19
lldb::SBCommand::AddMultiwordCommand
lldb::SBCommand AddMultiwordCommand(const char *name, const char *help=nullptr)
Definition: SBCommandInterpreter.cpp:676
lldb::SBCommandInterpreter::AllowExitCodeOnQuit
void AllowExitCodeOnQuit(bool allow)
Sets whether the command interpreter should allow custom exit codes for the 'quit' command.
Definition: SBCommandInterpreter.cpp:403
lldb::SBCommandInterpreter::HasCommands
bool HasCommands()
Definition: SBCommandInterpreter.cpp:344
lldb::SBCommandInterpreter::GetPromptOnQuit
bool GetPromptOnQuit()
Definition: SBCommandInterpreter.cpp:390
lldb::SBCommand::SetFlags
void SetFlags(uint32_t flags)
Definition: SBCommandInterpreter.cpp:744
lldb::SBCommandInterpreter::GetProcess
lldb::SBProcess GetProcess()
Definition: SBCommandInterpreter.cpp:362
lldb::SBCommandInterpreter::GetBroadcasterClass
static const char * GetBroadcasterClass()
Definition: SBCommandInterpreter.cpp:517
lldb::SBCommand::GetFlags
uint32_t GetFlags()
Definition: SBCommandInterpreter.cpp:738
lldb::SBEvent
Definition: SBEvent.h:21
lldb::SBProcess
Definition: SBProcess.h:23
lldb::SBCommandInterpreter::GetDebugger
lldb::SBDebugger GetDebugger()
Definition: SBCommandInterpreter.cpp:379
lldb::SBCommandInterpreter::HandleCommand
lldb::ReturnStatus HandleCommand(const char *command_line, lldb::SBCommandReturnObject &result, bool add_to_history=false)
Definition: SBCommandInterpreter.cpp:155
lldb::SBExecutionContext
Definition: SBExecutionContext.h:20
lldb::SBCommandInterpreter::IsValid
bool IsValid() const
Definition: SBCommandInterpreter.cpp:105
lldb::SBCommand::m_opaque_sp
lldb::CommandObjectSP m_opaque_sp
Definition: SBCommandInterpreter.h:404
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:143
lldb::SBCommandInterpreter::AddMultiwordCommand
lldb::SBCommand AddMultiwordCommand(const char *name, const char *help)
Definition: SBCommandInterpreter.cpp:572
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:488
lldb::SBCommand::GetHelpLong
const char * GetHelpLong()
Definition: SBCommandInterpreter.cpp:655
lldb::SBCommandInterpreter::eBroadcastBitThreadShouldExit
@ eBroadcastBitThreadShouldExit
Definition: SBCommandInterpreter.h:22
lldb::SBCommandInterpreter::AliasExists
bool AliasExists(const char *cmd)
Definition: SBCommandInterpreter.cpp:123
lldb::SBCommandInterpreter::HasAliases
bool HasAliases()
Definition: SBCommandInterpreter.cpp:350
lldb::SBCommandInterpreter::GetBroadcaster
lldb::SBBroadcaster GetBroadcaster()
Definition: SBCommandInterpreter.cpp:506
lldb::SBCommandInterpreter::eBroadcastBitAsynchronousErrorData
@ eBroadcastBitAsynchronousErrorData
Definition: SBCommandInterpreter.h:26
lldb::SBCommandInterpreter::ref
lldb_private::CommandInterpreter & ref()
Definition: SBCommandInterpreter.cpp:444
lldb::SBCommandInterpreter::HasCustomQuitExitCode
bool HasCustomQuitExitCode()
Returns true if the user has called the 'quit' command with a custom exit code.
Definition: SBCommandInterpreter.cpp:411
lldb::SBCommandInterpreter::GetArgumentTypeAsCString
static const char * GetArgumentTypeAsCString(const lldb::CommandArgumentType arg_type)
Definition: SBCommandInterpreter.cpp:524
lldb_private::CommandInterpreter
Definition: CommandInterpreter.h:214
SBDebugger.h
lldb::SBCommandInterpreter::SBCommandInterpreter
SBCommandInterpreter(const lldb::SBCommandInterpreter &rhs)
Definition: SBCommandInterpreter.cpp:86
lldb::SBCommand::SetHelpLong
void SetHelpLong(const char *)
Definition: SBCommandInterpreter.cpp:669
lldb::SBCommand
Definition: SBCommandInterpreter.h:289
lldb::SBCommandInterpreter::eBroadcastBitResetPrompt
@ eBroadcastBitResetPrompt
Definition: SBCommandInterpreter.h:23
lldb::SBCommandInterpreter::CommandExists
bool CommandExists(const char *cmd)
Definition: SBCommandInterpreter.cpp:115
lldb::SBCommand::GetHelp
const char * GetHelp()
Definition: SBCommandInterpreter.cpp:648
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:225
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:694
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:586
lldb::SBCommandInterpreter::HasAliasOptions
bool HasAliasOptions()
Definition: SBCommandInterpreter.cpp:356
uint32_t
lldb::SBCommandInterpreter::WasInterrupted
bool WasInterrupted() const
Definition: SBCommandInterpreter.cpp:137
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:427
lldb::SBCommandInterpreter::HandleCommandsFromFile
void HandleCommandsFromFile(lldb::SBFileSpec &file, lldb::SBExecutionContext &override_context, lldb::SBCommandInterpreterRunOptions &options, lldb::SBCommandReturnObject result)
Definition: SBCommandInterpreter.cpp:193
lldb::SBCommandInterpreter::eBroadcastBitQuitCommandReceived
@ eBroadcastBitQuitCommandReceived
Definition: SBCommandInterpreter.h:24
lldb::SBCommandInterpreter::operator=
const lldb::SBCommandInterpreter & operator=(const lldb::SBCommandInterpreter &rhs)
Definition: SBCommandInterpreter.cpp:95
lldb::SBCommand::SetHelp
void SetHelp(const char *)
Definition: SBCommandInterpreter.cpp:662
lldb::SBCommandInterpreter::GetArgumentDescriptionAsCString
static const char * GetArgumentDescriptionAsCString(const lldb::CommandArgumentType arg_type)
Definition: SBCommandInterpreter.cpp:533
lldb::SBFileSpec
Definition: SBFileSpec.h:16
lldb::SBCommand::SBCommand
SBCommand()
Definition: SBCommandInterpreter.cpp:628
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:449
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:240
lldb::SBCommandInterpreterRunOptions
Definition: SBCommandInterpreterRunOptions.h:23
lldb::SBCommandInterpreter::SetPromptOnQuit
void SetPromptOnQuit(bool b)
Definition: SBCommandInterpreter.cpp:396
lldb::SBCommandInterpreter::EventIsCommandInterpreterEvent
static bool EventIsCommandInterpreterEvent(const lldb::SBEvent &event)
Definition: SBCommandInterpreter.cpp:542
lldb::SBCommandInterpreter::SetCommandOverrideCallback
bool SetCommandOverrideCallback(const char *command_name, lldb::CommandOverrideCallback callback, void *baton)
Definition: SBCommandInterpreter.cpp:552
lldb::SBCommand::GetName
const char * GetName()
Definition: SBCommandInterpreter.cpp:642
lldb::SBCommandInterpreter::m_opaque_ptr
lldb_private::CommandInterpreter * m_opaque_ptr
Definition: SBCommandInterpreter.h:276
lldb
Definition: SBAddress.h:15
lldb::SBCommand::IsValid
bool IsValid()
Definition: SBCommandInterpreter.cpp:632
lldb::SBCommandPluginInterface::DoExecute
virtual bool DoExecute(lldb::SBDebugger, char **, lldb::SBCommandReturnObject &)
Definition: SBCommandInterpreter.h:283
lldb::SBCommandInterpreter::IsActive
bool IsActive()
Return true if the command interpreter is the active IO handler.
Definition: SBCommandInterpreter.cpp:131