CommandObject.h revision da26bd203cbb104291b39891febf7481794f205f
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 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() { 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 virtual bool 148 WantsRawCommandString() = 0; 149 150 // By default, WantsCompletion = !WantsRawCommandString. 151 // Subclasses who want raw command string but desire, for example, 152 // argument completion should override this method to return true. 153 virtual bool 154 WantsCompletion() { return !WantsRawCommandString(); } 155 156 virtual Options * 157 GetOptions (); 158 159 static const ArgumentTableEntry* 160 GetArgumentTable (); 161 162 static lldb::CommandArgumentType 163 LookupArgumentName (const char *arg_name); 164 165 static ArgumentTableEntry * 166 FindArgumentDataByType (lldb::CommandArgumentType arg_type); 167 168 int 169 GetNumArgumentEntries (); 170 171 CommandArgumentEntry * 172 GetArgumentEntryAtIndex (int idx); 173 174 static void 175 GetArgumentHelp (Stream &str, lldb::CommandArgumentType arg_type, CommandInterpreter &interpreter); 176 177 static const char * 178 GetArgumentName (lldb::CommandArgumentType arg_type); 179 180 // Generates a nicely formatted command args string for help command output. 181 // By default, all possible args are taken into account, for example, 182 // '<expr | variable-name>'. This can be refined by passing a second arg 183 // specifying which option set(s) we are interested, which could then, for 184 // example, produce either '<expr>' or '<variable-name>'. 185 void 186 GetFormattedCommandArguments (Stream &str, uint32_t opt_set_mask = LLDB_OPT_SET_ALL); 187 188 bool 189 IsPairType (ArgumentRepetitionType arg_repeat_type); 190 191 enum 192 { 193 eFlagProcessMustBeLaunched = (1 << 0), 194 eFlagProcessMustBePaused = (1 << 1) 195 }; 196 197 bool 198 ParseOptions (Args& args, 199 CommandReturnObject &result); 200 201 void 202 SetCommandName (const char *name); 203 204 // This function really deals with CommandObjectLists, but we didn't make a 205 // CommandObjectList class, so I'm sticking it here. But we really should have 206 // such a class. Anyway, it looks up the commands in the map that match the partial 207 // string cmd_str, inserts the matches into matches, and returns the number added. 208 209 static int 210 AddNamesMatchingPartialString (CommandMap &in_map, const char *cmd_str, StringList &matches); 211 212 //------------------------------------------------------------------ 213 /// The input array contains a parsed version of the line. The insertion 214 /// point is given by cursor_index (the index in input of the word containing 215 /// the cursor) and cursor_char_position (the position of the cursor in that word.) 216 /// This default version handles calling option argument completions and then calls 217 /// HandleArgumentCompletion if the cursor is on an argument, not an option. 218 /// Don't override this method, override HandleArgumentCompletion instead unless 219 /// you have special reasons. 220 /// 221 /// @param[in] interpreter 222 /// The command interpreter doing the completion. 223 /// 224 /// @param[in] input 225 /// The command line parsed into words 226 /// 227 /// @param[in] cursor_index 228 /// The index in \ainput of the word in which the cursor lies. 229 /// 230 /// @param[in] cursor_char_pos 231 /// The character position of the cursor in its argument word. 232 /// 233 /// @param[in] match_start_point 234 /// @param[in] match_return_elements 235 /// FIXME: Not yet implemented... If there is a match that is expensive to compute, these are 236 /// here to allow you to compute the completions in batches. Start the completion from \amatch_start_point, 237 /// and return \amatch_return_elements elements. 238 /// 239 /// @param[out] word_complete 240 /// \btrue if this is a complete option value (a space will be inserted after the 241 /// completion.) \bfalse otherwise. 242 /// 243 /// @param[out] matches 244 /// The array of matches returned. 245 /// 246 /// FIXME: This is the wrong return value, since we also need to make a distinction between 247 /// total number of matches, and the window the user wants returned. 248 /// 249 /// @return 250 /// \btrue if we were in an option, \bfalse otherwise. 251 //------------------------------------------------------------------ 252 virtual int 253 HandleCompletion (Args &input, 254 int &cursor_index, 255 int &cursor_char_position, 256 int match_start_point, 257 int max_return_elements, 258 bool &word_complete, 259 StringList &matches); 260 261 //------------------------------------------------------------------ 262 /// The input array contains a parsed version of the line. The insertion 263 /// point is given by cursor_index (the index in input of the word containing 264 /// the cursor) and cursor_char_position (the position of the cursor in that word.) 265 /// We've constructed the map of options and their arguments as well if that is 266 /// helpful for the completion. 267 /// 268 /// @param[in] interpreter 269 /// The command interpreter doing the completion. 270 /// 271 /// @param[in] input 272 /// The command line parsed into words 273 /// 274 /// @param[in] cursor_index 275 /// The index in \ainput of the word in which the cursor lies. 276 /// 277 /// @param[in] cursor_char_pos 278 /// The character position of the cursor in its argument word. 279 /// 280 /// @param[in] opt_element_vector 281 /// The results of the options parse of \a input. 282 /// 283 /// @param[in] match_start_point 284 /// @param[in] match_return_elements 285 /// See CommandObject::HandleCompletions for a description of how these work. 286 /// 287 /// @param[out] word_complete 288 /// \btrue if this is a complete option value (a space will be inserted after the 289 /// completion.) \bfalse otherwise. 290 /// 291 /// @param[out] matches 292 /// The array of matches returned. 293 /// 294 /// FIXME: This is the wrong return value, since we also need to make a distinction between 295 /// total number of matches, and the window the user wants returned. 296 /// 297 /// @return 298 /// \btrue if we were in an option, \bfalse otherwise. 299 //------------------------------------------------------------------ 300 301 virtual int 302 HandleArgumentCompletion (Args &input, 303 int &cursor_index, 304 int &cursor_char_position, 305 OptionElementVector &opt_element_vector, 306 int match_start_point, 307 int max_return_elements, 308 bool &word_complete, 309 StringList &matches) 310 { 311 return 0; 312 } 313 314 bool 315 HelpTextContainsWord (const char *search_word); 316 317 //------------------------------------------------------------------ 318 /// The flags accessor. 319 /// 320 /// @return 321 /// A reference to the Flags member variable. 322 //------------------------------------------------------------------ 323 Flags& 324 GetFlags() 325 { 326 return m_flags; 327 } 328 329 //------------------------------------------------------------------ 330 /// The flags const accessor. 331 /// 332 /// @return 333 /// A const reference to the Flags member variable. 334 //------------------------------------------------------------------ 335 const Flags& 336 GetFlags() const 337 { 338 return m_flags; 339 } 340 341 //------------------------------------------------------------------ 342 /// Check the command flags against the interpreter's current execution context. 343 /// 344 /// @param[out] result 345 /// A command result object, if it is not okay to run the command this will be 346 /// filled in with a suitable error. 347 /// 348 /// @return 349 /// \b true if it is okay to run this command, \b false otherwise. 350 //------------------------------------------------------------------ 351 bool 352 CheckFlags (CommandReturnObject &result); 353 354 //------------------------------------------------------------------ 355 /// Get the command that appropriate for a "repeat" of the current command. 356 /// 357 /// @param[in] current_command_line 358 /// The complete current command line. 359 /// 360 /// @return 361 /// NULL if there is no special repeat command - it will use the current command line. 362 /// Otherwise a pointer to the command to be repeated. 363 /// If the returned string is the empty string, the command won't be repeated. 364 //------------------------------------------------------------------ 365 virtual const char *GetRepeatCommand (Args ¤t_command_args, uint32_t index) 366 { 367 return NULL; 368 } 369 370 CommandOverrideCallback 371 GetOverrideCallback () const 372 { 373 return m_command_override_callback; 374 } 375 376 void * 377 GetOverrideCallbackBaton () const 378 { 379 return m_command_override_baton; 380 } 381 382 void 383 SetOverrideCallback (CommandOverrideCallback callback, void *baton) 384 { 385 m_command_override_callback = callback; 386 m_command_override_baton = baton; 387 } 388 389 virtual bool 390 Execute (const char *args_string, CommandReturnObject &result) = 0; 391 392protected: 393 CommandInterpreter &m_interpreter; 394 std::string m_cmd_name; 395 std::string m_cmd_help_short; 396 std::string m_cmd_help_long; 397 std::string m_cmd_syntax; 398 bool m_is_alias; 399 Flags m_flags; 400 std::vector<CommandArgumentEntry> m_arguments; 401 CommandOverrideCallback m_command_override_callback; 402 void * m_command_override_baton; 403 404 // Helper function to populate IDs or ID ranges as the command argument data 405 // to the specified command argument entry. 406 static void 407 AddIDsArgumentData(CommandArgumentEntry &arg, lldb::CommandArgumentType ID, lldb::CommandArgumentType IDRange); 408 409}; 410 411class CommandObjectParsed : public CommandObject 412{ 413public: 414 415 CommandObjectParsed (CommandInterpreter &interpreter, 416 const char *name, 417 const char *help = NULL, 418 const char *syntax = NULL, 419 uint32_t flags = 0) : 420 CommandObject (interpreter, name, help, syntax, flags) {} 421 422 virtual 423 ~CommandObjectParsed () {}; 424 425 virtual bool 426 Execute (const char *args_string, CommandReturnObject &result); 427 428protected: 429 virtual bool 430 DoExecute (Args& command, 431 CommandReturnObject &result) = 0; 432 433 virtual bool 434 WantsRawCommandString() { return false; }; 435}; 436 437class CommandObjectRaw : public CommandObject 438{ 439public: 440 441 CommandObjectRaw (CommandInterpreter &interpreter, 442 const char *name, 443 const char *help = NULL, 444 const char *syntax = NULL, 445 uint32_t flags = 0) : 446 CommandObject (interpreter, name, help, syntax, flags) {} 447 448 virtual 449 ~CommandObjectRaw () {}; 450 451 virtual bool 452 Execute (const char *args_string, CommandReturnObject &result); 453 454protected: 455 virtual bool 456 DoExecute (const char *command, CommandReturnObject &result) = 0; 457 458 virtual bool 459 WantsRawCommandString() { return true; }; 460}; 461 462 463} // namespace lldb_private 464 465 466#endif // liblldb_CommandObject_h_ 467