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_SBCommandInterpreter_h_
10 #define LLDB_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 LLDB_API SBCommandInterpreterRunOptions {
20   friend class SBDebugger;
21   friend class SBCommandInterpreter;
22 
23 public:
24   SBCommandInterpreterRunOptions();
25   ~SBCommandInterpreterRunOptions();
26 
27   bool GetStopOnContinue() const;
28 
29   void SetStopOnContinue(bool);
30 
31   bool GetStopOnError() const;
32 
33   void SetStopOnError(bool);
34 
35   bool GetStopOnCrash() const;
36 
37   void SetStopOnCrash(bool);
38 
39   bool GetEchoCommands() const;
40 
41   void SetEchoCommands(bool);
42 
43   bool GetEchoCommentCommands() const;
44 
45   void SetEchoCommentCommands(bool echo);
46 
47   bool GetPrintResults() const;
48 
49   void SetPrintResults(bool);
50 
51   bool GetAddToHistory() const;
52 
53   void SetAddToHistory(bool);
54 
55 private:
56   lldb_private::CommandInterpreterRunOptions *get() const;
57 
58   lldb_private::CommandInterpreterRunOptions &ref() const;
59 
60   // This is set in the constructor and will always be valid.
61   mutable std::unique_ptr<lldb_private::CommandInterpreterRunOptions>
62       m_opaque_up;
63 };
64 
65 class SBCommandInterpreter {
66 public:
67   enum {
68     eBroadcastBitThreadShouldExit = (1 << 0),
69     eBroadcastBitResetPrompt = (1 << 1),
70     eBroadcastBitQuitCommandReceived = (1 << 2), // User entered quit
71     eBroadcastBitAsynchronousOutputData = (1 << 3),
72     eBroadcastBitAsynchronousErrorData = (1 << 4)
73   };
74 
75   SBCommandInterpreter(const lldb::SBCommandInterpreter &rhs);
76 
77   ~SBCommandInterpreter();
78 
79   const lldb::SBCommandInterpreter &
80   operator=(const lldb::SBCommandInterpreter &rhs);
81 
82   static const char *
83   GetArgumentTypeAsCString(const lldb::CommandArgumentType arg_type);
84 
85   static const char *
86   GetArgumentDescriptionAsCString(const lldb::CommandArgumentType arg_type);
87 
88   static bool EventIsCommandInterpreterEvent(const lldb::SBEvent &event);
89 
90   explicit operator bool() const;
91 
92   bool IsValid() const;
93 
94   bool CommandExists(const char *cmd);
95 
96   bool AliasExists(const char *cmd);
97 
98   lldb::SBBroadcaster GetBroadcaster();
99 
100   static const char *GetBroadcasterClass();
101 
102   bool HasCommands();
103 
104   bool HasAliases();
105 
106   bool HasAliasOptions();
107 
108   lldb::SBProcess GetProcess();
109 
110   lldb::SBDebugger GetDebugger();
111 
112   lldb::SBCommand AddMultiwordCommand(const char *name, const char *help);
113 
114   lldb::SBCommand AddCommand(const char *name,
115                              lldb::SBCommandPluginInterface *impl,
116                              const char *help);
117 
118   lldb::SBCommand AddCommand(const char *name,
119                              lldb::SBCommandPluginInterface *impl,
120                              const char *help, const char *syntax);
121 
122   void SourceInitFileInHomeDirectory(lldb::SBCommandReturnObject &result);
123 
124   void
125   SourceInitFileInCurrentWorkingDirectory(lldb::SBCommandReturnObject &result);
126 
127   lldb::ReturnStatus HandleCommand(const char *command_line,
128                                    lldb::SBCommandReturnObject &result,
129                                    bool add_to_history = false);
130 
131   lldb::ReturnStatus HandleCommand(const char *command_line,
132                                    SBExecutionContext &exe_ctx,
133                                    SBCommandReturnObject &result,
134                                    bool add_to_history = false);
135 
136   void HandleCommandsFromFile(lldb::SBFileSpec &file,
137                               lldb::SBExecutionContext &override_context,
138                               lldb::SBCommandInterpreterRunOptions &options,
139                               lldb::SBCommandReturnObject result);
140 
141   // The pointer based interface is not useful in SWIG, since the cursor &
142   // last_char arguments are string pointers INTO current_line and you can't do
143   // that in a scripting language interface in general...
144 
145   // In either case, the way this works is that the you give it a line and
146   // cursor position in the line.  The function will return the number of
147   // completions.  The matches list will contain number_of_completions + 1
148   // elements.  The first element is the common substring after the cursor
149   // position for all the matches.  The rest of the elements are the matches.
150   // The first element is useful if you are emulating the common shell behavior
151   // where the tab completes to the string that is common among all the
152   // matches, then you should first check if the first element is non-empty,
153   // and if so just insert it and move the cursor to the end of the insertion.
154   // The next tab will return an empty common substring, and a list of choices
155   // (if any), at which point you should display the choices and let the user
156   // type further to disambiguate.
157 
158   int HandleCompletion(const char *current_line, const char *cursor,
159                        const char *last_char, int match_start_point,
160                        int max_return_elements, lldb::SBStringList &matches);
161 
162   int HandleCompletion(const char *current_line, uint32_t cursor_pos,
163                        int match_start_point, int max_return_elements,
164                        lldb::SBStringList &matches);
165 
166   // Same as HandleCompletion, but also fills out `descriptions` with
167   // descriptions for each match.
168   int HandleCompletionWithDescriptions(
169       const char *current_line, const char *cursor, const char *last_char,
170       int match_start_point, int max_return_elements,
171       lldb::SBStringList &matches, lldb::SBStringList &descriptions);
172 
173   int HandleCompletionWithDescriptions(const char *current_line,
174                                        uint32_t cursor_pos,
175                                        int match_start_point,
176                                        int max_return_elements,
177                                        lldb::SBStringList &matches,
178                                        lldb::SBStringList &descriptions);
179 
180   bool WasInterrupted() const;
181 
182   // Catch commands before they execute by registering a callback that will get
183   // called when the command gets executed. This allows GUI or command line
184   // interfaces to intercept a command and stop it from happening
185   bool SetCommandOverrideCallback(const char *command_name,
186                                   lldb::CommandOverrideCallback callback,
187                                   void *baton);
188 
189   SBCommandInterpreter(
190       lldb_private::CommandInterpreter *interpreter_ptr =
191           nullptr); // Access using SBDebugger::GetCommandInterpreter();
192 
193   /// Return true if the command interpreter is the active IO handler.
194   ///
195   /// This indicates that any input coming into the debugger handles will
196   /// go to the command interpreter and will result in LLDB command line
197   /// commands being executed.
198   bool IsActive();
199 
200   /// Get the string that needs to be written to the debugger stdin file
201   /// handle when a control character is typed.
202   ///
203   /// Some GUI programs will intercept "control + char" sequences and want
204   /// to have them do what normally would happen when using a real
205   /// terminal, so this function allows GUI programs to emulate this
206   /// functionality.
207   ///
208   /// \param[in] ch
209   ///     The character that was typed along with the control key
210   ///
211   /// \return
212   ///     The string that should be written into the file handle that is
213   ///     feeding the input stream for the debugger, or nullptr if there is
214   ///     no string for this control key.
215   const char *GetIOHandlerControlSequence(char ch);
216 
217   bool GetPromptOnQuit();
218 
219   void SetPromptOnQuit(bool b);
220 
221   /// Sets whether the command interpreter should allow custom exit codes
222   /// for the 'quit' command.
223   void AllowExitCodeOnQuit(bool allow);
224 
225   /// Returns true if the user has called the 'quit' command with a custom exit
226   /// code.
227   bool HasCustomQuitExitCode();
228 
229   /// Returns the exit code that the user has specified when running the
230   /// 'quit' command. Returns 0 if the user hasn't called 'quit' at all or
231   /// without a custom exit code.
232   int GetQuitStatus();
233 
234   /// Resolve the command just as HandleCommand would, expanding abbreviations
235   /// and aliases.  If successful, result->GetOutput has the full expansion.
236   void ResolveCommand(const char *command_line, SBCommandReturnObject &result);
237 
238 protected:
239   lldb_private::CommandInterpreter &ref();
240 
241   lldb_private::CommandInterpreter *get();
242 
243   void reset(lldb_private::CommandInterpreter *);
244 
245 private:
246   friend class SBDebugger;
247 
248   lldb_private::CommandInterpreter *m_opaque_ptr;
249 };
250 
251 class SBCommandPluginInterface {
252 public:
253   virtual ~SBCommandPluginInterface() = default;
254 
255   virtual bool DoExecute(lldb::SBDebugger /*debugger*/, char ** /*command*/,
256                          lldb::SBCommandReturnObject & /*result*/) {
257     return false;
258   }
259 };
260 
261 class SBCommand {
262 public:
263   SBCommand();
264 
265   explicit operator bool() const;
266 
267   bool IsValid();
268 
269   const char *GetName();
270 
271   const char *GetHelp();
272 
273   const char *GetHelpLong();
274 
275   void SetHelp(const char *);
276 
277   void SetHelpLong(const char *);
278 
279   uint32_t GetFlags();
280 
281   void SetFlags(uint32_t flags);
282 
283   lldb::SBCommand AddMultiwordCommand(const char *name,
284                                       const char *help = nullptr);
285 
286   lldb::SBCommand AddCommand(const char *name,
287                              lldb::SBCommandPluginInterface *impl,
288                              const char *help = nullptr);
289 
290   lldb::SBCommand AddCommand(const char *name,
291                              lldb::SBCommandPluginInterface *impl,
292                              const char *help, const char *syntax);
293 
294 private:
295   friend class SBDebugger;
296   friend class SBCommandInterpreter;
297 
298   SBCommand(lldb::CommandObjectSP cmd_sp);
299 
300   lldb::CommandObjectSP m_opaque_sp;
301 };
302 
303 } // namespace lldb
304 
305 #endif // LLDB_SBCommandInterpreter_h_
306