lldb/source/Commands/CommandOptionArgumentTable.cpp

   1 //===-- CommandOptionArgumentTable.cpp ------------------------------------===//
   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 #include "lldb/Interpreter/CommandOptionArgumentTable.h"
  10 #include "lldb/DataFormatters/FormatManager.h"
  11 #include "lldb/Target/Language.h"
  12 #include "lldb/Utility/StreamString.h"
  13
  14 using namespace lldb;
  15 using namespace lldb_private;
  16
  17 namespace lldb_private {
  18 llvm::StringRef RegisterNameHelpTextCallback() {
  19   return "Register names can be specified using the architecture specific "
  20          "names.  "
  21          "They can also be specified using generic names.  Not all generic "
  22          "entities have "
  23          "registers backing them on all architectures.  When they don't the "
  24          "generic name "
  25          "will return an error.\n"
  26          "The generic names defined in lldb are:\n"
  27          "\n"
  28          "pc       - program counter register\n"
  29          "ra       - return address register\n"
  30          "fp       - frame pointer register\n"
  31          "sp       - stack pointer register\n"
  32          "flags    - the flags register\n"
  33          "arg{1-6} - integer argument passing registers.\n";
  34 }
  35
  36 llvm::StringRef BreakpointIDHelpTextCallback() {
  37   return "Breakpoints are identified using major and minor numbers; the major "
  38          "number corresponds to the single entity that was created with a "
  39          "'breakpoint "
  40          "set' command; the minor numbers correspond to all the locations that "
  41          "were "
  42          "actually found/set based on the major breakpoint.  A full breakpoint "
  43          "ID might "
  44          "look like 3.14, meaning the 14th location set for the 3rd "
  45          "breakpoint.  You "
  46          "can specify all the locations of a breakpoint by just indicating the "
  47          "major "
  48          "breakpoint number. A valid breakpoint ID consists either of just the "
  49          "major "
  50          "number, or the major number followed by a dot and the location "
  51          "number (e.g. "
  52          "3 or 3.2 could both be valid breakpoint IDs.)";
  53 }
  54
  55 llvm::StringRef BreakpointIDRangeHelpTextCallback() {
  56   return "A 'breakpoint ID list' is a manner of specifying multiple "
  57          "breakpoints. "
  58          "This can be done through several mechanisms.  The easiest way is to "
  59          "just "
  60          "enter a space-separated list of breakpoint IDs.  To specify all the "
  61          "breakpoint locations under a major breakpoint, you can use the major "
  62          "breakpoint number followed by '.*', eg. '5.*' means all the "
  63          "locations under "
  64          "breakpoint 5.  You can also indicate a range of breakpoints by using "
  65          "<start-bp-id> - <end-bp-id>.  The start-bp-id and end-bp-id for a "
  66          "range can "
  67          "be any valid breakpoint IDs.  It is not legal, however, to specify a "
  68          "range "
  69          "using specific locations that cross major breakpoint numbers.  I.e. "
  70          "3.2 - 3.7"
  71          " is legal; 2 - 5 is legal; but 3.2 - 4.4 is not legal.";
  72 }
  73
  74 llvm::StringRef BreakpointNameHelpTextCallback() {
  75   return "A name that can be added to a breakpoint when it is created, or "
  76          "later "
  77          "on with the \"breakpoint name add\" command.  "
  78          "Breakpoint names can be used to specify breakpoints in all the "
  79          "places breakpoint IDs "
  80          "and breakpoint ID ranges can be used.  As such they provide a "
  81          "convenient way to group breakpoints, "
  82          "and to operate on breakpoints you create without having to track the "
  83          "breakpoint number.  "
  84          "Note, the attributes you set when using a breakpoint name in a "
  85          "breakpoint command don't "
  86          "adhere to the name, but instead are set individually on all the "
  87          "breakpoints currently tagged with that "
  88          "name.  Future breakpoints "
  89          "tagged with that name will not pick up the attributes previously "
  90          "given using that name.  "
  91          "In order to distinguish breakpoint names from breakpoint IDs and "
  92          "ranges, "
  93          "names must start with a letter from a-z or A-Z and cannot contain "
  94          "spaces, \".\" or \"-\".  "
  95          "Also, breakpoint names can only be applied to breakpoints, not to "
  96          "breakpoint locations.";
  97 }
  98
  99 llvm::StringRef GDBFormatHelpTextCallback() {
 100   return "A GDB format consists of a repeat count, a format letter and a size "
 101          "letter. "
 102          "The repeat count is optional and defaults to 1. The format letter is "
 103          "optional "
 104          "and defaults to the previous format that was used. The size letter "
 105          "is optional "
 106          "and defaults to the previous size that was used.\n"
 107          "\n"
 108          "Format letters include:\n"
 109          "o - octal\n"
 110          "x - hexadecimal\n"
 111          "d - decimal\n"
 112          "u - unsigned decimal\n"
 113          "t - binary\n"
 114          "f - float\n"
 115          "a - address\n"
 116          "i - instruction\n"
 117          "c - char\n"
 118          "s - string\n"
 119          "T - OSType\n"
 120          "A - float as hex\n"
 121          "\n"
 122          "Size letters include:\n"
 123          "b - 1 byte  (byte)\n"
 124          "h - 2 bytes (halfword)\n"
 125          "w - 4 bytes (word)\n"
 126          "g - 8 bytes (giant)\n"
 127          "\n"
 128          "Example formats:\n"
 129          "32xb - show 32 1 byte hexadecimal integer values\n"
 130          "16xh - show 16 2 byte hexadecimal integer values\n"
 131          "64   - show 64 2 byte hexadecimal integer values (format and size "
 132          "from the last format)\n"
 133          "dw   - show 1 4 byte decimal integer value\n";
 134 }
 135
 136 llvm::StringRef FormatHelpTextCallback() {
 137   static std::string help_text;
 138
 139   if (!help_text.empty())
 140     return help_text;
 141
 142   StreamString sstr;
 143   sstr << "One of the format names (or one-character names) that can be used "
 144           "to show a variable's value:\n";
 145   for (Format f = eFormatDefault; f < kNumFormats; f = Format(f + 1)) {
 146     if (f != eFormatDefault)
 147       sstr.PutChar('\n');
 148
 149     char format_char = FormatManager::GetFormatAsFormatChar(f);
 150     if (format_char)
 151       sstr.Printf("'%c' or ", format_char);
 152
 153     sstr.Printf("\"%s\"", FormatManager::GetFormatAsCString(f));
 154   }
 155
 156   sstr.Flush();
 157
 158   help_text = std::string(sstr.GetString());
 159
 160   return help_text;
 161 }
 162
 163 llvm::StringRef LanguageTypeHelpTextCallback() {
 164   static std::string help_text;
 165
 166   if (!help_text.empty())
 167     return help_text;
 168
 169   StreamString sstr;
 170   sstr << "One of the following languages:\n";
 171
 172   Language::PrintAllLanguages(sstr, "  ", "\n");
 173
 174   sstr.Flush();
 175
 176   help_text = std::string(sstr.GetString());
 177
 178   return help_text;
 179 }
 180
 181 llvm::StringRef SummaryStringHelpTextCallback() {
 182   return "A summary string is a way to extract information from variables in "
 183          "order to present them using a summary.\n"
 184          "Summary strings contain static text, variables, scopes and control "
 185          "sequences:\n"
 186          "  - Static text can be any sequence of non-special characters, i.e. "
 187          "anything but '{', '}', '$', or '\\'.\n"
 188          "  - Variables are sequences of characters beginning with ${, ending "
 189          "with } and that contain symbols in the format described below.\n"
 190          "  - Scopes are any sequence of text between { and }. Anything "
 191          "included in a scope will only appear in the output summary if there "
 192          "were no errors.\n"
 193          "  - Control sequences are the usual C/C++ '\\a', '\\n', ..., plus "
 194          "'\\$', '\\{' and '\\}'.\n"
 195          "A summary string works by copying static text verbatim, turning "
 196          "control sequences into their character counterpart, expanding "
 197          "variables and trying to expand scopes.\n"
 198          "A variable is expanded by giving it a value other than its textual "
 199          "representation, and the way this is done depends on what comes after "
 200          "the ${ marker.\n"
 201          "The most common sequence if ${var followed by an expression path, "
 202          "which is the text one would type to access a member of an aggregate "
 203          "types, given a variable of that type"
 204          " (e.g. if type T has a member named x, which has a member named y, "
 205          "and if t is of type T, the expression path would be .x.y and the way "
 206          "to fit that into a summary string would be"
 207          " ${var.x.y}). You can also use ${*var followed by an expression path "
 208          "and in that case the object referred by the path will be "
 209          "dereferenced before being displayed."
 210          " If the object is not a pointer, doing so will cause an error. For "
 211          "additional details on expression paths, you can type 'help "
 212          "expr-path'. \n"
 213          "By default, summary strings attempt to display the summary for any "
 214          "variable they reference, and if that fails the value. If neither can "
 215          "be shown, nothing is displayed."
 216          "In a summary string, you can also use an array index [n], or a "
 217          "slice-like range [n-m]. This can have two different meanings "
 218          "depending on what kind of object the expression"
 219          " path refers to:\n"
 220          "  - if it is a scalar type (any basic type like int, float, ...) the "
 221          "expression is a bitfield, i.e. the bits indicated by the indexing "
 222          "operator are extracted out of the number"
 223          " and displayed as an individual variable\n"
 224          "  - if it is an array or pointer the array items indicated by the "
 225          "indexing operator are shown as the result of the variable. if the "
 226          "expression is an array, real array items are"
 227          " printed; if it is a pointer, the pointer-as-array syntax is used to "
 228          "obtain the values (this means, the latter case can have no range "
 229          "checking)\n"
 230          "If you are trying to display an array for which the size is known, "
 231          "you can also use [] instead of giving an exact range. This has the "
 232          "effect of showing items 0 thru size - 1.\n"
 233          "Additionally, a variable can contain an (optional) format code, as "
 234          "in ${var.x.y%code}, where code can be any of the valid formats "
 235          "described in 'help format', or one of the"
 236          " special symbols only allowed as part of a variable:\n"
 237          "    %V: show the value of the object by default\n"
 238          "    %S: show the summary of the object by default\n"
 239          "    %@: show the runtime-provided object description (for "
 240          "Objective-C, it calls NSPrintForDebugger; for C/C++ it does "
 241          "nothing)\n"
 242          "    %L: show the location of the object (memory address or a "
 243          "register name)\n"
 244          "    %#: show the number of children of the object\n"
 245          "    %T: show the type of the object\n"
 246          "Another variable that you can use in summary strings is ${svar . "
 247          "This sequence works exactly like ${var, including the fact that "
 248          "${*svar is an allowed sequence, but uses"
 249          " the object's synthetic children provider instead of the actual "
 250          "objects. For instance, if you are using STL synthetic children "
 251          "providers, the following summary string would"
 252          " count the number of actual elements stored in an std::list:\n"
 253          "type summary add -s \"${svar%#}\" -x \"std::list<\"";
 254 }
 255
 256 llvm::StringRef ExprPathHelpTextCallback() {
 257   return "An expression path is the sequence of symbols that is used in C/C++ "
 258          "to access a member variable of an aggregate object (class).\n"
 259          "For instance, given a class:\n"
 260          "  class foo {\n"
 261          "      int a;\n"
 262          "      int b; .\n"
 263          "      foo* next;\n"
 264          "  };\n"
 265          "the expression to read item b in the item pointed to by next for foo "
 266          "aFoo would be aFoo.next->b.\n"
 267          "Given that aFoo could just be any object of type foo, the string "
 268          "'.next->b' is the expression path, because it can be attached to any "
 269          "foo instance to achieve the effect.\n"
 270          "Expression paths in LLDB include dot (.) and arrow (->) operators, "
 271          "and most commands using expression paths have ways to also accept "
 272          "the star (*) operator.\n"
 273          "The meaning of these operators is the same as the usual one given to "
 274          "them by the C/C++ standards.\n"
 275          "LLDB also has support for indexing ([ ]) in expression paths, and "
 276          "extends the traditional meaning of the square brackets operator to "
 277          "allow bitfield extraction:\n"
 278          "for objects of native types (int, float, char, ...) saying '[n-m]' "
 279          "as an expression path (where n and m are any positive integers, e.g. "
 280          "[3-5]) causes LLDB to extract"
 281          " bits n thru m from the value of the variable. If n == m, [n] is "
 282          "also allowed as a shortcut syntax. For arrays and pointers, "
 283          "expression paths can only contain one index"
 284          " and the meaning of the operation is the same as the one defined by "
 285          "C/C++ (item extraction). Some commands extend bitfield-like syntax "
 286          "for arrays and pointers with the"
 287          " meaning of array slicing (taking elements n thru m inside the array "
 288          "or pointed-to memory).";
 289 }
 290
 291 llvm::StringRef arch_helper() {
 292   static StreamString g_archs_help;
 293   if (g_archs_help.Empty()) {
 294     StringList archs;
 295
 296     ArchSpec::ListSupportedArchNames(archs);
 297     g_archs_help.Printf("These are the supported architecture names:\n");
 298     archs.Join("\n", g_archs_help);
 299   }
 300   return g_archs_help.GetString();
 301 }
 302
 303 template <int I> struct TableValidator : TableValidator<I + 1> {
 304   static_assert(
 305       g_argument_table[I].arg_type == I,
 306       "g_argument_table order doesn't match CommandArgumentType enumeration");
 307 };
 308
 309 template <> struct TableValidator<eArgTypeLastArg> {};
 310
 311 TableValidator<0> validator;
 312
 313 } // namespace lldb_private