diplodocus.org Git - nmh/blob - thirdparty/jsmn/README.md

   1
   2 JSMN
   3 ====
   4
   5 jsmn (pronounced like 'jasmine') is a minimalistic JSON parser in C.  It can be
   6 easily integrated into resource-limited or embedded projects.
   7
   8 You can find more information about JSON format at [json.org][1]
   9
  10 Library sources are available at [bitbucket.org/zserge/jsmn][2]
  11
  12 The web page with some information about jsmn can be found at
  13 [http://zserge.com/jsmn.html][3]
  14
  15 Philosophy
  16 ----------
  17
  18 Most JSON parsers offer you a bunch of functions to load JSON data, parse it
  19 and extract any value by its name. jsmn proves that checking the correctness of
  20 every JSON packet or allocating temporary objects to store parsed JSON fields
  21 often is an overkill.
  22
  23 JSON format itself is extremely simple, so why should we complicate it?
  24
  25 jsmn is designed to be  **robust** (it should work fine even with erroneous
  26 data), **fast** (it should parse data on the fly), **portable** (no superfluous
  27 dependencies or non-standard C extensions). An of course, **simplicity** is a
  28 key feature - simple code style, simple algorithm, simple integration into
  29 other projects.
  30
  31 Features
  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
  44 Design
  45 ------
  46
  47 The rudimentary jsmn object is a **token**. Let's consider a JSON string:
  48
  49         '{ "name" : "Jack", "age" : 27 }'
  50
  51 It 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
  57 In jsmn, tokens do not hold any data, but point to token boundaries in JSON
  58 string 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
  61 Every jsmn token has a type, which indicates the type of corresponding JSON
  62 token. 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
  71 Besides start/end positions, jsmn tokens for complex types (like arrays
  72 or objects) also contain a number of child items, so you can easily follow
  73 object hierarchy.
  74
  75 This approach provides enough information for parsing any JSON data and makes
  76 it possible to use zero-copy techniques.
  77
  78 Install
  79 -------
  80
  81 To clone the repository you should have mercurial installed. Just run:
  82
  83         $ hg clone http://bitbucket.org/zserge/jsmn jsmn
  84
  85 Repository layout is simple: jsmn.c and jsmn.h are library files, tests are in
  86 the jsmn\_test.c, you will also find README, LICENSE and Makefile files inside.
  87
  88 To build the library, run `make`. It is also recommended to run `make test`.
  89 Let me know, if some tests fail.
  90
  91 If build was successful, you should get a `libjsmn.a` library.
  92 The header file you should include is called `"jsmn.h"`.
  93
  94 API
  95 ---
  96
  97 Token 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
 107 numbers, booleans and null, because one can easily tell the type using the
 108 first character:
 109
 110 * <code>'t', 'f'</code> - boolean
 111 * <code>'n'</code> - null
 112 * <code>'-', '0'..'9'</code> - number
 113
 114 Token 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
 124 the opening quote and the previous symbol before final quote. This was made
 125 to simplify string extraction from JSON data.
 126
 127 All job is done by `jsmn_parser` object. You can initialize a new parser using:
 128
 129         struct jsmn_parser parser;
 130         jsmntok_t tokens[10];
 131
 132         // js - pointer to JSON string
 133         // tokens - an array of tokens available
 134         // 10 - number of tokens available
 135         jsmn_init_parser(&parser, js, tokens, 10);
 136
 137 This will create a parser, that can parse up to 10 JSON tokens from `js` string.
 138
 139 Later, you can use `jsmn_parse(&parser)` function to process JSON string with the parser.
 140
 141 A non-negative value is the number of tokens actually used by the parser.
 142 Passing NULL instead of the tokens array would not store parsing results, but
 143 instead the function will return the value of tokens needed to parse the given
 144 string. This can be useful if you don't know yet how many tokens to allocate.
 145
 146 If something goes wrong, you will get an error. Error will be one of these:
 147
 148 * `JSMN_ERROR_INVAL` - bad token, JSON string is corrupted
 149 * `JSMN_ERROR_NOMEM` - not enough tokens, JSON string is too large
 150 * `JSMN_ERROR_PART` - JSON string is too short, expecting more JSON data
 151
 152 If you get `JSON_ERROR_NOMEM`, you can re-allocate more tokens and call
 153 `jsmn_parse` once more.  If you read json data from the stream, you can
 154 periodically call `jsmn_parse` and check if return value is `JSON_ERROR_PART`.
 155 You will get this error until you reach the end of JSON data.
 156
 157 Other info
 158 ----------
 159
 160 This software is distributed under [MIT license](http://www.opensource.org/licenses/mit-license.php),
 161  so feel free to integrate it in your commercial products.
 162
 163 [1]: http://www.json.org/
 164 [2]: https://bitbucket.org/zserge/jsmn/wiki/Home
 165 [3]: http://zserge.com/jsmn.html