contrib/ntp/libjsmn/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         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
 139 This will create a parser, and then it tries to parse up to 10 JSON tokens from
 140 the `js` string.
 141
 142 A non-negative reutrn value of `jsmn_parse` is the number of tokens actually
 143 used by the parser.
 144 Passing NULL instead of the tokens array would not store parsing results, but
 145 instead the function will return the value of tokens needed to parse the given
 146 string. This can be useful if you don't know yet how many tokens to allocate.
 147
 148 If 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
 154 If 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
 156 periodically call `jsmn_parse` and check if return value is `JSON_ERROR_PART`.
 157 You will get this error until you reach the end of JSON data.
 158
 159 Other info
 160 ----------
 161
 162 This 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