HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
UT_JSONHandle.h
Go to the documentation of this file.
1 /*
2  * PROPRIETARY INFORMATION. This software is proprietary to
3  * Side Effects Software Inc., and is not to be reproduced,
4  * transmitted, or disclosed in any way without written permission.
5  *
6  * NAME: UT_JSONHandle.h ( UT Library, C++)
7  *
8  * COMMENTS:
9  */
10 
11 #ifndef __UT_JSONHandle__
12 #define __UT_JSONHandle__
13 
14 #include "UT_API.h"
15 #include <SYS/SYS_Types.h>
16 #include <SYS/SYS_String.h>
17 #include <iosfwd>
18 
19 class UT_JSONParser;
20 class UT_IStream;
21 class UT_WorkBuffer;
22 class UT_StringHolder;
23 
24 /// @brief UT_JSONHandle processes events from a UT_JSONParser parser
25 ///
26 /// The UT_JSONParser is passed a UT_JSONHandle to interpret the JSON tokens.
27 /// As each entity is encountered, an event callback is invoked on the handle
28 /// to process the token.
29 ///
30 /// It's possible to recurse into the parser from within a callback with a
31 /// different handler and possibly even a different input stream by calling
32 /// UT_JSONParser::parseObject().
33 ///
34 /// @see UT_JSONParser, UT_JSONHandleError, UT_JSONHandleNull, UT_JSONIStream
35 
37 public:
39  virtual ~UT_JSONHandle() {}
40 
41  /// Convenience method to parse a single object
42  bool parseObject(UT_JSONParser &p, UT_IStream *is=0);
43 
44  /// The Null Handle acts as a pass through when parsing a JSON file. It
45  /// can be used for simple syntax checking:
46  /// @code
47  /// UT_JSONHandle *h = UT_JSONHandle::getNullHandle();
48  /// UT_JSONParser p;
49  /// success = p.parseObject(*h);
50  /// UT_JSONHandle::releaseNullHandle(h);
51  /// @endcode
52  static UT_JSONHandle *getNullHandle();
53  /// Instead of deleting the null handle, please call releaseNullHandle()
54  static void releaseNullHandle(UT_JSONHandle *h);
55 
56  /// Event method to process a null token
57  virtual bool jsonNull(UT_JSONParser &p) = 0;
58  /// Event method to process a bool (true or false tokens)
59  virtual bool jsonBool(UT_JSONParser &p, bool value) = 0;
60 
61  /// Event method to process an integer
62  virtual bool jsonInt(UT_JSONParser &p, int64 value) = 0;
63  /// Event method to process a real/float
64  virtual bool jsonReal(UT_JSONParser &p, fpreal64 value) = 0;
65 
66  /// Event method to process a string value
67  virtual bool jsonString(UT_JSONParser &p, const char *value,
68  int64 len) = 0;
69  /// The string event taking a UT_StringHolder calls the jsonString() method
70  /// by default. However, if you can process a UT_StringHolder instead, you
71  /// can get a direct reference to the UT_StringHolder.
72  virtual bool jsonStringHolder(UT_JSONParser &p,
73  const UT_StringHolder &s);
74  /// Event method to process the key of a map/object is read
75  virtual bool jsonKey(UT_JSONParser &p, const char *v, int64 len)=0;
76  virtual bool jsonKeyHolder(UT_JSONParser &p,
77  const UT_StringHolder &s);
78 
79  /// Event method invoked at the start of a map/object
80  virtual bool jsonBeginMap(UT_JSONParser &p) = 0;
81  /// Event method invoked at the end of a map/object
82  virtual bool jsonEndMap(UT_JSONParser &p) = 0;
83  /// Event method invoked at the beginning of an array object
84  virtual bool jsonBeginArray(UT_JSONParser &p) = 0;
85  /// Event method invoked at the end of an array object
86  virtual bool jsonEndArray(UT_JSONParser &p) = 0;
87 
88  /// Event method to handle for uniform array of bool (encoded as bit
89  /// fields)
90  virtual bool uaBool(UT_JSONParser &p, int64 length);
91  /// Event method to handle uniform array of int8 data
92  virtual bool uaInt8(UT_JSONParser &p, int64 length);
93  /// Event method to handle uniform array of int16 data
94  virtual bool uaInt16(UT_JSONParser &p, int64 length);
95  /// Event method to handle uniform array of int32 data
96  virtual bool uaInt32(UT_JSONParser &p, int64 length);
97  /// Event method to handle uniform array of int64 data
98  virtual bool uaInt64(UT_JSONParser &p, int64 length);
99  /// Event method to handle uniform array of real16 data
100  virtual bool uaReal16(UT_JSONParser &p, int64 length);
101  /// Event method to handle uniform array of real32 data
102  virtual bool uaReal32(UT_JSONParser &p, int64 length);
103  /// Event method to handle uniform array of real64 data
104  virtual bool uaReal64(UT_JSONParser &p, int64 length);
105  /// Event method to handle uniform array of unsigned uint8 data
106  virtual bool uaUInt8(UT_JSONParser &p, int64 length);
107  /// Event method to handle uniform array of unsigned uint16 data
108  virtual bool uaUInt16(UT_JSONParser &p, int64 length);
109  /// Event method to handle uniform array of string data (use uaReadString)
110  virtual bool uaString(UT_JSONParser &p, int64 length);
111  /// Event method to handle uniform array of string token data (use
112  /// uaReadStringToken)
113  virtual bool uaStringToken(UT_JSONParser &p, int64 length);
114 
115  /// This method is called by addError to create the prefix for error
116  /// messages. By default, the method looks something like:
117  /// @code
118  /// msg.sprintf("JSON ERROR[%ld]:", (long)p.getStreamPosition());
119  /// @endcode
120  virtual void errorPrefix(UT_JSONParser &p, UT_WorkBuffer &msg);
121 
122 protected:
123  /// Convenience method to test key values
124  bool isKey(const char *s1, const char *s2) const
125  { return !SYSstrcasecmp(s1, s2); }
126  /// Convenience method to add an error about a bad key name
127  /// addError("Unexpected key token '%s'" % key);
128  /// This also skips the next object.
129  void skipBadKey(UT_JSONParser &p, const char *key);
130  /// Convenience method to add a fatal error about a bad key name
131  /// addError("Unexpected key token '%s'" % key);
132  void fatalBadKey(UT_JSONParser &p, const char *key);
133 };
134 
135 /// @brief This class generates errors on any JSON events.
136 ///
137 /// The UT_JSONHandleError class will throw errors on any JSON events. It's
138 /// useful as a base class for an event handler which only expects certain
139 /// events. For example, if you only expect the keyword argument, you might
140 /// have a class like: @code
141 /// class MyHandle : public UT_JSONHandleError {
142 /// virtual bool jsonKey(UT_JSONParser &p, const char *v, int64 len);
143 /// virtual const char *className() { return "MyClass" }
144 /// }
145 /// @endcode
146 /// The base class would handle trapping errors on anything other than a
147 /// map key.
148 ///
149 /// @note Uniform arrays are handled by the UT_JSONHandle base class
150 ///
151 /// @see UT_JSONHandle, UT_JSONHandleNull
153 public:
154  /// @param fatal @n
155  /// If fatal is true then errors will cause parsing to terminate.
156  /// Otherwise, parsing will continue and errors will cascade.
157  UT_JSONHandleError(bool fatal=true) : myFatal(fatal) {}
158  virtual ~UT_JSONHandleError() {}
159 
160  /// getClassName() should return a meaningful label. The errors generated
161  /// will be:
162  /// Error parsing %s: Unexpected "type" JSON object
163  /// The default is an empty string.
164  virtual const char *getClassName() const;
165 
166  virtual bool jsonNull(UT_JSONParser &p);
167  virtual bool jsonBool(UT_JSONParser &p, bool value);
168  virtual bool jsonInt(UT_JSONParser &p, int64 value);
169  virtual bool jsonReal(UT_JSONParser &p, fpreal64 value);
170  virtual bool jsonString(UT_JSONParser &p, const char *v, int64 len);
171  virtual bool jsonKey(UT_JSONParser &p, const char *v, int64 len);
172  virtual bool jsonBeginMap(UT_JSONParser &p);
173  virtual bool jsonEndMap(UT_JSONParser &p);
174  virtual bool jsonBeginArray(UT_JSONParser &p);
175  virtual bool jsonEndArray(UT_JSONParser &p);
176 protected:
177  /// Add a type error for the given name
178  virtual bool typeError(UT_JSONParser &p, const char *name);
179  /// Check whether errors should be fatal (or just warnings)
180  bool getFatal() const { return myFatal; }
181  /// Set whether errors should be fatal (or just warnings)
182  void setFatal(bool f) { myFatal = f; }
183 
184 private:
185  /// Whether errors terminate parsing.
186  bool myFatal;
187 };
188 
189 /// @brief This class skips over any JSON events.
190 ///
191 /// The UT_JSONHandleNull will simply skip over any JSON events.
192 /// useful as a base class for an event handler which only expects certain
193 /// events. For example, if you only expect the keyword argument, you might
194 /// have a class like: @code
195 /// class MyHandle : public UT_JSONHandleNull {
196 /// virtual bool jsonInt(UT_JSONParser &p, int64 len);
197 /// virtual bool jsonReal(UT_JSONParser &p, fpreal64 len);
198 /// virtual const char *className() { return "MyClass" }
199 /// }
200 /// @endcode
201 /// The base class would skip over anything other than an integer or real.
202 ///
203 /// @note Uniform arrays are handled by the UT_JSONHandle base class
204 ///
205 /// @see UT_JSONHandle, UT_JSONHandleError
207 public:
209  virtual ~UT_JSONHandleNull() {}
210  virtual bool jsonNull(UT_JSONParser &p);
211  virtual bool jsonBool(UT_JSONParser &p, bool value);
212  virtual bool jsonInt(UT_JSONParser &p, int64 value);
213  virtual bool jsonReal(UT_JSONParser &p, fpreal64 value);
214  virtual bool jsonString(UT_JSONParser &p, const char *v, int64 len);
215  virtual bool jsonKey(UT_JSONParser &p, const char *v, int64 len);
216  virtual bool jsonBeginMap(UT_JSONParser &p);
217  virtual bool jsonEndMap(UT_JSONParser &p);
218  virtual bool jsonBeginArray(UT_JSONParser &p);
219  virtual bool jsonEndArray(UT_JSONParser &p);
220 };
221 
222 
223 #endif
virtual ~UT_JSONHandleNull()
virtual bool jsonInt(UT_JSONParser &p, int64 value)=0
Event method to process an integer.
png_voidp s1
Definition: png.h:2193
virtual ~UT_JSONHandle()
Definition: UT_JSONHandle.h:39
const GLdouble * v
Definition: glcorearb.h:836
UT_JSONHandle processes events from a UT_JSONParser parser.
Definition: UT_JSONHandle.h:36
virtual bool jsonBool(UT_JSONParser &p, bool value)=0
Event method to process a bool (true or false tokens)
JSON reader class which handles parsing of JSON or bJSON files.
Definition: UT_JSONParser.h:75
#define UT_API
Definition: UT_API.h:13
virtual bool jsonBeginArray(UT_JSONParser &p)=0
Event method invoked at the beginning of an array object.
UT_JSONHandleError(bool fatal=true)
virtual bool jsonEndArray(UT_JSONParser &p)=0
Event method invoked at the end of an array object.
virtual bool jsonKey(UT_JSONParser &p, const char *v, int64 len)=0
Event method to process the key of a map/object is read.
long long int64
Definition: SYS_Types.h:107
GLfloat f
Definition: glcorearb.h:1925
void setFatal(bool f)
Set whether errors should be fatal (or just warnings)
virtual ~UT_JSONHandleError()
double fpreal64
Definition: SYS_Types.h:192
virtual bool jsonReal(UT_JSONParser &p, fpreal64 value)=0
Event method to process a real/float.
GLuint const GLchar * name
Definition: glcorearb.h:785
This class generates errors on any JSON events.
virtual bool jsonString(UT_JSONParser &p, const char *value, int64 len)=0
Event method to process a string value.
GLfloat GLfloat GLfloat GLfloat h
Definition: glcorearb.h:2001
GLsizei const GLfloat * value
Definition: glcorearb.h:823
png_voidp png_voidp s2
Definition: png.h:2193
bool isKey(const char *s1, const char *s2) const
Convenience method to test key values.
int SYSstrcasecmp(const char *a, const char *b)
Definition: SYS_String.h:227
virtual bool jsonBeginMap(UT_JSONParser &p)=0
Event method invoked at the start of a map/object.
This class skips over any JSON events.
bool getFatal() const
Check whether errors should be fatal (or just warnings)
virtual bool jsonNull(UT_JSONParser &p)=0
Event method to process a null token.
virtual bool jsonEndMap(UT_JSONParser &p)=0
Event method invoked at the end of a map/object.
GLuint GLsizei GLsizei * length
Definition: glcorearb.h:794