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