1 //===-- CommandObject.cpp ---------------------------------------*- 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 #include "lldb/Interpreter/CommandObject.h" 11 12 #include <string> 13 #include <map> 14 15 #include <getopt.h> 16 #include <stdlib.h> 17 #include <ctype.h> 18 19 #include "lldb/Core/Address.h" 20 #include "lldb/Core/ArchSpec.h" 21 #include "lldb/Interpreter/Options.h" 22 23 // These are for the Sourcename completers. 24 // FIXME: Make a separate file for the completers. 25 #include "lldb/Host/FileSpec.h" 26 #include "lldb/Core/FileSpecList.h" 27 #include "lldb/Target/Process.h" 28 #include "lldb/Target/Target.h" 29 30 #include "lldb/Interpreter/CommandInterpreter.h" 31 #include "lldb/Interpreter/CommandReturnObject.h" 32 #include "lldb/Interpreter/ScriptInterpreter.h" 33 #include "lldb/Interpreter/ScriptInterpreterPython.h" 34 35 using namespace lldb; 36 using namespace lldb_private; 37 38 //------------------------------------------------------------------------- 39 // CommandObject 40 //------------------------------------------------------------------------- 41 42 CommandObject::CommandObject 43 ( 44 CommandInterpreter &interpreter, 45 const char *name, 46 const char *help, 47 const char *syntax, 48 uint32_t flags 49 ) : 50 m_interpreter (interpreter), 51 m_cmd_name (name), 52 m_cmd_help_short (), 53 m_cmd_help_long (), 54 m_cmd_syntax (), 55 m_is_alias (false), 56 m_flags (flags), 57 m_arguments(), 58 m_command_override_callback (NULL), 59 m_command_override_baton (NULL) 60 { 61 if (help && help[0]) 62 m_cmd_help_short = help; 63 if (syntax && syntax[0]) 64 m_cmd_syntax = syntax; 65 } 66 67 CommandObject::~CommandObject () 68 { 69 } 70 71 const char * 72 CommandObject::GetHelp () 73 { 74 return m_cmd_help_short.c_str(); 75 } 76 77 const char * 78 CommandObject::GetHelpLong () 79 { 80 return m_cmd_help_long.c_str(); 81 } 82 83 const char * 84 CommandObject::GetSyntax () 85 { 86 if (m_cmd_syntax.length() == 0) 87 { 88 StreamString syntax_str; 89 syntax_str.Printf ("%s", GetCommandName()); 90 if (GetOptions() != NULL) 91 syntax_str.Printf (" <cmd-options>"); 92 if (m_arguments.size() > 0) 93 { 94 syntax_str.Printf (" "); 95 if (WantsRawCommandString()) 96 syntax_str.Printf("-- "); 97 GetFormattedCommandArguments (syntax_str); 98 } 99 m_cmd_syntax = syntax_str.GetData (); 100 } 101 102 return m_cmd_syntax.c_str(); 103 } 104 105 const char * 106 CommandObject::Translate () 107 { 108 //return m_cmd_func_name.c_str(); 109 return "This function is currently not implemented."; 110 } 111 112 const char * 113 CommandObject::GetCommandName () 114 { 115 return m_cmd_name.c_str(); 116 } 117 118 void 119 CommandObject::SetCommandName (const char *name) 120 { 121 m_cmd_name = name; 122 } 123 124 void 125 CommandObject::SetHelp (const char *cstr) 126 { 127 m_cmd_help_short = cstr; 128 } 129 130 void 131 CommandObject::SetHelpLong (const char *cstr) 132 { 133 m_cmd_help_long = cstr; 134 } 135 136 void 137 CommandObject::SetHelpLong (std::string str) 138 { 139 m_cmd_help_long = str; 140 } 141 142 void 143 CommandObject::SetSyntax (const char *cstr) 144 { 145 m_cmd_syntax = cstr; 146 } 147 148 Options * 149 CommandObject::GetOptions () 150 { 151 // By default commands don't have options unless this virtual function 152 // is overridden by base classes. 153 return NULL; 154 } 155 156 Flags& 157 CommandObject::GetFlags() 158 { 159 return m_flags; 160 } 161 162 const Flags& 163 CommandObject::GetFlags() const 164 { 165 return m_flags; 166 } 167 168 bool 169 CommandObject::ParseOptions 170 ( 171 Args& args, 172 CommandReturnObject &result 173 ) 174 { 175 // See if the subclass has options? 176 Options *options = GetOptions(); 177 if (options != NULL) 178 { 179 Error error; 180 options->NotifyOptionParsingStarting(); 181 182 // ParseOptions calls getopt_long, which always skips the zero'th item in the array and starts at position 1, 183 // so we need to push a dummy value into position zero. 184 args.Unshift("dummy_string"); 185 error = args.ParseOptions (*options); 186 187 // The "dummy_string" will have already been removed by ParseOptions, 188 // so no need to remove it. 189 190 if (error.Success()) 191 error = options->NotifyOptionParsingFinished(); 192 193 if (error.Success()) 194 { 195 if (options->VerifyOptions (result)) 196 return true; 197 } 198 else 199 { 200 const char *error_cstr = error.AsCString(); 201 if (error_cstr) 202 { 203 // We got an error string, lets use that 204 result.AppendError(error_cstr); 205 } 206 else 207 { 208 // No error string, output the usage information into result 209 options->GenerateOptionUsage (result.GetErrorStream(), this); 210 } 211 } 212 result.SetStatus (eReturnStatusFailed); 213 return false; 214 } 215 return true; 216 } 217 bool 218 CommandObject::ExecuteWithOptions (Args& args, CommandReturnObject &result) 219 { 220 for (size_t i = 0; i < args.GetArgumentCount(); ++i) 221 { 222 const char *tmp_str = args.GetArgumentAtIndex (i); 223 if (tmp_str[0] == '`') // back-quote 224 args.ReplaceArgumentAtIndex (i, m_interpreter.ProcessEmbeddedScriptCommands (tmp_str)); 225 } 226 227 if (GetFlags().AnySet (CommandObject::eFlagProcessMustBeLaunched | CommandObject::eFlagProcessMustBePaused)) 228 { 229 Process *process = m_interpreter.GetExecutionContext().GetProcessPtr(); 230 if (process == NULL) 231 { 232 // A process that is not running is considered paused. 233 if (GetFlags().Test(CommandObject::eFlagProcessMustBeLaunched)) 234 { 235 result.AppendError ("Process must exist."); 236 result.SetStatus (eReturnStatusFailed); 237 return false; 238 } 239 } 240 else 241 { 242 StateType state = process->GetState(); 243 244 switch (state) 245 { 246 case eStateInvalid: 247 case eStateSuspended: 248 case eStateCrashed: 249 case eStateStopped: 250 break; 251 252 case eStateConnected: 253 case eStateAttaching: 254 case eStateLaunching: 255 case eStateDetached: 256 case eStateExited: 257 case eStateUnloaded: 258 if (GetFlags().Test(CommandObject::eFlagProcessMustBeLaunched)) 259 { 260 result.AppendError ("Process must be launched."); 261 result.SetStatus (eReturnStatusFailed); 262 return false; 263 } 264 break; 265 266 case eStateRunning: 267 case eStateStepping: 268 if (GetFlags().Test(CommandObject::eFlagProcessMustBePaused)) 269 { 270 result.AppendError ("Process is running. Use 'process interrupt' to pause execution."); 271 result.SetStatus (eReturnStatusFailed); 272 return false; 273 } 274 } 275 } 276 } 277 278 if (!ParseOptions (args, result)) 279 return false; 280 281 // Call the command-specific version of 'Execute', passing it the already processed arguments. 282 return Execute (args, result); 283 } 284 285 class CommandDictCommandPartialMatch 286 { 287 public: 288 CommandDictCommandPartialMatch (const char *match_str) 289 { 290 m_match_str = match_str; 291 } 292 bool operator() (const std::pair<std::string, lldb::CommandObjectSP> map_element) const 293 { 294 // A NULL or empty string matches everything. 295 if (m_match_str == NULL || *m_match_str == '\0') 296 return 1; 297 298 size_t found = map_element.first.find (m_match_str, 0); 299 if (found == std::string::npos) 300 return 0; 301 else 302 return found == 0; 303 } 304 305 private: 306 const char *m_match_str; 307 }; 308 309 int 310 CommandObject::AddNamesMatchingPartialString (CommandObject::CommandMap &in_map, const char *cmd_str, 311 StringList &matches) 312 { 313 int number_added = 0; 314 CommandDictCommandPartialMatch matcher(cmd_str); 315 316 CommandObject::CommandMap::iterator matching_cmds = std::find_if (in_map.begin(), in_map.end(), matcher); 317 318 while (matching_cmds != in_map.end()) 319 { 320 ++number_added; 321 matches.AppendString((*matching_cmds).first.c_str()); 322 matching_cmds = std::find_if (++matching_cmds, in_map.end(), matcher);; 323 } 324 return number_added; 325 } 326 327 int 328 CommandObject::HandleCompletion 329 ( 330 Args &input, 331 int &cursor_index, 332 int &cursor_char_position, 333 int match_start_point, 334 int max_return_elements, 335 bool &word_complete, 336 StringList &matches 337 ) 338 { 339 // Default implmentation of WantsCompletion() is !WantsRawCommandString(). 340 // Subclasses who want raw command string but desire, for example, 341 // argument completion should override WantsCompletion() to return true, 342 // instead. 343 if (WantsRawCommandString() && !WantsCompletion()) 344 { 345 // FIXME: Abstract telling the completion to insert the completion character. 346 matches.Clear(); 347 return -1; 348 } 349 else 350 { 351 // Can we do anything generic with the options? 352 Options *cur_options = GetOptions(); 353 CommandReturnObject result; 354 OptionElementVector opt_element_vector; 355 356 if (cur_options != NULL) 357 { 358 // Re-insert the dummy command name string which will have been 359 // stripped off: 360 input.Unshift ("dummy-string"); 361 cursor_index++; 362 363 364 // I stick an element on the end of the input, because if the last element is 365 // option that requires an argument, getopt_long will freak out. 366 367 input.AppendArgument ("<FAKE-VALUE>"); 368 369 input.ParseArgsForCompletion (*cur_options, opt_element_vector, cursor_index); 370 371 input.DeleteArgumentAtIndex(input.GetArgumentCount() - 1); 372 373 bool handled_by_options; 374 handled_by_options = cur_options->HandleOptionCompletion (input, 375 opt_element_vector, 376 cursor_index, 377 cursor_char_position, 378 match_start_point, 379 max_return_elements, 380 word_complete, 381 matches); 382 if (handled_by_options) 383 return matches.GetSize(); 384 } 385 386 // If we got here, the last word is not an option or an option argument. 387 return HandleArgumentCompletion (input, 388 cursor_index, 389 cursor_char_position, 390 opt_element_vector, 391 match_start_point, 392 max_return_elements, 393 word_complete, 394 matches); 395 } 396 } 397 398 bool 399 CommandObject::HelpTextContainsWord (const char *search_word) 400 { 401 const char *short_help; 402 const char *long_help; 403 const char *syntax_help; 404 std::string options_usage_help; 405 406 407 bool found_word = false; 408 409 short_help = GetHelp(); 410 long_help = GetHelpLong(); 411 syntax_help = GetSyntax(); 412 413 if (strcasestr (short_help, search_word)) 414 found_word = true; 415 else if (strcasestr (long_help, search_word)) 416 found_word = true; 417 else if (strcasestr (syntax_help, search_word)) 418 found_word = true; 419 420 if (!found_word 421 && GetOptions() != NULL) 422 { 423 StreamString usage_help; 424 GetOptions()->GenerateOptionUsage (usage_help, this); 425 if (usage_help.GetSize() > 0) 426 { 427 const char *usage_text = usage_help.GetData(); 428 if (strcasestr (usage_text, search_word)) 429 found_word = true; 430 } 431 } 432 433 return found_word; 434 } 435 436 int 437 CommandObject::GetNumArgumentEntries () 438 { 439 return m_arguments.size(); 440 } 441 442 CommandObject::CommandArgumentEntry * 443 CommandObject::GetArgumentEntryAtIndex (int idx) 444 { 445 if (idx < m_arguments.size()) 446 return &(m_arguments[idx]); 447 448 return NULL; 449 } 450 451 CommandObject::ArgumentTableEntry * 452 CommandObject::FindArgumentDataByType (CommandArgumentType arg_type) 453 { 454 const ArgumentTableEntry *table = CommandObject::GetArgumentTable(); 455 456 for (int i = 0; i < eArgTypeLastArg; ++i) 457 if (table[i].arg_type == arg_type) 458 return (ArgumentTableEntry *) &(table[i]); 459 460 return NULL; 461 } 462 463 void 464 CommandObject::GetArgumentHelp (Stream &str, CommandArgumentType arg_type, CommandInterpreter &interpreter) 465 { 466 const ArgumentTableEntry* table = CommandObject::GetArgumentTable(); 467 ArgumentTableEntry *entry = (ArgumentTableEntry *) &(table[arg_type]); 468 469 // The table is *supposed* to be kept in arg_type order, but someone *could* have messed it up... 470 471 if (entry->arg_type != arg_type) 472 entry = CommandObject::FindArgumentDataByType (arg_type); 473 474 if (!entry) 475 return; 476 477 StreamString name_str; 478 name_str.Printf ("<%s>", entry->arg_name); 479 480 if (entry->help_function) 481 { 482 const char* help_text = entry->help_function(); 483 if (!entry->help_function.self_formatting) 484 { 485 interpreter.OutputFormattedHelpText (str, name_str.GetData(), "--", help_text, 486 name_str.GetSize()); 487 } 488 else 489 { 490 interpreter.OutputHelpText(str, name_str.GetData(), "--", help_text, 491 name_str.GetSize()); 492 } 493 } 494 else 495 interpreter.OutputFormattedHelpText (str, name_str.GetData(), "--", entry->help_text, name_str.GetSize()); 496 } 497 498 const char * 499 CommandObject::GetArgumentName (CommandArgumentType arg_type) 500 { 501 ArgumentTableEntry *entry = (ArgumentTableEntry *) &(CommandObject::GetArgumentTable()[arg_type]); 502 503 // The table is *supposed* to be kept in arg_type order, but someone *could* have messed it up... 504 505 if (entry->arg_type != arg_type) 506 entry = CommandObject::FindArgumentDataByType (arg_type); 507 508 if (entry) 509 return entry->arg_name; 510 511 StreamString str; 512 str << "Arg name for type (" << arg_type << ") not in arg table!"; 513 return str.GetData(); 514 } 515 516 bool 517 CommandObject::IsPairType (ArgumentRepetitionType arg_repeat_type) 518 { 519 if ((arg_repeat_type == eArgRepeatPairPlain) 520 || (arg_repeat_type == eArgRepeatPairOptional) 521 || (arg_repeat_type == eArgRepeatPairPlus) 522 || (arg_repeat_type == eArgRepeatPairStar) 523 || (arg_repeat_type == eArgRepeatPairRange) 524 || (arg_repeat_type == eArgRepeatPairRangeOptional)) 525 return true; 526 527 return false; 528 } 529 530 static CommandObject::CommandArgumentEntry 531 OptSetFiltered(uint32_t opt_set_mask, CommandObject::CommandArgumentEntry &cmd_arg_entry) 532 { 533 CommandObject::CommandArgumentEntry ret_val; 534 for (unsigned i = 0; i < cmd_arg_entry.size(); ++i) 535 if (opt_set_mask & cmd_arg_entry[i].arg_opt_set_association) 536 ret_val.push_back(cmd_arg_entry[i]); 537 return ret_val; 538 } 539 540 // Default parameter value of opt_set_mask is LLDB_OPT_SET_ALL, which means take 541 // all the argument data into account. On rare cases where some argument sticks 542 // with certain option sets, this function returns the option set filtered args. 543 void 544 CommandObject::GetFormattedCommandArguments (Stream &str, uint32_t opt_set_mask) 545 { 546 int num_args = m_arguments.size(); 547 for (int i = 0; i < num_args; ++i) 548 { 549 if (i > 0) 550 str.Printf (" "); 551 CommandArgumentEntry arg_entry = 552 opt_set_mask == LLDB_OPT_SET_ALL ? m_arguments[i] 553 : OptSetFiltered(opt_set_mask, m_arguments[i]); 554 int num_alternatives = arg_entry.size(); 555 556 if ((num_alternatives == 2) 557 && IsPairType (arg_entry[0].arg_repetition)) 558 { 559 const char *first_name = GetArgumentName (arg_entry[0].arg_type); 560 const char *second_name = GetArgumentName (arg_entry[1].arg_type); 561 switch (arg_entry[0].arg_repetition) 562 { 563 case eArgRepeatPairPlain: 564 str.Printf ("<%s> <%s>", first_name, second_name); 565 break; 566 case eArgRepeatPairOptional: 567 str.Printf ("[<%s> <%s>]", first_name, second_name); 568 break; 569 case eArgRepeatPairPlus: 570 str.Printf ("<%s> <%s> [<%s> <%s> [...]]", first_name, second_name, first_name, second_name); 571 break; 572 case eArgRepeatPairStar: 573 str.Printf ("[<%s> <%s> [<%s> <%s> [...]]]", first_name, second_name, first_name, second_name); 574 break; 575 case eArgRepeatPairRange: 576 str.Printf ("<%s_1> <%s_1> ... <%s_n> <%s_n>", first_name, second_name, first_name, second_name); 577 break; 578 case eArgRepeatPairRangeOptional: 579 str.Printf ("[<%s_1> <%s_1> ... <%s_n> <%s_n>]", first_name, second_name, first_name, second_name); 580 break; 581 // Explicitly test for all the rest of the cases, so if new types get added we will notice the 582 // missing case statement(s). 583 case eArgRepeatPlain: 584 case eArgRepeatOptional: 585 case eArgRepeatPlus: 586 case eArgRepeatStar: 587 case eArgRepeatRange: 588 // These should not be reached, as they should fail the IsPairType test above. 589 break; 590 } 591 } 592 else 593 { 594 StreamString names; 595 for (int j = 0; j < num_alternatives; ++j) 596 { 597 if (j > 0) 598 names.Printf (" | "); 599 names.Printf ("%s", GetArgumentName (arg_entry[j].arg_type)); 600 } 601 switch (arg_entry[0].arg_repetition) 602 { 603 case eArgRepeatPlain: 604 str.Printf ("<%s>", names.GetData()); 605 break; 606 case eArgRepeatPlus: 607 str.Printf ("<%s> [<%s> [...]]", names.GetData(), names.GetData()); 608 break; 609 case eArgRepeatStar: 610 str.Printf ("[<%s> [<%s> [...]]]", names.GetData(), names.GetData()); 611 break; 612 case eArgRepeatOptional: 613 str.Printf ("[<%s>]", names.GetData()); 614 break; 615 case eArgRepeatRange: 616 str.Printf ("<%s_1> .. <%s_n>", names.GetData(), names.GetData()); 617 break; 618 // Explicitly test for all the rest of the cases, so if new types get added we will notice the 619 // missing case statement(s). 620 case eArgRepeatPairPlain: 621 case eArgRepeatPairOptional: 622 case eArgRepeatPairPlus: 623 case eArgRepeatPairStar: 624 case eArgRepeatPairRange: 625 case eArgRepeatPairRangeOptional: 626 // These should not be hit, as they should pass the IsPairType test above, and control should 627 // have gone into the other branch of the if statement. 628 break; 629 } 630 } 631 } 632 } 633 634 CommandArgumentType 635 CommandObject::LookupArgumentName (const char *arg_name) 636 { 637 CommandArgumentType return_type = eArgTypeLastArg; 638 639 std::string arg_name_str (arg_name); 640 size_t len = arg_name_str.length(); 641 if (arg_name[0] == '<' 642 && arg_name[len-1] == '>') 643 arg_name_str = arg_name_str.substr (1, len-2); 644 645 const ArgumentTableEntry *table = GetArgumentTable(); 646 for (int i = 0; i < eArgTypeLastArg; ++i) 647 if (arg_name_str.compare (table[i].arg_name) == 0) 648 return_type = g_arguments_data[i].arg_type; 649 650 return return_type; 651 } 652 653 static const char * 654 BreakpointIDHelpTextCallback () 655 { 656 return "Breakpoint ID's consist major and minor numbers; the major number " 657 "corresponds to the single entity that was created with a 'breakpoint set' " 658 "command; the minor numbers correspond to all the locations that were actually " 659 "found/set based on the major breakpoint. A full breakpoint ID might look like " 660 "3.14, meaning the 14th location set for the 3rd breakpoint. You can specify " 661 "all the locations of a breakpoint by just indicating the major breakpoint " 662 "number. A valid breakpoint id consists either of just the major id number, " 663 "or the major number, a dot, and the location number (e.g. 3 or 3.2 could " 664 "both be valid breakpoint ids)."; 665 } 666 667 static const char * 668 BreakpointIDRangeHelpTextCallback () 669 { 670 return "A 'breakpoint id list' is a manner of specifying multiple breakpoints. " 671 "This can be done through several mechanisms. The easiest way is to just " 672 "enter a space-separated list of breakpoint ids. To specify all the " 673 "breakpoint locations under a major breakpoint, you can use the major " 674 "breakpoint number followed by '.*', eg. '5.*' means all the locations under " 675 "breakpoint 5. You can also indicate a range of breakpoints by using " 676 "<start-bp-id> - <end-bp-id>. The start-bp-id and end-bp-id for a range can " 677 "be any valid breakpoint ids. It is not legal, however, to specify a range " 678 "using specific locations that cross major breakpoint numbers. I.e. 3.2 - 3.7" 679 " is legal; 2 - 5 is legal; but 3.2 - 4.4 is not legal."; 680 } 681 682 static const char * 683 GDBFormatHelpTextCallback () 684 { 685 return "A GDB format consists of a repeat count, a format letter and a size letter. " 686 "The repeat count is optional and defaults to 1. The format letter is optional " 687 "and defaults to the previous format that was used. The size letter is optional " 688 "and defaults to the previous size that was used.\n" 689 "\n" 690 "Format letters include:\n" 691 "o - octal\n" 692 "x - hexadecimal\n" 693 "d - decimal\n" 694 "u - unsigned decimal\n" 695 "t - binary\n" 696 "f - float\n" 697 "a - address\n" 698 "i - instruction\n" 699 "c - char\n" 700 "s - string\n" 701 "T - OSType\n" 702 "A - float as hex\n" 703 "\n" 704 "Size letters include:\n" 705 "b - 1 byte (byte)\n" 706 "h - 2 bytes (halfword)\n" 707 "w - 4 bytes (word)\n" 708 "g - 8 bytes (giant)\n" 709 "\n" 710 "Example formats:\n" 711 "32xb - show 32 1 byte hexadecimal integer values\n" 712 "16xh - show 16 2 byte hexadecimal integer values\n" 713 "64 - show 64 2 byte hexadecimal integer values (format and size from the last format)\n" 714 "dw - show 1 4 byte decimal integer value\n" 715 ; 716 } 717 718 static const char * 719 FormatHelpTextCallback () 720 { 721 722 static char* help_text_ptr = NULL; 723 724 if (help_text_ptr) 725 return help_text_ptr; 726 727 StreamString sstr; 728 sstr << "One of the format names (or one-character names) that can be used to show a variable's value:\n"; 729 for (Format f = eFormatDefault; f < kNumFormats; f = Format(f+1)) 730 { 731 if (f != eFormatDefault) 732 sstr.PutChar('\n'); 733 734 char format_char = FormatManager::GetFormatAsFormatChar(f); 735 if (format_char) 736 sstr.Printf("'%c' or ", format_char); 737 738 sstr.Printf ("\"%s\"", FormatManager::GetFormatAsCString(f)); 739 } 740 741 sstr.Flush(); 742 743 std::string data = sstr.GetString(); 744 745 help_text_ptr = new char[data.length()+1]; 746 747 data.copy(help_text_ptr, data.length()); 748 749 return help_text_ptr; 750 } 751 752 static const char * 753 SummaryStringHelpTextCallback() 754 { 755 return 756 "A summary string is a way to extract information from variables in order to present them using a summary.\n" 757 "Summary strings contain static text, variables, scopes and control sequences:\n" 758 " - Static text can be any sequence of non-special characters, i.e. anything but '{', '}', '$', or '\\'.\n" 759 " - Variables are sequences of characters beginning with ${, ending with } and that contain symbols in the format described below.\n" 760 " - Scopes are any sequence of text between { and }. Anything included in a scope will only appear in the output summary if there were no errors.\n" 761 " - Control sequences are the usual C/C++ '\\a', '\\n', ..., plus '\\$', '\\{' and '\\}'.\n" 762 "A summary string works by copying static text verbatim, turning control sequences into their character counterpart, expanding variables and trying to expand scopes.\n" 763 "A variable is expanded by giving it a value other than its textual representation, and the way this is done depends on what comes after the ${ marker.\n" 764 "The most common sequence if ${var followed by an expression path, which is the text one would type to access a member of an aggregate types, given a variable of that type" 765 " (e.g. if type T has a member named x, which has a member named y, and if t is of type T, the expression path would be .x.y and the way to fit that into a summary string would be" 766 " ${var.x.y}). You can also use ${*var followed by an expression path and in that case the object referred by the path will be dereferenced before being displayed." 767 " If the object is not a pointer, doing so will cause an error. For additional details on expression paths, you can type 'help expr-path'. \n" 768 "By default, summary strings attempt to display the summary for any variable they reference, and if that fails the value. If neither can be shown, nothing is displayed." 769 "In a summary string, you can also use an array index [n], or a slice-like range [n-m]. This can have two different meanings depending on what kind of object the expression" 770 " path refers to:\n" 771 " - if it is a scalar type (any basic type like int, float, ...) the expression is a bitfield, i.e. the bits indicated by the indexing operator are extracted out of the number" 772 " and displayed as an individual variable\n" 773 " - if it is an array or pointer the array items indicated by the indexing operator are shown as the result of the variable. if the expression is an array, real array items are" 774 " printed; if it is a pointer, the pointer-as-array syntax is used to obtain the values (this means, the latter case can have no range checking)\n" 775 "If you are trying to display an array for which the size is known, you can also use [] instead of giving an exact range. This has the effect of showing items 0 thru size - 1.\n" 776 "Additionally, a variable can contain an (optional) format code, as in ${var.x.y%code}, where code can be any of the valid formats described in 'help format', or one of the" 777 " special symbols only allowed as part of a variable:\n" 778 " %V: show the value of the object by default\n" 779 " %S: show the summary of the object by default\n" 780 " %@: show the runtime-provided object description (for Objective-C, it calls NSPrintForDebugger; for C/C++ it does nothing)\n" 781 " %L: show the location of the object (memory address or a register name)\n" 782 " %#: show the number of children of the object\n" 783 " %T: show the type of the object\n" 784 "Another variable that you can use in summary strings is ${svar . This sequence works exactly like ${var, including the fact that ${*svar is an allowed sequence, but uses" 785 " the object's synthetic children provider instead of the actual objects. For instance, if you are using STL synthetic children providers, the following summary string would" 786 " count the number of actual elements stored in an std::list:\n" 787 "type summary add -s \"${svar%#}\" -x \"std::list<\""; 788 } 789 790 static const char * 791 ExprPathHelpTextCallback() 792 { 793 return 794 "An expression path is the sequence of symbols that is used in C/C++ to access a member variable of an aggregate object (class).\n" 795 "For instance, given a class:\n" 796 " class foo {\n" 797 " int a;\n" 798 " int b; .\n" 799 " foo* next;\n" 800 " };\n" 801 "the expression to read item b in the item pointed to by next for foo aFoo would be aFoo.next->b.\n" 802 "Given that aFoo could just be any object of type foo, the string '.next->b' is the expression path, because it can be attached to any foo instance to achieve the effect.\n" 803 "Expression paths in LLDB include dot (.) and arrow (->) operators, and most commands using expression paths have ways to also accept the star (*) operator.\n" 804 "The meaning of these operators is the same as the usual one given to them by the C/C++ standards.\n" 805 "LLDB also has support for indexing ([ ]) in expression paths, and extends the traditional meaning of the square brackets operator to allow bitfield extraction:\n" 806 "for objects of native types (int, float, char, ...) saying '[n-m]' as an expression path (where n and m are any positive integers, e.g. [3-5]) causes LLDB to extract" 807 " bits n thru m from the value of the variable. If n == m, [n] is also allowed as a shortcut syntax. For arrays and pointers, expression paths can only contain one index" 808 " and the meaning of the operation is the same as the one defined by C/C++ (item extraction). Some commands extend bitfield-like syntax for arrays and pointers with the" 809 " meaning of array slicing (taking elements n thru m inside the array or pointed-to memory)."; 810 } 811 812 void 813 CommandObject::AddIDsArgumentData(CommandArgumentEntry &arg, CommandArgumentType ID, CommandArgumentType IDRange) 814 { 815 CommandArgumentData id_arg; 816 CommandArgumentData id_range_arg; 817 818 // Create the first variant for the first (and only) argument for this command. 819 id_arg.arg_type = ID; 820 id_arg.arg_repetition = eArgRepeatOptional; 821 822 // Create the second variant for the first (and only) argument for this command. 823 id_range_arg.arg_type = IDRange; 824 id_range_arg.arg_repetition = eArgRepeatOptional; 825 826 // The first (and only) argument for this command could be either an id or an id_range. 827 // Push both variants into the entry for the first argument for this command. 828 arg.push_back(id_arg); 829 arg.push_back(id_range_arg); 830 } 831 832 const char * 833 CommandObject::GetArgumentTypeAsCString (const lldb::CommandArgumentType arg_type) 834 { 835 if (arg_type >=0 && arg_type < eArgTypeLastArg) 836 return g_arguments_data[arg_type].arg_name; 837 return NULL; 838 839 } 840 841 const char * 842 CommandObject::GetArgumentDescriptionAsCString (const lldb::CommandArgumentType arg_type) 843 { 844 if (arg_type >=0 && arg_type < eArgTypeLastArg) 845 return g_arguments_data[arg_type].help_text; 846 return NULL; 847 } 848 849 static 850 const char *arch_helper() 851 { 852 static StreamString g_archs_help; 853 if (g_archs_help.Empty()) 854 { 855 StringList archs; 856 ArchSpec::AutoComplete(NULL, archs); 857 g_archs_help.Printf("These are the supported architecture names:\n"); 858 archs.Join("\n", g_archs_help); 859 } 860 return g_archs_help.GetData(); 861 } 862 863 CommandObject::ArgumentTableEntry 864 CommandObject::g_arguments_data[] = 865 { 866 { eArgTypeAddress, "address", CommandCompletions::eNoCompletion, { NULL, false }, "A valid address in the target program's execution space." }, 867 { eArgTypeAliasName, "alias-name", CommandCompletions::eNoCompletion, { NULL, false }, "The name of an abbreviation (alias) for a debugger command." }, 868 { eArgTypeAliasOptions, "options-for-aliased-command", CommandCompletions::eNoCompletion, { NULL, false }, "Command options to be used as part of an alias (abbreviation) definition. (See 'help commands alias' for more information.)" }, 869 { eArgTypeArchitecture, "arch", CommandCompletions::eArchitectureCompletion, { arch_helper, true }, "The architecture name, e.g. i386 or x86_64." }, 870 { eArgTypeBoolean, "boolean", CommandCompletions::eNoCompletion, { NULL, false }, "A Boolean value: 'true' or 'false'" }, 871 { eArgTypeBreakpointID, "breakpt-id", CommandCompletions::eNoCompletion, { BreakpointIDHelpTextCallback, false }, NULL }, 872 { eArgTypeBreakpointIDRange, "breakpt-id-list", CommandCompletions::eNoCompletion, { BreakpointIDRangeHelpTextCallback, false }, NULL }, 873 { eArgTypeByteSize, "byte-size", CommandCompletions::eNoCompletion, { NULL, false }, "Number of bytes to use." }, 874 { eArgTypeClassName, "class-name", CommandCompletions::eNoCompletion, { NULL, false }, "Then name of a class from the debug information in the program." }, 875 { eArgTypeCommandName, "cmd-name", CommandCompletions::eNoCompletion, { NULL, false }, "A debugger command (may be multiple words), without any options or arguments." }, 876 { eArgTypeCount, "count", CommandCompletions::eNoCompletion, { NULL, false }, "An unsigned integer." }, 877 { eArgTypeEndAddress, "end-address", CommandCompletions::eNoCompletion, { NULL, false }, "Help text goes here." }, 878 { eArgTypeExpression, "expr", CommandCompletions::eNoCompletion, { NULL, false }, "Help text goes here." }, 879 { eArgTypeExpressionPath, "expr-path", CommandCompletions::eNoCompletion, { ExprPathHelpTextCallback, true }, NULL }, 880 { eArgTypeExprFormat, "expression-format", CommandCompletions::eNoCompletion, { NULL, false }, "[ [bool|b] | [bin] | [char|c] | [oct|o] | [dec|i|d|u] | [hex|x] | [float|f] | [cstr|s] ]" }, 881 { eArgTypeFilename, "filename", CommandCompletions::eDiskFileCompletion, { NULL, false }, "The name of a file (can include path)." }, 882 { eArgTypeFormat, "format", CommandCompletions::eNoCompletion, { FormatHelpTextCallback, true }, NULL }, 883 { eArgTypeFrameIndex, "frame-index", CommandCompletions::eNoCompletion, { NULL, false }, "Index into a thread's list of frames." }, 884 { eArgTypeFullName, "fullname", CommandCompletions::eNoCompletion, { NULL, false }, "Help text goes here." }, 885 { eArgTypeFunctionName, "function-name", CommandCompletions::eNoCompletion, { NULL, false }, "The name of a function." }, 886 { eArgTypeGDBFormat, "gdb-format", CommandCompletions::eNoCompletion, { GDBFormatHelpTextCallback, true }, NULL }, 887 { eArgTypeIndex, "index", CommandCompletions::eNoCompletion, { NULL, false }, "An index into a list." }, 888 { eArgTypeLanguage, "language", CommandCompletions::eNoCompletion, { NULL, false }, "A source language name." }, 889 { eArgTypeLineNum, "linenum", CommandCompletions::eNoCompletion, { NULL, false }, "Line number in a source file." }, 890 { eArgTypeLogCategory, "log-category", CommandCompletions::eNoCompletion, { NULL, false }, "The name of a category within a log channel, e.g. all (try \"log list\" to see a list of all channels and their categories." }, 891 { eArgTypeLogChannel, "log-channel", CommandCompletions::eNoCompletion, { NULL, false }, "The name of a log channel, e.g. process.gdb-remote (try \"log list\" to see a list of all channels and their categories)." }, 892 { eArgTypeMethod, "method", CommandCompletions::eNoCompletion, { NULL, false }, "A C++ method name." }, 893 { eArgTypeName, "name", CommandCompletions::eNoCompletion, { NULL, false }, "Help text goes here." }, 894 { eArgTypeNewPathPrefix, "new-path-prefix", CommandCompletions::eNoCompletion, { NULL, false }, "Help text goes here." }, 895 { eArgTypeNumLines, "num-lines", CommandCompletions::eNoCompletion, { NULL, false }, "The number of lines to use." }, 896 { eArgTypeNumberPerLine, "number-per-line", CommandCompletions::eNoCompletion, { NULL, false }, "The number of items per line to display." }, 897 { eArgTypeOffset, "offset", CommandCompletions::eNoCompletion, { NULL, false }, "Help text goes here." }, 898 { eArgTypeOldPathPrefix, "old-path-prefix", CommandCompletions::eNoCompletion, { NULL, false }, "Help text goes here." }, 899 { eArgTypeOneLiner, "one-line-command", CommandCompletions::eNoCompletion, { NULL, false }, "A command that is entered as a single line of text." }, 900 { eArgTypePath, "path", CommandCompletions::eNoCompletion, { NULL, false }, "Help text goes here." }, 901 { eArgTypePid, "pid", CommandCompletions::eNoCompletion, { NULL, false }, "The process ID number." }, 902 { eArgTypePlugin, "plugin", CommandCompletions::eNoCompletion, { NULL, false }, "Help text goes here." }, 903 { eArgTypeProcessName, "process-name", CommandCompletions::eNoCompletion, { NULL, false }, "The name of the process." }, 904 { eArgTypePythonClass, "python-class", CommandCompletions::eNoCompletion, { NULL, false }, "The name of a Python class." }, 905 { eArgTypePythonFunction, "python-function", CommandCompletions::eNoCompletion, { NULL, false }, "The name of a Python function." }, 906 { eArgTypePythonScript, "python-script", CommandCompletions::eNoCompletion, { NULL, false }, "Source code written in Python." }, 907 { eArgTypeQueueName, "queue-name", CommandCompletions::eNoCompletion, { NULL, false }, "The name of the thread queue." }, 908 { eArgTypeRegisterName, "register-name", CommandCompletions::eNoCompletion, { NULL, false }, "A register name." }, 909 { eArgTypeRegularExpression, "regular-expression", CommandCompletions::eNoCompletion, { NULL, false }, "A regular expression." }, 910 { eArgTypeRunArgs, "run-args", CommandCompletions::eNoCompletion, { NULL, false }, "Arguments to be passed to the target program when it starts executing." }, 911 { eArgTypeRunMode, "run-mode", CommandCompletions::eNoCompletion, { NULL, false }, "Help text goes here." }, 912 { eArgTypeScriptedCommandSynchronicity, "script-cmd-synchronicity", CommandCompletions::eNoCompletion, { NULL, false }, "The synchronicity to use to run scripted commands with regard to LLDB event system." }, 913 { eArgTypeScriptLang, "script-language", CommandCompletions::eNoCompletion, { NULL, false }, "The scripting language to be used for script-based commands. Currently only Python is valid." }, 914 { eArgTypeSearchWord, "search-word", CommandCompletions::eNoCompletion, { NULL, false }, "The word for which you wish to search for information about." }, 915 { eArgTypeSelector, "selector", CommandCompletions::eNoCompletion, { NULL, false }, "An Objective-C selector name." }, 916 { eArgTypeSettingIndex, "setting-index", CommandCompletions::eNoCompletion, { NULL, false }, "An index into a settings variable that is an array (try 'settings list' to see all the possible settings variables and their types)." }, 917 { eArgTypeSettingKey, "setting-key", CommandCompletions::eNoCompletion, { NULL, false }, "A key into a settings variables that is a dictionary (try 'settings list' to see all the possible settings variables and their types)." }, 918 { eArgTypeSettingPrefix, "setting-prefix", CommandCompletions::eNoCompletion, { NULL, false }, "The name of a settable internal debugger variable up to a dot ('.'), e.g. 'target.process.'" }, 919 { eArgTypeSettingVariableName, "setting-variable-name", CommandCompletions::eNoCompletion, { NULL, false }, "The name of a settable internal debugger variable. Type 'settings list' to see a complete list of such variables." }, 920 { eArgTypeShlibName, "shlib-name", CommandCompletions::eNoCompletion, { NULL, false }, "The name of a shared library." }, 921 { eArgTypeSourceFile, "source-file", CommandCompletions::eSourceFileCompletion, { NULL, false }, "The name of a source file.." }, 922 { eArgTypeSortOrder, "sort-order", CommandCompletions::eNoCompletion, { NULL, false }, "Specify a sort order when dumping lists." }, 923 { eArgTypeStartAddress, "start-address", CommandCompletions::eNoCompletion, { NULL, false }, "Help text goes here." }, 924 { eArgTypeSummaryString, "summary-string", CommandCompletions::eNoCompletion, { SummaryStringHelpTextCallback, true }, NULL }, 925 { eArgTypeSymbol, "symbol", CommandCompletions::eSymbolCompletion, { NULL, false }, "Any symbol name (function name, variable, argument, etc.)" }, 926 { eArgTypeThreadID, "thread-id", CommandCompletions::eNoCompletion, { NULL, false }, "Thread ID number." }, 927 { eArgTypeThreadIndex, "thread-index", CommandCompletions::eNoCompletion, { NULL, false }, "Index into the process' list of threads." }, 928 { eArgTypeThreadName, "thread-name", CommandCompletions::eNoCompletion, { NULL, false }, "The thread's name." }, 929 { eArgTypeUnsignedInteger, "unsigned-integer", CommandCompletions::eNoCompletion, { NULL, false }, "An unsigned integer." }, 930 { eArgTypeUnixSignal, "unix-signal", CommandCompletions::eNoCompletion, { NULL, false }, "A valid Unix signal name or number (e.g. SIGKILL, KILL or 9)." }, 931 { eArgTypeVarName, "variable-name", CommandCompletions::eNoCompletion, { NULL, false }, "The name of a variable in your program." }, 932 { eArgTypeValue, "value", CommandCompletions::eNoCompletion, { NULL, false }, "A value could be anything, depending on where and how it is used." }, 933 { eArgTypeWidth, "width", CommandCompletions::eNoCompletion, { NULL, false }, "Help text goes here." }, 934 { eArgTypeNone, "none", CommandCompletions::eNoCompletion, { NULL, false }, "No help available for this." }, 935 { eArgTypePlatform, "platform-name", CommandCompletions::ePlatformPluginCompletion, { NULL, false }, "The name of an installed platform plug-in . Type 'platform list' to see a complete list of installed platforms." }, 936 { eArgTypeWatchpointID, "watchpt-id", CommandCompletions::eNoCompletion, { NULL, false }, "Watchpoint IDs are positive integers." }, 937 { eArgTypeWatchpointIDRange, "watchpt-id-list", CommandCompletions::eNoCompletion, { NULL, false }, "For example, '1-3' or '1 to 3'." }, 938 { eArgTypeWatchType, "watch-type", CommandCompletions::eNoCompletion, { NULL, false }, "Specify the type for a watchpoint." } 939 }; 940 941 const CommandObject::ArgumentTableEntry* 942 CommandObject::GetArgumentTable () 943 { 944 // If this assertion fires, then the table above is out of date with the CommandArgumentType enumeration 945 assert ((sizeof (CommandObject::g_arguments_data) / sizeof (CommandObject::ArgumentTableEntry)) == eArgTypeLastArg); 946 return CommandObject::g_arguments_data; 947 } 948 949 950