JSON.h revision 360784
1//===--- JSON.h - JSON values, parsing and serialization -------*- 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/// \file 10/// This file supports working with JSON data. 11/// 12/// It comprises: 13/// 14/// - classes which hold dynamically-typed parsed JSON structures 15/// These are value types that can be composed, inspected, and modified. 16/// See json::Value, and the related types json::Object and json::Array. 17/// 18/// - functions to parse JSON text into Values, and to serialize Values to text. 19/// See parse(), operator<<, and format_provider. 20/// 21/// - a convention and helpers for mapping between json::Value and user-defined 22/// types. See fromJSON(), ObjectMapper, and the class comment on Value. 23/// 24/// - an output API json::OStream which can emit JSON without materializing 25/// all structures as json::Value. 26/// 27/// Typically, JSON data would be read from an external source, parsed into 28/// a Value, and then converted into some native data structure before doing 29/// real work on it. (And vice versa when writing). 30/// 31/// Other serialization mechanisms you may consider: 32/// 33/// - YAML is also text-based, and more human-readable than JSON. It's a more 34/// complex format and data model, and YAML parsers aren't ubiquitous. 35/// YAMLParser.h is a streaming parser suitable for parsing large documents 36/// (including JSON, as YAML is a superset). It can be awkward to use 37/// directly. YAML I/O (YAMLTraits.h) provides data mapping that is more 38/// declarative than the toJSON/fromJSON conventions here. 39/// 40/// - LLVM bitstream is a space- and CPU- efficient binary format. Typically it 41/// encodes LLVM IR ("bitcode"), but it can be a container for other data. 42/// Low-level reader/writer libraries are in Bitstream/Bitstream*.h 43/// 44//===---------------------------------------------------------------------===// 45 46#ifndef LLVM_SUPPORT_JSON_H 47#define LLVM_SUPPORT_JSON_H 48 49#include "llvm/ADT/DenseMap.h" 50#include "llvm/ADT/SmallVector.h" 51#include "llvm/ADT/StringRef.h" 52#include "llvm/Support/Error.h" 53#include "llvm/Support/FormatVariadic.h" 54#include "llvm/Support/raw_ostream.h" 55#include <map> 56 57namespace llvm { 58namespace json { 59 60// === String encodings === 61// 62// JSON strings are character sequences (not byte sequences like std::string). 63// We need to know the encoding, and for simplicity only support UTF-8. 64// 65// - When parsing, invalid UTF-8 is a syntax error like any other 66// 67// - When creating Values from strings, callers must ensure they are UTF-8. 68// with asserts on, invalid UTF-8 will crash the program 69// with asserts off, we'll substitute the replacement character (U+FFFD) 70// Callers can use json::isUTF8() and json::fixUTF8() for validation. 71// 72// - When retrieving strings from Values (e.g. asString()), the result will 73// always be valid UTF-8. 74 75/// Returns true if \p S is valid UTF-8, which is required for use as JSON. 76/// If it returns false, \p Offset is set to a byte offset near the first error. 77bool isUTF8(llvm::StringRef S, size_t *ErrOffset = nullptr); 78/// Replaces invalid UTF-8 sequences in \p S with the replacement character 79/// (U+FFFD). The returned string is valid UTF-8. 80/// This is much slower than isUTF8, so test that first. 81std::string fixUTF8(llvm::StringRef S); 82 83class Array; 84class ObjectKey; 85class Value; 86template <typename T> Value toJSON(const llvm::Optional<T> &Opt); 87 88/// An Object is a JSON object, which maps strings to heterogenous JSON values. 89/// It simulates DenseMap<ObjectKey, Value>. ObjectKey is a maybe-owned string. 90class Object { 91 using Storage = DenseMap<ObjectKey, Value, llvm::DenseMapInfo<StringRef>>; 92 Storage M; 93 94public: 95 using key_type = ObjectKey; 96 using mapped_type = Value; 97 using value_type = Storage::value_type; 98 using iterator = Storage::iterator; 99 using const_iterator = Storage::const_iterator; 100 101 Object() = default; 102 // KV is a trivial key-value struct for list-initialization. 103 // (using std::pair forces extra copies). 104 struct KV; 105 explicit Object(std::initializer_list<KV> Properties); 106 107 iterator begin() { return M.begin(); } 108 const_iterator begin() const { return M.begin(); } 109 iterator end() { return M.end(); } 110 const_iterator end() const { return M.end(); } 111 112 bool empty() const { return M.empty(); } 113 size_t size() const { return M.size(); } 114 115 void clear() { M.clear(); } 116 std::pair<iterator, bool> insert(KV E); 117 template <typename... Ts> 118 std::pair<iterator, bool> try_emplace(const ObjectKey &K, Ts &&... Args) { 119 return M.try_emplace(K, std::forward<Ts>(Args)...); 120 } 121 template <typename... Ts> 122 std::pair<iterator, bool> try_emplace(ObjectKey &&K, Ts &&... Args) { 123 return M.try_emplace(std::move(K), std::forward<Ts>(Args)...); 124 } 125 bool erase(StringRef K); 126 void erase(iterator I) { M.erase(I); } 127 128 iterator find(StringRef K) { return M.find_as(K); } 129 const_iterator find(StringRef K) const { return M.find_as(K); } 130 // operator[] acts as if Value was default-constructible as null. 131 Value &operator[](const ObjectKey &K); 132 Value &operator[](ObjectKey &&K); 133 // Look up a property, returning nullptr if it doesn't exist. 134 Value *get(StringRef K); 135 const Value *get(StringRef K) const; 136 // Typed accessors return None/nullptr if 137 // - the property doesn't exist 138 // - or it has the wrong type 139 llvm::Optional<std::nullptr_t> getNull(StringRef K) const; 140 llvm::Optional<bool> getBoolean(StringRef K) const; 141 llvm::Optional<double> getNumber(StringRef K) const; 142 llvm::Optional<int64_t> getInteger(StringRef K) const; 143 llvm::Optional<llvm::StringRef> getString(StringRef K) const; 144 const json::Object *getObject(StringRef K) const; 145 json::Object *getObject(StringRef K); 146 const json::Array *getArray(StringRef K) const; 147 json::Array *getArray(StringRef K); 148}; 149bool operator==(const Object &LHS, const Object &RHS); 150inline bool operator!=(const Object &LHS, const Object &RHS) { 151 return !(LHS == RHS); 152} 153 154/// An Array is a JSON array, which contains heterogeneous JSON values. 155/// It simulates std::vector<Value>. 156class Array { 157 std::vector<Value> V; 158 159public: 160 using value_type = Value; 161 using iterator = std::vector<Value>::iterator; 162 using const_iterator = std::vector<Value>::const_iterator; 163 164 Array() = default; 165 explicit Array(std::initializer_list<Value> Elements); 166 template <typename Collection> explicit Array(const Collection &C) { 167 for (const auto &V : C) 168 emplace_back(V); 169 } 170 171 Value &operator[](size_t I) { return V[I]; } 172 const Value &operator[](size_t I) const { return V[I]; } 173 Value &front() { return V.front(); } 174 const Value &front() const { return V.front(); } 175 Value &back() { return V.back(); } 176 const Value &back() const { return V.back(); } 177 Value *data() { return V.data(); } 178 const Value *data() const { return V.data(); } 179 180 iterator begin() { return V.begin(); } 181 const_iterator begin() const { return V.begin(); } 182 iterator end() { return V.end(); } 183 const_iterator end() const { return V.end(); } 184 185 bool empty() const { return V.empty(); } 186 size_t size() const { return V.size(); } 187 void reserve(size_t S) { V.reserve(S); } 188 189 void clear() { V.clear(); } 190 void push_back(const Value &E) { V.push_back(E); } 191 void push_back(Value &&E) { V.push_back(std::move(E)); } 192 template <typename... Args> void emplace_back(Args &&... A) { 193 V.emplace_back(std::forward<Args>(A)...); 194 } 195 void pop_back() { V.pop_back(); } 196 // FIXME: insert() takes const_iterator since C++11, old libstdc++ disagrees. 197 iterator insert(iterator P, const Value &E) { return V.insert(P, E); } 198 iterator insert(iterator P, Value &&E) { 199 return V.insert(P, std::move(E)); 200 } 201 template <typename It> iterator insert(iterator P, It A, It Z) { 202 return V.insert(P, A, Z); 203 } 204 template <typename... Args> iterator emplace(const_iterator P, Args &&... A) { 205 return V.emplace(P, std::forward<Args>(A)...); 206 } 207 208 friend bool operator==(const Array &L, const Array &R) { return L.V == R.V; } 209}; 210inline bool operator!=(const Array &L, const Array &R) { return !(L == R); } 211 212/// A Value is an JSON value of unknown type. 213/// They can be copied, but should generally be moved. 214/// 215/// === Composing values === 216/// 217/// You can implicitly construct Values from: 218/// - strings: std::string, SmallString, formatv, StringRef, char* 219/// (char*, and StringRef are references, not copies!) 220/// - numbers 221/// - booleans 222/// - null: nullptr 223/// - arrays: {"foo", 42.0, false} 224/// - serializable things: types with toJSON(const T&)->Value, found by ADL 225/// 226/// They can also be constructed from object/array helpers: 227/// - json::Object is a type like map<ObjectKey, Value> 228/// - json::Array is a type like vector<Value> 229/// These can be list-initialized, or used to build up collections in a loop. 230/// json::ary(Collection) converts all items in a collection to Values. 231/// 232/// === Inspecting values === 233/// 234/// Each Value is one of the JSON kinds: 235/// null (nullptr_t) 236/// boolean (bool) 237/// number (double or int64) 238/// string (StringRef) 239/// array (json::Array) 240/// object (json::Object) 241/// 242/// The kind can be queried directly, or implicitly via the typed accessors: 243/// if (Optional<StringRef> S = E.getAsString() 244/// assert(E.kind() == Value::String); 245/// 246/// Array and Object also have typed indexing accessors for easy traversal: 247/// Expected<Value> E = parse(R"( {"options": {"font": "sans-serif"}} )"); 248/// if (Object* O = E->getAsObject()) 249/// if (Object* Opts = O->getObject("options")) 250/// if (Optional<StringRef> Font = Opts->getString("font")) 251/// assert(Opts->at("font").kind() == Value::String); 252/// 253/// === Converting JSON values to C++ types === 254/// 255/// The convention is to have a deserializer function findable via ADL: 256/// fromJSON(const json::Value&, T&)->bool 257/// Deserializers are provided for: 258/// - bool 259/// - int and int64_t 260/// - double 261/// - std::string 262/// - vector<T>, where T is deserializable 263/// - map<string, T>, where T is deserializable 264/// - Optional<T>, where T is deserializable 265/// ObjectMapper can help writing fromJSON() functions for object types. 266/// 267/// For conversion in the other direction, the serializer function is: 268/// toJSON(const T&) -> json::Value 269/// If this exists, then it also allows constructing Value from T, and can 270/// be used to serialize vector<T>, map<string, T>, and Optional<T>. 271/// 272/// === Serialization === 273/// 274/// Values can be serialized to JSON: 275/// 1) raw_ostream << Value // Basic formatting. 276/// 2) raw_ostream << formatv("{0}", Value) // Basic formatting. 277/// 3) raw_ostream << formatv("{0:2}", Value) // Pretty-print with indent 2. 278/// 279/// And parsed: 280/// Expected<Value> E = json::parse("[1, 2, null]"); 281/// assert(E && E->kind() == Value::Array); 282class Value { 283public: 284 enum Kind { 285 Null, 286 Boolean, 287 /// Number values can store both int64s and doubles at full precision, 288 /// depending on what they were constructed/parsed from. 289 Number, 290 String, 291 Array, 292 Object, 293 }; 294 295 // It would be nice to have Value() be null. But that would make {} null too. 296 Value(const Value &M) { copyFrom(M); } 297 Value(Value &&M) { moveFrom(std::move(M)); } 298 Value(std::initializer_list<Value> Elements); 299 Value(json::Array &&Elements) : Type(T_Array) { 300 create<json::Array>(std::move(Elements)); 301 } 302 template <typename Elt> 303 Value(const std::vector<Elt> &C) : Value(json::Array(C)) {} 304 Value(json::Object &&Properties) : Type(T_Object) { 305 create<json::Object>(std::move(Properties)); 306 } 307 template <typename Elt> 308 Value(const std::map<std::string, Elt> &C) : Value(json::Object(C)) {} 309 // Strings: types with value semantics. Must be valid UTF-8. 310 Value(std::string V) : Type(T_String) { 311 if (LLVM_UNLIKELY(!isUTF8(V))) { 312 assert(false && "Invalid UTF-8 in value used as JSON"); 313 V = fixUTF8(std::move(V)); 314 } 315 create<std::string>(std::move(V)); 316 } 317 Value(const llvm::SmallVectorImpl<char> &V) 318 : Value(std::string(V.begin(), V.end())) {} 319 Value(const llvm::formatv_object_base &V) : Value(V.str()) {} 320 // Strings: types with reference semantics. Must be valid UTF-8. 321 Value(StringRef V) : Type(T_StringRef) { 322 create<llvm::StringRef>(V); 323 if (LLVM_UNLIKELY(!isUTF8(V))) { 324 assert(false && "Invalid UTF-8 in value used as JSON"); 325 *this = Value(fixUTF8(V)); 326 } 327 } 328 Value(const char *V) : Value(StringRef(V)) {} 329 Value(std::nullptr_t) : Type(T_Null) {} 330 // Boolean (disallow implicit conversions). 331 // (The last template parameter is a dummy to keep templates distinct.) 332 template < 333 typename T, 334 typename = typename std::enable_if<std::is_same<T, bool>::value>::type, 335 bool = false> 336 Value(T B) : Type(T_Boolean) { 337 create<bool>(B); 338 } 339 // Integers (except boolean). Must be non-narrowing convertible to int64_t. 340 template < 341 typename T, 342 typename = typename std::enable_if<std::is_integral<T>::value>::type, 343 typename = typename std::enable_if<!std::is_same<T, bool>::value>::type> 344 Value(T I) : Type(T_Integer) { 345 create<int64_t>(int64_t{I}); 346 } 347 // Floating point. Must be non-narrowing convertible to double. 348 template <typename T, 349 typename = 350 typename std::enable_if<std::is_floating_point<T>::value>::type, 351 double * = nullptr> 352 Value(T D) : Type(T_Double) { 353 create<double>(double{D}); 354 } 355 // Serializable types: with a toJSON(const T&)->Value function, found by ADL. 356 template <typename T, 357 typename = typename std::enable_if<std::is_same< 358 Value, decltype(toJSON(*(const T *)nullptr))>::value>, 359 Value * = nullptr> 360 Value(const T &V) : Value(toJSON(V)) {} 361 362 Value &operator=(const Value &M) { 363 destroy(); 364 copyFrom(M); 365 return *this; 366 } 367 Value &operator=(Value &&M) { 368 destroy(); 369 moveFrom(std::move(M)); 370 return *this; 371 } 372 ~Value() { destroy(); } 373 374 Kind kind() const { 375 switch (Type) { 376 case T_Null: 377 return Null; 378 case T_Boolean: 379 return Boolean; 380 case T_Double: 381 case T_Integer: 382 return Number; 383 case T_String: 384 case T_StringRef: 385 return String; 386 case T_Object: 387 return Object; 388 case T_Array: 389 return Array; 390 } 391 llvm_unreachable("Unknown kind"); 392 } 393 394 // Typed accessors return None/nullptr if the Value is not of this type. 395 llvm::Optional<std::nullptr_t> getAsNull() const { 396 if (LLVM_LIKELY(Type == T_Null)) 397 return nullptr; 398 return llvm::None; 399 } 400 llvm::Optional<bool> getAsBoolean() const { 401 if (LLVM_LIKELY(Type == T_Boolean)) 402 return as<bool>(); 403 return llvm::None; 404 } 405 llvm::Optional<double> getAsNumber() const { 406 if (LLVM_LIKELY(Type == T_Double)) 407 return as<double>(); 408 if (LLVM_LIKELY(Type == T_Integer)) 409 return as<int64_t>(); 410 return llvm::None; 411 } 412 // Succeeds if the Value is a Number, and exactly representable as int64_t. 413 llvm::Optional<int64_t> getAsInteger() const { 414 if (LLVM_LIKELY(Type == T_Integer)) 415 return as<int64_t>(); 416 if (LLVM_LIKELY(Type == T_Double)) { 417 double D = as<double>(); 418 if (LLVM_LIKELY(std::modf(D, &D) == 0.0 && 419 D >= double(std::numeric_limits<int64_t>::min()) && 420 D <= double(std::numeric_limits<int64_t>::max()))) 421 return D; 422 } 423 return llvm::None; 424 } 425 llvm::Optional<llvm::StringRef> getAsString() const { 426 if (Type == T_String) 427 return llvm::StringRef(as<std::string>()); 428 if (LLVM_LIKELY(Type == T_StringRef)) 429 return as<llvm::StringRef>(); 430 return llvm::None; 431 } 432 const json::Object *getAsObject() const { 433 return LLVM_LIKELY(Type == T_Object) ? &as<json::Object>() : nullptr; 434 } 435 json::Object *getAsObject() { 436 return LLVM_LIKELY(Type == T_Object) ? &as<json::Object>() : nullptr; 437 } 438 const json::Array *getAsArray() const { 439 return LLVM_LIKELY(Type == T_Array) ? &as<json::Array>() : nullptr; 440 } 441 json::Array *getAsArray() { 442 return LLVM_LIKELY(Type == T_Array) ? &as<json::Array>() : nullptr; 443 } 444 445private: 446 void destroy(); 447 void copyFrom(const Value &M); 448 // We allow moving from *const* Values, by marking all members as mutable! 449 // This hack is needed to support initializer-list syntax efficiently. 450 // (std::initializer_list<T> is a container of const T). 451 void moveFrom(const Value &&M); 452 friend class Array; 453 friend class Object; 454 455 template <typename T, typename... U> void create(U &&... V) { 456 new (reinterpret_cast<T *>(Union.buffer)) T(std::forward<U>(V)...); 457 } 458 template <typename T> T &as() const { 459 // Using this two-step static_cast via void * instead of reinterpret_cast 460 // silences a -Wstrict-aliasing false positive from GCC6 and earlier. 461 void *Storage = static_cast<void *>(Union.buffer); 462 return *static_cast<T *>(Storage); 463 } 464 465 friend class OStream; 466 467 enum ValueType : char { 468 T_Null, 469 T_Boolean, 470 T_Double, 471 T_Integer, 472 T_StringRef, 473 T_String, 474 T_Object, 475 T_Array, 476 }; 477 // All members mutable, see moveFrom(). 478 mutable ValueType Type; 479 mutable llvm::AlignedCharArrayUnion<bool, double, int64_t, llvm::StringRef, 480 std::string, json::Array, json::Object> 481 Union; 482 friend bool operator==(const Value &, const Value &); 483}; 484 485bool operator==(const Value &, const Value &); 486inline bool operator!=(const Value &L, const Value &R) { return !(L == R); } 487 488/// ObjectKey is a used to capture keys in Object. Like Value but: 489/// - only strings are allowed 490/// - it's optimized for the string literal case (Owned == nullptr) 491/// Like Value, strings must be UTF-8. See isUTF8 documentation for details. 492class ObjectKey { 493public: 494 ObjectKey(const char *S) : ObjectKey(StringRef(S)) {} 495 ObjectKey(std::string S) : Owned(new std::string(std::move(S))) { 496 if (LLVM_UNLIKELY(!isUTF8(*Owned))) { 497 assert(false && "Invalid UTF-8 in value used as JSON"); 498 *Owned = fixUTF8(std::move(*Owned)); 499 } 500 Data = *Owned; 501 } 502 ObjectKey(llvm::StringRef S) : Data(S) { 503 if (LLVM_UNLIKELY(!isUTF8(Data))) { 504 assert(false && "Invalid UTF-8 in value used as JSON"); 505 *this = ObjectKey(fixUTF8(S)); 506 } 507 } 508 ObjectKey(const llvm::SmallVectorImpl<char> &V) 509 : ObjectKey(std::string(V.begin(), V.end())) {} 510 ObjectKey(const llvm::formatv_object_base &V) : ObjectKey(V.str()) {} 511 512 ObjectKey(const ObjectKey &C) { *this = C; } 513 ObjectKey(ObjectKey &&C) : ObjectKey(static_cast<const ObjectKey &&>(C)) {} 514 ObjectKey &operator=(const ObjectKey &C) { 515 if (C.Owned) { 516 Owned.reset(new std::string(*C.Owned)); 517 Data = *Owned; 518 } else { 519 Data = C.Data; 520 } 521 return *this; 522 } 523 ObjectKey &operator=(ObjectKey &&) = default; 524 525 operator llvm::StringRef() const { return Data; } 526 std::string str() const { return Data.str(); } 527 528private: 529 // FIXME: this is unneccesarily large (3 pointers). Pointer + length + owned 530 // could be 2 pointers at most. 531 std::unique_ptr<std::string> Owned; 532 llvm::StringRef Data; 533}; 534 535inline bool operator==(const ObjectKey &L, const ObjectKey &R) { 536 return llvm::StringRef(L) == llvm::StringRef(R); 537} 538inline bool operator!=(const ObjectKey &L, const ObjectKey &R) { 539 return !(L == R); 540} 541inline bool operator<(const ObjectKey &L, const ObjectKey &R) { 542 return StringRef(L) < StringRef(R); 543} 544 545struct Object::KV { 546 ObjectKey K; 547 Value V; 548}; 549 550inline Object::Object(std::initializer_list<KV> Properties) { 551 for (const auto &P : Properties) { 552 auto R = try_emplace(P.K, nullptr); 553 if (R.second) 554 R.first->getSecond().moveFrom(std::move(P.V)); 555 } 556} 557inline std::pair<Object::iterator, bool> Object::insert(KV E) { 558 return try_emplace(std::move(E.K), std::move(E.V)); 559} 560inline bool Object::erase(StringRef K) { 561 return M.erase(ObjectKey(K)); 562} 563 564// Standard deserializers are provided for primitive types. 565// See comments on Value. 566inline bool fromJSON(const Value &E, std::string &Out) { 567 if (auto S = E.getAsString()) { 568 Out = *S; 569 return true; 570 } 571 return false; 572} 573inline bool fromJSON(const Value &E, int &Out) { 574 if (auto S = E.getAsInteger()) { 575 Out = *S; 576 return true; 577 } 578 return false; 579} 580inline bool fromJSON(const Value &E, int64_t &Out) { 581 if (auto S = E.getAsInteger()) { 582 Out = *S; 583 return true; 584 } 585 return false; 586} 587inline bool fromJSON(const Value &E, double &Out) { 588 if (auto S = E.getAsNumber()) { 589 Out = *S; 590 return true; 591 } 592 return false; 593} 594inline bool fromJSON(const Value &E, bool &Out) { 595 if (auto S = E.getAsBoolean()) { 596 Out = *S; 597 return true; 598 } 599 return false; 600} 601template <typename T> bool fromJSON(const Value &E, llvm::Optional<T> &Out) { 602 if (E.getAsNull()) { 603 Out = llvm::None; 604 return true; 605 } 606 T Result; 607 if (!fromJSON(E, Result)) 608 return false; 609 Out = std::move(Result); 610 return true; 611} 612template <typename T> bool fromJSON(const Value &E, std::vector<T> &Out) { 613 if (auto *A = E.getAsArray()) { 614 Out.clear(); 615 Out.resize(A->size()); 616 for (size_t I = 0; I < A->size(); ++I) 617 if (!fromJSON((*A)[I], Out[I])) 618 return false; 619 return true; 620 } 621 return false; 622} 623template <typename T> 624bool fromJSON(const Value &E, std::map<std::string, T> &Out) { 625 if (auto *O = E.getAsObject()) { 626 Out.clear(); 627 for (const auto &KV : *O) 628 if (!fromJSON(KV.second, Out[llvm::StringRef(KV.first)])) 629 return false; 630 return true; 631 } 632 return false; 633} 634 635// Allow serialization of Optional<T> for supported T. 636template <typename T> Value toJSON(const llvm::Optional<T> &Opt) { 637 return Opt ? Value(*Opt) : Value(nullptr); 638} 639 640/// Helper for mapping JSON objects onto protocol structs. 641/// 642/// Example: 643/// \code 644/// bool fromJSON(const Value &E, MyStruct &R) { 645/// ObjectMapper O(E); 646/// if (!O || !O.map("mandatory_field", R.MandatoryField)) 647/// return false; 648/// O.map("optional_field", R.OptionalField); 649/// return true; 650/// } 651/// \endcode 652class ObjectMapper { 653public: 654 ObjectMapper(const Value &E) : O(E.getAsObject()) {} 655 656 /// True if the expression is an object. 657 /// Must be checked before calling map(). 658 operator bool() { return O; } 659 660 /// Maps a property to a field, if it exists. 661 template <typename T> bool map(StringRef Prop, T &Out) { 662 assert(*this && "Must check this is an object before calling map()"); 663 if (const Value *E = O->get(Prop)) 664 return fromJSON(*E, Out); 665 return false; 666 } 667 668 /// Maps a property to a field, if it exists. 669 /// (Optional requires special handling, because missing keys are OK). 670 template <typename T> bool map(StringRef Prop, llvm::Optional<T> &Out) { 671 assert(*this && "Must check this is an object before calling map()"); 672 if (const Value *E = O->get(Prop)) 673 return fromJSON(*E, Out); 674 Out = llvm::None; 675 return true; 676 } 677 678private: 679 const Object *O; 680}; 681 682/// Parses the provided JSON source, or returns a ParseError. 683/// The returned Value is self-contained and owns its strings (they do not refer 684/// to the original source). 685llvm::Expected<Value> parse(llvm::StringRef JSON); 686 687class ParseError : public llvm::ErrorInfo<ParseError> { 688 const char *Msg; 689 unsigned Line, Column, Offset; 690 691public: 692 static char ID; 693 ParseError(const char *Msg, unsigned Line, unsigned Column, unsigned Offset) 694 : Msg(Msg), Line(Line), Column(Column), Offset(Offset) {} 695 void log(llvm::raw_ostream &OS) const override { 696 OS << llvm::formatv("[{0}:{1}, byte={2}]: {3}", Line, Column, Offset, Msg); 697 } 698 std::error_code convertToErrorCode() const override { 699 return llvm::inconvertibleErrorCode(); 700 } 701}; 702 703/// json::OStream allows writing well-formed JSON without materializing 704/// all structures as json::Value ahead of time. 705/// It's faster, lower-level, and less safe than OS << json::Value. 706/// 707/// Only one "top-level" object can be written to a stream. 708/// Simplest usage involves passing lambdas (Blocks) to fill in containers: 709/// 710/// json::OStream J(OS); 711/// J.array([&]{ 712/// for (const Event &E : Events) 713/// J.object([&] { 714/// J.attribute("timestamp", int64_t(E.Time)); 715/// J.attributeArray("participants", [&] { 716/// for (const Participant &P : E.Participants) 717/// J.value(P.toString()); 718/// }); 719/// }); 720/// }); 721/// 722/// This would produce JSON like: 723/// 724/// [ 725/// { 726/// "timestamp": 19287398741, 727/// "participants": [ 728/// "King Kong", 729/// "Miley Cyrus", 730/// "Cleopatra" 731/// ] 732/// }, 733/// ... 734/// ] 735/// 736/// The lower level begin/end methods (arrayBegin()) are more flexible but 737/// care must be taken to pair them correctly: 738/// 739/// json::OStream J(OS); 740// J.arrayBegin(); 741/// for (const Event &E : Events) { 742/// J.objectBegin(); 743/// J.attribute("timestamp", int64_t(E.Time)); 744/// J.attributeBegin("participants"); 745/// for (const Participant &P : E.Participants) 746/// J.value(P.toString()); 747/// J.attributeEnd(); 748/// J.objectEnd(); 749/// } 750/// J.arrayEnd(); 751/// 752/// If the call sequence isn't valid JSON, asserts will fire in debug mode. 753/// This can be mismatched begin()/end() pairs, trying to emit attributes inside 754/// an array, and so on. 755/// With asserts disabled, this is undefined behavior. 756class OStream { 757 public: 758 using Block = llvm::function_ref<void()>; 759 // If IndentSize is nonzero, output is pretty-printed. 760 explicit OStream(llvm::raw_ostream &OS, unsigned IndentSize = 0) 761 : OS(OS), IndentSize(IndentSize) { 762 Stack.emplace_back(); 763 } 764 ~OStream() { 765 assert(Stack.size() == 1 && "Unmatched begin()/end()"); 766 assert(Stack.back().Ctx == Singleton); 767 assert(Stack.back().HasValue && "Did not write top-level value"); 768 } 769 770 /// Flushes the underlying ostream. OStream does not buffer internally. 771 void flush() { OS.flush(); } 772 773 // High level functions to output a value. 774 // Valid at top-level (exactly once), in an attribute value (exactly once), 775 // or in an array (any number of times). 776 777 /// Emit a self-contained value (number, string, vector<string> etc). 778 void value(const Value &V); 779 /// Emit an array whose elements are emitted in the provided Block. 780 void array(Block Contents) { 781 arrayBegin(); 782 Contents(); 783 arrayEnd(); 784 } 785 /// Emit an object whose elements are emitted in the provided Block. 786 void object(Block Contents) { 787 objectBegin(); 788 Contents(); 789 objectEnd(); 790 } 791 792 // High level functions to output object attributes. 793 // Valid only within an object (any number of times). 794 795 /// Emit an attribute whose value is self-contained (number, vector<int> etc). 796 void attribute(llvm::StringRef Key, const Value& Contents) { 797 attributeImpl(Key, [&] { value(Contents); }); 798 } 799 /// Emit an attribute whose value is an array with elements from the Block. 800 void attributeArray(llvm::StringRef Key, Block Contents) { 801 attributeImpl(Key, [&] { array(Contents); }); 802 } 803 /// Emit an attribute whose value is an object with attributes from the Block. 804 void attributeObject(llvm::StringRef Key, Block Contents) { 805 attributeImpl(Key, [&] { object(Contents); }); 806 } 807 808 // Low-level begin/end functions to output arrays, objects, and attributes. 809 // Must be correctly paired. Allowed contexts are as above. 810 811 void arrayBegin(); 812 void arrayEnd(); 813 void objectBegin(); 814 void objectEnd(); 815 void attributeBegin(llvm::StringRef Key); 816 void attributeEnd(); 817 818 private: 819 void attributeImpl(llvm::StringRef Key, Block Contents) { 820 attributeBegin(Key); 821 Contents(); 822 attributeEnd(); 823 } 824 825 void valueBegin(); 826 void newline(); 827 828 enum Context { 829 Singleton, // Top level, or object attribute. 830 Array, 831 Object, 832 }; 833 struct State { 834 Context Ctx = Singleton; 835 bool HasValue = false; 836 }; 837 llvm::SmallVector<State, 16> Stack; // Never empty. 838 llvm::raw_ostream &OS; 839 unsigned IndentSize; 840 unsigned Indent = 0; 841}; 842 843/// Serializes this Value to JSON, writing it to the provided stream. 844/// The formatting is compact (no extra whitespace) and deterministic. 845/// For pretty-printing, use the formatv() format_provider below. 846inline llvm::raw_ostream &operator<<(llvm::raw_ostream &OS, const Value &V) { 847 OStream(OS).value(V); 848 return OS; 849} 850} // namespace json 851 852/// Allow printing json::Value with formatv(). 853/// The default style is basic/compact formatting, like operator<<. 854/// A format string like formatv("{0:2}", Value) pretty-prints with indent 2. 855template <> struct format_provider<llvm::json::Value> { 856 static void format(const llvm::json::Value &, raw_ostream &, StringRef); 857}; 858} // namespace llvm 859 860#endif 861