• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 //===-- JSONUtils.h ---------------------------------------------*- C++ -*-===//
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 #ifndef LLDB_TOOLS_LLDB_VSCODE_JSONUTILS_H
10 #define LLDB_TOOLS_LLDB_VSCODE_JSONUTILS_H
11 
12 #include "VSCodeForward.h"
13 #include "lldb/API/SBModule.h"
14 #include "llvm/ADT/StringRef.h"
15 #include "llvm/Support/JSON.h"
16 #include <stdint.h>
17 
18 namespace lldb_vscode {
19 
20 /// Emplace a StringRef in a json::Object after enusring that the
21 /// string is valid UTF8. If not, first call llvm::json::fixUTF8
22 /// before emplacing.
23 ///
24 /// \param[in] obj
25 ///     A JSON object that we will attempt to emplace the value in
26 ///
27 /// \param[in] key
28 ///     The key to use when emplacing the value
29 ///
30 /// \param[in] str
31 ///     The string to emplace
32 void EmplaceSafeString(llvm::json::Object &obj, llvm::StringRef key,
33                        llvm::StringRef str);
34 
35 /// Extract simple values as a string.
36 ///
37 /// \param[in] value
38 ///     A JSON value to extract the string from.
39 ///
40 /// \return
41 ///     A llvm::StringRef that contains the string value, or an empty
42 ///     string if \a value isn't a string.
43 llvm::StringRef GetAsString(const llvm::json::Value &value);
44 
45 /// Extract the string value for the specified key from the
46 /// specified object.
47 ///
48 /// \param[in] obj
49 ///     A JSON object that we will attempt to extract the value from
50 ///
51 /// \param[in] key
52 ///     The key to use when extracting the value
53 ///
54 /// \return
55 ///     A llvm::StringRef that contains the string value for the
56 ///     specified \a key, or an empty string if there is no key that
57 ///     matches or if the value is not a string.
58 llvm::StringRef GetString(const llvm::json::Object &obj, llvm::StringRef key);
59 llvm::StringRef GetString(const llvm::json::Object *obj, llvm::StringRef key);
60 
61 /// Extract the unsigned integer value for the specified key from
62 /// the specified object.
63 ///
64 /// \param[in] obj
65 ///     A JSON object that we will attempt to extract the value from
66 ///
67 /// \param[in] key
68 ///     The key to use when extracting the value
69 ///
70 /// \return
71 ///     The unsigned integer value for the specified \a key, or
72 ///     \a fail_value  if there is no key that matches or if the
73 ///     value is not an integer.
74 uint64_t GetUnsigned(const llvm::json::Object &obj, llvm::StringRef key,
75                      uint64_t fail_value);
76 uint64_t GetUnsigned(const llvm::json::Object *obj, llvm::StringRef key,
77                      uint64_t fail_value);
78 
79 /// Extract the boolean value for the specified key from the
80 /// specified object.
81 ///
82 /// \param[in] obj
83 ///     A JSON object that we will attempt to extract the value from
84 ///
85 /// \param[in] key
86 ///     The key to use when extracting the value
87 ///
88 /// \return
89 ///     The boolean value for the specified \a key, or \a fail_value
90 ///     if there is no key that matches or if the value is not a
91 ///     boolean value of an integer.
92 bool GetBoolean(const llvm::json::Object &obj, llvm::StringRef key,
93                 bool fail_value);
94 bool GetBoolean(const llvm::json::Object *obj, llvm::StringRef key,
95                 bool fail_value);
96 
97 /// Extract the signed integer for the specified key from the
98 /// specified object.
99 ///
100 /// \param[in] obj
101 ///     A JSON object that we will attempt to extract the value from
102 ///
103 /// \param[in] key
104 ///     The key to use when extracting the value
105 ///
106 /// \return
107 ///     The signed integer value for the specified \a key, or
108 ///     \a fail_value if there is no key that matches or if the
109 ///     value is not an integer.
110 int64_t GetSigned(const llvm::json::Object &obj, llvm::StringRef key,
111                   int64_t fail_value);
112 int64_t GetSigned(const llvm::json::Object *obj, llvm::StringRef key,
113                   int64_t fail_value);
114 
115 /// Check if the specified key exists in the specified object.
116 ///
117 /// \param[in] obj
118 ///     A JSON object that we will attempt to extract the value from
119 ///
120 /// \param[in] key
121 ///     The key to check for
122 ///
123 /// \return
124 ///     \b True if the key exists in the \a obj, \b False otherwise.
125 bool ObjectContainsKey(const llvm::json::Object &obj, llvm::StringRef key);
126 
127 /// Extract an array of strings for the specified key from an object.
128 ///
129 /// String values in the array will be extracted without any quotes
130 /// around them. Numbers and Booleans will be converted into
131 /// strings. Any NULL, array or objects values in the array will be
132 /// ignored.
133 ///
134 /// \param[in] obj
135 ///     A JSON object that we will attempt to extract the array from
136 ///
137 /// \param[in] key
138 ///     The key to use when extracting the value
139 ///
140 /// \return
141 ///     An array of string values for the specified \a key, or
142 ///     \a fail_value if there is no key that matches or if the
143 ///     value is not an array or all items in the array are not
144 ///     strings, numbers or booleans.
145 std::vector<std::string> GetStrings(const llvm::json::Object *obj,
146                                     llvm::StringRef key);
147 
148 /// Fill a response object given the request object.
149 ///
150 /// The \a response object will get its "type" set to "response",
151 /// the "seq" set to zero, "response_seq" set to the "seq" value from
152 /// \a request, "command" set to the "command" from \a request,
153 /// and "success" set to true.
154 ///
155 /// \param[in] request
156 ///     The request object received from a call to VSCode::ReadJSON().
157 ///
158 /// \param[in,out] response
159 ///     An empty llvm::json::Object object that will be filled
160 ///     in as noted in description.
161 void FillResponse(const llvm::json::Object &request,
162                   llvm::json::Object &response);
163 
164 /// Emplace the string value from an SBValue into the supplied object
165 /// using \a key as the key that will contain the value.
166 ///
167 /// The value is what we will display in VS Code. Some SBValue objects
168 /// can have a value and/or a summary. If a value has both, we
169 /// combine the value and the summary into one string. If we only have a
170 /// value or summary, then that is considered the value. If there is
171 /// no value and no summary then the value is the type name followed by
172 /// the address of the type if it has an address.
173 ///
174 ///
175 /// \param[in] v
176 ///     A lldb::SBValue object to extract the string value from
177 ///
178 ///
179 /// \param[in] object
180 ///     The object to place the value object into
181 ///
182 ///
183 /// \param[in] key
184 ///     The key name to use when inserting the value object we create
185 void SetValueForKey(lldb::SBValue &v, llvm::json::Object &object,
186                     llvm::StringRef key);
187 
188 /// Converts \a bp to a JSON value and appends the first valid location to the
189 /// \a breakpoints array.
190 ///
191 /// \param[in] bp
192 ///     A LLDB breakpoint object which will get the first valid location
193 ///     extracted and converted into a JSON object in the \a breakpoints array
194 ///
195 /// \param[in] breakpoints
196 ///     A JSON array that will get a llvm::json::Value for \a bp
197 ///     appended to it.
198 ///
199 /// \param[in] request_path
200 ///     An optional source path to use when creating the "Source" object of this
201 ///     breakpoint. If not specified, the "Source" object is created from the
202 ///     breakpoint's address' LineEntry. It is useful to ensure the same source
203 ///     paths provided by the setBreakpoints request are returned to the IDE.
204 ///
205 /// \param[in] request_line
206 ///     An optional line to use when creating the "Breakpoint" object to append.
207 ///     It is used if the breakpoint has no valid locations.
208 ///     It is useful to ensure the same line
209 ///     provided by the setBreakpoints request are returned to the IDE as a
210 ///     fallback.
211 void AppendBreakpoint(lldb::SBBreakpoint &bp, llvm::json::Array &breakpoints,
212                       llvm::Optional<llvm::StringRef> request_path = llvm::None,
213                       llvm::Optional<uint32_t> request_line = llvm::None);
214 
215 /// Converts breakpoint location to a Visual Studio Code "Breakpoint"
216 ///
217 /// \param[in] bp
218 ///     A LLDB breakpoint object to convert into a JSON value
219 ///
220 /// \param[in] request_path
221 ///     An optional source path to use when creating the "Source" object of this
222 ///     breakpoint. If not specified, the "Source" object is created from the
223 ///     breakpoint's address' LineEntry. It is useful to ensure the same source
224 ///     paths provided by the setBreakpoints request are returned to the IDE.
225 ///
226 /// \param[in] request_line
227 ///     An optional line to use when creating the resulting "Breakpoint" object.
228 ///     It is used if the breakpoint has no valid locations.
229 ///     It is useful to ensure the same line
230 ///     provided by the setBreakpoints request are returned to the IDE as a
231 ///     fallback.
232 ///
233 /// \return
234 ///     A "Breakpoint" JSON object with that follows the formal JSON
235 ///     definition outlined by Microsoft.
236 llvm::json::Value
237 CreateBreakpoint(lldb::SBBreakpoint &bp,
238                  llvm::Optional<llvm::StringRef> request_path = llvm::None,
239                  llvm::Optional<uint32_t> request_line = llvm::None);
240 
241 /// Converts a LLDB module to a VS Code DAP module for use in "modules" events.
242 ///
243 /// \param[in] module
244 ///     A LLDB module object to convert into a JSON value
245 ///
246 /// \return
247 ///     A "Module" JSON object with that follows the formal JSON
248 ///     definition outlined by Microsoft.
249 llvm::json::Value CreateModule(lldb::SBModule &module);
250 
251 /// Create a "Event" JSON object using \a event_name as the event name
252 ///
253 /// \param[in] event_name
254 ///     The string value to use for the "event" key in the JSON object.
255 ///
256 /// \return
257 ///     A "Event" JSON object with that follows the formal JSON
258 ///     definition outlined by Microsoft.
259 llvm::json::Object CreateEventObject(const llvm::StringRef event_name);
260 
261 /// Create a "ExceptionBreakpointsFilter" JSON object as described in
262 /// the Visual Studio Code debug adaptor definition.
263 ///
264 /// \param[in] bp
265 ///     The exception breakpoint object to use
266 ///
267 /// \return
268 ///     A "ExceptionBreakpointsFilter" JSON object with that follows
269 ///     the formal JSON definition outlined by Microsoft.
270 llvm::json::Value
271 CreateExceptionBreakpointFilter(const ExceptionBreakpoint &bp);
272 
273 /// Create a "Scope" JSON object as described in the Visual Studio Code
274 /// debug adaptor definition.
275 ///
276 /// \param[in] name
277 ///     The value to place into the "name" key
278 //
279 /// \param[in] variablesReference
280 ///     The value to place into the "variablesReference" key
281 //
282 /// \param[in] namedVariables
283 ///     The value to place into the "namedVariables" key
284 //
285 /// \param[in] expensive
286 ///     The value to place into the "expensive" key
287 ///
288 /// \return
289 ///     A "Scope" JSON object with that follows the formal JSON
290 ///     definition outlined by Microsoft.
291 llvm::json::Value CreateScope(const llvm::StringRef name,
292                               int64_t variablesReference,
293                               int64_t namedVariables, bool expensive);
294 
295 /// Create a "Source" JSON object as described in the Visual Studio Code
296 /// debug adaptor definition.
297 ///
298 /// \param[in] line_entry
299 ///     The LLDB line table to use when populating out the "Source"
300 ///     object
301 ///
302 /// \return
303 ///     A "Source" JSON object with that follows the formal JSON
304 ///     definition outlined by Microsoft.
305 llvm::json::Value CreateSource(lldb::SBLineEntry &line_entry);
306 
307 /// Create a "Source" object for a given source path.
308 ///
309 /// \param[in] source_path
310 ///     The path to the source to use when creating the "Source" object.
311 ///
312 /// \return
313 ///     A "Source" JSON object that follows the formal JSON
314 ///     definition outlined by Microsoft.
315 llvm::json::Value CreateSource(llvm::StringRef source_path);
316 
317 /// Create a "Source" object for a given frame.
318 ///
319 /// When there is no source file information for a stack frame, we will
320 /// create disassembly for a function and store a permanent
321 /// "sourceReference" that contains the textual disassembly for a
322 /// function along with address to line information. The "Source" object
323 /// that is created will contain a "sourceReference" that the VSCode
324 /// protocol can later fetch as text in order to display disassembly.
325 /// The PC will be extracted from the frame and the disassembly line
326 /// within the source referred to by "sourceReference" will be filled
327 /// in.
328 ///
329 /// \param[in] frame
330 ///     The LLDB stack frame to use when populating out the "Source"
331 ///     object.
332 ///
333 /// \param[out] disasm_line
334 ///     The line within the "sourceReference" file that the PC from
335 ///     \a frame matches.
336 ///
337 /// \return
338 ///     A "Source" JSON object with that follows the formal JSON
339 ///     definition outlined by Microsoft.
340 llvm::json::Value CreateSource(lldb::SBFrame &frame, int64_t &disasm_line);
341 
342 /// Create a "StackFrame" object for a LLDB frame object.
343 ///
344 /// This function will fill in the following keys in the returned
345 /// object:
346 ///   "id" - the stack frame ID as an integer
347 ///   "name" - the function name as a string
348 ///   "source" - source file information as a "Source" VSCode object
349 ///   "line" - the source file line number as an integer
350 ///   "column" - the source file column number as an integer
351 ///
352 /// \param[in] frame
353 ///     The LLDB stack frame to use when populating out the "StackFrame"
354 ///     object.
355 ///
356 /// \return
357 ///     A "StackFrame" JSON object with that follows the formal JSON
358 ///     definition outlined by Microsoft.
359 llvm::json::Value CreateStackFrame(lldb::SBFrame &frame);
360 
361 /// Create a "Thread" object for a LLDB thread object.
362 ///
363 /// This function will fill in the following keys in the returned
364 /// object:
365 ///   "id" - the thread ID as an integer
366 ///   "name" - the thread name as a string which combines the LLDB
367 ///            thread index ID along with the string name of the thread
368 ///            from the OS if it has a name.
369 ///
370 /// \param[in] thread
371 ///     The LLDB thread to use when populating out the "Thread"
372 ///     object.
373 ///
374 /// \return
375 ///     A "Thread" JSON object with that follows the formal JSON
376 ///     definition outlined by Microsoft.
377 llvm::json::Value CreateThread(lldb::SBThread &thread);
378 
379 /// Create a "StoppedEvent" object for a LLDB thread object.
380 ///
381 /// This function will fill in the following keys in the returned
382 /// object's "body" object:
383 ///   "reason" - With a valid stop reason enumeration string value
384 ///              that Microsoft specifies
385 ///   "threadId" - The thread ID as an integer
386 ///   "description" - a stop description (like "breakpoint 12.3") as a
387 ///                   string
388 ///   "preserveFocusHint" - a boolean value that states if this thread
389 ///                         should keep the focus in the GUI.
390 ///   "allThreadsStopped" - set to True to indicate that all threads
391 ///                         stop when any thread stops.
392 ///
393 /// \param[in] thread
394 ///     The LLDB thread to use when populating out the "StoppedEvent"
395 ///     object.
396 ///
397 /// \return
398 ///     A "StoppedEvent" JSON object with that follows the formal JSON
399 ///     definition outlined by Microsoft.
400 llvm::json::Value CreateThreadStopped(lldb::SBThread &thread, uint32_t stop_id);
401 
402 /// Create a "Variable" object for a LLDB thread object.
403 ///
404 /// This function will fill in the following keys in the returned
405 /// object:
406 ///   "name" - the name of the variable
407 ///   "value" - the value of the variable as a string
408 ///   "type" - the typename of the variable as a string
409 ///   "id" - a unique identifier for a value in case there are multiple
410 ///          variables with the same name. Other parts of the VSCode
411 ///          protocol refer to values by name so this can help
412 ///          disambiguate such cases if a IDE passes this "id" value
413 ///          back down.
414 ///   "variablesReference" - Zero if the variable has no children,
415 ///          non-zero integer otherwise which can be used to expand
416 ///          the variable.
417 ///   "evaluateName" - The name of the variable to use in expressions
418 ///                    as a string.
419 ///
420 /// \param[in] v
421 ///     The LLDB value to use when populating out the "Variable"
422 ///     object.
423 ///
424 /// \param[in] variablesReference
425 ///     The variable reference. Zero if this value isn't structured
426 ///     and has no children, non-zero if it does have children and
427 ///     might be asked to expand itself.
428 ///
429 /// \param[in] varID
430 ///     A unique variable identifier to help in properly identifying
431 ///     variables with the same name. This is an extension to the
432 ///     VS protocol.
433 ///
434 /// \param[in] format_hex
435 ///     It set to true the variable will be formatted as hex in
436 ///     the "value" key value pair for the value of the variable.
437 ///
438 /// \return
439 ///     A "Variable" JSON object with that follows the formal JSON
440 ///     definition outlined by Microsoft.
441 llvm::json::Value CreateVariable(lldb::SBValue v, int64_t variablesReference,
442                                  int64_t varID, bool format_hex);
443 
444 llvm::json::Value CreateCompileUnit(lldb::SBCompileUnit unit);
445 
446 /// Create a runInTerminal reverse request object
447 ///
448 /// \param[in] launch_request
449 ///     The original launch_request object whose fields are used to construct
450 ///     the reverse request object.
451 ///
452 /// \return
453 ///     A "runInTerminal" JSON object that follows the specification outlined by
454 ///     Microsoft.
455 llvm::json::Object
456 CreateRunInTerminalReverseRequest(const llvm::json::Object &launch_request);
457 
458 } // namespace lldb_vscode
459 
460 #endif
461