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