https://github.com/zltl/json-gen-c
A program to generate C code for json manipulation
https://github.com/zltl/json-gen-c
c json
Last synced: 4 months ago
JSON representation
A program to generate C code for json manipulation
- Host: GitHub
- URL: https://github.com/zltl/json-gen-c
- Owner: zltl
- License: gpl-3.0
- Created: 2022-03-22T08:18:35.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2025-11-23T16:05:18.000Z (7 months ago)
- Last Synced: 2025-11-23T17:28:44.662Z (7 months ago)
- Topics: c, json
- Language: C
- Homepage: https://zltl.github.io/json-gen-c/
- Size: 2.32 MB
- Stars: 24
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
json-gen-c
---
[](https://github.com/zltl/json-gen-c/actions/workflows/test.yml)
> Fast, tiny, and friendly code generator that turns your C structs into fully featured JSON serializers/deserializers.
## Highlights
- **Schema-first workflow** – describe your structs once, generate battle-tested C code automatically.
- **Zero runtime reflection** – everything happens at compile time, so the generated code stays fast and lean.
- **Thread-safe runtime** – the parsing context uses explicit structures rather than globals.
- **Batteries included** – includes a lightweight `sstr` string helper library and ready-made array helpers.
- **CI-friendly build** – warnings are treated as errors and the Make targets work the same locally and in automation.
## Contents
- [Overview](#overview)
- [Build and Install](#build-and-install)
- [Quick Start](#quick-start)
- [The Format of Structs Definition File](#the-format-of-structs-definition-file)
- [The JSON API](#the-json-api)
- [More Resources](#more-resources)
- [Contributing & Community](#contributing--community)
## Overview
json-gen-c is a program for serializing C structs to JSON and
deserializing JSON to C structs. It parses struct definition files
then generates C code to handle both directions.
- [Document](https://zltl.github.io/json-gen-c/)
## Build and Install
```bash
make
sudo make install
```
The project uses a modern, efficient build system with support for parallel compilation:
```bash
# Parallel build (recommended)
make -j$(nproc)
# Debug build
make debug
# Build with sanitizers
make sanitize
# Show build configuration
make show-config
```
To build example, tests, and benchmarks
```bash
# build ./build/example/example
make example
# build ./build/test/unit_test
make test
# build ./build/benchmark/json_bench
make benchmark
```
All build artifacts are organized under the `build/` directory:
- `build/bin/` - Main executable
- `build/lib/` - Static libraries
- `build/example/` - Example executable
- `build/test/` - Test executables
- `build/benchmark/` - Benchmark executable
## Quick Start
[example](./example/example.json-gen-c)
### Define Structs
For example, create a file name `struct.json-gen-c` as contents below:
```C
struct A {
int int_val1;
int int_val2;
long long_val;
double double_val;
float float_val;
sstr_t sstr_val;
int int_val_array[];
B b_val;
};
struct B {
int id;
};
```
Note that we don't use C-style string `char*`, a more resonable type is
`sstr_t`. You can find more details about `sstr_t` in
[document of sstr](https://zltl.github.io/json-gen-c/sstr_8h.html).
### Compiling Your Struct Definition File
```bash
json-gen-c -in struct.json-gen-c -out .
```
This generates the following files in your specified destination directory:
- `json.gen.h`, the header which declares your generated structures
and functions.
- `json.gen.c`, which contains the implementation of your functions.
- `sstr.h`, `sstr.c`, the string manipulation helper functions that
generated code depends on.
### Use Your Generated Codes
#### To Serialize Structs to JSON
```C
struct A a;
A_init(&a);
// set values to a ...
// ...
sstr_t json_str = sstr_new();
json_marshal_A(&a, json_str);
printf("marshal a to json> %s\n", sstr_cstr(json_str));
sstr_free(json_str);
A_clear(&a);
```
#### To Serialize Array of Structs to JSON
```C
struct A a[3];
for (i = 0; i < 3; ++i) {
A_init(&a[i]);
// set values to a[i] ...
}
sstr_t json_str = sstr_new();
json_marshal_array_A(a, 3, json_str);
printf("marshal a[] to json> %s\n", sstr_cstr(json_str));
for (i = 0; i < 3; ++i) {
A_clear(&a[i]);
}
```
#### To Deserialize JSON to Structs
```C
// const char *p_str = "{this is a json string}";
// sstr_t json_str = sstr(pstr);
struct A a;
A_init(&a);
json_unmarshal_A(json_str, &a); // json_str is a type of sstr_t
// ...
A_clear(&a);
```
#### To Deserialize JSON to Array of Structs
```C
// const char *p_str = "[this is a json string]";
// sstr_t json_str = sstr(pstr);
struct A *a = NULL;
int len = 0;
json_unmarshal_array_A(&a, &len, json_str);
// ...
int i;
for (i = 0; i < len; ++i) {
A_clear(&a[i]);
}
free(a);
```
## Build System
For detailed build system documentation, see [BUILD_SYSTEM.md](BUILD_SYSTEM.md).
If you are new to the project, the friendly walkthrough in [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md) covers installation, schema authoring, and integration.
## The Format of Structs Definition File
Define a struct like:
```
struct {
[]?;
[]?;
...
};
```
The field type can be one of the following:
- `int`
- `long`
- `float`
- `double`
- `sstr_t`
- `bool`
- a struct name
If a field is an array, just append `[]` after the field name.
## The JSON API
```C
// initialize a struct
// always return 0
int _init(struct *obj);
// uninitialize a struct
// always return 0
int _clear(struct *obj);
// marshal a struct to json string.
// return 0 if success.
int json_marshal_(struct *obj, sstr_t out);
// marshal an array of struct to json string.
// return 0 if success.
int json_marshal_array_(struct *obj, int len, sstr_t out);
// unmarshal a json string to a struct.
// return 0 if success.
int json_unmarshal_(sstr_t in, struct *obj);
// unmarshal a json string to array of struct
// return 0 if success.
int json_unmarshal_(sstr_t in, struct **obj, int *len);
```
## More Resources
- [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md) – step-by-step tutorial with code snippets.
- [example/](example/) – real schemas plus sample host programs.
- [Online reference](https://zltl.github.io/json-gen-c/) – API documentation generated via Doxygen.
- [doc/json-gen-c.1](doc/json-gen-c.1) – manual page installed with the CLI.
## Contributing & Community
We welcome issues, ideas, documentation updates, and code contributions.
- Read the [CONTRIBUTING.md](CONTRIBUTING.md) guide for local setup, coding style, and pull-request tips.
- File bugs or feature requests via [GitHub Issues](https://github.com/zltl/json-gen-c/issues) with clear reproduction details.
- Share what you build! Open a discussion or PR if you want your project added to a future showcase section.
Thanks for helping json-gen-c grow. Happy hacking!
## License
Codes of `json-gen-c` are licensed under GPL-3.0, except for the codes it
generated. The copy right of the codes generated by `json-gen-c` is owned
by the user who wrote the struct definition file, same as the copy right of
a PDF file generated by Latex is owned by the user who wrote the tex file.