1JSMN 2==== 3 4[](https://travis-ci.org/zserge/jsmn) 5 6jsmn (pronounced like 'jasmine') is a minimalistic JSON parser in C. It can be 7easily integrated into resource-limited or embedded projects. 8 9You can find more information about JSON format at [json.org][1] 10 11Library sources are available at https://github.com/zserge/jsmn 12 13The web page with some information about jsmn can be found at 14[http://zserge.com/jsmn.html][2] 15 16Philosophy 17---------- 18 19Most JSON parsers offer you a bunch of functions to load JSON data, parse it 20and extract any value by its name. jsmn proves that checking the correctness of 21every JSON packet or allocating temporary objects to store parsed JSON fields 22often is an overkill. 23 24JSON format itself is extremely simple, so why should we complicate it? 25 26jsmn is designed to be **robust** (it should work fine even with erroneous 27data), **fast** (it should parse data on the fly), **portable** (no superfluous 28dependencies or non-standard C extensions). And of course, **simplicity** is a 29key feature - simple code style, simple algorithm, simple integration into 30other projects. 31 32Features 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 45Design 46------ 47 48The rudimentary jsmn object is a **token**. Let's consider a JSON string: 49 50 '{ "name" : "Jack", "age" : 27 }' 51 52It 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 58In jsmn, tokens do not hold any data, but point to token boundaries in JSON 59string 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 62Every jsmn token has a type, which indicates the type of corresponding JSON 63token. 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 72Besides start/end positions, jsmn tokens for complex types (like arrays 73or objects) also contain a number of child items, so you can easily follow 74object hierarchy. 75 76This approach provides enough information for parsing any JSON data and makes 77it possible to use zero-copy techniques. 78 79Usage 80----- 81 82Download `jsmn.h`, include it, done. 83 84``` 85#include "jsmn.h" 86 87... 88jsmn_parser p; 89jsmntok_t t[128]; /* We expect no more than 128 JSON tokens */ 90 91jsmn_init(&p); 92r = jsmn_parse(&p, s, strlen(s), t, 128); 93``` 94 95Since jsmn is a single-header, header-only library, for more complex use cases 96you might need to define additional macros. `#define JSMN_STATIC` hides all 97jsmn API symbols by making them static. Also, if you want to include `jsmn.h` 98from multiple C files, to avoid duplication of symbols you may define `JSMN_HEADER` macro. 99 100``` 101/* In every .c file that uses jsmn include only declarations: */ 102#define JSMN_HEADER 103#include "jsmn.h" 104 105/* Additionally, create one jsmn.c file for jsmn implementation: */ 106#include "jsmn.h" 107``` 108 109API 110--- 111 112Token types are described by `jsmntype_t`: 113 114 typedef enum { 115 JSMN_UNDEFINED = 0, 116 JSMN_OBJECT = 1, 117 JSMN_ARRAY = 2, 118 JSMN_STRING = 3, 119 JSMN_PRIMITIVE = 4 120 } jsmntype_t; 121 122**Note:** Unlike JSON data types, primitive tokens are not divided into 123numbers, booleans and null, because one can easily tell the type using the 124first character: 125 126* <code>'t', 'f'</code> - boolean 127* <code>'n'</code> - null 128* <code>'-', '0'..'9'</code> - number 129 130Token is an object of `jsmntok_t` type: 131 132 typedef struct { 133 jsmntype_t type; // Token type 134 int start; // Token start position 135 int end; // Token end position 136 int size; // Number of child (nested) tokens 137 } jsmntok_t; 138 139**Note:** string tokens point to the first character after 140the opening quote and the previous symbol before final quote. This was made 141to simplify string extraction from JSON data. 142 143All job is done by `jsmn_parser` object. You can initialize a new parser using: 144 145 jsmn_parser parser; 146 jsmntok_t tokens[10]; 147 148 jsmn_init(&parser); 149 150 // js - pointer to JSON string 151 // tokens - an array of tokens available 152 // 10 - number of tokens available 153 jsmn_parse(&parser, js, strlen(js), tokens, 10); 154 155This will create a parser, and then it tries to parse up to 10 JSON tokens from 156the `js` string. 157 158A non-negative return value of `jsmn_parse` is the number of tokens actually 159used by the parser. 160Passing NULL instead of the tokens array would not store parsing results, but 161instead the function will return the value of tokens needed to parse the given 162string. This can be useful if you don't know yet how many tokens to allocate. 163 164If something goes wrong, you will get an error. Error will be one of these: 165 166* `JSMN_ERROR_INVAL` - bad token, JSON string is corrupted 167* `JSMN_ERROR_NOMEM` - not enough tokens, JSON string is too large 168* `JSMN_ERROR_PART` - JSON string is too short, expecting more JSON data 169 170If you get `JSMN_ERROR_NOMEM`, you can re-allocate more tokens and call 171`jsmn_parse` once more. If you read json data from the stream, you can 172periodically call `jsmn_parse` and check if return value is `JSMN_ERROR_PART`. 173You will get this error until you reach the end of JSON data. 174 175Other info 176---------- 177 178This software is distributed under [MIT license](http://www.opensource.org/licenses/mit-license.php), 179 so feel free to integrate it in your commercial products. 180 181[1]: http://www.json.org/ 182[2]: http://zserge.com/jsmn.html 183
){kind=link}