CommandObject.h revision f737d372a9672c9feaedf4b2cd7b16e31357d38e
1//===-- CommandObject.h -----------------------------------------*- C++ -*-===// 2// 3// The LLVM Compiler Infrastructure 4// 5// This file is distributed under the University of Illinois Open Source 6// License. See LICENSE.TXT for details. 7// 8//===----------------------------------------------------------------------===// 9 10#ifndef liblldb_CommandObject_h_ 11#define liblldb_CommandObject_h_ 12 13#include <map> 14#include <set> 15#include <string> 16#include <vector> 17 18#include "lldb/lldb-private.h" 19#include "lldb/Interpreter/Args.h" 20#include "lldb/Interpreter/CommandCompletions.h" 21#include "lldb/Core/StringList.h" 22#include "lldb/Core/Flags.h" 23 24namespace lldb_private { 25 26class CommandObject 27{ 28public: 29 30 typedef const char *(ArgumentHelpCallbackFunction) (); 31 32 struct ArgumentHelpCallback 33 { 34 ArgumentHelpCallbackFunction *help_callback; 35 bool self_formatting; 36 37 const char* 38 operator () () const 39 { 40 return (*help_callback)(); 41 } 42 43 operator bool() const 44 { 45 return (help_callback != NULL); 46 } 47 48 }; 49 50 struct ArgumentTableEntry // Entries in the main argument information table 51 { 52 lldb::CommandArgumentType arg_type; 53 const char *arg_name; 54 CommandCompletions::CommonCompletionTypes completion_type; 55 ArgumentHelpCallback help_function; 56 const char *help_text; 57 }; 58 59 struct CommandArgumentData // Used to build individual command argument lists 60 { 61 lldb::CommandArgumentType arg_type; 62 ArgumentRepetitionType arg_repetition; 63 uint32_t arg_opt_set_association; // This arg might be associated only with some particular option set(s). 64 CommandArgumentData(): 65 arg_type(lldb::eArgTypeNone), 66 arg_repetition(eArgRepeatPlain), 67 arg_opt_set_association(LLDB_OPT_SET_ALL) // By default, the arg associates to all option sets. 68 {} 69 }; 70 71 typedef std::vector<CommandArgumentData> CommandArgumentEntry; // Used to build individual command argument lists 72 73 static ArgumentTableEntry g_arguments_data[lldb::eArgTypeLastArg]; // Main argument information table 74 75 typedef std::map<std::string, lldb::CommandObjectSP> CommandMap; 76 77 CommandObject (CommandInterpreter &interpreter, 78 const char *name, 79 const char *help = NULL, 80 const char *syntax = NULL, 81 uint32_t flags = 0); 82 83 virtual 84 ~CommandObject (); 85 86 87 static const char * 88 GetArgumentTypeAsCString (const lldb::CommandArgumentType arg_type); 89 90 static const char * 91 GetArgumentDescriptionAsCString (const lldb::CommandArgumentType arg_type); 92 93 CommandInterpreter & 94 GetCommandInterpreter () 95 { 96 return m_interpreter; 97 } 98 99 const char * 100 GetHelp (); 101 102 virtual const char * 103 GetHelpLong (); 104 105 const char * 106 GetSyntax (); 107 108 const char * 109 Translate (); 110 111 const char * 112 GetCommandName (); 113 114 void 115 SetHelp (const char * str); 116 117 void 118 SetHelpLong (const char * str); 119 120 void 121 SetHelpLong (std::string str); 122 123 void 124 SetSyntax (const char *str); 125 126 virtual void 127 AddObject (const char *obj_name) {} 128 129 virtual bool 130 IsCrossRefObject () { return false; } 131 132 // override this to return true if you want to enable the user to delete 133 // the Command object from the Command dictionary (aliases have their own 134 // deletion scheme, so they do not need to care about this) 135 virtual bool 136 IsRemovable() const { return false; } 137 138 bool 139 IsAlias () { return m_is_alias; } 140 141 void 142 SetIsAlias (bool value) { m_is_alias = value; } 143 144 virtual bool 145 IsMultiwordObject () { return false; } 146 147 // this is needed in order to allow the SBCommand class to 148 // transparently try and load subcommands - it will fail on 149 // anything but a multiword command, but it avoids us doing 150 // type checkings and casts 151 virtual bool 152 LoadSubCommand (const char *cmd_name, 153 const lldb::CommandObjectSP& command_obj) 154 { 155 return false; 156 } 157 158 virtual bool 159 WantsRawCommandString() = 0; 160 161 // By default, WantsCompletion = !WantsRawCommandString. 162 // Subclasses who want raw command string but desire, for example, 163 // argument completion should override this method to return true. 164 virtual bool 165 WantsCompletion() { return !WantsRawCommandString(); } 166 167 virtual Options * 168 GetOptions (); 169 170 static const ArgumentTableEntry* 171 GetArgumentTable (); 172 173 static lldb::CommandArgumentType 174 LookupArgumentName (const char *arg_name); 175 176 static ArgumentTableEntry * 177 FindArgumentDataByType (lldb::CommandArgumentType arg_type); 178 179 int 180 GetNumArgumentEntries (); 181 182 CommandArgumentEntry * 183 GetArgumentEntryAtIndex (int idx); 184 185 static void 186 GetArgumentHelp (Stream &str, lldb::CommandArgumentType arg_type, CommandInterpreter &interpreter); 187 188 static const char * 189 GetArgumentName (lldb::CommandArgumentType arg_type); 190 191 // Generates a nicely formatted command args string for help command output. 192 // By default, all possible args are taken into account, for example, 193 // '<expr | variable-name>'. This can be refined by passing a second arg 194 // specifying which option set(s) we are interested, which could then, for 195 // example, produce either '<expr>' or '<variable-name>'. 196 void 197 GetFormattedCommandArguments (Stream &str, uint32_t opt_set_mask = LLDB_OPT_SET_ALL); 198 199 bool 200 IsPairType (ArgumentRepetitionType arg_repeat_type); 201 202 enum 203 { 204 eFlagProcessMustBeLaunched = (1 << 0), 205 eFlagProcessMustBePaused = (1 << 1) 206 }; 207 208 bool 209 ParseOptions (Args& args, 210 CommandReturnObject &result); 211 212 void 213 SetCommandName (const char *name); 214 215 // This function really deals with CommandObjectLists, but we didn't make a 216 // CommandObjectList class, so I'm sticking it here. But we really should have 217 // such a class. Anyway, it looks up the commands in the map that match the partial 218 // string cmd_str, inserts the matches into matches, and returns the number added. 219 220 static int 221 AddNamesMatchingPartialString (CommandMap &in_map, const char *cmd_str, StringList &matches); 222 223 //------------------------------------------------------------------ 224 /// The input array contains a parsed version of the line. The insertion 225 /// point is given by cursor_index (the index in input of the word containing 226 /// the cursor) and cursor_char_position (the position of the cursor in that word.) 227 /// This default version handles calling option argument completions and then calls 228 /// HandleArgumentCompletion if the cursor is on an argument, not an option. 229 /// Don't override this method, override HandleArgumentCompletion instead unless 230 /// you have special reasons. 231 /// 232 /// @param[in] interpreter 233 /// The command interpreter doing the completion. 234 /// 235 /// @param[in] input 236 /// The command line parsed into words 237 /// 238 /// @param[in] cursor_index 239 /// The index in \ainput of the word in which the cursor lies. 240 /// 241 /// @param[in] cursor_char_pos 242 /// The character position of the cursor in its argument word. 243 /// 244 /// @param[in] match_start_point 245 /// @param[in] match_return_elements 246 /// FIXME: Not yet implemented... If there is a match that is expensive to compute, these are 247 /// here to allow you to compute the completions in batches. Start the completion from \amatch_start_point, 248 /// and return \amatch_return_elements elements. 249 /// 250 /// @param[out] word_complete 251 /// \btrue if this is a complete option value (a space will be inserted after the 252 /// completion.) \bfalse otherwise. 253 /// 254 /// @param[out] matches 255 /// The array of matches returned. 256 /// 257 /// FIXME: This is the wrong return value, since we also need to make a distinction between 258 /// total number of matches, and the window the user wants returned. 259 /// 260 /// @return 261 /// \btrue if we were in an option, \bfalse otherwise. 262 //------------------------------------------------------------------ 263 virtual int 264 HandleCompletion (Args &input, 265 int &cursor_index, 266 int &cursor_char_position, 267 int match_start_point, 268 int max_return_elements, 269 bool &word_complete, 270 StringList &matches); 271 272 //------------------------------------------------------------------ 273 /// The input array contains a parsed version of the line. The insertion 274 /// point is given by cursor_index (the index in input of the word containing 275 /// the cursor) and cursor_char_position (the position of the cursor in that word.) 276 /// We've constructed the map of options and their arguments as well if that is 277 /// helpful for the completion. 278 /// 279 /// @param[in] interpreter 280 /// The command interpreter doing the completion. 281 /// 282 /// @param[in] input 283 /// The command line parsed into words 284 /// 285 /// @param[in] cursor_index 286 /// The index in \ainput of the word in which the cursor lies. 287 /// 288 /// @param[in] cursor_char_pos 289 /// The character position of the cursor in its argument word. 290 /// 291 /// @param[in] opt_element_vector 292 /// The results of the options parse of \a input. 293 /// 294 /// @param[in] match_start_point 295 /// @param[in] match_return_elements 296 /// See CommandObject::HandleCompletions for a description of how these work. 297 /// 298 /// @param[out] word_complete 299 /// \btrue if this is a complete option value (a space will be inserted after the 300 /// completion.) \bfalse otherwise. 301 /// 302 /// @param[out] matches 303 /// The array of matches returned. 304 /// 305 /// FIXME: This is the wrong return value, since we also need to make a distinction between 306 /// total number of matches, and the window the user wants returned. 307 /// 308 /// @return 309 /// \btrue if we were in an option, \bfalse otherwise. 310 //------------------------------------------------------------------ 311 312 virtual int 313 HandleArgumentCompletion (Args &input, 314 int &cursor_index, 315 int &cursor_char_position, 316 OptionElementVector &opt_element_vector, 317 int match_start_point, 318 int max_return_elements, 319 bool &word_complete, 320 StringList &matches) 321 { 322 return 0; 323 } 324 325 bool 326 HelpTextContainsWord (const char *search_word); 327 328 //------------------------------------------------------------------ 329 /// The flags accessor. 330 /// 331 /// @return 332 /// A reference to the Flags member variable. 333 //------------------------------------------------------------------ 334 Flags& 335 GetFlags() 336 { 337 return m_flags; 338 } 339 340 //------------------------------------------------------------------ 341 /// The flags const accessor. 342 /// 343 /// @return 344 /// A const reference to the Flags member variable. 345 //------------------------------------------------------------------ 346 const Flags& 347 GetFlags() const 348 { 349 return m_flags; 350 } 351 352 //------------------------------------------------------------------ 353 /// Check the command flags against the interpreter's current execution context. 354 /// 355 /// @param[out] result 356 /// A command result object, if it is not okay to run the command this will be 357 /// filled in with a suitable error. 358 /// 359 /// @return 360 /// \b true if it is okay to run this command, \b false otherwise. 361 //------------------------------------------------------------------ 362 bool 363 CheckFlags (CommandReturnObject &result); 364 365 //------------------------------------------------------------------ 366 /// Get the command that appropriate for a "repeat" of the current command. 367 /// 368 /// @param[in] current_command_line 369 /// The complete current command line. 370 /// 371 /// @return 372 /// NULL if there is no special repeat command - it will use the current command line. 373 /// Otherwise a pointer to the command to be repeated. 374 /// If the returned string is the empty string, the command won't be repeated. 375 //------------------------------------------------------------------ 376 virtual const char *GetRepeatCommand (Args ¤t_command_args, uint32_t index) 377 { 378 return NULL; 379 } 380 381 CommandOverrideCallback 382 GetOverrideCallback () const 383 { 384 return m_command_override_callback; 385 } 386 387 void * 388 GetOverrideCallbackBaton () const 389 { 390 return m_command_override_baton; 391 } 392 393 void 394 SetOverrideCallback (CommandOverrideCallback callback, void *baton) 395 { 396 m_command_override_callback = callback; 397 m_command_override_baton = baton; 398 } 399 400 virtual bool 401 Execute (const char *args_string, CommandReturnObject &result) = 0; 402 403protected: 404 CommandInterpreter &m_interpreter; 405 std::string m_cmd_name; 406 std::string m_cmd_help_short; 407 std::string m_cmd_help_long; 408 std::string m_cmd_syntax; 409 bool m_is_alias; 410 Flags m_flags; 411 std::vector<CommandArgumentEntry> m_arguments; 412 CommandOverrideCallback m_command_override_callback; 413 void * m_command_override_baton; 414 415 // Helper function to populate IDs or ID ranges as the command argument data 416 // to the specified command argument entry. 417 static void 418 AddIDsArgumentData(CommandArgumentEntry &arg, lldb::CommandArgumentType ID, lldb::CommandArgumentType IDRange); 419 420}; 421 422class CommandObjectParsed : public CommandObject 423{ 424public: 425 426 CommandObjectParsed (CommandInterpreter &interpreter, 427 const char *name, 428 const char *help = NULL, 429 const char *syntax = NULL, 430 uint32_t flags = 0) : 431 CommandObject (interpreter, name, help, syntax, flags) {} 432 433 virtual 434 ~CommandObjectParsed () {}; 435 436 virtual bool 437 Execute (const char *args_string, CommandReturnObject &result); 438 439protected: 440 virtual bool 441 DoExecute (Args& command, 442 CommandReturnObject &result) = 0; 443 444 virtual bool 445 WantsRawCommandString() { return false; }; 446}; 447 448class CommandObjectRaw : public CommandObject 449{ 450public: 451 452 CommandObjectRaw (CommandInterpreter &interpreter, 453 const char *name, 454 const char *help = NULL, 455 const char *syntax = NULL, 456 uint32_t flags = 0) : 457 CommandObject (interpreter, name, help, syntax, flags) {} 458 459 virtual 460 ~CommandObjectRaw () {}; 461 462 virtual bool 463 Execute (const char *args_string, CommandReturnObject &result); 464 465protected: 466 virtual bool 467 DoExecute (const char *command, CommandReturnObject &result) = 0; 468 469 virtual bool 470 WantsRawCommandString() { return true; }; 471}; 472 473 474} // namespace lldb_private 475 476 477#endif // liblldb_CommandObject_h_ 478