json4c

KO | EN

gitlite — search

#golang #android #rust #deep-learning #linux #nodejs #windows #awesome #awesome-list #vue #pytorch #ios #mcp #openai

(★ 10)

A simple, flexible JSON parser written in pure C99.

json4c Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

JSON4C
======

**WARNING**: This library does not yet support characters in strings outside of the ASCII range.

A simple, flexible JSON library written in pure C99.

## Building

JSON4C is a unity build for ease of use. The only files you need to worry about are `json.h` and `json.c`, the rest exist only for orginization purposes.

1. Copy `src` to your project.
2. Rename `src` to something like `json4c`.
3. `#include "json4c\json.h"` when you want to use the library.
4. Add `json4c\json.c` to your compilation process.

## Examples

### Types

The main type used by this library is `JsonNode`, it is used to represent the JSON tree. Below is its definition.

~~~c
typedef struct JsonNode {
	char* identifier;
	struct {
		JsonType type;
		union {
			int64_t integer;
			double real;
			bool boolean;
			char* string;
			struct {
				struct JsonNode** nodes;
				ptrdiff_t max;
				ptrdiff_t count;
			} jcomplex;
		};
	} value;
} JsonNode;
~~~

`JsonType` is a simple enum used for denoting what value the union represents, it is defined as:

~~~c
typedef enum {
	JSON_ERROR,
	JSON_OBJECT,
	JSON_ARRAY,
	JSON_INT,
	JSON_REAL,
	JSON_STRING,
	JSON_BOOL,
	JSON_NULL
} JsonType;
~~~

### Parsing

There are two functions provided for parsing JSON, `json_parse` and `json_parseFile`, below are their signatures.

~~~c
JsonNode* json_parse(char* buffer, ptrdiff_t length);
JsonNode* json_parseFile(char* path);
~~~

To extract data from a `JsonNode*` the library provides three functions, and some helper macros for type checking and casting.

~~~c
JsonNode* json_property(JsonNode* node, char* propertyName);
JsonNode* json_index(JsonNode* node, int index);
/*
	json_get is a combination of the other two functions,
	the call json_get(node, "friends", 0) roughly translates
	to json_index(json_property(node, "friends"), 0). In other
	words, json_get allows you to traverse the JSON tree in one go.
*/
JsonNode* json_get(JsonNode* node, ...);

// The helper macros are:
IS_INT(node)	AS_INT(node)
IS_REAL(node)	AS_REAL(node)
IS_STRING(node)	AS_STRING(node)
IS_BOOL(node) 	AS_BOOL(node)
IS_NULL(node) 	AS_ARRAY(node)
IS_ARRAY(node) 	AS_OBJECT(node)
IS_OBJECT(node)
IS_ERROR(node) 	
~~~

#### Usage

Here is an example of the different ways you can parse JSON and fetch data from the nodes.

~~~c
#include <stdio.h>
#include <string.h>
#include "json4c/json.h"

int main(int argc, char* argv[]) {
	if (argc < 2) return 1;
	
	// Using json_parse to parse a buffer of bytes/characters, and json_property to select a field.
	JsonNode* person = json_parse(argv[1], strlen(argv[1])); // { "name": "Lucas", "age": 34 }
	JsonNode* age = json_property(person, "age");
	printf("age = %d\n", AS_INT(age)); // Outputs "age = 34"
    json_node_free(person);
	
	// Using json_parseFile to parse JSON data, then json_index to get the data at an index.
	JsonNode* primes = json_parseFile("testdata/primes.json"); // [ 1, 3, 5, 7, 11, 13, 17, 23 ]
	JsonNode* five = json_index(primes, 2);
	printf("the third prime number is %d\n", AS_INT(five));
    json_node_free(primes);
	
	/*
		testdata/house.json:
		{
			"number": 305,
			"price": 432000,
			"rooms": 11,
			"baths": 2.5,
			"bedrooms": 3,
			"owners": [
				"Joshua Davison",
				"Wendy Whitley",
				"Carrol Gretchen"
			]
		}
	*/
	// Using json_parseFile to parse JSON data, the json_get to traverse the JSON tree.
	JsonNode* house = json_parseFile("testdata/house.json");
	// json_get(house, "owners", 2) is equivalent to json_index(json_property(house, "owners"), 2)
	JsonNode* carrolGretchen = json_get(house, "owners", 2);
	printf("the third owner of the house was %s", AS_STRING(carrolGretchen));
    json_node_free(house);

return 0;
}
~~~

### Serialization

There are a handful of functions the library provides for serialization. Below are their signatures.

~~~c
// Creating
JsonNode* json_object(void**);
JsonNode* json_emptyObject(void);
JsonNode* json_array(JsonNode**);
JsonNode* json_emptyArray(void);
JsonNode* json_bool(bool);
JsonNode* json_int(int);
JsonNode* json_real(double);
JsonNode* json_null(void);
JsonNode* json_string(char*);

// Writing
bool json_write(JsonNode* node, char* buffer, ptrdiff_t length, enum JsonWriteOption option);
void json_writeFile(JsonNode* node, char* path, enum JsonWriteOption option);
// NOTE: You are responsible for freeing the char* returned by these functions.
char* json_toBuffer(JsonNode* node, ptrdiff_t* length, ptrdiff_t* offset, enum JsonWriteOption option);
char* json_toString(JsonNode* node, enum JsonWriteOption option);
~~~

`enum JsonWriteOption` is defined as:

~~~c
enum JsonWriteOption {
	JSON_WRITE_PRETTY,
	JSON_WRITE_CONDENSED
};
~~~

`JSON_WRITE_PRETTY` adds whitespace characters and newlines to the written JSON, while `JSON_WRITE_CONDENSED` doesn't.

#### Usage

Here is an example of creating a JSON tree and writing it to the `data/test.json` file.

~~~c
#include <stdio.h>
#include "json4c/json.h"

int main(void) {
	/*
		The file created:
		{
			"test_status": "passing",
			"tests_passed": 123,
			"tests_failed": 0,
			"test_name": null,
			"files_tested": [
				"foo.xyz",
				"bar.xyz",
				"bazz.xyz"
			],
			"test_history": []
		}
	*/
	JsonNode* rootObject = json_object(
		"test_status", json_string("passing"),
		"tests_passed", json_int(123),
		"tests_failed", json_int(0),
		"test_name", json_null(),
		"files_tested", json_array(
			json_string("foo.xyz"),
			json_string("bar.xyz"),
			json_string("bazz.xyz")
		),
		"test_history", json_emptyArray()
	);
	json_writeFile("data/test.json", rootObject, JSON_WRITE_PRETTY);
	json_node_free(rootObject);
	return 0;
}
~~~

## Customization

### Macros

Below are all some of the macros the library uses that can be overidden by the user to suite their own needs.

~~~c
#define JSON_DEBUG
#define JSON_DYNAMIC_ARRAY_CAPACITY 16
#define JSON_DYNAMIC_ARRAY_GROW_BY 2
#define JSON_BUFFER_CAPACITY 256
#define JSON_MAX_ERRORS_RECORDED 64
~~~

Just use `-D` when compiling, e. `-D JSON_DEBUG -D JSON_DYNAMIC_ARRAY_GROW_BY=4`.

### Custom Allocators

If you want the library to use a custom allocator, you can use the `json_setAllocator` function.

~~~c
#include "json.h"
#include "your_allocator.h"

/*
	NOTE: 
	To support all kinds of custom allocators, the signatures for the
	allocator functions differ from you might expect. They are as follows:
	
	void* (*custom_alloc)(ptrdiff_t size, void* instanceptr);
	void (*custom_free)(void* ptr, ptrdiff_t size, void* instanceptr);
	void* (*custom_realloc)(void* ptr, ptrdiff_t newSize, ptrdiff_t oldSize, void* instanceptr);
*/

int main(void) {
	// NOTE: All arguments to json_setAllocator can be NULL except custom_alloc,
	// it is obviously recommended to supply a free function though.
	json_setAllocator(custom_alloc, custom_free, custom_realloc, custom_instance);
	JsonNode* jnode = json_parseFile("data\\foo.json"); // Allocated with custom_alloc
	json_node_free(jnode); // Freed with custom_free
	return 0;
}
~~~

Just make sure to set the allocator before any JSON allocations are made, and don't change it before all are freed.

## Error Handling

All errors that occur while parsing/serializing data are recorded to an internal error stack.
Some can be recovered from by the user of the library, for example checking if functions that return pointers returned NULL.
Some errors however are considered 'critical', like running out of memory.
The `json_error` API provided three 'events' (just global function pointers) that you can assign to functions that gracefully exit your program.
The function pointer globals are:

~~~c
extern void (*json_error_onErrorReported)(char* errorMsg);
extern void (*json_error_onCriticalErrorReported)(char* errorMsg);
extern void (*json_error_onMaxErrors)(void);
~~~

Still confused? Here is how to take advantage of them.

~~~c
#include <stdio.h>
#include "json4c/json.h"

#define YOUR_EXIT_CODE 1

void onJsonError(char* errorMsg) {
	fputs(errorMsg, stderr);
}

void onCriticalJsonError(char* errorMsg) {
	// We could just print errorMsg, but there is a better option.
	(void)errorMsg;
	json_error_printAll(stderr); // This includes errorMsg
	exit(YOUR_EXIT_CODE);
}

void configureLibraries(void) {
	json_error_onErrorReported = onJsonError;
	json_error_onCriticalErrorReported = onCriticalJsonError;
}

int main(int argc, char* argv[]) {
	if (argc < 2) return 1;
	
	configureLibraries();
	// If we ran out of memory parsing, onCriticalJsonError would be called.
	JsonNode* node = json_parse(argv[1]);
	
	if (IS_ERROR(node)) {
		// The buffer contained invalid data, onJsonError would have been called during the parse.
	} else {
		// Successful parse.
	}
	
	json_node_free(node);
	
	return 0;
}
~~~

json4c

json4c Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

json4c

json4c Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README