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