casa  5.7.0-16
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Public Member Functions | Static Public Member Functions | Private Member Functions | Private Attributes | List of all members
casacore::JsonOut Class Reference

Class to fill a file or stream in JSON format. More...

#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...
 
JsonOutoperator= (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< BoolitsFirstName
 

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 109 of file JsonOut.h.

Constructor & Destructor Documentation

casacore::JsonOut::JsonOut ( )

The default constructor creates the output on stdout.

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

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

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

Create the object using the given ostream object.

casacore::JsonOut::~JsonOut ( )

Close the stream.

It closes the ofstream object if created.

casacore::JsonOut::JsonOut ( const JsonOut other)
private

Copy constructor cannot be used.

Member Function Documentation

void casacore::JsonOut::end ( )

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

It checks if inside a JSON structure.

void casacore::JsonOut::endNested ( )

End a nested structure.

It decrements the indentation and writes the closing brace.

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

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

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.

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

Assignment cannot be used.

template<typename T >
void casacore::JsonOut::put ( 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.

void casacore::JsonOut::put ( Bool  value)
void casacore::JsonOut::put ( Float  value)
void casacore::JsonOut::put ( Double  value)
void casacore::JsonOut::put ( const Complex &  value)
void casacore::JsonOut::put ( const DComplex &  value)
void casacore::JsonOut::put ( const char *  value)
void casacore::JsonOut::put ( const String value)
void casacore::JsonOut::put ( const Record )
private

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

The Record can be nested.

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.

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

Write the name.

void casacore::JsonOut::putNull ( )

Write a null value.

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.

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.

template<typename T >
void casacore::JsonOut::write ( const String name,
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.

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

Write a comment on a separate line.

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

template<typename T >
void casacore::JsonOut::writeKV ( const String name,
value 
)
private

General function to write a key and value.

Specializations exist for particular data types.

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

Write a key and array value.

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

Write a key and valueholder.

Member Data Documentation

String casacore::JsonOut::itsCommentEnd
private

Definition at line 234 of file JsonOut.h.

String casacore::JsonOut::itsCommentStart
private

Definition at line 233 of file JsonOut.h.

std::ofstream casacore::JsonOut::itsFile
private

Definition at line 228 of file JsonOut.h.

vector<Bool> casacore::JsonOut::itsFirstName
private

Definition at line 235 of file JsonOut.h.

String casacore::JsonOut::itsIndent
private

Definition at line 230 of file JsonOut.h.

String casacore::JsonOut::itsIndentStep
private

Definition at line 231 of file JsonOut.h.

int casacore::JsonOut::itsLevel
private

Definition at line 232 of file JsonOut.h.

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

Definition at line 229 of file JsonOut.h.


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