lldb/tools/lldb-vscode/JSONUtils.h

   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