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 17 namespace lldb { 18 19 class SBCommandInterpreter { 20 public: 21 enum { 22 eBroadcastBitThreadShouldExit = (1 << 0), 23 eBroadcastBitResetPrompt = (1 << 1), 24 eBroadcastBitQuitCommandReceived = (1 << 2), // User entered quit 25 eBroadcastBitAsynchronousOutputData = (1 << 3), 26 eBroadcastBitAsynchronousErrorData = (1 << 4) 27 }; 28 29 SBCommandInterpreter(const lldb::SBCommandInterpreter &rhs); 30 31 ~SBCommandInterpreter(); 32 33 const lldb::SBCommandInterpreter & 34 operator=(const lldb::SBCommandInterpreter &rhs); 35 36 static const char * 37 GetArgumentTypeAsCString(const lldb::CommandArgumentType arg_type); 38 39 static const char * 40 GetArgumentDescriptionAsCString(const lldb::CommandArgumentType arg_type); 41 42 static bool EventIsCommandInterpreterEvent(const lldb::SBEvent &event); 43 44 explicit operator bool() const; 45 46 bool IsValid() const; 47 48 bool CommandExists(const char *cmd); 49 50 bool AliasExists(const char *cmd); 51 52 lldb::SBBroadcaster GetBroadcaster(); 53 54 static const char *GetBroadcasterClass(); 55 56 bool HasCommands(); 57 58 bool HasAliases(); 59 60 bool HasAliasOptions(); 61 62 lldb::SBProcess GetProcess(); 63 64 lldb::SBDebugger GetDebugger(); 65 66 lldb::SBCommand AddMultiwordCommand(const char *name, const char *help); 67 68 /// Add a new command to the lldb::CommandInterpreter. 69 /// 70 /// The new command won't support autorepeat. If you need this functionality, 71 /// use the override of this function that accepts the \a auto_repeat_command 72 /// parameter. 73 /// 74 /// \param[in] name 75 /// The name of the command. 76 /// 77 /// \param[in] impl 78 /// The handler of this command. 79 /// 80 /// \param[in] help 81 /// The general description to show as part of the help message of this 82 /// command. 83 /// 84 /// \return 85 /// A lldb::SBCommand representing the newly created command. 86 lldb::SBCommand AddCommand(const char *name, 87 lldb::SBCommandPluginInterface *impl, 88 const char *help); 89 90 /// Add a new command to the lldb::CommandInterpreter. 91 /// 92 /// The new command won't support autorepeat. If you need this functionality, 93 /// use the override of this function that accepts the \a auto_repeat_command 94 /// parameter. 95 /// 96 /// \param[in] name 97 /// The name of the command. 98 /// 99 /// \param[in] impl 100 /// The handler of this command. 101 /// 102 /// \param[in] help 103 /// The general description to show as part of the help message of this 104 /// command. 105 /// 106 /// \param[in] syntax 107 /// The syntax to show as part of the help message of this command. This 108 /// could include a description of the different arguments and flags this 109 /// command accepts. 110 /// 111 /// \return 112 /// A lldb::SBCommand representing the newly created command. 113 lldb::SBCommand AddCommand(const char *name, 114 lldb::SBCommandPluginInterface *impl, 115 const char *help, const char *syntax); 116 117 /// Add a new command to the lldb::CommandInterpreter. 118 /// 119 /// \param[in] name 120 /// The name of the command. 121 /// 122 /// \param[in] impl 123 /// The handler of this command. 124 /// 125 /// \param[in] help 126 /// The general description to show as part of the help message of this 127 /// command. 128 /// 129 /// \param[in] syntax 130 /// The syntax to show as part of the help message of this command. This 131 /// could include a description of the different arguments and flags this 132 /// command accepts. 133 /// 134 /// \param[in] auto_repeat_command 135 /// Autorepeating is triggered when the user presses Enter successively 136 /// after executing a command. If \b nullptr is provided, the previous 137 /// exact command will be repeated. If \b "" is provided, autorepeating 138 /// is disabled. Otherwise, the provided string is used as a repeat 139 /// command. 140 /// 141 /// \return 142 /// A lldb::SBCommand representing the newly created command. 143 lldb::SBCommand AddCommand(const char *name, 144 lldb::SBCommandPluginInterface *impl, 145 const char *help, const char *syntax, 146 const char *auto_repeat_command); 147 148 void SourceInitFileInHomeDirectory(lldb::SBCommandReturnObject &result); 149 void SourceInitFileInHomeDirectory(lldb::SBCommandReturnObject &result, 150 bool is_repl); 151 152 void 153 SourceInitFileInCurrentWorkingDirectory(lldb::SBCommandReturnObject &result); 154 155 lldb::ReturnStatus HandleCommand(const char *command_line, 156 lldb::SBCommandReturnObject &result, 157 bool add_to_history = false); 158 159 lldb::ReturnStatus HandleCommand(const char *command_line, 160 SBExecutionContext &exe_ctx, 161 SBCommandReturnObject &result, 162 bool add_to_history = false); 163 164 void HandleCommandsFromFile(lldb::SBFileSpec &file, 165 lldb::SBExecutionContext &override_context, 166 lldb::SBCommandInterpreterRunOptions &options, 167 lldb::SBCommandReturnObject result); 168 169 // The pointer based interface is not useful in SWIG, since the cursor & 170 // last_char arguments are string pointers INTO current_line and you can't do 171 // that in a scripting language interface in general... 172 173 // In either case, the way this works is that the you give it a line and 174 // cursor position in the line. The function will return the number of 175 // completions. The matches list will contain number_of_completions + 1 176 // elements. The first element is the common substring after the cursor 177 // position for all the matches. The rest of the elements are the matches. 178 // The first element is useful if you are emulating the common shell behavior 179 // where the tab completes to the string that is common among all the 180 // matches, then you should first check if the first element is non-empty, 181 // and if so just insert it and move the cursor to the end of the insertion. 182 // The next tab will return an empty common substring, and a list of choices 183 // (if any), at which point you should display the choices and let the user 184 // type further to disambiguate. 185 186 int HandleCompletion(const char *current_line, const char *cursor, 187 const char *last_char, int match_start_point, 188 int max_return_elements, lldb::SBStringList &matches); 189 190 int HandleCompletion(const char *current_line, uint32_t cursor_pos, 191 int match_start_point, int max_return_elements, 192 lldb::SBStringList &matches); 193 194 // Same as HandleCompletion, but also fills out `descriptions` with 195 // descriptions for each match. 196 int HandleCompletionWithDescriptions( 197 const char *current_line, const char *cursor, const char *last_char, 198 int match_start_point, int max_return_elements, 199 lldb::SBStringList &matches, lldb::SBStringList &descriptions); 200 201 int HandleCompletionWithDescriptions(const char *current_line, 202 uint32_t cursor_pos, 203 int match_start_point, 204 int max_return_elements, 205 lldb::SBStringList &matches, 206 lldb::SBStringList &descriptions); 207 208 bool WasInterrupted() const; 209 210 // Catch commands before they execute by registering a callback that will get 211 // called when the command gets executed. This allows GUI or command line 212 // interfaces to intercept a command and stop it from happening 213 bool SetCommandOverrideCallback(const char *command_name, 214 lldb::CommandOverrideCallback callback, 215 void *baton); 216 217 SBCommandInterpreter( 218 lldb_private::CommandInterpreter *interpreter_ptr = 219 nullptr); // Access using SBDebugger::GetCommandInterpreter(); 220 221 /// Return true if the command interpreter is the active IO handler. 222 /// 223 /// This indicates that any input coming into the debugger handles will 224 /// go to the command interpreter and will result in LLDB command line 225 /// commands being executed. 226 bool IsActive(); 227 228 /// Get the string that needs to be written to the debugger stdin file 229 /// handle when a control character is typed. 230 /// 231 /// Some GUI programs will intercept "control + char" sequences and want 232 /// to have them do what normally would happen when using a real 233 /// terminal, so this function allows GUI programs to emulate this 234 /// functionality. 235 /// 236 /// \param[in] ch 237 /// The character that was typed along with the control key 238 /// 239 /// \return 240 /// The string that should be written into the file handle that is 241 /// feeding the input stream for the debugger, or nullptr if there is 242 /// no string for this control key. 243 const char *GetIOHandlerControlSequence(char ch); 244 245 bool GetPromptOnQuit(); 246 247 void SetPromptOnQuit(bool b); 248 249 /// Sets whether the command interpreter should allow custom exit codes 250 /// for the 'quit' command. 251 void AllowExitCodeOnQuit(bool allow); 252 253 /// Returns true if the user has called the 'quit' command with a custom exit 254 /// code. 255 bool HasCustomQuitExitCode(); 256 257 /// Returns the exit code that the user has specified when running the 258 /// 'quit' command. Returns 0 if the user hasn't called 'quit' at all or 259 /// without a custom exit code. 260 int GetQuitStatus(); 261 262 /// Resolve the command just as HandleCommand would, expanding abbreviations 263 /// and aliases. If successful, result->GetOutput has the full expansion. 264 void ResolveCommand(const char *command_line, SBCommandReturnObject &result); 265 266 protected: 267 lldb_private::CommandInterpreter &ref(); 268 269 lldb_private::CommandInterpreter *get(); 270 271 void reset(lldb_private::CommandInterpreter *); 272 273 private: 274 friend class SBDebugger; 275 276 lldb_private::CommandInterpreter *m_opaque_ptr; 277 }; 278 279 class SBCommandPluginInterface { 280 public: 281 virtual ~SBCommandPluginInterface() = default; 282 283 virtual bool DoExecute(lldb::SBDebugger /*debugger*/, char ** /*command*/, 284 lldb::SBCommandReturnObject & /*result*/) { 285 return false; 286 } 287 }; 288 289 class SBCommand { 290 public: 291 SBCommand(); 292 293 explicit operator bool() const; 294 295 bool IsValid(); 296 297 const char *GetName(); 298 299 const char *GetHelp(); 300 301 const char *GetHelpLong(); 302 303 void SetHelp(const char *); 304 305 void SetHelpLong(const char *); 306 307 uint32_t GetFlags(); 308 309 void SetFlags(uint32_t flags); 310 311 lldb::SBCommand AddMultiwordCommand(const char *name, 312 const char *help = nullptr); 313 314 /// Add a new subcommand to the lldb::SBCommand. 315 /// 316 /// The new command won't support autorepeat. If you need this functionality, 317 /// use the override of this function that accepts the \a auto_repeat 318 /// parameter. 319 /// 320 /// \param[in] name 321 /// The name of the command. 322 /// 323 /// \param[in] impl 324 /// The handler of this command. 325 /// 326 /// \param[in] help 327 /// The general description to show as part of the help message of this 328 /// command. 329 /// 330 /// \return 331 /// A lldb::SBCommand representing the newly created command. 332 lldb::SBCommand AddCommand(const char *name, 333 lldb::SBCommandPluginInterface *impl, 334 const char *help = nullptr); 335 336 /// Add a new subcommand to the lldb::SBCommand. 337 /// 338 /// The new command won't support autorepeat. If you need this functionality, 339 /// use the override of this function that accepts the \a auto_repeat_command 340 /// parameter. 341 /// 342 /// \param[in] name 343 /// The name of the command. 344 /// 345 /// \param[in] impl 346 /// The handler of this command. 347 /// 348 /// \param[in] help 349 /// The general description to show as part of the help message of this 350 /// command. 351 /// 352 /// \param[in] syntax 353 /// The syntax to show as part of the help message of this command. This 354 /// could include a description of the different arguments and flags this 355 /// command accepts. 356 /// 357 /// \return 358 /// A lldb::SBCommand representing the newly created command. 359 lldb::SBCommand AddCommand(const char *name, 360 lldb::SBCommandPluginInterface *impl, 361 const char *help, const char *syntax); 362 363 /// Add a new subcommand to the lldb::SBCommand. 364 /// 365 /// The new command won't support autorepeat. If you need this functionality, 366 /// use the override of this function that accepts the \a auto_repeat_command 367 /// parameter. 368 /// 369 /// \param[in] name 370 /// The name of the command. 371 /// 372 /// \param[in] impl 373 /// The handler of this command. 374 /// 375 /// \param[in] help 376 /// The general description to show as part of the help message of this 377 /// command. 378 /// 379 /// \param[in] syntax 380 /// The syntax to show as part of the help message of this command. This 381 /// could include a description of the different arguments and flags this 382 /// command accepts. 383 /// 384 /// \param[in] auto_repeat_command 385 /// Autorepeating is triggered when the user presses Enter successively 386 /// after executing a command. If \b nullptr is provided, the previous 387 /// exact command will be repeated. If \b "" is provided, autorepeating 388 /// is disabled. Otherwise, the provided string is used as a repeat 389 /// command. 390 /// 391 /// \return 392 /// A lldb::SBCommand representing the newly created command. 393 lldb::SBCommand AddCommand(const char *name, 394 lldb::SBCommandPluginInterface *impl, 395 const char *help, const char *syntax, 396 const char *auto_repeat_command); 397 398 private: 399 friend class SBDebugger; 400 friend class SBCommandInterpreter; 401 402 SBCommand(lldb::CommandObjectSP cmd_sp); 403 404 lldb::CommandObjectSP m_opaque_sp; 405 }; 406 407 } // namespace lldb 408 409 #endif // LLDB_API_SBCOMMANDINTERPRETER_H 410