1 2JSMN 3==== 4 5jsmn (pronounced like 'jasmine') is a minimalistic JSON parser in C. It can be 6easily integrated into resource-limited or embedded projects. 7 8You can find more information about JSON format at [json.org][1] 9 10Library sources are available at [bitbucket.org/zserge/jsmn][2] 11 12The web page with some information about jsmn can be found at 13[http://zserge.com/jsmn.html][3] 14 15Philosophy 16---------- 17 18Most JSON parsers offer you a bunch of functions to load JSON data, parse it 19and extract any value by its name. jsmn proves that checking the correctness of 20every JSON packet or allocating temporary objects to store parsed JSON fields 21often is an overkill. 22 23JSON format itself is extremely simple, so why should we complicate it? 24 25jsmn is designed to be **robust** (it should work fine even with erroneous 26data), **fast** (it should parse data on the fly), **portable** (no superfluous 27dependencies or non-standard C extensions). An of course, **simplicity** is a 28key feature - simple code style, simple algorithm, simple integration into 29other projects. 30 31Features 32-------- 33 34* compatible with C89 35* no dependencies (even libc!) 36* highly portable (tested on x86/amd64, ARM, AVR) 37* about 200 lines of code 38* extremely small code footprint 39* API contains only 2 functions 40* no dynamic memory allocation 41* incremental single-pass parsing 42* library code is covered with unit-tests 43 44Design 45------ 46 47The rudimentary jsmn object is a **token**. Let's consider a JSON string: 48 49 '{ "name" : "Jack", "age" : 27 }' 50 51It holds the following tokens: 52 53* Object: `{ "name" : "Jack", "age" : 27}` (the whole object) 54* Strings: `"name"`, `"Jack"`, `"age"` (keys and some values) 55* Number: `27` 56 57In jsmn, tokens do not hold any data, but point to token boundaries in JSON 58string instead. In the example above jsmn will create tokens like: Object 59[0..31], String [3..7], String [12..16], String [20..23], Number [27..29]. 60 61Every jsmn token has a type, which indicates the type of corresponding JSON 62token. jsmn supports the following token types: 63 64* Object - a container of key-value pairs, e.g.: 65 `{ "foo":"bar", "x":0.3 }` 66* Array - a sequence of values, e.g.: 67 `[ 1, 2, 3 ]` 68* String - a quoted sequence of chars, e.g.: `"foo"` 69* Primitive - a number, a boolean (`true`, `false`) or `null` 70 71Besides start/end positions, jsmn tokens for complex types (like arrays 72or objects) also contain a number of child items, so you can easily follow 73object hierarchy. 74 75This approach provides enough information for parsing any JSON data and makes 76it possible to use zero-copy techniques. 77 78Install 79------- 80 81To clone the repository you should have mercurial installed. Just run: 82 83 $ hg clone http://bitbucket.org/zserge/jsmn jsmn 84 85Repository layout is simple: jsmn.c and jsmn.h are library files; demo.c is an 86example of how to use jsmn (it is also used in unit tests); test.sh is a test 87script. You will also find README, LICENSE and Makefile files inside. 88 89To build the library, run `make`. It is also recommended to run `make test`. 90Let me know, if some tests fail. 91 92If build was successful, you should get a `libjsmn.a` library. 93The header file you should include is called `"jsmn.h"`. 94 95API 96--- 97 98Token types are described by `jsmntype_t`: 99 100 typedef enum { 101 JSMN_PRIMITIVE = 0, 102 JSMN_OBJECT = 1, 103 JSMN_ARRAY = 2, 104 JSMN_STRING = 3 105 } jsmntype_t; 106 107**Note:** Unlike JSON data types, primitive tokens are not divided into 108numbers, booleans and null, because one can easily tell the type using the 109first character: 110 111* <code>'t', 'f'</code> - boolean 112* <code>'n'</code> - null 113* <code>'-', '0'..'9'</code> - number 114 115Token is an object of `jsmntok_t` type: 116 117 typedef struct { 118 jsmntype_t type; // Token type 119 int start; // Token start position 120 int end; // Token end position 121 int size; // Number of child (nested) tokens 122 } jsmntok_t; 123 124**Note:** string tokens point to the first character after 125the opening quote and the previous symbol before final quote. This was made 126to simplify string extraction from JSON data. 127 128All job is done by `jsmn_parser` object. You can initialize a new parser using: 129 130 struct jsmn_parser parser; 131 jsmntok_t tokens[10]; 132 133 // js - pointer to JSON string 134 // tokens - an array of tokens available 135 // 10 - number of tokens available 136 jsmn_init_parser(&parser, js, tokens, 10); 137 138This will create a parser, that can parse up to 10 JSON tokens from `js` string. 139 140Later, you can use `jsmn_parse(&parser)` function to process JSON string with the parser. 141If something goes wrong, you will get an error. Error will be one of these: 142 143* `JSMN_SUCCESS` - everything went fine. String was parsed 144* `JSMN_ERROR_INVAL` - bad token, JSON string is corrupted 145* `JSMN_ERROR_NOMEM` - not enough tokens, JSON string is too large 146* `JSMN_ERROR_PART` - JSON string is too short, expecting more JSON data 147 148If you get `JSON_ERROR_NOMEM`, you can re-allocate more tokens and call 149`jsmn_parse` once more. If you read json data from the stream, you can 150periodically call `jsmn_parse` and check if return value is `JSON_ERROR_PART`. 151You will get this error until you reach the end of JSON data. 152 153Other info 154---------- 155 156This software is distributed under [MIT license](http://www.opensource.org/licenses/mit-license.php), 157 so feel free to integrate it in your commercial products. 158 159[1]: http://www.json.org/ 160[2]: https://bitbucket.org/zserge/jsmn/wiki/Home 161[3]: http://zserge.com/jsmn.html 162