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(); 34 SBCommandInterpreter(const lldb::SBCommandInterpreter &rhs); 35 36 ~SBCommandInterpreter(); 37 38 const lldb::SBCommandInterpreter & 39 operator=(const lldb::SBCommandInterpreter &rhs); 40 41 static const char * 42 GetArgumentTypeAsCString(const lldb::CommandArgumentType arg_type); 43 44 static const char * 45 GetArgumentDescriptionAsCString(const lldb::CommandArgumentType arg_type); 46 47 static bool EventIsCommandInterpreterEvent(const lldb::SBEvent &event); 48 49 explicit operator bool() const; 50 51 bool IsValid() const; 52 53 /// Return whether a built-in command with the passed in 54 /// name or command path exists. 55 /// 56 /// \param[in] cmd 57 /// The command or command path to search for. 58 /// 59 /// \return 60 /// \b true if the command exists, \b false otherwise. 61 bool CommandExists(const char *cmd); 62 63 /// Return whether a user defined command with the passed in 64 /// name or command path exists. 65 /// 66 /// \param[in] cmd 67 /// The command or command path to search for. 68 /// 69 /// \return 70 /// \b true if the command exists, \b false otherwise. 71 bool UserCommandExists(const char *cmd); 72 73 /// Return whether the passed in name or command path 74 /// exists and is an alias to some other command. 75 /// 76 /// \param[in] cmd 77 /// The command or command path to search for. 78 /// 79 /// \return 80 /// \b true if the command exists, \b false otherwise. 81 bool AliasExists(const char *cmd); 82 83 lldb::SBBroadcaster GetBroadcaster(); 84 85 static const char *GetBroadcasterClass(); 86 87 bool HasCommands(); 88 89 bool HasAliases(); 90 91 bool HasAliasOptions(); 92 93 bool IsInteractive(); 94 95 lldb::SBProcess GetProcess(); 96 97 lldb::SBDebugger GetDebugger(); 98 99 #ifndef SWIG 100 lldb::SBCommand AddMultiwordCommand(const char *name, const char *help); 101 102 /// Add a new command to the lldb::CommandInterpreter. 103 /// 104 /// The new command won't support autorepeat. If you need this functionality, 105 /// use the override of this function that accepts the \a auto_repeat_command 106 /// parameter. 107 /// 108 /// \param[in] name 109 /// The name of the command. 110 /// 111 /// \param[in] impl 112 /// The handler of this command. 113 /// 114 /// \param[in] help 115 /// The general description to show as part of the help message of this 116 /// command. 117 /// 118 /// \return 119 /// A lldb::SBCommand representing the newly created command. 120 lldb::SBCommand AddCommand(const char *name, 121 lldb::SBCommandPluginInterface *impl, 122 const char *help); 123 124 /// Add a new command to the lldb::CommandInterpreter. 125 /// 126 /// The new command won't support autorepeat. If you need this functionality, 127 /// use the override of this function that accepts the \a auto_repeat_command 128 /// parameter. 129 /// 130 /// \param[in] name 131 /// The name of the command. 132 /// 133 /// \param[in] impl 134 /// The handler of this command. 135 /// 136 /// \param[in] help 137 /// The general description to show as part of the help message of this 138 /// command. 139 /// 140 /// \param[in] syntax 141 /// The syntax to show as part of the help message of this command. This 142 /// could include a description of the different arguments and flags this 143 /// command accepts. 144 /// 145 /// \return 146 /// A lldb::SBCommand representing the newly created command. 147 lldb::SBCommand AddCommand(const char *name, 148 lldb::SBCommandPluginInterface *impl, 149 const char *help, const char *syntax); 150 151 /// Add a new command to the lldb::CommandInterpreter. 152 /// 153 /// \param[in] name 154 /// The name of the command. 155 /// 156 /// \param[in] impl 157 /// The handler of this command. 158 /// 159 /// \param[in] help 160 /// The general description to show as part of the help message of this 161 /// command. 162 /// 163 /// \param[in] syntax 164 /// The syntax to show as part of the help message of this command. This 165 /// could include a description of the different arguments and flags this 166 /// command accepts. 167 /// 168 /// \param[in] auto_repeat_command 169 /// Autorepeating is triggered when the user presses Enter successively 170 /// after executing a command. If \b nullptr is provided, the previous 171 /// exact command will be repeated. If \b "" is provided, autorepeating 172 /// is disabled. Otherwise, the provided string is used as a repeat 173 /// command. 174 /// 175 /// \return 176 /// A lldb::SBCommand representing the newly created command. 177 lldb::SBCommand AddCommand(const char *name, 178 lldb::SBCommandPluginInterface *impl, 179 const char *help, const char *syntax, 180 const char *auto_repeat_command); 181 void SourceInitFileInGlobalDirectory(lldb::SBCommandReturnObject &result); 182 #endif 183 184 185 void SourceInitFileInHomeDirectory(lldb::SBCommandReturnObject &result); 186 void SourceInitFileInHomeDirectory(lldb::SBCommandReturnObject &result, 187 bool is_repl); 188 189 void 190 SourceInitFileInCurrentWorkingDirectory(lldb::SBCommandReturnObject &result); 191 192 lldb::ReturnStatus HandleCommand(const char *command_line, 193 lldb::SBCommandReturnObject &result, 194 bool add_to_history = false); 195 196 lldb::ReturnStatus HandleCommand(const char *command_line, 197 SBExecutionContext &exe_ctx, 198 SBCommandReturnObject &result, 199 bool add_to_history = false); 200 201 void HandleCommandsFromFile(lldb::SBFileSpec &file, 202 lldb::SBExecutionContext &override_context, 203 lldb::SBCommandInterpreterRunOptions &options, 204 lldb::SBCommandReturnObject result); 205 206 // The pointer based interface is not useful in SWIG, since the cursor & 207 // last_char arguments are string pointers INTO current_line and you can't do 208 // that in a scripting language interface in general... 209 210 // In either case, the way this works is that the you give it a line and 211 // cursor position in the line. The function will return the number of 212 // completions. The matches list will contain number_of_completions + 1 213 // elements. The first element is the common substring after the cursor 214 // position for all the matches. The rest of the elements are the matches. 215 // The first element is useful if you are emulating the common shell behavior 216 // where the tab completes to the string that is common among all the 217 // matches, then you should first check if the first element is non-empty, 218 // and if so just insert it and move the cursor to the end of the insertion. 219 // The next tab will return an empty common substring, and a list of choices 220 // (if any), at which point you should display the choices and let the user 221 // type further to disambiguate. 222 223 #ifndef SWIG 224 int HandleCompletion(const char *current_line, const char *cursor, 225 const char *last_char, int match_start_point, 226 int max_return_elements, lldb::SBStringList &matches); 227 #endif 228 229 int HandleCompletion(const char *current_line, uint32_t cursor_pos, 230 int match_start_point, int max_return_elements, 231 lldb::SBStringList &matches); 232 233 // Same as HandleCompletion, but also fills out `descriptions` with 234 // descriptions for each match. 235 #ifndef SWIG 236 int HandleCompletionWithDescriptions( 237 const char *current_line, const char *cursor, const char *last_char, 238 int match_start_point, int max_return_elements, 239 lldb::SBStringList &matches, lldb::SBStringList &descriptions); 240 #endif 241 242 int HandleCompletionWithDescriptions(const char *current_line, 243 uint32_t cursor_pos, 244 int match_start_point, 245 int max_return_elements, 246 lldb::SBStringList &matches, 247 lldb::SBStringList &descriptions); 248 249 /// Returns whether an interrupt flag was raised either by the SBDebugger - 250 /// when the function is not running on the RunCommandInterpreter thread, or 251 /// by SBCommandInterpreter::InterruptCommand if it is. If your code is doing 252 /// interruptible work, check this API periodically, and interrupt if it 253 /// returns true. 254 bool WasInterrupted() const; 255 256 /// Interrupts the command currently executing in the RunCommandInterpreter 257 /// thread. 258 /// 259 /// \return 260 /// \b true if there was a command in progress to recieve the interrupt. 261 /// \b false if there's no command currently in flight. 262 bool InterruptCommand(); 263 264 // Catch commands before they execute by registering a callback that will get 265 // called when the command gets executed. This allows GUI or command line 266 // interfaces to intercept a command and stop it from happening 267 #ifndef SWIG 268 bool SetCommandOverrideCallback(const char *command_name, 269 lldb::CommandOverrideCallback callback, 270 void *baton); 271 #endif 272 273 /// Return true if the command interpreter is the active IO handler. 274 /// 275 /// This indicates that any input coming into the debugger handles will 276 /// go to the command interpreter and will result in LLDB command line 277 /// commands being executed. 278 bool IsActive(); 279 280 /// Get the string that needs to be written to the debugger stdin file 281 /// handle when a control character is typed. 282 /// 283 /// Some GUI programs will intercept "control + char" sequences and want 284 /// to have them do what normally would happen when using a real 285 /// terminal, so this function allows GUI programs to emulate this 286 /// functionality. 287 /// 288 /// \param[in] ch 289 /// The character that was typed along with the control key 290 /// 291 /// \return 292 /// The string that should be written into the file handle that is 293 /// feeding the input stream for the debugger, or nullptr if there is 294 /// no string for this control key. 295 const char *GetIOHandlerControlSequence(char ch); 296 297 bool GetPromptOnQuit(); 298 299 void SetPromptOnQuit(bool b); 300 301 /// Sets whether the command interpreter should allow custom exit codes 302 /// for the 'quit' command. 303 void AllowExitCodeOnQuit(bool allow); 304 305 /// Returns true if the user has called the 'quit' command with a custom exit 306 /// code. 307 bool HasCustomQuitExitCode(); 308 309 /// Returns the exit code that the user has specified when running the 310 /// 'quit' command. Returns 0 if the user hasn't called 'quit' at all or 311 /// without a custom exit code. 312 int GetQuitStatus(); 313 314 /// Resolve the command just as HandleCommand would, expanding abbreviations 315 /// and aliases. If successful, result->GetOutput has the full expansion. 316 void ResolveCommand(const char *command_line, SBCommandReturnObject &result); 317 318 protected: 319 friend class lldb_private::CommandPluginInterfaceImplementation; 320 321 /// Access using SBDebugger::GetCommandInterpreter(); 322 SBCommandInterpreter(lldb_private::CommandInterpreter *interpreter_ptr); 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 DoExecute(lldb::SBDebugger,char **,lldb::SBCommandReturnObject &)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