jsmn/README

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.