151 lines
3.5 KiB
Markdown
151 lines
3.5 KiB
Markdown
# tomlc17
|
|
|
|
A lightweight, strictly compliant TOML v1.1 parser for C and C++.
|
|
|
|
## Overview
|
|
|
|
`tomlc17` parses TOML documents into an in-memory tree structure for
|
|
straightforward navigation. It is optimized for clean integration and
|
|
efficient execution, utilizing a single-pass scanner, a dedicated
|
|
string memory pool, and safe recursive teardowns.
|
|
|
|
* **Compliance:** Fully implements TOML v1.1 and passes the standard
|
|
`toml-test` validation suite.
|
|
* **Compatibility:** Written in C17. Fully compatible with C99 and C++.
|
|
* **Modern C++ Support:** Includes dedicated C++20 accessors (see
|
|
`README_CXX.md`).
|
|
* **Zero-Friction Integration:** Amalgamated design. Simply drop
|
|
`tomlc17.h` and `tomlc17.c` into your source tree, or build it as a
|
|
library.
|
|
|
|
## Quick Start
|
|
|
|
For complete API details, refer to [`API.md`](API.md).
|
|
|
|
### Example: Parsing & Extraction
|
|
|
|
Parsing a toml document creates a tree data structure in memory that
|
|
reflects the document. Information can be extracted by navigating this
|
|
data structure.
|
|
|
|
|
|
```c
|
|
/*
|
|
* Parse the config file simple.toml:
|
|
*
|
|
* [server]
|
|
* host = "www.example.com"
|
|
* port = [8080, 8181, 8282]
|
|
*
|
|
*/
|
|
#include "../src/tomlc17.h"
|
|
#include <errno.h>
|
|
#include <inttypes.h>
|
|
#include <stdlib.h>
|
|
#include <string.h>
|
|
|
|
static void error(const char *msg, const char *msg1) {
|
|
fprintf(stderr, "ERROR: %s%s\n", msg, msg1 ? msg1 : "");
|
|
exit(1);
|
|
}
|
|
|
|
int main() {
|
|
// Parse the toml file
|
|
toml_result_t result = toml_parse_file_ex("simple.toml");
|
|
|
|
// Check for parse error
|
|
if (!result.ok) {
|
|
error(result.errmsg, 0);
|
|
}
|
|
|
|
// Extract values
|
|
toml_datum_t host = toml_seek(result.toptab, "server.host");
|
|
toml_datum_t port = toml_seek(result.toptab, "server.port");
|
|
|
|
// Print server.host
|
|
if (host.type != TOML_STRING) {
|
|
error("missing or invalid 'server.host' property in config", 0);
|
|
}
|
|
printf("server.host = %s\n", host.u.s);
|
|
|
|
// Print server.port
|
|
if (port.type != TOML_ARRAY) {
|
|
error("missing or invalid 'server.port' property in config", 0);
|
|
}
|
|
printf("server.port = [");
|
|
for (int i = 0; i < port.u.arr.size; i++) {
|
|
toml_datum_t elem = port.u.arr.elem[i];
|
|
if (elem.type != TOML_INT64) {
|
|
error("server.port element not an integer", 0);
|
|
}
|
|
printf("%s%" PRId64, i ? ", " : "", elem.u.int64);
|
|
}
|
|
printf("]\n");
|
|
|
|
// Done!
|
|
toml_free(result);
|
|
return 0;
|
|
}
|
|
```
|
|
|
|
|
|
## Building
|
|
|
|
For debug build:
|
|
```bash
|
|
export DEBUG=1
|
|
make
|
|
```
|
|
|
|
For release build:
|
|
```bash
|
|
unset DEBUG
|
|
make
|
|
```
|
|
|
|
## Running tests
|
|
|
|
We run the official `toml-test` as described
|
|
[here](https://github.com/toml-lang/toml-test). Refer to
|
|
[this
|
|
section](https://github.com/toml-lang/toml-test?tab=readme-ov-file#installation)
|
|
for prerequisites to run the tests.
|
|
|
|
The following command invokes the tests:
|
|
|
|
```bash
|
|
make test
|
|
```
|
|
|
|
As of May 7, 2025, all tests passed for TOML v1.0:
|
|
|
|
```
|
|
toml-test v0001-01-01 [/home/cktan/p/tomlc17/test/stdtest/driver]: using embedded tests
|
|
valid tests: 185 passed, 0 failed
|
|
invalid tests: 371 passed, 0 failed
|
|
```
|
|
|
|
As of Dec 25, 2025, all tests passed for TOML v1.1:
|
|
|
|
```
|
|
toml-test v0001-01-01 [/home/cktan/p/tomlc17/test/stdtest/driver] [no encoder]
|
|
valid tests: 214 passed, 0 failed
|
|
encoder tests: no encoder command given
|
|
invalid tests: 466 passed, 0 failed
|
|
```
|
|
|
|
## Installing
|
|
|
|
The install command will copy `tomlc17.h`, `tomlcpp.hpp` and
|
|
`libtomlc17.a` to the `$prefix/include` and `$prefix/lib` directories.
|
|
|
|
```bash
|
|
unset DEBUG
|
|
make clean install prefix=/usr/local
|
|
```
|
|
|
|
## Options
|
|
|
|
For information on configuring library options, such as setting custom memory
|
|
allocators, see [`OPTIONS.md`](OPTIONS.md).
|