add config support

2026-07-30 13:18:41 +02:00
parent 215ed9705e
commit dc1aa5e5b6
124 changed files with 7402 additions and 8 deletions
@@ -0,0 +1,150 @@
+# 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).