LLVM 20.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_ostream & rawValueBegin ()
 
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 979 of file JSON.h.

Member Typedef Documentation

◆ Block

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

Definition at line 981 of file JSON.h.

Constructor & Destructor Documentation

◆ OStream()

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

Definition at line 983 of file JSON.h.

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

◆ ~OStream()

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

Definition at line 987 of file JSON.h.

References assert(), llvm::SmallVectorTemplateCommon< T, typename >::back(), and llvm::SmallVectorBase< Size_T >::size().

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

References arrayBegin(), and arrayEnd().

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

◆ arrayBegin()

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

Definition at line 840 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 848 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

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

Definition at line 1034 of file JSON.h.

References value.

Referenced by dumpFunctionProfileJson(), llvm::JSONScopedPrinter::printBoolean(), llvm::JSONScopedPrinter::printNumber(), llvm::JSONScopedPrinter::printString(), llvm::Logger::startObservation(), llvm::Logger::switchContext(), and 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 1038 of file JSON.h.

References array().

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

◆ attributeBegin()

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

Definition at line 878 of file JSON.cpp.

References assert(), llvm::json::fixUTF8(), llvm::json::isUTF8(), LLVM_LIKELY, OS, and llvm::json::quote().

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

◆ attributeEnd()

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

Definition at line 898 of file JSON.cpp.

References assert().

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

◆ 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 1042 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 803 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 994 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 1009 of file JSON.h.

References objectBegin(), and objectEnd().

Referenced by llvm::json::abbreviateChildren(), 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 859 of file JSON.cpp.

References OS.

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

◆ objectEnd()

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

Definition at line 867 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 1017 of file JSON.h.

References rawValueBegin(), and rawValueEnd().

Referenced by llvm::json::abbreviate(), and rawValue().

◆ rawValue() [2/2]

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

Definition at line 1022 of file JSON.h.

References OS, and rawValue().

◆ rawValueBegin()

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

Definition at line 906 of file JSON.cpp.

References OS.

Referenced by rawValue().

◆ rawValueEnd()

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

Definition at line 913 of file JSON.cpp.

References assert().

Referenced by rawValue().

◆ value()

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

Emit a self-contained value (number, string, vector<string> etc).

Definition at line 754 of file JSON.cpp.

References llvm::json::Value::Array, llvm::json::Value::Boolean, E, llvm::format(), llvm::json::Value::Null, llvm::json::Value::Number, llvm::json::Value::Object, OS, llvm::json::quote(), llvm::json::sortedElements(), llvm::json::Value::String, and value.

Referenced by llvm::json::abbreviate(), llvm::json::abbreviateChildren(), llvm::format_provider< llvm::json::Value >::format(), llvm::json::operator<<(), and llvm::JSONScopedPrinter::printString().

The documentation for this class was generated from the following files:
Generated on Wed Sep 11 2024 18:59:35 for LLVM by doxygen 1.9.6