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
14using namespace lldb;
15using namespace lldb_private;
16
17namespace lldb_private {
18llvm::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
36llvm::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
55llvm::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
74llvm::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
99llvm::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
136llvm::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(ch: '\n');
148
149 char format_char = FormatManager::GetFormatAsFormatChar(format: f);
150 if (format_char)
151 sstr.Printf(format: "'%c' or ", format_char);
152
153 sstr.Printf(format: "\"%s\"", FormatManager::GetFormatAsCString(format: f));
154 }
155
156 sstr.Flush();
157
158 help_text = std::string(sstr.GetString());
159
160 return help_text;
161}
162
163llvm::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(s&: sstr, prefix: " ", suffix: "\n");
173
174 sstr.Flush();
175
176 help_text = std::string(sstr.GetString());
177
178 return help_text;
179}
180
181llvm::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
256llvm::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
291llvm::StringRef arch_helper() {
292 static StreamString g_archs_help;
293 if (g_archs_help.Empty()) {
294 StringList archs;
295
296 ArchSpec::ListSupportedArchNames(list&: archs);
297 g_archs_help.Printf(format: "These are the supported architecture names:\n");
298 archs.Join(separator: "\n", strm&: g_archs_help);
299 }
300 return g_archs_help.GetString();
301}
302
303template <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
309template <> struct TableValidator<eArgTypeLastArg> {};
310
311TableValidator<0> validator;
312
313} // namespace lldb_private
314

source code of lldb/source/Commands/CommandOptionArgumentTable.cpp