Coverage Report

Created: 2022-01-18 06:27

/Users/buildslave/jenkins/workspace/coverage/llvm-project/lldb/include/lldb/API/SBCommandInterpreter.h
Line
Count
Source (jump to first uncovered line)
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
19
class SBCommandInterpreter {
20
public:
21
  enum {
22
    eBroadcastBitThreadShouldExit = (1 << 0),
23
    eBroadcastBitResetPrompt = (1 << 1),
24
    eBroadcastBitQuitCommandReceived = (1 << 2), // User entered quit
25
    eBroadcastBitAsynchronousOutputData = (1 << 3),
26
    eBroadcastBitAsynchronousErrorData = (1 << 4)
27
  };
28
29
  SBCommandInterpreter(const lldb::SBCommandInterpreter &rhs);
30
31
  ~SBCommandInterpreter();
32
33
  const lldb::SBCommandInterpreter &
34
  operator=(const lldb::SBCommandInterpreter &rhs);
35
36
  static const char *
37
  GetArgumentTypeAsCString(const lldb::CommandArgumentType arg_type);
38
39
  static const char *
40
  GetArgumentDescriptionAsCString(const lldb::CommandArgumentType arg_type);
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
52
  lldb::SBBroadcaster GetBroadcaster();
53
54
  static const char *GetBroadcasterClass();
55
56
  bool HasCommands();
57
58
  bool HasAliases();
59
60
  bool HasAliasOptions();
61
62
  lldb::SBProcess GetProcess();
63
64
  lldb::SBDebugger GetDebugger();
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,
87
                             lldb::SBCommandPluginInterface *impl,
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,
114
                             lldb::SBCommandPluginInterface *impl,
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,
144
                             lldb::SBCommandPluginInterface *impl,
145
                             const char *help, const char *syntax,
146
                             const char *auto_repeat_command);
147
148
  void SourceInitFileInHomeDirectory(lldb::SBCommandReturnObject &result);
149
  void SourceInitFileInHomeDirectory(lldb::SBCommandReturnObject &result,
150
                                     bool is_repl);
151
152
  void
153
  SourceInitFileInCurrentWorkingDirectory(lldb::SBCommandReturnObject &result);
154
155
  lldb::ReturnStatus HandleCommand(const char *command_line,
156
                                   lldb::SBCommandReturnObject &result,
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
164
  void HandleCommandsFromFile(lldb::SBFileSpec &file,
165
                              lldb::SBExecutionContext &override_context,
166
                              lldb::SBCommandInterpreterRunOptions &options,
167
                              lldb::SBCommandReturnObject result);
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.
196
  int HandleCompletionWithDescriptions(
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,
214
                                  lldb::CommandOverrideCallback callback,
215
                                  void *baton);
216
217
  SBCommandInterpreter(
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:
267
  lldb_private::CommandInterpreter &ref();
268
269
  lldb_private::CommandInterpreter *get();
270
271
  void reset(lldb_private::CommandInterpreter *);
272
273
private:
274
  friend class SBDebugger;
275
276
  lldb_private::CommandInterpreter *m_opaque_ptr;
277
};
278
279
class SBCommandPluginInterface {
280
public:
281
  virtual ~SBCommandPluginInterface() = default;
282
283
  virtual bool DoExecute(lldb::SBDebugger /*debugger*/, char ** /*command*/,
284
0
                         lldb::SBCommandReturnObject & /*result*/) {
285
0
    return false;
286
0
  }
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,
333
                             lldb::SBCommandPluginInterface *impl,
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,
360
                             lldb::SBCommandPluginInterface *impl,
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,
394
                             lldb::SBCommandPluginInterface *impl,
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