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