forked from netmail-open/wjelement
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathwjreader.html
208 lines (199 loc) · 5.79 KB
/
wjreader.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
<html>
<head>
<title>WJElement Documentation: wjreader</title>
</head>
<body>
<a href="index.html">Index</a>
<h1>WJReader Synopsis</h1>
<p>
The WARP JSON Reader provides the ability to parse a JSON document as a
stream. All parsing is done with a portion of the document loaded into a
buffer, and the buffer is reloaded as needed.
</p>
<p>
This allows the parser to be very fast, but does require that data in the
document is accessed in the order of the document.
</p>
<h1>WJReader Data Types</h1>
<p>
<strong>WJReader</strong>
is The WJReader document, the library's primary structure
</p>
<p>
From wjreader.h:
<blockquote><pre>
typedef struct {
uint32 depth;
uint32 maxdepth;
void *userdata;
} WJReaderPublic;
typedef WJReaderPublic * WJReader;
</pre></blockquote>
</p>
<p>
<strong>WJRType</strong>
specifies the type of a value being read.
</p>
<p>
From wjreader.h:
<blockquote><pre>
typedef enum {
WJR_TYPE_OBJECT = 'O',
WJR_TYPE_ARRAY = 'A',
WJR_TYPE_STRING = 'S',
WJR_TYPE_NUMBER = 'N',
WJR_TYPE_BOOL = 'B',
WJR_TYPE_TRUE = 'T',
WJR_TYPE_FALSE = 'F',
WJR_TYPE_NULL = '0',
WJR_TYPE_UNKNOWN = '?'
} WJRType;
</pre></blockquote>
</p>
<p>
<strong>WJReadCallback</strong>
- Generic data reader (from file, socket, decoder, etc.)
</p>
<p>
<blockquote><pre>
typedef size_t (* WJReadCallback)(char *data, size_t length, size_t seen, void *userdata);
</pre></blockquote>
</p>
<h1>WJReader Interfaces</h1>
<h2>Document/Reader Management</h2>
<p>
<strong>WJROpenDocument</strong>
- Open a JSON document and prepare to parse.
</p>
<p>
<blockquote><pre>
WJReader WJROpenDocument(WJReadCallback callback, void *userdata, char *buffer,
size_t buffersize);
WJReader _WJROpenDocument(WJReadCallback callback, void *userdata, char *buffer,
size_t buffersize, uint32 maxdepth);
</pre></blockquote>
</p>
<p>
A callback function must be
provided which will be used to read data as it is needed. The callback is
expected to load data into the provided buffer and return the number of
bytes that where loaded. If the number of bytes loaded is less than the
requested length then it is assumed that the end of the document has been
reached.
</p>
<p>
If a buffer is provided to WJROpenDocument() then that buffer will be used,
rather than allocating a new buffer. The size of the buffer must be
provided as buffersize. If a buffer is not provided then one will be
allocated of size buffersize.
</p>
<p>
If a buffersize of 0 is passed to WJROpenDocument then the default size will
be used (4KB). Some data is kept in the buffer while parsing, such as
element names and values. If the buffer is not large enough for these then
the document will fail to be parsed and will be aborted.
</p>
<p>
<strong>WJROpenFILEDocument</strong>
- helper to read from an open FILE *.
</p>
<p>
<blockquote><pre>
WJReader WJROpenFILEDocument(FILE *jsonfile, char *buffer, size_t buffersize);
</pre></blockquote>
</p>
<p>
An alternative method of opening a JSON document, which will provide a
proper callback for reading the data from an open FILE *.
</p>
<p>
As with the standard WJROpenDocument() a buffersize of 0 will use the
default buffer size.
</p>
<p>
<strong>WJROpenMemDocument</strong>
- helper to read from memory.
</p>
<p>
<blockquote><pre>
WJReader WJROpenMemDocument(char *json, char *buffer, size_t buffersize);
</pre></blockquote>
</p>
<p>
An alternative method of opening a JSON document, which will provide a
proper callback for reading from a pre-allocated buffer in memory.
</p>
<p>
As with the standard WJROpenDocument() a buffersize of 0 will use the
default buffer size.
</p>
<p>
<strong>WJRCloseDocument</strong>
- Close a WJReader document.
</p>
<p>
<blockquote><pre>
XplBool WJRCloseDocument(WJReader doc);
</pre></blockquote>
</p>
<h2>JSON Values</h2>
<p>
<strong>WJRNext</strong>
- Get the type and name of the next element in 'doc'.
</p>
<p>
<blockquote><pre>
char * WJRNext(char *parent, size_t maxnamelen, WJReader doc);
</pre></blockquote>
</p>
<p>
Returns a string, which contains the name of the next element of the
specified parent, prefixed by a single character that represents the type.
The pointer returned may be used as the parent argument in future calls to
WJRNext() in order to return the children of the current object.
</p>
<p>
If the object's name is larger than the maxnamelen argument then it will be
truncated.
</p>
<p>
These WJReader functions
Return the value of the last object returned by WJRNext(). The calling
application is expected to know the type of the value, and call the
appropriate function. When possible the value will be converted if it does
not match the requested type.
</p>
<p>
If the buffer is not large enough to contain the entire value then the
WJRString() function may return a partial value. It may be called multiple
times until a NULL is returned to ensure that the entire value has been
read.
</p>
<p>
<blockquote><pre>
char * WJRString(XplBool *complete, WJReader doc);
char * WJRStringEx(XplBool *complete, size_t *length, WJReader doc);
XplBool WJRBoolean(WJReader doc);
int32 WJRInt32(WJReader doc);
uint32 WJRUInt32(WJReader doc);
int64 WJRInt64(WJReader doc);
uint64 WJRUInt64(WJReader doc);
double WJRDouble(WJReader doc);
</pre></blockquote>
</p>
<p>
<strong>WJRNegative</strong>
- Check whether the current WJR_TYPE_NUMBER value is negative
</p>
<p>
<blockquote><pre>
XplBool WJRNegative(WJReader doc);
</pre></blockquote>
</p>
<p>
If the current element is a WJR_TYPE_NUMBER then this function can be used
to determine if the value is negative or positive. If negative then TRUE
will be returned.
</p>
</body>
</html>