LLVM  13.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. More...
 
void value (const Value &V)
 Emit a self-contained value (number, string, vector<string> etc). More...
 
void array (Block Contents)
 Emit an array whose elements are emitted in the provided Block. More...
 
void object (Block Contents)
 Emit an object whose elements are emitted in the provided Block. More...
 
void rawValue (llvm::function_ref< void(raw_ostream &)> Contents)
 Emit an externally-serialized value. More...
 
void rawValue (llvm::StringRef Contents)
 
void comment (llvm::StringRef)
 Emit a JavaScript comment associated with the next printed value. More...
 
void attribute (llvm::StringRef Key, const Value &Contents)
 Emit an attribute whose value is self-contained (number, vector<int> etc). More...
 
void attributeArray (llvm::StringRef Key, Block Contents)
 Emit an attribute whose value is an array with elements from the Block. More...
 
void attributeObject (llvm::StringRef Key, Block Contents)
 Emit an attribute whose value is an object with attributes from the Block. More...
 
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 886 of file JSON.h.

Member Typedef Documentation

◆ Block

Definition at line 888 of file JSON.h.

Constructor & Destructor Documentation

◆ OStream()

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

Definition at line 890 of file JSON.h.

References llvm::SmallVectorImpl< T >::emplace_back().

◆ ~OStream()

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

Definition at line 894 of file JSON.h.

References assert().

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 910 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 823 of file JSON.cpp.

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

◆ arrayEnd()

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

Definition at line 831 of file JSON.cpp.

References assert().

Referenced by array().

◆ attribute()

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

Emit an attribute whose value is self-contained (number, vector<int> etc).

Definition at line 941 of file JSON.h.

References value().

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

◆ 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 945 of file JSON.h.

References array().

◆ attributeBegin()

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

◆ attributeEnd()

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

Definition at line 881 of file JSON.cpp.

References assert().

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

◆ 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 949 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 786 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 901 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 916 of file JSON.h.

References objectBegin(), and objectEnd().

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

◆ objectBegin()

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

Definition at line 842 of file JSON.cpp.

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

◆ objectEnd()

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

Definition at line 850 of file JSON.cpp.

References assert().

Referenced by object().

◆ 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 924 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 929 of file JSON.h.

References rawValue().

◆ rawValueBegin()

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

Definition at line 889 of file JSON.cpp.

Referenced by rawValue().

◆ rawValueEnd()

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

Definition at line 896 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: