Stroika Library 3.0d23
 
Loading...
Searching...
No Matches
Variant/JSON/Writer.h
Go to the documentation of this file.
1/*
2 * Copyright(c) Sophist Solutions, Inc. 1990-2026. All rights reserved
3 */
4#ifndef _Stroika_Foundation_DataExchange_Variant_JSON_Writer_h_
5#define _Stroika_Foundation_DataExchange_Variant_JSON_Writer_h_ 1
6
7#include "Stroika/Foundation/StroikaPreComp.h"
8
9#include <optional>
10
11#include "Stroika/Foundation/Characters/FloatConversion.h"
12#include "Stroika/Foundation/Common/Common.h"
16
17/**
18 * \file
19 */
20
21namespace Stroika::Foundation::DataExchange::Variant::JSON {
22
23 /**
24 * \note Our definition of the JSON format comes from:
25 * http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf
26 *
27 * There are several variations. Please also note that http://jsonlint.com/ disallows
28 * json top level values other than array or object, but that doesn't appear to follow
29 * the standard as specified in ECMA.
30 *
31 * This implementation allows any top-level value (as ECMA-404 calls for).
32 *
33 * \note Though ANY VariantValue can be mapped to a JSON object, the return trip
34 * will NOT necessarily be the same as the start object, because VariantValue supports more builtin types
35 * than JSON (e.g. Date). If you map a date to JSON, and back, you will get a String.
36 *
37 * \note Writing NAN/INF values (if fAllowNANInf set - default) - transforms those values to strings, but on roundtrip
38 * automatically transforms them back to the correct IEEE floating point type (if you coerce the VariantValue
39 * return from parsing to a floating point type).
40 *
41 * \par Example Usage
42 * \code
43 * VariantValue v{3};
44 * JSON::Writer{}.Write (v, IO::FileSystem::FileOutputStream ("fred.json"));
45 * \endcode
46 *
47 * \par Example Usage
48 * \code
49 * Mapping<String, VariantValue> m;
50 * m.Add ("max-files", 10);
51 * m.Add ("max-processes", 3);
52 * stringstream stringBuf;
53 * JSON::Writer{}.Write (VariantValue{m}, Streams::iostream::OutputStreamFromStdOStream (stringBuf));
54 * \endcode
55 *
56 * \par Example Usage
57 * \code
58 * VariantValue v{3}; // or any other variant value - like a Mapping<String,VariantValue>
59 * String x = JSON::Writer {}.WriteAsString (v);
60 * \endcode
61 *
62 */
63 class Writer : public Variant::Writer {
64 private:
66
67 private:
68 class Rep_;
69
70 public:
71 DISABLE_COMPILER_GCC_WARNING_START ("GCC diagnostic ignored \"-Wdeprecated-declarations\"");
72 DISABLE_COMPILER_CLANG_WARNING_START ("clang diagnostic ignored \"-Wdeprecated-declarations\"");
73 /**
74 */
75 struct Options {
76 /**
77 * This defaults to true.
78 *
79 * If false, more compact, and no leading/trailing spaces.
80 */
81 optional<bool> fPrettyPrint;
82
83 [[deprecated ("Since Stroika v3.0d23 use fPrettyPrint")]] optional<bool> fJSONPrettyPrint; //deprecated name
84
85 /**
86 * This defaults to off, since its costly, and rarely needed. Principally used for regression tests
87 * where we want to compare we get the same results as last time.
88 */
89 optional<bool> fCanonicalize;
90
91 /**
92 */
93 optional<Characters::FloatConversion::ToStringOptions> fFloatOptions;
94
95 /**
96 * This defaults to 4. If fPrettyPrint evaluates false, then this is ignored.
97 */
98 optional<unsigned int> fSpacesPerIndent;
99
100 /**
101 * This defaults to true.
102 *
103 * \note Note - NAN values (if floating point) - are also illegal, and generate a 'Require' failure.
104 * From http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf:
105 * Numeric values that cannot be represented as sequences of digits (such as Infinity and NaN) are not
106 * permitted.
107 *
108 * And yet, there is a natural way to represent the numbers.
109 * We DEFAULT to allowing this. If not allowed, then presence of NANs and INF in input, is treated as an assertion error.
110 *
111 * \note - because these would be ILLEGAL JSON, - they are written as strings. So when written, they REMAIN LEGAL JSON. And when you
112 * re-read the JSON, it will be read as a string. But when you coerce that string to a floating point type, the 'INF' or whatever,
113 * will be coerced to the proper IEEE floating point type.
114 */
115 optional<bool> fAllowNANInf;
116
117 /**
118 * defaults to Characters::kEOL if not specified
119 */
120 optional<String> fLineTermination;
121 };
122 DISABLE_COMPILER_GCC_WARNING_END ("GCC diagnostic ignored \"-Wdeprecated-declarations\"");
123 DISABLE_COMPILER_CLANG_WARNING_END ("clang diagnostic ignored \"-Wdeprecated-declarations\"");
124
125 public:
126 Writer (const Options& options = {});
127
128 private:
129 nonvirtual shared_ptr<Rep_> GetRep_ () const;
130 };
131
132}
133
134/*
135 ********************************************************************************
136 ***************************** Implementation Details ***************************
137 ********************************************************************************
138 */
139
140#endif /*_Stroika_Foundation_DataExchange_Variant_JSON_Writer_h_*/
abstract class specifying interface for writers VariantValue objects to serialized formats like JSON,...