Loading...
Searching...
No Matches
JsonOut.h
Go to the documentation of this file.
//# JsonOut.h: Fill a file or stream in JSON format
//# Copyright (C) 2016
//# Associated Universities, Inc. Washington DC, USA.
//#
//# This library is free software; you can redistribute it and/or modify it
//# under the terms of the GNU Library General Public License as published by
//# the Free Software Foundation; either version 2 of the License, or (at your
//# option) any later version.
//#
//# This library is distributed in the hope that it will be useful, but WITHOUT
//# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
//# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
//# License for more details.
//#
//# You should have received a copy of the GNU Library General Public License
//# along with this library; if not, write to the Free Software Foundation,
//# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
//#
//# Correspondence concerning AIPS++ should be addressed as follows:
//# Internet email: casa-feedback@nrao.edu.
//# Postal address: AIPS++ Project Office
//# National Radio Astronomy Observatory
//# 520 Edgemont Road
//# Charlottesville, VA 22903-2475 USA
#ifndef CASA_JSONOUT_H
#define CASA_JSONOUT_H
//# Includes
#include <casacore/casa/aips.h>
#include <casacore/casa/BasicSL/String.h>
#include <casacore/casa/Arrays/Array.h>
#include <casacore/casa/BasicSL/Complex.h>
#include <casacore/casa/vector.h>
#include <iostream>
#include <fstream>
namespace casacore { //# NAMESPACE CASACORE - BEGIN
//# Forward Declarations
class Record;
class ValueHolder;
// <summary>
// Class to fill a file or stream in JSON format.
// </summary>
// <use visibility=export>
// <reviewed reviewer="" date="" tests="tJsonOut">
// </reviewed>
//# <prerequisite>
//# </prerequisite>
// <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.
// <br>- A complex number is written as a nested struct with fields
// "r" and "i".
// <br>- An Array is written as a (possibly nested) sequence of values.
// <br>- A Record is written as a nested struct; subrecords are supported.
// <br>- A ValueHolder is written depending on the data type it contains.
// <br>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.
// </synopsis>
// <example>
// The following example is read back by the example in class JsonParser.
// <srcblock>
// // 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();
// </srcblock>
// See tJsonOut.cc for more elaborate examples.
// </example>
// <motivation>
// JSON is a commonly used interchange format.
// </motivation>
//
//# <todo asof="1996/03/10">
//# <li>
//# </todo>
class JsonOut
{
public:
// The default constructor creates the output on stdout.
JsonOut();
// Create the file with the given name using an ofstream object.
JsonOut (const String& name);
// Create the object using the given ostream object.
JsonOut (ostream& os);
// Close the stream. It closes the ofstream object if created.
~JsonOut();
// 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 start (const String& commentStart=String(),
const String& commentEnd=String(),
const String& indent=" ");
// End a structure by clearing the indentation and writing a }.
// It checks if inside a JSON structure.
void end();
// 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.
void startNested (const String& name, const String& comment=String());
// End a nested structure.
// It decrements the indentation and writes the closing brace.
void endNested();
// 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.
template <typename T>
void write (const String& name, T value, const String& comment=String());
// Write a comment on a separate line.
// If comments are not supported, an empty line is written.
void writeComment (const String& comment);
// Write a null value.
void putNull();
// 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.
// <br>These functions are meant for internal use by the 'write' function.
// <group>
template <typename T> void put (T value);
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);
// </group>
// 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.
// <br>These functions are meant for internal use by the 'write' function.
template <typename T>
void putArray (const Array<T>& value, const String& indent,
Bool firstLine);
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);
// Escape special characters (including control characters) in a string.
static String escapeString (const String& in);
private:
// Copy constructor cannot be used.
JsonOut (const JsonOut& other);
// Assignment cannot be used.
JsonOut& operator= (const JsonOut& other);
// Write the name.
void putName (const String& name);
// General function to write a key and value.
// Specializations exist for particular data types.
template <typename T>
void writeKV (const String& name, T value);
// Write a key and array value.
template <typename T>
void writeKV (const String& name, const Array<T>& value);
// Write a key and valueholder.
void writeKV (const String& name, const ValueHolder& vh);
// Put a Record which is written as a {} structure.
// The Record can be nested.
void put (const Record&);
// Get the indentation after a name.
// It indents with the length of the name (including quotes and colon)
// with a maximum of 20 spaces.
String indentValue (const String& indent, const String& name) const;
//# Data fields.
std::ofstream itsFile;
std::ostream& itsStream;
String itsIndent;
String itsIndentStep;
int itsLevel;
String itsCommentStart;
String itsCommentEnd;
vector<Bool> itsFirstName;
};
} //# NAMESPACE CASACORE - END
#ifndef CASACORE_NO_AUTO_TEMPLATES
#include <casacore/casa/Json/JsonOut.tcc>
#endif //# CASACORE_NO_AUTO_TEMPLATES
#endif
casacore::Array
Definition Array.h:155
casacore::JsonOut::put
void put(const String &value)
casacore::JsonOut::JsonOut
JsonOut(ostream &os)
Create the object using the given ostream object.
casacore::JsonOut::itsCommentEnd
String itsCommentEnd
Definition JsonOut.h:234
casacore::JsonOut::writeKV
void writeKV(const String &name, const Array< T > &value)
Write a key and array value.
casacore::JsonOut::JsonOut
JsonOut(const String &name)
Create the file with the given name using an ofstream object.
casacore::JsonOut::writeKV
void writeKV(const String &name, T value)
General function to write a key and value.
casacore::JsonOut::writeKV
void writeKV(const String &name, const ValueHolder &vh)
Write a key and valueholder.
casacore::JsonOut::writeComment
void writeComment(const String &comment)
Write a comment on a separate line.
casacore::JsonOut::itsFile
std::ofstream itsFile
Definition JsonOut.h:228
casacore::JsonOut::~JsonOut
~JsonOut()
Close the stream.
casacore::JsonOut::put
void put(const char *value)
casacore::JsonOut::startNested
void startNested(const String &name, const String &comment=String())
Start a nested structure; i.e., a field with a structured value.
casacore::JsonOut::itsLevel
int itsLevel
Definition JsonOut.h:232
casacore::JsonOut::putArray
void putArray(const Array< T > &value, const String &indent, Bool firstLine, Bool valueEndl)
casacore::JsonOut::start
void start(const String &commentStart=String(), const String &commentEnd=String(), const String &indent=" ")
Start a JSON structure by writing a { and setting the indentation.
casacore::JsonOut::putName
void putName(const String &name)
Write the name.
casacore::JsonOut::put
void put(const Complex &value)
casacore::JsonOut::operator=
JsonOut & operator=(const JsonOut &other)
Assignment cannot be used.
casacore::JsonOut::put
void put(const Record &)
Put a Record which is written as a {} structure.
casacore::JsonOut::write
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...
casacore::JsonOut::put
void put(Float value)
casacore::JsonOut::JsonOut
JsonOut()
The default constructor creates the output on stdout.
casacore::JsonOut::put
void put(const DComplex &value)
casacore::JsonOut::JsonOut
JsonOut(const JsonOut &other)
Copy constructor cannot be used.
casacore::JsonOut::put
void put(Bool value)
casacore::JsonOut::itsFirstName
vector< Bool > itsFirstName
Definition JsonOut.h:235
casacore::JsonOut::itsIndent
String itsIndent
Definition JsonOut.h:230
casacore::JsonOut::putNull
void putNull()
Write a null value.
casacore::JsonOut::putArray
void putArray(const Array< String > &value, const String &indent, Bool firstLine)
casacore::JsonOut::put
void put(Double value)
casacore::JsonOut::putArray
void putArray(const Array< T > &value, const String &indent, Bool firstLine)
Put a line defining an array value.
casacore::JsonOut::itsStream
std::ostream & itsStream
Definition JsonOut.h:229
casacore::JsonOut::escapeString
static String escapeString(const String &in)
Escape special characters (including control characters) in a string.
casacore::JsonOut::indentValue
String indentValue(const String &indent, const String &name) const
Get the indentation after a name.
casacore::JsonOut::put
void put(T value)
Put a scalar value with sufficient accuracy.
casacore::JsonOut::itsCommentStart
String itsCommentStart
Definition JsonOut.h:233
casacore::JsonOut::itsIndentStep
String itsIndentStep
Definition JsonOut.h:231
casacore::JsonOut::end
void end()
End a structure by clearing the indentation and writing a }.
casacore::JsonOut::endNested
void endNested()
End a nested structure.
casacore::String
String: the storage and methods of handling collections of characters.
Definition String.h:223
casacore::ValueHolder
Definition ValueHolder.h:66
casacore::Record
Record()
casacore
this file contains all the compiler specific defines
Definition mainpage.dox:28
casacore::Float
float Float
Definition aipstype.h:52
casacore::name
String name() const
Return the name of the field.
Definition RecordField.h:163
casacore::comment
const String & comment(const RecordFieldId &) const override
Get the comment for this field.
casacore::Bool
bool Bool
Define the standard types used by Casacore.
Definition aipstype.h:40
casacore::value
NewDelAllocator< T > NewDelAllocator< T >::value
Definition Allocator.h:368
casacore::Double
double Double
Definition aipstype.h:53