casacore
Loading...
Searching...
No Matches
JsonOut.h
Go to the documentation of this file.
1//# JsonOut.h: Fill a file or stream in JSON format
2//# Copyright (C) 2016
3//# Associated Universities, Inc. Washington DC, USA.
4//#
5//# This library is free software; you can redistribute it and/or modify it
6//# under the terms of the GNU Library General Public License as published by
7//# the Free Software Foundation; either version 2 of the License, or (at your
8//# option) any later version.
9//#
10//# This library is distributed in the hope that it will be useful, but WITHOUT
11//# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12//# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13//# License for more details.
14//#
15//# You should have received a copy of the GNU Library General Public License
16//# along with this library; if not, write to the Free Software Foundation,
17//# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18//#
19//# Correspondence concerning AIPS++ should be addressed as follows:
20//# Internet email: casa-feedback@nrao.edu.
21//# Postal address: AIPS++ Project Office
22//# National Radio Astronomy Observatory
23//# 520 Edgemont Road
24//# Charlottesville, VA 22903-2475 USA
25
26#ifndef CASA_JSONOUT_H
27#define CASA_JSONOUT_H
28
29//# Includes
30#include <casacore/casa/aips.h>
31#include <casacore/casa/BasicSL/String.h>
32#include <casacore/casa/Arrays/Array.h>
33#include <casacore/casa/BasicSL/Complex.h>
34#include <casacore/casa/vector.h>
35#include <iostream>
36#include <fstream>
37
38namespace casacore { //# NAMESPACE CASACORE - BEGIN
39
40 //# Forward Declarations
41 class Record;
42 class ValueHolder;
43
44
45 // <summary>
46 // Class to fill a file or stream in JSON format.
47 // </summary>
48
49 // <use visibility=export>
50 // <reviewed reviewer="" date="" tests="tJsonOut">
51 // </reviewed>
52
53 //# <prerequisite>
54 //# </prerequisite>
55
56 // <synopsis>
57 // JsonOut is a class to create a JSON file. JsonParser.h can be used
58 // to interpret a JSON file whereafter JsonKVMap gets out the information.
59 //
60 // Besides the standard JSON types (bool, int, float, string), sequences
61 // and nested structs, JsonOut also supports Casacore data type (D)Complex,
62 // Array, Record, and ValueHolder.
63 // <br>- A complex number is written as a nested struct with fields
64 // "r" and "i".
65 // <br>- An Array is written as a (possibly nested) sequence of values.
66 // <br>- A Record is written as a nested struct; subrecords are supported.
67 // <br>- A ValueHolder is written depending on the data type it contains.
68 // <br>Note that floating point values are written with high accuracy
69 // (7 digits for single precision, 16 digits for double precision).
70 //
71 // Although standard JSON does not support comments, many parsers do support
72 // C-style and C++-style comments. JsonOut has the possibility to define
73 // arbitrary comment delimiters (e.g., / * and * / for C-style).
74 // If no start delimiter is given, possible comments are ignored.
75 //
76 // The output of JsonOut can be any iostream. If a file name is given, an
77 // ofstream will be opened in the constructor and closed in the destructor.
78 // The output is formatted pretty nicely. Nested structs are indented with
79 // 2 spaces. Arrays are written with a single axis per line; continuation
80 // lines are indented properly. String arrays have one value per line.
81 // </synopsis>
82
83 // <example>
84 // The following example is read back by the example in class JsonParser.
85 // <srcblock>
86 // // Create the JSON file.
87 // JsonOut jout(fullName + "/imageconcat.json");
88 // // Start the JSON struct; possible comments will be ignored.
89 // jout.start();
90 // // Write some fields (one line per field).
91 // jout.write ("Version", 1);
92 // jout.write ("DataType", "float");
93 // jout.write ("Axis", latticeConcat_p.axis());
94 // jout.write ("Images", Array<String>(latticeNames));
95 // // End the JSON struct.
96 // jout.end();
97 // </srcblock>
98 // See tJsonOut.cc for more elaborate examples.
99 // </example>
100
101 // <motivation>
102 // JSON is a commonly used interchange format.
103 // </motivation>
104 //
105 //# <todo asof="1996/03/10">
106 //# <li>
107 //# </todo>
108
110 {
111 public:
112 // The default constructor creates the output on stdout.
114
115 // Create the file with the given name using an ofstream object.
116 JsonOut (const String& name);
117
118 // Create the object using the given ostream object.
119 JsonOut (ostream& os);
120
121 // Close the stream. It closes the ofstream object if created.
123
124 // Start a JSON structure by writing a { and setting the indentation.
125 // It checks if not inside a JSON structure.
126 // It is possible to define the comment delimiters
127 // (e.g., / * and * / or // and empty).
128 // If commentStart is empty, possible comments are ignored.
129 void start (const String& commentStart=String(),
130 const String& commentEnd=String(),
131 const String& indent=" ");
132
133 // End a structure by clearing the indentation and writing a }.
134 // It checks if inside a JSON structure.
135 void end();
136
137 // Start a nested structure; i.e., a field with a structured value.
138 // It writes the name and opening brace and increments the indentation.
139 // If supported, the comment is written on a line preceeding the key line.
140 void startNested (const String& name, const String& comment=String());
141
142 // End a nested structure.
143 // It decrements the indentation and writes the closing brace.
144 void endNested();
145
146 // Write one or more lines defining a keyword-value pair, where value
147 // can be of any type including Array, Record, and ValueHolder.
148 // A non-finite floating point number and a null ValueHolder are
149 // written as a null value.
150 // If supported, the comment is written on a line preceeding the
151 // 'key:value' line.
152 template <typename T>
153 void write (const String& name, T value, const String& comment=String());
154
155 // Write a comment on a separate line.
156 // If comments are not supported, an empty line is written.
157 void writeComment (const String& comment);
158
159 // Write a null value.
160 void putNull();
161
162 // Put a scalar value with sufficient accuracy.
163 // A Complex value is written as a nested JSON structure
164 // with fields r and i.
165 // A string is enclosed in quotes and escaped where necessary.
166 // A NaN is written as a null value.
167 // <br>These functions are meant for internal use by the 'write' function.
168 // <group>
169 template <typename T> void put (T value);
170 void put (Bool value);
173 void put (const Complex& value);
174 void put (const DComplex& value);
175 void put (const char* value);
176 void put (const String& value);
177 // </group>
178
179 // Put a line defining an array value. Multi-dim arrays are written as
180 // nested [] lines.
181 // Normally the values of the first dimension are written on a single line,
182 // but for string values a line per value is used.
183 // <br>These functions are meant for internal use by the 'write' function.
184 template <typename T>
185 void putArray (const Array<T>& value, const String& indent,
186 Bool firstLine);
187 void putArray (const Array<String>& value, const String& indent,
188 Bool firstLine);
189 template <typename T>
190 void putArray (const Array<T>& value, const String& indent,
191 Bool firstLine, Bool valueEndl);
192
193 // Escape special characters (including control characters) in a string.
194 static String escapeString (const String& in);
195
196 private:
197 // Copy constructor cannot be used.
198 JsonOut (const JsonOut& other);
199
200 // Assignment cannot be used.
201 JsonOut& operator= (const JsonOut& other);
202
203 // Write the name.
204 void putName (const String& name);
205
206 // General function to write a key and value.
207 // Specializations exist for particular data types.
208 template <typename T>
209 void writeKV (const String& name, T value);
210
211 // Write a key and array value.
212 template <typename T>
213 void writeKV (const String& name, const Array<T>& value);
214
215 // Write a key and valueholder.
216 void writeKV (const String& name, const ValueHolder& vh);
217
218 // Put a Record which is written as a {} structure.
219 // The Record can be nested.
220 void put (const Record&);
221
222 // Get the indentation after a name.
223 // It indents with the length of the name (including quotes and colon)
224 // with a maximum of 20 spaces.
225 String indentValue (const String& indent, const String& name) const;
226
227 //# Data fields.
228 std::ofstream itsFile;
229 std::ostream& itsStream;
235 vector<Bool> itsFirstName;
236 };
237
238
239} //# NAMESPACE CASACORE - END
240
241#ifndef CASACORE_NO_AUTO_TEMPLATES
242#include <casacore/casa/Json/JsonOut.tcc>
243#endif //# CASACORE_NO_AUTO_TEMPLATES
244#endif
void put(const String &value)
JsonOut(ostream &os)
Create the object using the given ostream object.
String itsCommentEnd
Definition JsonOut.h:234
void writeKV(const String &name, const Array< T > &value)
Write a key and array value.
JsonOut(const String &name)
Create the file with the given name using an ofstream object.
void writeKV(const String &name, T value)
General function to write a key and value.
void writeKV(const String &name, const ValueHolder &vh)
Write a key and valueholder.
void writeComment(const String &comment)
Write a comment on a separate line.
std::ofstream itsFile
Definition JsonOut.h:228
~JsonOut()
Close the stream.
void put(const char *value)
void startNested(const String &name, const String &comment=String())
Start a nested structure; i.e., a field with a structured value.
void putArray(const Array< T > &value, const String &indent, Bool firstLine, Bool valueEndl)
void start(const String &commentStart=String(), const String &commentEnd=String(), const String &indent=" ")
Start a JSON structure by writing a { and setting the indentation.
void putName(const String &name)
Write the name.
void put(const Complex &value)
JsonOut & operator=(const JsonOut &other)
Assignment cannot be used.
void put(const Record &)
Put a Record which is written as a {} structure.
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...
void put(Float value)
JsonOut()
The default constructor creates the output on stdout.
void put(const DComplex &value)
JsonOut(const JsonOut &other)
Copy constructor cannot be used.
void put(Bool value)
vector< Bool > itsFirstName
Definition JsonOut.h:235
void putNull()
Write a null value.
void putArray(const Array< String > &value, const String &indent, Bool firstLine)
void put(Double value)
void putArray(const Array< T > &value, const String &indent, Bool firstLine)
Put a line defining an array value.
std::ostream & itsStream
Definition JsonOut.h:229
static String escapeString(const String &in)
Escape special characters (including control characters) in a string.
String indentValue(const String &indent, const String &name) const
Get the indentation after a name.
void put(T value)
Put a scalar value with sufficient accuracy.
String itsCommentStart
Definition JsonOut.h:233
String itsIndentStep
Definition JsonOut.h:231
void end()
End a structure by clearing the indentation and writing a }.
void endNested()
End a nested structure.
String: the storage and methods of handling collections of characters.
Definition String.h:223
this file contains all the compiler specific defines
Definition mainpage.dox:28
float Float
Definition aipstype.h:52
bool Bool
Define the standard types used by Casacore.
Definition aipstype.h:40
LatticeExprNode value(const LatticeExprNode &expr)
This function returns the value of the expression without a mask.
double Double
Definition aipstype.h:53