LLDB  mainline
CommandOptionArgumentTable.cpp
Go to the documentation of this file.
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 
11 #include "lldb/Target/Language.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 
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 
312 
313 } // namespace lldb_private
lldb::Format
Format
Display format definitions.
Definition: lldb-enumerations.h:156
lldb_private::RegisterNameHelpTextCallback
llvm::StringRef RegisterNameHelpTextCallback()
Definition: CommandOptionArgumentTable.cpp:18
FormatManager.h
lldb_private::LanguageTypeHelpTextCallback
llvm::StringRef LanguageTypeHelpTextCallback()
Definition: CommandOptionArgumentTable.cpp:163
lldb_private::SummaryStringHelpTextCallback
llvm::StringRef SummaryStringHelpTextCallback()
Definition: CommandOptionArgumentTable.cpp:181
Language.h
lldb_private::arch_helper
llvm::StringRef arch_helper()
Definition: CommandOptionArgumentTable.cpp:291
lldb_private::StreamString::GetString
llvm::StringRef GetString() const
Definition: StreamString.cpp:51
lldb_private::BreakpointNameHelpTextCallback
llvm::StringRef BreakpointNameHelpTextCallback()
Definition: CommandOptionArgumentTable.cpp:74
lldb_private::TableValidator
Definition: CommandOptionArgumentTable.cpp:303
lldb::eArgTypeLastArg
@ eArgTypeLastArg
Definition: lldb-enumerations.h:615
StreamString.h
lldb_private::StringList
Definition: StringList.h:26
lldb_private::StreamString
Definition: StreamString.h:23
lldb_private::FormatHelpTextCallback
llvm::StringRef FormatHelpTextCallback()
Definition: CommandOptionArgumentTable.cpp:136
lldb_private::StreamString::Empty
bool Empty() const
Definition: StreamString.cpp:36
string
string(SUBSTRING ${p} 10 -1 pStripped) if($
Definition: Plugins/CMakeLists.txt:40
lldb::kNumFormats
@ kNumFormats
Definition: lldb-enumerations.h:203
lldb_private::Stream::PutChar
size_t PutChar(char ch)
Definition: Stream.cpp:104
lldb_private::BreakpointIDRangeHelpTextCallback
llvm::StringRef BreakpointIDRangeHelpTextCallback()
Definition: CommandOptionArgumentTable.cpp:55
lldb_private::ExprPathHelpTextCallback
llvm::StringRef ExprPathHelpTextCallback()
Definition: CommandOptionArgumentTable.cpp:256
lldb_private::GDBFormatHelpTextCallback
llvm::StringRef GDBFormatHelpTextCallback()
Definition: CommandOptionArgumentTable.cpp:99
lldb_private::BreakpointIDHelpTextCallback
llvm::StringRef BreakpointIDHelpTextCallback()
Definition: CommandOptionArgumentTable.cpp:36
lldb_private::Stream::Printf
size_t Printf(const char *format,...) __attribute__((format(printf
Output printf formatted output to the stream.
Definition: Stream.cpp:107
lldb_private
A class that represents a running process on the host machine.
Definition: SBCommandInterpreterRunOptions.h:16
lldb_private::StreamString::Flush
void Flush() override
Flush the stream.
Definition: StreamString.cpp:22
CommandOptionArgumentTable.h
lldb_private::validator
TableValidator< 0 > validator
Definition: CommandOptionArgumentTable.cpp:311
lldb_private::g_argument_table
static constexpr CommandObject::ArgumentTableEntry g_argument_table[]
Definition: CommandOptionArgumentTable.h:163
lldb_private::StringList::Join
void Join(const char *separator, Stream &strm)
Definition: StringList.cpp:92
lldb
Definition: SBAddress.h:15
lldb::eFormatDefault
@ eFormatDefault
Definition: lldb-enumerations.h:157