LLVM 19.0.0git
Classes | Public Types | Public Member Functions | List of all members
llvm::json::OStream Class Reference

json::OStream allows writing well-formed JSON without materializing all structures as json::Value ahead of time. More...

#include "llvm/Support/JSON.h"

Public Types

using Block = llvm::function_ref< void()>
 

Public Member Functions

 OStream (llvm::raw_ostream &OS, unsigned IndentSize=0)
 
 ~OStream ()
 
void flush ()
 Flushes the underlying ostream. OStream does not buffer internally.
 
void value (const Value &V)
 Emit a self-contained value (number, string, vector<string> etc).
 
void array (Block Contents)
 Emit an array whose elements are emitted in the provided Block.
 
void object (Block Contents)
 Emit an object whose elements are emitted in the provided Block.
 
void rawValue (llvm::function_ref< void(raw_ostream &)> Contents)
 Emit an externally-serialized value.
 
void rawValue (llvm::StringRef Contents)
 
void comment (llvm::StringRef)
 Emit a JavaScript comment associated with the next printed value.
 
void attribute (llvm::StringRef Key, const Value &Contents)
 Emit an attribute whose value is self-contained (number, vector<int> etc).
 
void attributeArray (llvm::StringRef Key, Block Contents)
 Emit an attribute whose value is an array with elements from the Block.
 
void attributeObject (llvm::StringRef Key, Block Contents)
 Emit an attribute whose value is an object with attributes from the Block.
 
void arrayBegin ()
 
void arrayEnd ()
 
void objectBegin ()
 
void objectEnd ()
 
void attributeBegin (llvm::StringRef Key)
 
void attributeEnd ()
 
raw_ostreamrawValueBegin ()
 
void rawValueEnd ()
 

Detailed Description

json::OStream allows writing well-formed JSON without materializing all structures as json::Value ahead of time.

It's faster, lower-level, and less safe than OS << json::Value. It also allows emitting more constructs, such as comments.

Only one "top-level" object can be written to a stream. Simplest usage involves passing lambdas (Blocks) to fill in containers:

json::OStream J(OS); J.array([&]{ for (const Event &E : Events) J.object([&] { J.attribute("timestamp", int64_t(E.Time)); J.attributeArray("participants", [&] { for (const Participant &P : E.Participants) J.value(P.toString()); }); }); });

This would produce JSON like:

[ { "timestamp": 19287398741, "participants": [ "King Kong", "Miley Cyrus", "Cleopatra" ] }, ... ]

The lower level begin/end methods (arrayBegin()) are more flexible but care must be taken to pair them correctly:

json::OStream J(OS); for (const Event &E : Events) { J.objectBegin(); J.attribute("timestamp", int64_t(E.Time)); J.attributeBegin("participants"); for (const Participant &P : E.Participants) J.value(P.toString()); J.attributeEnd(); J.objectEnd(); } J.arrayEnd();

If the call sequence isn't valid JSON, asserts will fire in debug mode. This can be mismatched begin()/end() pairs, trying to emit attributes inside an array, and so on. With asserts disabled, this is undefined behavior.

Definition at line 977 of file JSON.h.

Member Typedef Documentation

◆ Block

Definition at line 979 of file JSON.h.

Constructor & Destructor Documentation

◆ OStream()

llvm::json::OStream::OStream ( llvm::raw_ostream OS,
unsigned  IndentSize = 0 
)
inlineexplicit

Definition at line 981 of file JSON.h.

References llvm::SmallVectorImpl< T >::emplace_back(), and OS.

◆ ~OStream()

llvm::json::OStream::~OStream ( )
inline

Member Function Documentation

◆ array()

void llvm::json::OStream::array ( Block  Contents)
inline

Emit an array whose elements are emitted in the provided Block.

Definition at line 1001 of file JSON.h.

References arrayBegin(), and arrayEnd().

Referenced by attributeArray(), and llvm::json::Path::Root::printErrorContext().

◆ arrayBegin()

void llvm::json::OStream::arrayBegin ( )

Definition at line 844 of file JSON.cpp.

References OS.

Referenced by array(), llvm::sampleprof::SampleProfileReader::dumpJson(), and llvm::TimeTraceProfiler::write().

◆ arrayEnd()

void llvm::json::OStream::arrayEnd ( )

Definition at line 852 of file JSON.cpp.

References assert(), and OS.

Referenced by array(), llvm::sampleprof::SampleProfileReader::dumpJson(), and llvm::TimeTraceProfiler::write().

◆ attribute()

void llvm::json::OStream::attribute ( llvm::StringRef  Key,
const Value Contents 
)
inline

◆ attributeArray()

void llvm::json::OStream::attributeArray ( llvm::StringRef  Key,
Block  Contents 
)
inline

Emit an attribute whose value is an array with elements from the Block.

Definition at line 1036 of file JSON.h.

References array().

Referenced by dumpFunctionProfileJson(), and llvm::JSONScopedPrinter::printList().

◆ attributeBegin()

void llvm::json::OStream::attributeBegin ( llvm::StringRef  Key)

◆ attributeEnd()

void llvm::json::OStream::attributeEnd ( )

◆ attributeObject()

void llvm::json::OStream::attributeObject ( llvm::StringRef  Key,
Block  Contents 
)
inline

Emit an attribute whose value is an object with attributes from the Block.

Definition at line 1040 of file JSON.h.

References object().

Referenced by llvm::TimeTraceProfiler::write().

◆ comment()

void llvm::json::OStream::comment ( llvm::StringRef  Comment)

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!

Definition at line 807 of file JSON.cpp.

References assert().

Referenced by llvm::json::Path::Root::printErrorContext().

◆ flush()

void llvm::json::OStream::flush ( )
inline

Flushes the underlying ostream. OStream does not buffer internally.

Definition at line 992 of file JSON.h.

References llvm::raw_ostream::flush().

◆ object()

void llvm::json::OStream::object ( Block  Contents)
inline

Emit an object whose elements are emitted in the provided Block.

Definition at line 1007 of file JSON.h.

References objectBegin(), and objectEnd().

Referenced by attributeObject(), dumpFunctionProfileJson(), llvm::json::Path::Root::printErrorContext(), llvm::Logger::startObservation(), llvm::Logger::switchContext(), and llvm::TimeTraceProfiler::write().

◆ objectBegin()

void llvm::json::OStream::objectBegin ( )

Definition at line 863 of file JSON.cpp.

References OS.

Referenced by object(), and llvm::TimeTraceProfiler::write().

◆ objectEnd()

void llvm::json::OStream::objectEnd ( )

Definition at line 871 of file JSON.cpp.

References assert(), and OS.

Referenced by object(), and llvm::TimeTraceProfiler::write().

◆ rawValue() [1/2]

void llvm::json::OStream::rawValue ( llvm::function_ref< void(raw_ostream &)>  Contents)
inline

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.

Definition at line 1015 of file JSON.h.

References rawValueBegin(), and rawValueEnd().

Referenced by rawValue().

◆ rawValue() [2/2]

void llvm::json::OStream::rawValue ( llvm::StringRef  Contents)
inline

Definition at line 1020 of file JSON.h.

References OS, and rawValue().

◆ rawValueBegin()

raw_ostream & llvm::json::OStream::rawValueBegin ( )

Definition at line 910 of file JSON.cpp.

References OS.

Referenced by rawValue().

◆ rawValueEnd()

void llvm::json::OStream::rawValueEnd ( )

Definition at line 917 of file JSON.cpp.

References assert().

Referenced by rawValue().

◆ value()

void llvm::json::OStream::value ( const Value V)

The documentation for this class was generated from the following files: