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 <cstdint> 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 /// \return 403 /// The variable name of \a value or a default placeholder. 404 const char *GetNonNullVariableName(lldb::SBValue value); 405 406 /// VSCode can't display two variables with the same name, so we need to 407 /// distinguish them by using a suffix. 408 /// 409 /// If the source and line information is present, we use it as the suffix. 410 /// Otherwise, we fallback to the variable address or register location. 411 std::string CreateUniqueVariableNameForDisplay(lldb::SBValue v, 412 bool is_name_duplicated); 413 414 /// Create a "Variable" object for a LLDB thread object. 415 /// 416 /// This function will fill in the following keys in the returned 417 /// object: 418 /// "name" - the name of the variable 419 /// "value" - the value of the variable as a string 420 /// "type" - the typename of the variable as a string 421 /// "id" - a unique identifier for a value in case there are multiple 422 /// variables with the same name. Other parts of the VSCode 423 /// protocol refer to values by name so this can help 424 /// disambiguate such cases if a IDE passes this "id" value 425 /// back down. 426 /// "variablesReference" - Zero if the variable has no children, 427 /// non-zero integer otherwise which can be used to expand 428 /// the variable. 429 /// "evaluateName" - The name of the variable to use in expressions 430 /// as a string. 431 /// 432 /// \param[in] v 433 /// The LLDB value to use when populating out the "Variable" 434 /// object. 435 /// 436 /// \param[in] variablesReference 437 /// The variable reference. Zero if this value isn't structured 438 /// and has no children, non-zero if it does have children and 439 /// might be asked to expand itself. 440 /// 441 /// \param[in] varID 442 /// A unique variable identifier to help in properly identifying 443 /// variables with the same name. This is an extension to the 444 /// VS protocol. 445 /// 446 /// \param[in] format_hex 447 /// It set to true the variable will be formatted as hex in 448 /// the "value" key value pair for the value of the variable. 449 /// 450 /// \param[in] is_name_duplicated 451 /// Whether the same variable name appears multiple times within the same 452 /// context (e.g. locals). This can happen due to shadowed variables in 453 /// nested blocks. 454 /// 455 /// As VSCode doesn't render two of more variables with the same name, we 456 /// apply a suffix to distinguish duplicated variables. 457 /// 458 /// \return 459 /// A "Variable" JSON object with that follows the formal JSON 460 /// definition outlined by Microsoft. 461 llvm::json::Value CreateVariable(lldb::SBValue v, int64_t variablesReference, 462 int64_t varID, bool format_hex, 463 bool is_name_duplicated = false); 464 465 llvm::json::Value CreateCompileUnit(lldb::SBCompileUnit unit); 466 467 /// Create a runInTerminal reverse request object 468 /// 469 /// \param[in] launch_request 470 /// The original launch_request object whose fields are used to construct 471 /// the reverse request object. 472 /// 473 /// \param[in] debug_adaptor_path 474 /// Path to the current debug adaptor. It will be used to delegate the 475 /// launch of the target. 476 /// 477 /// \param[in] comm_file 478 /// The fifo file used to communicate the with the target launcher. 479 /// 480 /// \return 481 /// A "runInTerminal" JSON object that follows the specification outlined by 482 /// Microsoft. 483 llvm::json::Object 484 CreateRunInTerminalReverseRequest(const llvm::json::Object &launch_request, 485 llvm::StringRef debug_adaptor_path, 486 llvm::StringRef comm_file); 487 488 /// Convert a given JSON object to a string. 489 std::string JSONToString(const llvm::json::Value &json); 490 491 } // namespace lldb_vscode 492 493 #endif 494