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

[dsanders]

Summary

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.

[sammccall]

This is really nice. There's an argument for parsing and emitting (validation and formatting) but obviously also a performance tradeoff so the feature makes sense.

Just some style nits (mostly local consistency) and a small API tweak again for consistency.

llvm/include/llvm/Support/JSON.h

793

can we have a rawValue(function_ref<void(raw_ostream&)>)?

The "low-level" ideas of raw-output and no-lexical-nesting are independent.

Providing the ostream as a parameter makes the usable lifetime clear.

821

Consistently with the others, we should doc this among the high level functions, and leave the low-level ones undocumented.

821

"something external" is a bit vague.

Maybe "Write an externally-serialized value. The caller must write exactly one valid JSON value to the provided stream. No validation or formatting is performed on the output."

822

This can return raw_ostream&, to relieve the caller of needing to hold a reference, and to hide the implementation detail that we don't internally wrap the original ostream.

842

nit: this should match the name of the feature elsewhere, as they directly correspond. RawValue?
nit: comment needs to mention that it's a single value
nit: line comment as above.

Maybe "// External code is writing a single value to OS directly"?

llvm/lib/Support/JSON.cpp

639

nit: move after attributeBegin/End to match decls?

647

nit: drop assertion message for consistency with other End functions

[sammccall]

I like this feature, and we have a use case for it too (inside the error-printer in JSON.cpp itself).

Do you want to do another pass on it, and add some tests? If not, I'm happy to do this myself

[sammccall]

D88902 is a stab at addressing the comments here, adding a test, and using this to implement printErrorContext().

llvm/include/llvm/Support/JSON.h

void array(Block Contents) {
     Contents();
     arrayEnd();
   }
   /// Emit an object whose elements are emitted in the provided Block.
   void object(Block Contents) {
     objectBegin();
     Contents();
     objectEnd();
   }
 
   // High level functions to output object attributes.
   // Valid only within an object (any number of times).
 
   /// Emit an attribute whose value is self-contained (number, vector<int> etc).
   void attribute(llvm::StringRef Key, const Value& Contents) {
     attributeImpl(Key, [&] { value(Contents); });
   }
public:
 
   void arrayBegin();
   void arrayEnd();
   void objectBegin();
   void objectEnd();
   void attributeBegin(llvm::StringRef Key);
   void attributeEnd();
 
- private:
+  /// Inform the writer that something external is about to write a value to OS.
+  void rawValueBegin();
+  /// Inform the writer that something external has finished writing a value to
+  /// OS.
+  void rawValueEnd();
+
   void attributeImpl(llvm::StringRef Key, Block Contents) {
     attributeBegin(Key);
     Contents();
     attributeEnd();
   }
 
   void valueBegin();
   void newline();
 
   enum Context {
     Singleton, // Top level, or object attribute.
     Array,
     Object,
+    /// Something outside this object is writing to OS such as a 3rd-party API.
+    ExternalStreamWriter,
   };
   struct State {
     Context Ctx = Singleton;
     bool HasValue = false;
   };
   llvm::SmallVector<State, 16> Stack; // Never empty.
   llvm::raw_ostream &OS;
   unsigned IndentSize;

llvm/lib/Support/JSON.cpp

if (Stack.back().HasValue) {
     assert(Stack.back().Ctx != Singleton && "Only one value allowed here");
     OS << ',';
   }
   if (Stack.back().Ctx == Array)
     newline();
   Stack.back().HasValue = true;
 }
 
+void llvm::json::OStream::rawValueBegin() {
+  valueBegin();
+  Stack.emplace_back();
+  Stack.back().Ctx = ExternalStreamWriter;
+}
+
+void llvm::json::OStream::rawValueEnd() {
+  assert(Stack.back().Ctx == ExternalStreamWriter &&
+         "Expected matching rawValueBegin");
+  Stack.pop_back();
+}
+
 void llvm::json::OStream::newline() {
   if (IndentSize) {
     OS.write('\n');
     OS.indent(Indent);
   }
 }
 
 void llvm::json::OStream::arrayBegin() {