420 lines · c
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-exception6//7//===----------------------------------------------------------------------===//8 9#ifndef LLDB_TOOLS_LLDB_DAP_JSONUTILS_H10#define LLDB_TOOLS_LLDB_DAP_JSONUTILS_H11 12#include "DAPForward.h"13#include "Protocol/ProtocolRequests.h"14#include "lldb/API/SBCompileUnit.h"15#include "lldb/API/SBFormat.h"16#include "lldb/API/SBType.h"17#include "lldb/API/SBValue.h"18#include "lldb/lldb-types.h"19#include "llvm/ADT/StringMap.h"20#include "llvm/ADT/StringRef.h"21#include "llvm/Support/JSON.h"22#include <cstdint>23#include <optional>24#include <string>25#include <unordered_map>26#include <utility>27#include <vector>28 29namespace lldb_dap {30 31/// Emplace a StringRef in a json::Object after ensuring that the32/// string is valid UTF8. If not, first call llvm::json::fixUTF833/// before emplacing.34///35/// \param[in] obj36/// A JSON object that we will attempt to emplace the value in37///38/// \param[in] key39/// The key to use when emplacing the value40///41/// \param[in] str42/// The string to emplace43void EmplaceSafeString(llvm::json::Object &obj, llvm::StringRef key,44 llvm::StringRef str);45 46/// Extract simple values as a string.47///48/// \param[in] value49/// A JSON value to extract the string from.50///51/// \return52/// A llvm::StringRef that contains the string value, or an empty53/// string if \a value isn't a string.54llvm::StringRef GetAsString(const llvm::json::Value &value);55 56/// Extract the string value for the specified key from the57/// specified object.58///59/// \param[in] obj60/// A JSON object that we will attempt to extract the value from61///62/// \param[in] key63/// The key to use when extracting the value64///65/// \return66/// A llvm::StringRef that contains the string value for the67/// specified \a key, or \a std::nullopt if there is no key that68/// matches or if the value is not a string.69std::optional<llvm::StringRef> GetString(const llvm::json::Object &obj,70 llvm::StringRef key);71std::optional<llvm::StringRef> GetString(const llvm::json::Object *obj,72 llvm::StringRef key);73 74/// Extract the integer value for the specified key from the specified object75/// and return it as the specified integer type T.76///77/// \param[in] obj78/// A JSON object that we will attempt to extract the value from79///80/// \param[in] key81/// The key to use when extracting the value82///83/// \return84/// The integer value for the specified \a key, or std::nullopt if there is85/// no key that matches or if the value is not an integer.86/// @{87template <typename T>88std::optional<T> GetInteger(const llvm::json::Object &obj,89 llvm::StringRef key) {90 return obj.getInteger(key);91}92 93template <typename T>94std::optional<T> GetInteger(const llvm::json::Object *obj,95 llvm::StringRef key) {96 if (obj != nullptr)97 return GetInteger<T>(*obj, key);98 return std::nullopt;99}100/// @}101 102/// Extract the boolean value for the specified key from the103/// specified object.104///105/// \param[in] obj106/// A JSON object that we will attempt to extract the value from107///108/// \param[in] key109/// The key to use when extracting the value110///111/// \return112/// The boolean value for the specified \a key, or std::nullopt113/// if there is no key that matches or if the value is not a114/// boolean value of an integer.115/// @{116std::optional<bool> GetBoolean(const llvm::json::Object &obj,117 llvm::StringRef key);118std::optional<bool> GetBoolean(const llvm::json::Object *obj,119 llvm::StringRef key);120/// @}121 122/// Check if the specified key exists in the specified object.123///124/// \param[in] obj125/// A JSON object that we will attempt to extract the value from126///127/// \param[in] key128/// The key to check for129///130/// \return131/// \b True if the key exists in the \a obj, \b False otherwise.132bool ObjectContainsKey(const llvm::json::Object &obj, llvm::StringRef key);133 134/// Encodes a memory reference135std::string EncodeMemoryReference(lldb::addr_t addr);136 137/// Decodes a memory reference138std::optional<lldb::addr_t>139DecodeMemoryReference(llvm::StringRef memoryReference);140 141/// Decodes a memory reference from the given json value.142///143/// \param[in] v144/// A JSON value that we expected to contain the memory reference.145///146/// \param[in] key147/// The key of the memory reference.148///149/// \param[out] out150/// The memory address, if successfully decoded.151///152/// \param[in] path153/// The path for reporting errors.154///155/// \param[in] required156/// Indicates if the key is required to be present, otherwise report an error157/// if the key is missing.158///159/// \return160/// Returns \b true if the address was decoded successfully.161bool DecodeMemoryReference(const llvm::json::Value &v, llvm::StringLiteral key,162 lldb::addr_t &out, llvm::json::Path path,163 bool required);164 165/// Extract an array of strings for the specified key from an object.166///167/// String values in the array will be extracted without any quotes168/// around them. Numbers and Booleans will be converted into169/// strings. Any NULL, array or objects values in the array will be170/// ignored.171///172/// \param[in] obj173/// A JSON object that we will attempt to extract the array from174///175/// \param[in] key176/// The key to use when extracting the value177///178/// \return179/// An array of string values for the specified \a key, or180/// \a fail_value if there is no key that matches or if the181/// value is not an array or all items in the array are not182/// strings, numbers or booleans.183std::vector<std::string> GetStrings(const llvm::json::Object *obj,184 llvm::StringRef key);185 186/// Extract an object of key value strings for the specified key from an object.187///188/// String values in the object will be extracted without any quotes189/// around them. Numbers and Booleans will be converted into190/// strings. Any NULL, array or objects values in the array will be191/// ignored.192///193/// \param[in] obj194/// A JSON object that we will attempt to extract the array from195///196/// \param[in] key197/// The key to use when extracting the value198///199/// \return200/// An object of key value strings for the specified \a key, or201/// \a fail_value if there is no key that matches or if the202/// value is not an object or key and values in the object are not203/// strings, numbers or booleans.204std::unordered_map<std::string, std::string>205GetStringMap(const llvm::json::Object &obj, llvm::StringRef key);206 207/// Fill a response object given the request object.208///209/// The \a response object will get its "type" set to "response",210/// the "seq" set to zero, "response_seq" set to the "seq" value from211/// \a request, "command" set to the "command" from \a request,212/// and "success" set to true.213///214/// \param[in] request215/// The request object received from a call to DAP::ReadJSON().216///217/// \param[in,out] response218/// An empty llvm::json::Object object that will be filled219/// in as noted in description.220void FillResponse(const llvm::json::Object &request,221 llvm::json::Object &response);222 223/// Create a "Event" JSON object using \a event_name as the event name224///225/// \param[in] event_name226/// The string value to use for the "event" key in the JSON object.227///228/// \return229/// A "Event" JSON object with that follows the formal JSON230/// definition outlined by Microsoft.231llvm::json::Object CreateEventObject(const llvm::StringRef event_name);232 233/// Create a "StackFrame" object for a LLDB frame object.234///235/// This function will fill in the following keys in the returned236/// object:237/// "id" - the stack frame ID as an integer238/// "name" - the function name as a string239/// "source" - source file information as a "Source" DAP object240/// "line" - the source file line number as an integer241/// "column" - the source file column number as an integer242///243/// \param[in] dap244/// The DAP session associated with the stopped thread.245///246/// \param[in] frame247/// The LLDB stack frame to use when populating out the "StackFrame"248/// object.249///250/// \param[in] format251/// The LLDB format to use when populating out the "StackFrame"252/// object.253///254/// \return255/// A "StackFrame" JSON object with that follows the formal JSON256/// definition outlined by Microsoft.257llvm::json::Value CreateStackFrame(DAP &dap, lldb::SBFrame &frame,258 lldb::SBFormat &format);259 260/// Create a "StackFrame" label object for a LLDB thread.261///262/// This function will fill in the following keys in the returned263/// object:264/// "id" - the thread ID as an integer265/// "name" - the thread name as a string which combines the LLDB266/// thread index ID along with the string name of the thread267/// from the OS if it has a name.268/// "presentationHint" - "label"269///270/// \param[in] thread271/// The LLDB thread to use when populating out the "Thread"272/// object.273///274/// \param[in] format275/// The configured formatter for the DAP session.276///277/// \return278/// A "StackFrame" JSON object with that follows the formal JSON279/// definition outlined by Microsoft.280llvm::json::Value CreateExtendedStackFrameLabel(lldb::SBThread &thread,281 lldb::SBFormat &format);282 283/// Create a "StoppedEvent" object for a LLDB thread object.284///285/// This function will fill in the following keys in the returned286/// object's "body" object:287/// "reason" - With a valid stop reason enumeration string value288/// that Microsoft specifies289/// "threadId" - The thread ID as an integer290/// "description" - a stop description (like "breakpoint 12.3") as a291/// string292/// "preserveFocusHint" - a boolean value that states if this thread293/// should keep the focus in the GUI.294/// "allThreadsStopped" - set to True to indicate that all threads295/// stop when any thread stops.296///297/// \param[in] dap298/// The DAP session associated with the stopped thread.299///300/// \param[in] thread301/// The LLDB thread to use when populating out the "StoppedEvent"302/// object.303///304/// \param[in] stop_id305/// The stop id for this event.306///307/// \return308/// A "StoppedEvent" JSON object with that follows the formal JSON309/// definition outlined by Microsoft.310llvm::json::Value CreateThreadStopped(DAP &dap, lldb::SBThread &thread,311 uint32_t stop_id);312 313/// \return314/// The variable name of \a value or a default placeholder.315const char *GetNonNullVariableName(lldb::SBValue &value);316 317/// VSCode can't display two variables with the same name, so we need to318/// distinguish them by using a suffix.319///320/// If the source and line information is present, we use it as the suffix.321/// Otherwise, we fallback to the variable address or register location.322std::string CreateUniqueVariableNameForDisplay(lldb::SBValue &v,323 bool is_name_duplicated);324 325/// Helper struct that parses the metadata of an \a lldb::SBValue and produces326/// a canonical set of properties that can be sent to DAP clients.327struct VariableDescription {328 // The error message if SBValue.GetValue() fails.329 std::optional<std::string> error;330 // The display description to show on the IDE.331 std::string display_value;332 // The display name to show on the IDE.333 std::string name;334 // The variable path for this variable.335 std::string evaluate_name;336 // The output of SBValue.GetValue() if it doesn't fail. It might be empty.337 std::string value;338 // The summary string of this variable. It might be empty.339 std::string summary;340 // The auto summary if using `enableAutoVariableSummaries`.341 std::optional<std::string> auto_summary;342 // The type of this variable.343 lldb::SBType type_obj;344 // The display type name of this variable.345 std::string display_type_name;346 /// The SBValue for this variable.347 lldb::SBValue v;348 349 VariableDescription(lldb::SBValue v, bool auto_variable_summaries,350 bool format_hex = false, bool is_name_duplicated = false,351 std::optional<std::string> custom_name = {});352 353 /// Returns a description of the value appropriate for the specified context.354 std::string GetResult(protocol::EvaluateContext context);355};356 357/// Does the given variable have an associated value location?358bool ValuePointsToCode(lldb::SBValue v);359 360/// Pack a location into a single integer which we can send via361/// the debug adapter protocol.362int64_t PackLocation(int64_t var_ref, bool is_value_location);363 364/// Reverse of `PackLocation`365std::pair<int64_t, bool> UnpackLocation(int64_t location_id);366 367llvm::json::Value CreateCompileUnit(lldb::SBCompileUnit &unit);368 369/// Create a runInTerminal reverse request object370///371/// \param[in] program372/// Path to the program to run in the terminal.373///374/// \param[in] args375/// The arguments for the program.376///377/// \param[in] env378/// The environment variables to set in the terminal.379///380/// \param[in] cwd381/// The working directory for the run in terminal request.382///383/// \param[in] comm_file384/// The fifo file used to communicate the with the target launcher.385///386/// \param[in] debugger_pid387/// The PID of the lldb-dap instance that will attach to the target. The388/// launcher uses it on Linux tell the kernel that it should allow the389/// debugger process to attach.390///391/// \param[in] stdio392/// An array of file paths for redirecting the program's standard IO393/// streams.394///395/// \param[in] external396/// If set to true, the program will run in an external terminal window397/// instead of IDE's integrated terminal.398///399/// \return400/// A "runInTerminal" JSON object that follows the specification outlined by401/// Microsoft.402llvm::json::Object CreateRunInTerminalReverseRequest(403 llvm::StringRef program, const std::vector<std::string> &args,404 const llvm::StringMap<std::string> &env, llvm::StringRef cwd,405 llvm::StringRef comm_file, lldb::pid_t debugger_pid,406 const std::vector<std::optional<std::string>> &stdio, bool external);407 408/// Create a "Terminated" JSON object that contains statistics409///410/// \return411/// A body JSON object with debug info and breakpoint info412llvm::json::Object CreateTerminatedEventObject(lldb::SBTarget &target);413 414/// Convert a given JSON object to a string.415std::string JSONToString(const llvm::json::Value &json);416 417} // namespace lldb_dap418 419#endif420