[json] Provide a means to delegate writing a value to another API

[sammccall]

Summary

(Based on D87170 by dsanders)

I recently had need to call out to an external API to emit a JSON object as part
of one an LLVM tool was emitting. However, our JSON support didn't provide a way
to delegate part of the JSON output to that API.

Add rawValueBegin() and rawValueEnd() to maintain and check the internal state
while something else is writing to the stream. It's the users responsibility to
ensure that the resulting JSON output is still valid.

[kadircet]

So that's how you hit function_ref being constructable from anything :D

Thanks, LGTM! It is amazing how fast that FIXME got cleaned up

llvm/include/llvm/Support/JSON.h

void array(Block Contents) {
     arrayEnd();
   }
   /// Emit an object whose elements are emitted in the provided Block.
   void object(Block Contents) {
     objectBegin();
     Contents();
     objectEnd();
   }
+  /// Emit an externally-serialized value.
+  /// The caller must write exactly one valid JSON value to the provided stream.
+  /// No validation or formatting of this value occurs.
+  void rawValue(llvm::function_ref<void(raw_ostream &)> Contents) {
+    rawValueBegin();
+    Contents(OS);
+    rawValueEnd();
+  }
+  void rawValue(llvm::StringRef Contents) {
+    rawValue([&](raw_ostream &OS) { OS << Contents; });
+  }
   /// Emit a JavaScript comment associated with the next printed value.
   /// The string must be valid until the next attribute or value is emitted.
   /// Comments are not part of standard JSON, and many parsers reject them!
   void comment(llvm::StringRef);
 
   // High level functions to output object attributes.
   // Valid only within an object (any number of times).
 
public:
   // Must be correctly paired. Allowed contexts are as above.
 
   void arrayBegin();
   void arrayEnd();
   void objectBegin();
   void objectEnd();
   void attributeBegin(llvm::StringRef Key);
   void attributeEnd();
+  raw_ostream &rawValueBegin();
+  void rawValueEnd();
 
- private:
   void attributeImpl(llvm::StringRef Key, Block Contents) {
     attributeBegin(Key);
     Contents();
     attributeEnd();
   }
 
   void valueBegin();
   void flushComment();
   void newline();
 
   enum Context {
     Singleton, // Top level, or object attribute.
     Array,
     Object,
+    RawValue, // External code writing a value to OS directly.
   };
   struct State {
     Context Ctx = Singleton;
     bool HasValue = false;
   };
   llvm::SmallVector<State, 16> Stack; // Never empty.
   llvm::StringRef PendingComment;
   llvm::raw_ostream &OS;

llvm/lib/Support/JSON.cpp

llvm::sort(Elements,
                return L->first < R->first;
              });
   return Elements;
 }
 
 // Prints a one-line version of a value that isn't our main focus.
 // We interleave writes to OS and JOS, exploiting the lack of extra buffering.
 // This is OK as we own the implementation.
-// FIXME: once we have a "write custom serialized value" API, use it here.
-void abbreviate(const Value &V, OStream &JOS, raw_ostream &OS) {
+void abbreviate(const Value &V, OStream &JOS) {
   switch (V.kind()) {
   case Value::Array:
-    JOS.array([&] {
-      if (!V.getAsArray()->empty())
-        OS << " ... ";
-    });
+    JOS.rawValue(V.getAsArray()->empty() ? "[]" : "[ ... ]");
     break;
   case Value::Object:
-    JOS.object([&] {
-      if (!V.getAsObject()->empty())
-        OS << " ... ";
-    });
+    JOS.rawValue(V.getAsObject()->empty() ? "{}" : "{ ... }");
     break;
   case Value::String: {
     llvm::StringRef S = *V.getAsString();
     if (S.size() < 40) {
       JOS.value(V);
     } else {
       std::string Truncated = fixUTF8(S.take_front(37));
       Truncated.append("...");
       JOS.value(Truncated);
     }
     break;
   }
   default:
     JOS.value(V);
   }
 }
 
 // Prints a semi-expanded version of a value that is our main focus.
 // Array/Object entries are printed, but not recursively as they may be huge.
-void abbreviateChildren(const Value &V, OStream &JOS, raw_ostream &OS) {
+void abbreviateChildren(const Value &V, OStream &JOS) {
   switch (V.kind()) {
   case Value::Array:
     JOS.array([&] {
       for (const auto &I : *V.getAsArray())
-        abbreviate(I, JOS, OS);
+        abbreviate(I, JOS);
     });
     break;
   case Value::Object:
     JOS.object([&] {
       for (const auto *KV : sortedElements(*V.getAsObject())) {
         JOS.attributeBegin(KV->first);
-        abbreviate(KV->second, JOS, OS);
+        abbreviate(KV->second, JOS);
         JOS.attributeEnd();
       }
     });
     break;
   default:
     JOS.value(V);
   }
 }
void Path::Root::printErrorContext(const Value &R, raw_ostream &OS) const {
   auto PrintValue = [&](const Value &V, ArrayRef<Segment> Path, auto &Recurse) {
     // Print the target node itself, with the error as a comment.
     // Also used if we can't follow our path, e.g. it names a field that
     // *should* exist but doesn't.
     auto HighlightCurrent = [&] {
       std::string Comment = "error: ";
       Comment.append(ErrorMessage.data(), ErrorMessage.size());
       JOS.comment(Comment);
-      abbreviateChildren(V, JOS, OS);
+      abbreviateChildren(V, JOS);
     };
     if (Path.empty()) // We reached our target.
       return HighlightCurrent();
     const Segment &S = Path.back(); // Path is in reverse order.
     if (S.isField()) {
       // Current node is an object, path names a field.
       llvm::StringRef FieldName = S.field();
       const Object *O = V.getAsObject();
       if (!O || !O->get(FieldName))
         return HighlightCurrent();
       JOS.object([&] {
         for (const auto *KV : sortedElements(*O)) {
           JOS.attributeBegin(KV->first);
           if (FieldName.equals(KV->first))
             Recurse(KV->second, Path.drop_back(), Recurse);
           else
-            abbreviate(KV->second, JOS, OS);
+            abbreviate(KV->second, JOS);
           JOS.attributeEnd();
         }
       });
     } else {
       // Current node is an array, path names an element.
       const Array *A = V.getAsArray();
       if (!A || S.index() >= A->size())
         return HighlightCurrent();
       JOS.array([&] {
         unsigned Current = 0;
         for (const auto &V : *A) {
           if (Current++ == S.index())
             Recurse(V, Path.drop_back(), Recurse);
           else
-            abbreviate(V, JOS, OS);
+            abbreviate(V, JOS);
         }
       });
     }
   };
   PrintValue(R, ErrorPath, PrintValue);
 }
 
 namespace {

 void llvm::json::OStream::attributeEnd() {
   assert(Stack.back().Ctx == Singleton);
   assert(Stack.back().HasValue && "Attribute must have a value");
   assert(PendingComment.empty());
   Stack.pop_back();
   assert(Stack.back().Ctx == Object);
 }
 
+raw_ostream &llvm::json::OStream::rawValueBegin() {
+  valueBegin();
+  Stack.emplace_back();
+  Stack.back().Ctx = RawValue;
+  return OS;
+}
+
+void llvm::json::OStream::rawValueEnd() {
+  assert(Stack.back().Ctx == RawValue);
+  Stack.pop_back();
+}
+
 } // namespace json
 } // namespace llvm
 
 void llvm::format_provider<llvm::json::Value>::format(
     const llvm::json::Value &E, raw_ostream &OS, StringRef Options) {
   unsigned IndentAmount = 0;
   if (!Options.empty() && Options.getAsInteger(/*Radix=*/10, IndentAmount))
     llvm_unreachable("json::Value format options should be an integer");
   json::OStream(OS, IndentAmount).value(E);
 }
 

llvm/unittests/Support/JSONTest.cpp

auto StreamStuff = [](unsigned Indent) {
     J.object([&] {
       J.attributeArray("foo", [&] {
         J.value(nullptr);
         J.comment("element");
         J.value(42.5);
         J.arrayBegin();
         J.value(43);
         J.arrayEnd();
+        J.rawValue([](raw_ostream &OS) { OS << "'unverified\nraw value'"; });
       });
       J.comment("attribute");
       J.attributeBegin("bar");
       J.comment("attribute value");
       J.objectBegin();
       J.objectEnd();
       J.attributeEnd();
       J.attribute("baz", "xyz");
     });
     return OS.str();
   };
 
   const char *Plain =
-      R"(/*top* /level*/{"foo":[null,/*element*/42.5,[43]],/*attribute*/"bar":/*attribute value*/{},"baz":"xyz"})";
+      R"(/*top* /level*/{"foo":[null,/*element*/42.5,[43],'unverified
+raw value'],/*attribute*/"bar":/*attribute value*/{},"baz":"xyz"})";
   EXPECT_EQ(Plain, StreamStuff(0));
   const char *Pretty = R"(/* top* /level */
 {
   "foo": [
     null,
     /* element */
     42.5,
     [
       43
-    ]
+    ],
+    'unverified
+raw value'
   ],
   /* attribute */
   "bar": /* attribute value */ {},
   "baz": "xyz"
 })";
   EXPECT_EQ(Pretty, StreamStuff(2));
 }