1  /*
  2    Copyright (c) 2009 Dave Gamble
  3  
  4    Permission is hereby granted, free of charge, to any person obtaining a copy
  5    of this software and associated documentation files (the "Software"), to deal
  6    in the Software without restriction, including without limitation the rights
  7    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  8    copies of the Software, and to permit persons to whom the Software is
  9    furnished to do so, subject to the following conditions:
 10  
 11    The above copyright notice and this permission notice shall be included in
 12    all copies or substantial portions of the Software.
 13  
 14    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 15    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 16    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 17    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 18    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 19    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 20    THE SOFTWARE.
 21  */
 22  
 23  Welcome to cJSON.
 24  
 25  cJSON aims to be the dumbest possible parser that you can get your job done with.
 26  It's a single file of C, and a single header file.
 27  
 28  JSON is described best here: http://www.json.org/
 29  It's like XML, but fat-free. You use it to move data around, store things, or just
 30  generally represent your program's state.
 31  
 32  
 33  First up, how do I build?
 34  Add cJSON.c to your project, and put cJSON.h somewhere in the header search path.
 35  For example, to build the test app:
 36  
 37  gcc cJSON.c test.c -o test -lm
 38  ./test
 39  
 40  
 41  As a library, cJSON exists to take away as much legwork as it can, but not get in your way.
 42  As a point of pragmatism (i.e. ignoring the truth), I'm going to say that you can use it
 43  in one of two modes: Auto and Manual. Let's have a quick run-through.
 44  
 45  
 46  I lifted some JSON from this page: http://www.json.org/fatfree.html
 47  That page inspired me to write cJSON, which is a parser that tries to share the same
 48  philosophy as JSON itself. Simple, dumb, out of the way.
 49  
 50  Some JSON:
 51  {
 52      "name": "Jack (\"Bee\") Nimble", 
 53      "format": {
 54          "type":       "rect", 
 55          "width":      1920, 
 56          "height":     1080, 
 57          "interlace":  false, 
 58          "frame rate": 24
 59      }
 60  }
 61  
 62  Assume that you got this from a file, a webserver, or magic JSON elves, whatever,
 63  you have a char * to it. Everything is a cJSON struct.
 64  Get it parsed:
 65  	cJSON *root = cJSON_Parse(my_json_string);
 66  
 67  This is an object. We're in C. We don't have objects. But we do have structs.
 68  What's the framerate?
 69  
 70  	cJSON *format = cJSON_GetObjectItem(root,"format");
 71  	int framerate = cJSON_GetObjectItem(format,"frame rate")->valueint;
 72  
 73  
 74  Want to change the framerate?
 75  	cJSON_GetObjectItem(format,"frame rate")->valueint=25;
 76  	
 77  Back to disk?
 78  	char *rendered=cJSON_Print(root);
 79  
 80  Finished? Delete the root (this takes care of everything else).
 81  	cJSON_Delete(root);
 82  
 83  That's AUTO mode. If you're going to use Auto mode, you really ought to check pointers
 84  before you dereference them. If you want to see how you'd build this struct in code?
 85  	cJSON *root,*fmt;
 86  	root=cJSON_CreateObject();	
 87  	cJSON_AddItemToObject(root, "name", cJSON_CreateString("Jack (\"Bee\") Nimble"));
 88  	cJSON_AddItemToObject(root, "format", fmt=cJSON_CreateObject());
 89  	cJSON_AddStringToObject(fmt,"type",		"rect");
 90  	cJSON_AddNumberToObject(fmt,"width",		1920);
 91  	cJSON_AddNumberToObject(fmt,"height",		1080);
 92  	cJSON_AddFalseToObject (fmt,"interlace");
 93  	cJSON_AddNumberToObject(fmt,"frame rate",	24);
 94  
 95  Hopefully we can agree that's not a lot of code? There's no overhead, no unnecessary setup.
 96  Look at test.c for a bunch of nice examples, mostly all ripped off the json.org site, and
 97  a few from elsewhere.
 98  
 99  What about manual mode? First up you need some detail.
100  Let's cover how the cJSON objects represent the JSON data.
101  cJSON doesn't distinguish arrays from objects in handling; just type.
102  Each cJSON has, potentially, a child, siblings, value, a name.
103  
104  The root object has: Object Type and a Child
105  The Child has name "name", with value "Jack ("Bee") Nimble", and a sibling:
106  Sibling has type Object, name "format", and a child.
107  That child has type String, name "type", value "rect", and a sibling:
108  Sibling has type Number, name "width", value 1920, and a sibling:
109  Sibling has type Number, name "height", value 1080, and a sibling:
110  Sibling has type False, name "interlace", and a sibling:
111  Sibling has type Number, name "frame rate", value 24
112  
113  Here's the structure:
114  typedef struct cJSON {
115  	struct cJSON *next,*prev;
116  	struct cJSON *child;
117  
118  	int type;
119  
120  	char *valuestring;
121  	int valueint;
122  	double valuedouble;
123  
124  	char *string;
125  } cJSON;
126  
127  By default all values are 0 unless set by virtue of being meaningful.
128  
129  next/prev is a doubly linked list of siblings. next takes you to your sibling,
130  prev takes you back from your sibling to you.
131  Only objects and arrays have a "child", and it's the head of the doubly linked list.
132  A "child" entry will have prev==0, but next potentially points on. The last sibling has next=0.
133  The type expresses Null/True/False/Number/String/Array/Object, all of which are #defined in
134  cJSON.h
135  
136  A Number has valueint and valuedouble. If you're expecting an int, read valueint, if not read
137  valuedouble.
138  
139  Any entry which is in the linked list which is the child of an object will have a "string"
140  which is the "name" of the entry. When I said "name" in the above example, that's "string".
141  "string" is the JSON name for the 'variable name' if you will.
142  
143  Now you can trivially walk the lists, recursively, and parse as you please.
144  You can invoke cJSON_Parse to get cJSON to parse for you, and then you can take
145  the root object, and traverse the structure (which is, formally, an N-tree),
146  and tokenise as you please. If you wanted to build a callback style parser, this is how
147  you'd do it (just an example, since these things are very specific):
148  
149  void parse_and_callback(cJSON *item,const char *prefix)
150  {
151  	while (item)
152  	{
153  		char *newprefix=malloc(strlen(prefix)+strlen(item->name)+2);
154  		sprintf(newprefix,"%s/%s",prefix,item->name);
155  		int dorecurse=callback(newprefix, item->type, item);
156  		if (item->child && dorecurse) parse_and_callback(item->child,newprefix);
157  		item=item->next;
158  		free(newprefix);
159  	}
160  }
161  
162  The prefix process will build you a separated list, to simplify your callback handling.
163  The 'dorecurse' flag would let the callback decide to handle sub-arrays on it's own, or
164  let you invoke it per-item. For the item above, your callback might look like this:
165  
166  int callback(const char *name,int type,cJSON *item)
167  {
168  	if (!strcmp(name,"name"))	{ /* populate name */ }
169  	else if (!strcmp(name,"format/type")	{ /* handle "rect" */ }
170  	else if (!strcmp(name,"format/width")	{ /* 800 */ }
171  	else if (!strcmp(name,"format/height")	{ /* 600 */ }
172  	else if (!strcmp(name,"format/interlace")	{ /* false */ }
173  	else if (!strcmp(name,"format/frame rate")	{ /* 24 */ }
174  	return 1;
175  }
176  
177  Alternatively, you might like to parse iteratively.
178  You'd use:
179  
180  void parse_object(cJSON *item)
181  {
182  	int i; for (i=0;i<cJSON_GetArraySize(item);i++)
183  	{
184  		cJSON *subitem=cJSON_GetArrayItem(item,i);
185  		// handle subitem.	
186  	}
187  }
188  
189  Or, for PROPER manual mode:
190  
191  void parse_object(cJSON *item)
192  {
193  	cJSON *subitem=item->child;
194  	while (subitem)
195  	{
196  		// handle subitem
197  		if (subitem->child) parse_object(subitem->child);
198  		
199  		subitem=subitem->next;
200  	}
201  }
202  
203  Of course, this should look familiar, since this is just a stripped-down version
204  of the callback-parser.
205  
206  This should cover most uses you'll find for parsing. The rest should be possible
207  to infer.. and if in doubt, read the source! There's not a lot of it! ;)
208  
209  
210  In terms of constructing JSON data, the example code above is the right way to do it.
211  You can, of course, hand your sub-objects to other functions to populate.
212  Also, if you find a use for it, you can manually build the objects.
213  For instance, suppose you wanted to build an array of objects?
214  
215  cJSON *objects[24];
216  
217  cJSON *Create_array_of_anything(cJSON **items,int num)
218  {
219  	int i;cJSON *prev, *root=cJSON_CreateArray();
220  	for (i=0;i<24;i++)
221  	{
222  		if (!i)	root->child=objects[i];
223  		else	prev->next=objects[i], objects[i]->prev=prev;
224  		prev=objects[i];
225  	}
226  	return root;
227  }
228  	
229  and simply: Create_array_of_anything(objects,24);
230  
231  cJSON doesn't make any assumptions about what order you create things in.
232  You can attach the objects, as above, and later add children to each
233  of those objects.
234  
235  As soon as you call cJSON_Print, it renders the structure to text.
236  
237  
238  
239  The test.c code shows how to handle a bunch of typical cases. If you uncomment
240  the code, it'll load, parse and print a bunch of test files, also from json.org,
241  which are more complex than I'd care to try and stash into a const char array[].
242  
243  
244  Enjoy cJSON!
245  
246  
247  - Dave Gamble, Aug 2009