Repository files navigation

jsmn (pronounced like 'jasmine') is a minimalistic JSON parser in C. It can beeasily integrated into resource-limited or embedded projects.

You can find more information about JSON format atjson.org

Library sources are available athttps://github.com/zserge/jsmn

The web page with some information about jsmn can be found athttp://zserge.com/jsmn.html

Most JSON parsers offer you a bunch of functions to load JSON data, parse itand extract any value by its name. jsmn proves that checking the correctness ofevery JSON packet or allocating temporary objects to store parsed JSON fieldsoften is an overkill.

JSON format itself is extremely simple, so why should we complicate it?

jsmn is designed to berobust (it should work fine even with erroneousdata),fast (it should parse data on the fly),portable (no superfluousdependencies or non-standard C extensions). And of course,simplicity is akey feature - simple code style, simple algorithm, simple integration intoother projects.

• compatible with C89
• no dependencies (even libc!)
• highly portable (tested on x86/amd64, ARM, AVR)
• about 200 lines of code
• extremely small code footprint
• API contains only 2 functions
• no dynamic memory allocation
• incremental single-pass parsing
• library code is covered with unit-tests

The rudimentary jsmn object is atoken. Let's consider a JSON string:

'{ "name" : "Jack", "age" : 27 }'

It holds the following tokens:

• Object:{ "name" : "Jack", "age" : 27} (the whole object)
• Strings:"name","Jack","age" (keys and some values)
• Number:27

In jsmn, tokens do not hold any data, but point to token boundaries in JSONstring 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].

Every jsmn token has a type, which indicates the type of corresponding JSONtoken. 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) ornull

Besides start/end positions, jsmn tokens for complex types (like arraysor objects) also contain a number of child items, so you can easily followobject hierarchy.

This approach provides enough information for parsing any JSON data and makesit possible to use zero-copy techniques.

Downloadjsmn.h, include it, done.

#include "jsmn.h"...jsmn_parser p;jsmntok_t t[128]; /* We expect no more than 128 JSON tokens */jsmn_init(&p);r = jsmn_parse(&p, s, strlen(s), t, 128); // "s" is the char array holding the json content

Since jsmn is a single-header, header-only library, for more complex use casesyou might need to define additional macros.#define JSMN_STATIC hides alljsmn API symbols by making them static. Also, if you want to includejsmn.hfrom multiple C files, to avoid duplication of symbols you may defineJSMN_HEADER macro.

/* In every .c file that uses jsmn include only declarations: */#define JSMN_HEADER#include "jsmn.h"/* Additionally, create one jsmn.c file for jsmn implementation: */#include "jsmn.h"

Token types are described byjsmntype_t:

typedef enum {JSMN_UNDEFINED = 0,JSMN_OBJECT = 1 << 0,JSMN_ARRAY = 1 << 1,JSMN_STRING = 1 << 2,JSMN_PRIMITIVE = 1 << 3} jsmntype_t;

Note: Unlike JSON data types, primitive tokens are not divided intonumbers, booleans and null, because one can easily tell the type using thefirst character:

• 't', 'f' - boolean
• 'n' - null
• '-', '0'..'9' - number

Token is an object ofjsmntok_t type:

typedef struct {jsmntype_t type; // Token typeint start;       // Token start positionint end;         // Token end positionint size;        // Number of child (nested) tokens} jsmntok_t;

Note: string tokens point to the first character afterthe opening quote and the previous symbol before final quote. This was madeto simplify string extraction from JSON data.

All job is done byjsmn_parser object. You can initialize a new parser using:

jsmn_parser parser;jsmntok_t tokens[10];jsmn_init(&parser);// js - pointer to JSON string// tokens - an array of tokens available// 10 - number of tokens availablejsmn_parse(&parser, js, strlen(js), tokens, 10);

This will create a parser, and then it tries to parse up to 10 JSON tokens fromthejs string.

A non-negative return value ofjsmn_parse is the number of tokens actuallyused by the parser.Passing NULL instead of the tokens array would not store parsing results, butinstead the function will return the number of tokens needed to parse the givenstring. This can be useful if you don't know yet how many tokens to allocate.

If something goes wrong, you will get an error. Error will be one of these:

• JSMN_ERROR_INVAL - bad token, JSON string is corrupted
• JSMN_ERROR_NOMEM - not enough tokens, JSON string is too large
• JSMN_ERROR_PART - JSON string is too short, expecting more JSON data

If you getJSMN_ERROR_NOMEM, you can re-allocate more tokens and calljsmn_parse once more. If you read json data from the stream, you canperiodically calljsmn_parse and check if return value isJSMN_ERROR_PART.You will get this error until you reach the end of JSON data.

This software is distributed underMIT license,so feel free to integrate it in your commercial products.