ezJSONWriter Class Reference

The base class for JSON writers. More...

#include <JSONWriter.h>

Inheritance diagram for ezJSONWriter:

Public Types
enum class	WhitespaceMode {   All , LessIndentation , NoIndentation , NewlinesOnly ,   None }
	Modes to configure how much whitespace the JSON writer will output. More...
enum class	ArrayMode { InOneLine , OneLinePerItem }
	Modes to configure how arrays are written. More...

Public Member Functions
	ezJSONWriter ()
	Constructor.
virtual	~ezJSONWriter ()
	Destructor.
void	SetWhitespaceMode (WhitespaceMode whitespaceMode)
	Configures how much whitespace is output.
void	SetArrayMode (ArrayMode arrayMode)
	Configures how arrays are written.
void	AddVariableBool (ezStringView sName, bool value)
	Shorthand for "BeginVariable(szName); WriteBool(value); EndVariable(); ".
void	AddVariableInt32 (ezStringView sName, ezInt32 value)
	Shorthand for "BeginVariable(szName); WriteInt32(value); EndVariable(); ".
void	AddVariableUInt32 (ezStringView sName, ezUInt32 value)
	Shorthand for "BeginVariable(szName); WriteUInt32(value); EndVariable(); ".
void	AddVariableInt64 (ezStringView sName, ezInt64 value)
	Shorthand for "BeginVariable(szName); WriteInt64(value); EndVariable(); ".
void	AddVariableUInt64 (ezStringView sName, ezUInt64 value)
	Shorthand for "BeginVariable(szName); WriteUInt64(value); EndVariable(); ".
void	AddVariableFloat (ezStringView sName, float value)
	Shorthand for "BeginVariable(szName); WriteFloat(value); EndVariable(); ".
void	AddVariableDouble (ezStringView sName, double value)
	Shorthand for "BeginVariable(szName); WriteDouble(value); EndVariable(); ".
void	AddVariableString (ezStringView sName, ezStringView value)
	Shorthand for "BeginVariable(szName); WriteString(value); EndVariable(); ".
void	AddVariableNULL (ezStringView sName)
	Shorthand for "BeginVariable(szName); WriteNULL(value); EndVariable(); ".
void	AddVariableTime (ezStringView sName, ezTime value)
	Shorthand for "BeginVariable(szName); WriteTime(value); EndVariable(); ".
void	AddVariableUuid (ezStringView sName, ezUuid value)
	Shorthand for "BeginVariable(szName); WriteUuid(value); EndVariable(); ".
void	AddVariableAngle (ezStringView sName, ezAngle value)
	Shorthand for "BeginVariable(szName); WriteAngle(value); EndVariable(); ".
void	AddVariableColor (ezStringView sName, const ezColor &value)
	Shorthand for "BeginVariable(szName); WriteColor(value); EndVariable(); ".
void	AddVariableColorGamma (ezStringView sName, const ezColorGammaUB &value)
	Shorthand for "BeginVariable(szName); WriteColorGamma(value); EndVariable(); ".
void	AddVariableVec2 (ezStringView sName, const ezVec2 &value)
	Shorthand for "BeginVariable(szName); WriteVec2(value); EndVariable(); ".
void	AddVariableVec3 (ezStringView sName, const ezVec3 &value)
	Shorthand for "BeginVariable(szName); WriteVec3(value); EndVariable(); ".
void	AddVariableVec4 (ezStringView sName, const ezVec4 &value)
	Shorthand for "BeginVariable(szName); WriteVec4(value); EndVariable(); ".
void	AddVariableVec2I32 (ezStringView sName, const ezVec2I32 &value)
	Shorthand for "BeginVariable(szName); WriteVec2I32(value); EndVariable(); ".
void	AddVariableVec3I32 (ezStringView sName, const ezVec3I32 &value)
	Shorthand for "BeginVariable(szName); WriteVec3I32(value); EndVariable(); ".
void	AddVariableVec4I32 (ezStringView sName, const ezVec4I32 &value)
	Shorthand for "BeginVariable(szName); WriteVec4I32(value); EndVariable(); ".
void	AddVariableQuat (ezStringView sName, const ezQuat &value)
	Shorthand for "BeginVariable(szName); WriteQuat(value); EndVariable(); ".
void	AddVariableMat3 (ezStringView sName, const ezMat3 &value)
	Shorthand for "BeginVariable(szName); WriteMat3(value); EndVariable(); ".
void	AddVariableMat4 (ezStringView sName, const ezMat4 &value)
	Shorthand for "BeginVariable(szName); WriteMat4(value); EndVariable(); ".
void	AddVariableDataBuffer (ezStringView sName, const ezDataBuffer &value)
	Shorthand for "BeginVariable(szName); WriteDataBuffer(value); EndVariable(); ".
void	AddVariableVariant (ezStringView sName, const ezVariant &value)
	Shorthand for "BeginVariable(szName); WriteVariant(value); EndVariable(); ".
virtual void	WriteBool (bool value)=0
	Writes a bool to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().
virtual void	WriteInt32 (ezInt32 value)=0
	Writes an int32 to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().
virtual void	WriteUInt32 (ezUInt32 value)=0
	Writes a uint32 to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().
virtual void	WriteInt64 (ezInt64 value)=0
	Writes an int64 to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().
virtual void	WriteUInt64 (ezUInt64 value)=0
	Writes a uint64 to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().
virtual void	WriteFloat (float value)=0
	Writes a float to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().
virtual void	WriteDouble (double value)=0
	Writes a double to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().
virtual void	WriteString (ezStringView value)=0
	Writes a string to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().
virtual void	WriteNULL ()=0
	Writes the value 'null' to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().
virtual void	WriteTime (ezTime value)=0
	Writes a time value to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().
virtual void	WriteColor (const ezColor &value)=0
	Writes an ezColor to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().
virtual void	WriteColorGamma (const ezColorGammaUB &value)=0
	Writes an ezColorGammaUB to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().
virtual void	WriteVec2 (const ezVec2 &value)=0
	Writes an ezVec2 to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().
virtual void	WriteVec3 (const ezVec3 &value)=0
	Writes an ezVec3 to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().
virtual void	WriteVec4 (const ezVec4 &value)=0
	Writes an ezVec4 to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().
virtual void	WriteVec2I32 (const ezVec2I32 &value)=0
	Writes an ezVec2I32 to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().
virtual void	WriteVec3I32 (const ezVec3I32 &value)=0
	Writes an ezVec3I32 to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().
virtual void	WriteVec4I32 (const ezVec4I32 &value)=0
	Writes an ezVec4I32 to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().
virtual void	WriteQuat (const ezQuat &value)=0
	Writes an ezQuat to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().
virtual void	WriteMat3 (const ezMat3 &value)=0
	Writes an ezMat3 to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().
virtual void	WriteMat4 (const ezMat4 &value)=0
	Writes an ezMat4 to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().
virtual void	WriteUuid (const ezUuid &value)=0
	Writes an ezUuid to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().
virtual void	WriteAngle (ezAngle value)=0
	Writes an ezAngle to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().
virtual void	WriteDataBuffer (const ezDataBuffer &value)=0
	Writes an ezDataBuffer to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().
virtual void	WriteVariant (const ezVariant &value)
	The default implementation dispatches all supported types to WriteBool, WriteInt32, etc. and asserts on the more complex types.
virtual void	WriteBinaryData (ezStringView sDataType, const void *pData, ezUInt32 uiBytes, ezStringView sValueString=nullptr)=0
	Outputs a chunk of memory in some JSON form that can be interpreted as binary data when reading it again.
virtual void	BeginVariable (ezStringView sName)=0
	Begins outputting a variable. szName is the variable name.
virtual void	EndVariable ()=0
	Ends outputting a variable.
virtual void	BeginArray (ezStringView sName=nullptr)=0
	Begins outputting an array variable.
virtual void	EndArray ()=0
	Ends outputting an array variable.
virtual void	BeginObject (ezStringView sName=nullptr)=0
	Begins outputting an object variable.
virtual void	EndObject ()=0
	Ends outputting an object variable.
bool	HadWriteError () const
	Indicates if an error was encountered while writing.
void	Abandon ()
	Gives up on the output, so that the writer may be destroyed with containers still open.

Protected Member Functions
void	SetWriteErrorState ()
	called internally when there was an error during writing

Protected Attributes
WhitespaceMode	m_WhitespaceMode = WhitespaceMode::All
ArrayMode	m_ArrayMode = ArrayMode::InOneLine

Detailed Description

The base class for JSON writers.

Declares a common interface for writing JSON files. Also implements some utility functions built on top of the interface (AddVariable()).

Member Enumeration Documentation

ArrayMode

enum class ezJSONWriter::ArrayMode

strong

Modes to configure how arrays are written.

Enumerator
InOneLine	All array items are written in a single line in the file.
OneLinePerItem	Each array item is put on a separate line.

WhitespaceMode

enum class ezJSONWriter::WhitespaceMode

strong

Modes to configure how much whitespace the JSON writer will output.

Enumerator
All	All whitespace is output. This is the default, it should be used for files that are read by humans.
LessIndentation	Saves some space by using less space for indentation.
NoIndentation	Saves even more space by dropping all indentation from the output. The result will be noticeably less readable.
NewlinesOnly	All unnecessary whitespace, except for newlines, is not output.
None	No whitespace, not even newlines, is output. This should be used when JSON is used for data exchange, but probably not read by humans.

Member Function Documentation

Abandon()

void ezJSONWriter::Abandon ( )

inline

Gives up on the output, so that the writer may be destroyed with containers still open.

Derived writers are allowed to assert on destruction that every BeginObject() / BeginArray() was matched, because an unbalanced stream is usually a bug. That check makes an early return between Begin and End fatal, which is a problem for code that discovers half way through writing that it cannot continue - a failed lookup, an object that turned out to be invalid.

Calling this marks the output as unusable and suppresses that check. The written text is not valid JSON afterwards and must not be used. To bail out and still produce usable output, use ezStandardJSONWriter::EndAll() instead.

BeginArray()

virtual void ezJSONWriter::BeginArray ( ezStringView  sName = nullptr )

pure virtual

Begins outputting an array variable.

If szName is nullptr this will create an anonymous array, which is necessary when you want to put an array as a value into another array. BeginArray() with a non-nullptr value for szName is identical to calling BeginVariable() first. In this case EndArray() will also end the variable definition, so no additional call to EndVariable() is required.

Implemented in ezStandardJSONWriter.

BeginObject()

virtual void ezJSONWriter::BeginObject ( ezStringView  sName = nullptr )

pure virtual

Begins outputting an object variable.

If szName is nullptr this will create an anonymous object, which is necessary when you want to put an object as a value into an array. BeginObject() with a non-nullptr value for szName is identical to calling BeginVariable() first. In this case EndObject() will also end the variable definition, so no additional call to EndVariable() is required.

Implemented in ezStandardJSONWriter.

BeginVariable()

virtual void ezJSONWriter::BeginVariable ( ezStringView  sName )

pure virtual

Begins outputting a variable. szName is the variable name.

Between BeginVariable() and EndVariable() you can call the WriteXYZ functions once to write out the variable's data. You can also call BeginArray() and BeginObject() without a variable name to output an array or object variable.

Implemented in ezStandardJSONWriter.

EndArray()

virtual void ezJSONWriter::EndArray ( )

pure virtual

Ends outputting an array variable.

Implemented in ezStandardJSONWriter.

EndObject()

virtual void ezJSONWriter::EndObject ( )

pure virtual

Ends outputting an object variable.

Implemented in ezStandardJSONWriter.

EndVariable()

virtual void ezJSONWriter::EndVariable ( )

pure virtual

Ends outputting a variable.

Implemented in ezStandardJSONWriter.

HadWriteError()

bool ezJSONWriter::HadWriteError

(

)

const

Indicates if an error was encountered while writing.

If any error was encountered at any time during writing, this will return true

WriteAngle()

virtual void ezJSONWriter::WriteAngle ( ezAngle  value )

pure virtual

Writes an ezAngle to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().

Note

Standard JSON does not have a suitable type for this. A derived class might turn this into an object or output it via WriteBinaryData().

Implemented in ezStandardJSONWriter.

WriteBinaryData()

virtual void ezJSONWriter::WriteBinaryData ( ezStringView  sDataType, const void *  pData, ezUInt32  uiBytes, ezStringView  sValueString = nullptr  )

pure virtual

Outputs a chunk of memory in some JSON form that can be interpreted as binary data when reading it again.

How exactly the raw data is represented in JSON is up to the derived class. szDataType allows to additionally output a string that identifies the type of data.

Implemented in ezStandardJSONWriter.

WriteBool()

virtual void ezJSONWriter::WriteBool ( bool  value )

pure virtual

Writes a bool to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().

Implemented in ezStandardJSONWriter.

WriteColor()

void ezJSONWriter::WriteColor ( const ezColor &  value )

pure virtual

Writes an ezColor to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().

Note

Standard JSON does not have a suitable type for this. A derived class might turn this into an object or output it via WriteBinaryData().

Implemented in ezStandardJSONWriter.

WriteColorGamma()

void ezJSONWriter::WriteColorGamma ( const ezColorGammaUB &  value )

pure virtual

Writes an ezColorGammaUB to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().

Note

Standard JSON does not have a suitable type for this. A derived class might turn this into an object or output it via WriteBinaryData().

Implemented in ezStandardJSONWriter.

WriteDataBuffer()

void ezJSONWriter::WriteDataBuffer ( const ezDataBuffer &  value )

pure virtual

Writes an ezDataBuffer to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().

Note

Standard JSON does not have a suitable type for this. A derived class might turn this into an object or output it via WriteBinaryData().

Implemented in ezStandardJSONWriter.

WriteDouble()

virtual void ezJSONWriter::WriteDouble ( double  value )

pure virtual

Writes a double to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().

Implemented in ezStandardJSONWriter.

WriteFloat()

virtual void ezJSONWriter::WriteFloat ( float  value )

pure virtual

Writes a float to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().

Implemented in ezStandardJSONWriter.

WriteInt32()

virtual void ezJSONWriter::WriteInt32 ( ezInt32  value )

pure virtual

Writes an int32 to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().

Implemented in ezStandardJSONWriter.

WriteInt64()

virtual void ezJSONWriter::WriteInt64 ( ezInt64  value )

pure virtual

Writes an int64 to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().

Implemented in ezStandardJSONWriter.

WriteMat3()

void ezJSONWriter::WriteMat3 ( const ezMat3 &  value )

pure virtual

Writes an ezMat3 to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().

Note

Standard JSON does not have a suitable type for this. A derived class might turn this into an object or output it via WriteBinaryData().

Implemented in ezStandardJSONWriter.

WriteMat4()

void ezJSONWriter::WriteMat4 ( const ezMat4 &  value )

pure virtual

Writes an ezMat4 to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().

Note

Standard JSON does not have a suitable type for this. A derived class might turn this into an object or output it via WriteBinaryData().

Implemented in ezStandardJSONWriter.

WriteNULL()

virtual void ezJSONWriter::WriteNULL ( )

pure virtual

Writes the value 'null' to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().

Implemented in ezStandardJSONWriter.

WriteQuat()

void ezJSONWriter::WriteQuat ( const ezQuat &  value )

pure virtual

Writes an ezQuat to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().

Note

Standard JSON does not have a suitable type for this. A derived class might turn this into an object or output it via WriteBinaryData().

Implemented in ezStandardJSONWriter.

WriteString()

virtual void ezJSONWriter::WriteString ( ezStringView  value )

pure virtual

Writes a string to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().

Implemented in ezStandardJSONWriter.

WriteTime()

virtual void ezJSONWriter::WriteTime ( ezTime  value )

pure virtual

Writes a time value to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().

Implemented in ezStandardJSONWriter.

WriteUInt32()

virtual void ezJSONWriter::WriteUInt32 ( ezUInt32  value )

pure virtual

Writes a uint32 to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().

Implemented in ezStandardJSONWriter.

WriteUInt64()

virtual void ezJSONWriter::WriteUInt64 ( ezUInt64  value )

pure virtual

Writes a uint64 to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().

Implemented in ezStandardJSONWriter.

WriteUuid()

virtual void ezJSONWriter::WriteUuid ( const ezUuid &  value )

pure virtual

Writes an ezUuid to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().

Note

Standard JSON does not have a suitable type for this. A derived class might turn this into an object or output it via WriteBinaryData().

Implemented in ezStandardJSONWriter.

WriteVariant()

void ezJSONWriter::WriteVariant ( const ezVariant &  value )

virtual

The default implementation dispatches all supported types to WriteBool, WriteInt32, etc. and asserts on the more complex types.

A derived class may override this function to implement support for the remaining variant types, if required.

Reimplemented in ezMcpJsonWriter.

WriteVec2()

void ezJSONWriter::WriteVec2 ( const ezVec2 &  value )

pure virtual

Writes an ezVec2 to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().

Note

Standard JSON does not have a suitable type for this. A derived class might turn this into an object or output it via WriteBinaryData().

Implemented in ezStandardJSONWriter.

WriteVec2I32()

void ezJSONWriter::WriteVec2I32 ( const ezVec2I32 &  value )

pure virtual

Writes an ezVec2I32 to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().

Note

Standard JSON does not have a suitable type for this. A derived class might turn this into an object or output it via WriteBinaryData().

Implemented in ezStandardJSONWriter.

WriteVec3()

void ezJSONWriter::WriteVec3 ( const ezVec3 &  value )

pure virtual

Writes an ezVec3 to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().

Note

Standard JSON does not have a suitable type for this. A derived class might turn this into an object or output it via WriteBinaryData().

Implemented in ezStandardJSONWriter.

WriteVec3I32()

void ezJSONWriter::WriteVec3I32 ( const ezVec3I32 &  value )

pure virtual

Writes an ezVec3I32 to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().

Note

Standard JSON does not have a suitable type for this. A derived class might turn this into an object or output it via WriteBinaryData().

Implemented in ezStandardJSONWriter.

WriteVec4()

void ezJSONWriter::WriteVec4 ( const ezVec4 &  value )

pure virtual

Writes an ezVec4 to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().

Note

Standard JSON does not have a suitable type for this. A derived class might turn this into an object or output it via WriteBinaryData().

Implemented in ezStandardJSONWriter.

WriteVec4I32()

void ezJSONWriter::WriteVec4I32 ( const ezVec4I32 &  value )

pure virtual

Writes an ezVec4I32 to the JSON file. Can only be called between BeginVariable() / EndVariable() or BeginArray() / EndArray().

Note

Standard JSON does not have a suitable type for this. A derived class might turn this into an object or output it via WriteBinaryData().

Implemented in ezStandardJSONWriter.

---

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

• /home/runner/work/ezEngine/ezEngine/Code/Engine/Foundation/IO/JSONWriter.h
• /home/runner/work/ezEngine/ezEngine/Code/Engine/Foundation/IO/Implementation/JSONWriter.cpp