#include <JsonOut.h>

Public Member Functions
	JsonOut ()
	The default constructor creates the output on stdout. More...

	JsonOut (const String &name)
	Create the file with the given name using an ofstream object. More...

	JsonOut (ostream &os)
	Create the object using the given ostream object. More...

	~JsonOut ()
	Close the stream. More...

void	start (const String &commentStart=String(), const String &commentEnd=String(), const String &indent=" ")
	Start a JSON structure by writing a { and setting the indentation. More...

void	end ()
	End a structure by clearing the indentation and writing a }. More...

void	startNested (const String &name, const String &comment=String())
	Start a nested structure; i.e., a field with a structured value. More...

void	endNested ()
	End a nested structure. More...

template<typename T >
void	write (const String &name, T value, const String &comment=String())
	Write one or more lines defining a keyword-value pair, where value can be of any type including Array, Record, and ValueHolder. More...

void	writeComment (const String &comment)
	Write a comment on a separate line. More...

void	putNull ()
	Write a null value. More...

template<typename T >
void	put (T value)
	Put a scalar value with sufficient accuracy. More...

void	put (Bool value)

void	put (Float value)

void	put (Double value)

void	put (const Complex &value)

void	put (const DComplex &value)

void	put (const char *value)

void	put (const String &value)

template<typename T >
void	putArray (const Array< T > &value, const String &indent, Bool firstLine)
	Put a line defining an array value. More...

void	putArray (const Array< String > &value, const String &indent, Bool firstLine)

template<typename T >
void	putArray (const Array< T > &value, const String &indent, Bool firstLine, Bool valueEndl)

Static Public Member Functions
static String	escapeString (const String &in)
	Escape special characters (including control characters) in a string. More...

Private Member Functions
	JsonOut (const JsonOut &other)
	Copy constructor cannot be used. More...

JsonOut &	operator= (const JsonOut &other)
	Assignment cannot be used. More...

void	putName (const String &name)
	Write the name. More...

template<typename T >
void	writeKV (const String &name, T value)
	General function to write a key and value. More...

template<typename T >
void	writeKV (const String &name, const Array< T > &value)
	Write a key and array value. More...

void	writeKV (const String &name, const ValueHolder &vh)
	Write a key and valueholder. More...

void	put (const Record &)
	Put a Record which is written as a {} structure. More...

String	indentValue (const String &indent, const String &name) const
	Get the indentation after a name. More...

Private Attributes
std::ofstream	itsFile

std::ostream &	itsStream

String	itsIndent

String	itsIndentStep

int	itsLevel

String	itsCommentStart

String	itsCommentEnd

vector< Bool >	itsFirstName

Detailed Description

Class to fill a file or stream in JSON format.

Intended use:

Public interface

Review Status

Test programs:: tJsonOut

Synopsis

JsonOut is a class to create a JSON file. JsonParser.h can be used to interpret a JSON file whereafter JsonKVMap gets out the information.

Besides the standard JSON types (bool, int, float, string), sequences and nested structs, JsonOut also supports Casacore data type (D)Complex, Array, Record, and ValueHolder.
- A complex number is written as a nested struct with fields "r" and "i".
- An Array is written as a (possibly nested) sequence of values.
- A Record is written as a nested struct; subrecords are supported.
- A ValueHolder is written depending on the data type it contains.
Note that floating point values are written with high accuracy (7 digits for single precision, 16 digits for double precision).

Although standard JSON does not support comments, many parsers do support C-style and C++-style comments. JsonOut has the possibility to define arbitrary comment delimiters (e.g., / * and * / for C-style). If no start delimiter is given, possible comments are ignored.

The output of JsonOut can be any iostream. If a file name is given, an ofstream will be opened in the constructor and closed in the destructor. The output is formatted pretty nicely. Nested structs are indented with 2 spaces. Arrays are written with a single axis per line; continuation lines are indented properly. String arrays have one value per line.

Example

The following example is read back by the example in class JsonParser.

// Create the JSON file.
JsonOut jout(fullName + "/imageconcat.json");
// Start the JSON struct; possible comments will be ignored.
jout.start();
// Write some fields (one line per field).
jout.write ("Version", 1);
jout.write ("DataType", "float");
jout.write ("Axis", latticeConcat_p.axis());
jout.write ("Images", Array<String>(latticeNames));
// End the JSON struct.
jout.end();

See tJsonOut.cc for more elaborate examples.

Motivation

JSON is a commonly used interchange format.

Definition at line 111 of file JsonOut.h.

Constructor & Destructor Documentation

◆ JsonOut() [1/4]

casacore::JsonOut::JsonOut ( )

The default constructor creates the output on stdout.

◆ JsonOut() [2/4]

casacore::JsonOut::JsonOut ( const String & name )

Create the file with the given name using an ofstream object.

◆ JsonOut() [3/4]

casacore::JsonOut::JsonOut ( ostream & os )

Create the object using the given ostream object.

◆ ~JsonOut()

casacore::JsonOut::~JsonOut ( )

Close the stream.

It closes the ofstream object if created.

◆ JsonOut() [4/4]

casacore::JsonOut::JsonOut ( const JsonOut & other )

private

Copy constructor cannot be used.

Member Function Documentation

◆ end()

void casacore::JsonOut::end ( )

End a structure by clearing the indentation and writing a }.

It checks if inside a JSON structure.

◆ endNested()

void casacore::JsonOut::endNested ( )

End a nested structure.

It decrements the indentation and writes the closing brace.

◆ escapeString()

static String casacore::JsonOut::escapeString ( const String & in )

static

Escape special characters (including control characters) in a string.

◆ indentValue()

String casacore::JsonOut::indentValue	(	const String &	indent,
		const String &	name
	)		const

private

Get the indentation after a name.

It indents with the length of the name (including quotes and colon) with a maximum of 20 spaces.

◆ operator=()

JsonOut& casacore::JsonOut::operator= ( const JsonOut & other )

private

Assignment cannot be used.

◆ put() [1/9]

void casacore::JsonOut::put ( Bool value )

◆ put() [2/9]

void casacore::JsonOut::put ( const char * value )

◆ put() [3/9]

void casacore::JsonOut::put ( const Complex & value )

◆ put() [4/9]

void casacore::JsonOut::put ( const DComplex & value )

◆ put() [5/9]

void casacore::JsonOut::put ( const Record & )

private

Put a Record which is written as a {} structure.

The Record can be nested.

◆ put() [6/9]

void casacore::JsonOut::put ( const String & value )

◆ put() [7/9]

void casacore::JsonOut::put ( Double value )

◆ put() [8/9]

void casacore::JsonOut::put ( Float value )

◆ put() [9/9]

template<typename T >

void casacore::JsonOut::put ( T value )

Put a scalar value with sufficient accuracy.

A Complex value is written as a nested JSON structure with fields r and i. A string is enclosed in quotes and escaped where necessary. A NaN is written as a null value.
These functions are meant for internal use by the 'write' function.

◆ putArray() [1/3]

void casacore::JsonOut::putArray	(	const Array< String > &	value,
		const String &	indent,
		Bool	firstLine
	)

◆ putArray() [2/3]

template<typename T >

void casacore::JsonOut::putArray	(	const Array< T > &	value,
		const String &	indent,
		Bool	firstLine
	)

Put a line defining an array value.

Multi-dim arrays are written as nested [] lines. Normally the values of the first dimension are written on a single line, but for string values a line per value is used.
These functions are meant for internal use by the 'write' function.

◆ putArray() [3/3]

template<typename T >

void casacore::JsonOut::putArray	(	const Array< T > &	value,
		const String &	indent,
		Bool	firstLine,
		Bool	valueEndl
	)

◆ putName()

void casacore::JsonOut::putName ( const String & name )

private

Write the name.

◆ putNull()

void casacore::JsonOut::putNull ( )

Write a null value.

◆ start()

void casacore::JsonOut::start	(	const String &	commentStart = `String()`,
		const String &	commentEnd = `String()`,
		const String &	indent = `" "`
	)

Start a JSON structure by writing a { and setting the indentation.

It checks if not inside a JSON structure. It is possible to define the comment delimiters (e.g., / * and * / or // and empty). If commentStart is empty, possible comments are ignored.

◆ startNested()

void casacore::JsonOut::startNested	(	const String &	name,
		const String &	comment = `String()`
	)

Start a nested structure; i.e., a field with a structured value.

It writes the name and opening brace and increments the indentation. If supported, the comment is written on a line preceeding the key line.

◆ write()

template<typename T >

void casacore::JsonOut::write	(	const String &	name,
		T	value,
		const String &	comment = `String()`
	)

Write one or more lines defining a keyword-value pair, where value can be of any type including Array, Record, and ValueHolder.

A non-finite floating point number and a null ValueHolder are written as a null value. If supported, the comment is written on a line preceeding the 'key:value' line.

◆ writeComment()

void casacore::JsonOut::writeComment ( const String & comment )

Write a comment on a separate line.

If comments are not supported, an empty line is written.

◆ writeKV() [1/3]

template<typename T >

void casacore::JsonOut::writeKV	(	const String &	name,
		const Array< T > &	value
	)

private

Write a key and array value.

◆ writeKV() [2/3]

void casacore::JsonOut::writeKV	(	const String &	name,
		const ValueHolder &	vh
	)

private

Write a key and valueholder.

◆ writeKV() [3/3]

template<typename T >

void casacore::JsonOut::writeKV	(	const String &	name,
		T	value
	)

private

General function to write a key and value.

Specializations exist for particular data types.

Member Data Documentation

◆ itsCommentEnd

String casacore::JsonOut::itsCommentEnd

private

Definition at line 236 of file JsonOut.h.

◆ itsCommentStart

String casacore::JsonOut::itsCommentStart

private

Definition at line 235 of file JsonOut.h.

◆ itsFile

std::ofstream casacore::JsonOut::itsFile

private

Definition at line 230 of file JsonOut.h.

◆ itsFirstName

vector<Bool> casacore::JsonOut::itsFirstName

private

Definition at line 237 of file JsonOut.h.

◆ itsIndent

String casacore::JsonOut::itsIndent

private

Definition at line 232 of file JsonOut.h.

◆ itsIndentStep

String casacore::JsonOut::itsIndentStep

private

Definition at line 233 of file JsonOut.h.

◆ itsLevel

int casacore::JsonOut::itsLevel

private

Definition at line 234 of file JsonOut.h.

◆ itsStream

std::ostream& casacore::JsonOut::itsStream

private

Definition at line 231 of file JsonOut.h.

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

casa/Json/JsonOut.h

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Intended use:

Review Status

Synopsis

Example

Motivation

Constructor & Destructor Documentation

◆ JsonOut() [1/4]

◆ JsonOut() [2/4]

◆ JsonOut() [3/4]

◆ ~JsonOut()

◆ JsonOut() [4/4]

Member Function Documentation

◆ end()

◆ endNested()

◆ escapeString()

◆ indentValue()

◆ operator=()

◆ put() [1/9]

◆ put() [2/9]

◆ put() [3/9]

◆ put() [4/9]

◆ put() [5/9]

◆ put() [6/9]

◆ put() [7/9]

◆ put() [8/9]

◆ put() [9/9]

◆ putArray() [1/3]

◆ putArray() [2/3]

◆ putArray() [3/3]

◆ putName()

◆ putNull()

◆ start()

◆ startNested()

◆ write()

◆ writeComment()

◆ writeKV() [1/3]

◆ writeKV() [2/3]

◆ writeKV() [3/3]

Member Data Documentation

◆ itsCommentEnd

◆ itsCommentStart

◆ itsFile

◆ itsFirstName

◆ itsIndent

◆ itsIndentStep

◆ itsLevel

◆ itsStream