You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
130 lines
4.0 KiB
130 lines
4.0 KiB
|
|
JSMN
|
|
====
|
|
|
|
jsmn (pronounced like 'jasmine') is a minimalistic JSON parser in C. It can be
|
|
easily integrated into resource-limited or embedded projects.
|
|
|
|
You can find more information on JSON at (http://www.json.org/)
|
|
|
|
Philosophy
|
|
----------
|
|
|
|
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
|
|
is an overkill.
|
|
|
|
JSON format itself is extremely simple, so why should we complicate it?
|
|
|
|
jsmn is designed to be **robust** (it should work fine even with erroneous
|
|
data), **fast** (it should parse data on the fly), **portable** (no unneeded
|
|
dependencies or non-standard C extensions). An of course, **simplicity** is a
|
|
key feature - simple code style, simple algorithm, simple integration.
|
|
|
|
Features
|
|
--------
|
|
|
|
* compatible with C89
|
|
* no dependencies (even libc!)
|
|
* about 200 lines of code
|
|
* extremely small code footprint
|
|
* no dynamic memory allocation
|
|
* incremental single-pass parsing
|
|
* library code is covered with unit-tests
|
|
|
|
Design
|
|
------
|
|
|
|
The rudimentary jsmn object is a **token**.
|
|
|
|
When parsing is done, token objects contain start and end positions of JSON
|
|
token inside the JSON data block. You can just copy a corresponding range of
|
|
bytes and get token value.
|
|
|
|
Another propetry of token is token type. It describes the type of the
|
|
corresponding JSON object.
|
|
|
|
jsmn supports the following token types:
|
|
|
|
* Object - a container of key-value pairs, e.g.:
|
|
`{ "foo":"bar", "x":0.3 }`
|
|
* Array - a sequence of values, e.g.:
|
|
`[ 1, 2, 3 ]`
|
|
* String - a quoted sequence of chars, e.g.: `"foo"`
|
|
* Primitive - a number, a boolean (`true`, `false`) or `null`
|
|
|
|
jsmn doesn't handle specific JSON data types. It just points to the token
|
|
boundaries - you should parse single data fields by your own if you need this.
|
|
|
|
Get sources
|
|
-----------
|
|
|
|
Clone the repository (you should have mercurial installed):
|
|
|
|
$ hg clone http://bitbucket.org/zserge/jsmn jsmn
|
|
|
|
Repository layout it simple: jsmn.c and jsmn.h are library files; demo.c is an
|
|
example of how to use jsmn (it is also used in unit testing); test.sh is a test
|
|
script. You will also find README, LICENSE and Makefile files inside.
|
|
|
|
API
|
|
---
|
|
|
|
Token types are described by `jsontype_t`:
|
|
|
|
typedef enum {
|
|
JSON_OBJECT,
|
|
JSON_ARRAY,
|
|
JSON_STRING,
|
|
JSON_PRIMITIVE
|
|
} jsontype_t;
|
|
|
|
**Note:** primitive tokens are not divided into numbers, booleans and null,
|
|
because one can easily tell the type using the first character:
|
|
|
|
* <code>'t', 'f'</code> - boolean
|
|
* <code>'n'</code> - null
|
|
* <code>'-', '0'..'9'</code> - number
|
|
|
|
Tokens are described with `jsontok_t`:
|
|
|
|
typedef struct {
|
|
jsontype_t type;
|
|
int start;
|
|
int end;
|
|
} jsontok_t;
|
|
|
|
**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.
|
|
|
|
All job is done by `jsmn_parser` object. You can initialize a new parser using:
|
|
|
|
struct jsmn_parser parser;
|
|
jsmntok_t tokens[10];
|
|
|
|
jsmn_init_parser(&parser, js, &tokens, 10);
|
|
|
|
This will create a parser, that can parse up to 10 JSON tokens from `js` string.
|
|
|
|
Later, you can use `jsmn_parse(&parser)` function to process JSON string with the parser.
|
|
It something goes wrong, you will return an error. Error will be one of these:
|
|
|
|
* `JSON_SUCCESS` - everything went fine. String was parsed
|
|
* `JSON_ERROR_INVAL` - bad token, JSON string is corrupted
|
|
* `JSON_ERROR_NOMEM` - not enough tokens, JSON string is too large
|
|
* `JSON_ERROR_PART` - JSON string is too short, it doesn't contain the whole JSON data
|
|
|
|
If you get `JSON_ERROR_NOMEM`, you can allocate more tokens and call `jsmn_parse` once more.
|
|
If you read json data from the stream, you can call jsmn_parse and check if
|
|
return value is `JSON_ERROR_PART` to see if you have reached the end of JSON
|
|
data.
|
|
|
|
Other info
|
|
----------
|
|
|
|
This software is distributed under [MIT license](http://www.opensource.org/licenses/mit-license.php),
|
|
so feel free to integrate it in your commercial products.
|
|
|