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