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 | |
18 | namespace lldb_private { |
19 | class CommandPluginInterfaceImplementation; |
20 | } |
21 | |
22 | namespace lldb { |
23 | |
24 | class SBCommandInterpreter { |
25 | public: |
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 | |
321 | protected: |
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 | |
332 | private: |
333 | friend class SBDebugger; |
334 | |
335 | lldb_private::CommandInterpreter *m_opaque_ptr; |
336 | }; |
337 | |
338 | #ifndef SWIG |
339 | class SBCommandPluginInterface { |
340 | public: |
341 | virtual ~SBCommandPluginInterface() = default; |
342 | |
343 | virtual bool DoExecute(lldb::SBDebugger /*debugger*/, char ** /*command*/, |
344 | lldb::SBCommandReturnObject & /*result*/) { |
345 | return false; |
346 | } |
347 | }; |
348 | |
349 | class SBCommand { |
350 | public: |
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 | |
458 | private: |
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 | |