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, tests are in 86the jsmn\_test.c, you will also find README, LICENSE and Makefile files inside. 87 88To build the library, run `make`. It is also recommended to run `make test`. 89Let me know, if some tests fail. 90 91If build was successful, you should get a `libjsmn.a` library. 92The header file you should include is called `"jsmn.h"`. 93 94API 95--- 96 97Token types are described by `jsmntype_t`: 98 99 typedef enum { 100 JSMN_PRIMITIVE = 0, 101 JSMN_OBJECT = 1, 102 JSMN_ARRAY = 2, 103 JSMN_STRING = 3 104 } jsmntype_t; 105 106**Note:** Unlike JSON data types, primitive tokens are not divided into 107numbers, booleans and null, because one can easily tell the type using the 108first character: 109 110* <code>'t', 'f'</code> - boolean 111* <code>'n'</code> - null 112* <code>'-', '0'..'9'</code> - number 113 114Token is an object of `jsmntok_t` type: 115 116 typedef struct { 117 jsmntype_t type; // Token type 118 int start; // Token start position 119 int end; // Token end position 120 int size; // Number of child (nested) tokens 121 } jsmntok_t; 122 123**Note:** string tokens point to the first character after 124the opening quote and the previous symbol before final quote. This was made 125to simplify string extraction from JSON data. 126 127All job is done by `jsmn_parser` object. You can initialize a new parser using: 128 129 jsmn_parser parser; 130 jsmntok_t tokens[10]; 131 132 jsmn_init(&parser); 133 134 // js - pointer to JSON string 135 // tokens - an array of tokens available 136 // 10 - number of tokens available 137 jsmn_parse(&parser, js, tokens, 10); 138 139This will create a parser, and then it tries to parse up to 10 JSON tokens from 140the `js` string. 141 142A non-negative reutrn value of `jsmn_parse` is the number of tokens actually 143used by the parser. 144Passing NULL instead of the tokens array would not store parsing results, but 145instead the function will return the value of tokens needed to parse the given 146string. This can be useful if you don't know yet how many tokens to allocate. 147 148If something goes wrong, you will get an error. Error will be one of these: 149 150* `JSMN_ERROR_INVAL` - bad token, JSON string is corrupted 151* `JSMN_ERROR_NOMEM` - not enough tokens, JSON string is too large 152* `JSMN_ERROR_PART` - JSON string is too short, expecting more JSON data 153 154If you get `JSON_ERROR_NOMEM`, you can re-allocate more tokens and call 155`jsmn_parse` once more. If you read json data from the stream, you can 156periodically call `jsmn_parse` and check if return value is `JSON_ERROR_PART`. 157You will get this error until you reach the end of JSON data. 158 159Other info 160---------- 161 162This software is distributed under [MIT license](http://www.opensource.org/licenses/mit-license.php), 163 so feel free to integrate it in your commercial products. 164 165[1]: http://www.json.org/ 166[2]: https://bitbucket.org/zserge/jsmn/wiki/Home 167[3]: http://zserge.com/jsmn.html 168