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#include "lldb/API/SBStructuredData.h"
17
18namespace lldb_private {
19class CommandPluginInterfaceImplementation;
20}
21
22namespace lldb {
23
24class SBCommandInterpreter {
25public:
26 enum {
27 eBroadcastBitThreadShouldExit = (1 << 0),
28 eBroadcastBitResetPrompt = (1 << 1),
29 eBroadcastBitQuitCommandReceived = (1 << 2), // User entered quit
30 eBroadcastBitAsynchronousOutputData = (1 << 3),
31 eBroadcastBitAsynchronousErrorData = (1 << 4)
32 };
33
34 SBCommandInterpreter();
35 SBCommandInterpreter(const lldb::SBCommandInterpreter &rhs);
36
37 ~SBCommandInterpreter();
38
39 const lldb::SBCommandInterpreter &
40 operator=(const lldb::SBCommandInterpreter &rhs);
41
42 static const char *
43 GetArgumentTypeAsCString(const lldb::CommandArgumentType arg_type);
44
45 static const char *
46 GetArgumentDescriptionAsCString(const lldb::CommandArgumentType arg_type);
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
84 lldb::SBBroadcaster GetBroadcaster();
85
86 static const char *GetBroadcasterClass();
87
88 bool HasCommands();
89
90 bool HasAliases();
91
92 bool HasAliasOptions();
93
94 bool IsInteractive();
95
96 lldb::SBProcess GetProcess();
97
98 lldb::SBDebugger GetDebugger();
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,
122 lldb::SBCommandPluginInterface *impl,
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,
149 lldb::SBCommandPluginInterface *impl,
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,
179 lldb::SBCommandPluginInterface *impl,
180 const char *help, const char *syntax,
181 const char *auto_repeat_command);
182 void SourceInitFileInGlobalDirectory(lldb::SBCommandReturnObject &result);
183#endif
184
185
186 void SourceInitFileInHomeDirectory(lldb::SBCommandReturnObject &result);
187 void SourceInitFileInHomeDirectory(lldb::SBCommandReturnObject &result,
188 bool is_repl);
189
190 void
191 SourceInitFileInCurrentWorkingDirectory(lldb::SBCommandReturnObject &result);
192
193 lldb::ReturnStatus HandleCommand(const char *command_line,
194 lldb::SBCommandReturnObject &result,
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
202 void HandleCommandsFromFile(lldb::SBFileSpec &file,
203 lldb::SBExecutionContext &override_context,
204 lldb::SBCommandInterpreterRunOptions &options,
205 lldb::SBCommandReturnObject result);
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
237 int HandleCompletionWithDescriptions(
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#ifndef SWIG
269 bool SetCommandOverrideCallback(const char *command_name,
270 lldb::CommandOverrideCallback callback,
271 void *baton);
272#endif
273
274 /// Return true if the command interpreter is the active IO handler.
275 ///
276 /// This indicates that any input coming into the debugger handles will
277 /// go to the command interpreter and will result in LLDB command line
278 /// commands being executed.
279 bool IsActive();
280
281 /// Get the string that needs to be written to the debugger stdin file
282 /// handle when a control character is typed.
283 ///
284 /// Some GUI programs will intercept "control + char" sequences and want
285 /// to have them do what normally would happen when using a real
286 /// terminal, so this function allows GUI programs to emulate this
287 /// functionality.
288 ///
289 /// \param[in] ch
290 /// The character that was typed along with the control key
291 ///
292 /// \return
293 /// The string that should be written into the file handle that is
294 /// feeding the input stream for the debugger, or nullptr if there is
295 /// no string for this control key.
296 const char *GetIOHandlerControlSequence(char ch);
297
298 bool GetPromptOnQuit();
299
300 void SetPromptOnQuit(bool b);
301
302 /// Sets whether the command interpreter should allow custom exit codes
303 /// for the 'quit' command.
304 void AllowExitCodeOnQuit(bool allow);
305
306 /// Returns true if the user has called the 'quit' command with a custom exit
307 /// code.
308 bool HasCustomQuitExitCode();
309
310 /// Returns the exit code that the user has specified when running the
311 /// 'quit' command. Returns 0 if the user hasn't called 'quit' at all or
312 /// without a custom exit code.
313 int GetQuitStatus();
314
315 /// Resolve the command just as HandleCommand would, expanding abbreviations
316 /// and aliases. If successful, result->GetOutput has the full expansion.
317 void ResolveCommand(const char *command_line, SBCommandReturnObject &result);
318
319 SBStructuredData GetStatistics();
320
321protected:
322 friend class lldb_private::CommandPluginInterfaceImplementation;
323
324 /// Access using SBDebugger::GetCommandInterpreter();
325 SBCommandInterpreter(lldb_private::CommandInterpreter *interpreter_ptr);
326 lldb_private::CommandInterpreter &ref();
327
328 lldb_private::CommandInterpreter *get();
329
330 void reset(lldb_private::CommandInterpreter *);
331
332private:
333 friend class SBDebugger;
334
335 lldb_private::CommandInterpreter *m_opaque_ptr;
336};
337
338#ifndef SWIG
339class SBCommandPluginInterface {
340public:
341 virtual ~SBCommandPluginInterface() = default;
342
343 virtual bool DoExecute(lldb::SBDebugger /*debugger*/, char ** /*command*/,
344 lldb::SBCommandReturnObject & /*result*/) {
345 return false;
346 }
347};
348
349class SBCommand {
350public:
351 SBCommand();
352
353 explicit operator bool() const;
354
355 bool IsValid();
356
357 const char *GetName();
358
359 const char *GetHelp();
360
361 const char *GetHelpLong();
362
363 void SetHelp(const char *);
364
365 void SetHelpLong(const char *);
366
367 uint32_t GetFlags();
368
369 void SetFlags(uint32_t flags);
370
371 lldb::SBCommand AddMultiwordCommand(const char *name,
372 const char *help = nullptr);
373
374 /// Add a new subcommand to the lldb::SBCommand.
375 ///
376 /// The new command won't support autorepeat. If you need this functionality,
377 /// use the override of this function that accepts the \a auto_repeat
378 /// parameter.
379 ///
380 /// \param[in] name
381 /// The name of the command.
382 ///
383 /// \param[in] impl
384 /// The handler of this command.
385 ///
386 /// \param[in] help
387 /// The general description to show as part of the help message of this
388 /// command.
389 ///
390 /// \return
391 /// A lldb::SBCommand representing the newly created command.
392 lldb::SBCommand AddCommand(const char *name,
393 lldb::SBCommandPluginInterface *impl,
394 const char *help = nullptr);
395
396 /// Add a new subcommand to the lldb::SBCommand.
397 ///
398 /// The new command won't support autorepeat. If you need this functionality,
399 /// use the override of this function that accepts the \a auto_repeat_command
400 /// parameter.
401 ///
402 /// \param[in] name
403 /// The name of the command.
404 ///
405 /// \param[in] impl
406 /// The handler of this command.
407 ///
408 /// \param[in] help
409 /// The general description to show as part of the help message of this
410 /// command.
411 ///
412 /// \param[in] syntax
413 /// The syntax to show as part of the help message of this command. This
414 /// could include a description of the different arguments and flags this
415 /// command accepts.
416 ///
417 /// \return
418 /// A lldb::SBCommand representing the newly created command.
419 lldb::SBCommand AddCommand(const char *name,
420 lldb::SBCommandPluginInterface *impl,
421 const char *help, const char *syntax);
422
423 /// Add a new subcommand to the lldb::SBCommand.
424 ///
425 /// The new command won't support autorepeat. If you need this functionality,
426 /// use the override of this function that accepts the \a auto_repeat_command
427 /// parameter.
428 ///
429 /// \param[in] name
430 /// The name of the command.
431 ///
432 /// \param[in] impl
433 /// The handler of this command.
434 ///
435 /// \param[in] help
436 /// The general description to show as part of the help message of this
437 /// command.
438 ///
439 /// \param[in] syntax
440 /// The syntax to show as part of the help message of this command. This
441 /// could include a description of the different arguments and flags this
442 /// command accepts.
443 ///
444 /// \param[in] auto_repeat_command
445 /// Autorepeating is triggered when the user presses Enter successively
446 /// after executing a command. If \b nullptr is provided, the previous
447 /// exact command will be repeated. If \b "" is provided, autorepeating
448 /// is disabled. Otherwise, the provided string is used as a repeat
449 /// command.
450 ///
451 /// \return
452 /// A lldb::SBCommand representing the newly created command.
453 lldb::SBCommand AddCommand(const char *name,
454 lldb::SBCommandPluginInterface *impl,
455 const char *help, const char *syntax,
456 const char *auto_repeat_command);
457
458private:
459 friend class SBDebugger;
460 friend class SBCommandInterpreter;
461
462 SBCommand(lldb::CommandObjectSP cmd_sp);
463
464 lldb::CommandObjectSP m_opaque_sp;
465};
466#endif
467
468} // namespace lldb
469
470#endif // LLDB_API_SBCOMMANDINTERPRETER_H
471

source code of lldb/include/lldb/API/SBCommandInterpreter.h