1/*!
2\page json Json Handling
3
4<a href="http://www.json.org/">JSON</a> is a simple textual description of a
5data structure.  An example of some JSON would be;
6
7\code
8[ "apple", "orange", { "drink": "tonic water", "count" : 123 } ]
9\endcode
10
11This example is a list that contains two strings followed by an "object".  The
12term object refers to a construct akin to a "dictionary" or a "map".  It is also
13possible for top-level objects to be non-collection types such as strings.  The
14following is also valid JSON;
15
16\code
17"fijoa"
18\endcode
19
20This page details how Haiku provides facilities for both parsing as well as
21writing data encoded as Json.
22
23\section parsing-in-memory-model Parsing with Generic In-Memory Model
24
25For some applications, parsing to an in-memory data structure is ideal.  In
26such cases, the \c BJson class provides static methods for parsing a block
27of JSON data into a \c BMessage object.  The application logic is then able to
28introspect the \c BMessage to obtain values.
29
30\subsection bmessage-structure BMessage Structure
31
32The \c BMessage class has the ability to carry a collection of key-value pairs.
33In the case of a Json object type, the key-value pairs correlate to a JSON
34object or array.  In the case of a JSON array type, the key-value pairs are
35the index of the elements in the JSON array represented as strings.
36
37For example, the following JSON array...
38
39\code
40[ "a", "b", "c" ]
41\endcode
42
43...would be represented by the following \c BMessage ;
44
45<table>
46	<tr>
47		<th>Key</th>
48		<th>Value</th>
49	</tr>
50	<tr>
51		<td>\c "0"</td>
52		<td>\c "a"</td>
53	</tr>
54	<tr>
55		<td>\c "1"</td>
56		<td>\c "b"</td>
57	</tr>
58	<tr>
59		<td>\c "2"</td>
60		<td>\c "c"</td>
61	</tr>
62</table>
63
64A Json object that, in its entirety, consists of a non-collection type such as
65a simple string or a boolean is not able to be represented by a \c BMessage ;
66at the top level there must be an array or an object for the parse to be
67successful.
68
69\section parsing-streaming Stream-based Parsing
70
71Streaming is useful in many situations;
72
73	- where handling the parsed data is easier to undertake as a stream of
74		events
75	- where the quantity of input or output data could be non-trivial and
76		holding that quantity of material in memory is undesirable
77	- where being able to start processing a stream of data before the entire
78		payload has arrived is desirable
79
80This architecture is sometimes known as an event-based parser or a "SAX" parser.
81
82The \c BJson class provides a static method that accepts a stream of Json
83data in the form of a \c BDataIO. A \c BJsonEventListener sub-class is also
84supplied and as each Json token is read-in from the stream, it will be
85provided to the listener.  The listener must implement three callback methods
86to handle the Json tokens;
87
88<table>
89	<tr>
90		<th>Method</th>
91		<th>Description</th>
92	</tr>
93	<tr>
94		<td>\c Handle(..)</td>
95		<td>Provides JSON events to the listener</td>
96	</tr>
97	<tr>
98		<td>\c HandleError(..)</td>
99		<td>Signals parse or processing errors to the listener</td>
100	</tr>
101	<tr>
102		<td>\c Complete(..)</td>
103		<td>Informs the listener that parsing has completed</td>
104	</tr>
105</table>
106
107Events are embodied in instances of the \c BJsonEvent class and each of
108these has a type.  Example types are;
109
110	- \c B_JSON_STRING
111	- \c B_JSON_OBJECT_START
112	- \c B_JSON_TRUE
113
114In this way, the listener is able to interpret the incoming stream of data as
115Json and handle it in some way.
116
117The following Json...
118
119\code
120{"color": "red", "alpha": 0.6}
121\endcode
122
123Would yield the following stream of events;
124
125<table>
126	<tr>
127		<th>Event Type</th>
128		<th>Event Data</th>
129	</tr>
130	<tr>
131		<td>\c B_JSON_OBJECT_START</td>
132		<td>-</td>
133	</tr>
134	<tr>
135		<td>\c B_JSON_OBJECT_NAME</td>
136		<td>"color"</td>
137	</tr>
138	<tr>
139		<td>\c B_JSON_STRING</td>
140		<td>"red"</td>
141	</tr>
142	<tr>
143		<td>\c B_JSON_OBJECT_NAME</td>
144		<td>"alpha"</td>
145	</tr>
146	<tr>
147		<td>\c B_JSON_NUMBER</td>
148		<td>0.6</td>
149	</tr>
150	<tr>
151		<td>\c B_JSON_OBJECT_END</td>
152		<td>-</td>
153	</tr>
154</table>
155
156\subsection parsing-streaming-numbers Number Handling
157
158The Json number literal format does not specify a numeric type such as \c int32
159or \c double.  To cope with the widest range of possibilities, the
160\c B_JSON_NUMBER event type captures the content as a string and then the
161\c BJsonEvent object is able to provide the original string for specific
162handling as well as convenient accessors for parsing to \c double or \c int64
163types.  This provides a high level of flexibility for the client.
164
165\subsection parsing-streaming-stacked-listeners Stacked Listeners
166
167One implementation approach for a listener implement that might be used to
168read a data-transfer-object (DTO) is to create "sub-listeners" that mirror
169the structure of the Json data.
170
171In the following example, a nested data structure is being parsed.
172
173\image html stacked-listeners.svg
174
175A primary-listener is employed called \c ColorGradientsListener.  The
176primary-listener accepts Json parse events and will relay them to a
177sub-listener.  The sub-listener is implemented to specifically deal with one
178tier of the inbound data.  The sub-listeners are structured in a stack where
179the sub-listener at the head of the stack has a pointer to its parent.  The
180primary-listener maintains a pointer to the current head of the stack and will
181direct events to that sub-listener.
182
183In response to events, the sub-listener can take-up the data, pop itself from
184the stack or push additional sub-listeners from the stack.
185
186The same approach has been used in the following classes in a more generic
187manner;
188
189	- \c BJsonTextWriter
190	- \c BJsonMessageWriter
191
192The intention with this approach is that the structure of the event handling
193code in the sub-listeners mirrors that of the data-structure being parsed.
194Hopefully this makes creating the filling of a specific data-model easier even
195when very specific behaviours are required.
196
197From a schema of the data structure it is probably also possible to create
198these sub-listeners and in this way automatically generate the C++ parse
199code as event listeners.
200
201\section writing Writing
202
203In order to render a data-structure as textual Json data, the opposite flow
204occurs; events are emitted by the client software into a class
205\c BJsonTextWriter.  This class supports public methods such as
206\c WriteFalse() , \c WriteObjectStart() and \c WriteString(...) that control
207the outbound Json stream.
208
209\section end-to-end End to End
210
211Because \c BJsonTextWriter is accepting JSON parse events, it is also a
212\c JsonEventListener and so can be used as a listener with the stream parsing;
213producing Json output from Json input.  The output will however not include
214inbound whitespace because whitespace is not grammatically significant in Json.
215
216*/