### Install tomlc17 Library

Source: https://github.com/cktan/tomlc17/blob/main/README.md

Installs the tomlc17 header and library files to the specified prefix. Ensure the DEBUG environment variable is unset for a release installation.

```bash
unset DEBUG
make clean install prefix=/usr/local
```

--------------------------------

### Configure Global TOML Options with C API

Source: https://context7.com/cktan/tomlc17/llms.txt

Use `toml_default_option` to get default settings and `toml_set_option` to apply custom configurations like UTF-8 validation and memory allocators. This must be called once during program initialization and is not thread-safe.

```c
#include "tomlc17.h"
#include <stdlib.h>
#include <stdio.h>
#include <string.h>

// Custom allocator example (wrapping system malloc/realloc/free)
static size_t total_allocated = 0;

static void *my_realloc(void *ptr, size_t size) {
    total_allocated += size;
    return realloc(ptr, size);
}

static void my_free(void *ptr) {
    free(ptr);
}

int main() {
    // Retrieve defaults, then override specific fields
    toml_option_t opt = toml_default_option();
    opt.check_utf8   = true;       // enable strict UTF-8 validation
    opt.mem_realloc  = my_realloc; // custom allocator
    opt.mem_free     = my_free;    // custom free
    toml_set_option(opt);          // applies to all subsequent parse calls

    const char *src = "name = \"héllo\"\n";  // valid UTF-8
    toml_result_t result = toml_parse(src, strlen(src));
    if (!result.ok) {
        fprintf(stderr, "error: %s\n", result.errmsg);
    } else {
        toml_datum_t name = toml_get(result.toptab, "name");
        printf("name = %s\n", name.u.s);  // name = héllo
    }
    toml_free(result);
    printf("total bytes allocated via custom allocator: %zu\n", total_allocated);
    return 0;
}
```

--------------------------------

### Get Default TOML Options with `toml_default_option`

Source: https://github.com/cktan/tomlc17/blob/main/API.md

Retrieve the current default parsing options. This is useful as a starting point before modifying specific fields for custom configurations.

```c
toml_option_t toml_default_option(void);
```

--------------------------------

### Parse TOML file and access values in C++

Source: https://github.com/cktan/tomlc17/blob/main/README_CXX.md

Demonstrates parsing a TOML file and accessing string and integer vector values using `get()` and `seek()` methods. Includes error handling for missing or invalid properties. Ensure the TOML file exists and has the expected structure.

```cpp
/*
 * Parse the config file simple.toml:
 *
 * [server]
 * host = "www.example.com"
 * port = [8080, 8181, 8282]
 *
 */
#include "../src/tomlcpp.hpp"
#include <iostream>
#include <vector>

using std::cout;

static void error(const char *msg) {
  fprintf(stderr, "ERROR: %s\n", msg);
  exit(1);
}

int main() {
  // Parse the toml file
  toml::Result result = toml::parse_file_ex("simple.toml");

  // Check for parse error
  if (!result.ok()) {
    error(result.errmsg());
  }

  // Extract values
  std::string host;
  std::vector<int64_t> port;

  try {
    // use the Datum::get() method
    host = result.get({"server", "host"})->as_str().value();
  } catch (const std::bad_optional_access &ex) {
    error("missing or invalid 'server.host' property in config");
  }

  try {
    // use the Datum::seek() method
    port = result.seek("server.port")->as_intvec().value();
  } catch (const std::bad_optional_access &ex) {
    error("missing or invalid 'server.port' property in config");
  }

  // Print values
  cout << "server.host = " << host << "\n";
  cout << "server.port = [";
  for (size_t i = 0; i < port.size(); i++) {
    cout << (i ? ", " : "") << port[i];
  }
  cout << "]\n";

  // Done! No need to call toml_free(). Result::~Result() will handle destruction.
  return 0;
}

```

--------------------------------

### toml_seek

Source: https://github.com/cktan/tomlc17/blob/main/API.md

Looks up a dot-separated key path starting from a given table. Returns TOML_UNKNOWN if any component is not found.

```APIDOC
## toml_seek

### Description
Look up a dot-separated key path starting from `table`. For example, `"server.host"` is equivalent to calling `toml_get` twice.

### Constraints
- Keys must not contain escape characters.
- The total length of `multipart_key` must not exceed 255 bytes.

### Returns
A datum with `type == TOML_UNKNOWN` if any component is not found.
```

--------------------------------

### toml_seek

Source: https://context7.com/cktan/tomlc17/llms.txt

Traverses a dot-separated key path from a starting table to retrieve a TOML value. This is equivalent to calling `toml_get()` repeatedly for each component of the path. Keys in the path must not contain escape characters, and the path itself must not exceed 255 bytes.

```APIDOC
## `toml_seek` — Dot-separated key path lookup

### Description
Traverses a dot-separated key path from a starting table, equivalent to calling `toml_get()` repeatedly for each component. Keys must not contain escape characters and the path must not exceed 255 bytes.

### Parameters
- `result.toptab` (toml_table_t*): The starting table to search within.
- `path` (const char*): The dot-separated key path to look up.

### Returns
- `toml_datum_t`: A structure containing the type and value of the found TOML element. If the path is not found, `type` will be `TOML_UNKNOWN`.
```

--------------------------------

### Parse TOML from String using toml_parse

Source: https://context7.com/cktan/tomlc17/llms.txt

Parses a TOML document from a NUL-terminated string. Ensure to call `toml_free()` on the result. This example demonstrates parsing and seeking specific values.

```c
#include "tomlc17.h"
#include <string.h>
#include <stdio.h>

int main() {
    const char *src =
        "title = \"My App\"\n"
        "\n"
        "[database]\n"
        "host    = \"localhost\"\n"
        "port    = 5432\n"
        "enabled = true\n";

    toml_result_t result = toml_parse(src, strlen(src));
    if (!result.ok) {
        fprintf(stderr, "parse error: %s\n", result.errmsg);
        toml_free(result);
        return 1;
    }

    toml_datum_t title = toml_seek(result.toptab, "title");
    toml_datum_t host  = toml_seek(result.toptab, "database.host");
    toml_datum_t port  = toml_seek(result.toptab, "database.port");

    printf("title = %s\n", title.u.s);         // title = My App
    printf("host  = %s\n", host.u.s);          // host  = localhost
    printf("port  = %\" PRId64 "\n", port.u.int64); // port  = 5432

    toml_free(result);
    return 0;
}
```

--------------------------------

### Get Value from TOML Table

Source: https://github.com/cktan/tomlc17/blob/main/API.md

Looks up a single key within a TOML table. Returns a datum with type TOML_UNKNOWN if the key is not found or the input is not a table.

```c
toml_datum_t toml_get(toml_datum_t table, const char *key);
```

--------------------------------

### toml_datum_t Structure and Inspection

Source: https://context7.com/cktan/tomlc17/llms.txt

Represents a node in the TOML parse tree. Use `toml_free()` to release memory. This example shows how to inspect different datum types and access their union fields.

```c
#include "tomlc17.h"
#include <inttypes.h>
#include <stdio.h>

// Given a parsed result, inspect a datum's type and access its union fields:
void inspect_datum(toml_datum_t d) {
    switch (d.type) {
    case TOML_STRING:
        printf("string: %s (len=%d)\n", d.u.s, d.u.str.len);
        break;
    case TOML_INT64:
        printf("int64: %\" PRId64 "\n", d.u.int64);
        break;
    case TOML_FP64:
        printf("fp64: %f\n", d.u.fp64);
        break;
    case TOML_BOOLEAN:
        printf("bool: %s\n", d.u.boolean ? "true" : "false");
        break;
    case TOML_DATE:
        printf("date: %d-%02d-%02d\n", d.u.ts.year, d.u.ts.month, d.u.ts.day);
        break;
    case TOML_TIME:
        printf("time: %02d:%02d:%02d.%06d\n",
               d.u.ts.hour, d.u.ts.minute, d.u.ts.second, d.u.ts.usec);
        break;
    case TOML_DATETIMETZ:
        printf("datetimetz: %d-%02d-%02dT%02d:%02d:%02d tz=%+d min\n",
               d.u.ts.year, d.u.ts.month, d.u.ts.day,
               d.u.ts.hour, d.u.ts.minute, d.u.ts.second, d.u.ts.tz);
        break;
    case TOML_ARRAY:
        printf("array with %d elements\n", d.u.arr.size);
        break;
    case TOML_TABLE:
        printf("table with %d keys\n", d.u.tab.size);
        for (int i = 0; i < d.u.tab.size; i++) {
            printf("  key[%d] = %s\n", i, d.u.tab.key[i]);
        }
        break;
    case TOML_UNKNOWN:
        printf("not found\n");
        break;
    }
}
```

--------------------------------

### Define a multi-step task plan

Source: https://github.com/cktan/tomlc17/blob/main/CLAUDE.md

When working on multi-step tasks, outline a brief plan with clear verification steps for each stage. This helps in defining success criteria and looping until verified.

```markdown
1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]
```

--------------------------------

### Parse TOML File and Extract Data in C

Source: https://github.com/cktan/tomlc17/blob/main/README.md

Demonstrates parsing a TOML file and extracting string and array values. Ensure the TOML file exists and has the expected structure. Error handling for missing or invalid properties is included.

```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;
}

```

--------------------------------

### Run tomlc17 Tests

Source: https://github.com/cktan/tomlc17/blob/main/README.md

Executes the official toml-test suite against the library. Ensure prerequisites for toml-test are met.

```bash
make test
```

--------------------------------

### Parse TOML from a file path

Source: https://context7.com/cktan/tomlc17/llms.txt

Use `toml_parse_file_ex` for the simplest way to parse a TOML file directly from its path. This function handles opening, reading, and closing the file internally.

```c
#include "tomlc17.h"
#include <stdio.h>
#include <inttypes.h>

// TOML file: simple.toml
// [server]
// host = "www.example.com"
// port = [8080, 8181, 8282]

int main() {
    toml_result_t result = toml_parse_file_ex("simple.toml");
    if (!result.ok) {
        fprintf(stderr, "ERROR: %s\n", result.errmsg);
        toml_free(result);
        return 1;
    }

    toml_datum_t host = toml_seek(result.toptab, "server.host");
    toml_datum_t port = toml_seek(result.toptab, "server.port");

    if (host.type != TOML_STRING) { fprintf(stderr, "missing server.host\n"); goto done; }
    if (port.type != TOML_ARRAY)  { fprintf(stderr, "missing server.port\n"); goto done; }

    printf("server.host = %s\n", host.u.s);
    printf("server.port = [");
    for (int i = 0; i < port.u.arr.size; i++) {
        printf("%s%" PRId64, i ? ", " : "", port.u.arr.elem[i].u.int64);
    }
    printf("]\n");
    // Output:
    // server.host = www.example.com
    // server.port = [8080, 8181, 8282]

done:
    toml_free(result);
    return 0;
}
```

--------------------------------

### `toml_set_option` / `toml_default_option` — Global configuration

Source: https://context7.com/cktan/tomlc17/llms.txt

Configures UTF-8 validation and a custom memory allocator. This function should be called once during program initialization and is not thread-safe.

```APIDOC
## `toml_set_option` / `toml_default_option` — Global configuration

Configures UTF-8 validation and a custom memory allocator. Call once during program initialization; not thread-safe.

### Description

Allows setting global options for TOML parsing, such as enabling strict UTF-8 validation and providing a custom memory allocation strategy.

### Usage

```c
#include "tomlc17.h"

toml_option_t opt = toml_default_option();
opt.check_utf8 = true;       // enable strict UTF-8 validation
opt.mem_realloc = my_realloc; // custom allocator
opt.mem_free = my_free;    // custom free
toml_set_option(opt);          // applies to all subsequent parse calls
```

### Parameters

- `opt` (toml_option_t) - A structure containing configuration options:
  - `check_utf8` (bool) - If true, enables strict UTF-8 validation.
  - `mem_realloc` (void* (*)(void*, size_t)) - Pointer to a custom reallocation function.
  - `mem_free` (void (*)(void*)) - Pointer to a custom free function.

### Note

This function is not thread-safe and should be called only once during program initialization.
```

--------------------------------

### Build Debug Version of tomlc17

Source: https://github.com/cktan/tomlc17/blob/main/README.md

Builds the library with debug symbols enabled. Set the DEBUG environment variable before running make.

```bash
export DEBUG=1
make
```

--------------------------------

### Include tomlc17 Header

Source: https://github.com/cktan/tomlc17/blob/main/API.md

Include the main header file for the tomlc17 library before using any of its functions.

```c
#include "tomlc17.h"
```

--------------------------------

### TOML Option Structure

Source: https://github.com/cktan/tomlc17/blob/main/API.md

Structure for configuring global parsing options, such as UTF-8 validation and custom memory allocators.

```c
struct toml_option_t {
  bool check_utf8;
  void *(*mem_realloc)(void *ptr, size_t);
  void (*mem_free)(void *ptr);
};
```

--------------------------------

### Build Release Version of tomlc17

Source: https://github.com/cktan/tomlc17/blob/main/README.md

Builds the library without debug symbols. Unset the DEBUG environment variable before running make.

```bash
unset DEBUG
make
```

--------------------------------

### Find TOML Table Entry with `toml_table_find` (Deprecated)

Source: https://github.com/cktan/tomlc17/blob/main/API.md

This function is an alias for `toml_get()` and is deprecated. Use `toml_get()` for finding table entries.

```c
toml_datum_t toml_table_find(toml_datum_t table, const char *key);
```

--------------------------------

### Set Global TOML Options with `toml_set_option`

Source: https://github.com/cktan/tomlc17/blob/main/API.md

Replace the global TOML parsing options. This change affects all subsequent parse calls and should be done once during program initialization as it is not thread-safe.

```c
void toml_set_option(toml_option_t opt);
```

```c
toml_option_t opt = toml_default_option();
opt.mem_realloc = my_realloc;
opt.mem_free    = my_free;
toml_set_option(opt);
```

--------------------------------

### Lookup single key in a TOML table

Source: https://context7.com/cktan/tomlc17/llms.txt

Use `toml_get` to retrieve a specific key's datum from a `TOML_TABLE`. If the key is not found or the input is not a table, a datum with `type == TOML_UNKNOWN` is returned.

```c
#include "tomlc17.h"
#include <string.h>
#include <stdio.h>

int main() {
    const char *src =
        "[owner]\n"
        "name = \"Tom\"\n"
        "age  = 42\n";

    toml_result_t result = toml_parse(src, strlen(src));
    if (!result.ok) { toml_free(result); return 1; }

    // Step into the [owner] table first
    toml_datum_t owner = toml_get(result.toptab, "owner");
    if (owner.type != TOML_TABLE) { toml_free(result); return 1; }

    // Then look up individual keys within that table
    toml_datum_t name = toml_get(owner, "name");
    toml_datum_t age  = toml_get(owner, "age");
    toml_datum_t miss = toml_get(owner, "missing_key");

    printf("name    = %s\n",  name.u.s);        // name    = Tom
    printf("age     = %" PRId64 "\n", age.u.int64); // age     = 42
    printf("missing = %s\n",  miss.type == TOML_UNKNOWN ? "not found" : "found");
    // missing = not found

    toml_free(result);
    return 0;
}
```

--------------------------------

### Parse TOML with C++20 API and RAII

Source: https://context7.com/cktan/tomlc17/llms.txt

Utilize the `toml::parse_file_ex` function for parsing TOML files. The `toml::Result` object manages memory automatically (RAII), eliminating the need for manual `toml_free()` calls. Access data using type-safe methods like `as_str()`, `as_intvec()`, `as_bool()`, `as_real()`, and `as_datetimetz()`.

```cpp
#include "tomlcpp.hpp"
#include <iostream>
#include <vector>
#include <chrono>

// TOML file: app.toml
// [server]
// host    = "api.example.com"
// port    = [8080, 8443]
// enabled = true
// ratio   = 0.95
//
// [event]
// created = 2024-06-01T12:00:00Z

int main() {
    // Parse from a file path — Result is RAII, no explicit free needed
    toml::Result result = toml::parse_file_ex("app.toml");
    if (!result.ok()) {
        std::cerr << "ERROR: " << result.errmsg() << "\n";
        return 1;
    }

    // get() with initializer_list for nested keys
    auto host = result.get({"server", "host"})->as_str();
    if (!host) { std::cerr << "missing server.host\n"; return 1; }
    std::cout << "host = " << *host << "\n";  // host = api.example.com

    // seek() with dot-separated path
    auto ports = result.seek("server.port")->as_intvec();
    if (!ports) { std::cerr << "missing server.port\n"; return 1; }
    std::cout << "ports = [";
    for (size_t i = 0; i < ports->size(); i++)
        std::cout << (i ? ", " : "") << (*ports)[i];
    std::cout << "]\n";  // ports = [8080, 8443]

    // Boolean access
    auto enabled = result.seek("server.enabled")->as_bool();
    std::cout << "enabled = " << (*enabled ? "true" : "false") << "\n"; // enabled = true

    // Float access
    auto ratio = result.seek("server.ratio")->as_real();
    std::cout << "ratio = " << *ratio << "\n"; // ratio = 0.95

    // Datetime with std::chrono
    auto created = result.seek("event.created")->as_datetimetz();
    if (created) {
        auto [tp, tz_offset_min] = *created;
        auto tt = std::chrono::system_clock::to_time_t(
                      std::chrono::time_point_cast<std::chrono::seconds>(
                          tp));
        std::cout << "created (unix) = " << tt << ", tz_offset_min = " << tz_offset_min << "\n";
    }

    // Parse from string
    toml::Result r2 = toml::parse("[db]\nport = 5432\n");
    auto db_port = r2.seek("db.port")->as_int();
    std::cout << "db.port = " << *db_port << "\n"; // db.port = 5432

    return 0;
    // result and r2 are automatically freed by ~Result()
}
```

--------------------------------

### Parse TOML from File Path

Source: https://github.com/cktan/tomlc17/blob/main/API.md

Parses a TOML document from a file path. The library opens and closes the file internally. The result must be freed using toml_free().

```c
toml_result_t toml_parse_file_ex(const char *fname);
```

--------------------------------

### `toml::parse`, `toml::parse_file`, `toml::parse_file_ex` — C++ parse functions

Source: https://context7.com/cktan/tomlc17/llms.txt

Parses TOML data from a string or file using C++ RAII wrappers, std::optional for safe access, and std::chrono for date/time types. Manual memory management is not required.

```APIDOC
## C++20 API (`tomlcpp.hpp`)

### `toml::parse`, `toml::parse_file`, `toml::parse_file_ex` — C++ parse functions

The `toml` namespace wraps the C API with RAII (`toml::Result` auto-frees on destruction), `std::optional`-based safe accessors on `toml::Datum`, and `std::chrono` date/time types. No manual `toml_free()` call is needed.

### Description

These functions provide a C++ interface for parsing TOML content from strings or files. They leverage RAII for automatic resource management and offer type-safe accessors for TOML values, including support for `std::chrono` types.

### Usage

```cpp
#include "tomlcpp.hpp"

// Parse from a file path
toml::Result result = toml::parse_file_ex("app.toml");
if (!result.ok()) {
    std::cerr << "ERROR: " << result.errmsg() << "\n";
    return 1;
}

// Accessing values
auto host = result.get({"server", "host"})->as_str();
auto ports = result.seek("server.port")->as_intvec();
auto enabled = result.seek("server.enabled")->as_bool();
auto ratio = result.seek("server.ratio")->as_real();
auto created = result.seek("event.created")->as_datetimetz();

// Parse from string
toml::Result r2 = toml::parse("[db]\nport = 5432\n");
auto db_port = r2.seek("db.port")->as_int();
```

### Functions

- `toml::parse(const char* src, size_t len)`: Parses TOML from a string.
- `toml::parse_file(const char* path)`: Parses TOML from a file.
- `toml::parse_file_ex(const char* path)`: Parses TOML from a file with extended error information.

### Return Value

- `toml::Result`: An object containing the parsed TOML data or an error message. `toml::Result` manages its own memory, so no manual `toml_free()` is needed.

### Accessors

- `as_str()`: Access as a `std::string`.
- `as_int()`: Access as an `int64_t`.
- `as_intvec()`: Access as a `std::vector<int64_t>`.
- `as_bool()`: Access as a `bool`.
- `as_real()`: Access as a `double`.
- `as_datetimetz()`: Access as a `std::pair<std::chrono::system_clock::time_point, int>` representing time point and timezone offset in minutes.
```

--------------------------------

### toml_parse_file_ex

Source: https://github.com/cktan/tomlc17/blob/main/API.md

Parses a TOML document from a file path. Opens and closes the file internally. The result must be released with `toml_free()`.

```APIDOC
## toml_parse_file_ex

### Description
Parse a TOML document from a file path. Opens and closes the file internally.
The result must be released with `toml_free()`.

### Method
```c
toml_result_t toml_parse_file_ex(const char *fname);
```
```

--------------------------------

### Lookup Key Path with `toml_seek`

Source: https://github.com/cktan/tomlc17/blob/main/API.md

Use `toml_seek` to access nested TOML values using a dot-separated key path. Returns TOML_UNKNOWN if any part of the path is not found. Keys must not contain escape characters and the total key length is limited to 255 bytes.

```c
toml_datum_t toml_seek(toml_datum_t table, const char *multipart_key);
```

--------------------------------

### Merge TOML Results with `toml_merge`

Source: https://github.com/cktan/tomlc17/blob/main/API.md

Combine two TOML results, overriding the first with the second according to specific rules for different data types and structures. Remember to free all three results independently.

```c
toml_result_t toml_merge(const toml_result_t *r1, const toml_result_t *r2);
```

--------------------------------

### Parse TOML from an open file handle

Source: https://context7.com/cktan/tomlc17/llms.txt

Use `toml_parse_file` to parse TOML content from an already open `FILE*`. The caller is responsible for closing the file handle using `fclose`.

```c
#include "tomlc17.h"
#include <stdio.h>

int main() {
    FILE *fp = fopen("config.toml", "r");
    if (!fp) { perror("fopen"); return 1; }

    toml_result_t result = toml_parse_file(fp);
    fclose(fp);  // caller closes the file

    if (!result.ok) {
        fprintf(stderr, "parse error: %s\n", result.errmsg);
        toml_free(result);
        return 1;
    }

    toml_datum_t val = toml_seek(result.toptab, "section.key");
    if (val.type == TOML_STRING) {
        printf("section.key = %s\n", val.u.s);
    }

    toml_free(result);
    return 0;
}
```

--------------------------------

### toml_default_option

Source: https://github.com/cktan/tomlc17/blob/main/API.md

Retrieves the current default TOML parsing options.

```APIDOC
## toml_default_option

### Description
Return the current default options. Use this to obtain a baseline before modifying individual fields.
```

--------------------------------

### Check TOML Result Equivalence with `toml_equiv`

Source: https://github.com/cktan/tomlc17/blob/main/API.md

Determine if two TOML results represent identical documents. The order of keys in tables and elements in arrays is significant for equivalence.

```c
bool toml_equiv(const toml_result_t *r1, const toml_result_t *r2);
```

--------------------------------

### toml_equiv

Source: https://github.com/cktan/tomlc17/blob/main/API.md

Compares two TOML results for equality. Returns true if they represent identical documents.

```APIDOC
## toml_equiv

### Description
Return `true` if the two results represent identical documents. Table key order and array element order are both significant.
```

--------------------------------

### toml_merge: Merging TOML documents

Source: https://context7.com/cktan/tomlc17/llms.txt

Use toml_merge to combine two TOML documents, where the second document overrides the first. Tables are merged recursively, arrays-of-tables have entries appended, and other keys are overridden. Remember to free all three results independently.

```c
#include "tomlc17.h"
#include <string.h>
#include <stdio.h>

int main() {
    // Base configuration (e.g., defaults file)
    const char *base =
        "title = \"My App\"\n"
        "\n"
        "[database]\n"
        "server = \"localhost\"\n"
        "port   = 5432\n"
        "enabled = true\n";

    // Override configuration (e.g., environment-specific file)
    const char *override =
        "[database]\n"
        "server  = \"prod.db.example.com\"\n"
        "enabled = false\n"
        "\n"
        "[logging]\n"
        "level = \"warn\"\n";

    toml_result_t r1 = toml_parse(base,     strlen(base));
    toml_result_t r2 = toml_parse(override, strlen(override));

    toml_result_t merged = toml_merge(&r1, &r2);
    if (!merged.ok) {
        fprintf(stderr, "merge error: %s\n", merged.errmsg);
    } else {
        // title preserved from r1
        toml_datum_t title   = toml_seek(merged.toptab, "title");
        // server overridden by r2
        toml_datum_t server  = toml_seek(merged.toptab, "database.server");
        // port preserved from r1 (not in r2)
        toml_datum_t port    = toml_seek(merged.toptab, "database.port");
        // enabled overridden by r2
        toml_datum_t enabled = toml_seek(merged.toptab, "database.enabled");
        // new key from r2
        toml_datum_t level   = toml_seek(merged.toptab, "logging.level");

        printf("title   = %s\n",  title.u.s);              // title   = My App
        printf("server  = %s\n",  server.u.s);             // server  = prod.db.example.com
        printf("port    = %" PRId64 "\n", port.u.int64);   // port    = 5432
        printf("enabled = %s\n",  enabled.u.boolean ? "true" : "false"); // enabled = false
        printf("level   = %s\n",  level.u.s);              // level   = warn
    }

    // All three must be freed independently
    toml_free(r1);
    toml_free(r2);
    toml_free(merged);
    return 0;
}

```

--------------------------------

### toml_get

Source: https://github.com/cktan/tomlc17/blob/main/API.md

Looks up a single key in a table. Returns a datum with `type == TOML_UNKNOWN` if the key is not found or if `table` is not a `TOML_TABLE`.

```APIDOC
## toml_get

### Description
Look up a single key in a table. Returns a datum with `type == TOML_UNKNOWN`
if the key is not found or if `table` is not a `TOML_TABLE`.

### Method
```c
toml_datum_t toml_get(toml_datum_t table, const char *key);
```
```

--------------------------------

### `toml_get` — Single-key lookup

Source: https://context7.com/cktan/tomlc17/llms.txt

Retrieves a single key's value from a TOML table. If the key is not found or the input datum is not a table, it returns a datum with `type == TOML_UNKNOWN`.

```APIDOC
## `toml_get` — Single-key lookup

### Description
Looks up exactly one key in a `TOML_TABLE` datum. Returns a datum with `type == TOML_UNKNOWN` if not found or if the input is not a table.

### Method
(Implicitly C function call)

### Parameters
- `table` (toml_datum_t) - The TOML table datum to search within.
- `key` (const char*) - The key to look up.

### Return Value
- `toml_datum_t` - A datum representing the value associated with the key. Its `type` field indicates the data type (e.g., `TOML_STRING`, `TOML_INT`, `TOML_TABLE`, `TOML_UNKNOWN`).

### Request Example
```c
#include "tomlc17.h"
#include <string.h>
#include <stdio.h>

int main() {
    const char *src =
        "[owner]\n"
        "name = \"Tom\"\n"
        "age  = 42\n";

    toml_result_t result = toml_parse(src, strlen(src));
    if (!result.ok) { toml_free(result); return 1; }

    // Step into the [owner] table first
    toml_datum_t owner = toml_get(result.toptab, "owner");
    if (owner.type != TOML_TABLE) { toml_free(result); return 1; }

    // Then look up individual keys within that table
    toml_datum_t name = toml_get(owner, "name");
    toml_datum_t age  = toml_get(owner, "age");
    toml_datum_t miss = toml_get(owner, "missing_key");

    printf("name    = %s\n",  name.u.s);        // name    = Tom
    printf("age     = %\"PRId64\"\n", age.u.int64); // age     = 42
    printf("missing = %s\n",  miss.type == TOML_UNKNOWN ? "not found" : "found");
    // missing = not found

    toml_free(result);
    return 0;
}
```
```

--------------------------------

### Parse TOML from String

Source: https://github.com/cktan/tomlc17/blob/main/API.md

Parses a TOML document from a NUL-terminated string. The returned result must be freed using toml_free().

```c
toml_result_t toml_parse(const char *src, int len);
```

--------------------------------

### toml_set_option

Source: https://github.com/cktan/tomlc17/blob/main/API.md

Replaces the global TOML parsing options. This affects all subsequent parse calls and is not thread-safe.

```APIDOC
## toml_set_option

### Description
Replace the global options. This affects all subsequent parse calls. Not thread-safe; call once during program initialization.

### Example — custom allocator:

```c
toml_option_t opt = toml_default_option();
opt.mem_realloc = my_realloc;
opt.mem_free    = my_free;
toml_set_option(opt);
```
```

--------------------------------

### Parse TOML from File Pointer

Source: https://github.com/cktan/tomlc17/blob/main/API.md

Parses a TOML document from an open FILE pointer. The caller is responsible for closing the file. The result must be freed using toml_free().

```c
toml_result_t toml_parse_file(FILE *fp);
```

--------------------------------

### toml_parse_file

Source: https://github.com/cktan/tomlc17/blob/main/API.md

Parses a TOML document from an open file handle. The caller is responsible for calling `fclose(fp)`. The result must be released with `toml_free()`.

```APIDOC
## toml_parse_file

### Description
Parse a TOML document from an open file handle. The caller is responsible for
calling `fclose(fp)`. The result must be released with `toml_free()`.

### Method
```c
toml_result_t toml_parse_file(FILE *fp);
```
```

--------------------------------

### toml_parse

Source: https://github.com/cktan/tomlc17/blob/main/API.md

Parses a TOML document from a NUL-terminated string. The result must be released with `toml_free()`.

```APIDOC
## toml_parse

### Description
Parse a TOML document from a NUL-terminated string. `len` is the length of `src`
excluding the NUL terminator. The result must be released with `toml_free()`.

### Method
```c
toml_result_t toml_parse(const char *src, int len);
```
```

--------------------------------

### TOML Data Types

Source: https://github.com/cktan/tomlc17/blob/main/API.md

Enumeration representing the different types of TOML values that can be stored in a toml_datum_t.

```c
typedef enum {
  TOML_UNKNOWN = 0,
  TOML_STRING,
  TOML_INT64,
  TOML_FP64,
  TOML_BOOLEAN,
  TOML_DATE,
  TOML_TIME,
  TOML_DATETIME,
  TOML_DATETIMETZ,
  TOML_ARRAY,
  TOML_TABLE,
} toml_type_t;
```

--------------------------------

### toml_equiv

Source: https://context7.com/cktan/tomlc17/llms.txt

Performs a deep equality check between two parsed TOML documents. The function returns `true` if the documents are identical in terms of both key order within tables and element order within arrays. Otherwise, it returns `false`.

```APIDOC
## `toml_equiv` — Deep equality check

### Description
Returns `true` if two parse results represent identical TOML documents. Both table key order and array element order are significant.

### Parameters
- `r1` (const toml_result_t*): Pointer to the first TOML parse result.
- `r2` (const toml_result_t*): Pointer to the second TOML parse result.

### Returns
- `bool`: `true` if the documents are equivalent, `false` otherwise.
```

--------------------------------

### TOML Datum Structure

Source: https://github.com/cktan/tomlc17/blob/main/API.md

Represents a single node in the parsed TOML document tree, holding its type and value.

```c
struct toml_datum_t {
  toml_type_t type;
  union {
    const char *s;           // TOML_STRING: shorthand for str.ptr
    struct {
      const char *ptr;       // NUL-terminated string
      int len;               // length excluding the NUL terminator
    } str;                   // TOML_STRING
    int64_t int64;           // TOML_INT64
    double  fp64;            // TOML_FP64
    bool    boolean;         // TOML_BOOLEAN
    struct {
      int16_t year, month, day;
      int16_t hour, minute, second;
      int32_t usec;          // microseconds
      int16_t tz;            // timezone offset in minutes
    } ts;                    // TOML_DATE, TOML_TIME, TOML_DATETIME, TOML_DATETIMETZ
    struct {
      int32_t       size;    // number of elements
      toml_datum_t *elem;    // elem[0..size-1]
    } arr;                   // TOML_ARRAY
    struct {
      int32_t        size;   // number of key/value pairs
      const char   **key;    // key[0..size-1]  (NUL-terminated strings)
      int           *len;    // len[0..size-1]  (key lengths)
      toml_datum_t  *value;  // value[0..size-1]
    } tab;                   // TOML_TABLE
  } u;
};
```

--------------------------------

### toml_merge

Source: https://github.com/cktan/tomlc17/blob/main/API.md

Produces a new TOML result by merging two existing results, with the second result overriding the first.

```APIDOC
## toml_merge

### Description
Produce a new result that is `r1` overridden by `r2`. Merge rules:

- Key in r2 not in r1 → added to result.
- Key in r2 with a different type than r1 → overrides r1.
- Key is an array of tables → r2's entries are appended to r1's.
- Key is a table → r2's sub-keys are recursively merged into r1's.
- Otherwise → r2 overrides r1.

### Note
All three results (`r1`, `r2`, and the returned result) must each be freed with `toml_free()` independently.
```

--------------------------------

### toml_merge

Source: https://context7.com/cktan/tomlc17/llms.txt

Merges two parsed TOML documents, producing a new result where the second document (`r2`) overrides the first (`r1`). Tables are merged recursively, arrays-of-tables have entries from `r2` appended to `r1`, and all other key types are overridden by `r2`. It's important to note that all three results (`r1`, `r2`, and the merged result) must be freed independently.

```APIDOC
## `toml_merge` — Merge two parsed documents

### Description
Produces a new result that is `r1` overridden by `r2`. Tables are recursively merged, arrays-of-tables have r2 entries appended to r1, and all other keys are overridden by r2. All three results (`r1`, `r2`, and the returned merged result) must be freed independently.

### Parameters
- `r1` (const toml_result_t*): The base TOML parse result.
- `r2` (const toml_result_t*): The overriding TOML parse result.

### Returns
- `toml_result_t`: A new TOML parse result representing the merged document. If merging fails, `ok` will be false and `errmsg` will contain the error message.
```

--------------------------------

### Free TOML parse result memory

Source: https://context7.com/cktan/tomlc17/llms.txt

Always call `toml_free` on the `toml_result_t` returned by parsing functions, regardless of whether parsing was successful. This releases all allocated memory.

```c
#include "tomlc17.h"
#include <string.h>

int main() {
    const char *src = "key = \"value\"\n";
    toml_result_t result = toml_parse(src, strlen(src));

    // Always free, even on error
    if (!result.ok) {
        fprintf(stderr, "error: %s\n", result.errmsg);
        toml_free(result);  // still required
        return 1;
    }

    // use result ...

    toml_free(result);  // all datum pointers become invalid after this
    return 0;
}
```

--------------------------------

### toml_free

Source: https://github.com/cktan/tomlc17/blob/main/API.md

Releases all memory associated with a `toml_result_t`. Must be called on every result returned by a parse or merge function, regardless of whether parsing succeeded. All pointers obtained from this result become invalid after this call.

```APIDOC
## toml_free

### Description
Release all memory associated with a `toml_result_t`. Must be called on every
result returned by a parse or merge function, regardless of whether parsing
succeeded. All pointers obtained from this result become invalid after this call.

### Method
```c
void toml_free(toml_result_t result);
```
```

--------------------------------

### TOML Result Structure

Source: https://github.com/cktan/tomlc17/blob/main/API.md

Structure returned by parsing functions, indicating success or failure and holding the parsed TOML data or an error message.

```c
struct toml_result_t {
  bool         ok;
  toml_datum_t toptab;
  char         errmsg[200];
};
```

--------------------------------

### Free TOML Result Memory

Source: https://github.com/cktan/tomlc17/blob/main/API.md

Releases all memory associated with a toml_result_t. This function must be called on every result, regardless of success or failure.

```c
void toml_free(toml_result_t result);
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.