Home | History | Annotate | only in /external/jsmn
Up to higher level directory
NameDateSize
Android.mk23-Apr-2015769
jsmn.c23-Apr-20157.3K
jsmn.h23-Apr-20151.6K
jsmn_test.c23-Apr-201516.6K
LICENSE23-Apr-20151K
Makefile23-Apr-2015385
MODULE_LICENSE_MIT23-Apr-20150
NOTICE23-Apr-20151K
README.md23-Apr-20155K

README.md

      1 JSMN
      2 jsmn (pronounced like 'jasmine') is a minimalistic JSON parser in C. It can be easily integrated into resource-limited or embedded projects.
      3 You can find more information about JSON format at json.org
      4 Library sources are available at bitbucket.org/zserge/jsmn
      5 The web page with some information about jsmn can be found at http://zserge.com/jsmn.html
      6 Philosophy
      7 Most JSON parsers offer you a bunch of functions to load JSON data, parse it and extract any value by its name. jsmn proves that checking the correctness of every JSON packet or allocating temporary objects to store parsed JSON fields often is an overkill.
      8 JSON format itself is extremely simple, so why should we complicate it?
      9 jsmn is designed to be robust (it should work fine even with erroneous data), fast (it should parse data on the fly), portable (no superfluous dependencies or non-standard C extensions). An of course, simplicity is a key feature - simple code style, simple algorithm, simple integration into other projects.
     10 Features
     11 compatible with C89
     12 no dependencies (even libc!)
     13 highly portable (tested on x86/amd64, ARM, AVR)
     14 about 200 lines of code
     15 extremely small code footprint
     16 API contains only 2 functions
     17 no dynamic memory allocation
     18 incremental single-pass parsing
     19 library code is covered with unit-tests
     20 Design
     21 The rudimentary jsmn object is a token. Let's consider a JSON string:
     22 '{ "name" : "Jack", "age" : 27 }'
     23 It holds the following tokens:
     24 Object: { "name" : "Jack", "age" : 27} (the whole object)
     25 Strings: "name", "Jack", "age" (keys and some values)
     26 Number: 27
     27 In jsmn, tokens do not hold any data, but point to token boundaries in JSON string instead. In the example above jsmn will create tokens like: Object [0..31], String [3..7], String [12..16], String [20..23], Number [27..29].
     28 Every jsmn token has a type, which indicates the type of corresponding JSON token. jsmn supports the following token types:
     29 Object - a container of key-value pairs, e.g.: { "foo":"bar", "x":0.3 }
     30 Array - a sequence of values, e.g.: [ 1, 2, 3 ]
     31 String - a quoted sequence of chars, e.g.: "foo"
     32 Primitive - a number, a boolean (true, false) or null
     33 Besides start/end positions, jsmn tokens for complex types (like arrays or objects) also contain a number of child items, so you can easily follow object hierarchy.
     34 This approach provides enough information for parsing any JSON data and makes it possible to use zero-copy techniques.
     35 Install
     36 To clone the repository you should have mercurial installed. Just run:
     37 $ hg clone http://bitbucket.org/zserge/jsmn jsmn
     38 Repository layout is simple: jsmn.c and jsmn.h are library files, tests are in the jsmn_test.c, you will also find README, LICENSE and Makefile files inside.
     39 To build the library, run make. It is also recommended to run make test. Let me know, if some tests fail.
     40 If build was successful, you should get a libjsmn.a library. The header file you should include is called "jsmn.h".
     41 API
     42 Token types are described by jsmntype_t:
     43 typedef enum {
     44     JSMN_PRIMITIVE = 0,
     45     JSMN_OBJECT = 1,
     46     JSMN_ARRAY = 2,
     47     JSMN_STRING = 3
     48 } jsmntype_t;
     49 Note: Unlike JSON data types, primitive tokens are not divided into numbers, booleans and null, because one can easily tell the type using the first character:
     50 <code>'t', 'f'</code> - boolean
     51 <code>'n'</code> - null
     52 <code>'-', '0'..'9'</code> - number
     53 Token is an object of jsmntok_t type:
     54 typedef struct {
     55     jsmntype_t type; // Token type
     56     int start;       // Token start position
     57     int end;         // Token end position
     58     int size;        // Number of child (nested) tokens
     59 } jsmntok_t;
     60 Note: string tokens point to the first character after the opening quote and the previous symbol before final quote. This was made to simplify string extraction from JSON data.
     61 All job is done by jsmn_parser object. You can initialize a new parser using:
     62 struct jsmn_parser parser;
     63 jsmntok_t tokens[10];
     64 
     65 // js - pointer to JSON string
     66 // tokens - an array of tokens available
     67 // 10 - number of tokens available
     68 jsmn_init_parser(&parser, js, tokens, 10);
     69 This will create a parser, that can parse up to 10 JSON tokens from js string.
     70 Later, you can use jsmn_parse(&parser) function to process JSON string with the parser.
     71 A non-negative value is the number of tokens actually used by the parser. Passing NULL instead of the tokens array would not store parsing results, but instead the function will return the value of tokens needed to parse the given string. This can be useful if you don't know yet how many tokens to allocate.
     72 If something goes wrong, you will get an error. Error will be one of these:
     73 JSMN_ERROR_INVAL - bad token, JSON string is corrupted
     74 JSMN_ERROR_NOMEM - not enough tokens, JSON string is too large
     75 JSMN_ERROR_PART - JSON string is too short, expecting more JSON data
     76 If you get JSON_ERROR_NOMEM, you can re-allocate more tokens and call jsmn_parse once more. If you read json data from the stream, you can periodically call jsmn_parse and check if return value is JSON_ERROR_PART. You will get this error until you reach the end of JSON data.
     77 Other info
     78 This software is distributed under MIT license, so feel free to integrate it in your commercial products.
     79