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