1 //===-- SBCommandInterpreter.h ----------------------------------*- C++ -*-===//
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
7 //===----------------------------------------------------------------------===//
9 #ifndef LLDB_SBCommandInterpreter_h_
10 #define LLDB_SBCommandInterpreter_h_
14 #include "lldb/API/SBDebugger.h"
15 #include "lldb/API/SBDefines.h"
19 class LLDB_API SBCommandInterpreterRunOptions {
20 friend class SBDebugger;
21 friend class SBCommandInterpreter;
24 SBCommandInterpreterRunOptions();
25 ~SBCommandInterpreterRunOptions();
27 bool GetStopOnContinue() const;
29 void SetStopOnContinue(bool);
31 bool GetStopOnError() const;
33 void SetStopOnError(bool);
35 bool GetStopOnCrash() const;
37 void SetStopOnCrash(bool);
39 bool GetEchoCommands() const;
41 void SetEchoCommands(bool);
43 bool GetEchoCommentCommands() const;
45 void SetEchoCommentCommands(bool echo);
47 bool GetPrintResults() const;
49 void SetPrintResults(bool);
51 bool GetAddToHistory() const;
53 void SetAddToHistory(bool);
56 lldb_private::CommandInterpreterRunOptions *get() const;
58 lldb_private::CommandInterpreterRunOptions &ref() const;
60 // This is set in the constructor and will always be valid.
61 mutable std::unique_ptr<lldb_private::CommandInterpreterRunOptions>
65 class SBCommandInterpreter {
68 eBroadcastBitThreadShouldExit = (1 << 0),
69 eBroadcastBitResetPrompt = (1 << 1),
70 eBroadcastBitQuitCommandReceived = (1 << 2), // User entered quit
71 eBroadcastBitAsynchronousOutputData = (1 << 3),
72 eBroadcastBitAsynchronousErrorData = (1 << 4)
75 SBCommandInterpreter(const lldb::SBCommandInterpreter &rhs);
77 ~SBCommandInterpreter();
79 const lldb::SBCommandInterpreter &
80 operator=(const lldb::SBCommandInterpreter &rhs);
83 GetArgumentTypeAsCString(const lldb::CommandArgumentType arg_type);
86 GetArgumentDescriptionAsCString(const lldb::CommandArgumentType arg_type);
88 static bool EventIsCommandInterpreterEvent(const lldb::SBEvent &event);
90 explicit operator bool() const;
94 bool CommandExists(const char *cmd);
96 bool AliasExists(const char *cmd);
98 lldb::SBBroadcaster GetBroadcaster();
100 static const char *GetBroadcasterClass();
106 bool HasAliasOptions();
108 lldb::SBProcess GetProcess();
110 lldb::SBDebugger GetDebugger();
112 lldb::SBCommand AddMultiwordCommand(const char *name, const char *help);
114 lldb::SBCommand AddCommand(const char *name,
115 lldb::SBCommandPluginInterface *impl,
118 lldb::SBCommand AddCommand(const char *name,
119 lldb::SBCommandPluginInterface *impl,
120 const char *help, const char *syntax);
122 void SourceInitFileInHomeDirectory(lldb::SBCommandReturnObject &result);
125 SourceInitFileInCurrentWorkingDirectory(lldb::SBCommandReturnObject &result);
127 lldb::ReturnStatus HandleCommand(const char *command_line,
128 lldb::SBCommandReturnObject &result,
129 bool add_to_history = false);
131 lldb::ReturnStatus HandleCommand(const char *command_line,
132 SBExecutionContext &exe_ctx,
133 SBCommandReturnObject &result,
134 bool add_to_history = false);
136 void HandleCommandsFromFile(lldb::SBFileSpec &file,
137 lldb::SBExecutionContext &override_context,
138 lldb::SBCommandInterpreterRunOptions &options,
139 lldb::SBCommandReturnObject result);
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...
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.
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);
162 int HandleCompletion(const char *current_line, uint32_t cursor_pos,
163 int match_start_point, int max_return_elements,
164 lldb::SBStringList &matches);
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);
173 int HandleCompletionWithDescriptions(const char *current_line,
175 int match_start_point,
176 int max_return_elements,
177 lldb::SBStringList &matches,
178 lldb::SBStringList &descriptions);
180 bool WasInterrupted() const;
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,
189 SBCommandInterpreter(
190 lldb_private::CommandInterpreter *interpreter_ptr =
191 nullptr); // Access using SBDebugger::GetCommandInterpreter();
193 /// Return true if the command interpreter is the active IO handler.
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.
200 /// Get the string that needs to be written to the debugger stdin file
201 /// handle when a control character is typed.
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
209 /// The character that was typed along with the control key
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);
217 bool GetPromptOnQuit();
219 void SetPromptOnQuit(bool b);
221 /// Sets whether the command interpreter should allow custom exit codes
222 /// for the 'quit' command.
223 void AllowExitCodeOnQuit(bool allow);
225 /// Returns true if the user has called the 'quit' command with a custom exit
227 bool HasCustomQuitExitCode();
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.
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);
239 lldb_private::CommandInterpreter &ref();
241 lldb_private::CommandInterpreter *get();
243 void reset(lldb_private::CommandInterpreter *);
246 friend class SBDebugger;
248 lldb_private::CommandInterpreter *m_opaque_ptr;
251 class SBCommandPluginInterface {
253 virtual ~SBCommandPluginInterface() = default;
255 virtual bool DoExecute(lldb::SBDebugger /*debugger*/, char ** /*command*/,
256 lldb::SBCommandReturnObject & /*result*/) {
265 explicit operator bool() const;
269 const char *GetName();
271 const char *GetHelp();
273 const char *GetHelpLong();
275 void SetHelp(const char *);
277 void SetHelpLong(const char *);
281 void SetFlags(uint32_t flags);
283 lldb::SBCommand AddMultiwordCommand(const char *name,
284 const char *help = nullptr);
286 lldb::SBCommand AddCommand(const char *name,
287 lldb::SBCommandPluginInterface *impl,
288 const char *help = nullptr);
290 lldb::SBCommand AddCommand(const char *name,
291 lldb::SBCommandPluginInterface *impl,
292 const char *help, const char *syntax);
295 friend class SBDebugger;
296 friend class SBCommandInterpreter;
298 SBCommand(lldb::CommandObjectSP cmd_sp);
300 lldb::CommandObjectSP m_opaque_sp;
305 #endif // LLDB_SBCommandInterpreter_h_