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