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